Godot

← 将内容接入游戏

Godot 4.x · GDScript

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

1 · 准备文件和场景

创建以 Label 为根节点的场景并保存。将完整的港口导出文件放在 res://story/ 下，把 FirstText.gd 挂到 Label 上，按 F6 运行场景。

story.json · 导出文件说明

2 · 显示第一句文本

extends Label

const TEXT_ID = "fd7b61a3-8233-4ba7-8f77-b88b119a91bf"
var story: Dictionary

func _ready() -> void:
    var parser = JSON.new()
    var error = parser.parse(FileAccess.get_file_as_string("res://story/story.json"))
    if error != OK or not parser.data is Dictionary:
        text = "Cannot read story/story.json"
        return
    story = parser.data
    show_language("en")

func show_language(locale: String) -> void:
    var record: Dictionary = story["content"]["texts"][TEXT_ID]
    var translation: Dictionary = story["content"]["translations"].get(locale, {}).get(TEXT_ID, {})
    var message: Dictionary = translation.get("message", record["sourceMessage"])
    var line := ""
    for segment in message["segments"]:
        if segment["kind"] != "text":
            text = "This example needs text-only segments"
            return
        line += segment["text"]
    text = line

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

姓名和对话：使用 Label.text。选项：使用 Button.text 和 pressed 信号，并保留选项 ID。End：对共同的 Control 容器调用 hide()。示例中的 show_language("de") 会切换同一句文本的语言，不会推进节点。

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

# story is the Dictionary loaded above. These Harbour options have no conditions.
var choice: Dictionary = story["execution"]["nodes"]["42edfff8-b8fe-46bf-ae0d-9e2347b6e726"]
for option_id in choice["optionOrder"]:
    var option: Dictionary = choice["options"][option_id]
    print(option_id, " ", option["text"]["textRef"])
# Resolve each text and bind its option_id to a Button's pressed signal.
var branch: Dictionary = story["execution"]["nodes"]["c1c3c372-0a73-4cd0-851d-ede59d5709bb"]
var gold := 10 # Repeat with 2.
var next: Dictionary = branch["whenTrue"] if gold >= branch["condition"]["right"]["value"]["value"] else branch["whenFalse"]
print(next["nodeRef"])

4 · 映射你自己的图片

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

# Put mira.png at res://portraits/mira.png and add a TextureRect named Portrait.
var portraits = {"807b2957-7bab-4a28-83a4-1f3d1589bbc2": preload("res://portraits/mira.png")}
# node is the current dialogue dictionary, not a Godot scene node.
$Portrait.texture = portraits.get(node.get("speakerRef", ""))

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

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

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

使用 FileAccess 时，导出包必须保留原始 JSON：可用时选择 Keep File，或设置相应的非资源文件导出筛选。图片可以使用导入的 Texture2D 资源，也可以明确包含原始 PNG 文件。请同时测试导出后的游戏。

检查结果

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

官方文档

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

• FileAccess / 打包文件
• JSON 解析
• 按钮信号