QuestGraph

QuestGraph represents a state machine of quest stages, objectives, conditions checked against WorldFacts, one-time rewards with deduplication guards, cycle diagnostics, and snapshot/restore for persistence.

Constructor

new QuestGraph(definitionopt)

Parameters:
NameTypeAttributesDescription
definitionObject<optional>

Classes

QuestGraph

Members

currentStageId

Currently active stage ID.

history

History of quest state transitions.

state

Current quest state ('unstarted', 'active', 'completed', 'failed').

Methods

(static) validate(questDef) → {Object}

Validates a quest graph definition.

Parameters:
NameTypeDescription
questDefObject
Returns:
Type: 
Object

addStage(stage) → {this}

Adds a stage or objective to the quest graph.

Parameters:
NameTypeDescription
stageObject
Returns:
Type: 
this

bind(facts, busopt) → {function}

Binds WorldFacts and optional TypedEventBus to trigger fact/event-driven evaluation automatically.

Parameters:
NameTypeAttributesDefaultDescription
factsWorldFacts
busObject<optional>
null
Returns:

Unbind callback

Type: 
function

claimReward(reward, factsopt) → {Object}

Claims a one-time reward with deduplication guard. Prevents rewards from ever being awarded twice.

Parameters:
NameTypeAttributesDefaultDescription
rewardObject | string
factsWorldFacts<optional>
null
Returns:

Result object with awarded flag and rewardId

Type: 
Object

complete() → {this}

Marks the quest as completed, awarding one-time quest rewards with deduplication.

Returns:
Type: 
this

completeStage(stageId) → {this}

Completes a specific stage, granting its deduplicated one-time rewards, and advances to the next stage or completes the quest.

Parameters:
NameTypeDescription
stageIdstring
Returns:
Type: 
this

diagnostics() → {Object}

Runs diagnostics on the quest graph: detects missing node references, absent speakers (if dialogue is attached), contradictory conditions, and unsupported cycles.

Returns:
Type: 
Object

evaluate(factsopt, eventopt) → {boolean}

Evaluates current active stage conditions against WorldFacts and optional event. If conditions are met, advances stage or completes quest.

Parameters:
NameTypeAttributesDefaultDescription
factsWorldFacts<optional>
null
eventObject | string<optional>
null
Returns:

True if stage transitioned

Type: 
boolean

fail(reasonopt) → {this}

Marks the quest as failed.

Parameters:
NameTypeAttributesDescription
reasonstring<optional>
Returns:
Type: 
this

getActiveStage() → {Object|null}

Gets the currently active stage object.

Returns:
Type: 
Object | null

getClaimedRewards() → {Array.<string>}

Returns an array of all claimed reward IDs.

Returns:
Type: 
Array.<string>

getStage(stageId) → {Object|null}

Gets a stage by ID.

Parameters:
NameTypeDescription
stageIdstring
Returns:
Type: 
Object | null

hasClaimedReward(rewardId) → {boolean}

Checks if a reward ID has already been claimed.

Parameters:
NameTypeDescription
rewardIdstring
Returns:
Type: 
boolean

hasStage(stageId) → {boolean}

Checks if a stage exists.

Parameters:
NameTypeDescription
stageIdstring
Returns:
Type: 
boolean

isActive() → {boolean}

Checks if quest is currently active.

Returns:
Type: 
boolean

isCompleted() → {boolean}

Checks if quest has completed.

Returns:
Type: 
boolean

isFailed() → {boolean}

Checks if quest has failed.

Returns:
Type: 
boolean

reset()

Resets quest to unstarted state and clears active stage.

restore(snapshot) → {this}

Restores quest state, active stage, and claimed reward deduplication guards from snapshot.

Parameters:
NameTypeDescription
snapshotObject
Returns:
Type: 
this

setFacts(facts) → {this}

Sets or updates the authoritative WorldFacts instance.

Parameters:
NameTypeDescription
factsWorldFacts
Returns:
Type: 
this

snapshot() → {Object}

Serializes quest state, active stage, and claimed rewards for save games.

Returns:
Type: 
Object

start() → {this}

Starts the quest, activating the initial stage.

Returns:
Type: 
this