Dialogue Forge

Every node is either a Character node or an Action node.

1. 1Drag a Character or Action node from the sidebar onto the canvas.
2. 2Click a node to open its inspector. Edit name, dialogue, and any attributes.
3. 3Connect nodes by hovering over a node's right handle until the cursor changes, then drag to another node's left handle.
4. 4For Branch nodes, double-click each outgoing edge label to type the player choice text.
5. 5Every conversation path must end at an End action node. The validation bar will flag open paths.

Variables define the gameplay state that your dialogue can read and react to. Declare them in the Variables panel and they become available across every node in the project.

Reference any variable directly inside a Character node's dialogue text using {variableName} syntax. Tokens are resolved at preview and runtime — the raw text is stored as-is in the JSON.

"Greetings, {playerName}. You have {inventory.length} items."
"Your current level is {stats.level} and your speed is {stats.speed}."
"The password is {secretCode}."

Attach conditions to edges to control which paths are available at runtime. An edge is only traversable when all its conditions evaluate to true against the current variable state.

The in-editor preview simulator evaluates variable interpolation and conditions against a live state snapshot. You can set variable overrides before running to test specific branches.

The export is a self-contained JSON object. Here's the top-level shape:

{
  "version": 1,
  "name": "My Dialogue",
  "exportedAt": "2025-01-01T00:00:00.000Z",
  "nodes": [ ...node objects... ],
  "edges": [ ...edge objects... ]
}

A character node:

{
  "id": "char-abc123",
  "type": "character",
  "position": { "x": 0, "y": 0 },        // editor layout only — ignore at runtime
  "data": {
    "name": "Guard",
    "dialogue": "Halt! Who goes there?",
    "emotion": "angry",                   // free-form string
    "portrait": "",                       // URL or asset path
    "attributeSchema": [
      { "id": "attr-hp", "name": "HP", "type": "number", "defaultValue": 100 }
    ],
    "attributes": { "attr-hp": 100 }      // current values, keyed by schema id
  }
}

An action node:

{
  "id": "act-def456",
  "type": "action",
  "position": { "x": 240, "y": 0 },
  "data": {
    "actionType": "branch",   // "branch" | "trigger" | "jump" | "end"
    "label": "Player Choice",
    "attributeSchema": [],
    "attributes": {}
  }
}

An edge:

{
  "id": "edge-ghi789",
  "source": "act-def456",      // id of the node this edge exits
  "target": "char-jkl012",     // id of the node this edge enters
  "type": "dialogue",
  "data": {
    "optionText": "I'm a traveler.",   // player-facing choice label (branch edges)
    "conditions": {},                  // reserved for runtime conditions
    "metadata": {}                     // reserved for custom data
  }
}

The graph is a directed acyclic graph (DAG). At runtime, load the JSON, find the entry node, and walk edges until you hit an end action. Below is a complete, copy-pasteable TypeScript runtime.

Step 1 — TypeScript types

interface NodeData {
  name?: string;
  dialogue?: string;
  emotion?: string;
  portrait?: string;
  actionType?: "branch" | "trigger" | "jump" | "end";
  label?: string;
  attributes?: Record<string, unknown>;
}

interface DialogueNode {
  id: string;
  type: "character" | "action";
  data: NodeData;
}

interface DialogueEdge {
  id: string;
  source: string;
  target: string;
  data: { optionText: string; conditions: object; metadata: object };
}

interface DialogueGraph {
  version: number;
  name: string;
  nodes: DialogueNode[];
  edges: DialogueEdge[];
}

Step 2 — Build lookup maps

import graphJson from "./my-dialogue.forge.json";

const graph = graphJson as DialogueGraph;

// O(1) lookups by id
const nodeById = new Map(graph.nodes.map((n) => [n.id, n]));

// Outgoing edges grouped by source node
const edgesFrom = new Map<string, DialogueEdge[]>();
for (const edge of graph.edges) {
  if (!edgesFrom.has(edge.source)) edgesFrom.set(edge.source, []);
  edgesFrom.get(edge.source)!.push(edge);
}

Step 3 — Find the entry node

function findStartNode(graph: DialogueGraph): DialogueNode {
  const hasIncoming = new Set(graph.edges.map((e) => e.target));
  // Root nodes have no incoming edges
  return graph.nodes.find((n) => !hasIncoming.has(n.id)) ?? graph.nodes[0];
}

Step 4 — Dialogue runner

class DialogueRunner {
  private currentId: string;

  constructor(startNode: DialogueNode) {
    this.currentId = startNode.id;
  }

  get current(): DialogueNode        { return nodeById.get(this.currentId)!; }
  get choices(): DialogueEdge[]      { return edgesFrom.get(this.currentId) ?? []; }
  get isEnded(): boolean {
    const n = this.current;
    return n.type === "action" && n.data.actionType === "end";
  }

  /** Move to the next node. Pass a choiceIndex for branch nodes. */
  advance(choiceIndex = 0): boolean {
    if (this.isEnded) return false;
    const edge = this.choices[choiceIndex];
    if (!edge) return false;
    this.currentId = edge.target;
    return true;
  }
}

// ── Example traversal loop ─────────────────────────────────────
const runner = new DialogueRunner(findStartNode(graph));

while (!runner.isEnded) {
  const node = runner.current;

  if (node.type === "character") {
    console.log(`${node.data.name}: ${node.data.dialogue}`);
    runner.advance();                    // auto-advance (single outgoing edge)

  } else if (node.data.actionType === "branch") {
    runner.choices.forEach((e, i) =>
      console.log(`  [${i}] ${e.data.optionText}`)
    );
    const playerChoice = 0;             // ← replace with real player input
    runner.advance(playerChoice);

  } else if (node.data.actionType === "trigger") {
    fireGameEvent(node.data.label!);    // ← your event system here
    runner.advance();

  } else if (node.data.actionType === "jump") {
    runner.advance();                    // follows the single outgoing edge
  }
}

Other engines