Skip to Content
AwakenUnreal pluginRegister NPCs in C++

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.cs has PrivateDependencyModuleNames.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 false

Attach 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

FunctionReturnsBehaviour
static UAwakenDebugSubsystem* Get(const UObject* WorldContext)The subsystem, or nullNull outside a game or Play In Editor world. C++ only.
bool RegisterNpc(const FString& Id, const FString& DisplayName)false for an empty idRegisters 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 actorThe 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) constThe id, or emptyThe id an actor was registered under.

State

Every setter returns false when the id is not registered.

FunctionNotes
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

FunctionNotes
TArray<FString> GetNpcIds() constIn registration order.
int32 GetNpcCount() const
bool GetNpc(const FString& Id, FAwakenNpcSnapshot& OutNpc) constThe NPC as the debug views show it: what the game set, plus what was collected from components.
FString DescribeNpcs(bool bDetails = true) constAll 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

Last updated on