AI Players
Type to search documentation.

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:

Path
data/<namespace>/aiplayers/difficulty/<id>.json

Its 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

data/aiplayers/aiplayers/difficulty/normal.json
{
"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": [] }
}
}
KeyRangeDefaultDescription
display_namestring""Human-readable name.
reaction_ticks0 to 1004Delay before the bot notices what it sees, and before it raises its shield.
aim_error_degrees0 to 453.0Spread applied to the bot’s arrows.
fov_degrees1 to 360180Field of view for spotting entities.
perception_radius4 to 12832How far the bot perceives blocks and entities. Also scales its engagement range (aggression × perception_radius).
path_max_nodes100 to 1,000,00020000Node budget of one path search. When reached, the bot follows the best partial path.
path_max_millis10 to 10,000200Time 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_quality0 to 10.9Below 1, the bot occasionally picks its second-best objective.
combat_skill0 to 10.7Each swing is delayed by up to (1 − skill) × 10 ticks. The skill is also the chance it tries a critical hit.
parkourbooleantrueWhether 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_workbooleantrueWith 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_dragonbooleantrueWith 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).
threatsobjectsee belowPer-monster danger weights (0 to 100) used when fleeing and in the gear comparison for Nether and End mobs.
cheatsobjectnoneSee 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):

Default threat weights
"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
}
  • piglin applies only while the piglin truce is off (0 while the bot wears its gold truce piece and the piglin is calm).
  • zombified_piglin applies only to an angry zombified piglin (calm ones are neutral).
  • magma_cube_small is a size-1 magma cube.
  • ender_dragon is 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.
  • shulker is 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 in threats fails the file.

Cheats

A difficulty with 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 }]
}
}
}
KeyDescription
starting_kitItems 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_minutesHow often the gift is given, in minutes of world time (0 to 1440, 0 = never), counted from the last gift.
resource_gift.itemsThe items of each gift.
reveal_enemy_basesBoolean, 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 / countAn 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