Connect dialogue and game

VNLE stores your story’s flow. The player follows that flow. Your dialogue box displays its result: name, image, text and available replies. Your game manages inventory, movement and other game systems.

How the dialogue box works

1. The player speaks to Mira. Your game pauses movement, opens the dialogue box and starts the matching entry point.
2. For a dialogue, the UI reads text, speaker and portrait from the player view. Continue calls next().
3. For a choice, it creates a button for each offered answer. Clicking calls choose(option.id).
4. The player runs conditions, variable changes, jumps, calls and returns until it reaches another visible step.
5. A game action waits for your game. In this example, give_item adds an item and returns the matching outcome. Only then does the conversation continue.
6. For finished, your game hides the dialogue box and enables movement again. The End node ends the conversation, not the game.

Use the JavaScript example

vnle-player.mjs contains the VNLE player. demo.mjs connects it to the included dialogue box. Open both files to follow each action.

import {StoryPlayer} from './vnle-player.mjs';
const story = await (await fetch('./story.json')).json();
const map = await (await fetch('./guide-map.json')).json();
const inventory = [];
const player = await StoryPlayer.create(story, {
  locale: 'en',
  assetBase: new URL('./', location.href).href,
  onChange(view) {
    // Update your dialogue box here. See demo.mjs for the complete UI.
    console.log(view.kind, view.speaker, view.text, view.portrait);
  },
  async onCommand(command) {
    if (command.key === 'give_item') {
      const itemId = command.arguments[map.input].value;
      if (!inventory.includes(itemId)) inventory.push(itemId);
      return {outcomeId: map.accepted};
    }
    throw new Error('Unknown game action: ' + command.key);
  }
});
await player.start(map.start);

Try the dialogue box in your browser · View JavaScript source code

Language and saved games

player.language('de'); // Redraw the current line in German.
const saved = {player: player.snapshot(), inventory};
// Save the complete object with your game state.
await player.restore(saved.player);

Save inventory and dialogue state together. Restore the inventory too when loading. A dialogue save contains execution progress and its variables; it does not replace the rest of your game save. The player checks whether the execution state belongs to the story build.

Ready-to-open examples

Godot · Phaser