> 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). # 模组框架 视频链接 本指南将向你展示如何制作 Mod，将 Convai 的功能添加到任何已有或已发布的 Unreal Engine 游戏中，适用于 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++ Mod 制作 API、SDK 生成器、蓝图 Mod 加载器、实时属性编辑器以及其他转储工具。 ### **安装** 让我们先从设置 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*”的任意目录中。打包你的 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 中创建一个函数，用于打印曲线名称，这样会得到一个可移动的 blendshape 列表。检查哪些 blendshape 与嘴唇相关。使用 setmorphtarget 节点在蓝图 mod 中创建一个函数，以给定值移动某个 blendshape。一旦你有了 blendshape 名称列表，以及一个接收 blendshape 名称和值并按该值移动它的函数，下一步就是在你的 lua mod 中创建一个函数，它本质上会使用几个公式来计算应将某个 blendshape 移动多少，然后对口型同步所需的每个 blendshape 调用你上面创建的函数。\ \ 要使用 UE4SS 创建 lua mod，请转到此文件夹 *Phoenix\Binaries\Win64\Mods* 然后创建一个以你的 mod 名称命名的文件夹，然后打开 *Phoenix\Binaries\Win64\Mods\mods.txt* 并启用你的 mod。创建一个 *Scripts\main.lua* 文件，用于存放你的 lua mod 的逻辑。\ \ 要使用 UE4SS 创建蓝图 mod，请在与你正在 mod 制作的游戏相同版本的 unreal engine 中打开一个空白且不包含任何内容的项目。空白项目的名称应与游戏文件夹中的名称相同，例如霍格沃茨之遗有一个名为 phoenix 的文件夹，所以我将空白关卡命名为 phoenix。在项目设置/打包中启用“*使用 Pak 文件*”和“*生成分块*”以及你所 mod 制作的游戏所需的其他任何设置。例如，霍格沃茨之遗使用 Io Store，所以我也必须启用该设置。然后在编辑器首选项/实验性中启用“*允许 ChunkID 分配*”。接下来创建一个任意名称的空白关卡，然后创建一个 Mods 文件夹，再创建一个与你的 mod 同名的文件夹，并在其中创建一个名为 ModActor 的 actor。将这个 ModActor 拖入关卡。打开 ModActor，并制作几个蓝图函数，之后你可以从 lua mod 中调用它们。右键单击你创建的关卡，进入资产操作/分配到 chunk 并选择一个数字，对 ModActor 和任何其他使用相同数字的资产重复同样操作。前往 *文件/打包项目/构建* 配置并选择 Shipping，然后点击 Windows 来打包你的 mod。在你选择用于打包 mod 的文件夹中，前往 *WindowsNoEditor/{project\_name}/Content/Paks* 并将带有你上面选择的编号的三个文件重命名，使其与你在 unreal engine 的 Mods 文件夹中创建的文件夹名称一致。\ \ 要在我们的 Lua mod 中调用蓝图 mod 的函数，我们使用“*查找第一个*”来定位上面创建的 ModActor，然后调用所需函数。查看“*main.lua*", "*main.cc*", "*convailevel.umap*”和“*ModActor.uasset*”将有助于更清楚地理解。 ### **来自社区的实用工具、示例和指南** * * * * * * * ### **特别鸣谢** 特别感谢 UE4SS 和霍格沃茨之遗的 mod 社区。没有他们宝贵的帮助、工具、指南和文档，这一切都无法实现。非常感谢他们不可或缺的贡献！ --- # 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 dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/modding-framework.md?ask= ``` The question should be specific, self-contained, and written in natural language. 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.