Register NPCs in C++
UAwakenDebugSubsystem is the registry of a world’s NPCs. You register each NPC once, by actor or by id, then call setters as the NPC changes. Every Awaken view shows what you set.
Before you start
- AwakenDebug is installed in the project.
- Your game module’s
Build.cshasPrivateDependencyModuleNames.Add("AwakenDebug");.
Register and update an NPC
Get the subsystem
Get returns null outside a game or Play In Editor world, so check the result.
#include "AwakenDebugSubsystem.h"
UAwakenDebugSubsystem* Debug = UAwakenDebugSubsystem::Get(this);
if (!Debug)
{
return;
}Register the NPC
Register an actor. Its position follows the actor, and the NPC is removed when the actor is destroyed.
const FString Id = Debug->RegisterActor(GuardActor, TEXT("Gate Guard"), TEXT("guard-1"));Or register something that has no actor, such as a squad, a director or a simulated entity:
Debug->RegisterNpc(TEXT("director"), TEXT("Encounter Director"));Report what it is doing
Debug->SetNpcStatus(Id, TEXT("Patrolling"));
Debug->SetNpcGoal(Id, TEXT("walk to the north gate"));
Debug->SetNpcGoals(Id, { TEXT("walk to the north gate"), TEXT("report in") });Report its blackboard
Choose the setter by the type of the value. The type is kept in the NPC file.
Debug->SetBlackboardValue(Id, TEXT("target"), TEXT("north gate")); // text
Debug->SetBlackboardNumber(Id, TEXT("distance"), 1240.0); // number
Debug->SetBlackboardBool(Id, TEXT("alert"), false); // true or falseAttach a behaviour tree snapshot
A snapshot is any JSON object, as text.
Debug->SetNpcTreeJson(Id, TEXT("{\"node\":\"Patrol\",\"status\":\"running\"}"));Remove the NPC
An actor’s NPC is removed with the actor. Remove any other NPC yourself.
Debug->UnregisterNpc(TEXT("director"));Choose stable ids
Use ids that stay the same between runs, such as guard-1 or a save-game id. The Awaken viewers select rows by id, so ids must be unique.
When you pass no id to RegisterActor, the id is the actor’s object name. That is stable for an actor placed in a level. A spawned actor gets the engine’s Class_N name, which depends on spawn order.
Function reference
All of these are members of UAwakenDebugSubsystem. Every one except Get is also callable from Blueprint.
Registration
| Function | Returns | Behaviour |
|---|---|---|
static UAwakenDebugSubsystem* Get(const UObject* WorldContext) | The subsystem, or null | Null outside a game or Play In Editor world. C++ only. |
bool RegisterNpc(const FString& Id, const FString& DisplayName) | false for an empty id | Registers by id alone. Registering an id again keeps its state and updates the name. |
FString RegisterActor(AActor* Actor, const FString& DisplayName = TEXT(""), const FString& Id = TEXT("")) | The id, or an empty string for a null actor | The id is Id when given, else the actor’s object name. |
void UnregisterNpc(const FString& Id) | Removes the NPC. | |
void UnregisterActor(AActor* Actor) | Removes the actor’s NPC. | |
bool IsRegistered(const FString& Id) const | ||
FString GetActorNpcId(const AActor* Actor) const | The id, or empty | The id an actor was registered under. |
State
Every setter returns false when the id is not registered.
| Function | Notes |
|---|---|
bool SetNpcName(const FString& Id, const FString& DisplayName) | |
bool SetNpcStatus(const FString& Id, const FString& Status) | A short state word or phrase: Idle, Patrolling, GameOver. |
bool SetNpcGoal(const FString& Id, const FString& Goal) | The goal the NPC is working on now. |
bool SetNpcGoals(const FString& Id, const TArray<FString>& Goals) | The goal list, most important first. |
bool SetNpcPosition(const FString& Id, FVector Position) | For an NPC that has no actor. Ignored while a registered actor is alive. |
bool SetBlackboardValue(const FString& Id, const FString& Key, const FString& Value) | Published as a JSON string. |
bool SetBlackboardNumber(const FString& Id, const FString& Key, double Value) | Published as a JSON number. |
bool SetBlackboardBool(const FString& Id, const FString& Key, bool bValue) | Published as a JSON boolean. |
bool RemoveBlackboardKey(const FString& Id, const FString& Key) | |
bool ClearBlackboard(const FString& Id) | |
bool SetNpcTreeJson(const FString& Id, const FString& TreeJson) | Any JSON object. An empty string removes the snapshot. Text that is not a JSON object returns false and keeps the previous snapshot. |
Reading and selection
| Function | Notes |
|---|---|
TArray<FString> GetNpcIds() const | In registration order. |
int32 GetNpcCount() const | |
bool GetNpc(const FString& Id, FAwakenNpcSnapshot& OutNpc) const | The NPC as the debug views show it: what the game set, plus what was collected from components. |
FString DescribeNpcs(bool bDetails = true) const | All NPCs as text. This is what Awaken.Dump logs. |
void SelectNpc(const FString& Id) | The NPC the HUD shows in detail. Empty selects the first one. |
FString GetSelectedNpcId() const |
FAwakenNpcSnapshot has the fields Id, Name, Status, Goal, Goals, Blackboard (values as text), TreeJson, Position and Actor.
What the file keeps
The HUD, the editor tab and Awaken.Dump show your values in full, cut only to fit a line. The NPC file has limits: for example 64 rows, 16 goals and 32 blackboard keys per NPC. See the limits table.
Next steps
- Prefer a component? See The Awaken Npc component.
- See the NPCs in the HUD.
- Have a component report its own state without registration code: Behaviour trees with AgentLoopBT.