Custom AI

ai:
  goals:
    - clear: [MOVE, TARGET]
    - bestiary:melee_attack{speed=1.0}
    - bestiary:hover_strafe{distance=6;height=3}
    - bestiary:avoid_void
  navigation: flying

Two tiers

Custom AI is split by what it costs, and each tier reports itself at startup.

Tier	Needs	Gives
Goals	Paper, any supported version	goals, including clearing vanilla ones
NMS	Paper 1.20.5+, Mojang-mapped	`navigation`, `move_control`, `look_control`, brains

Goals go through Paper's supported goal-selector API, so they cost zero NMS and work across the entire supported band, including stripping a Ravager's vanilla goals entirely and replacing them.

Clearing vanilla goals

- clear: [MOVE, TARGET]

The four categories are MOVE, LOOK, JUMP and TARGET. A bare clear with no list clears all of them.

Clearing is what makes a custom mob feel custom rather than like a reskin: a ravager that should hover and strafe has to stop wanting to charge first. Put it first in the list.

Goal order is priority

Goals take their priority from their position in the list, first being highest. Override it explicitly with priority: in the structured form:

- type: bestiary:melee_attack
  speed: 1.0
  priority: 2

The built-in goals

All are namespaced bestiary:.

bestiary:melee_attack: Closes and attacks. speed (1.0), reach (3.0).
bestiary:ranged_attack: Casts a skill at range. skill, range, interval.
bestiary:strafe: Strafes around the target. speed (1.0), step (0.2).
bestiary:hover_strafe: Orbits at a height, which is the flying-boss goal. distance (6.0), speed (1.0), height (3.0), step (0.2).
bestiary:circle_target: Orbits on the ground. radius (5.0), speed (1.0), step (0.3).
bestiary:keep_distance: Backs away to hold a range. distance (8.0), speed (1.0).
bestiary:charge: Rushes the target from range. speed, min_distance, interval.
bestiary:flee_below_health: Runs below a health percentage. percent, speed.
bestiary:patrol_anchor: Circles its anchor while idle. radius, speed, interval.
bestiary:return_to_anchor: Comes back when it strays too far. distance, speed, teleport.
bestiary:look_at_target: Faces the target. range.
bestiary:float: Swims rather than sinking.
bestiary:avoid_void: Refuses to path off an edge. margin, min_y.
bestiary:follow_owner: For summons. distance, speed.
bestiary:guard_area: Holds a radius. radius.

ai:
  navigation: flying

default, ground, flying, amphibious or climbing. Anything but default needs the NMS tier, because PathNavigation is not exposed by Bukkit or Paper at all.

move_control and look_control take the same tier and are set the same way.

Turning vanilla AI off entirely

options:
  ai: false

Different from clearing goals: this disables the mob's AI outright. Scripted movement mechanics still work, so it is the right choice for something driven entirely by skills, such as a statue that only casts.

Writing your own

Goals compile against bestiary-api and never against a Paper class, so a custom goal still loads on a server where the Goal API is absent and simply never runs. See For developers.

Checking which tier you got

/bestiary platform

The AI tier: line reads Paper Goal API + NMS, Paper Goal API, or none (Spigot).

Treat this as part of the configuration result. A goal definition can load when its runtime tier is unavailable, so a clean reload alone does not prove a goal or navigation mode can run. Spawn the mob, attach /bestiary debug <mob>, and verify targeting and movement on the server family used in production.