> 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 等不同引擎的游戏中。 视频链接 本指南将向你展示如何制作模组，为任何现有或已发布的 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++ 模组化 API、SDK 生成器、蓝图模组加载器、实时属性编辑器以及其他转储工具。 ### **安装** 让我们从设置 Convai SDK 开始。首先，前往仓库的 readme 并按照说明安装 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/*" 并粘贴到 "*main.exe*" 文件旁边的 "*convai-sdk-cpp\bazel-bin*" 目录中，或者你用于执行 "*main.exe*" 的目录。打包你的模组时，确保将 "*roots.pem*" 文件与 "*main.exe*" 一起包含。\ \ 如果你已经安装了模组，UE4SS 应该也已经安装好了。\ \ 要制作蓝图模组，你需要安装制作该游戏时所使用的 Unreal Engine 版本。例如，霍格沃茨之遗使用的是 UE4.27，因此我们需要使用该版本来制作蓝图模组。找到游戏的 exe 文件，右键单击它，选择属性并转到详细信息选项卡，你就能找到版本。 ### **模组创建** 为了理解模组创建流程，让我们一步步回顾我为《霍格沃茨之遗》模组所做的操作。你可以在仓库中找到我使用的代码。\ \ 我们将从“main.cc”开始，它包含了“*main.exe*”的逻辑。实际上，“*main.cc*”会捕获玩家的音频，在 "*get\_response\_config\_example.txt*" 文件中查找角色 ID、API 密钥、可用操作等详细信息。然后它会将这些信息发送给 Convai。之后，它会播放玩家正在互动的角色所生成的对话音频，并将对话和操作都保存到一个文本文件中。这个文本文件随后用于显示字幕并选择游戏中的适当操作。此外，你甚至可以从 convai sdk 中获取用于精确嘴型同步的 lipsync viseme 数据。\ \ 一旦我们有了 “*main.exe*”，我们只在玩家与角色互动时执行它。我们使用 UE4SS 创建一个 Lua 模组，它会等待玩家按下 F7。按下 F7 后，Lua 模组会找到类为 "*NPC\_Character*" 的最近角色，提取角色名称等信息，并用它去查找 Lua 文件中定义的字典里的角色 ID。然后，这些信息会写入 "*get\_response\_config\_example.txt*" 文件。\ \ 接下来，我们使用 os.execute 来运行 “main.exe”。执行在播放完对话后完成。我们解析对话文本和操作值来显示字幕。对于操作值，我们将其保存到一个全局变量中。在蓝图模组中，我们在 ModActor 里创建一个名为 “actionfunction” 的空函数，并带有一个输出引脚。在 Lua 模组中，我们创建一个同名的自定义事件，将输出值设置为操作值。当蓝图模组调用这个空函数时，实际触发的是 Lua 模组中定义的自定义事件，并传入操作值。然后蓝图模组会用它来触发正确的操作。\ \ 要添加嘴型同步，请在你的蓝图模组中创建一个函数，打印曲线名称，这样你就会得到一个可以移动的 blendshape 列表。检查哪些 blendshape 与嘴唇相关。使用 setmorphtarget 节点在蓝图模组中创建一个函数，以给定值移动某个 blendshape。一旦你有了 blendshape 名称列表，以及一个可以接收 blendshape 名称和值并按该值移动它的函数，下一步就是在你的 lua 模组中创建一个函数，它本质上会使用几个公式计算给定 blendshape 应该移动多少，然后对嘴型同步所需的每个 blendshape 调用你上面创建的函数。\ \ 要使用 UE4SS 创建 lua 模组，请进入这个文件夹 *Phoenix\Binaries\Win64\Mods* 并创建一个以你的模组名称命名的文件夹，然后打开 *Phoenix\Binaries\Win64\Mods\mods.txt* 并启用你的模组。创建一个 *Scripts\main.lua* 文件，它将承载你的 lua 模组的逻辑。\ \ 要使用 UE4SS 创建蓝图模组，请在 Unreal Engine 中打开一个不含任何内容的空项目，且版本与您要模组化的游戏相同。空项目的名称应与游戏文件夹中的名称相同，例如霍格沃茨之遗的文件夹名叫 phoenix，所以我把空关卡命名为 phoenix。在项目设置/打包中启用 “*Use Pak File*” 和 “*Generate Chunks*” 以及你要模组化的游戏所需的其他任何设置。例如，霍格沃茨之遗使用 Io Store，所以我也必须启用该设置。然后在编辑器首选项/实验性中启用 “*Allow ChunkID Assignments*”。接着创建一个任意名称的空关卡，再创建一个 Mods 文件夹，然后在其中创建一个以你的模组命名的文件夹，并在里面创建一个名为 ModActor 的 actor。将这个 ModActor 拖入关卡中。打开 ModActor，创建几个你稍后可以从 Lua 模组中调用的蓝图函数。右键单击你创建的关卡，进入 asset actions/assign to chunk，并选择一个数字；对 ModActor 以及任何其他使用相同数字的资源重复此操作。进入 *文件/打包项目/构建* 配置，选择 shipping，然后点击 Windows 来打包你的模组。在你选择的打包目录中，进入 *WindowsNoEditor/{project\_name}/Content/Paks* ，并将上面选择的那个数字对应的三个文件重命名为与你在 Unreal Engine 的 Mods 文件夹中创建的文件夹名称一致。\ \ 要在 Lua 模组中调用蓝图模组中的函数，我们使用 “*FindFirstOf*” 来定位我们上面创建的 ModActor，然后调用所需的函数。查看 “*main.lua*", "*main.cc*", "*convailevel.umap*” 和 “*ModActor.uasset*” 中的代码会更容易理解。 ### **社区提供的实用工具、示例和指南** * * * * * * * ### **特别鸣谢** 特别要向 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=&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.