/**
* @file storyGraph.js
* Galatea Story & Dialogue Graph System (STORY-01).
* Provides StoryGraph (dialogue nodes with speaker, text, condition-checked choices,
* fact-mutating consequences, transitions) and QuestGraph (stages/objectives,
* fact-driven conditions, deduplicated one-time rewards, state machine,
* diagnostics, and snapshot/restore).
*/
import { WorldFacts } from "../core/worldFacts.js";
/**
* Evaluates a single condition against WorldFacts.
* @param {Object|Function} condition
* @param {WorldFacts} facts
* @param {Object} [context]
* @returns {boolean}
*/
function evaluateSingleCondition(condition, facts, context = null) {
if (!condition) return true;
if (typeof condition === "function") {
return Boolean(condition(facts, context));
}
if (typeof condition !== "object") {
return Boolean(condition);
}
if (condition.not) {
return !evaluateSingleCondition(condition.not, facts, context);
}
if (Array.isArray(condition.allOf)) {
return condition.allOf.every(c => evaluateSingleCondition(c, facts, context));
}
if (Array.isArray(condition.anyOf)) {
return condition.anyOf.some(c => evaluateSingleCondition(c, facts, context));
}
// Explicit fact / key condition
if ("fact" in condition || "key" in condition) {
const factKey = condition.fact || condition.key;
const actualValue = facts ? facts.get(factKey) : undefined;
const op = condition.op || condition.operator || "==";
const expectedValue = condition.value;
// Numeric range check (min/max)
if ("min" in condition || "max" in condition) {
if (typeof actualValue !== "number") return false;
if ("min" in condition && actualValue < condition.min) return false;
if ("max" in condition && actualValue > condition.max) return false;
return true;
}
switch (op) {
case "==":
case "===":
case "eq":
case "equals":
return actualValue === expectedValue;
case "!=":
case "!==":
case "neq":
case "not_equals":
return actualValue !== expectedValue;
case ">":
case "gt":
return typeof actualValue === "number" && actualValue > expectedValue;
case ">=":
case "gte":
return typeof actualValue === "number" && actualValue >= expectedValue;
case "<":
case "lt":
return typeof actualValue === "number" && actualValue < expectedValue;
case "<=":
case "lte":
return typeof actualValue === "number" && actualValue <= expectedValue;
case "includes":
case "contains":
if (Array.isArray(actualValue)) return actualValue.includes(expectedValue);
if (typeof actualValue === "string") return actualValue.includes(String(expectedValue));
return false;
case "in":
if (Array.isArray(expectedValue)) return expectedValue.includes(actualValue);
if (typeof expectedValue === "string") return expectedValue.includes(String(actualValue));
return false;
case "has":
case "exists":
return facts ? facts.has(factKey) : false;
case "lacks":
case "not_exists":
return facts ? !facts.has(factKey) : true;
default:
return actualValue === expectedValue;
}
}
// Object map format: { 'player.hasKey': true, 'player.level': 5 }
if (facts) {
for (const [k, v] of Object.entries(condition)) {
if (k === "op" || k === "value" || k === "operator") continue;
const actual = facts.get(k);
if (typeof v === "object" && v !== null) {
if ("min" in v && (typeof actual !== "number" || actual < v.min)) return false;
if ("max" in v && (typeof actual !== "number" || actual > v.max)) return false;
if ("op" in v) {
if (!evaluateSingleCondition({ fact: k, ...v }, facts, context)) return false;
}
} else if (actual !== v) {
return false;
}
}
return true;
}
return true;
}
/**
* Evaluates conditions against WorldFacts. Supports single condition or array (AND).
* @param {Object|Array|Function} conditions
* @param {WorldFacts} facts
* @param {Object} [context]
* @returns {boolean}
*/
export function evaluateConditions(conditions, facts, context = null) {
if (!conditions) return true;
if (Array.isArray(conditions)) {
if (conditions.length === 0) return true;
return conditions.every(c => evaluateSingleCondition(c, facts, context));
}
return evaluateSingleCondition(conditions, facts, context);
}
/**
* Applies consequences/effects to WorldFacts.
* @param {Object|Array|Function} effects
* @param {WorldFacts} facts
*/
export function applyEffects(effects, facts) {
if (!effects || !facts) return;
if (typeof effects === "function") {
effects(facts);
return;
}
const effectList = Array.isArray(effects) ? effects : [effects];
for (const eff of effectList) {
if (!eff) continue;
if (typeof eff === "function") {
eff(facts);
continue;
}
if (eff.set && typeof eff.set === "object") {
for (const [k, v] of Object.entries(eff.set)) {
facts.set(k, v);
}
continue;
}
const key = eff.fact || eff.key;
if (!key) continue;
const op = eff.op || eff.operation || "set";
if (op === "set") {
facts.set(key, eff.value);
} else if (op === "add" || op === "+" || op === "increment") {
const current = facts.get(key, 0);
const delta = typeof eff.value === "number" ? eff.value : (typeof eff.amount === "number" ? eff.amount : 1);
facts.set(key, (typeof current === "number" ? current : 0) + delta);
} else if (op === "subtract" || op === "-" || op === "decrement") {
const current = facts.get(key, 0);
const delta = typeof eff.value === "number" ? eff.value : (typeof eff.amount === "number" ? eff.amount : 1);
facts.set(key, (typeof current === "number" ? current : 0) - delta);
} else if (op === "toggle") {
facts.set(key, !facts.get(key, false));
} else if (op === "delete" || op === "remove") {
facts.delete(key);
} else {
facts.set(key, eff.value);
}
}
}
/**
* Detects logical contradictions in a set of conditions.
* @param {Array|Object} conditions
* @returns {Array<{ fact: string, message: string }>}
*/
export function detectContradictions(conditions) {
const list = Array.isArray(conditions)
? conditions
: (conditions && typeof conditions === "object" ? [conditions] : []);
const contradictions = [];
// Flatten any allOf if present
const flattened = [];
for (const item of list) {
if (!item || typeof item !== "object") continue;
if (item.contradictory === true || item.contradiction === true) {
contradictions.push({
fact: item.fact || item.key || "unknown",
message: "Explicit contradictory condition flag"
});
continue;
}
if (Array.isArray(item.allOf)) {
flattened.push(...item.allOf);
} else if ("fact" in item || "key" in item) {
flattened.push(item);
} else {
// Check direct map { key: val }
for (const [k, v] of Object.entries(item)) {
if (k === "op" || k === "value") continue;
if (typeof v === "object" && v !== null) {
flattened.push({ fact: k, ...v });
} else {
flattened.push({ fact: k, op: "==", value: v });
}
}
}
}
// Check individual condition self-contradictions (e.g. min > max)
for (const item of flattened) {
if (typeof item.min === "number" && typeof item.max === "number" && item.min > item.max) {
contradictions.push({
fact: item.fact || item.key || "unknown",
message: `Condition specifies min (${item.min}) greater than max (${item.max})`
});
}
}
// Group by fact key
const byFact = new Map();
for (const item of flattened) {
const fact = item.fact || item.key;
if (!fact) continue;
if (!byFact.has(fact)) byFact.set(fact, []);
byFact.get(fact).push(item);
}
for (const [fact, conds] of byFact.entries()) {
let exactValue = undefined;
let hasExact = false;
let notValues = new Set();
let lowerBound = -Infinity;
let lowerStrict = false;
let upperBound = Infinity;
let upperStrict = false;
for (const c of conds) {
const op = c.op || c.operator || "==";
const val = c.value;
if (op === "==" || op === "===" || op === "eq" || op === "equals") {
if (hasExact && exactValue !== val) {
contradictions.push({
fact,
message: `Fact '${fact}' cannot simultaneously equal '${exactValue}' and '${val}'`
});
}
exactValue = val;
hasExact = true;
} else if (op === "!=" || op === "!==" || op === "neq" || op === "not_equals") {
notValues.add(val);
} else if (op === ">" || op === "gt") {
if (typeof val === "number") {
if (val > lowerBound || (val === lowerBound && !lowerStrict)) {
lowerBound = val;
lowerStrict = true;
}
}
} else if (op === ">=" || op === "gte" || "min" in c) {
const bound = typeof val === "number" ? val : c.min;
if (typeof bound === "number" && bound > lowerBound) {
lowerBound = bound;
lowerStrict = false;
}
} else if (op === "<" || op === "lt") {
if (typeof val === "number") {
if (val < upperBound || (val === upperBound && !upperStrict)) {
upperBound = val;
upperStrict = true;
}
}
} else if (op === "<=" || op === "lte" || "max" in c) {
const bound = typeof val === "number" ? val : c.max;
if (typeof bound === "number" && bound < upperBound) {
upperBound = bound;
upperStrict = false;
}
}
}
// Check if exactValue conflicts with notValues
if (hasExact && notValues.has(exactValue)) {
contradictions.push({
fact,
message: `Fact '${fact}' required to equal '${exactValue}' but also required not to equal '${exactValue}'`
});
}
// Check numeric range contradiction: lowerBound vs upperBound
if (lowerBound > upperBound) {
contradictions.push({
fact,
message: `Fact '${fact}' has lower bound (${lowerBound}) exceeding upper bound (${upperBound})`
});
} else if (lowerBound === upperBound && (lowerStrict || upperStrict)) {
contradictions.push({
fact,
message: `Fact '${fact}' requires value strictly between ${lowerBound} and ${upperBound}`
});
}
// Check exactValue against bounds
if (hasExact && typeof exactValue === "number") {
if (lowerStrict ? exactValue <= lowerBound : exactValue < lowerBound) {
contradictions.push({
fact,
message: `Fact '${fact}' exact value (${exactValue}) violates lower bound (${lowerBound})`
});
}
if (upperStrict ? exactValue >= upperBound : exactValue > upperBound) {
contradictions.push({
fact,
message: `Fact '${fact}' exact value (${exactValue}) violates upper bound (${upperBound})`
});
}
}
}
return contradictions;
}
/**
* StoryGraph represents an interactive dialogue flow with branching choices,
* condition checks against WorldFacts, fact consequences, and diagnostics.
*/
export class StoryGraph {
#nodes = new Map();
#visitedNodes = new Set();
#history = [];
#currentNodeId = null;
#state = "unstarted";
/**
* @param {Object} [definition]
*/
constructor(definition = {}) {
this.id = definition.id || `story_graph_${Math.random().toString(36).slice(2, 9)}`;
this.name = definition.name || this.id;
this.initialNodeId = definition.initialNodeId || definition.startNodeId || definition.entryNodeId || null;
this.facts = definition.facts instanceof WorldFacts ? definition.facts : null;
if (Array.isArray(definition.nodes)) {
for (const node of definition.nodes) {
this.addNode(node);
}
} else if (definition.nodes && typeof definition.nodes === "object") {
for (const [id, node] of Object.entries(definition.nodes)) {
this.addNode({ id, ...node });
}
}
}
/**
* Current dialogue node ID.
* @returns {string|null}
*/
get currentNodeId() {
return this.#currentNodeId;
}
/**
* Current story state ('unstarted', 'active', 'completed').
* @returns {string}
*/
get state() {
return this.#state;
}
/**
* Sequence of visited node IDs in order.
* @returns {string[]}
*/
get history() {
return [...this.#history];
}
/**
* Set of unique visited node IDs.
* @returns {Set}
*/
get visitedNodes() {
return new Set(this.#visitedNodes);
}
/**
* Adds a dialogue node to the graph.
* @param {Object} node
* @returns {this}
*/
addNode(node) {
if (!node || typeof node !== "object") {
throw new TypeError("Story node must be an object");
}
if (!node.id || typeof node.id !== "string") {
throw new TypeError("Story node must have a non-empty string 'id'");
}
const normalizedNode = {
id: node.id,
speaker: node.speaker !== undefined ? node.speaker : "",
text: node.text || "",
choices: Array.isArray(node.choices) ? node.choices.map((c, i) => ({
id: c.id || `choice_${i}`,
text: c.text || "",
targetNodeId: c.targetNodeId || c.next || c.target || null,
condition: c.condition || c.conditions || c.when || null,
consequence: c.consequence || c.effects || c.action || null,
metadata: c.metadata || {}
})) : [],
next: node.next || node.targetNodeId || null,
conditions: node.conditions || node.condition || null,
effects: node.effects || node.consequence || node.onEnter || null,
metadata: node.metadata || {}
};
this.#nodes.set(normalizedNode.id, normalizedNode);
if (!this.initialNodeId) {
this.initialNodeId = normalizedNode.id;
}
return this;
}
/**
* Gets a node by ID.
* @param {string} nodeId
* @returns {Object|null}
*/
getNode(nodeId) {
const node = this.#nodes.get(nodeId);
return node ? { ...node, choices: node.choices.map(c => ({ ...c })) } : null;
}
/**
* Checks if a node ID exists in the graph.
* @param {string} nodeId
* @returns {boolean}
*/
hasNode(nodeId) {
return this.#nodes.has(nodeId);
}
/**
* Binds or updates the authoritative WorldFacts instance.
* @param {WorldFacts} facts
* @returns {this}
*/
setFacts(facts) {
this.facts = facts instanceof WorldFacts ? facts : null;
return this;
}
/**
* Starts the dialogue sequence at the given node or initialNodeId.
* @param {string} [nodeId]
* @param {WorldFacts} [facts]
* @returns {Object} Current node
*/
start(nodeId = null, facts = null) {
if (facts instanceof WorldFacts) {
this.setFacts(facts);
}
const targetId = nodeId || this.initialNodeId;
if (!targetId || !this.#nodes.has(targetId)) {
throw new Error(`Cannot start story graph: node '${targetId}' not found`);
}
this.#state = "active";
this.#currentNodeId = targetId;
this.#history = [targetId];
this.#visitedNodes = new Set([targetId]);
const node = this.#nodes.get(targetId);
if (node.effects && this.facts) {
applyEffects(node.effects, this.facts);
}
return this.getCurrentNode();
}
/**
* Returns the current node enriched with available choices.
* @returns {Object|null}
*/
getCurrentNode() {
if (!this.#currentNodeId || this.#state !== "active") return null;
const node = this.getNode(this.#currentNodeId);
if (!node) return null;
return {
...node,
availableChoices: this.getAvailableChoices(this.#currentNodeId)
};
}
/**
* Returns all choices for a node with their availability evaluated against facts.
* @param {string} [nodeId]
* @returns {Array<Object>}
*/
getChoices(nodeId = null) {
const id = nodeId || this.#currentNodeId;
if (!id || !this.#nodes.has(id)) return [];
const node = this.#nodes.get(id);
return node.choices.map(choice => {
const isAvailable = choice.condition
? evaluateConditions(choice.condition, this.facts)
: true;
return {
...choice,
available: isAvailable
};
});
}
/**
* Returns only the choices currently available according to WorldFacts.
* @param {string} [nodeId]
* @returns {Array<Object>}
*/
getAvailableChoices(nodeId = null) {
return this.getChoices(nodeId).filter(c => c.available);
}
/**
* Selects a dialogue choice by index or ID, applies consequences, and transitions.
* @param {number|string} choiceIndexOrId
* @returns {Object|null} The new current node, or null if dialogue ended
*/
choose(choiceIndexOrId) {
if (this.#state !== "active" || !this.#currentNodeId) {
throw new Error("Cannot choose: dialogue is not active");
}
const choices = this.getChoices(this.#currentNodeId);
let selectedChoice = null;
if (typeof choiceIndexOrId === "number") {
selectedChoice = choices[choiceIndexOrId];
} else if (typeof choiceIndexOrId === "string") {
selectedChoice = choices.find(c => c.id === choiceIndexOrId);
}
if (!selectedChoice) {
throw new Error(`Choice '${choiceIndexOrId}' not found on current node '${this.#currentNodeId}'`);
}
if (!selectedChoice.available) {
throw new Error(`Choice '${selectedChoice.text || selectedChoice.id}' is locked: condition not satisfied`);
}
// Apply consequence effects
if (selectedChoice.consequence && this.facts) {
applyEffects(selectedChoice.consequence, this.facts);
}
const nextId = selectedChoice.targetNodeId;
if (!nextId || nextId === "end" || nextId === "exit") {
this.#state = "completed";
this.#currentNodeId = null;
return null;
}
if (!this.#nodes.has(nextId)) {
throw new Error(`Choice target node '${nextId}' does not exist in story graph`);
}
this.#currentNodeId = nextId;
this.#history.push(nextId);
this.#visitedNodes.add(nextId);
const nextNode = this.#nodes.get(nextId);
if (nextNode.effects && this.facts) {
applyEffects(nextNode.effects, this.facts);
}
return this.getCurrentNode();
}
/**
* Advances linear dialogue to the next node (when node has no choices but defines 'next').
* @returns {Object|null}
*/
advance() {
if (this.#state !== "active" || !this.#currentNodeId) {
throw new Error("Cannot advance: dialogue is not active");
}
const node = this.#nodes.get(this.#currentNodeId);
const nextId = node.next;
if (!nextId || nextId === "end" || nextId === "exit") {
this.#state = "completed";
this.#currentNodeId = null;
return null;
}
if (!this.#nodes.has(nextId)) {
throw new Error(`Next node '${nextId}' does not exist in story graph`);
}
this.#currentNodeId = nextId;
this.#history.push(nextId);
this.#visitedNodes.add(nextId);
const nextNode = this.#nodes.get(nextId);
if (nextNode.effects && this.facts) {
applyEffects(nextNode.effects, this.facts);
}
return this.getCurrentNode();
}
/**
* Checks if dialogue sequence is active.
* @returns {boolean}
*/
isActive() {
return this.#state === "active";
}
/**
* Checks if dialogue sequence has completed.
* @returns {boolean}
*/
isCompleted() {
return this.#state === "completed";
}
/**
* Resets dialogue to unstarted state.
*/
reset() {
this.#state = "unstarted";
this.#currentNodeId = null;
this.#history = [];
this.#visitedNodes.clear();
}
/**
* Serializes runtime dialogue state for save games.
* @returns {Object}
*/
snapshot() {
return {
id: this.id,
state: this.#state,
currentNodeId: this.#currentNodeId,
history: [...this.#history],
visitedNodes: Array.from(this.#visitedNodes)
};
}
/**
* Restores dialogue state from snapshot.
* @param {Object} snapshot
* @returns {this}
*/
restore(snapshot) {
if (!snapshot || typeof snapshot !== "object") {
throw new TypeError("StoryGraph snapshot must be an object");
}
this.#state = snapshot.state || "unstarted";
this.#currentNodeId = snapshot.currentNodeId || null;
this.#history = Array.isArray(snapshot.history) ? [...snapshot.history] : [];
this.#visitedNodes = new Set(Array.isArray(snapshot.visitedNodes) ? snapshot.visitedNodes : []);
return this;
}
/**
* Runs comprehensive diagnostics on the story graph:
* detects missing node references, absent speakers, and contradictory conditions.
* @returns {{ valid: boolean, errors: Array<Object>, warnings: Array<Object> }}
*/
diagnostics() {
return StoryGraph.validate({
initialNodeId: this.initialNodeId,
nodes: Array.from(this.#nodes.values())
});
}
/**
* Validates a story graph definition structure.
* @param {Object} storyDef
* @returns {{ valid: boolean, errors: Array<Object>, warnings: Array<Object> }}
*/
static validate(storyDef) {
const errors = [];
const warnings = [];
if (!storyDef || typeof storyDef !== "object") {
errors.push({
code: "INVALID_DEFINITION",
message: "Story definition must be a non-null object"
});
return { valid: false, errors, warnings };
}
const nodes = Array.isArray(storyDef.nodes)
? storyDef.nodes
: (storyDef.nodes && typeof storyDef.nodes === "object"
? Object.entries(storyDef.nodes).map(([id, n]) => ({ id, ...n }))
: []);
const nodeIds = new Set(nodes.map(n => n.id).filter(Boolean));
// 1. Initial node existence check
const initialId = storyDef.initialNodeId || storyDef.startNodeId || storyDef.entryNodeId;
if (initialId && !nodeIds.has(initialId)) {
errors.push({
code: "MISSING_NODE_REFERENCE",
message: `Initial node '${initialId}' does not exist in graph`,
nodeId: initialId
});
}
// 2. Validate each node
for (const node of nodes) {
const nodeId = node.id || "unnamed";
// Check absent speaker
if (node.speaker === undefined || node.speaker === null || (typeof node.speaker === "string" && !node.speaker.trim())) {
errors.push({
code: "ABSENT_SPEAKER",
message: `Dialogue node '${nodeId}' has missing or empty speaker`,
nodeId
});
}
// Check linear 'next' transition reference
if (node.next && typeof node.next === "string" && node.next !== "end" && node.next !== "exit") {
if (!nodeIds.has(node.next)) {
errors.push({
code: "MISSING_NODE_REFERENCE",
message: `Node '${nodeId}' references non-existent node '${node.next}' in 'next'`,
nodeId,
targetNodeId: node.next
});
}
}
// Check node-level condition contradictions
if (node.conditions || node.condition) {
const conds = node.conditions || node.condition;
const nodeContradictions = detectContradictions(conds);
for (const c of nodeContradictions) {
errors.push({
code: "CONTRADICTORY_CONDITIONS",
message: `Node '${nodeId}' condition contradiction: ${c.message}`,
nodeId,
fact: c.fact
});
}
}
// Check choices
if (Array.isArray(node.choices)) {
for (let i = 0; i < node.choices.length; i++) {
const choice = node.choices[i];
const targetId = choice.targetNodeId || choice.next || choice.target;
// Missing choice target reference
if (targetId && typeof targetId === "string" && targetId !== "end" && targetId !== "exit") {
if (!nodeIds.has(targetId)) {
errors.push({
code: "MISSING_NODE_REFERENCE",
message: `Choice [${i}] in node '${nodeId}' references non-existent node '${targetId}'`,
nodeId,
targetNodeId: targetId
});
}
}
// Contradictory conditions on choice
if (choice.condition || choice.conditions) {
const conds = choice.condition || choice.conditions;
const choiceContradictions = detectContradictions(conds);
for (const c of choiceContradictions) {
errors.push({
code: "CONTRADICTORY_CONDITIONS",
message: `Choice [${i}] in node '${nodeId}' has contradictory conditions: ${c.message}`,
nodeId,
choiceIndex: i,
fact: c.fact
});
}
}
}
}
}
return {
valid: errors.length === 0,
errors,
warnings
};
}
}
/**
* 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.
*/
export class QuestGraph {
#stages = new Map();
#claimedRewards = new Set();
#history = [];
#currentStageId = null;
#state = "unstarted";
/**
* @param {Object} [definition]
*/
constructor(definition = {}) {
this.id = definition.id || `quest_${Math.random().toString(36).slice(2, 9)}`;
this.title = definition.title || definition.name || this.id;
this.description = definition.description || "";
this.initialStageId = definition.initialStageId || definition.startStageId || null;
this.rewards = Array.isArray(definition.rewards) ? definition.rewards.map(r => ({ ...r })) : [];
this.facts = definition.facts instanceof WorldFacts ? definition.facts : null;
this.bus = definition.bus || null;
const stageList = Array.isArray(definition.stages)
? definition.stages
: (Array.isArray(definition.objectives)
? definition.objectives
: (definition.stages && typeof definition.stages === "object"
? Object.entries(definition.stages).map(([id, s]) => ({ id, ...s }))
: []));
for (const stage of stageList) {
this.addStage(stage);
}
}
/**
* Current quest state ('unstarted', 'active', 'completed', 'failed').
* @returns {string}
*/
get state() {
return this.#state;
}
/**
* Currently active stage ID.
* @returns {string|null}
*/
get currentStageId() {
return this.#currentStageId;
}
/**
* History of quest state transitions.
* @returns {Array<Object>}
*/
get history() {
return [...this.#history];
}
/**
* Adds a stage or objective to the quest graph.
* @param {Object} stage
* @returns {this}
*/
addStage(stage) {
if (!stage || typeof stage !== "object") {
throw new TypeError("Quest stage must be an object");
}
if (!stage.id || typeof stage.id !== "string") {
throw new TypeError("Quest stage must have a non-empty string 'id'");
}
const normalizedStage = {
id: stage.id,
title: stage.title || stage.name || stage.id,
description: stage.description || "",
state: stage.state || "unstarted",
conditions: stage.conditions || stage.condition || null,
failureConditions: stage.failureConditions || null,
event: stage.event || stage.events || null,
next: stage.next || stage.nextStageId || null,
rewards: Array.isArray(stage.rewards) ? stage.rewards.map((r, i) => ({
id: r.id || `${this.id}_${stage.id}_reward_${i}`,
...r
})) : [],
speaker: stage.speaker !== undefined ? stage.speaker : null,
metadata: stage.metadata || {}
};
this.#stages.set(normalizedStage.id, normalizedStage);
if (!this.initialStageId) {
this.initialStageId = normalizedStage.id;
}
return this;
}
/**
* Gets a stage by ID.
* @param {string} stageId
* @returns {Object|null}
*/
getStage(stageId) {
const stage = this.#stages.get(stageId);
return stage ? { ...stage, rewards: stage.rewards.map(r => ({ ...r })) } : null;
}
/**
* Gets the currently active stage object.
* @returns {Object|null}
*/
getActiveStage() {
if (!this.#currentStageId) return null;
return this.getStage(this.#currentStageId);
}
/**
* Checks if a stage exists.
* @param {string} stageId
* @returns {boolean}
*/
hasStage(stageId) {
return this.#stages.has(stageId);
}
/**
* Sets or updates the authoritative WorldFacts instance.
* @param {WorldFacts} facts
* @returns {this}
*/
setFacts(facts) {
this.facts = facts instanceof WorldFacts ? facts : null;
return this;
}
/**
* Starts the quest, activating the initial stage.
* @returns {this}
*/
start() {
if (this.#state === "active") return this;
const startId = this.initialStageId;
if (!startId || !this.#stages.has(startId)) {
throw new Error(`Cannot start quest '${this.id}': initial stage '${startId}' not found`);
}
this.#state = "active";
this.#currentStageId = startId;
const initialStage = this.#stages.get(startId);
initialStage.state = "active";
this.#history.push({
type: "quest_started",
questId: this.id,
stageId: startId,
timestamp: Date.now()
});
if (this.bus && typeof this.bus.emit === "function") {
this.bus.emit("quest:started", { questId: this.id, stageId: startId });
}
if (this.facts) {
this.evaluate(this.facts);
}
return this;
}
/**
* Marks the quest as completed, awarding one-time quest rewards with deduplication.
* @returns {this}
*/
complete() {
if (this.#state === "completed") return this;
this.#state = "completed";
if (this.#currentStageId && this.#stages.has(this.#currentStageId)) {
this.#stages.get(this.#currentStageId).state = "completed";
}
this.#currentStageId = null;
this.#history.push({
type: "quest_completed",
questId: this.id,
timestamp: Date.now()
});
// Award one-time quest completion rewards
for (let i = 0; i < this.rewards.length; i++) {
const reward = this.rewards[i];
const rewardObj = typeof reward === "object" && reward !== null
? { id: reward.id || `${this.id}_completion_reward_${i}`, ...reward }
: { id: `${this.id}_completion_reward_${i}`, value: reward };
this.claimReward(rewardObj, this.facts);
}
if (this.bus && typeof this.bus.emit === "function") {
this.bus.emit("quest:completed", { questId: this.id });
}
return this;
}
/**
* Marks the quest as failed.
* @param {string} [reason]
* @returns {this}
*/
fail(reason = "") {
if (this.#state === "failed") return this;
this.#state = "failed";
if (this.#currentStageId && this.#stages.has(this.#currentStageId)) {
this.#stages.get(this.#currentStageId).state = "failed";
}
this.#history.push({
type: "quest_failed",
questId: this.id,
reason,
timestamp: Date.now()
});
if (this.bus && typeof this.bus.emit === "function") {
this.bus.emit("quest:failed", { questId: this.id, reason });
}
return this;
}
/**
* Completes a specific stage, granting its deduplicated one-time rewards,
* and advances to the next stage or completes the quest.
* @param {string} stageId
* @returns {this}
*/
completeStage(stageId) {
if (!this.#stages.has(stageId)) return this;
const stage = this.#stages.get(stageId);
stage.state = "completed";
this.#history.push({
type: "stage_completed",
questId: this.id,
stageId,
timestamp: Date.now()
});
// Grant stage rewards with deduplication
if (Array.isArray(stage.rewards)) {
for (const reward of stage.rewards) {
this.claimReward(reward, this.facts);
}
}
if (this.bus && typeof this.bus.emit === "function") {
this.bus.emit("quest:stage_completed", { questId: this.id, stageId });
}
const nextId = stage.next;
if (nextId && this.#stages.has(nextId)) {
this.#currentStageId = nextId;
const nextStage = this.#stages.get(nextId);
nextStage.state = "active";
this.#history.push({
type: "stage_started",
questId: this.id,
stageId: nextId,
timestamp: Date.now()
});
} else {
// Final stage completed: complete the quest
this.complete();
}
return this;
}
/**
* Claims a one-time reward with deduplication guard.
* Prevents rewards from ever being awarded twice.
* @param {Object|string} reward
* @param {WorldFacts} [facts]
* @returns {Object} Result object with awarded flag and rewardId
*/
claimReward(reward, facts = null) {
const factStore = facts || this.facts;
let rewardId = null;
if (typeof reward === "string") {
rewardId = reward;
} else if (reward && typeof reward === "object") {
rewardId = reward.id || `${this.id}_reward_${Math.random().toString(36).slice(2, 9)}`;
}
if (!rewardId) {
return { awarded: false, rewardId: "", reason: "INVALID_REWARD" };
}
// Deduplication guard
if (this.#claimedRewards.has(rewardId)) {
return { awarded: false, rewardId, reason: "ALREADY_CLAIMED" };
}
this.#claimedRewards.add(rewardId);
// Apply reward effects to WorldFacts if present
if (factStore && typeof reward === "object" && reward !== null) {
if (reward.fact || reward.key) {
const key = reward.fact || reward.key;
const op = reward.op || (reward.type === "gold" || reward.type === "xp" ? "add" : "set");
if (op === "add" || op === "+" || op === "increment") {
const cur = factStore.get(key, 0);
const amount = typeof reward.value === "number" ? reward.value : (typeof reward.amount === "number" ? reward.amount : 0);
factStore.set(key, (typeof cur === "number" ? cur : 0) + amount);
} else {
factStore.set(key, reward.value !== undefined ? reward.value : (reward.amount !== undefined ? reward.amount : true));
}
} else if (reward.effects) {
applyEffects(reward.effects, factStore);
}
}
if (this.bus && typeof this.bus.emit === "function") {
this.bus.emit("reward:granted", { questId: this.id, rewardId, reward });
}
return { awarded: true, rewardId };
}
/**
* Checks if a reward ID has already been claimed.
* @param {string} rewardId
* @returns {boolean}
*/
hasClaimedReward(rewardId) {
return this.#claimedRewards.has(rewardId);
}
/**
* Returns an array of all claimed reward IDs.
* @returns {string[]}
*/
getClaimedRewards() {
return Array.from(this.#claimedRewards);
}
/**
* Evaluates current active stage conditions against WorldFacts and optional event.
* If conditions are met, advances stage or completes quest.
* @param {WorldFacts} [facts]
* @param {Object|string} [event]
* @returns {boolean} True if stage transitioned
*/
evaluate(facts = null, event = null) {
if (facts instanceof WorldFacts) {
this.setFacts(facts);
}
const factStore = this.facts;
if (this.#state !== "active" || !this.#currentStageId) {
return false;
}
const stage = this.#stages.get(this.#currentStageId);
if (!stage || stage.state !== "active") {
return false;
}
// 1. Check failure conditions
if (stage.failureConditions && evaluateConditions(stage.failureConditions, factStore, event)) {
this.fail("Stage failure condition met");
return true;
}
// 2. Check event match if stage specifies event requirement
let eventMatched = true;
if (stage.event) {
if (!event) {
eventMatched = false;
} else {
const eventName = typeof event === "string" ? event : (event.type || event.name);
const reqEvents = Array.isArray(stage.event) ? stage.event : [stage.event];
eventMatched = reqEvents.includes(eventName);
}
}
// 3. Check fact conditions
let conditionsMet = false;
if (stage.conditions) {
conditionsMet = evaluateConditions(stage.conditions, factStore, event);
} else if (!stage.event) {
// Unconditional stage
conditionsMet = true;
}
if (eventMatched && (conditionsMet || (!stage.conditions && stage.event))) {
this.completeStage(stage.id);
// Re-evaluate if chained stage conditions are already fulfilled
if (this.#state === "active" && this.#currentStageId) {
this.evaluate(factStore, event);
}
return true;
}
return false;
}
/**
* Binds WorldFacts and optional TypedEventBus to trigger fact/event-driven evaluation automatically.
* @param {WorldFacts} facts
* @param {Object} [bus]
* @returns {Function} Unbind callback
*/
bind(facts, bus = null) {
if (facts instanceof WorldFacts) {
this.setFacts(facts);
}
if (bus) {
this.bus = bus;
}
const unbinders = [];
// Bind facts onChange
if (this.facts && typeof this.facts.onChange === "function") {
const unbindFacts = this.facts.onChange("*", () => {
if (this.#state === "active") {
this.evaluate(this.facts);
}
});
unbinders.push(unbindFacts);
}
// Bind bus events for stages requiring events
if (this.bus && typeof this.bus.on === "function") {
const registeredEvents = new Set();
for (const stage of this.#stages.values()) {
if (stage.event) {
const evts = Array.isArray(stage.event) ? stage.event : [stage.event];
for (const e of evts) registeredEvents.add(e);
}
}
for (const evtName of registeredEvents) {
const unbindEvt = this.bus.on(evtName, (eventData) => {
if (this.#state === "active") {
this.evaluate(this.facts, { type: evtName, data: eventData });
}
});
unbinders.push(unbindEvt);
}
}
return () => {
for (const u of unbinders) {
if (typeof u === "function") u();
}
};
}
/**
* Checks if quest is currently active.
* @returns {boolean}
*/
isActive() {
return this.#state === "active";
}
/**
* Checks if quest has completed.
* @returns {boolean}
*/
isCompleted() {
return this.#state === "completed";
}
/**
* Checks if quest has failed.
* @returns {boolean}
*/
isFailed() {
return this.#state === "failed";
}
/**
* Resets quest to unstarted state and clears active stage.
*/
reset() {
this.#state = "unstarted";
this.#currentStageId = null;
for (const stage of this.#stages.values()) {
stage.state = "unstarted";
}
this.#history = [];
this.#claimedRewards.clear();
}
/**
* Serializes quest state, active stage, and claimed rewards for save games.
* @returns {Object}
*/
snapshot() {
return {
id: this.id,
state: this.#state,
currentStageId: this.#currentStageId,
stages: Array.from(this.#stages.entries()).map(([id, stage]) => ({
id,
state: stage.state
})),
claimedRewards: Array.from(this.#claimedRewards),
history: [...this.#history]
};
}
/**
* Restores quest state, active stage, and claimed reward deduplication guards from snapshot.
* @param {Object} snapshot
* @returns {this}
*/
restore(snapshot) {
if (!snapshot || typeof snapshot !== "object") {
throw new TypeError("QuestGraph snapshot must be an object");
}
this.#state = snapshot.state || "unstarted";
this.#currentStageId = snapshot.currentStageId || null;
if (Array.isArray(snapshot.stages)) {
for (const s of snapshot.stages) {
if (s && s.id && this.#stages.has(s.id)) {
this.#stages.get(s.id).state = s.state || "unstarted";
}
}
}
this.#claimedRewards = new Set(Array.isArray(snapshot.claimedRewards) ? snapshot.claimedRewards : []);
this.#history = Array.isArray(snapshot.history) ? [...snapshot.history] : [];
return this;
}
/**
* Runs diagnostics on the quest graph:
* detects missing node references, absent speakers (if dialogue is attached),
* contradictory conditions, and unsupported cycles.
* @returns {{ valid: boolean, errors: Array<Object>, warnings: Array<Object> }}
*/
diagnostics() {
return QuestGraph.validate({
initialStageId: this.initialStageId,
stages: Array.from(this.#stages.values())
});
}
/**
* Validates a quest graph definition.
* @param {Object} questDef
* @returns {{ valid: boolean, errors: Array<Object>, warnings: Array<Object> }}
*/
static validate(questDef) {
const errors = [];
const warnings = [];
if (!questDef || typeof questDef !== "object") {
errors.push({
code: "INVALID_DEFINITION",
message: "Quest definition must be a non-null object"
});
return { valid: false, errors, warnings };
}
const stages = Array.isArray(questDef.stages)
? questDef.stages
: (Array.isArray(questDef.objectives)
? questDef.objectives
: (questDef.stages && typeof questDef.stages === "object"
? Object.entries(questDef.stages).map(([id, s]) => ({ id, ...s }))
: []));
const stageMap = new Map();
for (const s of stages) {
if (s && s.id) stageMap.set(s.id, s);
}
// 1. Initial stage check
const initialId = questDef.initialStageId || questDef.startStageId;
if (initialId && !stageMap.has(initialId)) {
errors.push({
code: "MISSING_STAGE_REFERENCE",
message: `Initial stage '${initialId}' does not exist in quest graph`,
stageId: initialId
});
}
// 2. Validate stage references, conditions, and absent speakers
for (const stage of stages) {
const stageId = stage.id || "unnamed";
// Check next stage reference
if (stage.next && typeof stage.next === "string" && stage.next !== "end" && stage.next !== "complete") {
if (!stageMap.has(stage.next)) {
errors.push({
code: "MISSING_STAGE_REFERENCE",
message: `Stage '${stageId}' references non-existent stage '${stage.next}' in 'next'`,
stageId,
targetStageId: stage.next
});
}
} else if (Array.isArray(stage.next)) {
for (const nextId of stage.next) {
if (nextId && typeof nextId === "string" && nextId !== "end" && nextId !== "complete") {
if (!stageMap.has(nextId)) {
errors.push({
code: "MISSING_STAGE_REFERENCE",
message: `Stage '${stageId}' references non-existent stage '${nextId}' in 'next'`,
stageId,
targetStageId: nextId
});
}
}
}
}
// Check contradictory conditions on stage
if (stage.conditions || stage.condition) {
const conds = stage.conditions || stage.condition;
const contradictions = detectContradictions(conds);
for (const c of contradictions) {
errors.push({
code: "CONTRADICTORY_CONDITIONS",
message: `Stage '${stageId}' has contradictory conditions: ${c.message}`,
stageId,
fact: c.fact
});
}
}
// Check absent speaker if speaker property is explicitly provided but empty/blank
if (stage.speaker !== undefined && stage.speaker !== null) {
if (typeof stage.speaker !== "string" || !stage.speaker.trim()) {
errors.push({
code: "ABSENT_SPEAKER",
message: `Quest stage '${stageId}' has empty or invalid speaker string`,
stageId
});
}
}
}
// 3. Detect unsupported cycles in quest graphs using 3-color DFS
const visited = new Set();
const visiting = new Map();
const currentPath = [];
const detectedCycles = new Set();
function dfs(currentId) {
visiting.set(currentId, currentPath.length);
currentPath.push(currentId);
const stage = stageMap.get(currentId);
const outgoing = [];
if (stage && stage.next) {
if (Array.isArray(stage.next)) {
outgoing.push(...stage.next);
} else if (typeof stage.next === "string") {
outgoing.push(stage.next);
}
}
for (const nextId of outgoing) {
if (!nextId || nextId === "end" || nextId === "complete") continue;
if (!stageMap.has(nextId)) continue;
if (visiting.has(nextId)) {
// Cycle detected
const startIdx = visiting.get(nextId);
const cycleNodes = currentPath.slice(startIdx).concat(nextId);
const cycleKey = cycleNodes.join(" -> ");
if (!detectedCycles.has(cycleKey)) {
detectedCycles.add(cycleKey);
errors.push({
code: "UNSUPPORTED_CYCLE",
message: `Unsupported cycle detected in quest graph: ${cycleKey}`,
stageId: currentId,
cycle: cycleNodes
});
}
} else if (!visited.has(nextId)) {
dfs(nextId);
}
}
visiting.delete(currentId);
currentPath.pop();
visited.add(currentId);
}
if (initialId && stageMap.has(initialId)) {
dfs(initialId);
}
for (const id of stageMap.keys()) {
if (!visited.has(id)) {
dfs(id);
}
}
return {
valid: errors.length === 0,
errors,
warnings
};
}
}