Utility-HTN Agent

Adds one slot to the current builder. Call Initialize Slot Builder first.

Adds an agent to a squad and syncs squad world-state keys.

Finds nearest free slot and reserves it for the agent.

Clears one shared squad state key.

Starts a new slot collection. Use with Add Slot To Builder then commit with Load Slot Set.

Marks squad plans stale so they are replanned on coordination pass.

Imports slot coordinates from a JSON array string.

Loads JSON slot positions from a world-state key and imports them.

Commits all slots added via Add Slot To Builder to coordination.

Releases a slot reservation if present.

Removes an agent from its current squad and releases owned slots.

Requests immediate plan updates for all squad members.

Reserves a squad slot for an agent if free or expired.

Controls whether owned slots are auto-released when agents are deregistered.

Enables or disables squad coordination processing globally.

Caps number of squads processed per coordination pass. 0 means all.

Sets default reservation TTL in seconds for slot operations.

Sets optional time slice cap per coordination pass. 0 disables slice.

Sets global coordination update interval in seconds.

Stores world position for a squad slot.

Combined slot reservation control for reserve or release modes.

Sets one leader UID for the squad.

Writes one shared squad state key and mirrors it to squad members.

Combined squad plan control for invalidate, request, or both.

True if the agent is currently assigned to the given squad.

True if the slot is not currently reserved by a live owner.

True if the agent is the current leader of its squad.

Triggered when a slot reservation is released or expires.

Triggered when a slot reservation succeeds.

Triggered when an agent joins or leaves a squad.

Triggered when a squad shared state key is updated or cleared.

Returns the squad id for an agent UID.

Returns slot id assigned to an agent for the slot type.

Returns 1 if coordination processing is enabled, else 0.

Returns coordination update interval in seconds.

Returns number of coordination squads processed in last pass.

Returns coordination time slice cap in seconds.

Returns member count for a squad.

Returns number of active squads.

Returns total number of expired slot releases.

Returns squad member UID at a zero-based index.

Returns current owner UID for a slot, or 0 if free.

Returns leader UID for a squad.

Returns one squad state value by key.

Adds one task to the network being built. Specify task ID, description, and type for manager reference.

Starts a new task network definition. Use with Add Task to Builder then commit with Load Task Network.

Commits all accumulated tasks to a JSON representation and stores in world state for export or manager registration.

Switches this object to another AI profile and replans. Use case: turn a civilian into a guard during an alarm.

Turns this agent processing on or off. Use case: disable distant enemies to save CPU.

Sets periodic planning time in seconds. Use case: increase to 2 seconds for background NPCs to reduce CPU.

Changes when this agent replans. Use case: use reactive mode for bosses that must react instantly.

Sets how often periodic planning runs in seconds. Use case: raise to 2 seconds for low-priority NPCs.

Sets auto-fail timeout in seconds for stuck tasks. Use case: recover agents stuck behind obstacles.

Reports damage and updates related world-state values. Use case: trigger retreat behavior when health drops.

Reports a sound event for hearing reactions. Use case: alert nearby guards when player makes noise.

Marks target as no longer visible. Use case: call when line-of-sight breaks.

Reports visual contact and updates target data. Use case: call when enemy raycast detects player.

Stops temporary override and returns to normal planning. Use case: end cutscene idle behavior early.

Marks current task as done so plan can continue. Use case: call after reaching a patrol waypoint.

Marks current task as failed to force replanning. Use case: call when pathfinding cannot reach target.

Pauses AI updates for this object. Use case: freeze enemies during pause menu or dialogue.

Runs a one-off task before returning to normal plan. Use case: force "idle" during a short cutscene.

Requests an immediate replan now. Use case: call right after a major world-state change.

Resumes AI updates and replans immediately. Use case: wake enemies when player enters the area.

Removes current target data for this agent. Use case: clear chase data after the player escapes.

Deletes one world-state key on this agent. Use case: clear a temporary flag like "heardNoise".

Stores a patrol waypoint in world state. Use case: set patrol routes at layout start from events.

Sets target UID and position in one step. Use case: lock onto player when entering attack range.

Writes any custom world-state key for this agent. Use case: set "hasCover" after finding cover.

Runs when alert tier changes. Use case: switch sprite animation from patrol to combat.

Runs when no valid plan is found. Use case: force a safe fallback task like idle.

Runs when a signal is received. Use case: play an exclamation sound when enemy hears noise.

Runs after task completion is marked. Use case: start movement for the next task.

Runs after task failure is marked. Use case: play a failed path reaction before retry.

Runs when a new primitive task starts. Use case: branch event logic by CurrentTask.

Runs when temporary override ends. Use case: resume normal patrol animation.

Runs when temporary override starts. Use case: force a guard to hold position briefly.

True when this agent still has work to do. Use case: skip idle logic while a plan is active.

True when a visible target is set. Use case: only run chase movement when target exists.

True if a world-state key exists. Use case: check if patrol data was set before using it.

True for alerted or combat tiers. Use case: enable weapon behavior only at high alert.

True when alert tier matches selected value. Use case: run separate logic for suspicious vs combat.

True when this behavior is processing. Use case: skip AI movement events when disabled.

True when current task matches the id. Use case: run patrol code only during task "patrol".

True only at combat tier. Use case: start firing logic only when fully engaged.

True while temporary task override is active. Use case: block normal task completion events during cutscenes.

True when Pause was applied. Use case: avoid sending duplicate pause commands.

Returns this agent type id. Use case: show current AI profile in a debug panel.

Returns alert level from 0 to 1. Use case: drive UI color intensity for enemy awareness.

Returns alert tier index. Use case: switch behavior branches with a numeric tier check.

Returns alert tier name text. Use case: print "suspicious" or "combat" to debug text.

Returns last completed task id. Use case: log finished tasks for tuning AI flow.

Returns current task id. Use case: route event-sheet logic by active task name.

Returns 1 if enabled, else 0. Use case: show current AI processing state in a debug text object.

Returns last failed task id. Use case: track tasks that frequently fail and need redesign.

Returns last known target X. Use case: move to investigate where the player was seen.

Returns last known target Y. Use case: move to investigate where the player was seen.

Returns remaining task count. Use case: detect empty plans and request fallback behavior.

Returns task id at a plan index. Use case: preview next task for debugging.

Returns previous task id. Use case: detect transitions like patrol to chase.

Returns previous alert tier index. Use case: trigger one-time effects on tier changes.

Returns task restored after temporary override. Use case: continue a paused patrol task cleanly.

Returns latest stimulus intensity. Use case: scale reaction strength from weak to strong.

Returns latest stimulus type text. Use case: handle sound and damage with different responses.

Returns latest stimulus X position. Use case: face toward the source of a sound.

Returns latest stimulus Y position. Use case: move to inspect where damage came from.

Returns current target UID. Use case: fetch target instance for aim or movement logic.

Reads a world-state value by key. Use case: check custom flags like "isCoverAvailable" in events.