AI Goals, Targeting & Movement {id="ai-goals-targeting-movement"}

Mob intelligence is defined through three configurable behavior blocks: goals (what the mob does), target selectors (who it targets), and move control (how it moves). Each block is deserialized from the blueprint once and copied per spawn, allowing mobs to exhibit diverse, context-sensitive behaviors.

Structure Overview

A typical mob blueprint organizes behavior as:

goal-selectors:           # What the mob does
  melee-attack: { ... }
  cast-skill: { ... }
  idle: { ... }

target-selectors:         # Who it targets
  player: { ... }

move-control:             # How it moves
  type: walking

Each block is independent but works together: goals execute in priority order, targeting supplies the mob's current target, and move control determines movement type.

Goal Selectors

Goals define the mob's action behavior. Each goal type maps to a key under goal-selectors; a key can hold either a single goal (map value) or multiple goals of the same type (list value).

goal-selectors:
  melee-attack:        # Single goal (map)
    attack-range: 2.0
  cast-skill:          # Multiple goals of same type (list)
    - skill: fireball
    - skill: ice-blast
  idle: { }            # Empty defaults work fine

Unknown keys (e.g. a clear pseudo-entry) are safely ignored, never fatal.

Shared Goal Fields

All goal types share these configurable fields:

Field	Type	Default	Description
`priority`	int	`0`	Lower-priority goals run first; higher priority goals interrupt lower ones. Added to the mob's goal selector with this priority.
`flags`	List	`[MOVE, LOOK]`	Enum flags: `MOVE`, `LOOK`, `JUMP`. Controls which movement axes the goal claims. When unset, defaults to `MOVE` + `LOOK`.
`is-interruptible`	boolean	`true`	When `false`, this goal cannot be interrupted by higher-priority goals once started.
`requires-update-every-tick`	boolean	`false`	When `true`, `canContinueToUse` is rechecked every tick; the goal stops if it returns `false`.
`can-continue-to-use-also-can-use`	boolean	`true`	When `true`, `canContinueToUse` re-checks `canUse` each tick as a second condition. Set `false` to decouple them (goal can continue even if `canUse` flips false).
`can-use-requirements`	Requirement list	None	Conditions the mob must satisfy to start this goal. Evaluated once per selection. If any requirement fails, the goal cannot be used.
`can-continue-requirements`	Requirement list	None	Conditions the mob must satisfy to keep running this goal. Re-evaluated every tick when `requires-update-every-tick` is true. If any requirement fails, the goal stops.
`start-actions`	Action list	None	Actions run when the goal starts (e.g. start a timer, play a sound). See amob-actions.md.
`stop-actions`	Action list	None	Actions run when the goal stops.
`interrupt-actions`	Action list	None	Actions run when the goal is interrupted (a higher-priority goal takes over).

Goal Types

`melee-attack`

Chases the target, then strikes when within range. Extends follow-target internally.

Field	Type	Default	Description
`attack-range`	double (ph)	`2.5`	Distance in blocks within which the mob swings and deals damage. The mob stops advancing once within this range — it is used as the chase stop distance, overriding `stop-distance`.
`attack-damage`	float (ph)	`5.0`	Damage dealt per swing. Applied as direct entity damage, not a weapon.
`attack-interval-ticks`	int (ph)	`0`	Ticks between strikes while the goal keeps running. See cadence.
`sweep-particle`	boolean (ph)	`false`	Flash a sweep-attack particle halfway between mob and target on every strike — visual feedback for base types with no visible arm swing (pigs, …).
`speed-modifier`	double	`1.0`	Movement speed multiplier while pathing toward target (inherited from follow-target).

Cadence

`attack-interval-ticks`	Behaviour
`<= 0` (default)	Strike once, then stop. The goal restarts through the goal selector, so the cadence is whatever the selector re-poll gives.
`> 0`	The goal keeps running and strikes every that-many ticks while the target stays in range (`20` = one hit per second) — the pet / sentry style.

The interval is tracked as a deadline on the entity tick rather than a countdown: goals only tick every other game tick unless requires-update-every-tick is set, which would silently double a counted-down interval.

Kill credit for owned mobs

When the mob has an owner who is online and in the same world, the strike's damage source names the mob as the direct entity and the owner as the causing entity. Everything keyed off the attacker then treats the hit as the owner's: AstralSkill's damage indicator shows it to them, the victim's healthbar is revealed to them, and the kill is recorded for them. The victim also retaliates against the owner rather than the pet, since vanilla sets lastHurtByMob from the causing entity.

Ownerless mobs — and pets whose owner is offline or in another world — keep the plain mob attack source.

Example (skeleton with melee fallback):

goal-selectors:
  melee-attack:
    priority: 10
    attack-range: 2.0
    attack-damage: 8.0
    speed-modifier: 1.2

Example (pet striking once a second, damage scaling with its level):

goal-selectors:
  melee-attack:
    priority: 10
    attack-range: 2.5
    attack-damage: "%mob_pet_level%"
    attack-interval-ticks: 20
    sweep-particle: true

`follow-target`

Chases and faces the target without striking. Useful for positioning-only mechanics or ranged attackers that should close distance without melee.

Field	Type	Default	Description
`stop-distance`	double	`2.0`	Distance in blocks at which the mob stops advancing.
`speed-modifier`	double	`1.0`	Movement speed multiplier while chasing.

Special behaviors:

Phasing mobs (removePhysics: true): ignore pathfinding and beeline directly through walls toward the target.
Path recalculation: re-paths after 2 ticks once the previous path is exhausted, or after 4-10 ticks (randomized) if the target has merely moved while a path is still active — avoiding the every-tick recompute that would stall movement into a near-target shuffle.

Example (chase without striking):

goal-selectors:
  follow-target:
    priority: 2
    flags: [MOVE, LOOK]
    stop-distance: 1.5
    speed-modifier: 1.0

`idle`

Wanders randomly within a configurable radius of the spawn point. Yields immediately when a target appears, allowing combat goals to take over.

Field	Type	Default	Description
`range`	double	`10.0`	Wander radius around spawn, in blocks.
`speed-modifier`	double	`1.0`	Movement speed multiplier while strolling.
`interval`	int	`120`	Roughly one stroll starts per `interval` ticks. Higher = more idle time between moves.

Example:

goal-selectors:
  idle:
    priority: 3
    flags: [MOVE]
    range: 5.0
    speed-modifier: 0.8
    interval: 30

`kite`

Pure positioning: the mob tries to hold a distance band from its target, closing in when too far and backing away when too close. No attacking; useful paired with a separate skill-casting goal.

Field	Type	Default	Description
`preferred-range`	double	`8.0`	Distance in blocks the mob tries to maintain from target.
`range-tolerance`	double	`1.5`	Half-width of the dead band around `preferred-range`. Mob holds position while inside `[preferred-range - tolerance, preferred-range + tolerance]`.
`speed-modifier`	double	`1.0`	Movement speed multiplier while repositioning.

Example:

goal-selectors:
  kite:
    priority: 2
    flags: [MOVE, LOOK]
    preferred-range: 8.0
    range-tolerance: 1.5
    speed-modifier: 1.0

`cast-skill`

Extends kite: maintains a distance band and casts a skill at the target on cooldown. Requires the skill to be registered in AstralSkill. For skill DSL details, see amob-skills.md.

Field	Type	Default	Description
`skill`	String	Required	Id of the skill to cast. Must be registered in AstralSkill; if not found or AstralSkill is absent, the goal behaves like `kite` only.
`force-cast`	boolean	`false`	When `true`, the skill cast is forced (bypasses some engine checks). See amob-skills.md.
`preferred-range`	double	`8.0`	Inherited from `kite`.
`range-tolerance`	double	`1.5`	Inherited from `kite`.
`speed-modifier`	double	`1.0`	Inherited from `kite`.

Example (ranged mob with dual-cast pattern):

goal-selectors:
  cast-skill:
    - flags: [LOOK]        # LOOK only; don't let charging steal MOVE from kite
      priority: 1
      skill: skeleton-cast # windup/charge phase
      preferred-range: 8.0
      range-tolerance: 4.0
      start-actions:
        - "[start-timer] cooldown-cast"
      can-use-requirements:
        min-requirements: 1
        requirements:
          - "[compare] %mob_timer_cooldown-cast% > 4000"
          - "[compare] %mob_timer_cooldown-cast% == 0"
    - flags: [LOOK]
      priority: 0
      skill: skeleton-attack-1 # fire/release phase
      preferred-range: 8.0
      range-tolerance: 4.0
      can-use-requirements:
        min-requirements: 3
        requirements:
          - "[compare] %mob_timer_cooldown-cast% > 3000"
          - "[compare] %mob_timer_cooldown-cast% < 3999"

`float`

Vanilla's FloatGoal as a configurable goal: while in water (above the swim threshold) or lava, the mob repeatedly triggers its jump control so it bobs to the surface instead of sinking.

Field	Type	Default	Description
`jump-chance`	double	`0.8`	Chance per tick to trigger the jump control while floating (vanilla's value).

Every vanilla mob has this at priority 0 — but blueprint mobs strip all vanilla goals, so any mob that can end up in water (a pet following its owner across a lake, most walkers) has to declare it:

goal-selectors:
  float:
    priority: 0

It claims only the JUMP flag by default, so movement and look goals keep running while afloat.

`follow-owner`

Follows the mob's owner: paths once they get far enough away, stops advancing once close, and teleports to them when left too far behind.

Field	Type	Default	Description
`start-distance`	double	`5.0`	The goal activates once the owner is at least this many blocks away.
`stop-distance`	double	`3.0`	The goal deactivates once within this many blocks of the owner.
`teleport-distance`	double	`12.0`	Beyond this distance the mob teleports near the owner instead of pathing. Non-positive disables teleporting.
`teleport-radius`	double	`2.0`	Radius around the owner within which a landing spot is looked for.
`teleport-attempts`	int	`8`	Candidate spots tried per blink before giving up.
`speed-modifier`	double	`1.0`	Movement speed multiplier while following.
`look-distance`	double	`16.0`	How far away the mob still turns to look at its owner.

Distances use vanilla tamed-animal hysteresis: the goal only starts beyond start-distance but keeps running until within stop-distance, so a pet does not flicker between following and idling at the boundary. That gap is also what leaves room for lower-priority goals like idle-animation to run while the owner stands still.

Teleports snap to solid ground and reject landings inside blocks or liquid.

`heal-owner`

Support goal for pets: heals the mob's owner on a pulse whenever they are missing health.

Field	Type	Default	Description
`heal-amount`	float	`2.0`	Health restored per pulse, in half-hearts like every HP value.
`heal-interval-ticks`	int	`20`	Ticks between pulses (`20` = once per second).
`max-distance`	double	`0.0`	Only heal while the owner is within this many blocks. Non-positive disables the check — the follow/teleport goals keep a pet near its owner anyway.
`particles`	boolean	`true`	Show heart particles on the owner on every pulse.

It claims no movement flags by default, so it runs alongside follow-owner/idle-animation rather than competing with them — the pet keeps flying after its owner while topping them up. Explicitly configured flags still win, for the rare mob that wants different behaviour.

Heals go through the CraftBukkit heal path, firing EntityRegainHealthEvent with the CUSTOM reason, so other plugins observe them like any regen.

`teleport-closer`

Blink goal: when the mob is farther than min-distance from its target it teleports to a valid spot near the target rather than pathing there. Pairs naturally with a melee-attack that then takes over once the blink drops the mob into range.

Field	Type	Default	Description
`min-distance`	double	`6.0`	The mob only blinks at or beyond this distance; within it, other goals handle the approach.
`teleport-radius`	double	`3.0`	Radius of the disc around the target the mob lands in. Candidates are uniformly random inside it, so the mob may end up nearer or, occasionally, farther.
`cooldown-ticks`	int	`60`	Minimum ticks between teleports.
`attempts`	int	`8`	Candidate spots tried per blink before giving up for this attempt.

Each candidate is validated the same way as follow-owner's: snapped to solid ground, rejected inside blocks or liquid.

`idle-animation`

Plays a configurable, purely client-side animation sequence while the mob stands still — the pet idle animations (wolf sit, sniffer search/dig, armadillo roll, allay dance, ravager roar, …) as blueprint configuration instead of hardcoded per-type logic.

The goal activates when the mob has no target and its navigation is idle. An idle-tick counter then drives the steps: after start-delay idle ticks, each step fires when the counter reaches its at offset.

Field	Type	Default	Description
`start-delay`	int (ticks)	`30`	Idle ticks before the step at `at: 0` fires.
`loop`	boolean	`false`	Restart the counter after the last step, so the sequence repeats while the mob stays idle.
`loop-delay`	int (ticks)	`60`	Pause before the sequence restarts when `loop` is on.
`steps`	List[Step]	`[]`	The sequence (below).
`on-move`	List[Metadata]	—	Metadata applied when the goal stops — e.g. returning a sniffer to `SEARCHING` or a wolf to its stand-up flags.

Each step:

Field	Type	Default	Description
`at`	int	`0`	Idle-tick offset (after `start-delay`) at which the step fires.
`chance`	double	`1.0`	Probability (0–1) that it fires when its offset is reached.
`metadata`	List[Metadata]	—	Entity-metadata overrides to write.
`status`	Integer	—	Entity-status byte broadcast to every tracking player — the client interprets it for the spoofed type (e.g. `39` = ravager roar).
`pick`	List[Step]	—	Variants; one is chosen uniformly at random and applied. Its own `chance`/`metadata`/`status` are honoured, its `at` is ignored.

Each metadata entry is one client-side write: index, type (an EntityDataTypes constant name, case- and dash-insensitive — BYTE, SHORT, INT, LONG, FLOAT, BOOLEAN, STRING, ENTITY_POSE, SNIFFER_STATE, ARMADILLO_STATE) and value. Byte/short/int accept hex (0x05) as well as decimal, so bit-flag fields (sitting, rearing, dancing, …) are reachable. Indices 0-15 are shared by every mob; higher indices belong to the blueprint's spoofed type.

Overrides are forced into every outgoing metadata packet by the packet spoofing layer, so they stick. When the mob moves again — follow-owner preempting this goal, being ridden, any other movement — the goal stops, every override it wrote is dropped, and on-move is applied.

goal-selectors:
  idle-animation:
    priority: 10
    start-delay: 30
    steps:
      - at: 0
        metadata:
          - index: 18
            type: BYTE
            value: "0x05"    # tamed + sitting
    on-move:
      - index: 18
        type: BYTE
        value: "0x04"        # tamed, standing

Target Selectors

Target selectors find and acquire targets (usually players). Each selector scans on an interval and applies filters (line of sight, path reachability, custom requirements). Like goals, a target-selectors key can map to a single selector or a list.

Currently only one type is implemented:

`player`

Targets players within range. Uses vanilla player scanning and optional requirement filters.

Shared Selector Fields

Field	Type	Default	Description
`must-see`	boolean	`false`	Require line of sight to acquire and maintain target. When `false`, the mob targets through walls.
`must-reach`	boolean	`false`	Require a navigable path to the target. When `false`, the mob can target unreachable players (useful for phasing/flying mobs).
`interval`	int	`10`	Re-scan cadence. The mob searches for a new target roughly every `interval` ticks.
`range`	double	`-1`	Detection range in blocks. Non-positive (`<= 0`) uses the mob's `follow_range` attribute instead.
`priority`	int	`0`	Selector priority (lower runs first in the target selector).
`requirements`	Requirement list	None	Per-candidate filters evaluated on each scan. The candidate (player) is the requirement executor, so player-relative conditions (in region, health, permission, …) are meaningful. The mob is exposed via `%mob_*%` placeholders.

PlayerTargetMode

When multiple players pass filters, mode picks which one becomes the target. Case- and underscore-insensitive.

Mode	Behavior
`CLOSEST`	Pick the nearest player (default vanilla behavior).
`RANDOM`	Pick a uniformly random candidate.
`FURTHEST`	Pick the most distant candidate.
`HIGHEST_HP`	Pick the player with the most current health.
`LOWEST_HP`	Pick the player with the least current health.

Example:

target-selectors:
  player:
    must-see: false
    must-reach: false
    range: 100
    interval: 10
    mode: CLOSEST

Example with custom requirements (target only if player is at least 5 blocks away):

target-selectors:
  player:
    range: 50
    requirements:
      - "[compare] %mob_target_distance% >= 5"

Move Control

Move control defines how the mob physically moves. It is a discriminated union — you must specify a type field, and the deserialization expects fields relevant to that type. Mobs without a move-control block use walking by default.

General Structure

move-control:
  type: <walking|flying|creaking|cube|none>
  # type-specific fields follow

Unknown type values fail to load (logged as an error; the mob keeps its default walking control).

`walking`

Standard ground movement using vanilla pathfinding. This is the default when move-control is omitted.

Field	Type	Default	Description
`phase-through-heads`	boolean	`true`	When `true`, player skulls and mob heads are treated as empty space by the pathfinder, so the mob walks straight through them instead of routing around them. Set `false` to keep heads as obstacles.

Example (explicit walking with head-phasing disabled):

move-control:
  type: walking
  phase-through-heads: false

`flying`

Aerial movement with hoisting and hover-height control. Registers FLYING_SPEED attribute and swaps to FlyingPathNavigation.

Field	Type	Default	Description
`max-turn`	int	`20`	Maximum turning rate (degrees per tick). Lower = slower turns.
`hovers-in-place`	boolean	`true`	When `true`, gravity is disabled so the mob hovers at its current altitude when idle (not steering). When `false`, the mob falls to ground level when it stops moving.
`flying-speed`	double	`0.4`	Speed attribute value while airborne (range 0.0–1.0+). Higher = faster flight.
`hover-height`	double	`0.0`	Blocks of clearance above ground the mob maintains while hovering idle (when `hovers-in-place` is true). Applies only when idle; during active steering, movement is not constrained.

Behavioral notes:

Gravity is kept off for the mob's entire lifetime when hovers-in-place is true, ensuring smooth hover hold.
hover-height only takes effect while the mob is not steering toward a waypoint.
For a flyer that should descend and land when target is lost, set hovers-in-place: false.

Example (Blaze-like flyer with hover):

move-control:
  type: flying
  flying-speed: 0.65
  hover-height: 1.0
  hovers-in-place: true

`cube`

Slime / Magma Cube style hopping locomotion. The mob bounces toward its goal instead of walking.

Field	Type	Default	Description
`min-jump-delay`	int	`10`	Minimum ground ticks between hops.
`max-jump-delay`	int	`30`	Maximum ground ticks between hops. Actual delay is random in `[min, max)`.
`jump-height`	double	`0.42`	Jump strength attribute value. ~0.42 is a normal mob jump (~1.25 blocks high). Higher = higher hops.

Example:

move-control:
  type: cube
  min-jump-delay: 10
  max-jump-delay: 30
  jump-height: 0.42

`creaking`

Creaking mob movement (gated / special behavior; no configuration fields).

move-control:
  type: creaking

`none`

No movement control; the mob is stationary. Useful for immobile bosses or triggers.

move-control:
  type: none

Practical Patterns

Simple Melee Mob

Chases and strikes on sight:

goal-selectors:
  melee-attack:
    attack-range: 2.0
    attack-damage: 5.0
    priority: 1
  idle:
    range: 10.0
    priority: 2

target-selectors:
  player:
    must-see: false
    range: 50

Ranged Caster (Skeleton)

Keeps distance and fires projectiles:

move-control:
  type: walking

goal-selectors:
  cast-skill:
    - skill: skeleton-cast
      flags: [LOOK]
      priority: 1
      preferred-range: 8.0
      range-tolerance: 4.0
    - skill: skeleton-attack
      flags: [LOOK]
      priority: 0
      preferred-range: 8.0
      range-tolerance: 4.0
  kite:
    priority: 2
    preferred-range: 8.0
    range-tolerance: 1.5
  idle:
    priority: 3
    range: 5.0

target-selectors:
  player:
    must-see: false
    range: 100

Flying Ranged Boss (Blaze)

Hovers in place and kites while casting:

move-control:
  type: flying
  flying-speed: 0.65
  hover-height: 1.0

goal-selectors:
  cast-skill:
    - skill: blaze-cast
      priority: 1
      preferred-range: 10.0
  kite:
    priority: 2
    preferred-range: 10.0
  idle:
    priority: 3
    range: 5.0

target-selectors:
  player:
    must-see: false
    range: 100

Stationary Boss (Wither)

Immobile; multiple cast goals with complex timing patterns:

move-control:
  type: none

goal-selectors:
  cast-skill:
    - skill: wither-rain-cast
      priority: 5
      preferred-range: 40.0  # Ignored; no MOVE flag
      can-use-requirements:
        min-requirements: 2
        requirements:
          - "[compare] %mob_timer_cooldown-cast-rain% > 15000"
          - "[compare] %mob_timer_cooldown-cast-rain% == 0"
    - skill: wither-360-cast
      priority: 3
      preferred-range: 20.0
      can-continue-to-use-also-can-use: false
      can-continue-requirements:
        - "[compare] %mob_timer_cooldown-cast-360% < 1000"

target-selectors:
  player:
    must-see: false
    range: 350

Creeper Clone

Self-detonates while chasing:

goal-selectors:
  cast-skill:
    skill: creeper-detonate
    flags: [LOOK]
    priority: 0
    force-cast: true
    can-use-requirements:
      min-requirements: 2
      requirements:
        - "[compare] %mob_timer_cooldown-cast% > 4500"
        - "[compare] %mob_timer_cooldown-cast% == 0"
        - "[compare] %mob_target_distance% <= 4"
  follow-target:
    priority: 1
    stop-distance: 1.5
    speed-modifier: 1.0
  idle:
    priority: 2
    range: 5.0

target-selectors:
  player:
    must-see: false
    range: 100

Summary Tables

Goal Types Quick Reference

Type	Purpose	Key Fields	Extends
`melee-attack`	Chase then strike	`attack-range`, `attack-damage`, `attack-interval-ticks`	`follow-target`
`follow-target`	Chase without striking	`stop-distance`, `speed-modifier`	`AstralGoal`
`idle`	Wander near spawn	`range`, `speed-modifier`, `interval`	`AstralGoal`
`kite`	Hold distance band	`preferred-range`, `range-tolerance`	`AstralGoal`
`cast-skill`	Kite + cast skill	`skill`, `force-cast`, + kite fields	`KiteGoal`
`float`	Bob to the surface in water/lava	`jump-chance`	`AstralGoal`
`follow-owner`	Follow (and teleport to) the owner	`start-distance`, `teleport-distance`	`AstralGoal`
`heal-owner`	Pulse-heal the owner	`heal-amount`, `heal-interval-ticks`	`AstralGoal`
`teleport-closer`	Blink toward the target	`min-distance`, `teleport-radius`	`AstralGoal`
`idle-animation`	Client-side idle animation sequence	`steps`, `on-move`	`AstralGoal`

Target Selector Types Quick Reference

Type	Purpose	Modes
`player`	Target players	`CLOSEST`, `RANDOM`, `FURTHEST`, `HIGHEST_HP`, `LOWEST_HP`

Move Control Types Quick Reference

Type	Behavior	Key Fields
`walking`	Ground pathfinding (default)	`phase-through-heads`
`flying`	Aerial movement with hover	`flying-speed`, `hovers-in-place`, `hover-height`
`cube`	Slime-style hopping	`min-jump-delay`, `max-jump-delay`, `jump-height`
`creaking`	Creaking mob (gated)	None
`none`	Stationary / no movement	None

Shared Goal Flags

Flag	Effect
`MOVE`	The goal controls horizontal movement.
`LOOK`	The goal controls head rotation (look direction).
`JUMP`	The goal controls jumping.
Default	`MOVE` + `LOOK` when unset.

Cross-References

Mob Actions — action syntax for start-actions, stop-actions, interrupt-actions.
Casting Skills — skill DSL and how cast-skill goals trigger them.
mob Placeholders — available placeholders in requirements (e.g. %mob_timer_*%, %mob_memory_*%, %mob_target_distance%).

Last modified: 25 September 2026