UBehaviorTreeComponent

class AIModule Since 4.0

Inherits: UObjectBase › UObjectBaseUtility › UObject › UActorComponent › UBrainComponent › UBehaviorTreeComponent

#include "BehaviorTree/BehaviorTreeComponent.h"

Description

The runtime component that executes a UBehaviorTree asset. Owned by AAIController and responsible for ticking the tree, managing active tasks, and handling aborts.

Caveats & Gotchas

• You typically do not interact with UBehaviorTreeComponent directly — use AAIController::RunBehaviorTree() and the Blackboard API instead.
• Accessed via AAIController::GetBrainComponent() cast to UBehaviorTreeComponent if you need low-level control.
• Stopping the component mid-execution (StopTree()) will abort the active task and clean up the active branch.

Example

Stop a running behavior tree C++

if (UBehaviorTreeComponent* BTC = Cast<UBehaviorTreeComponent>(GetBrainComponent()))
{
    BTC->StopTree();
}

Functions (49)

Lifecycle 11 Utility 1 Debugging 6 Execution 26 Logic 5

Lifecycle

11 ▼

Access	Type	Name	Description
public	function	UBehaviorTreeComponent::IsInstanceStackEmpty	Returns true if the instance stack has no running behavior tree instances — no tree has been started, or the tree has fully stopped and been cleaned up.
public	function	UBehaviorTreeComponent::IsPaused	Returns true if the tree is running but execution requests are currently being postponed because PauseLogic was called.
public	function	UBehaviorTreeComponent::IsRunning	Returns true if the behavior tree logic is currently active and processing execution requests.
public	function	UBehaviorTreeComponent::RestartTree	Restarts execution from the root node of the currently running tree, either by re-evaluating in place or by fully stopping and starting it again.
public	function	UBehaviorTreeComponent::StartTree	Begins executing the given behavior tree asset from its root node.
public	function	UBehaviorTreeComponent::StopTree	Stops execution of the currently running tree, aborting the active task and clearing all tree instances.
public	function	UBehaviorTreeComponent::TickComponent	Drives execution flow processing and ticks active tasks/services/decorators for the running behavior tree each frame.
public	function	UBehaviorTreeComponent::Cleanup	Tears down the running tree: removes all instances, clears node memory, and resets internal execution state.
public	function	UBehaviorTreeComponent::GetAccumulatedTickDeltaTime	Returns the total delta time accumulated for the current tick, accounting for any frames that were skipped due to ScheduleNextTick throttling.
public	function	UBehaviorTreeComponent::ScheduleNextTick	Requests when the behavior tree component should next process a full tick, letting the tree throttle its own update frequency instead of always running every frame.
public	function	UBehaviorTreeComponent::UninitializeComponent	Overrides UActorComponent::UninitializeComponent to tear down the behavior tree instance stack and release runtime node memory before the component is destroyed.

Utility

1 ▼

Access	Type	Name	Description
public	function	UBehaviorTreeComponent::AddReferencedObjects	Reports extra UObject references held by the behavior tree instance stack to the garbage collector.

Debugging

6 ▼

Access	Type	Name	Description
public	function	UBehaviorTreeComponent::DescribeActiveTasks	Returns a string listing the names of all currently active task nodes, including any running in parallel, across the whole instance stack.
public	function	UBehaviorTreeComponent::DescribeActiveTrees	Returns a string listing the behavior tree assets running on the instance stack, from the root tree down through any pushed dynamic subtrees.
public	function	UBehaviorTreeComponent::DescribeSelfToVisLog	Writes a summary of the tree's current state (active tasks, running trees) into the given Visual Logger snapshot so it shows up when replaying the log in the Visual Logger tool.
public	function	UBehaviorTreeComponent::EndFrame	Static hook called once per frame to flush accumulated behavior tree search timing into the FramePro/CSV profiler.
public	function	UBehaviorTreeComponent::GetDebugInfoString	Returns a human-readable summary of the brain component's current state, overriding UBrainComponent's base implementation with behavior-tree-specific details such as the active tree and current task.
public	function	UBehaviorTreeComponent::SetCSVTickStatName	Sets a custom CSV profiler stat name to attribute this behavior tree component's tick cost to in CSV profiling captures, instead of a generic default label.

Execution

26 ▼

Access	Type	Name	Description
public	function	UBehaviorTreeComponent::GetActiveNode	Returns the currently executing node in the active instance on top of the stack — typically the task currently running.
public	function	UBehaviorTreeComponent::GetTaskStatus	Returns the current runtime status of the given task node — Active, Aborting, or Inactive.
public	function	UBehaviorTreeComponent::IsExecutingBranch	Returns true if the active node is currently executing somewhere underneath the given node (optionally restricted to one specific child branch).
public	function	UBehaviorTreeComponent::OnTaskFinished	Notifies the tree that a task has finished its latent execution (or been aborted), triggering the next execution search.
public	function	UBehaviorTreeComponent::RequestBranchEvaluation	Requests a new execution search starting from the given decorator's branch, used when a decorator's condition changes outside the tree's normal tick, e.
public	function	UBehaviorTreeComponent::FindInstanceContainingNode	Searches the current instance stack for the subtree that owns the given node and returns its instance index.
public	function	UBehaviorTreeComponent::FindTemplateNode	Given an instanced runtime node, returns the shared template node it was created from.
public	function	UBehaviorTreeComponent::ForEachChildTask	Invokes the given functor once for every task node in every running instance on the stack.
public	function	UBehaviorTreeComponent::GetActiveInstanceIdx	Returns the index of the instance currently on top of the stack — the subtree that owns the active node.
public	function	UBehaviorTreeComponent::GetNodeMemory	Returns a pointer to the raw per-instance memory block allocated for a node, as configured by that node's GetInstanceMemorySize.
public	function	UBehaviorTreeComponent::HandleMessage	Routes an incoming FAIMessage to the message observers registered via RegisterMessageObserver, resuming any latent task waiting on it.
public	function	UBehaviorTreeComponent::IsAbortPending	Returns true if the component is waiting for one or more latent task aborts to finish before it can apply a pending execution change.
public	function	UBehaviorTreeComponent::IsAuxNodeActive	Returns true if the given auxiliary node (a ticking decorator or service) is currently registered and active on the running tree.
public	function	UBehaviorTreeComponent::IsRestartPending	Returns true if there is a pending execution request that will switch the tree to a higher-priority node rather than simply continuing to the next sibling.
public	function	UBehaviorTreeComponent::ProcessExecutionRequest	Runs the pending execution search and applies its results — the step that turns a queued RequestExecution/RequestBranchEvaluation call into an actual change of active node.
public	function	UBehaviorTreeComponent::RegisterMessageObserver	Sets up an observer that resumes a task's latent execution when a matching FAIMessage is broadcast to this component.
public	function	UBehaviorTreeComponent::RegisterParallelTask	Adds a task to the component's internal list of active parallel-running tasks, used for tracking tasks executing under a parallel composite node.
public	function	UBehaviorTreeComponent::RequestBranchActivation	Requests that the branch guarded by the given decorator be activated, typically because the decorator's condition just started passing.
public	function	UBehaviorTreeComponent::RequestBranchDeactivation	Requests that the branch guarded by the given decorator be deactivated.
public	function	UBehaviorTreeComponent::RequestExecution	Low-level entry point for triggering a new execution search from a specific composite node.
public	function	UBehaviorTreeComponent::ScheduleExecutionUpdate	Flags the component to process its pending execution flow update on the next tick instead of running it immediately.
public	function	UBehaviorTreeComponent::UnregisterAuxNodesInBranch	Unregisters all auxiliary nodes (decorators and services) attached anywhere under the given composite node's branch.
public	function	UBehaviorTreeComponent::UnregisterAuxNodesInRange	Unregisters all auxiliary nodes whose execution index falls strictly between FromIndex and ToIndex.
public	function	UBehaviorTreeComponent::UnregisterAuxNodesUpTo	Unregisters all auxiliary nodes (decorators and services) whose execution index is less important than the given index.
public	function	UBehaviorTreeComponent::UnregisterMessageObserversFrom	Removes all message observers previously registered for the given task via RegisterMessageObserver.
public	function	UBehaviorTreeComponent::UnregisterParallelTask	Removes a task from the internal list of active parallel tasks, undoing a prior RegisterParallelTask call.

Logic

5 ▼

Access	Type	Name	Description
public	function	UBehaviorTreeComponent::AddCooldownTagDuration	Sets or extends a gameplay-tag-keyed cooldown that Cooldown decorators elsewhere in the tree can check via the tag, without needing a dedicated blackboard key.
public	function	UBehaviorTreeComponent::GetCurrentTree	Returns the behavior tree asset for the currently active instance on the stack.
public	function	UBehaviorTreeComponent::GetRootTree	Returns the behavior tree asset at the bottom of the instance stack — the tree that was originally started with StartTree, regardless of any dynamic subtrees pushed on top of it.
public	function	UBehaviorTreeComponent::GetTagCooldownEndTime	Returns the world time at which the given cooldown tag's duration ends, or 0.
public	function	UBehaviorTreeComponent::SetDynamicSubtree	Assigns a behavior tree asset to a RunBehaviorDynamic task in the running tree identified by InjectTag, allowing subtrees to be swapped in at runtime without restarting the whole tree.

Version History

Introduced in: 4.0

Version	Status	Notes
5.6	stable	—

Feedback

Was this helpful?