GameMaker

← 将内容接入游戏

GameMaker · GML（struct_get / struct_exists）

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

1 · 准备文件和场景

将 story.json 添加为 Included File。创建 obj_dialogue，在第一个房间中放置一个实例，并将代码粘贴到 Create 事件。添加 Draw GUI 事件，内容为 draw_text_ext(24, 24, dialogue_text, -1, 700);。此教程使用桌面端文件访问方式。

story.json · 导出文件说明

2 · 显示第一句文本

// obj_dialogue: Create event. story.json is an Included File.
dialogue_text = "Cannot read story.json";
var file = buffer_load(working_directory + "story.json");
if (file >= 0) {
    var raw = buffer_read(file, buffer_text);
    buffer_delete(file);
    try {
        story = json_parse(raw);
        var locale = "en";
        var id = "fd7b61a3-8233-4ba7-8f77-b88b119a91bf";
        var record = struct_get(story.content.texts, id);
        var message = record.sourceMessage;
        if (struct_exists(story.content.translations, locale)) {
            var translations = struct_get(story.content.translations, locale);
            if (struct_exists(translations, id)) message = struct_get(translations, id).message;
        }
        dialogue_text = "";
        for (var i = 0; i < array_length(message.segments); i++) {
            var segment = message.segments[i];
            if (segment.kind != "text") throw "Text-only example";
            dialogue_text += segment.text;
        }
    } catch (error) { dialogue_text = "Cannot read this story text"; }
}
// Put the following line in the same object's Draw GUI event, not Create:
// draw_text_ext(24, 24, dialogue_text, -1, 700);

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

在 Draw GUI 中绘制姓名和对话。使用携带选项 ID 的按钮实例显示选项。End：将 dialogue_open 变量设为 false，并用它控制绘制和输入。不要调用 game_end()。

1. Continue 与 End：沿连接继续，关闭对话框
2. 选项：选项 ID、顺序和选中后的流程
3. 条件与变量：十枚或两枚金币
4. 语言：保留相同 ID，重新解析内容
5. Command：给予物品或打开商店
6. Call/Return：进入子故事后返回

// After story was loaded successfully.
var choice = struct_get(story.execution.nodes, "42edfff8-b8fe-46bf-ae0d-9e2347b6e726");
for (var i = 0; i < array_length(choice.optionOrder); i++) {
    var option_id = choice.optionOrder[i];
    var option = struct_get(choice.options, option_id);
    show_debug_message(option_id + " " + option.text.textRef);
    // Resolve text; keep option_id on your answer button instance.
}
var branch = struct_get(story.execution.nodes, "c1c3c372-0a73-4cd0-851d-ede59d5709bb");
var gold = 10; // Repeat with 2.
var next_step = gold >= branch.condition.right.value.value ? branch.whenTrue : branch.whenFalse;
show_debug_message(next_step.nodeRef);

4 · 映射你自己的图片

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

// Import mira.png as sprite spr_mira. In Create:
portraits = {};
struct_set(portraits, "807b2957-7bab-4a28-83a4-1f3d1589bbc2", spr_mira);
// In Draw GUI, with node holding the current dialogue struct:
if (struct_exists(portraits, node.speakerRef)) {
    draw_sprite(struct_get(portraits, node.speakerRef), 0, 96, 180);
}

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

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

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

为所选构建目标包含该文件。使用 struct_get 读取 ID 键；带连字符的名称不能通过点语法访问。对于浏览器目标，需要单独调整并测试文件加载路径。

检查结果

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

官方文档

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

• 将 JSON 转换为结构体
• 缓冲加载
• 包含文件