Architecture

Table of Contents

  1. Module Structure
  2. Object Model
  3. Lifecycle
  4. Event Queue
  5. Ticking
  6. Replication Strategy
  7. Diagnostics

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 id PulseQuest:<tag>. The runtime resolves them through an FPulseDefinitionResolver, keeps the quests it loaded (LoadedQuests) and the starts that wait for a quest (pending starts). See Quest Catalog.
  • UPulseQuestRuntime holds 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.
  • UPulseQuestInstance executes the StateTree of a running quest on the authority.
  • UPulseQuestData is 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.
  • UPulseQuestObjective is 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).
  • UPulseQuestManagerData holds manager wide data (subclass it for your own). Its story (history, flags, tracked quest) is one state struct, FPulseQuestStoryState, changed with the pure functions of Pulse::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

  1. BeginPlay of the manager calls UPulseQuestRuntime::Initialize: the authority starts loading the exact quests of its set (bPreloadQuests), creates the manager data and the director.
  2. StartQuest checks CanStartQuest (authority only) and queues an AddQuest event. A quest that still loads becomes a pending start; its AddQuest event is queued when it arrived.
  3. 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.
  4. 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.
  5. When an objective completes, the quest is notified and a RemoveObjective event is queued.
  6. When the StateTree finishes or StopQuest is called, all objectives of the quest are stopped, the history is written, clients get an RPC and a RemoveQuest event is queued.
  7. EndPlay of 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:

  • StartQuest and StartObjective take 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 and LoadQuestManager finish in a later tick; listen to OnResetEvent, OnSavedEvent or OnLoadedEvent.

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.
  • UPulseQuestManager replicates to its owner only; APulseSharedQuestHost replicates to its players.
  • Clients compare the replicated lists with their client ledger (SyncReplicated): the pure plan Pulse::Quest::ClientSync::PlanSync gets 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

  • LogPulseQuest log category; quest manager logs are also Visual Logger entries of the manager.
  • stat Quest (stat group STATGROUP_Quest): manager tick, event queue, quest instance tick, objective tick, director tick.

Back to top

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

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