VNLE 使用手册

Phaser

Phaser 3.90 · JavaScript

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

1 · 准备文件和场景

在同一个 Web 项目中创建 index.html、first-text.js 和 story/story.json。通过 script 标签先引入 Phaser 3.90，再引入 first-text.js。可以使用已有的 examples/phaser/phaser.min.js。请通过本地 Web 服务器打开项目，不要双击 HTML 文件。

story.json · 导出文件说明

2 · 显示第一句文本

<!doctype html>
<html lang="en"><meta charset="utf-8"><title>First VNLE text</title>
<script src="phaser.min.js"></script>
<script src="first-text.js"></script></html>

Phaser 3.90 · Phaser 许可证

class FirstText extends Phaser.Scene {
  preload() {
    this.load.json('story', 'story/story.json');
    this.load.on('loaderror', file => console.error('Cannot load', file.src));
  }
  create() {
    const story = this.cache.json.get('story');
    if (!story) { this.add.text(24, 24, 'Cannot load story.json'); return; }
    const locale = 'en';
    const id = 'fd7b61a3-8233-4ba7-8f77-b88b119a91bf';
    const record = story.content.texts[id];
    const translation = story.content.translations[locale]?.[id];
    const message = translation ? translation.message : record.sourceMessage;
    const text = message.segments.map(segment => {
      if (segment.kind !== 'text') throw new Error('Text-only example');
      return segment.text;
    }).join('');
    this.add.text(24, 24, text, {fontSize: '24px', wordWrap: {width: 720}});
  }
}
new Phaser.Game({type: Phaser.AUTO, width: 800, height: 300, scene: FirstText});

预期显示：“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。后续流程取决于节点类型。

姓名和对话：使用 Text.setText()。选项：使用 Text.setInteractive() 和 pointerdown，并让每项保留自己的选项 ID。End：用 setVisible(false) 隐藏对话对象并禁用其输入，游戏场景继续运行。

用当前编程语言查看选项和金币检查

读取选项数据

将这段代码插入加载完成后可访问 story 的位置（RPG Maker 中使用 const story = $gameTemp.vnleExample.story;）。它会输出 ID 以供检查，请将输出替换为你的选项按钮。此代码只涵盖港口示例中的两个选项及随后的金币检查，并非通用解释器。

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

有 10 枚金币时，next 指向 Pay five gold；有 2 枚时则指向 Not enough gold。在实际游戏中，只有选中的路径到达该节点时才执行检查。每个选项都有自己的后续流程。

4 · 映射你自己的图片

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

// preload(): the key is a real VNLE character ID; the file is yours.
this.load.image('807b2957-7bab-4a28-83a4-1f3d1589bbc2', 'assets/portraits/mira.png');
// create(): keep one image for the dialogue bar.
this.portrait = this.add.image(100, 180, '807b2957-7bab-4a28-83a4-1f3d1589bbc2').setVisible(false);
// When showing a dialogue; node is your current dialogue object:
const key = node.speakerRef;
this.portrait.setVisible(Boolean(key && this.textures.exists(key)));
if (key && this.textures.exists(key)) this.portrait.setTexture(key);

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

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

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

将 JSON 和图片保留在发布的 Web 文件夹中。除非配置了加载器路径，否则路径相对于 HTML 页面。preload 将加载请求加入队列，在 create 中使用数据，并检查加载失败的情况。

检查结果

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

官方文档

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