StateTree Integration
Table of Contents
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.