Architecture
Table of Contents
Module Structure
| Module | Type | Content |
|---|---|---|
PulseQuest | Runtime | Quest managers, quest runtime, quests, objectives, director, StateTree schemas and nodes, gameplay events, save types |
PulseQuestMVVM | Runtime | View models for UI (UMVVMPulseQuestManager, …) and the Quest UI settings |
PulseQuestEditor | Editor | StateTree validator (objective save ids), deprecated director editor extension |
PulseQuest has no dependency on other Pulse plugins. Integrations are separate bridge plugins: PulseDialogQuestBridge (dialogs and cutscenes of PulseDialog) and others; saving with PulseSave needs none (the managers save themselves as bytes).
Object Model
IPulseQuestManagerInterface UPulseQuestManager component or APulseSharedQuestHost actor
└─ UPulseQuestRuntime all state and logic of the manager (transient subobject)
├─ UPulseQuestManagerData replicated, saved: history, story flags, tracked quest
├─ UPulseQuestDirector (optional) authority only, saved
├─ active quests (by tag)
│ ├─ UPulseQuestInstance authority only, runs the quest StateTree
│ └─ UPulseQuestData shell: the entry owns its run state (replicated list) and server state; saved
├─ active objectives (by handle) each entry owns the FPulseObjectiveState, copied into the replicated list
│ └─ UPulseQuestObjective shell: reads its state from the entry; replicated unless NetMode = ServerOnly
└─ extensions e.g. the view model of the manager
Pulse.Message.Quest.GameplayEvent message bus channel: gameplay events that quests count
UPulseQuest(data asset) describes a quest: tag, texts, default flags, conditions, rewards, quest data class, StateTree.UPulseQuestSet(data asset) lists the quests a manager may start as tags: exact quests, quest groups and other sets.- Quest catalog (
Pulse::Quest::Catalog): quests are definitions of PulseFoundation with the idPulseQuest:<tag>. The runtime resolves them through anFPulseDefinitionResolver, keeps the quests it loaded (LoadedQuests) and the starts that wait for a quest (pending starts). See Quest Catalog. UPulseQuestRuntimeholds active quests and objectives, the event queue, the load stack and the director, and does save and load. Manager implementations only create it and forward ticks, replication and RPCs.UPulseQuestInstanceexecutes the StateTree of a running quest on the authority.UPulseQuestDatais the data of a running quest that clients see and that is saved. Its run state (FPulseQuestRunState) and server state (FPulseQuestRunServerState) are owned by the runtime entry of the run while it is registered; loaded data on the load stack keeps them itself.UPulseQuestObjectiveis a unit of work inside a quest. It is a gameplay task owner. Its state (FPulseObjectiveState) is owned by the runtime entry while it is registered (detached state otherwise).UPulseQuestManagerDataholds manager wide data (subclass it for your own). Its story (history, flags, tracked quest) is one state struct,FPulseQuestStoryState, changed with the pure functions ofPulse::Quest::Story.
State and rules live in plain structs and pure functions (Quest/State); the objects call the rules on a copy of their state, apply the result in one step, replicate it and fire their events afterwards.
Quest data, objectives, quest instances and the director keep the manager object (component or host) as outer, so GetQuestManager() and replication work on all of them.
Lifecycle
BeginPlayof the manager callsUPulseQuestRuntime::Initialize: the authority starts loading the exact quests of its set (bPreloadQuests), creates the manager data and the director.StartQuestchecksCanStartQuest(authority only) and queues an AddQuest event. A quest that still loads becomes a pending start; its AddQuest event is queued when it arrived.- In the next manager tick the event creates the quest instance and quest data, starts the StateTree and replicates the data. The quest gets a run id that is the same on server and clients.
- A Quest Objective task (or
StartObjective) queues an AddObjective event. It runs in the same tick (the queue is processed until it is empty, up to 8 passes). The objective is created, loaded from saved data if any, started and replicated. - When an objective completes, the quest is notified and a RemoveObjective event is queued.
- When the StateTree finishes or
StopQuestis called, all objectives of the quest are stopped, the history is written, clients get an RPC and a RemoveQuest event is queued. EndPlayof the manager cleans everything up. Queued events and pending starts are cancelled, so everyone waiting for them gets a failure; loads of quests are cancelled.
Event Queue
All changes to active quests and objectives go through the event queue of the runtime. This keeps starts, stops, resets, saves and loads in a defined order and avoids changing the active maps while they are iterated.
| Event | Purpose |
|---|---|
AddQuest / RemoveQuest / StopQuest | Start, remove or stop a quest (authority) |
AddObjective / RemoveObjective | Start or remove an objective |
SyncReplicated | Clients: add and remove local quests and objectives to match the replicated ones |
Reset | Stops everything, clears the manager data, restarts the director. Discards later events |
Save | Saves. Later events wait for the next tick |
Load | Loads. Discards later events |
Every event is either processed or cancelled. A cancelled start calls OnAdded with failure, a cancelled save or load finishes with failure. StateTree tasks therefore never wait forever.
Consequences:
StartQuestandStartObjectivetake effect in the next manager tick.- A quest that finished can be started again right away; its old run is removed first.
ResetQuestManager, async saves andLoadQuestManagerfinish in a later tick; listen toOnResetEvent,OnSavedEventorOnLoadedEvent.
Ticking
The manager only ticks while it has something to do: queued events, running quests (authority), objectives that tick or a director. Objectives tick only if they use it (bWantsTick in C++ or an implemented Blueprint Tick).
Replication Strategy
- Quests, objectives and manager data are replicated as sub-objects (registered sub-object list) with fast array containers and push model.
UPulseQuestManagerreplicates to its owner only;APulseSharedQuestHostreplicates to its players.- Clients compare the replicated lists with their client ledger (
SyncReplicated): the pure planPulse::Quest::ClientSync::PlanSyncgets the replicated runs and objectives as ids and flags and returns the steps (add, finish, remove, update) and the new ledger; the runtime stores the ledger and executes the steps. New runs are added, runs that are not replicated anymore (finished, reset, removed) are finished and removed. - Results of quests and objectives arrive by reliable RPC and are planned the same way. A result that arrives before its quest or objective is kept and applied when it arrives; results that can never be applied are dropped, so clients keep neither “ghost” quests nor results forever.
See Multiplayer.
Diagnostics
LogPulseQuestlog category; quest manager logs are also Visual Logger entries of the manager.stat Quest(stat groupSTATGROUP_Quest): manager tick, event queue, quest instance tick, objective tick, director tick.