Unreal C++ API Reference¶

Full API reference for the TryllClient Unreal Engine plugin, auto-generated from Doxygen documentation blocks in tryll/clients/unreal/Source/TryllClient/Public/. Browse individual classes and structs in the sidebar.

Entry points¶

Type	Role
`UTryllSubsystem`	`UGameInstanceSubsystem` — connect, configure, manage models, storages, and mutable KBs
`UTryllWorkflowAsset`	`UDataAsset` — editor-authored graph; assign to an agent component
`UTryllVoiceProfile`	`UPrimaryDataAsset` — an agent's voice (`FTryllVoiceProfileData Voice`); assign to `UTryllAgentComponent::VoiceProfile`
`FTryllAgent`	Agent handle delivered by `UTryllSubsystem::RequestCreateAgent`
`FTryllMutableKb`	Session store handle from `RequestEnsureMutableKb` — write, query, list, export
`FTryllAgentVariables`	Per-agent Variables mirror — typed setters/getters, deferred flush

Components¶

UActorComponents you add to an actor. Their Blueprint surface is in the Blueprint Catalog; per-member detail is on each class page below.

Type	Role
`UTryllAgentComponent`	Manages one agent — graph, `SendMessage`, runtime param changes
`UTryllSpeakerComponent`	Plays streaming TTS audio
`UTryllLipSyncComponent`	Plays the viseme track on a face with ARKit morph targets
`UTryllVoiceInputComponent`	Microphone capture + STT

Graph types¶

Type	Role
`FTryllGraphDescription`	Complete graph: nodes (with typed params carrying exit fields), start node, default model name. There is no separate routes list
`FTryllGraphBuilder`	Fluent builder for `FTryllGraphDescription`
`FTryllNodeDescription`	Single node definition — name + typed params pointer
`UTryllNodeParamsBase`	Base class for typed node params; exit fields live on each concrete subclass

Supporting types¶

Type	Role
`FTryllError`	Error envelope — `ETryllErrorCode` + message string
`FTryllModelInfo`	Model catalog row returned by `RequestListModels`. `TtsCapabilities` (when `bHasTtsCapabilities`) says which voice fields a TTS model can use, including `bExpressiveness` and `NumSpeakers`
`FTryllVoiceProfileData`	The voice fields (mirrors `VoiceProfile` in `voice.fbs`): `TtsModelName`, `SpeakerId`, `ReferenceVoice`, `VoiceDescription`, `Speed`, `Lang`, `Expressiveness`, `Prepare`, `bEmitVisemes`, `DeliveryModes`, `DefaultDeliveryMode`. `Validate` / `ValidateAgainst` run the checks the server makes
`FTryllDeliveryMode`	One named delivery: `Name`, `ReferenceVoice`, `Instruction`, `Expressiveness`, `SpeedScale`
`FTryllMemorySnapshot`	Server-wide RAM/VRAM snapshot returned by `RequestGetMemoryConsumption`
`FTryllMutableKbInfo`	Enumerated session store row (`Name`, `Schema`, live count, generation)
`FTryllMutableKbSnapshot`	Per-store TMKB snapshot (`ToFlatBufferBytes` / `FromFlatBufferBytes`)
`FTryllGameMemorySnapshot`	Whole-session TMKB (`save_id` + stores)
`FTryllToolDefinition`	Tool declaration
`FTryllToolParamDefinition`	Single parameter within a `FTryllToolDefinition`
`FTryllVariableDecl`	Name + typed initial value, declared on `UTryllWorkflowAsset::Variables` / passed to `CreateAgent`
`FTryllVariableOverride`	Per-instance initial-value override for a declared variable (Material-Instance pattern)
`UTryllSubsystem::FEmbeddedStorageInfo`	Embedded-storage descriptor
`UTryllRuntimeSettings`	Project settings (`UDeveloperSettings`) — engines, auto-launch, storage
`UTryllNodeParamsFactory`	Blueprint/C++ factory: `MakeXxxParams` + `CloneParams` for node params
`FTryllVoiceInput`	STT session handle owned by `UTryllVoiceInputComponent`
`FTryllTranscriptUpdate`	Transcript update payload (`Text`, `Kind`, `AudioMsConsumed`)
`ETryllWorkload`	`Interactive` / `Background` — scheduling hint on `UTryllAgentComponent::Workload` and `RequestCreateAgent`

Headers¶

Header	Declares
`TryllSubsystem.h`	`UTryllSubsystem`, `FEmbeddedStorageInfo`
`TryllAgent.h`	`FTryllAgent`, `FTryllDialogInteraction`. Voice: `SetVoice`, `SetDeliveryMode`, `GetVoice`, `GetDeliveryMode`. TTS setters: `SetOnTtsAudioFormat`, `SetOnTtsAudio`, `SetOnTtsVisemes`
`TryllVoiceProfile.h`	`UTryllVoiceProfile`, `FTryllVoiceProfileData`, `FTryllDeliveryMode`, `ETryllVoicePreparation`
`TryllAgentVariables.h`	`FTryllAgentVariables`
`TryllVariableDecl.h`	`FTryllVariableDecl`, `FTryllVariableOverride`, `ETryllVariableType`
`TryllAgentComponent.h`	`UTryllAgentComponent`
`TryllSpeakerComponent.h`	`UTryllSpeakerComponent` (native delegates `OnTtsPcm`, `OnTtsTurnStarted`, `OnTtsVisemes`), `FTryllTtsPlaybackClock`
`TryllTtsPlaybackEvents.h`	`FTryllTtsPlaybackEvents`
`TryllLipSyncComponent.h`	`UTryllLipSyncComponent`
`TryllVisemeEvent.h`	`ETryllViseme`, `FTryllVisemeEvent`, `FTryllVisemePose`, `FTryllVisemeChannelWeight`, `FTryllVisemeSettings`
`TryllVisemePlayer.h`	`FTryllVisemePlayer` (evaluates a viseme track; used by the MetaHuman plugin)
`TryllVoiceInputComponent.h`	`UTryllVoiceInputComponent`
`TryllVoiceInput.h`	`FTryllVoiceInput`, `FTryllTranscriptUpdate`, `ETryllTranscriptUpdateKind`
`TryllWorkflowAsset.h`	`UTryllWorkflowAsset`
`TryllRuntimeSettings.h`	`UTryllRuntimeSettings`, `EServerBuildVariant`
`TryllGraphDescription.h`	`FTryllGraphDescription`, `FTryllGraphBuilder`, `FTryllNodeDescription`, `ETryllInferenceEngine`, `ETryllNodeType`
`Generated/TryllNodeParamsFactory.h`	`UTryllNodeParamsFactory`
`TryllModelInfo.h`	`FTryllModelInfo`, `ETryllModelStatus`, `FTryllTtsCapabilities`
`TryllMemorySnapshot.h`	`FTryllMemorySnapshot`, `FTryllMemoryDevice`, `FTryllMemoryComponent`, `ETryllMemoryTier`
`TryllMutableKb.h`	`FTryllMutableKb`
`TryllMutableKbTypes.h`	Upsert/hit/record/stats/info DTOs, embed timing, compatibility
`TryllMkbSnapshot.h`	`FTryllMutableKbSnapshot`, `FTryllGameMemorySnapshot`
`TryllError.h`	`FTryllError`, `ETryllErrorCode`
`TryllThrottle.h`	`ETryllWorkload`

Selected method signatures¶

`UTryllSubsystem::CreateSession`¶

UFUNCTION(BlueprintCallable, Category = "Tryll|Session")
void CreateSession(
    FString GameName = TEXT(""),
    FString Locale = TEXT(""),
    bool    bUseProjectLocaleWhenEmpty = true);

The call takes no engine arguments, and it does not choose an engine: each model's catalog entry names the engine that runs it. Protocol v13 replaced the four per-role engine fields with an optional, advisory engines warm-up list. The subsystem still sends that list, built from the Model Manager manifest (UTryllRuntimeSettings::BuildEngineDeclarations()), so the server can start those engines early. It never gates a load.

GameName maps to the same-named UTryllRuntimeSettings field. It is the session name, and the empty-name fallback for --project-name. Telemetry groups by a hidden project id. See Telemetry. Storage Data Folder is a launcher setting: the plugin passes --storage-root (default <Project>/TryllStorage/, outside Content/). It is not sent on CreateSession (protocol v24). CreateAgent, CreateEmbeddedStringStorage, and CreateVoiceInput fail fast if a referenced model is not already on disk — acquire models explicitly beforehand via the editor Model Manager.

To configure from the project settings asset instead of passing parameters, call CreateSessionFromSettings() — this runs automatically once connected when UTryllRuntimeSettings::bAutoCreateSession is true.

`UTryllSubsystem::RequestGetMemoryConsumption`¶

void RequestGetMemoryConsumption(TFunction<FTryllOnGetMemoryConsumption> OnComplete);

Session-scoped (needs CreateSession) but the numbers are server-wide — every session on that process. Never returns AgentBusy. Not a UFUNCTION; Blueprint binds OnGetMemoryConsumptionComplete after a C++ call. See Inspect Server Memory.

Experimental mutable knowledge bases¶

Session-scoped named stores. Enumerate, save, and load live on UTryllSubsystem; per-store ops live on FTryllMutableKb (TFunction completions, same style as FTryllAgent). RequestLoadGameMemory rejects Unspecified locally (InvalidEmbedTiming, 8107). Inspect and edit stores in Window ▸ Tryll ▸ Tryll Knowledge: list stores, Filter and Query records, write (upsert an id and text), delete selected records, clear a store, and export or import TMKB snapshots. See Save and Load Agent State.

void RequestEnsureMutableKb(
    const FString& Name,
    const FString& Schema,
    TFunction<FTryllOnEnsureMutableKb> OnComplete);

void RequestEnumerateMutableKbs(TFunction<FTryllOnEnumerateMutableKbs> OnComplete);

void RequestSaveGameMemory(
    const FString& Path,
    const FString& SaveId,
    TFunction<FTryllOnSaveGameMemory> OnComplete);

void RequestLoadGameMemory(
    const FString& Path,
    ETryllMutableKbEmbedTiming EmbedTiming,
    ETryllMutableKbCompatibility Compatibility,
    TFunction<FTryllOnLoadGameMemory> OnComplete);

Optional Blueprint multicast exists for the four session ops. The handle is not a UObject.

Usage¶

Build a graph in C++¶

Set node parameters on a params object, then add it to the builder and create the agent from the resulting graph:

UTryllGenerateParams* P = UTryllNodeParamsFactory::MakeGenerateParams(this);
P->bOverrideModelName    = true;
P->ModelName             = TEXT("qwen2.5-0.5b-instruct");
P->bOverrideSystemPrompt = true;
P->SystemPrompt          = TEXT("You are helpful.");

const FTryllGraphDescription Graph =
    FTryllGraphBuilder()
        .AddNode(TEXT("gen"), P)
        .SetStartNode(TEXT("gen"))
        .SetDefaultModelName(TEXT("qwen2.5-0.5b-instruct"))
        .Build();

Subsystem->RequestCreateAgent(Graph,
    [](TSharedPtr<FTryllAgent> Agent, FTryllError Error) { /* … */ });

The typed helpers are free functions generated into TryllGraphBuilder.Nodes.h: AddGenerateNode(Builder, Name, Params), AddRetrieveNode(Builder, Name, Params), and one Add<NodeType>Node per node type. They are not members of FTryllGraphBuilder, so .AddGenerate(...) does not compile. The member AddNode(Name, Params) accepts any node type.

When you drive an agent through UTryllAgentComponent, author the graph as a UTryllWorkflowAsset (Content Browser → Tryll → Workflow Asset) and assign it to the component's Workflow Asset slot. A component cannot create an agent without one.

Give an agent a voice¶

A graph with a Speak or Generate And Speak node needs a voice profile; the server refuses it with AgentVoiceRequired (3025) otherwise. On UTryllAgentComponent, assign a UTryllVoiceProfile asset to Voice Profile. With the subsystem, pass the voice as the trailing argument of RequestCreateAgent:

On a component, enable Voice Delivery to override the profile's default for that agent instance. The dropdown contains neutral and the profile's named modes; changing it also switches a live PIE or Tryll Chat agent.

FTryllVoiceProfileData Voice;
Voice.TtsModelName = TEXT("Pocket TTS (int8)");
Voice.ReferenceVoice.Path = TEXT("voices/mack.wav");
Voice.bEmitVisemes = true;
FTryllDeliveryMode Angry;
Angry.Name = TEXT("angry");
Angry.ReferenceVoice.Path = TEXT("voices/mack_angry.wav");
Voice.DeliveryModes.Add(Angry);

Subsystem->RequestCreateAgent(
    Graph,
    [](TSharedPtr<FTryllAgent> Agent, const FTryllError& Err) { /* ... */ },
    /*bEnableDiagnostics=*/false,
    /*bMaintainDialogueHistory=*/true,
    /*Variables=*/{},
    ETryllKvCacheInitialization::AllocateOnly,
    ETryllWorkload::Interactive,
    Voice);

At runtime, switch the delivery mode (allowed mid-turn, applies from the next sentence) or replace the voice (idle only):

Agent->SetDeliveryMode(TEXT("angry"), /*Intensity=*/0.8f,
    [](const FTryllError& Err) { /* 3024 UnknownDeliveryMode for an undefined mode */ });
Agent->SetVoice(OtherProfile->Voice,
    [](const FTryllError& Err) { /* 3023 InvalidVoiceProfile keeps the old voice */ });

UTryllAgentComponent::SetVoice(UTryllVoiceProfile*) and SetDeliveryMode(Mode, Intensity) wrap these and report through OnVoiceChanged / OnDeliveryModeChanged. ChangeParams cannot reach any voice field.

Change a node parameter at runtime¶

Clone the baseline, set the field's bOverrideXxx flag along with the value, then send. The agent must be idle or paused; OnParamChanged fires on completion:

auto* Base = Cast<UTryllGenerateParams>(AgentComponent->GetNodeParamsBaseline(TEXT("gen")));
auto* Mut  = Cast<UTryllGenerateParams>(UTryllNodeParamsFactory::CloneParams(Base, this));
Mut->bOverrideSystemPrompt = true;
Mut->SystemPrompt          = TEXT("New prompt");
AgentComponent->ChangeParams(TEXT("gen"), Mut);

Pause and resume a turn¶

FTryllAgent::Resume / UTryllAgentComponent::Resume continue a turn suspended at a Pause node or a paused ToolCall. Two events report the pause. UTryllAgentComponent::OnPaused (NodeName, PendingExit) fires for that component's agent only. UTryllSubsystem::OnPaused adds an AgentId and fires for every agent. ChangeParams is allowed while parked:

// Bound to AgentComponent->OnPaused (UFUNCTION on this class).
void AThisClass::HandlePaused(const FString& NodeName, const FString& PendingExit)
{
    // ChangeParams here is allowed — the agent is paused, not busy.
    AgentComponent->Resume(); // empty = continue via PendingExit; or Resume(TEXT("other_node")) to jump
}

See How to pause and resume a turn.

Append or remove scripted dialog history¶

FTryllAgent::AppendInteractions / RemoveInteractionsFromEnd mutate history without running the graph. Strict idle-only (AgentBusy while running, paused, or during a KV-cache operation). Each FTryllDialogInteraction has UserMessage / AssistantMessage — empty strings omit that side; both empty → skipped server-side.

TArray<FTryllDialogInteraction> Seed;
{
    FTryllDialogInteraction Opener;
    Opener.AssistantMessage = TEXT("Welcome, traveler.");
    Seed.Add(Opener);
}
Agent->AppendInteractions(Seed,
    [](uint32 Count, const FTryllError& Err)
    {
        if (Err.IsOk()) UE_LOG(LogTemp, Log, TEXT("Appended %u interactions"), Count);
    });

Agent->RemoveInteractionsFromEnd(1); // drop last whole interaction

See Seed and edit dialog history.

Export and import a dialog snapshot¶

FTryllAgent::ExportDialog / ImportDialog capture or replace the completed dialog. These are C++ only — FTryllDialogSnapshot is not Blueprint-exposed. ToFlatBufferBytes / FromFlatBufferBytes produce canonical TDLG bytes; the game owns storage. See Export and import dialog and Save and load agent state.

Throttle the GPU and mark background agents¶

UTryllSubsystem::SetInferenceThrottle (Blueprint-callable, Tryll|Session) reports how hard the server should yield the GPU back to your game — 0.f = full speed (the default for a session that never calls it), 1.f = maximum yielding. Fire-and-forget: no request id, no response, no completion delegate, so calling it from Tick costs nothing but the frame. It never changes what is generated, only how fast.

void AMyGameMode::Tick(float DeltaSeconds)
{
    Super::Tick(DeltaSeconds);
    // Example policy: yield harder as your own frame time worsens.
    const float Pressure = FMath::GetMappedRangeValueClamped(
        FVector2D(11.f, 20.f), FVector2D(0.f, 1.f), DeltaSeconds * 1000.f);
    GetGameInstance()->GetSubsystem<UTryllSubsystem>()->SetInferenceThrottle(Pressure);
}

Agents nobody is waiting on should say so, so their inference is the first to give way. On UTryllAgentComponent this is the Workload property (Tryll|Agent category, editable in the Details panel); in C++ it is the trailing Workload argument to UTryllSubsystem::RequestCreateAgent:

Subsystem->RequestCreateAgent(
    Graph,
    [](TSharedPtr<FTryllAgent> Agent, const FTryllError& Err) { /* ... */ },
    /*bEnableDiagnostics=*/false,
    /*bMaintainDialogueHistory=*/true,
    /*Variables=*/{},
    ETryllKvCacheInitialization::AllocateOnly,
    ETryllWorkload::Background);

Everything else the server classifies from the graph itself, per turn — streamed Generate text is protected, spoken and buffered work absorbs the slack. See Wire Protocol and Server configuration.

Read and write Agent Variables¶

FTryllAgent::GetVariables() returns the Agent Variables mirror. Writes update the local mirror synchronously; the wire update is batched and flushed automatically immediately before the next SendMessage/Resume/ChangeParams call:

FTryllAgentVariables& Vars = Agent->GetVariables();
FTryllError Err = Vars.SetInt(TEXT("level"), 13);
if (!Err.IsOk()) UE_LOG(LogTemp, Warning, TEXT("%d: %s"), Err.Code, *Err.Message);
Vars.AddToSet(TEXT("quests_reached"), TEXT("lost_amulet"));
// Optional eager flush (Details "Flush Now" / UTryllAgentVariables::FlushIfDirty):
Vars.FlushIfDirty([](const FTryllError& FlushErr) { /* ... */ });

An unknown name or type mismatch returns a non-OK FTryllError immediately (no wire round-trip), using the same 3013/3014 codes the server would return.

Per-instance Variable Overrides on UTryllAgentComponent use the Material-Instance pattern (see Agent Variables). Details edits live-apply through UTryllAgentComponent::GetLiveVariables() when a PIE agent or Tryll Chat editor-preview agent is attached. Unchecking an override assigns the workflow declaration default. Helpers live in TryllVariableOverrideUtils.

Override flags

Most value fields on a UTryllXxxParams are gated by a bOverrideXxx flag; plain fields such as MinSentenceChars and FirstChunkMaxChars apply directly. (Voice settings are not node params: they live on the agent's voice profile.) For a gated field, set the flag or the value is silently ignored — the node falls back to the graph's default model / authored defaults. The clone preserves the baseline's flags, but set the flag explicitly when you start overriding a field the node didn't author.

Note

The component classes (UTryllAgentComponent, UTryllSpeakerComponent, UTryllLipSyncComponent, UTryllVoiceInputComponent) and project settings (UTryllRuntimeSettings) are also documented in the Blueprint Catalog; per-member detail is on the auto-generated class pages in the sidebar.