StateTree Orchestration System

StateTree Stack and StateTree Queue both run StateTrees, but they solve problems at different levels. Stack determines which AI layer currently owns control. Queue determines how an already-decided multi-step task is executed, replaced, and completed. Together, they let Unit baseline behavior, squad behavior, player commands, and task sequences compose without being forced into one oversized and difficult-to-maintain StateTree.

What Problem Does This System Solve?

Complex AI often needs patrol, formation behavior, alert states, player commands, combos, and failure fallback at the same time. If every state competes through transitions in a single StateTree, priority becomes opaque: should a command immediately override squad behavior, where should execution return after the command, and who cleans up an interrupted combo?

GAIS separates these concerns. Stack manages control ownership and fallback among long-lived behavior layers. Queue manages a short-term execution plan that has already been decided. The Command System only accepts, validates, and tracks command execution. When it selects the StateTree backend, Stack places that command in the reserved Command layer.

What Can This System Do?

Capability	Example Use
Behavior-layer override and fallback	A Unit is patrolling; the squad enters alert and overrides it with the Squad layer; when that layer ends, control safely returns to the lower layer.
Let commands take over AI	Move, attack, or interaction commands temporarily control AI through the Command layer instead of directly damaging Unit/Squad behavior trees.
Execute an already-decided task sequence	Run “move to cover → wait → activate Ability” as a Queue Dispatch and receive a terminal result.
Append or replace tasks	Add a closing action to an existing plan or fully replace the old plan with a new Dispatch.
Observe actual behavior state	Use Requested/Applied to distinguish what policy wants from what the executor is actually running.
Provide command context to StateTree	The Command layer exposes command definition, variant, target, range, and execution Pawn through Blackboard.

It does not replace Tactical Assignment's matching of who should do what, the CommandSystem command ledger, or a general-purpose task queue. Tactical Assignment produces or selects commands, CommandSystem accepts them and owns their lifecycle, Stack decides behavior priority, and Queue executes already-decided plans.

How Stack, Queue, and Commands Work Together

UGAIS_StateTreeStackComponent owns decision-layer control. SetLayerStateTree and ClearLayer manage non-Command layers such as Unit and Squad. The Command layer can only be established or removed by an execution route carrying an exact command identity. When a real layer switch occurs, Stack clears Queue work that is no longer applicable so an old plan cannot keep running under a new behavior layer.

UGAIS_StateTreeQueueComponent is an optional executor. A Dispatch is a formal plan: it replaces the current plan, generates a Handle, and records result/reason for that Handle. Enqueue only appends work. If a Dispatch is active, enqueued work delays its completion; without one, it is anonymous work. Therefore, when another system must await completion, it must track the Dispatch Handle rather than only checking whether Queue briefly becomes Idle.

Requested and Applied

Stack stores both Requested and Applied for an execution. Requested is the target layer and complete StateTree reference selected by current policy. Applied is the state physically installed in the executor. During safe switching or same-layer StateTree replacement, the two can differ.

Use GetRequestedLayer / GetRequestedStateTree to observe what policy wants next.
Use GetAppliedLayer / GetAppliedStateTree to determine the behavior actually running now.
Use HasPendingLayerTransition and its reason tag to diagnose an incomplete switch.
Listen to OnActiveLayerStateTreeReplaced for same-layer asset replacement; listen to OnActiveLayerChanged for a real layer change.

Every replacement has an independent generation. Late callbacks from an old StateTree, old Command, or old Queue execution cannot settle an execution that has already been replaced.

Blackboard and Command Execution

The default UGAIS_CommandExecutionDefinition_StateTree routes an accepted command into the Command layer. Stack writes the command Definition, variant Index, target Actor/location, range, HomeLocation, and executing Pawn into the Blackboard Keys configured in project settings. The Command StateTree reads the validated context and reports success, failure, or cancellation.

If the project changes a Blackboard Key, UGAIS_DeveloperSettings, the Blackboard asset, and every StateTree reader must be updated together. Changing only one side results in “the command entered the Command layer, but the Tree has no usable context.”

When to Use Stack and When to Use Queue

Requirement	Use
Choose whether Unit, Squad, or Command currently owns control	Stack.
Execute a known sequence of steps within one behavior layer	Queue.
Restore previous AI after a command ends	CommandSystem + Stack Command layer.
Choose executors by candidate sets, targets, and capacity	Tactical Assignment.
Implement actual movement, skills, or animation for one Pawn	Command StateTree, Ability, or project backend.

For integration steps, see Integrate StateTree and Blackboard. For fields and Handles, see StateTree Queue and Orchestration Parameters. For the command relationship, see Command System.

Table of contents