> For the complete documentation index, see [llms.txt](https://docs.convai.com/api-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/modding-framework.md).

# Modding 框架

Convai 引入了 Modding 框架，使得可以轻松将 AI 驱动的 NPC 集成到 Unreal、Unity 等不同引擎的游戏中。

视频链接

本指南将介绍如何制作 Mod，为任何现有或已发布的 Unreal Engine 游戏添加 Convai 功能，适用于 4.12 至 5.2 版本。\
\
我们将使用以下工具：

* [Convai SDK(C++)](https://github.com/Conv-AI/convai-sdk-cpp)：此代码仓库提供一组库，可通过 gRPC 流式传输访问 Convai Character GetResponse API。
* [UE4SS Lua 脚本系统平台](https://github.com/UE4SS-RE/RE-UE4SS)：用于 UE4/5 游戏的 C++ Modding API、SDK 生成器、蓝图 Mod 加载器、实时属性编辑器以及其他转储工具。

### **安装**

首先设置 Convai SDK。前往代码仓库的自述文件，按照说明安装 Bazel 并构建项目。\
\
如果遇到“*roots.pem*”错误，请打开文件“*convai-sdk-cpp\bazel-convai-sdk-cpp\external\com\_github\_grpc\_grpc\src\core\lib\security\security\_connector\ssl\_utils.cc*”，找到第 60 行。将路径改为仅包含“*roots.pem*”。然后，从“*roots.pem*convai-sdk-cpp/bazel-convai-sdk-cpp/external/com\_github\_grpc\_grpc/etc/*convai-sdk-cpp/bazel-convai-sdk-cpp/external/com\_github\_grpc\_grpc/etc/*”中复制“*main.exe*”文件，并将其粘贴到“*convai-sdk-cpp\bazel-bin*”目录中，或者粘贴到你用来运行“*main.exe*”的其他目录中。打包 Mod 时，请确保将“*roots.pem*”文件与“*main.exe*”一同包含在内。\
\
如果已安装该 Mod，UE4SS 应该也已安装。\
\
要制作蓝图 Mod，你需要安装制作该游戏时使用的 Unreal Engine 版本。例如，《霍格沃茨之遗》使用 UE4.27，因此制作蓝图 Mod 时需要使用该版本。找到游戏的 exe 文件，右键单击并选择“属性”，然后转到“详细信息”选项卡，即可查看版本。

### **创建 Mod**

为了了解 Mod 的创建过程，我们以《霍格沃茨之遗》Mod 的制作步骤为例。你可以在代码仓库中找到我使用的代码。\
\
先来看“main.cc”，其中包含“*main.exe*”的逻辑。基本上，“*main.cc*”会采集玩家的音频，并从“*get\_response\_config\_example.txt*”文件中读取角色 ID、API 密钥、可用动作等信息，然后将这些信息发送给 Convai。随后，它会播放玩家正在交谈的角色生成的对话音频，并将对话和动作保存到文本文件中。之后会使用该文本文件显示字幕并选择合适的游戏内动作。此外，你还可以从 Convai SDK 获取唇形同步 viseme 数据，以实现准确的唇形同步。\
\
有了“*main.exe*”后，我们只会在玩家与角色互动时运行它。我们使用 UE4SS 创建 Lua Mod，使其等待玩家按下 F7。按下 F7 后，Lua Mod 会查找距离最近的“*NPC\_Character*”类角色，提取角色名称等信息，并使用这些信息从 Lua 文件中定义的字典查找角色 ID。随后，这些信息会写入“*get\_response\_config\_example.txt*”文件。\
\
接下来，我们使用 os.execute 运行“main.exe”。播放完对话后，程序执行结束。我们解析对话文本和动作值，将对话显示为字幕。对于动作值，我们将其保存到一个全局变量中。在蓝图 Mod 中，我们在 ModActor 中创建一个名为“actionfunction”的空函数，并为其添加一个输出引脚。在 Lua Mod 中，我们创建一个同名的自定义事件，并将输出值设为动作值。当蓝图 Mod 调用这个空函数时，实际触发的是 Lua Mod 中定义的自定义事件，并传入动作值。然后，蓝图 Mod 会用这个值触发相应的动作。\
\
要添加唇形同步，请在蓝图 Mod 中创建一个用于打印曲线名称的函数，这样就能得到可调整的混合变形体列表。检查哪些混合变形体与嘴唇相关。使用 setmorphtarget 节点在蓝图 Mod 中创建一个函数，以给定数值调整混合变形体。获得混合变形体名称列表，并创建一个接收混合变形体名称和数值、按该数值进行调整的函数后，下一步是在 Lua Mod 中创建一个函数，通过一些方程计算各个混合变形体需要调整的幅度，然后针对唇形同步所需的每个混合变形体调用前面创建的函数。\
\
要使用 UE4SS 创建 Lua Mod，请前往此文件夹 *Phoenix\Binaries\Win64\Mods* 然后创建一个以 Mod 命名的文件夹，并打开 *Phoenix\Binaries\Win64\Mods\mods.txt* 启用你的 Mod。创建一个 *Scripts\main.lua* 文件，用于存放 Lua Mod 的逻辑。\
\
要使用 UE4SS 创建蓝图 Mod，请使用与待修改游戏相同版本的 Unreal Engine 打开一个不含内容的空白项目。空白项目的名称应与游戏文件夹中的名称相同。例如，《霍格沃茨之遗》的文件夹名为 phoenix，因此我将空白项目命名为 phoenix。在“项目设置/打包”中启用“*使用 Pak 文件*”和“*生成分块*”，以及待修改游戏所需的其他设置。例如，《霍格沃茨之遗》使用 Io Store，因此我也必须启用该设置。然后，在“编辑器首选项/实验性”中启用“*允许分配 ChunkID*”。接下来，创建一个名称任意的空白关卡，再创建 Mods 文件夹，然后在其中创建一个以 Mod 命名的文件夹，并在该文件夹中创建一个名为 ModActor 的 Actor。将此 ModActor 拖入关卡。打开 ModActor，创建几个稍后可从 Lua Mod 调用的蓝图函数。右键单击创建的关卡，依次选择“资源操作/分配到分块”，然后选择一个编号；对 ModActor 以及其他资源重复此操作，并使用相同的编号。前往 *文件/打包项目/构建* 配置，选择 Shipping，然后单击 Windows 来打包 Mod。在你选择的 Mod 打包文件夹中，前往 *WindowsNoEditor/{project\_name}/Content/Paks* 并将上面选定编号的三个文件重命名，使其与您在 Unreal Engine 的 Mods 文件夹中创建的文件夹名称一致。\
\
要在 Lua 模组中调用蓝图模组里的函数，我们使用“*FindFirstOf*”来定位上面创建的 ModActor，然后调用所需的函数。查看“*main.lua*", "*main.cc*", "*convailevel.umap*”和“*ModActor.uasset*”中的代码会有助于更清楚地理解。

### **社区提供的实用工具、示例和指南**

* <https://www.nexusmods.com/hogwartslegacy/articles/132>
* <https://modding.wiki/en/hogwartslegacy/developers/hlblueprintex>
* <https://modding.wiki/en/hogwartslegacy>
* <https://github.com/LongerWarrior/FModel/releases/tag/HW_1.0.0.0>
* <https://modding.wiki/en/hogwartslegacy/developers/PhoenixUProjGuide>
* <https://modding.wiki/en/hogwartslegacy/developers/luaexamples>
* <https://docs.ue4ss.com/dev/index.html>

### **特别感谢**

特别感谢 UE4SS 和《霍格沃茨之遗》的模组社区。没有他们提供的宝贵帮助、工具、指南和文档，这一切都不可能实现。衷心感谢他们不可或缺的贡献！


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/modding-framework.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
