Placeholders

AstralMobs registers a single placeholder namespace mob with AstralCore. Unlike global placeholders, mob_* placeholders are local — they resolve only within specific contexts where a mob is available in the placeholder container, such as in goal requirement/action contexts, spawn/death actions, and health-display conditions.

The mob namespace implements ComplexPlaceholder, allowing chaining (e.g., %mob_target_name%, %mob_memory_<key>%) and integration with the requirement DSL operators like [compare].

Identity

Placeholder	Type	Description
`%mob_type%`	String	Spoofed entity type name as displayed to the client (e.g., "Creeper", "Evoker").
`%mob_uuid%`	String	Mob's UUID as a string, useful for issuing commands (e.g., `%mob_uuid%` in effect commands).

Health

Placeholder	Type	Description
`%mob_health%`	Float	Current health in half-hearts.
`%mob_max-health%`	Float	Maximum health.
`%mob_remaining-health%`	Double	Health-to-max ratio (0.0 to 1.0); useful for phase gating.

State

Placeholder	Type	Description
`%mob_has-target%`	Boolean	True if the mob has an active target (player or entity).
`%mob_active-goal%`	String	Simple class name of the currently running `AstralGoal`, or `"none"` if no blueprint goal is active.
`%mob_location%`	LocationPlaceholder	Mob's current block location; supports sub-placeholders (`%mob_location_x%`, `%mob_location_y%`, `%mob_location_z%`, `%mob_location_world%`).
`%mob_location-up%`	LocationPlaceholder	Mob's location offset one block upward; used for particle/visual effects.

Target

When the mob has no target, all %mob_target_*% placeholders return null.

Placeholder	Type	Description
`%mob_target_name%`	String	Display name of the target (typically a player name).
`%mob_target_type%`	String	Entity type of the target (e.g., "Player", "Zombie").
`%mob_target_distance%`	Float	Distance in blocks from the mob to the target.

Memory

Memory is a key-value store (type Object) scoped to the individual mob instance, populated and read by actions.

Placeholder	Type	Description
`%mob_memory_<key>%`	Object	Arbitrary value stored under `<key>` by the `store-memory` action. Defaults to the string `"0"` if the key has never been set.

Example: In the creeper blueprint, [store-memory] cooldown-move 2000 sets a 2-second cooldown duration, then later requirements read it with [compare] %mob_timer_cooldown-move% >= %mob_memory_cooldown-move%.

Timers

Timers measure elapsed milliseconds since the start-timer action last (re)started a named timer for that mob. Each timer is scoped to the mob and the key string.

Placeholder	Type	Description
`%mob_timer_<key>%`	Long	Milliseconds elapsed since the timer `<key>` was last started. Returns `0` if the timer was never started; this is the special case used in requirement gates (e.g., `[compare] %mob_timer_cooldown% == 0` on the first tick).

Example: The evoker boss uses [compare] %mob_timer_cooldown-cast-goal% > 4000 to enforce a 4-second minimum between goal state changes.

Passenger & Vehicle

Placeholder	Type	Description
`%mob_passenger%`	NMSMob or null	If this mob is a vehicle carrying a blueprint passenger, returns the passenger mob; otherwise `null`.
`%mob_vehicle%`	NMSMob or null	If this mob is mounted as a passenger on another blueprint mob, returns the vehicle mob; otherwise `null`.
`%mob_has-passenger%`	Boolean	True if this mob has a passenger.
`%mob_has-vehicle%`	Boolean	True if this mob is mounted on a vehicle.

Full Reference

All placeholders registered by the mob namespace:

Placeholder	Type	Description
`%mob_type%`	String	Spoofed entity type name.
`%mob_uuid%`	String	Mob UUID (string format).
`%mob_health%`	Float	Current health (half-hearts).
`%mob_max-health%`	Float	Maximum health.
`%mob_remaining-health%`	Double	Health-to-max ratio (0–1).
`%mob_memory_<key>%`	Object	Stored value under key, or `"0"` if unset.
`%mob_timer_<key>%`	Long	Milliseconds elapsed since timer key started (0 if never started).
`%mob_passenger%`	NMSMob or null	Passenger mob, or null.
`%mob_vehicle%`	NMSMob or null	Vehicle mob, or null.
`%mob_has-passenger%`	Boolean	Has a passenger.
`%mob_has-vehicle%`	Boolean	Mounted on a vehicle.
`%mob_has-target%`	Boolean	Has an active target.
`%mob_location%`	LocationPlaceholder	Current location.
`%mob_location-up%`	LocationPlaceholder	Location + 1 block up.
`%mob_target_name%`	String	Target display name (null if no target).
`%mob_target_type%`	String	Target entity type (null if no target).
`%mob_target_distance%`	Float	Distance to target (null if no target).
`%mob_active-goal%`	String	Running goal class name, or `"none"`.

Usage in Requirements & Actions

Mob placeholders integrate seamlessly with the requirement DSL and action system. The [compare] requirement operator supports arithmetic and equality checks:

goal-selectors:
  cast-skill:
    priority: 0
    skill: creeper-detonate
    can-use-requirements:
      min-requirements: 2  # OR logic: fire on first tick OR after cooldown
      requirements:
        - "[compare] %mob_timer_cooldown-cast% > 4500"
        - "[compare] %mob_timer_cooldown-cast% == 0"  # First tick special case
        - "[compare] %mob_target_distance% <= 4"

The store-memory and start-timer actions populate memory and timer placeholders:

goal-selectors:
  cast-skill:
    start-actions:
      - "[start-timer] cooldown-cast"           # Begin measuring elapsed time
      - "[store-memory] shot-count 0"           # Initialize a counter
    stop-actions:
      - "[store-memory] shot-count 0"           # Reset on goal stop

Later requirements chain these:

follow-target:
  can-use-requirements:
    requirements:
      - "[compare] %mob_timer_cooldown-move% >= %mob_memory_cooldown-move%"

Consult Mob Actions and AI Goals, Targeting & Movement for full action/requirement syntax.

Last modified: 25 July 2026