MonoGame

← 将内容接入游戏

MonoGame 3.8 · DesktopGL · C# / .NET

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

1 · 准备文件和场景

从 MonoGame DesktopGL 项目开始。将 story.json 放在 Content/ 中，作为原始文件复制到输出目录（见下方项目配置）。将 ReadWelcome 添加到 Game1。在 Content Pipeline Tool 中创建名为 DialogueFont 的 SpriteFont，构建内容后用以下方式加载：Content.Load("DialogueFont")。

story.json · 导出文件说明

2 · 显示第一句文本

<ItemGroup>
  <None Update="Content/story.json" CopyToOutputDirectory="PreserveNewest" />
</ItemGroup>

在 Game1 中添加字段 SpriteFont _dialogueFont; 和 string _dialogueLine = "";。在 LoadContent 中使用 _dialogueFont = Content.Load("DialogueFont"); _dialogueLine = ReadWelcome("en");。在 Draw 中现有的 SpriteBatch 块内使用 _spriteBatch.DrawString(_dialogueFont, _dialogueLine, new Vector2(24, 24), Color.White);。如果还没有 SpriteBatch，请在 LoadContent 中用 new SpriteBatch(GraphicsDevice) 创建，并在 Draw 中使用 Begin()/End()。

// Game1.cs: add using System.IO; using System.Text.Json; using System.Text;
// Place this method inside the existing Game1 class.
private string ReadWelcome(string locale)
{
    using var stream = TitleContainer.OpenStream("Content/story.json");
    using var document = JsonDocument.Parse(stream);
    var content = document.RootElement.GetProperty("content");
    const string id = "fd7b61a3-8233-4ba7-8f77-b88b119a91bf";
    var message = content.GetProperty("texts").GetProperty(id).GetProperty("sourceMessage");
    if (content.GetProperty("translations").TryGetProperty(locale, out var table)
        && table.TryGetProperty(id, out var translation))
        message = translation.GetProperty("message");
    var line = new StringBuilder();
    foreach (var segment in message.GetProperty("segments").EnumerateArray())
    {
        if (segment.GetProperty("kind").GetString() != "text")
            throw new InvalidDataException("Text-only example");
        line.Append(segment.GetProperty("text").GetString());
    }
    return line.ToString();
}

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

姓名和对话：在 Begin/End 之间调用 SpriteBatch.DrawString。对于较长文本，需要处理换行，并确保字体包含所需字形。选项区域及鼠标、键盘输入由游戏处理，应保留选项 ID，而非使用译文标识选项。End：用 dialogueOpen = false 停止绘制和处理输入，不要调用 Game.Exit()。

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

// Inside ReadWelcome while document is alive; inspect data before returning.
var nodes = document.RootElement.GetProperty("execution").GetProperty("nodes");
var choice = nodes.GetProperty("42edfff8-b8fe-46bf-ae0d-9e2347b6e726");
foreach (var idToken in choice.GetProperty("optionOrder").EnumerateArray())
{
    string optionId = idToken.GetString();
    var option = choice.GetProperty("options").GetProperty(optionId);
    System.Console.WriteLine(optionId + " " + option.GetProperty("text").GetProperty("textRef").GetString());
}
var branch = nodes.GetProperty("c1c3c372-0a73-4cd0-851d-ede59d5709bb");
int gold = 10; // Repeat with 2.
int minimum = branch.GetProperty("condition").GetProperty("right").GetProperty("value").GetProperty("value").GetInt32();
var next = branch.GetProperty(gold >= minimum ? "whenTrue" : "whenFalse");
System.Console.WriteLine(next.GetProperty("nodeRef").GetString());
// Copy strings/values you need later before disposing JsonDocument.

4 · 映射你自己的图片

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

// Game1 class field, so both LoadContent and Draw can access it:
private readonly System.Collections.Generic.Dictionary<string, Texture2D> portraits = new();
// Inside LoadContent(): import/build mira.png as portraits/mira.
portraits["807b2957-7bab-4a28-83a4-1f3d1589bbc2"] = Content.Load<Texture2D>("portraits/mira");
// Inside a SpriteBatch Begin/End in Draw; speakerId comes from speakerRef:
if (portraits.TryGetValue(speakerId, out var portrait))
    _spriteBatch.Draw(portrait, new Vector2(24, 120), Color.White);

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

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

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

此示例不要用 Content.Load 加载 JSON。TitleContainer 打开原始文件，csproj 负责复制文件。通过 Content Pipeline 构建 SpriteFont 和纹理。请先在 DesktopGL 上使用此教程，其他平台需要单独验证。

检查结果

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

官方文档

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

• TitleContainer.OpenStream
• SpriteFont 设置和绘图
• JSON 文档访问