Defold

← 将内容接入游戏

Defold · Lua · GUI

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

1 · 准备文件和场景

将 story.json 复制到 /story/，在 game.project 的 project → custom_resources 中添加 /story。创建 GUI，添加名为 dialogue 的文本节点，选择字体资源，再将 GUI 添加到游戏对象。为 GUI 指定 first_text.gui_script，然后运行项目。

story.json · 导出文件说明

2 · 显示第一句文本

-- first_text.gui_script: attach to a GUI containing a text node named dialogue.
function init(self)
    local raw, error = sys.load_resource("/story/story.json")
    if not raw then
        gui.set_text(gui.get_node("dialogue"), "Cannot load story.json")
        return
    end
    local ok, story = pcall(json.decode, raw)
    if not ok then
        gui.set_text(gui.get_node("dialogue"), "Invalid JSON")
        return
    end
    local locale = "en"
    local id = "fd7b61a3-8233-4ba7-8f77-b88b119a91bf"
    local content = story.content
    local translation = (content.translations[locale] or {})[id]
    local message = translation and translation.message or content.texts[id].sourceMessage
    local parts = {}
    for _, segment in ipairs(message.segments) do
        assert(segment.kind == "text", "Text-only example")
        parts[#parts + 1] = segment.text
    end
    gui.set_text(gui.get_node("dialogue"), table.concat(parts))
end

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

姓名和对话：使用 gui.set_text。选项：使用 GUI 节点、输入焦点，以及 on_input 中的 gui.pick_node；单独保留选项 ID。End：通过 gui.set_enabled(node, false) 禁用共同的 GUI 父节点，并释放输入焦点。

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

-- Inside a function where the decoded story table is available.
local choice = story.execution.nodes["42edfff8-b8fe-46bf-ae0d-9e2347b6e726"]
for _, option_id in ipairs(choice.optionOrder) do
    local option = choice.options[option_id]
    print(option_id, option.text.textRef)
    -- Resolve the text; retain option_id for the corresponding GUI button.
end
local branch = story.execution.nodes["c1c3c372-0a73-4cd0-851d-ede59d5709bb"]
local gold = 10 -- Repeat with 2.
local next_step = branch.whenFalse
if gold >= branch.condition.right.value.value then next_step = branch.whenTrue end
print(next_step.nodeRef)

4 · 映射你自己的图片

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

-- Add mira.png to an atlas and register that atlas as portraits in the GUI Textures.
local portraits = { ["807b2957-7bab-4a28-83a4-1f3d1589bbc2"] = "mira" }
local portrait = gui.get_node("portrait") -- GUI Box node using the portraits texture
local animation = portraits[node.speakerRef]
gui.set_enabled(portrait, animation ~= nil)
if animation then gui.play_flipbook(portrait, hash(animation)) end

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

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

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

custom_resources 会将原始 JSON 包含在发布包中。Lua 数组从 1 开始，用 ipairs 遍历 optionOrder，用 table[id] 读取 JSON 中以 ID 为键的映射。通过 atlas 资源将图片加入 GUI。

检查结果

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

官方文档

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

• 加载 JSON 数据
• 系统资源
• 图形用户界面 API