Mob Actions {id="mob-actions"}

AstralMobs registers five custom actions for the AstralCore action DSL, executable in mob-context locations (spawn-actions, death-actions, and goal start/stop/interrupt-actions). Most require the mob context to read or write mob-specific state; one (spawn-mob-location) runs globally and can spawn mobs anywhere in the configuration layer.

All actions support standard action parameters (delay, async — see Actions). Arguments marked required must be present; empty/null arguments are skipped with a silent return.

Action Reference

Action ID	Arguments	Mob Context Required	Effect
`spawn-mob-location`	`blueprint-id`, `location`	No	Spawns a blueprint at a location via `MobsAPI.spawnMob()`. Usable anywhere actions run (menus, item pipelines, etc.), not just mob contexts.
`store-memory`	`key`, `value`	Yes	Writes an arbitrary value into the mob's memory map, readable as `%mob_memory_<key>%` and usable in math expressions like `$e(%mob_memory_count%+1)`.
`start-timer`	`key`	Yes	(Re)starts a millisecond timer for the mob, readable as `%mob_timer_<key>%`. The cornerstone of boss cooldown gating — timers increment independently and are compared in requirements.
`send-entity-status`	`status`	Yes	Broadcasts an entity-status packet (byte code) interpreted by the client per the spoofed entity type (e.g. Warden, Wither, Evoker), triggering one-shot animations and effects — `4` for attack swing, `62` for warden sonic-boom, `61` for warden sniff. Not all animations are reachable this way; pose-driven ones (e.g. Warden roar) require `edit-entity-metadata` index 6.
`edit-entity-metadata`	`index`, `datatype`, `value`	Yes	Writes or clears a client-side entity metadata field by index and data type. Blank/empty `value` removes the override. Changes are broadcast immediately and re-asserted every 10 ticks by the reconciliation loop, ensuring dropped packets or stale state converge on the client. Supports hex literals for byte/short/int values.

`spawn-mob-location`

Spawns a blueprint instance at a location via MobsAPI.spawnMob().

Argument	Type	Required	Description
`blueprint-id`	string (placeholder-resolved)	Yes	Id of a loaded blueprint. Resolved through the action context.
`location`	`Location` (placeholder-resolved)	Yes	Bukkit location to spawn at. Resolved through the action context.

Mob context: Not required. Usable anywhere actions run (menus, commands, item pipelines).

spawn-actions:
  - "[spawn-mob-location] minion-spawner %player_location%"

# With placeholder indirection
  - "[spawn-mob-location] %parameters_mob_type% %parameters_spawn_loc%"

`store-memory`

Writes a key-value pair into the mob's in-memory data store, accessible during the mob's lifetime via the %mob_memory_<key>% placeholder.

Argument	Type	Required	Description
`key`	string (placeholder-resolved)	Yes	Memory key identifier. Spaces and most punctuation are allowed.
`value`	any (placeholder-resolved)	Yes	Value to store. Serialized as a string in placeholders but supports any type internally. Can be a literal (`0`, `true`, `hello`) or a placeholder expression including math: `$e(%mob_memory_count%+1)`.

Mob context: Required. Throws if not in an NMSMob context.

Memory values are compared in requirements and used to drive goal state machines — tracking shot counts, cooldown durations, or phase flags.

goal-selectors:
  cast-skill:
    - priority: 3
      skill: laser-attack
      start-actions:
        - "[start-timer] cooldown-laser"
        - "[store-memory] shot-count 0"      # Initialize counter
      can-use-requirements:
        - "[compare] %mob_timer_cooldown-laser% > 5000"
    - priority: 2
      skill: laser-fire
      start-actions:
        - "[store-memory] shot-count $e(%mob_memory_shot-count%+1)"  # Increment
      can-use-requirements:
        - "[compare] %mob_memory_shot-count% < 5"  # Gate at 5 shots

`start-timer`

Starts (or restarts) a millisecond-resolution timer tracked on the mob, readable as %mob_timer_<key>%.

Argument	Type	Required	Description
`key`	string (placeholder-resolved)	Yes	Timer key identifier.

Mob context: Required. Throws if not in an NMSMob context.

Timers increment independently from spawn. They are the primary tool for cooldown gating: a goal's start-actions restarts its timer, then can-use-requirements check if enough time has elapsed. Starting a timer that already exists resets it to 0.

goal-selectors:
  cast-skill:
    - priority: 5
      skill: explosion
      force-cast: true
      start-actions:
        - "[start-timer] cooldown-explosion"
        - "[start-timer] cooldown-global"
        - "[start-timer] cooldown-move"
        - "[store-memory] cooldown-move 500"
      can-use-requirements:
        min-requirements: 2
        requirements:
          - "[compare] %mob_timer_cooldown-explosion% > 10000"  # 10s cooldown
          - "[compare] %mob_timer_cooldown-explosion% == 0"     # Fire on first tick
          - "[compare] %mob_timer_cooldown-global% > 3000"      # Or respects a global gate

When a goal's start-actions run on each selection cycle, starting the same timer resets its counter — this is intentional and used to gate repeated uses. A can-continue-requirements check like %mob_timer_some-timer% < 2000 lets the goal keep running for a short window after it started, then stops it once the timer exceeds that threshold.

`send-entity-status`

Broadcasts an entity-status packet (a.k.a. entity event) to all players tracking the mob. The client interprets the status byte according to the entity type it renders (the spoof type in the blueprint), triggering built-in type-specific animations and effects.

Argument	Type	Required	Description
`status`	integer, 0-255 (placeholder-resolved)	Yes	Entity-status code. Interpreted per the spoofed entity type.

Mob context: Required. Throws if not in an NMSMob context.

Important: Pose-driven animations (e.g., Warden roar, sniff, dig) are not reachable via entity status — they are driven by entity metadata (pose index 6) and require edit-entity-metadata instead.

Common codes (type-specific; check Minecraft source for others):

4 — Attack swing (most mobs)
61 — Warden sniff
62 — Warden sonic-boom

Example from warden.yml:

goal-selectors:
  cast-skill:
    - priority: 3
      skill: laser-warning
      start-actions:
        - "[start-timer] cooldown-cast-laser"
        - "[send-entity-status] 62"       # Warden sonic-boom animation
    - priority: 18
      skill: melee-attack
      attack-range: 2.0
      start-actions:
        - "[start-timer] cooldown-melee"
        - "[send-entity-status] 4"        # Attack swing
      can-use-requirements:
        min-requirements: 2
        requirements:
          - "[compare] %mob_timer_cooldown-melee% > 1500"
          - "[compare] %mob_timer_cooldown-melee% == 0"

`edit-entity-metadata`

Writes (or clears) a single client-side entity metadata field and immediately broadcasts the change. Metadata overrides are re-asserted to every player tracking the mob every 10 ticks (100ms), ensuring dropped packets or stale state converge on the client.

Argument	Type	Required	Description
`index`	integer 0-255 (placeholder-resolved)	Yes	Metadata index to write. Indices 0-15 are shared by all mobs; 16+ are type-specific (e.g., Warden anger, Wither skull count).
`datatype`	enum (case-insensitive, dashes → underscores)	Yes	Entity data type: `BYTE`, `SHORT`, `INT`, `LONG`, `FLOAT`, `BOOLEAN`, `STRING`, `COMPONENT`, or `ENTITY_POSE`.
`value`	string/number (placeholder-resolved)	No	Value to coerce to the data type. Blank or empty string removes the metadata override, returning control to the server. Byte/short/int accept hex literals (`0x40`). For `ENTITY_POSE`, use enum names: `STANDING`, `ROARING`, `EMERGING`, `DIGGING`, `SNIFFING`, `ROARING`, etc.

Mob context: Required. Throws if not in an NMSMob context.

Hex values: Byte, short, and int values accept decimal or hexadecimal (0x... prefix) literals. Example: [edit-entity-metadata] 0 BYTE 0x40 sets the entity-flags index to 64.

Metadata indices (type-independent, 0-15):

0 — Entity flags (byte, bitmask): standing-on-ground, is-on-fire, is-crouching, etc.
6 — Pose (EntityPose): STANDING, FALL_FLYING, SLEEPING, SWIMMING, SPIN_ATTACK, ROARING, EMERGING, DIGGING, SNIFFING, etc.
9 — Health (float, server-side entity data replicated here; setting it does not heal, only cosmetic on client).
14 — No gravity (boolean).

Type-specific indices (examples):

Wither: index 19 = invulnerable timer (int, ticks) — as used in the shipped wither.yml blueprint.

Type-specific indices vary by base entity (vanilla NMS class). Consult NMS entity classes or test with your target mob type to discover which indices matter.

Example from warden.yml (pose sequencing):

goal-selectors:
  cast-skill:
    - priority: 6
      skill: explosion
      force-cast: true
      start-actions:
        - "[start-timer] cooldown-explode"
        - "[edit-entity-metadata] 6 ENTITY_POSE ROARING <delay=15>"   # Roar at tick 15
        - "[edit-entity-metadata] 6 ENTITY_POSE STANDING <delay=45>"  # Return to standing at tick 45

Example from wither.yml (health and wither-specific metadata):

goal-selectors:
  follow-target:
    - priority: 8
      start-actions:
        - "[edit-entity-metadata] 9 FLOAT 1.0"    # Client-side health (cosmetic)
        - "[edit-entity-metadata] 19 INT 100"     # Wither-specific: invulnerable timer
      can-use-requirements:
        min-requirements: 2
        requirements:
          - "[compare] %mob_timer_cooldown-invisible% > 15000"
          - "[compare] %mob_timer_cooldown-invisible% == 0"
    - priority: 7
      start-actions:
        - "[edit-entity-metadata] 9 FLOAT 2000.0"  # Reset
        - "[edit-entity-metadata] 19 INT 0"        # Clear immunity

Action Lists & Contexts

The five mob actions run in these configuration contexts:

Context	Location	Trigger
`spawn-actions`	Blueprint root	When the mob is spawned (once per instance).
`death-actions`	Blueprint root	When the mob dies.
`start-actions`	Goal definition	When the goal starts (selected from idle/other goals).
`stop-actions`	Goal definition	When the goal stops (interrupted or requirement fails).
`interrupt-actions`	Goal definition	When a higher-priority goal interrupts this one.

Spawn and death actions automatically have mob context. Goal-lifecycle actions (start/stop/interrupt) also run in mob context. Non-mob actions (e.g., console, message, sound) can also run in these contexts; only store-memory, start-timer, send-entity-status, and edit-entity-metadata require mob context and will throw if used outside it.

Cross-References

AI Goals, Targeting & Movement — Goal configuration and lifecycle
Blueprint YAML Reference — Top-level spawn-actions and death-actions
Placeholders — %mob_memory_% and %mob_timer_% reference
Actions — Action DSL syntax, global parameters, other actions
Functions — Math expressions like $e(%mob_memory_count%+1)
Requirements — Requirement DSL used in goal gate checking
Developer API — MobsAPI.spawnMob(), NMSMob interface

Last modified: 25 July 2026