RPG Maker MZ

← 将内容接入游戏

RPG Maker MZ · JavaScript + 事件命令

先让游戏显示一句话。这个小示例直接读取实际的港口导出数据，还不是完整的对话播放器。之后再将数据接入你的游戏界面。

1 · 准备文件和场景

本指南适用于 MZ。将 story.json 复制到 data/。创建以 Action Button 触发的地图事件，依次添加加载脚本、下方说明的等待循环和显示脚本。保留游戏变量 1 存放文本，变量 2 存放图片映射。之后添加内容为 \V[1] 的 Show Text 命令。无需插件。

story.json · 导出文件说明

2 · 显示第一句文本

// 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();

然后依次添加事件命令：Loop → Conditional Branch（Script: $gameTemp.vnleExample.ready）→ Break Loop → End → Wait: 1 frame → Repeat Above。将显示脚本放在循环之后，这样加载期间引擎仍能响应。

// 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.

预期显示：“Welcome to the harbour. I am Mira.”设置 locale = "de" 或将语言参数设为 de 时，应显示：“Willkommen im Hafen. Ich bin Mira.”找不到对应语言时会使用原文。此示例支持文本片段，不会悄悄忽略占位符。

3 · 从一句话到完整对话

上方固定的文本 ID 仅用于首次测试。在游戏中，请从 story-index.json 选择 flowRef/entryRef，读取 execution.entries[entryRef].nodeRef，再读取 execution.nodes[nodeRef]。当前对话节点提供 text.textRef 和 speakerRef。后续流程取决于节点类型。

Show Text 显示变量 1 并等待确认。Show Choices 提供选项及对应的事件分支。若要从完整导出生成动态选项列表，游戏需要将选项 ID 连接到自己的选项控制器。End 结束对话事件并移除对话图片。

1. Continue 与 End：沿连接继续，关闭对话框
2. 选项：选项 ID、顺序和选中后的流程
3. 条件与变量：十枚或两枚金币
4. 语言：保留相同 ID，重新解析内容
5. Command：给予物品或打开商店
6. Call/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 · 映射你自己的图片

这段补充代码要求当前对话对象名为 node，并使用注释中指定名称的界面元素。对于 C++ 和 MonoGame，speakerRef 已读取为 SpeakerId 或 speakerId。映射键是米拉实际的角色 ID，图片名称和位置则由你的游戏决定。请将代码插入标明的位置。

// 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.

与对话文本一样，通过 content.characters[speakerRef].nameTextRef 解析角色姓名。找不到图片映射时，应隐藏上一张立绘或显示占位图。图片不会根据语言选择。

使用完整导出中的图片引用

5 · 将文件随游戏一起发布

部署后确认 data/story.json 存在。通过编辑器导入图片，并注意排除未使用文件的选项。不要假定 MZ API 可以原样用于 MV、VX Ace 或其他版本。

检查结果

1. 英语和德语问候应正确显示；选择不可用的语言时回退到英语。
2. 加入流程后，测试两个选项、10/2 枚金币、从子故事返回，以及 End。
3. 在项目目录之外运行构建后的游戏，确认 JSON、字体和立绘仍然可用。

官方文档

此实现方式所用的 API 与设置参考：

• MZ 事件命令
• MZ 脚本参考
• MZ 消息命令