StateTree Integration

Table of Contents

  1. Overview
  2. Schema Types
    1. Pulse Quest (UPulseQuestStateTreeSchema)
    2. Pulse Quest Director (UPulseQuestDirectorStateTreeSchema)
    3. External data
  3. Tasks
    1. Quest Objective (FStateTreeStartObjective)
    2. Start Quest (FStateTreeStartQuestTask)
    3. Finish Quest (FPulseQuestTask_FinishQuest)
    4. Wait for tasks
    5. Other tasks
  4. Conditions and Considerations
  5. StateTree Events

Overview

The logic of a quest is a StateTree with the Pulse Quest schema. The quest instance runs it on the authority and ticks it with the quest manager. A director can run a StateTree as well, with the Pulse Quest Director schema (see Quest Director). When a quest is saved, its active state is stored (by state id, with the path as fallback); after loading, the quest continues in that state.

A quest finishes when its StateTree finishes: Tree Succeeded → Success, Tree Failed → Failure, stopped → Stopped. The Finish Quest task ends it from any state.


Schema Types

Pulse Quest (UPulseQuestStateTreeSchema)

Context data:

Name Type (default, can be changed on the schema)
Quest QuestClass – UPulseQuest
MetaData MetaDataClass – the quest’s MetaData object (optional)
QuestData QuestDataClass – UPulseQuestData
QuestManager QuestManagerClass – an object implementing IPulseQuestManagerInterface
QuestManagerData QuestManagerDataClass – UPulseQuestManagerData

Set the classes on the schema to your subclasses to bind their properties directly. Task properties in the category Context bind to the context data automatically.

Pulse Quest Director (UPulseQuestDirectorStateTreeSchema)

Context data: QuestManager, QuestManagerData, QuestDirector (UPulseQuestStateTreeDirector subclass).

External data

Nodes may request external data of these types; the quest manager provides them:

Type Source
World subsystem The world of the quest manager
Game instance subsystem The game instance
Local player subsystem The first local player
Actor component Component of the actor that owns the quest manager
Actor The actor that owns the quest manager (if the type matches)

Other external data types are not allowed in quest StateTrees.


Tasks

Quest Objective (FStateTreeStartObjective)

Runs an objective while the state is active.

Parameter Description
ObjectiveClass Objective to start (see Objectives)
SaveID Overrides the save id of the objective class. Needed if the same class runs twice in one quest
ShouldBeSaved Default uses the class
DisplayText, TargetProgress Override the display text and target progress of the class
Targets Marker targets (actor or location with radius), e.g. where to go. Used by Reach Location
CompletionMode Result the objective gets when the state is left before it completed
StoppedResult Whether an objective that ends with no result finishes the task with success or failure
bRemoveSaveIDFromFinishedObjectives Forget the finished result when the state is left, so the objective can run again when the state is entered again
Output ObjectiveHandle Handle of the started objective

The task succeeds or fails with the objective. Objectives that already finished in a saved run finish the task right away (see StartIfCompletedAtSave). Save ids: if neither the task nor the class sets one, the task generates one from the state and the objective class, so objectives are saved without setup. The StateTree validator reports two objectives with the same save id in one quest.

Start Quest (FStateTreeStartQuestTask)

Starts another quest of the same manager (owner Quest).

Parameter Description
QuestTag Quest to start
bWaitForCompletion If true, the task runs until the quest ends and finishes with its result
FinishType Result the quest gets when the state is left while the task waits (or before the quest started). None keeps it running
DuplicateBehavior Quest already active or queued: Fail, Succeed or TreatAsStarted
bIgnoreConditions Start the quest even if its conditions do not pass
StoppedResult How a quest that ends with no result finishes the task

Finish Quest (FPulseQuestTask_FinishQuest)

Ends this quest with Result (Success, Failure or Stopped) at the start of the next manager tick.

Wait for tasks

Task Parameters Finishes when
Wait for (Quest Started) QuestTag, bCompleteWithSuccess The quest starts. If it is already active, right away
Wait for (Quest Finished) QuestTag, StoppedResult The quest ends, with its result. Succeeds right away if the quest is not active
Wait for (Objective Started) QuestTag, ObjectiveClass, bCompleteWithSuccess A matching objective starts. If one is already active, right away
Wait for (Objective Finished) QuestTag, ObjectiveClass, StoppedResult A matching objective ends, with its result. Succeeds right away if none is active
Wait for Quest Event EventTag, bExactMatch, ContextTagQuery, RequiredCount, bOnlyEventsOfQuestManager Enough matching gameplay events arrived. Output: Count, LastEvent

Other tasks

Task Description
Broadcast Quest Event Broadcasts a gameplay event (instigator: owner of the quest manager if not set) and succeeds
Set Story Flag Sets or clears story flags and succeeds
Set Quest State Director only, see Quest Director

All tasks except Quest Objective, Start Quest and Finish Quest can be used in quest and director StateTrees.


Conditions and Considerations

Node Schemas Description
Compare Tag (condition) both TagA is TagB (or a child of it without bExactMatch), bInvert
Is Quest Active (condition) both The quest QuestTag runs (bInvert)
Can Start Quest (condition) both CanStartQuest succeeds for QuestTag, including its conditions (bInvert)
Quest Finished (condition) both QuestTag finished at least MinCount times with one of Results, from the quest history (bInvert)
Is Objective Active (condition) both A matching objective runs (QuestTag, ObjectiveClass, both optional, bInvert)
Has Story Flag (condition) both The story flags match Query (bInvert)
Is Objective Finished (condition) quest The objective with SaveID finished in this run with one of Results (bInvert)
Gameplay Tag Input (consideration) both Score from TagScores for the bound Tag

Use Quest Finished and Has Story Flag to branch the story, Is Objective Finished for branches inside a quest. StateTree’s own Delay task and event transitions cover timers and gameplay events.


StateTree Events

SendEventToQuest on the quest manager (or Send Quest State Tree Event in UPulseQuestLibrary) sends a FStateTreeEvent to the StateTree of a running quest (authority). Use it for “On Event” transitions.


Back to top

Copyright © 2026 LuQ Studios. Distributed under the MIT License.

This site uses Just the Docs, a documentation theme for Jekyll.