miaoda-game-scenario-phaser

Use this Phaser 4 adapter to run miaoda-game-scenario-core scripts with delayed waits, command handlers, and choice presenters tied to a Scene lifecycle.

Install

pnpm add miaoda-game-scenario-phaser miaoda-game-scenario-core

Phaser >=4 <5 is required.

Minimal controller

const story = scene.scenarios.create()
  .on('say', (ctx) => dialogue.show(ctx.args[0], ctx.args[1]))
  .onChoice((options, signal) => menu.present(options, signal));

story.load(scriptText);
await story.play();

Dialogue reveal driver

PhaserDialoguePresenter drives the shared DialoguePlayer from Scene update events while the game retains ownership of its Text objects and input layout:

const presenter = new PhaserDialoguePresenter(scene, {
  charactersPerSecond: 36,
  render: ({ speaker, visibleText }) => text.setText(`${speaker ?? ''}: ${visibleText}`),
});

story.on('say', (ctx) => presenter.present({
  speaker: ctx.args[0],
  text: ctx.args.slice(1).join(' '),
}, ctx.signal));
controls.bindButton('dialogue.advance', () => nextKey.isDown);
// Call only on the action's pressed edge, not every frame while held.
if (controls.pressed('dialogue.advance')) presenter.advance();

One advance first reveals the current page, the next moves pages or completes the command. Scene shutdown and the handler AbortSignal cancel pending dialogue without leaving a scenario Promise unresolved. The presenter supplies no visual skin and never creates a second input or Game Object owner.

Register ScenarioPlugin as a Scene Plugin to use scene.scenarios.create(), or construct new ScenarioController(scene) directly. wait uses seconds and is driven by Phaser delayed calls. Handlers receive an abort signal; cancel their own tweens, audio, and UI when the Scene shuts down.

Save controller.snapshot only at a quiescent boundary. Restore with loadSnapshot(snapshot) and continue with resume() after loading the same script into a fresh controller.

A displayed choice menu is a safe checkpoint: the Core runner is quiescent and its snapshot owns the exact options and target labels even while the controller's play() promise and isPlaying remain active. Restoring that snapshot presents the same options through onChoice before continuing. A pending command or wait is not safe because its Scene-side effect may already have started. Do not restore onto a controller that is still playing.

Calling stop() while the menu is displayed cancels the Core choice. If a presenter promise later returns an index, the controller ignores it and executes no branch.

Public API

ScenarioController, ScenarioPlugin, PhaserDialoguePresenter, command/choice registration, load, play, resume, and stop are exported. Import engine-independent scenario types from miaoda-game-scenario-core. The adapter does not provide a dialogue skin or choice layout.