rehan-remade/universal-modder · 上手攻略

  • 仓库：rehan-remade/universal-modder
  • 链接：https://github.com/rehan-remade/universal-modder
  • 分类：agent / game-modding
  • 作者：spark
  • 更新：2026-10-13

⚠️ 自检：GitHub README 已 fetch ✓；本仓库无顶会/论文 venue（MIT 应用项目，非论文）→ 标 ⚠️；README 子模块 anchor 已对齐（skills/mod-any-game / fal-assets / um CLI / knowledge/INDEX）✓。

§0 这是什么

universal-modder 是一个面向 AI 编程 Agent 的"通用游戏 Modding 工具包 + 共享知识库"。它把以下能力打包成一个开源项目：

  • Skills（Agent Skills 格式）：11 个工作流脚本，涵盖游戏侦察、逆向工程、美术/3D/音频生成、游戏内自动化、合成视频、移植、发布等。
  • um CLI（Python）：一组命令行子命令，把 Skills 背后要用到的工具（fal API、ComfyUI、Blender、ffmpeg、游戏进程管理、存档备份、知识库管理）统一收敛。
  • fal MCP 服务器：https://mcp.fal.ai/mcp，Bearer Token 鉴权，提供 sprite / image / 3D / SFX / music / voice / video 等生成能力。
  • knowledge/：一份机器可索引的"游戏实战笔记库"——按游戏分目录，记录每个 Mod 的引擎版本、可走路线、踩坑、修复方式；下个 Agent 可以直接复用。

它支持 Claude Code / Codex / Cursor / Gemini CLI / GitHub Copilot / OpenCode 以及任何"读 AGENTS.md"的 Agent。单人 / 自己服务器上的多人游戏都允许 Mod；涉及在线反作弊、写外挂对抗玩家、绕过反作弊/DRM/授权校验 全部拒绝。

§1 解决什么问题

游戏 Modding 的痛点很真实：

  1. 每个游戏的引擎不一样（Unity / Unreal / .NET/XNA / Godot / Source / Bethesda / Minecraft Forge-Fabric / AoE2 Genie / Bannerlord / RE Engine / FromSoft / GTA / Hedgehog / Frostbite / Cyberpunk / BG3 / GameMaker / RPG Maker / Ren'Py / Paradox / Doom / HTML5 / LÖVE / Java……）。
  2. Modding 流程碎片化：侦察 → 选路线 → 备份 → 逆向 → 写最小可用切片 → 美术资产 → 真实游戏验证 → 录视频 → 发布 → 写笔记——任何一环遗漏都会让下一个 Agent 重复踩坑。
  3. AI Agent 直接跑 Modding：工具链、脚本、模型 API 各家各异；Agent 缺一个统一"协作入口"。
  4. 知识沉淀缺失：Discord / 论坛 / GitHub Issues 里的经验散落，下次换个人/Agent 重新摸索。

universal-modder 的回答是：给 Agent 一个 Skills+CLI+MCP 的"游戏 Modding 操作手册"+ 一个能 PR 的实战笔记库。

§2 快速安装

2.1 前置依赖

依赖 用途
Python 3.10+ um CLI 运行环境
Git 拉仓库、子模块、PR
ffmpeg 录屏 / 合成 showcase 视频
uv（推荐）/ pipx 隔离安装 um CLI
Blender（可选） um render3d（GLB → 引擎就绪帧）
FAL_KEY fal API 密钥，控制台 https://fal.ai/dashboard/keys

2.2 三种安装路线

A. 用某个 IDE Agent（推荐起步）——按 IDE 走：

# Claude Code
/plugin marketplace add rehan-remade/universal-modder
/plugin install universal-modder@universal-modder

# Codex
codex plugin marketplace add rehan-remade/universal-modder
codex plugin add universal-modder@universal-modder

# Gemini CLI
gemini extensions install https://github.com/rehan-remade/universal-modder

# VS Code / Copilot：开 chat.plugins.enabled → Chat: Install Plugin From Source → 贴仓库 URL
# Cursor：Cursor Marketplace 或 clone（Cursor 读 AGENTS.md + .cursor/mcp.json）

B. 只要 Skills（任意 Agent）

npx skills add https://github.com/rehan-remade/universal-modder

C. 完全克隆（OpenCode / 自定义 Agent）

git clone https://github.com/rehan-remade/universal-modder
cd universal-modder
export PATH="$PWD/bin:$PATH"   # 让 um 命令直接可用

Clone 后，仓库内已经把 Skills 复制到各 Agent 默认查找目录（.agents/skills、/codex/skills、.claude/skills），MCP 配置也按 IDE 落到 .mcp.json / .codex/config.toml / .cursor/mcp.json / .vscode/mcp.json / gemini-extension.json / opencode.json。

D. OpenCode 2（无 clone）

opencode plugin add 'github:rehan-remade/universal-modder#main::path:plugins/opencode'

只装 um_run + fal MCP；Skills 走 Skills only 模式单独加。

2.3 安装 um CLI（任意位置）

export FAL_KEY=...                  # fal 鉴权（um fal + fal MCP 都用）
uv tool install git+https://github.com/rehan-remade/universal-modder
# 或：pipx install git+https://github.com/rehan-remade/universal-modder

装完后 um --help 应输出主命令组：scan / fal / comfy / sprite / render3d / win / video / backup / publish / kb。

§3 核心用法（可直接复制）

3.1 扫描你机器上的游戏

um scan
# 输出：Steam/Epic/Xbox 安装路径 + 引擎指纹 + .NET 还是 native + 反作弊 + 已装 loader + 存档目录 + 推荐路线（ranked）

3.2 改一个 Mod 的最小闭环

# （a）让 Agent 读 skills/mod-any-game/SKILL.md，然后跑循环：
#     侦察 → 选路线 → 建安全实验室（备份存档）→ 读真源码 → 写一个 working slice → 游戏内验证 → 录屏 → 打包 → 写 field note

# （b）生成美术 / 3D / 音频资产
um fal sprite "a homing missile launcher, terraria sprite sheet, 8 directions"
um fal model3d "robotaxi" --rig
um render3d model.glb --heading aoe2 --frames 8 --out ./sprites
um fal sfx "tactical nuke detonation"
um fal music "boss fight loop, 110 bpm"

# （c）Windows 进程/录屏（也可从 WSL 调用）
um win shot                              # 截屏
um win record --audio process-loopback  # 只录游戏内声音
um win drive --to-game "key w"           # 安全地把输入送到游戏窗口

# （d）合成 showcase 视频
um video contact-sheet ./captures
um video compile ./edl.json --music ./theme.mp3 --title-style space-grotesk

3.3 查/写知识库

um kb search "grand theft auto"           # 开 Mod 前先查：别人有没有踩过坑
um kb new --game "Hades II" --title "A new boon god" --from-scan hades --agent "Codex (gpt-6)"
um kb check knowledge/games/hades-ii/a-new-boon-god.md
um kb pr knowledge/games/hades-ii/a-new-boon-god.md --yes   # 人说 OK 后才 PR

3.4 备用路线：无 fal 也能跑（本地 ComfyUI）

um comfy status
um comfy image "homing missile sprite" --sprite   # --sprite 会自动做切边
um comfy run my-workflow.json                     # 任何 ComfyUI 导出的 (API) workflow

§4 典型适用场景

场景 怎么做
Terraria 加导弹发射器/战术核弹 examples/terraria-tmodloader：tModLoader 项目，所有 sprite 由 fal 出
给 AoE2 DE 加新文明 + 3D 渲染单位 examples/aoe2-de-civ：genieutils-py + 自写 .sld sprite writer + fal image-to-3D
Minecraft 嵌进 GTA V Story Mode examples/minecraft-gta5-passthrough：Fabric 端 + ScriptHookV/ReShade 端用本地 WebSocket 交换相机/地形/事件；Minecraft TNT/箭 变 GTA 爆炸
移植老 mod 到新版本/loader skills/port-a-mod：固定一个 pinned source、私有 decompile、按脚本提数据、按 unit 测试、按层 audit、resumable status doc + Forge 1.7.10 → Fabric 1.20.1 映射表
反向一个未知文件格式 skills/reverse-engineering：ILSpy / Cpp2IL / Vineflower / Ghidra / IDA-over-MCP / Cheat Engine / Frida / RenderDoc，"格式逆向 + 往返证明"
给 Agent 沉淀笔记 skills/share-field-notes：写 markdown + front matter + 提 PR，让下个 Agent 起步就是"站在你的肩膀上"

§5 坑与注意（工程节 · 三段式）

沿用 W39/W40 lessons 共识："现象 / 影响 / 修复" 三段式 + 诚实标注。

坑 1：FAL_KEY 未设导致 fal 全系命令静默失败

  • 现象：um fal image "..." 返回空 manifest，无报错；MCP 工具列表里没有 fal 工具。
  • 影响：Agent 误以为"fal 挂了"而开始瞎改；3D 资源全用占位图。
  • 修复：export FAL_KEY=... 后重开会话；用 um fal search --schema 验证连接；也可以走本地 ComfyUI 兜底（um comfy）。

坑 2：Skill 复制与源文件 drift（仓库测试会拦）

  • 现象：编辑 skills/ 后没同步到 .agents/skills / .claude/skills，CI 跑 um kb check --index / pytest 失败。
  • 影响：Agent 看到的 Skill 落后于源；复现性破坏。
  • 修复：Skill 永远只编辑 skills/，然后 cp 到各 Agent 默认目录；仓库里有测试断言两者一致。

坑 3：OpenCode 2 插件安装 ≠ Skills 安装

  • 现象：opencode plugin add ... 只装了 um_run + fal MCP；Agent 找不到任何 Skill。
  • 影响：只能裸跑 um CLI，丢失 mod-any-game 等工作流。
  • 修复：再加一次 npx skills add https://github.com/rehan-remade/universal-modder（README 明确说"add the skills with Skills only"）。

坑 4：在线带反作弊的游戏——工具会硬性拒绝

  • 现象：试图对 Valorant / EAC / BattlEye / VAC 保护的游戏运行 um win 或反编译 → um publish check 报 BLOCKED。
  • 影响：脚本直接退出，无 modding plan；这是设计如此。
  • 修复：只 Mod 本地单人、自托管多人；离线客户端（Elden Ring offline 等）走 examples/ 已工作示例。

坑 5：Windows PowerShell 5.1 写 um/ps1/*.ps1 的语法限制

  • 现象：自己加 PS1 工具时用了字符串插值 / out var / expression-bodied member，PowerShell 5.1 编译失败。
  • 影响：进程类工具（输入注入 / 进程环回音频）在 Win 7/8/Server 2016 等老 PowerShell 上完全用不了。
  • 修复：严格遵循 README 约束——"no string interpolation, no out var, no expression-bodied members"；或者直接让目标机用 PowerShell 7+。

坑 6：3D → sprite 渲染需要 Blender 在 PATH

  • 现象：um render3d model.glb --heading aoe2 报 "blender not found"。
  • 影响：所有 3D 转 sprite 流程断链；AoE2 新文明示例跑不通。
  • 修复：装 Blender 并确保 blender 命令在 PATH；或 BLENDER=/path/to/blender 环境变量指明路径。

坑 7：录屏/游戏音频双轨被吞

  • 现象：um win record 录下来只有桌面声，没有游戏声。
  • 影响：showcase 视频里游戏 BGM/SFX 全无，演示效果崩坏。
  • 修复：用 um win record --audio process-loopback（仓库自带的 um/ps1/ProcLoopback 工具只录当前游戏进程音频）。

坑 8：把游戏文件 / 反编译产物 / 密钥塞进 PR

  • 现象：um publish check 抛 BLOCKED: game files / decompiled / leaked keys。
  • 影响：无法发布；违反项目 CONTRIBUTING.md 红线（"no game files, no decompiled dumps, no cheating other players"）。
  • 修复：Mod 只 ship 代码 + 你自己的美术 + 补丁 / converter；decompile 留在仓库外。

§6 与同类对比

项目 形态 区别
tModLoader / BepInEx / SKSE / Fabric / BepInEx 等 loader 单游戏 loader 通用 mod 框架，但不是给 Agent 用的，没有 Skills/MCP/笔记库
ScriptHookV / ReShade / UE4SS / REFramework 单游戏注入/hook 同上，是被 universal-modder 站在肩膀上的工具
Mod Organizer 2 / Vortex Mod 管理器 GUI 人类工具，不带 AI 工作流；universal-modder 通过 um backup 间接管存档
ILSpy / Vineflower / Ghidra / IDA 反编译器 是 universal-modder 的 skills/reverse-engineering 引用的工具，而非"代替品"
universal-modder Skills + CLI + MCP + 笔记库 第一个把"多引擎 + Agent 工作流 + 共享笔记库"打包的开源项目

定位一句话：它不是某个游戏的 mod loader，而是"让任意 AI Agent 都能给任意 PC 游戏做 mod"的工作手册 + 协作入口。

§7 一句话推荐结论

如果你有一个 AI 编程 Agent（Claude Code / Codex / Cursor / OpenCode 等）、你恰好想给自己拥有的 PC 游戏做点东西——装上 um CLI 和 fal MCP，clone 仓库，让 Agent 跑一遍 skills/mod-any-game/SKILL.md 的循环，剩下的它自己干。引擎覆盖广、反作弊安全护栏硬、知识库可 PR 越用越厚；最大的限制是你得有 FAL_KEY、Blender、目标游戏的合法所有权，以及别想打在线反作弊游戏的主意。

spark · 2026-10-13 · 单篇完成（清单仅 1 项，按 work-guard "不足三项不补齐"规则不补第 2/3 篇）