Universal Modder 是一套帮助 AI 编程代理研究、制作和测试 PC 游戏 Mod 的开源工具集。 它把技能指引、名为 um 的 Python 命令行工具、具体游戏的实践记录，以及用于生成素材的 fal 接口组合起来。本文所指的原项目是 GitHub 上的 rehan-remade/universal-modder（英文）。

初次使用时，适合从自己拥有的游戏里做一个小改动：先识别引擎与 Mod 加载器，备份测试存档，用占位素材做出功能，再进入游戏验证。“Universal”表达的是工具集覆盖多种技术路线，并不代表所有游戏、所有版本都能直接修改。

资料核查于 2026 年 10 月 9 日，对应仓库提交 8370faa 和软件包版本 0.2.0。本文依据原项目文档与源码编写，未实机运行示例 Mod，也未验证完整的 OmniaKey 接入链路。下文外部资料均为英文。

Universal Modder 包含哪些部分

项目 README 中的几层能力需要分开理解：

组成	负责什么	仍需准备什么
代理技能	指导调研、实现、素材处理与测试	已能正常调用模型的编程代理
`um` 命令行	扫描游戏安装、处理精灵图、备份存档及辅助录制	对应的本机依赖和游戏工具
共享知识库	记录其他项目的版本、实现路线与失败经验	对自己安装版本的重新验证
fal 接口	向 fal 请求图片、3D、音频或视频素材	独立的 fal 密钥与用量预算

仓库列出了 Claude Code、Codex、Cursor、Gemini CLI、Copilot 和 OpenCode 的安装入口。这说明它提供了不同代理的接入方式，并不等于所有游戏操作都跨系统通用。例如，其 Windows 游戏控制工具面向 Windows 原生环境或 WSL。

如何在 Claude Code 中安装

README 列出的依赖包括 Git、Python 3.10 或以上版本与 ffmpeg，推荐使用 uv；将 3D 模型渲染成精灵图时还需要 Blender。先按自己的制作路线准备环境，再让代理开始改游戏。

在 Claude Code 内部依次输入：

text

/plugin marketplace add rehan-remade/universal-modder
/plugin install universal-modder@universal-modder

这两条是 Claude Code 插件命令，不是终端 Shell 命令。启用前查看插件源码与申请的权限；使用其他代理时，按原项目 README 中对应的安装说明操作。

项目为插件和克隆仓库的使用方式提供了 CLI 启动器。如果单独打开终端后找不到 um，文档给出的独立安装方式是：

bash

uv tool install git+https://github.com/rehan-remade/universal-modder
um --help

这一步从仓库安装 CLI，不会顺带配置编程代理或 fal 账号。以上命令经过源码核对，本文未实际执行安装。

先识别游戏，再修改文件

下面是项目提供的发现命令。把 Terraria 换成自己的游戏名或安装目录：

bash

um scan --list
um kb search "Terraria"
um scan "Terraria" --json

游戏侦察指引说明，扫描器通过读取文件判断引擎特征、已安装加载器、存档位置与可能的修改路线。游戏没有出现在库列表中时，可以直接传入安装目录。

扫描结果用于制定方案，不能证明游戏已经受支持或可以放心修改。原指引也提醒，保护程序可能装在游戏目录之外，启动器还可能干扰引擎判断。仍要查阅当前社区加载器文档与游戏自己的 Mod 政策。

让代理在 MODDING_PLAN.md 中记录游戏版本、加载器版本、存档与日志路径、拟修改内容和恢复方法，并用 MODLOG.md 保存进度与发现。已有加载器或官方 Mod 接口能实现需求时，优先采用这条路线。

首个 Mod 的提示词与验收方法

选一个效果容易观察的小功能。下面是本文设计的提示词模板，不是已经测试过的 Mod：

在我的本地 Terraria 测试环境中，按已安装的 tModLoader 版本规划一个新的装饰物品。先检查游戏和加载器。使用占位素材及可丢弃的测试世界。改文件前列出受影响路径、备份和恢复步骤。说明如何获得物品、在游戏内验证效果以及移除 Mod。付费生成素材或对外发布之前先询问我。

项目的完整制作流程建议先用占位素材做出一小段可运行功能，再扩展范围。可以把它落实成五项验收：

**能加载：**游戏通过预期加载器启动，日志能识别该 Mod。
**看得见：**物品或改动在指定测试场景中出现。
**行为正确：**实际效果符合需求，不能只看编译成功。
**存取正常：**在测试世界保存并重新载入后，结果符合预期。
**能够恢复：**禁用 Mod 并恢复备份后，测试环境回到预期状态。

通过这些检查后，再制作正式精灵图、音效或演示视频。生成一张截图或者成功构建代码，都不能单独证明游戏兼容性。

哪些游戏有现成示例

把仓库示例视为带有版本范围的起点。作者记录的测试结果与自己机器上的验证是两回事：

**Terraria / tModLoader：**Fal Arsenal 记录的来源是 Terraria 1.4.4、tModLoader 2026.07 下的单人项目。README 明确表示多人模式未测试，应使用备用世界。
**帝国时代 II 决定版：**文明示例包含生成素材和精灵图转换，但它占用已有文明槽位，不能据此认定可以任意增加新槽位。
**Minecraft × GTA V：**示例在 GTA V 故事模式中组合两个运行中的游戏。文档记录的测试目标是 Steam 版 GTA V Legacy，构建号 3889；不能把结论扩展到 GTA Online 或其他版本。

判断兼容性时，可以按引擎指引 → 有版本记录的游戏示例 → 自己的游戏内测试逐级确认。仓库里有 Unity 或 Unreal 的说明，并不等于所有采用这些引擎的游戏都已经适配。

Universal Modder 免费吗，必须用 fal 吗

工具集源码采用 MIT 许可证。完整项目仍可能有三部分成本：编程模型访问、素材生成，以及构建和测试所需的本机硬件或工具。

fal 有独立的模型计费，费用取决于模型及相关生成设置。fal 鉴权文档使用 FAL_KEY。请在启动代理的环境里私下配置真实密钥，以下仅为占位示例。

Bash 或 Zsh：

bash

export FAL_KEY="YOUR_FAL_API_KEY"

Windows PowerShell：

powershell

$env:FAL_KEY = "YOUR_FAL_API_KEY"

编程模型凭据，包括 OmniaKey 密钥，都不是 fal 密钥。安装插件不会合并两边的账单。批准批量生成前，先确认素材模型和生成数量；不要把密钥写入 Mod 文件或发布压缩包。

也可以先用占位素材或自己制作的图片。项目素材指引还提供通过 um comfy 调用本地 ComfyUI 生成图片的路线，无需 fal 密钥。它内置的图片流程不能替代 fal 的整套音频、3D 和视频流程，本地硬件与模型环境也需要自行准备。

首次运行失败时查什么

每次只排查一层：

**找不到 um：**先检查当前终端的 PATH 和 CLI 独立安装情况，再排查游戏加载器。
**识别不到游戏：**直接传入安装目录，并对照当前社区文档检查扫描结果。
**fal 鉴权失败：**确认代理进程拿到了目标 fal 账号的 FAL_KEY。编程代理登录成功不能证明 fal 鉴权正常。
**编译通过却没有加载：**先核对游戏与加载器版本、安装路径和加载器日志，再考虑重新生成素材。
**素材进游戏后不对：**先检查尺寸、透明通道、帧排布与朝向是否符合游戏要求，再调整生图提示词。

把失败日志和最小复现步骤写进项目记录，下一轮调试才有可验证的依据。

能用于联机或对外发布吗

遵守项目列出的使用边界：修改自己拥有的游戏，优先在离线测试或自己控制且获准的环境中操作，不绕过反作弊、DRM 或所有权检查。项目规则拒绝向受保护的在线客户端注入代码；私人服务器本身也不会消除客户端保护或发行商限制。

分享前检查游戏条款以及素材、工具的许可证。工具集采用 MIT，并不授予你分发游戏文件、提取素材或反编译源码的权利。发布自己的作品时，应写清安装方式、已测试版本与移除方法。

编程模型的连接方式可继续阅读 Claude Code 接入指南，费用参考 OmniaKey 当前价格。模型连接与 fal 分别配置后，仍需在自己的环境中验证实际 Mod 工作流。

Universal Modder 安装指南