System·phaserthree·v1.0.0·MIT

Dialogue System

Branching JSON-driven dialogue runner with choices and variables. Engine-agnostic — bring your own UI renderer.

#dialogue#narrative#rpg

Install

npx gamecn add dialogue-system

Source preview

Compatibility

Engines
phaser >=3.80.0 <4.0.0three >=0.160.0
Frameworksvanilla, react
Languagestypescript
Bundlersvite

Files installed

  • {systems}/DialogueSystem.ts
  • docs/gamecn/dialogue-system.md(docs)

Notes

Authoring a script

import type { DialogueScript } from "@/systems/DialogueSystem";

const script: DialogueScript = {
  start: "intro",
  nodes: {
    intro: {
      id: "intro",
      speaker: "Old Man",
      text: "Have we met before, traveler?",
      choices: [
        { text: "We have.", next: "remember", set: { metBefore: true } },
        { text: "I don't think so.", next: "forget" },
      ],
    },
    remember: {
      id: "remember",
      speaker: "Old Man",
      text: "Then you know what I want.",
      next: "end",
    },
    forget: {
      id: "forget",
      speaker: "Old Man",
      text: "Hmph. Then begone.",
      next: "end",
    },
    end: {
      id: "end",
      text: "(end)",
      // no `next` → finishes
    },
  },
};

Running it

import { DialogueSystem } from "@/systems/DialogueSystem";

const dialogue = new DialogueSystem(script);

dialogue.onChange(({ current, finished }) => {
  if (finished) {
    ui.hide();
    return;
  }
  ui.show(current!.speaker, current!.text, dialogue.visibleChoices());
});

dialogue.start({ playerName: "Max" });

// On UI events:
dialogue.next();          // advance linear node
dialogue.choose(0);       // pick visible choice 0

Conditional choices

{
  text: "Show the king's seal.",
  next: "kingResponse",
  if: (vars) => vars.hasSeal === true,
}

Notes

  • The runner is pure logic — ship any UI you like (DOM, Phaser containers, R3F components).
  • Variables are an opaque Record<string, unknown>; structure them however you want.
  • Pair with @main/save-load to persist progress (vars + current node id).

Related