Unreal Engine

← 将内容接入游戏

Unreal Engine 5 · C++

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

1 · 准备文件和场景

使用 C++ 项目，并将自己的 Actor 放在当前打开的地图中。在 .Build.cs 的模块依赖中添加 Json，将 story.json 放入 Content/Story。把下方辅助函数加入 Actor 的 .cpp，在 BeginPlay 中、Super::BeginPlay() 之后调用 UE_LOG(LogTemp, Display, TEXT("%s"), *ReadWelcome());，再在 Output Log 中查看结果。

story.json · 导出文件说明

2 · 显示第一句文本

// Add these includes at the top of your existing Actor .cpp file.
#include "Misc/FileHelper.h"
#include "Misc/Paths.h"
#include "Dom/JsonObject.h"
#include "Serialization/JsonReader.h"
#include "Serialization/JsonSerializer.h"

// File-local helper; call from your Actor's BeginPlay.
static FString ReadWelcome()
{
    FString Raw;
    if (!FFileHelper::LoadFileToString(Raw, *(FPaths::ProjectContentDir() / TEXT("Story/story.json"))))
        return TEXT("Cannot load story.json");
    TSharedPtr<FJsonObject> Story;
    const auto Reader = TJsonReaderFactory<>::Create(Raw);
    if (!FJsonSerializer::Deserialize(Reader, Story) || !Story.IsValid())
        return TEXT("Invalid JSON");
    // Following accesses expect the supplied, validated Harbour export.
    const auto Content = Story->GetObjectField(TEXT("content"));
    const FString Id = TEXT("fd7b61a3-8233-4ba7-8f77-b88b119a91bf");
    auto Message = Content->GetObjectField(TEXT("texts"))->GetObjectField(Id)->GetObjectField(TEXT("sourceMessage"));
    const FString Locale = TEXT("en");
    const TSharedPtr<FJsonObject>* Table = nullptr;
    const TSharedPtr<FJsonObject>* Translation = nullptr;
    if (Content->GetObjectField(TEXT("translations"))->TryGetObjectField(Locale, Table)
        && (*Table)->TryGetObjectField(Id, Translation))
        Message = (*Translation)->GetObjectField(TEXT("message"));
    FString Line;
    for (const auto& Segment : Message->GetArrayField(TEXT("segments")))
    {
        const auto Part = Segment->AsObject();
        if (Part->GetStringField(TEXT("kind")) != TEXT("text"))
            return TEXT("Text-only example");
        Line += Part->GetStringField(TEXT("text"));
    }
    return 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。后续流程取决于节点类型。

对话栏可使用 UMG：UTextBlock::SetText(FText::FromString(Line))、UButton::OnClicked 和 UImage。控件需要 UMG 模块依赖和绑定的控件字段。End：调用 RemoveFromParent()，或更改可见性并恢复游戏输入模式。上方 JSON 读取代码本身不需要 UMG。

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

// Inside ReadWelcome, after Story has been parsed successfully.
const auto Nodes = Story->GetObjectField(TEXT("execution"))->GetObjectField(TEXT("nodes"));
const auto Choice = Nodes->GetObjectField(TEXT("42edfff8-b8fe-46bf-ae0d-9e2347b6e726"));
for (const auto& IdValue : Choice->GetArrayField(TEXT("optionOrder")))
{
    const FString OptionId = IdValue->AsString();
    const auto Option = Choice->GetObjectField(TEXT("options"))->GetObjectField(OptionId);
    UE_LOG(LogTemp, Display, TEXT("%s: %s"), *OptionId, *Option->GetObjectField(TEXT("text"))->GetStringField(TEXT("textRef")));
}
const auto Branch = Nodes->GetObjectField(TEXT("c1c3c372-0a73-4cd0-851d-ede59d5709bb"));
const double Minimum = Branch->GetObjectField(TEXT("condition"))->GetObjectField(TEXT("right"))->GetObjectField(TEXT("value"))->GetNumberField(TEXT("value"));
const int32 Gold = 10; // Repeat with 2.
const auto Next = Branch->GetObjectField(Gold >= Minimum ? TEXT("whenTrue") : TEXT("whenFalse"));
UE_LOG(LogTemp, Display, TEXT("%s"), *Next->GetStringField(TEXT("nodeRef")));

4 · 映射你自己的图片

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

// In your UUserWidget header; assign the imported texture in its Blueprint defaults.
UPROPERTY(EditDefaultsOnly, Category="Dialogue")
TMap<FString, TObjectPtr<UTexture2D>> Portraits;
// Set the map key to: 807b2957-7bab-4a28-83a4-1f3d1589bbc2
// In widget code, PortraitImage is your bound UImage; SpeakerId comes from speakerRef.
auto* Texture = Portraits.Find(SpeakerId);
PortraitImage->SetBrushFromTexture(Texture ? Texture->Get() : nullptr);
PortraitImage->SetVisibility(Texture && Texture->Get()
    ? ESlateVisibility::Visible : ESlateVisibility::Hidden);

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

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

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

在 Project Settings → Packaging → Additional Non-Asset Directories to Package 中添加 Story。FFileHelper 使用 Unreal 的文件访问方式。不要将此 JSON 作为 DataTable 导入，其嵌套 ID 映射不是 DataTable 行。本指南使用 C++，是否将结果提供给 Blueprint 由你的项目决定。

检查结果

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

官方文档

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

• JSON 反序列化
• JSON 对象字段
• 打包设置
• UMG