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.
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
UAgentLoopBTComponentis 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:
| Call | Node type | Behaviour |
|---|---|---|
MoveForward | action | Turns toward the target and moves MoveSpeed * DeltaTime. Running until the actor is within AcceptanceRadius, then succeeded. Writes distanceToTarget to the blackboard. |
IsNearTarget | condition | Succeeds 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:
macOS
vendor/unreal-plugins/AgentLoopBT/Scripts/build-rust-lib.shCopy the plugin into the project
vendor/unreal-plugins/AgentLoopBT/Scripts/install-into-project.sh /path/to/MyGameThe script refuses to run until the Rust library is built.
Enable it
"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;| Property | Default | Use |
|---|---|---|
TreePath | Path to a .bt.json file: absolute, or relative to the project directory. Ignored when TreeJson is set. | |
TreeJson | Inline .bt.json text. Takes precedence over TreePath. | |
TargetLocation | Zero vector | Where MoveForward heads when TargetActor is unset. |
TargetActor | When set, MoveForward heads for this actor. | |
MoveSpeed | 300 | Centimetres per second. |
AcceptanceRadius | 50 | Centimetres. |
bLoadOnBeginPlay | true | Load the tree in BeginPlay. |
bRestartWhenFinished | false | Reset 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:
| Field | Comes from |
|---|---|
| Status | The tree’s status. |
| Goal | The blackboard’s goal key, when the tree sets one. |
| Tree | The loaded .bt.json. |
| Blackboard | The 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
UAgentLoopBTComponentis found and listed automatically. - For a component of any other class, register the actor or add the Awaken Npc component. Its
GetAwakenDebugInfois 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
- In-game panel, HUD and debugger.
- Register NPCs in C++ for state a tree does not report.