StateTree, Queue, and Orchestration

This page documents the primary runtime surfaces of StateTreeStack and StateTreeQueue. Stack owns control of the behavior layer; Queue owns the execution sequence for already-decided tasks. They are often used together, but their parameters represent different responsibilities.

For the feature model, see StateTree Orchestration System. For integration, see Integrate StateTree and Blackboard. For debugging, see GameplayDebugger.

Stack

Stack fields and functions answer which StateTree layer is currently effective. Stack is appropriate for Unit, Squad, Command, and similar levels of override; it is not a task list.

Surface	Purpose
`LayerStateTrees`	StateTree references currently bound to each layer.
`SetLayerStateTree`	Sets the StateTree for a layer.
`ClearLayer`	Clears a layer and permits fallback; Command routing is handled by its exact execution lifecycle.
`GetRequestedLayer` / `GetRequestedStateTree`	Queries the request currently selected by Stack policy.
`GetAppliedLayer` / `GetAppliedStateTree`	Queries the decision layer and StateTree actually installed on the executor.
`OnActiveLayerChanged`	Event for a layer change.
`OnActiveLayerStateTreeReplaced`	Event for StateTree replacement while the active layer remains unchanged.
`HasPendingLayerTransition` / `GetPendingReasonTag`	Queries a pending transition and its reason while Requested and Applied have not converged.

Queue

Queue fields and functions answer which tasks are in the current dispatch, how far execution has progressed, and what result it produced. Queue is appropriate for an already-decided execution plan; it should not decide long-term AI control authority.

Surface	Purpose
`EnqueueTask(s)`	Appends tasks; with an active dispatch, they postpone its completion, while without one they are anonymous work.
`DispatchTask` / `DispatchTasks`	Replaces the current queue and returns an official `FGAIS_StateTreeDispatchHandle`, suitable for awaiting completion or precise cancellation.
`CancelDispatch`	Cancels only the official dispatch that still matches the active handle.
`ClearQueue`	Clears execution work; an active dispatch completes as Canceled.
`GetLastDispatchCompletion`	Queries the most recently committed official dispatch result.

Events

Event	Purpose
`OnDispatchCompleted`	The sole official dispatch-completion event; state is committed before it fires, and anonymous Enqueue work does not broadcast it.

StateTree helper surfaces

FGAIS_STE_Context resolves the Pawn, AIController, Blackboard, command component, squad component, unit component, and queue component. FGAIS_STE_EvalBBAsActor_Data and FGAIS_STE_EvalBBVAsActor are Blackboard Actor-reading surfaces. Queue Tasks include Enqueue, Dispatch, and Track Queue task types.

Common misconfiguration

Symptom	Common cause
AI does not return to its previous behavior after a command override.	Command execution did not complete or cancel, or the lower-layer StateTree did not retain a valid reference.
Queue tasks are still assumed to be valid after a layer switch.	The layer switch clears Queue; dispatch a new plan for the new layer.
One StateTree becomes too large to maintain.	Layer decisions, task execution, combo branches, and tactical selection were all placed in one StateTree; separate them across Stack layers, Queue tasks, and Tactical Assignment.

Table of contents