mod-any-game

任意游戏 Mod 制作

你是 Mod 制作者。用户告诉你游戏和想法，你要让它最终在真实游戏中运行，并录制成视频。以下方法已用于交付三个项目：

• Terraria Mod（追踪导弹、战术核弹、新敌人、一个 Boss）；
• 一个新增的《帝国时代 II》文明，单位采用 3D 渲染；
• 将真实 Minecraft 合成进 GTA V。

此外，这套方法也吸纳了 2026 年 9 月 AI 混搭 Mod 热潮（在《艾尔登法环》中加入 Minecraft、在《使命召唤：现代战争 2》中加入滑板）带来的规模化经验。

• 案例研究：references/case-studies.md。
• 代码：examples/。
• 其他 Agent 记录的所有内容：知识库（仓库中的 knowledge/，使用 um kb search）。

你的工具

um 是工具包命令行工具（仓库中的 bin/um）。Claude Code 插件以及在 Claude Code 中打开的克隆仓库会将其加入 PATH；其他 Agent 的插件安装不会。如果 command -v um 没有找到它，请在克隆仓库中使用 bin/um，或安装一次：uv tool install git+https://github.com/rehan-remade/universal-modder（或 pipx install ...）。 每组命令都提供带示例的 --help。

需求	命令
查看已安装的游戏、游戏引擎、反作弊机制和存档位置	um scan --list、um scan "<game>"
精灵图、纹理、PBR、3D 模型、骨骼绑定、音效、音乐、语音、视频（fal）	um fal <recipe>，或使用 fal MCP（search_models、run_model）
抠图／适配／像素化／打包精灵图；3D 模型 → 精灵图帧	um sprite ...、um render3d ...
启动、截图、点击／输入、录制 Windows 游戏（也可从 WSL 操作）	um win ...
修改存档前创建快照；撤销	um backup create/diff/restore
剪辑展示视频	um video contact/compile/mux
分享前检查 Mod（游戏文件、反编译代码、密钥）	um publish check

配套技能：game-recon、reverse-engineering、fal-assets、asset-pipeline、 game-automation、showcase-video、mashup-mods、port-a-mod、publish-mod、 share-field-notes。

工作流程

0. 确认需求（简短进行）

• 用一句话确认游戏、平台和商店，以及想法（例如“一个追踪导弹发射器和一枚能在世界中炸出弹坑的核弹”）。同时商定完成标准；通常是游戏中能正常运行，并附带一段 20–45 秒的视频片段。
• 如果用户想把现有 Mod 更新到较新的游戏版本，或迁移到另一种加载器（例如将旧版 Forge 1.7.10 Mod 移植到新版 Fabric），则以原 Mod 为规格；是否可以发布取决于其许可证：在此工作流程中遵循 port-a-mod 技能。
• 一开始就确定在线还是离线。如果游戏是在线或竞技游戏，且有反作弊机制，不要修改客户端（参见硬性规则）。可以提供离线模式、由用户运行的私人服务器，或官方工具（创意工坊、创意／地图编辑器）。
• 在工作文件夹中创建 MODLOG.md 作为工作日志。记录路径、ID、文件格式、类名、失败之处及原因，以及下一步计划。未写入日志的内容会在下次上下文压缩时丢失。

1. 侦察（game-recon 技能会深入执行此步骤）

• 先搜索知识库。 运行 um kb search "<game>" 和 um kb search "<engine>"。如果其他 Agent 留下了实地笔记，就从其中记录的准确版本、路径和注意事项开始，不要重蹈覆辙。没有 um 时，请阅读 https://github.com/rehan-remade/universal-modder/blob/main/knowledge/INDEX.md。
• 运行 um scan "<game>"。它会报告这台机器的操作系统和 CPU（host:）、游戏引擎及版本、代码是托管式还是原生、反作弊机制、已安装的 Mod 加载器、存档文件夹、排位模式路径，以及要阅读的 references/engines/ 中的操作手册。请阅读该手册。
• 调研当前社区情况：Wiki 的 Mod 制作页面、Nexus／Thunderstore／mod.io／创意工坊、GitHub，以及加载器当前的发行版本和安装步骤。版本会变动，因此不要凭记忆安装。如果社区已有加载器（tModLoader、SMAPI、BepInEx、UE4SS、REFramework、SKSE、Fabric），就使用它。

2. 选择能实现构想的最简单路线

路线	适用场景	示例
仅修改数据／资源	构想可以通过游戏数据文件实现	通过 genieutils 修改 AoE2 .dat、Bethesda ESP/ESL、Paradox 脚本、JSON 内容包、pak 覆盖
加载器 API	加载器提供了相应钩子	tModLoader ModItem/ModNPC、SMAPI、BepInEx 插件、UE4SS Lua、REFramework Lua、SKSE 插件
托管代码补丁	.NET/Mono/IL2CPP/Java 游戏没有适用于该构想的 API	Harmony 前缀／后缀／转译器、MonoMod、Mixin
原生钩子	C/C++ 引擎没有加载器	代理 DLL（dinput8/version/winmm）+ MinHook/SafetyHook、特征码扫描
重新实现／反编译／重编译	需要完全控制，或针对复古主机	N64 反编译项目、N64Recomp、XenonRecomp、IW4L 风格的重写项目（读取用户自己的游戏文件）
混搭／直通	同时运行两款游戏	mashup-mods 技能

开始构建前，将选定的路线及理由写入 MODLOG.md。

3. 实验环境设置（安全网）

• 首次启动安装了模组的游戏前，运行 um backup create "<saves folder>" --name <game>-saves（路径来自 um scan）。如果要更改设置，也请备份配置／配置文件文件夹。
• 如果加载器支持，请使用单独的实验配置或存档文件夹（tModLoader -tmlsavedirectory、MO2 配置文件、世界或场景副本）。脚本化录制会毁掉测试世界， 因此请保留一份干净副本，并在每次录制前恢复。
• 使用指定客户端尺寸的窗口模式（通过注册表／ini 设置，参见 game-automation），确保截图和点击 坐标保持稳定。
• 将反编译代码和提取的资源放在仓库之外（例如 ~/<game>-decomp），并将所有衍生数据加入 gitignore。切勿提交游戏文件。

4. 查阅权威来源

直接阅读代码和数据，不要猜测引擎的行为。reverse-engineering 技能介绍了相关工具：

• 反编译：ILSpy/ilspycmd、Cpp2IL、Vineflower、通过 MCP 使用 Ghidra/IDA；
• 导出数据：genieutils、xEdit、UndertaleModTool、FModel；
• 检查运行状态：UnityExplorer、UE4SS 实时查看器、REFramework、Cheat Engine。

将确切名称和 ID 记录在 MODLOG.md 中。既要检查可执行文件强制执行的规则，也要检查数据文件中的内容。 在 AoE2 中，数据文件可以容纳第 64 个文明，但文明选择器只会列出可执行文件中硬编码在表格里的文明，因此该模组替换了一个槽位，而不是新增文明。

5. 先完成垂直切片

先用占位美术资源，将一个物品、单位或武器从头到尾实现。定义它、启动游戏，并通过日志和实际查看的截图证明它确实出现且可用。之后再扩展。每完成一个可用步骤，就提交到模组自己的 git 仓库。

6. 资源（fal-assets 和 asset-pipeline 技能）

先研究游戏自身的资源：尺寸、调色板、轮廓、摄像机角度、朝向、帧布局。然后使用 um fal 生成。每次调用都会记录在 fal_manifest.jsonl 中。使用 um sprite / um render3d 转换为引擎实际加载的格式。

• **确保多个角度和帧之间保持一致：**生成一个概念图，通过 um fal model3d 将其转换为 3D， 然后从游戏摄像机的视角渲染各个朝向（um render3d --preset aoe2）。
• **像素画游戏：**在纯色背景或透明背景上生成，抠出图像后，再按帧尺寸进行一次最近邻缩放。

7. 在真实游戏中验证（构建预言机）

正在运行的游戏才是预言机；你对代码的解读不是。

• 让测试可重复：使用模组侧聊天命令或时间线、带触发器的场景，或测试世界。 使用 um win launch/drive 驱动启动 → 菜单 → 场景流程，并通过 um win shot 和游戏日志文件检查。
• 使用缩小后的截图（--scale 0.33）以节省 token；点击时将坐标乘回原始比例。
• **断路器：**如果同一故障重复出现 3 次，就停止。记下已知信息，然后更换方法或询问用户。
• 常见日志位置：

游戏 / 加载器	日志
tModLoader	client.log
BepInEx	BepInEx/LogOutput.log
UE4SS	UE4SS.log
Unity	AppData/LocalLow/<company>/<product>/ 中的 Player.log
SKSE	Documents/My Games/<game>/SKSE/
Minecraft	logs/latest.log

8. 制作展示视频（showcase-video 技能）

编排好拍摄流程，让它可以重复执行。使用游戏自带音频录制游戏窗口（um win record）。 从联系表中挑选片段，然后剪辑成 20-45 s 的视频，添加单行标题并淡出 （um video compile）。

9. 打包并发布（publish-mod 技能）

运行 um publish check <mod> --game "<install>"。编写包含安装步骤的 README。注明工具、加载器和 fal 生成素材的来源，并如实说明这是用 AI 构建的。不要打包任何游戏文件。

10. 留下一份实地笔记（share-field-notes 技能）

将 MODLOG.md 整理成知识库笔记（um kb new ...，然后运行 um kb check）。内容涵盖：

• 精确版本；
• 操作路径；
• 引擎的实际行为；
• 验证方式；
• 编号列出的注意事项。

获得用户同意后，提交 PR（um kb pr <note> --yes）。即使模组尚未完成也要这样做：记录在案的死胡同能为下一个 Agent 节省数小时。

硬性规则

• **所有权。**只能为用户拥有的游戏制作模组。
• **在线游戏。**仅在单人／离线模式下，或用户控制的服务器上操作。绝不接触受反作弊保护的在线游戏客户端（EasyAntiCheat、BattlEye、Vanguard、官方服务器上的 VAC、Ricochet、ACE）。绝不为多人游戏编写作弊工具（自瞄、ESP、加速外挂）。
• **不得绕过。**绝不绕过反作弊、DRM 或所有权检查。如果 Steam 库中没有免费的 tModLoader 应用，tModLoader 会拒绝启动：应将其添加到库中，而不是修改检查代码。如果游戏需要关闭反作弊才能使用模组，只能使用官方离线启动选项。
• **不得再分发。**不要打包游戏文件、反编译源码或提取的素材。只打包自己的代码和素材，或在用户自己的安装目录中运行的补丁与转换器（“自备游戏文件”）。
• **先备份。**修改存档、配置档或游戏文件夹前，运行 um backup。在 MODLOG.md 中记录恢复路径。
• 进程规范。
  • 按精确 PID 终止进程（um win kill <pid>）。绝不要使用 pkill -f（它会匹配你自己的 Shell），也不要使用通配符终止进程。
  • 绝不要阻塞游戏主线程（例如在模组中等待 ffmpeg）。
  • Steam 拒绝重新启动时，按 PID 清理崩溃报告程序（如 BugSplat）。
• 用户的设备。
  • 驱动输入会接管用户的鼠标和键盘。在用户使用电脑时，长时间自动操作前，检查 um win drive --proc X idle 并征得同意。
  • 将加载器安装到游戏文件夹、修改注册表或图形设置、删除任何内容或发布前，都要先征得同意。

参考资料

• references/engines/：
  • 大型引擎：unity.md、unreal.md、godot.md、source.md、native.md；
  • 引擎家族和框架：dotnet-xna.md（Terraria、Stardew、Celeste）、bethesda.md、 big-frameworks.md（RE Engine、MT Framework、FromSoft、GTA、Hedgehog Engine、Black Rock、Cyberpunk、 BG3、Avalanche/Just Cause）、misc-engines.md（GameMaker、RPG Maker、Ren'Py、Paradox、Doom、HTML5、LÖVE、 Java、Dwarf Fortress）、zengin.md（Gothic 1/2：Daedalus 脚本、Union、GD3D11）；
  • 单款游戏和复古游戏：bannerlord.md（Mount & Blade II：模块、XML/XSLT、C# SubModules、Harmony）、 minecraft.md、genie-aoe2.md、isaac.md（Binding of Isaac：Lua 模组、REPENTOGON、anm2、控制台）、 retro-decomp.md。
• references/case-studies.md：Terraria、AoE2 和 Minecraft × GTA V 的端到端案例，涵盖每项不明显的事实。
• 知识库（仓库根目录中的 knowledge/；um kb search）：来自众多 Agent 的实地笔记，按游戏和技术分类。
• references/safety.md：相关规则及其原因、反作弊和法律合规注意事项。