Quest Manager
Table of Contents
- Overview
UPulseQuestManagerAPulseSharedQuestHost- Manager Parameters
- Manager Interface API
UPulseQuestLibrary- Messages
- Debugging
- Data Validation
- Subclassing
Overview
A quest manager runs the quests of a player or a group. There are two implementations of IPulseQuestManagerInterface:
| Class | Use |
|---|---|
UPulseQuestManager | Actor component, usually on the player controller or player state. Quests of one player. |
APulseSharedQuestHost | Actor (AInfo). Quests shared by a group of players (party). See Multiplayer. |
Both create a UPulseQuestRuntime that holds the state and logic. The interface can’t be implemented in Blueprint; Blueprints call its functions on either class. To find the manager of a player use Find Quest Manager (UPulseQuestLibrary), which looks at the actor, its controller, player state and pawn.
UPulseQuestManager
A UGameplayTasksComponent, so objectives can run gameplay tasks with the owner as task owner.
| Property / function | Description |
|---|---|
bAutoManageAvatarActor | On a player controller or player state, keeps the avatar on the controlled pawn (on a pawn: the pawn) |
Set Avatar Actor / Get Avatar Actor | Avatar for gameplay tasks and location objectives |
ManagerParams | See below |
Blueprint events: On Quest Started, On Quest Finished, On Objective Started, On Objective Finished, On Quest Manager Reset, On Quest Manager Saved, On Quest Manager Loaded (with FPulseQuestManagerLoadResultInfo).
The component replicates by default (to the owning connection only). Without a Quest Set it uses Default Quest Set of Project Settings > Pulse > Quest; Quest Manager in the same settings adds the component to every player controller automatically.
APulseSharedQuestHost
A placeable actor with its own player list (AddPlayer, RemovePlayer, HasPlayer, GetAllPlayers). It is only relevant for its players. Events: QuestStarted, Quest Finished, ObjectiveStarted, Objective Finished, QuestManagerReset, QuestManagerSaved, QuestManagerLoaded. See Multiplayer.
Manager Parameters
FPulseQuestManagerParams (component) and FPulseSharedQuestManagerParams (host) share FPulseQuestManagerParamsBase:
| Property | Description |
|---|---|
bAllowMultipleQuests | If false, a quest can only start while no other quest runs or is queued. Quests restored from a save are not limited |
QuestSet | Quests this manager may start |
QuestDirectorClass | Optional director, created on the authority |
QuestManagerDataClass | UPulseQuestManagerData subclass (UPulseSharedQuestManagerData for the host) |
View models are configured in Project Settings → Pulse → Quest → UI (see MVVM & UI).
Manager Interface API
Quests
| Function | Description |
|---|---|
StartQuest(Params) | Authority. Queues the start of a quest, or waits for its quest to load (pending start). Returns an FPulseResult: Success, or a Pulse.Quest.Failure.* reason with a text for the player (GetDisplayText) |
CanStartQuest(Params) | Same checks without starting, including the conditions of the quest (the line of the first failing condition is the message of the result). A quest the set allows that is not loaded yet starts loading and answers NotReady |
GetAvailableQuestTags(OutQuests) | Quests of the quest set (exact quests and the quests of the catalog below its groups) that CanStartQuest accepts right now, e.g. for a quest board |
HasQuestFinished(Quest, Results) | Whether the quest finished with one of the results (quest history) |
StopQuest(Quest, Result) | Authority. Stops a running quest with Success, Failure or Stopped |
SendEventToQuest(Quest, Event) | Authority. Sends a StateTree event to the quest |
IsQuestActive(Quest) | Whether the quest runs |
GetQuestData(Quest) | Quest data of an active quest |
GetActiveQuests(OutTags, OutData) / GetActiveQuestTags / GetNumActiveQuests | Running quests |
Start failure tags: Pulse.Quest.Failure.QuestNotFound (the quest set does not allow it, or no catalog knows it), .InvalidQuest (no valid StateTree), .DuplicateQuest (running, queued or a pending start), .AlreadyActive (bAllowMultipleQuests is false; pending starts count), .ConditionsNotMet (UPulseQuest::AreConditionsMet gives the line of the condition), .NoAuthority (called on a client), .NotReady (before BeginPlay, while cleaning up, or CanStartQuest of a quest that still loads).
Pending starts
A quest manager finds its quests through the quest catalog. Quest assets load at once when they are needed (the default catalog), and the exact quests of a set with bPreloadQuests load when the manager starts, so a start normally runs as before. A quest of a catalog that loads only asynchronously (a backend, daily quests) may not be ready when it is started:
CanStartQuestchecks the set, duplicates and the limit, starts the load and answersPulse.Quest.Failure.NotReady.StartQuestkeeps the start as a pending start and answers Success. When the quest arrives, the checks of a start run again, now with the conditions of the quest, and the quest starts like any other (OnAddedof the params reportstrue). A start whose conditions do not pass then, or whose quest does not load, reportsOnAdded(false)and a warning in the log.- Duplicates and the limit of
bAllowMultipleQuestscount pending starts; a reset or the end of the manager discards them (OnAdded(false)), like queued starts. IsQuestPending(Tag)of the runtime tells whether a quest loads or waits;PulseQuestInfolists the pending starts.- A quest the catalog does not know (
Pulse.Result.Failure.NotFoundor.Invalid) is not asked again until the quest definitions change (a quest is registered or unregistered, the kind gets another catalog). A timeout or another failure of the catalog is asked again by the next start. - The manager keeps the quests it loaded. When a quest is registered again with the same tag (a daily quest made anew from a template), the next start uses the new quest; quests that already run keep the quest they started with.
The event queue stays synchronous: an AddQuest event is queued only once its quest is there.
Blueprint: Stop a quest and send it an event
Send Event to Quest(Quest = quest tag, Event =Make StateTreeEventwith aTagand optional payload). The quest state tree receives the event (authority only).Stop Quest(Quest = quest tag, Result =Success,FailureorStopped).On Quest Finished(event dispatcher on the quest manager) →Quest Data→Is Stopped→Out Result.
Quest History
The manager data (UPulseQuestManagerData) records every quest that finishes on the authority, unless the quest has PQF_NoHistory. The history is replicated with the manager data and saved with it. A reset of the manager clears it. The entry is recorded before On Quest Finished is broadcast.
| Function (on the manager data) | Description |
|---|---|
HasQuestFinished(Quest, Results) | Finished at least once with one of the results (default Success) |
GetQuestFinishCount(Quest, Results) | How often it finished with one of the results |
GetLastQuestFinishResult(Quest) | Result of the last finish, None if never |
GetQuestHistoryEntry(Quest, OutEntry) / Get Quest History | FPulseQuestHistoryEntry with LastResult, NumSucceeded, NumFailed, NumStopped |
RemoveQuestHistoryEntry(Quest) / ClearQuestHistory() | Forget quests (authority) |
Get Story State | History, story flags and tracked quest as one FPulseQuestStoryState |
OnQuestHistoryChanged | Event on the authority and on clients |
The manager data also holds the story flags and the tracked quest. When a quest finishes, the runtime calls ApplyQuestFinished (C++, override it for own reactions and call Super): history and tracked quest change in one step, before the rewards and the quest events.
Objectives
| Function | Description |
|---|---|
StartObjective(Params) | Authority. Queues an objective for a running quest. Returns its handle |
GetObjective(Handle) | The objective of a handle |
GetActiveObjectives(OutObjectives) | All running objectives |
GetObjectivesForQuest(Quest, OutObjectives) | Running objectives of a quest |
IsObjectiveActive(Quest, ObjectiveClass) | Empty quest = any quest, empty class = any class |
GetNumActiveObjectives() | Number of running objectives |
Blueprint: Query active quests and objectives
Get Active Quests→Out Active Quests(tags) andOut Quest Data.Is Quest Active(Quest = tag) → Branch.Get Objectives for Quest(Quest = tag) →For Each Loop→ readCompletion Statusor cast to your objective class.Is Objective Active(Quest = tag or empty for any quest, Objective Class = class or empty for any class).
Reset, save and load
| Function | Description |
|---|---|
Reset Quest Manager | Authority. Stops all quests and objectives, clears the manager data and restarts the director in a later tick |
SaveQuestManager(SaveTo, bSaveAsync) / LoadQuestManager(LoadFrom, Params) | See Save & Load |
AddSaveObject / RemoveSaveObject | Own objects saved with the manager |
Get Quest Manager Data | The manager data |
Native events (C++)
OnQuestStartedEvent, OnQuestFinishedEvent, OnObjectiveStartedEvent, OnObjectiveFinishedEvent, OnResetEvent, OnSavedEvent, OnLoadedEvent. They live on the runtime (GetQuestRuntime()), which also has OnManagerDataChanged.
Net helpers
GetOwnerNetRole, IsLocallyControlled, IsQuestManagerReplicated, GetQuestAvatars, IsActorOfQuestManager, and in UPulseQuestUtils: Is Local Quest Manager, Is Authority Quest Manager.
UPulseQuestLibrary
| Node | Description |
|---|---|
Find Quest Manager(Actor) | Manager on the actor, its controller, player state or pawn (also for actors owned by them, and for the player of the instigator of projectiles) |
Find Shared Quest Hosts(Actor) | Shared hosts the player belongs to |
Start Quest For Actor | Finds the manager and starts a quest (authority) |
Send Quest State Tree Event | StateTree event to a running quest (authority) |
Complete Objectives Of Class | Completes running objectives of a class, optionally of one quest (authority) |
Has Story Flag / Set Story Flag | Story flags of a manager |
Messages
Every quest runtime also broadcasts on the PulseFoundation message bus (on the authority and the owning client), so other systems (notifications, statistics, sounds) react without a reference to the manager:
| Channel | Payload |
|---|---|
Pulse.Message.Quest.Started | FPulseQuestMessage (quest manager, quest tag, quest data, bLoadedFromSaveGame, RunId) |
Pulse.Message.Quest.Finished | FPulseQuestMessage with Result (Success, Failure, Stopped) |
Pulse.Message.Quest.ObjectiveFinished | FPulseQuestObjectiveMessage (quest manager, quest tag, objective, bSucceeded, Handle, RunId, Status, formatted DisplayText) |
The ids and the text let receivers work without the quest data or objective object.
The context of the messages names the player of a player’s quest manager as Player (none for shared quest hosts), the quest as Source, its tag in Tags and an Amount of 1, so message triggers count finished quests (“finish 5 quests”) and filter them with conditions. Started of a quest restored from a save game carries CatchUp = Load; on a client, Started of a quest that already ran when the client joined carries CatchUp = Replication, so toasts and counters leave both out. The channels are registered with the message bus, so the channel pickers and trigger checks know their payload.
Debugging
- Tools > Debug > Pulse Debugger > Live and the gameplay debugger category Pulse show each quest manager: net role, avatars, available quests, active quests with their objectives and progress.
- Quest starts, finishes and finished objectives are events on the Timeline page (source
Quest), in order with the events of the other Pulse plugins (dialogs, messages).
Data Validation
Quest managers, shared hosts, quests, quest sets, objectives and quest StateTrees are validated in the editor: missing quest sets or data classes, quests with the wrong StateTree schema, duplicate quest tags (across all quest assets and inside a set), quests in no quest set (setting), quest set loops, objectives without save id (setting) and duplicate objective save ids in a quest StateTree.
Subclassing
UPulseQuestManager and APulseSharedQuestHost are Blueprintable. In C++ override the Handle... hooks of the interface (HandleQuestStarted, HandleQuestFinished, HandleObjectiveStarted, HandleObjectiveFinished, HandleObjectiveChanged, HandleQuestManagerReset, HandleQuestManagerSaved, HandleQuestManagerLoaded) and CreateQuestInstance for a custom UPulseQuestInstance.