For pack makers
Difficulty files
The JSON format of difficulties, including how to set up cheats.
A difficulty is a JSON file in a data pack, at:
data/<namespace>/aiplayers/difficulty/<id>.jsonIts id is <namespace>:<id>. As with play styles, every key is optional. Unknown keys and out-of-range values make
the file fail, and /aiplayer profile list reports what went wrong. Bots whose difficulty is missing use the
built-in Normal values.
Format
{ "display_name": "Normal", "reaction_ticks": 4, "aim_error_degrees": 3.0, "fov_degrees": 180, "perception_radius": 32, "path_max_nodes": 20000, "path_max_millis": 200, "decision_quality": 0.9, "combat_skill": 0.7, "parkour": true, "creeper_tactic": "fight", "night_work": true, "end_dragon": true, "cheats": { "starting_kit": [], "resource_gift": { "interval_minutes": 0, "items": [] } }}| Key | Range | Default | Description |
|---|---|---|---|
display_name | string | "" | Human-readable name. |
reaction_ticks | 0 to 100 | 4 | Delay before the bot notices what it sees, and before it raises its shield. |
aim_error_degrees | 0 to 45 | 3.0 | Spread applied to the bot’s arrows. |
fov_degrees | 1 to 360 | 180 | Field of view for spotting entities. |
perception_radius | 4 to 128 | 32 | How far the bot perceives blocks and entities. Also scales its engagement range (aggression × perception_radius). |
path_max_nodes | 100 to 1,000,000 | 20000 | Node budget of one path search. When reached, the bot follows the best partial path. |
path_max_millis | 10 to 10,000 | 200 | Time budget of one path search, in milliseconds of the server’s bot clock (on a background thread). At the default clock, they’re wall milliseconds. |
decision_quality | 0 to 1 | 0.9 | Below 1, the bot occasionally picks its second-best objective. |
combat_skill | 0 to 1 | 0.7 | Each swing is delayed by up to (1 − skill) × 10 ticks. The skill is also the chance it tries a critical hit. |
parkour | boolean | true | Whether the bot jumps over 1- and 2-block gaps. |
creeper_tactic | "fight" or "flee" | "fight" | With "fight", a fit bot holding a sword or axe fights creepers using hit-and-step-back. With "flee", it always runs (aiplayers:easy ships "flee"). |
night_work | boolean | true | With true, a sheltered bot works through the night on safe ground (its mine, base chests and workstations) and goes to bed only when every real player online is asleep. With false, it goes indoors at dusk and idles until dawn (aiplayers:easy ships false). |
end_dragon | boolean | true | With false the bot never goes to the End, whatever its style’s end.travel says, and refuses an end or outer order (aiplayers:easy ships false). |
threats | object | see below | Per-monster danger weights (0 to 100) used when fleeing and in the gear comparison for Nether and End mobs. |
cheats | object | none | See Cheats. |
Threat weights
The optional threats object sets how dangerous a bot considers each monster when it picks a flee direction and
when it sizes up gated Nether and End mobs (blaze, wither_skeleton, hoglin, piglin_brute, ender_dragon,
shulker):
"threats": { "zombie": 1.0, "skeleton": 1.3, "spider": 0.8, "creeper": 1.5, "enderman": 1.2, "witch": 1.4, "ghast": 2.0, "blaze": 2.5, "wither_skeleton": 3.0, "piglin_brute": 3.5, "hoglin": 2.5, "magma_cube": 1.5, "magma_cube_small": 0.5, "piglin": 1.5, "zombified_piglin": 2.0, "ender_dragon": 6.0, "shulker": 2.0}piglinapplies only while the piglin truce is off (0while the bot wears its gold truce piece and the piglin is calm).zombified_piglinapplies only to an angry zombified piglin (calm ones are neutral).magma_cube_smallis a size-1 magma cube.ender_dragonis the dragon’s weight for a bot outside a party’s fight. Such a bot keeps away from the dragon when its side is lighter.shulkeris the weight a city raid gives each shulker in sight when comparing it against its party.- Any monster not listed defaults to
1.0. An unknown key inthreatsfails the file.
Cheats
{ "display_name": "Normal (head start)", "cheats": { "starting_kit": [ { "item": "minecraft:stone_pickaxe" }, { "item": "minecraft:bread", "count": 8 } ], "resource_gift": { "interval_minutes": 5, "items": [{ "item": "minecraft:oak_log", "count": 4 }] } }}| Key | Description |
|---|---|
starting_kit | Items given once per life: at the bot’s first check, then after each respawn (not for permadeath bots). Reconnects and restarts give nothing. |
resource_gift.interval_minutes | How often the gift is given, in minutes of world time (0 to 1440, 0 = never), counted from the last gift. |
resource_gift.items | The items of each gift. |
reveal_enemy_bases | Boolean, default false. Hands the bot every enemy faction’s base as confirmed knowledge without any scouting: position, bounds, the chests with their last-seen contents, the wall’s gates and the golem count. The copies refresh whenever they’d change, and at least once a minute. While the cheat is in effect, the bot doesn’t scout on its own. See Raiding enemy bases. |
item / count | An item id, and a count from 1 to 64 (default 1). |
Cheats only apply when both the server’s cheats_allowed is true and the bot has
/aiplayer set <bot> cheats true. Items that don’t fit in the inventory are dropped at the bot’s feet. Every
application is logged, e.g. Cheat for AI player Ann: starting kit (respawn): breadx3.
Missing keys take the Normal defaults, so a cheat-only difficulty like the one above plays the same as Normal, plus its cheats.
Last updated Oct 30, 2026