GDevelop

← 将内容接入游戏

GDevelop 5 — JavaScript 事件

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

1 · 准备文件和场景

在项目资源中添加名为 story.json 的 JSON 资源，文件为 story.json。创建名为 DialogueText 的 Text 对象并放入场景。添加 At the beginning of the scene 事件，在其下添加 JavaScript 事件。加载完成后的回调会填充显示内容。

story.json · 导出文件说明

2 · 显示第一句文本

// JavaScript event under "At the beginning of the scene".
// Register story.json as a JSON resource named story.json first.
const label = runtimeScene.getObjects('DialogueText')[0];
const manager = runtimeScene.getGame().getJsonManager();
manager.loadJson('story.json', (error, story) => {
  if (error || !story) { label.setString('Cannot load story.json'); return; }
  try {
    const locale = 'en';
    const id = 'fd7b61a3-8233-4ba7-8f77-b88b119a91bf';
    const content = 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('');
    label.setString(line);
  } catch (error) { label.setString('Cannot read this story text'); }
});

预期显示：“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 对象使用 setString()。选项按钮事件保留选项 ID；JavaScript 可以处理相同的 JSON 对象。End：通过 hide(true) 隐藏对话对象，并用场景变量控制是否处理其输入事件。

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，图片名称和位置则由你的游戏决定。请将代码插入标明的位置。

// Add the image to a Portrait Sprite animation named Mira in the editor.
const animations = {'807b2957-7bab-4a28-83a4-1f3d1589bbc2': 'Mira'};
const portrait = runtimeScene.getObjects('Portrait')[0];
const animation = animations[node.speakerRef];
portrait.hide(!animation);
if (animation) portrait.setAnimationName(animation);

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

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

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

导出时将文件作为项目资源注册并保留，不要硬编码本地磁盘路径。回调是异步的：后续事件必须等待加载成功后再使用数据。

检查结果

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

官方文档

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

• JSON 资源管理器
• RuntimeGame
• Sprite 动画 API