Skip to Content
AwakenUnreal pluginBehaviour trees with AgentLoopBT

Behaviour trees with AgentLoopBT

AgentLoopBT is a second Unreal plugin. It runs AgentLoop .bt.json behaviour trees inside a game. When a project has both plugins, AwakenDebug lists every actor that has an AgentLoopBT tree, with the tree’s status, the loaded tree and its blackboard. You write no registration code.

Neither plugin depends on the other. AwakenDebug finds the tree component through a reflected function.

Tested on

AgentLoopBT is tested on macOS (Apple silicon) with Unreal Engine 5.8.4 and on Windows 11 with Unreal Engine 5.8. AwakenDebug is tested on Unreal Engine 5.9 on macOS. The two together are covered by the automation test AwakenDebug.Providers.AgentLoopBTIsListedAutomatically, which runs when both plugins are in the project.

What AgentLoopBT is

  • UAgentLoopBTComponent is an actor component. It loads a tree from a file or from inline JSON and ticks it once per frame.
  • The trees are run by AgentLoop’s Rust behaviour tree engine, linked into the plugin as a static library. Unreal’s own Behavior Tree assets are not used.
  • The plugin is C++ only. It exposes nothing to Blueprint.

It binds two leaves that act on the owning actor:

CallNode typeBehaviour
MoveForwardactionTurns toward the target and moves MoveSpeed * DeltaTime. Running until the actor is within AcceptanceRadius, then succeeded. Writes distanceToTarget to the blackboard.
IsNearTargetconditionSucceeds when the actor is within AcceptanceRadius of the target.

A tree that calls anything else fails to load, and the error names the unbound call. Nodes that need the AgentLoop daemon (llm-action, llm-selector, llm-condition and plugin-action) are refused at load.

Add AgentLoopBT to a project

Build the Rust library

The static library is a build product. From the AgentLoop repository:

vendor/unreal-plugins/AgentLoopBT/Scripts/build-rust-lib.sh

Copy the plugin into the project

vendor/unreal-plugins/AgentLoopBT/Scripts/install-into-project.sh /path/to/MyGame

The script refuses to run until the Rust library is built.

Enable it

MyGame.uproject
"Plugins": [ { "Name": "AgentLoopBT", "Enabled": true } ]

Build the editor target

Close the editor and build your project.

Give an actor a tree

#include "AgentLoopBTComponent.h" UAgentLoopBTComponent* Brain = CreateDefaultSubobject<UAgentLoopBTComponent>(TEXT("Brain")); Brain->TreePath = TEXT("Content/AI/ApproachTarget.bt.json"); // relative to the project directory Brain->TargetActor = SomeActor;
PropertyDefaultUse
TreePathPath to a .bt.json file: absolute, or relative to the project directory. Ignored when TreeJson is set.
TreeJsonInline .bt.json text. Takes precedence over TreePath.
TargetLocationZero vectorWhere MoveForward heads when TargetActor is unset.
TargetActorWhen set, MoveForward heads for this actor.
MoveSpeed300Centimetres per second.
AcceptanceRadius50Centimetres.
bLoadOnBeginPlaytrueLoad the tree in BeginPlay.
bRestartWhenFinishedfalseReset and run the tree again after it succeeds or fails.

Use SetBlackboardValue and GetBlackboardValue to share state with the tree. Blackboard values are strings.

A loose .bt.json under Content/ is not cooked. A packaged game needs its folder under Additional Non-Asset Directories to Package, or the tree inlined through TreeJson.

See the tree in Awaken

With AwakenDebug in the same project, start the game and press F10. Every actor with a UAgentLoopBTComponent is listed:

FieldComes from
StatusThe tree’s status.
GoalThe blackboard’s goal key, when the tree sets one.
TreeThe loaded .bt.json.
BlackboardThe keys the component knows about: the ones set through SetBlackboardValue, the ones its leaves write (distanceToTarget, lastError), goal and treeTicks.

AwakenDebug looks for such actors once a second.

A blackboard key that only tree nodes write is not shown. The engine’s C interface cannot list keys, so the component reports only the keys it knows about.

The same rows appear in the NPC file, so the Awaken app and GameGen show them too.

Let your own component report

Any component can take part without registration code. Declare this reflected function on it:

UFUNCTION() void GetAwakenDebugInfo(FString& Status, FString& Goal, TMap<FString, FString>& Blackboard, FString& TreeJson);

AwakenDebug matches the function by its name and by the order and types of its four parameters. The parameter names are free. Unreal does not allow a parameter named like one of the class’s own properties, so rename them if they clash, as UAgentLoopBTComponent does with OutStatus, OutGoal, OutBlackboard and OutTreeJson.

How often the function is read depends on the class:

  • An actor with a UAgentLoopBTComponent is found and listed automatically.
  • For a component of any other class, register the actor or add the Awaken Npc component. Its GetAwakenDebugInfo is then read four times a second.

What the game sets wins

A collected status or goal is used only while the game has left that field empty. A blackboard key set by the game hides a collected key of the same name.

Limits of AgentLoopBT

  • No Blueprint API.
  • No debug link to the daemon, no time travel and no editor interface of its own. AwakenDebug is how you see its trees.
  • The static library is about 64 MB on arm64. The linker strips what the plugin does not call.

Next steps

Last updated on