RPG Maker MZ

← Bring content into your game

RPG Maker MZ · JavaScript + event commands

Start with one visible sentence. This small example reads the real Harbour export directly; it is not a complete dialogue player. Then connect the data to your game UI.

1 · Prepare files and scene

This guide targets MZ. Copy story.json into data/. Create a map event triggered by Action Button. Add the loading script first, then the wait loop described below, then the display script. Reserve game variable 1 for text and 2 for the image mapping. Follow it with a Show Text command containing \V[1]. No plugin is required.

story.json · Export files explained

2 · Show the first text

// Event command: Script. The next command waits until loading finishes.
$gameTemp.vnleExample = { ready: false, story: null, error: null };
const request = new XMLHttpRequest();
request.open('GET', 'data/story.json');
request.overrideMimeType('application/json');
request.timeout = 15000;
request.onload = () => {
  try {
    if (request.status >= 400) throw new Error('HTTP ' + request.status);
    $gameTemp.vnleExample.story = JSON.parse(request.responseText);
  } catch (error) { $gameTemp.vnleExample.error = String(error); }
  $gameTemp.vnleExample.ready = true;
};
request.onerror = request.ontimeout = () => {
  $gameTemp.vnleExample.error = 'Cannot load data/story.json';
  $gameTemp.vnleExample.ready = true;
};
request.send();

Then add event commands: Loop → Conditional Branch (Script: $gameTemp.vnleExample.ready) → Break Loop → End → Wait: 1 frame → Repeat Above. Put the display script after the loop. This keeps the engine responsive while loading.

// Event command: Script, AFTER the loading loop below has finished.
const result = $gameTemp.vnleExample;
if (result.error) {
  $gameVariables.setValue(1, result.error);
} else {
  const locale = 'en';
  const id = 'fd7b61a3-8233-4ba7-8f77-b88b119a91bf';
  const content = result.story.content;
  const translation = (content.translations[locale] || {})[id];
  const message = translation ? translation.message : content.texts[id].sourceMessage;
  const line = message.segments.map(segment => {
    if (segment.kind !== 'text') throw new Error('Text-only example');
    return segment.text;
  }).join('');
  $gameVariables.setValue(1, line);
}
// Next event command: Show Text, containing \V[1]. Reserve variable 1 for this sample.

Expected: “Welcome to the harbour. I am Mira.” With locale = "de" or the language parameter de: “Willkommen im Hafen. Ich bin Mira.” A missing language uses source text. This sample supports text segments; it deliberately does not silently discard placeholders.

3 · From one sentence to a conversation

The fixed text ID above is for the first test. In your game choose flowRef/entryRef from story-index.json, read execution.entries[entryRef].nodeRef, then execution.nodes[nodeRef]. The current dialogue supplies text.textRef and speakerRef. Continuations depend on node kind.

Show Text displays variable 1 and waits for confirmation. Show Choices offers answers with corresponding event branches. For a dynamic answer list from the complete export, your game connects option IDs to its own choice controller. End finishes conversation events and removes the dialogue picture.

1. Continue and End: follow connections, close the text box
2. Choices: answer ID, order and selected continuation
3. Conditions and variables: ten or two gold
4. Language: the same IDs, newly resolved content
5. Command: give an item or open a shop
6. Call/Return: visit a substory and return

// story is already loaded. Keep each optionId on its answer button.
const choice = story.execution.nodes['42edfff8-b8fe-46bf-ae0d-9e2347b6e726'];
for (const optionId of choice.optionOrder) {
  const option = choice.options[optionId];
  console.log(optionId, option.text.textRef); // Resolve text, then create your button.
}
// Inspect the actual purchase check. This particular node is Gold >= 5.
const branch = story.execution.nodes['c1c3c372-0a73-4cd0-851d-ede59d5709bb'];
const gold = 10; // Repeat with 2, using your current game value.
const next = gold >= branch.condition.right.value.value ? branch.whenTrue : branch.whenFalse;
console.log(next.nodeRef);

4 · Map your own images

This supplementary excerpt expects a current dialogue object named node and the UI elements named in its comments. For C++ and MonoGame, speakerRef has already been read as SpeakerId or speakerId. The key is Mira’s actual character ID; the image name and location belong to your game. Insert the lines at the indicated locations.

// node is your current VNLE dialogue. Reserve variable 2 for this mapping.
$gameVariables.setValue(2, node.speakerRef === '807b2957-7bab-4a28-83a4-1f3d1589bbc2' ? 1 : 0);
// Event commands: if Variable 2 == 1, Show Picture 20: mira from img/pictures.
// Otherwise: Erase Picture 20. Erase it again when the conversation ends.

Resolve speaker names through content.characters[speakerRef].nameTextRef just like dialogue text. Missing mappings should hide the previous portrait or show a placeholder. Images are not selected by language.

Use image references from the complete export

5 · Ship files with the game

After deployment check that data/story.json is present. Import images through the editor and account for the unused-file exclusion option. Do not assume MZ APIs apply unchanged to MV, VX Ace or other editions.

Check your result

1. English and German greetings display correctly; an unavailable language falls back to English.
2. When adding flow: try both answers, gold 10/2, the return from the substory and End.
3. Run the built game outside your project folder. JSON, fonts and portraits must be available there too.

Official documentation

API and setup references for this approach:

• MZ event commands
• MZ script reference
• MZ message commands