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	`2.5`	Distance in blocks within which the mob swings and deals damage. The mob stops advancing once within this range.
`attack-damage`	float	`5.0`	Damage dealt per swing. Applied as direct entity damage, not a weapon.
`stop-distance`	double	`2.0`	Distance the mob gets close before stopping (inherited from follow-target). Overridden by `attack-range`.
`speed-modifier`	double	`1.0`	Movement speed multiplier while pathing toward target (inherited from follow-target).

Example (skeleton with melee fallback):

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

`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"

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`	`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`

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 July 2026