Universal Modder 跨游戏混作(Mashup)实战:把一款游戏装进另一款
Universal Modder 跨游戏混作(Mashup)实战:把一款游戏装进另一款
Universal Modder 的 mashup-mods 技能解决一类非常具体的需求:把 A 游戏的内容、机制或运行时,装进 B 游戏——"Minecraft 出现在 Elden Ring 里""在 MW2 里滑板"。本文以该技能文档为主干,完整拆解动手前的七步规划流程、五种可落地的混作模式(内容移植 / 双游戏直通 / 反编译库化 / 重实现再融合 / 无头规则重实现)、桥接契约与护栏,并用仓库自带的 examples/minecraft-gta5-passthrough 真实代码逐条印证。读完你能独立判断"这条混作该走哪条路线"、写出 CONTRACT.md、挑出第一块可验证切片,并用仓库里的假宿主(fake host)在没有真实游戏的情况下把桥打通。
先回答"用户到底想要什么":动手前的七步
技能文档 SKILL.md 开篇给出一条总原则:2026 年 9 月那一波走红的 AI 混作(MW2 滑板、Minecraft 进 Skyrim、Elden Ring × Mario 64、Minecraft 里的 Black Ops 2)都只用了少数几种模式。核心方法论是——先规划,再写代码;这类项目失败于"漂移"(在错误猜测上自信地往下建),而不是缺代码。因此所有模式之前,必须先走完下面七步。
- 搞清楚用户从"客游戏(guest)"那里到底要什么。 是要它的真实行为(物理、物品栏、战斗),还是只要它的外观、或某一个机制?不确定就问。这个答案决定了客游戏是否必须真正跑起来,以及哪条路线最轻。
- 给最近的混作路线命名。 仓库把它拆成七条路线,见 choosing-a-mashup-route.md。注意 "passthrough" 这个词本身是模糊的——它覆盖了三种完全不同的构建方式(状态交换、一张合成画面、宿主自绘客网格)。
- 在案例索引里找到最近的既有项目。 mashup-cases.md 按路线、版本、谁拥有玩家、单位、传输方式建了索引。找到最接近的一行后,若其仓库可读,就读它的 README 和设计文档,并在自己跑通之前,把读到的东西当作"作者自述"对待。同时对两款游戏、两款引擎各跑一次
um kb search——其他 Agent 关于任一端的笔记在这里同样适用。 - 如果是"重建客游戏"而非"运行客游戏"(在真宿主里重建它的引擎或某机制),读 rebuilt-guest-engine-inside-a-host.md,搞清重建部分应该跑在哪里、如何对原始做校验。
- 只要状态跨越两个游戏/引擎/进程,就把契约写下来: 谁拥有玩家、控制如何交回、单位与坐标轴、每条通道满了/迟到了怎么办、协议版本与字节序、生命周期。统一放在
docs/CONTRACT.md,模板见 bridge-contracts-ownership-units-and-lifecycle.md。 - 决定"怎么知道它真的跑了"。 在加功能之前,先为你的路线挑一块"第一切片"和能证明它的检查。首切片表见 choosing-a-mashup-route.md,各类校验器(oracle)见 oracles-how-agents-know-a-mod-works.md。
- 把计划记下来,并在动工前告知用户。 把选定的路线和理由写进
MODLOG.md(mod-any-game技能本就要求)。同时告诉用户:每位玩家要自备/安装哪些东西、在哪个操作系统上、你的方案与最近的既有项目差在哪里。
七条路线(供第 2 步对照,摘自 choosing-a-mashup-route.md):
| 路线 | 什么在跑 | 跨了什么 | 每个玩家要自备 |
|---|---|---|---|
| 活直通(状态交换) | 两款真实游戏 | 位置、碰撞、命中、事件 | 两款游戏 + 两个 loader |
| 帧合成(画面传输) | 两款真实游戏 | 色彩+深度+HUD 图、一个相机姿态 | 两款游戏 |
| 原生几何转移 | 宿主自绘客网格 | 网格、图集、碰撞 | 两款游戏 |
| 共享中立模拟 | 独立服务器,游戏是查看器 | 中立状态与输入意图 | 一个查看器 |
| 引擎重建 | 一个读自有数据的重建引擎 | 无;单进程 | 原作文件 |
| 资产/地图转换 | 只有宿主 | 离线转换出的文件 | 宿主(+一份源副本) |
| 真宿主内重建客引擎/机制 | 真宿主 + 重建的客引擎或单一机制 | 重建部分的状态(经 DLL 或 worker 进程) | 宿主 + 一份客数据副本 |
该笔记强调:大多数已发布项目是混用路线——"帧合成负责画面 + 状态交换负责碰撞与战斗"是最常见的组合。选路时按序回答四个问题(真实行为还是只要外观?谁拥有玩家、控制如何交回?宿主能否自绘客几何?每位玩家要自备/运行什么、在哪个 OS?),并从第一天就记下精确构建版本——有的宿主必须钉死到某一可执行文件版本(例如 examples/minecraft-gta5-passthrough 就是在 GTA V Legacy build 3889 上验证的)。
模式一:移植内容(最轻)
把敌兵、武器或方块类型作为宿主的新内容带进宿主,模仿客游戏。例如"给黑暗之魂加了爬行者""Minecraft 方块作为 Elden Ring 的物品"。
- 从客游戏的真相源读取行为:反编译,或读 wiki 上的精确数值(速度、计时器、伤害),再用宿主的 MOD API 重实现(宿主 AI 状态机、宿主投射物)。
- 资产绝不直接拷贝客文件进 MOD。 应在运行时或安装时从用户自己的安装转换(一个转换脚本),或用 fal 重造"看起来像"的替代物。
- 无 IPC、廉价且健壮,任何带 loader 的宿主都能做。
- 工作过的转换器:把 Bloons TD 6(Unity 6)资产转成私有的 Minecraft 资源包,见 bloons-td-6-in-minecraft.md。
模式二:双游戏直通(passthrough,两个游戏同时跑)
这是最重也最出彩的路线。以仓库里 Minecraft × GTA V 为标杆,标准架构分六步:
- 客进程(如带 Fabric MOD 的 Minecraft,或一个无头重实现):跑模拟,每 tick 发布状态——玩家附近的实体/方块,或一个渲染层。
- 传输,全走
127.0.0.1:- 状态:共享内存环形缓冲(
CreateFileMapping)或 UDP/命名管道; - 控制:JSON 行或 HTTP;
- GPU 帧:DXGI 共享句柄(
CreateSharedHandle/OpenSharedResource1+ keyed mutex)、Vulkan 外部内存或 Spout2。实践中各帧桥(本仓库 GTA V 示例、以及社区里的 Elden Ring / MHW 桥)都会把像素读回 CPU 再经共享内存拷贝——这跨 GPU、跨 Wine 边界都能用。上传要留预算(见 frame-compositing-depth-and-pose-sync.md)。
- 状态:共享内存环形缓冲(
- 宿主注入: 宿主侧插件(SKSE/xNVSE/UE4SS/REFramework/ReShade addon)把客几何画在宿主的渲染通道内部——用宿主的视口投影矩阵(用 RenderDoc 找)和深度缓冲,或生成宿主原生对象让宿主光照/阴影生效。
- 反向通道: 宿主玩家附近的碰撞(射线投射,或导出的近旁网格)以实心方块/collider 形式送回客游戏。输入同一时刻只路由给一个进程。
- 同步: 每条消息带时间戳,容忍两个帧率差异,一侧挂掉时有看门狗。姿态只连同它的像素一起发布,并在宿主侧配对;宿主相机要在"当前时刻"读。碰撞分方向、分消费者,见 collision-and-combat-bridging.md。
- 从小开始: 先在 A 进程画一个立方体、在 B 里出现在正确位置;再逐帧对位置;然后上碰撞;最后才是真实内容。
实战印证:Minecraft 装进 GTA V
上面六步在仓库里有完整落地,代码在 examples/minecraft-gta5-passthrough,每条经验写在 minecraft-passthrough.md。真实组件映射如下:
GTA V (story mode) Minecraft 26.3 + Fabric (mc/)
MCPassthrough.asi (gta/src) dev.rehan.passthrough
script.cpp -- WebSocket 127.0.0.1:25599 --> HostLink: cam / ground / key / slot / cmd
<------------------------------- explosion events
compositor.cpp (ReShade add-on) <-- 共享内存 FrameExporter: world RGBA + depth, overlay RGBA
MCPassthrough.fx: 深度测试 + overlay "Local\MCPassthroughFrame"
- Minecraft(Fabric MOD): 通过
127.0.0.1上的 WebSocket 从宿主取相机、地面、输入(见 HostLink.java)。每帧把世界色彩+深度、以及独立的"手/HUD"叠加层,写进命名共享内存(见 FrameExporter.java 与 SharedMemory.java)。 - GTA(ScriptHookV ASI + ReShade addon):
- 每帧发出 GTA 渲染所用相机、玩家脚位与朝向(
cam); - 在玩家四周 40 方块内、每帧 160 根探针探地面,作为
ground送出,MOD 用屏障方块把它们填满,让方块/怪/物品能落在 GTA 世界里(见 script.cpp); - 用着色器把 Minecraft 色彩对 GTA 的反向 Z 深度做合成(见 compositor.cpp 与 MCPassthrough.fx);
- 把 Minecraft 的爆炸、箭、烟花命中,转成 GTA 的爆炸与子弹。
- 每帧发出 GTA 渲染所用相机、玩家脚位与朝向(
- 坐标映射: 1 米 = 1 方块。GTA
(x, y, z)→ MC(x, z + yOffset, −y);yaw = 180 − heading;pitch = −pitch。脚本自动选yOffset让地面落在整数方块上(F8 重新水平)。 - 延迟: Minecraft 的帧会被重投影到 GTA 相机上(先旋转、再用深度做完整 6-DoF)。测姿态延迟的办法是摆一个"一侧有、另一侧没有"的场景(一面金墙 vs 城市天际线)。
- 没装游戏就建好了大部分: 在宿主游戏装上之前,先对着一个假宿主(已知几何)和一个假 D3D11 "GTA"(跑真正的 compositor)把桥搭起来——正是 fakegta.cpp 与 fakehost.py 的角色。
- 什么没成: 把宿主游戏的手枪塞进 Steve 手里(瞄准相机和动画对不上);而"客武器 + 宿主特效"可以。
值得注意的实现细节:GTA 会把系统
dxgi.dll优先于文件夹里的代理加载,所以 ReShade 只能以ReShade64.asi身份装进游戏(由 ASI loader 加载)——这也是 install.sh 特意处理的一点。
模式三:把反编译作品库化
把某个反编译项目当库用:喂进碰撞与输入,返回角色状态与网格。例如把 Super Mario 64 反编译(libsm64)封装后嵌入 Garry's Mod——宿主把自己的碰撞喂进客模拟。任何反编译/重编译(见 retro-decomp.md)都可以这样包。用户自备 ROM 供资产用。
模式四:重实现再融合(最重,控制最强)
- IW4L: LLM 写出的 Rust 版 MW2 运行时(Bevy + wgpu),从用户安装读 MW2 的 FastFiles,把 D3D9 着色器翻成 WGSL。
- Skate 3 的 Rust 引擎: 对着一个静态重编译和一份 IDA 数据库当 oracle 建出来。
- 融合: 两者加一个 Minecraft Rust 重实现,塞进同一进程。滑板模拟是个 worker,接管 MW2 士兵;MW2 地图碰撞喂进滑板世界;磨栏杆来自可走碰撞的边缘;滑板骨骼被重定向到 MW2 骨架上。
- 让它跑起来的关键:
- 一个脚本化运行时当 oracle:
spawn; wait 2s; screenshot; dump,带阻塞动词、每次跑产出证据文件; - 一个证据日志(
context/artifacts/<日期>/<步骤>-FINAL|PART),原则是"不在 artifact 里的知识就等于不存在"; - 只做 owner 批准的端到端测试;
- 一次发布检查,在任何 push 前 grep 零售偏移与反编译器命名(
um publish check做的就是这类事,见 publish.py——它会匹配FUN_xxxx/sub_XXXX/ "Decompiled with" 等反编译器指纹); - 只在用户文件上跑的转换器;游戏资产永不入库。
- 一个脚本化运行时当 oracle:
- 度量与保真度: engine-recreation-measures-and-fidelity.md 讲每类重建如何度量、为什么脚本是保真度的一部分、以及别的 MOD 需要的 SDK 规则。
模式五:无头重实现客规则,宿主只做视图
宿主保持真游戏(它的武器、MOD、多人);只把客的规则重写成一份不 import 宿主任何东西的纯模拟。最适合"玩法即数字"的客游戏(塔防、卡牌、解谜、俯视角 2D、回合制),以及"绝不能被注入"的、带在线能力的客游戏。范例:Minecraft 里的 Bloons TD 6,见 bloons-td-6-in-minecraft.md。
- 模拟即真相源。 按客自己的步进率与单位跑(BTD6:60 步/秒、BTD6 单位)。游戏速度改的是"每个宿主 tick 的步数",永不改 dt。
- 只有一个帧映射函数在客单位与宿主坐标间转换(原点、缩放、轴翻转),服务端与客户端共用。
- 玩家必须触碰的东西做镜像实体。 宿主实体每 tick 从模拟复制位置,其受击/交互处理器转发进模拟;剥掉宿主本来会对它做的所有事——AI、重力、击退、药水、火、推挤。
- 高量级东西不做宿主实体(投射物、粒子)。每 tick 发一批生成记录,客户端跑同一份运动代码;特效与音效同样批处理,带上限。
- 每个 UI 按钮都是一条命令。 界面显示服务端快照、再发命令回去,于是每个动作都能脱离界面测试。
- 宿主特性喂给模拟,永不绕过模拟。 宿主武器/方块/药水变成模拟里的状态与伤害事件;什么都没有时,游戏必须能一模一样地打完(用无头跑校验)。
- 客资产来自一次跑在用户安装上的转换器,落到本地私有资源包;MOD 必须在资源包缺失时仍可用占位物玩。
- Oracle: 先无头引擎 bench(几秒、不启动宿主),再宿主侧 bench,见 oracles-how-agents-know-a-mod-works.md。
桥接契约:所有跨状态点都要写下来
技能文档第 5 步要求"状态一跨边界就写契约"。bridge-contracts-ownership-units-and-lifecycle.md 给出了七类契约字段与一份可直接套用的 docs/CONTRACT.md 模板:
# Bridge contract: <guest> inside <host>
Route: <passthrough | frame compositing | geometry transfer | rebuilt engine | ...>
Host: <游戏, 精确构建, loader+版本, OS / 翻译层+版本>
Guest: <游戏或引擎, 精确版本, loader+版本>
## Ownership
| System | Owner | 交接触发 | 如何交回 |
|---|---|---|---|
| 玩家移动 / 相机 / 碰撞(两向) / NPC / 伤害 / 物品栏 / 存档 / 菜单 / 过场 | ... |
## Units and axes
host_to_guest(x, y, z) = ...
## Channels
| 名称 | 类型 | 方向 | 速率 | 满了/迟到怎么办 |
## Protocol
Magic: ... Version: ... 字节序: ... 重启检测: ...
## Lifecycle
启动顺序 / 暂停 / 换图 / 死亡 / 断开 / 崩溃 / 卸载
## Not covered
...
几个来自既有项目的所有权与单位决策可作参照:SkyCraft 里 Minecraft 拥有移动,但家具/坐骑/处决把控制临时交回 Skyrim;GTA V 示例里步行时 GTA 拥有玩家、鞘翅飞行时 Minecraft 拥有;单位映射从 SkyCraft 的"70 宿主单位/方块"到 GTA V 的"1 米 = 1 方块"各不相同,务必把单位写进消息。传输侧常见策略:seqlock 快照(连续被替换的状态,写时计数为奇、读前读后各查一次)、有界队列(离散事件,显式丢弃行为)、填充字节环(变长数据如网格)、图像三缓冲、重启代(generation)(代变了就补发状态)。字节序要单独钉死——GalaxyCraft 宿主协议是小端 v10,而模拟机的 PowerPC 邮箱是大端 v5,很多显示列表负载本身已是大端、不能再翻。两侧要加同样的"编译期布局测试"(C 断言固定偏移、区域长度、结构体大小)。
怎么知道它真的跑了:Oracle 分层
技能文档反复强调"先规划 oracle,再写代码"。oracles-how-agents-know-a-mod-works.md 给出一张校验器表(按"最可能犯的错"挑最便宜的那个):
| Oracle | 抓什么 | 例子 |
|---|---|---|
| 往返(round trip) | 文件格式理解错 | 解码→编码→再解码,比对 |
| 轨迹回放 | 移植与原作不一致 | 喂 t 帧状态+动作,比对 t+1 |
| 脚本场景 + 你亲眼看截图 | 尺度、朝向、层级、"到底显没显示" | um win shot --scale 0.33 |
| 游戏日志 | 加载错误、缺资产 | tModLoader client.log 等 |
| 合成宿主 | 真游戏装上之前抓集成 bug | Minecraft × GTA 的假宿主 + 假 D3D11 |
| 测量场景 | 时序与同步 | 金墙 vs 天际线看一帧姿态领先 |
| 字节匹配构建 | 反编译错误 | 反编译回去得到同一 ROM |
| 无头引擎 bench | 规则/数据错、回归 | BTD6 纯 Java 模拟,javac 独跑 885 个测试 |
| 发布检查 | 别把不该发的发出去 | um publish check --game <安装目录> |
配套四条铁律:把整个循环自动化(一条命令回答"跑没跑起来");设断路器(约 3 次相同失败就停、记下已知、换思路);保 MODLOG.md 日志;如实记录 oracle 没覆盖到的部分。其中"合成宿主能跑"≠"游戏里能跑",假宿主只能用来快速迭代,收尾前必须真跑一次。
护栏
技能文档的 Guardrails 在收尾处再次强调,任何混作都适用:
- 离线、单机、或用户自跑的服务。 永不接入真游戏的官方在线服务。
- 客侧一切来自用户自己的安装或 dump。 发布的是代码与转换器,不是资产(
um publish check --game)。 - 带在线能力的客游戏(账号、合作、排行榜)只从文件离线读:MOD 或工具绝不启动、补丁或 hook 它。
- 诚实说明哪些是 AI 建的。 没 AI 参与的创建者被公开点名过。
- 诚实说明验证到什么程度:README、设计文档、合成同伴、一个绿测试都不等于一次真跑,证据等级见 evidence-levels-for-mashup-claims.md——只有"真游戏跑了这个构建且有人看过"这一档才支撑
status: working,且仅限实际玩过的场景。
发布前的最后一道关
在打包安装器或 loader 之前,读 installers-load-order-and-loaded-code-checks.md(加载代码检查、加载顺序、钉死的下载、精确卸载)。发布侧由 publish.py 实现:um publish check ./MyMod --game "C:\...\Steam\...\Terraria" 会同时扫源码里的反编译器指纹(FUN_xxxx / DAT_xxxx / sub_XXXX、// Decompiled with、ILSpy/dnSpy 头)和针对指定游戏安装做资产核对——这正是模式四要求的"push 前 grep 零售偏移与反编译器命名"的落地。
小结
mashup-mods 技能的骨架可以压缩成一条决策链:先问用户要客游戏的行为还是外观 → 用七条路线命名方案 → 在 mashup-cases.md 里找最近先例并用 um kb search 补两端笔记 → 为每个跨状态点写 CONTRACT.md → 挑一条路线的首切片和一个 oracle → 记下路线再动手。五种模式按"最轻能交付想法的那条"递进:内容移植(无 IPC)→ 双游戏直通(画面+状态,最出彩也最重)→ 反编译库化 → 重实现再融合 → 无头规则重实现。仓库自带的 Minecraft × GTA V 示例 是直通路线的完整参照系——它的 WebSocket 相机通道、160 根地面探针、ReShade 反向 Z 深度合成、以及"没装游戏就用 fake host 先打通"的工程方法,可以直接照搬到其它宿主。记住贯穿全文的一句话:这些项目不是败在缺代码,而是败在漂移——把契约和 oracle 写在前面,漂移才有地方可拦。