Unity

← 将内容接入游戏

Unity 6 · C# · Newtonsoft Json

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

1 · 准备文件和场景

将 story.json 导入 Assets/Story。在 Package Manager 中安装 Unity 包 com.unity.nuget.newtonsoft-json。创建 Canvas → Text - TextMeshPro，若提示则导入 TMP Essentials。将 FirstText.cs 挂到 GameObject，在 Inspector 中将 JSON TextAsset 和文本对象分别赋给 storyFile 和 dialogueText，然后点击 Play。

story.json · 导出文件说明

2 · 显示第一句文本

using System;
using Newtonsoft.Json.Linq;
using TMPro;
using UnityEngine;

public class FirstText : MonoBehaviour
{
    [SerializeField] private TextAsset storyFile;
    [SerializeField] private TMP_Text dialogueText;
    private JObject story;

    private void Start()
    {
        try { story = JObject.Parse(storyFile.text); ShowLanguage("en"); }
        catch (Exception error) { dialogueText.text = "Cannot read story.json"; Debug.LogException(error); }
    }

    public void ShowLanguage(string locale)
    {
        const string id = "fd7b61a3-8233-4ba7-8f77-b88b119a91bf";
        var content = story["content"];
        var translation = content["translations"]?[locale]?[id];
        var message = translation?["message"] ?? content["texts"][id]["sourceMessage"];
        string line = "";
        foreach (var segment in message["segments"])
        {
            if ((string)segment["kind"] != "text") throw new Exception("Text-only example");
            line += (string)segment["text"];
        }
        dialogueText.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。后续流程取决于节点类型。

姓名和对话：使用 TMP_Text.text。选项：使用 Button.onClick，将每个选项 ID 保存在独立的局部变量中。End：调用 dialogPanel.SetActive(false)。按钮可传入字符串 de 调用 ShowLanguage，切换语言而不重置进度。

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

// Inside a method after story (JObject) has been loaded.
var choice = story["execution"]["nodes"]["42edfff8-b8fe-46bf-ae0d-9e2347b6e726"];
foreach (var optionIdToken in choice["optionOrder"])
{
    string optionId = (string)optionIdToken;
    var option = choice["options"][optionId];
    Debug.Log(optionId + " " + (string)option["text"]["textRef"]);
    // Resolve the text and retain optionId in your Button.onClick listener.
}
var branch = story["execution"]["nodes"]["c1c3c372-0a73-4cd0-851d-ede59d5709bb"];
int gold = 10; // Repeat with 2.
var next = gold >= (int)branch["condition"]["right"]["value"]["value"]
    ? branch["whenTrue"] : branch["whenFalse"];
Debug.Log((string)next["nodeRef"]);

4 · 映射你自己的图片

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

// Add inside your own MonoBehaviour. Assign a Sprite and a UI Image in Inspector.
[SerializeField] private Sprite miraPortrait;
[SerializeField] private UnityEngine.UI.Image portrait;
// node is the current JObject dialogue:
portrait.sprite = (string)node["speakerRef"] == "807b2957-7bab-4a28-83a4-1f3d1589bbc2" ? miraPortrait : null;
portrait.enabled = portrait.sprite != null;

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

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

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

被引用的 TextAsset 会随场景一起打包。ID 表是使用动态键的 JSON 对象，这里的 JObject 不能直接替换为 JsonUtility。此示例不需要通过 StreamingAssets 访问文件。

检查结果

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

官方文档

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

• Unity Newtonsoft Json 包
• TextAsset
• JSON 序列化限制