mashup-mods

混搭：将一个游戏放进另一个游戏

2026 年 9 月，一波由 AI 制作的混搭作品走红：在 MW2 中滑滑板、在 Skyrim 中玩 Minecraft、 在 Elden Ring 和 Mario 64 中玩游戏，以及在 Minecraft 中玩 Black Ops 2。它们采用了少数几种模式。选择能实现创意的最轻量方案，并在编写代码前规划好验证方法：这些项目失败的原因是偏离目标，而不是缺少代码。

选择模式之前

在编写任何混搭代码之前，请先完成以下步骤。这里提到的路线、模式和项目均来自现有的混搭作品。先从最接近的项目入手，或者另行设计，并写下原因。末尾的防护措施始终适用。

1. 弄清楚用户想从客体游戏中获得什么。 是它的真实行为（物理、物品栏、战斗），还是只要它的外观或某个机制？如果不清楚，请询问。答案决定客体游戏是否必须运行，以及实现创意所需的最轻量路线。
2. 指出最接近的混搭路线。 knowledge/techniques/choosing-a-mashup-route.md 将混搭分为七条路线。单说“直通”含义不明确：它涵盖三种不同的构建方式（状态交换、合成画面、由宿主绘制客体网格）。
3. 在 references/mashup-cases.md 中找到最接近的先例项目（路线、版本、玩家归谁控制、单位、传输方式）。如果能访问其代码仓库，请阅读 README 和设计文档。在亲自运行之前，应将读到的内容视为创作者的报告。还要运行 um kb search，分别搜索两款游戏和两款引擎；其他 Agent 对任一游戏的记录也适用于此处。
4. 如果是重建客体，而非运行客体（在真实宿主内部重建客体的引擎或某种机制），请阅读 knowledge/techniques/rebuilt-guest-engine-inside-a-host.md，了解重建部分应在哪里运行，以及如何与原版进行核对。
5. 在状态跨越两款游戏、两个引擎或两个进程时，写明约定： 谁控制玩家，以及控制权如何交还；单位和坐标轴；每个通道及其满载或延迟时的处理方式；协议版本和字节序；生命周期。将其写入 docs/CONTRACT.md；参见 knowledge/techniques/bridge-contracts-ownership-units-and-lifecycle.md。
6. 确定如何判断它是否有效。 添加功能前，先为所选路线挑选一个初始切片，并确定能证明其有效的检查。参见 knowledge/techniques/choosing-a-mashup-route.md 中的初始切片表，以及 knowledge/techniques/oracles-how-agents-know-a-mod-works.md。
7. 记录计划，并在开始构建前告知用户。 按照 mod-any-game 技能的要求，将所选路线及原因写入 MODLOG.md。同时告知用户这些内容，并说明每位玩家需要拥有和安装什么（以及对应的操作系统），还要说明计划与最接近的先例项目有哪些不同。

之后，在发布安装程序或加载器之前，请阅读 knowledge/techniques/installers-load-order-and-loaded-code-checks.md（已加载代码检查、加载顺序、固定下载版本、精确卸载）。

模式 1：移植内容（最轻量）

将敌人、武器或方块类型作为新的宿主内容加入宿主，模仿客体内容。 示例：“Claude 为 Dark Souls 添加了苦力怕”、将 Minecraft 方块做成 Elden Ring 物品。

• 从权威来源读取客体内容的行为：反编译，或查阅 wiki 中的精确数值（速度、计时器、伤害）。在宿主的 Mod API 中重新实现（宿主 AI 状态机、宿主投射物）。
• 资源： 切勿将客体游戏的文件复制到你的 Mod 中。应在运行时或安装时从用户的安装目录转换资源（使用转换脚本），或用 fal 重新制作相似外观。
• 这种方式成本低、稳定可靠，且不需要 IPC。只要宿主有加载器，就能使用。
• 已验证的转换器：将 Bloons TD 6（Unity 6）资源转换为私有 Minecraft 资源包，参见 knowledge/games/minecraft/bloons-td-6-in-minecraft.md 和资源管线第 6 节。

模式 2：透传（同时运行两款游戏）

chasm 对 Minecraft-in-Skyrim 的描述是：“Minecraft 和 Skyrim 同时运行，你要分别为两者制作一个 mod，让它们能够通信。然后将你想要的内容透传到渲染器的正确位置，并把碰撞数据等内容反馈给 Minecraft。” 源代码现已公开，名为 SkyCraft。在 0.1.2 中，Fabric mod 会导出 Minecraft 的网格和图集，而 SKSE 插件会在 Skyrim 自己的 D3D11 世界渲染阶段内绘制它们（使用原生深度、雾效、光照和捕获的太阳阴影）；只有手部、HUD 和屏幕会被捕获为图像。Skyrim 的 Havok 形状会以三角形和体素的形式传回。LibertyCraft 基于它分叉开发，用于 GTA IV，并保留了来宾端。以下设计是这种实现方式的标准方案。

1. 来宾进程（例如使用 Fabric mod 的 Minecraft，或无头重实现）：运行模拟，并在每个 tick 发布状态。这些状态可以是玩家附近的实体和方块，也可以是渲染层。
2. 传输，全部通过 127.0.0.1：
   • 状态：共享内存环形缓冲区（CreateFileMapping），或 UDP／命名管道；
   • 控制：JSON 行或 HTTP；
   • GPU 帧：DXGI 共享句柄（CreateSharedHandle / OpenSharedResource1 + keyed mutex）、Vulkan 外部内存或 Spout2。实际上，帧桥接方案（本仓库的 GTA V 示例、NewVegasCraft、CrossOver 的 Elden Ring / MHW 桥接方案）都会先将像素读回 CPU，再通过共享内存复制；这种方式也适用于不同 GPU 之间以及跨越 Wine 边界的场景。请预留上传所需的预算（见 knowledge/techniques/frame-compositing-depth-and-pose-sync.md）。
3. 主机注入：主机端插件（SKSE/xNVSE/UE4SS/REFramework/ReShade addon）会在主机的渲染阶段内绘制来宾的几何体。它会使用主机的视图投影矩阵（可通过 RenderDoc 查找）和深度缓冲区，或生成主机原生对象，以应用主机的光照和阴影。Skyrim 片段中的 Steve 使用了 Skyrim 的光照，这说明应将其集成到场景中，而不是作为平面叠加层。
4. **反向通道：**玩家附近的主机碰撞信息（射线检测或导出的附近网格）会作为实心方块或碰撞体发送给来宾。输入一次只路由到一个进程。
5. **同步：**为每条消息添加时间戳，容忍两边的帧率差异，并在任一侧退出时使用看门狗。仅在有对应像素时发布姿态，并在主机端将二者匹配；在当前时间读取主机摄像机。碰撞按方向和使用方区分：见 knowledge/techniques/collision-and-combat-bridging.md。
6. **从小处着手：**先让进程 A 中的立方体出现在进程 B 的正确位置。然后逐帧同步位置，再实现碰撞，最后才加入真实内容。

公开提供的桥接插件模板：chasm-bridge-fnv（精简的 xNVSE 插件，使用文件投放／HTTP 传输，并支持数据驱动的操作）。examples/terraria-tmodloader/reference/ 中的 Terraria Agent 桥接方案采用了相同思路。

实例：在 GTA V 中运行真正的 Minecraft

代码：examples/minecraft-gta5-passthrough。所有课程：knowledge/games/gta-v/minecraft-passthrough.md。

• **Minecraft（Fabric 模组）：**通过 WebSocket 从宿主获取摄像机、地面和输入，连接地址为 127.0.0.1。每帧都会将世界颜色和深度，以及单独的手部/HUD 叠加层写入命名共享内存。
• GTA（ScriptHookV ASI + ReShade 插件）：
  • 发送 GTA 的摄像机，以及玩家下方的地面（作为屏障方块）；
  • 在着色器中，将 Minecraft 的颜色与 GTA 的反向 Z 深度合成；
  • 将 Minecraft 的爆炸、箭矢和烟花命中效果转换为 GTA 的爆炸和子弹。
• **映射：**1 米 = 1 个方块。GTA (x, y, z) → MC (x, z + offset, −y)；偏航角 = 180 − heading； 俯仰角 = −pitch。
• **延迟：**将 Minecraft 的画面重新投影到 GTA 的摄像机视角，先处理旋转，再使用深度实现完整的 6 自由度。 在其中一侧会绘制某些内容、另一侧不会的场景中测量姿态延迟（例如金色墙壁与天际线）。
• **未运行游戏也能构建：**大部分内容都是在宿主游戏尚未安装时构建的，使用已知几何体的 虚拟宿主，以及运行真实合成器的虚拟 D3D11“GTA”。
• **未奏效的尝试：**让宿主游戏的枪出现在 Steve 手中（瞄准摄像机和动画不匹配）。 使用客体武器搭配宿主效果则奏效。

模式 3：将反编译项目嵌入为库

libsm64 将 Super Mario 64 的反编译项目转换为库：输入碰撞和操作，就会返回 Mario 的状态和网格。G64 将其嵌入 Garry's Mod；宿主将自身的碰撞数据输入客体模拟。任何反编译/重新编译项目（参见 skills/mod-any-game/references/engines/retro-decomp.md）都可以用这种方式封装。用户需自行提供 ROM 以获取资源。

模式 4：重新实现，然后融合（工作量最大，控制力最强）

• **IW4L：**由大模型编写的 Rust MW2 运行时（Bevy + wgpu）。它读取用户安装目录中的 MW2 FastFiles，并将 D3D9 着色器转换为 WGSL。
• **Skate 3 Rust 引擎：**以静态重新编译项目和 IDA 数据库为参考构建。
• **混合项目：**在一个进程中融合两者，并加入 Minecraft 的 Rust 重新实现。滑板模拟作为工作线程接管 MW2 士兵。MW2 地图碰撞数据输入滑板世界。磨杆来自可行走碰撞边缘。滑板骨骼会重定向到 MW2 骨架。
• 成功的关键：
  • 可脚本化运行时作为参考：spawn; wait 2s; screenshot; dump，包含阻塞式动词，并为每次运行生成证据文件。
  • 证据日志（context/artifacts/<date>/<step>-FINAL|PART）。“未记录在产物中的知识并不存在。”
  • 仅运行经负责人批准的端到端测试。
  • 发布检查：在每次推送前搜索零售版偏移量和反编译器名称（um publish check 会执行类似检查）。
  • 转换器直接处理用户的文件；绝不提交游戏资源。
• 衡量指标与保真度：knowledge/techniques/engine-recreation-measures-and-fidelity.md 介绍了如何衡量各类重建项目、脚本为何也是保真度的一部分，以及其他模组需要遵循的 SDK 规则。

模式 5：无头重实现客体的规则，让宿主仅作为视图

宿主仍是真正的游戏（包括其武器、模组和多人游戏）；只有客体的规则会被重写， 成为不导入宿主任何内容的纯模拟。最适合玩法由数字构成的客体（塔防、卡牌、解谜、俯视角 2D、回合制），以及完全不能或不应运行的客体 （受反作弊保护的客户端，或没有离线模式的客体）。示例：在 Minecraft 中游玩 Bloons TD 6 （knowledge/games/minecraft/bloons-td-6-in-minecraft.md）。

• 模拟是事实来源。 按客体自身的步进速率和单位运行（BTD6：每秒 60 步， BTD6 单位）。游戏速度只改变每个宿主 tick 的步数，不改变 dt。
• 使用一个帧映射函数在客体单位和宿主坐标之间转换（原点、缩放、轴翻转）， 供服务器和客户端共用。
• 为玩家必须接触的对象创建镜像实体。 每个 tick 都从模拟中复制位置的宿主实体，其受伤／交互处理程序会将操作转发给模拟。移除宿主原本会对它们执行的所有行为：AI、重力、击退、药水、燃烧、推挤。
• 高数量对象不创建宿主实体（投射物、粒子）。每个 tick 发送批量生成记录，并在客户端运行相同的移动代码。效果和音效也用相同方式批处理，并设置上限。
• 每个 UI 按钮都是一条命令。 屏幕显示服务器快照并发送命令，因此每项操作都能脱离屏幕单独测试。
• 宿主功能只能馈入模拟，不能绕过模拟。 宿主武器、方块或药水会变成模拟状态和伤害事件；如果没有这些功能，游戏必须完全相同地运行（通过无头运行检查）。
• 客体资源由转换器从用户自己的安装文件中提取，放入本地私有资源包；缺少资源包时，模组仍必须能用占位内容游玩。
• **验证基准：**先运行无头引擎基准测试（耗时数秒，无需宿主），再运行宿主侧基准测试（参见 knowledge/techniques/oracles-how-agents-know-a-mod-works.md）。

安全准则

• 仅限离线、单人游戏，或由用户自行运行的服务器。绝不连接到真实游戏的官方在线服务。
• 客体侧的所有内容都来自用户自己的安装文件或转储文件。发布代码和转换器，不发布资源 （um publish check --game）。
• 具备在线功能的客体（账号、合作游戏、排行榜）只能在用户自行启动的离线会话中启动并挂钩（离线模式，或阻止其联网），且绝不能在反作弊运行时操作。挂钩的进程在整个运行期间都必须保持离线：退出该进程，并在联网前以未修改状态重新启动。Setup 和 anti_cheat 中的说明会明确这一点。如果读取离线文件就足够，则不挂钩进程仍是更安全的做法。无法在离线时关闭反作弊的客户端绝不能挂钩（skills/mod-any-game/references/safety.md）。
• 如实说明哪些内容由 AI 构建。曾有创作者因未如实说明而遭到公开批评。
• 如实说明验证了哪些内容：README、设计文档、模拟对等端或通过的测试，都不等同于真实运行（knowledge/techniques/evidence-levels-for-mashup-claims.md）。