references/mashup-cases.md
# Mashup cases: routes, versions and ownership
A compact index of mashup projects. Use it to find the closest prior project before choosing a route.
Versions are the ones the projects named; check current releases. Creator claims are reports.
| Project | Route | Host / guest and versions | Player owner | Units | Transport |
|---|---|---|---|---|---|
| [SkyCraft](https://github.com/chasmlol/SkyCraft) 0.1.2 | passthrough + geometry transfer | Skyrim (SKSE, D3D11; AE path preferred) / Minecraft Fabric | Minecraft; Skyrim for furniture, mounts, kill-moves | 70 Skyrim units per block | named shared memory: snapshots, rings, actor tables, triple-buffered overlay |
| [LibertyCraft](https://github.com/mrborghini/libertycraft) | passthrough + geometry transfer (fork of SkyCraft) | GTA IV (a community scripting SDK, D3D9) under Wine on Linux / the forked Fabric mod | Minecraft; GTA for missions, cutscenes, cars | 1 m per block | SkyCraft v11 layout, new magic; seqlocks, bounded queues, byte rings, triple buffers; Windows/POSIX split |
| [ValCraft](https://github.com/LoAlCo/ValCraft) | passthrough | Valheim (BepInEx) / hidden Minecraft Fabric | Minecraft simulates the player | — | shared memory |
| [Killcraft](https://github.com/goonsn/Killcraft) | passthrough (SkyCraft's guest mod) | ULTRAKILL / hidden Minecraft running SkyCraft's Fabric mod | Minecraft (movement, health, inventory, combat) | 2 host units per block | — |
| [FalloutCraft](https://github.com/zeyvu/FalloutCraft) | passthrough (SkyCraft lineage) | Fallout 4 1.11.240, F4SE 0.7.9 / Minecraft 26.3 Fabric | — | — | — |
| Minecraft × GTA V (`examples/minecraft-gta5-passthrough`) | frame compositing + state | GTA V Legacy build 3889, ScriptHookV 3889.0, ReShade 6.8.0 / Minecraft 26.3 Fabric (author's test, Sept 2026) | GTA on foot; Minecraft in elytra flight | 1 m = 1 block; (x, y, z) → (x, z + yOffset, −y) | WebSocket 127.0.0.1 for gameplay; named shared memory for colour/depth/HUD |
| Wither Storm × GTA V | frame compositing + state (built from the GTA V example) | GTA V Legacy / Minecraft Java 1.20.1 with a large boss mod | — | 1 m = 1 block | the GTA V example's transport |
| [CrossOver bridge](https://github.com/justbustin/minecraft-crossover-bridge): Monster Hunter: World | frame compositing + state | MHW 15.23.00 (build 421810), CrossOver with a Direct3D-on-Metal layer, D3D11 / Minecraft 1.21.1 Fabric on native macOS | Minecraft drives movement and camera | damage = native HP | file-backed shared memory (8 MiB control + frame mapping) |
| CrossOver bridge: Elden Ring | frame compositing + state | ER app 1.17.1 (exe 2.7.1.0), CrossOver D3DMetal/D3D12 / Minecraft 1.21.1 Fabric | Minecraft drives movement and camera | damage = MC damage scaled by target max HP | as above, frame layout v2 with separate hand layer |
| [NewVegasCraft](https://github.com/Davozh/new-vegascraft) | frame compositing + state | Fallout: New Vegas Steam 1.4.0.525, xNVSE, ReShade (Proton setup) / Minecraft | Minecraft | 70 host units per block; exterior yOffset −34 | WebSocket + mapped file |
| [Minecraft × Half-Life](https://github.com/SawyerTheNerd/Minecraft-X-HalfLife) (GoldSrc) | geometry transfer | Half-Life client/server DLLs (OpenGL) / hidden Minecraft | Minecraft; Half-Life for ladders, use, noclip, death | 40 units per block; health ×5 | shared mapping (SkyCraft-derived name) |
| [GalaxyCraft](https://github.com/M0uidev/GalaxyCraft) | geometry transfer into an emulated game | Super Mario Galaxy 2 in Dolphin + native module / Minecraft Fabric | native Mario, or Minecraft with Mario hidden | GX display lists, KCL collision | 30,134,304-byte mapping; host LE v10, mailbox BE v5 |
| [Signet](https://github.com/kian-cx/signetprotocol) | shared neutral simulation | own server; Doom/Quake-style viewers are reimplementations; Minecraft via official-server gateway | server-authoritative, 20 Hz client prediction | neutral metres, 2.5D height grid | JSON over TCP |
| [Faith Runner](https://github.com/tnrjns/faith-runner) | subsystem transplant | Mirror's Edge movement in Rust → Skyrim (SKSE) and Minecraft (Java FFI) | the transplanted mechanic | 70 units per metre in Skyrim | static/dynamic C exports |
| ER Mario 0.3.8 | rebuilt mechanic, in-process | Elden Ring (me3) / libsm64 compiled into a Rust DLL; owner's US Mario 64 ROM for textures, audio and animations | Mario; a hidden native character follows for doors, menus, quests, deaths and saves | — | in-process C API |
| libsm64 | rebuilt mechanic as a library | any host that feeds collision and input (Garry's Mod, ER Mario) / Super Mario 64 decomp | Mario's state, stepped by the host | — | C library |
| [AC1 Movement Rewritten](https://github.com/Banned445/AC1-Movement-Rewritten) | subsystem recreation | Bevy greybox; owned AC PC install for models/animations; capsule fallback | the recreation | — | — |
| Diablo II movement in DevilutionX | subsystem transplant | DevilutionX (Diablo I) | Diablo I systems underneath | 256/8 fine units per tick at 20 ticks/s (v0.2) | in-process |
| [Garry's Redemption](https://github.com/codeByAlexff/garrys-redemption) | frame overlay window + state | RDR2 / hidden Garry's Mod | GMod for sandbox and player physics (design) | 0.01905 m per Source unit | versioned shared memory per direction |
| [BullySkate](https://github.com/Faiqie/BullySkate) | rebuilt guest subsystems in workers | Bully (ASI + scripting) / Skate physics and audio workers | the worker while skating | — | event-driven worker contracts |
| [IW4L](https://github.com/vladtrc/iw4L) 0.1.0-demo.2 | engine recreation | MW2 assets from the owned install / Rust, Bevy, wgpu; D3D9 shaders translated toward WGSL | the recreation (authoritative state, client prediction, snapshots) | — | one process |
| [benilla](https://github.com/samwhosung/benilla) | engine recreation | WoW 1.12.1 (build 5875) data / Rust, Bevy; extension point for extra Bevy plugins | the recreation | — | one process |
| [SK8-ENGINE](https://github.com/SK8-ENGINE/skate-3-rust-engine) | engine recreation (base of BullySkate, SkateGM, World of Skatecraft, the 2010 mashup) | owner's Skate 3 Xbox 360 data / Rust, Bevy; Lua SDK owns game policy | the recreation | — | one process |
| [HL2-RS](https://github.com/kvalls/hl2-rs) | engine recreation (standalone) | Half-Life 2 Source assets / Rust | the recreation | Source units converted at load | one process |
| CS:Craft | engine recreation + added Minecraft mode | CS:GO formats in Rust/Bevy, fixed 64 Hz simulation | the recreation | Source (x, y, z) → Bevy (x, z, −y), inches kept | one process; [IW4L](https://github.com/vladtrc/iw4L) "stitching" is a design |
| [World of Skatecraft](https://github.com/Kimmo3223/world-of-skatecraft) | rebuilt Skate engine inside a recreated host | [benilla](https://github.com/samwhosung/benilla) (recreated WoW 1.12.1 client, build 5875 data) + patched private-server core on Linux | the Skate engine while skating | — | in-process via extension entry point |
| [SkateGM](https://github.com/the-schwilliam/SkateGM) | rebuilt Skate engine inside a host | Garry's Mod / rebuilt Skate engine, owner Xbox 360 data | the Skate engine while skating | — | in-process native module + Lua |
| [Halo / MW2 Director](https://github.com/0xburn/halo-mw2-director) | engine recreation + map import + authored cinematic | IW4L (Rust MW2 runtime) on macOS Metal / owned Halo CE assets | IW4L (MW2 movement and rules) | — | one process |
| PipeLink | installer + converters around GTA SA × Skate × MW2 | GTA SA 1.0 US / Skate engine, IW4L | — | GTA Z-up → Skate Y-up | — |
| [Touhou HFR](https://github.com/vittorioromeo/th12_hfr) (adjacent: timing/render mod, not a mashup) | native timing and graphics patch | Touhou executables (TH08–TH20 targets by version) and New Classic | the original game | 60 Hz native vs substeps | proxy DLLs |
| [2010 Rust Rewrite Mashup](https://github.com/chasmlol/2010-rust-rewrite-mashup) | engine recreation + fusion | IW4L-derived runtime + Minecraft reimplementation | one runtime | 36 host units per block | one process |
## Using a row
1. Open the closest row's own repository and read its current README and design doc.
2. Copy its ownership and unit decisions into your `docs/CONTRACT.md`
(`knowledge/techniques/bridge-contracts-ownership-units-and-lifecycle.md`).
3. Note its known limits as your first test cases.
4. Never cite a row as proof that something works in game.
SKILL.md
---
name: mashup-mods
description: Build cross-game mashups and total conversions, the "Minecraft inside Elden Ring" or "skateboarding in MW2" kind. Covers passthrough mods (two games running at once and exchanging state, rendering and collision), porting one game's content or mechanics into another, embedding a decompiled game as a library, and clean reimplementations that read the user's own game files. Use when the user wants to combine two games, bring an enemy, mechanic or world from one game into another, or rebuild a game's runtime, or reimplement the guest's rules headless inside a real host.
---
# Mashups: putting one game inside another
In September 2026 a wave of AI-built mashups went viral: skateboarding in MW2, Minecraft inside Skyrim,
Elden Ring and Mario 64, Black Ops 2 inside Minecraft. They use a handful of patterns. Pick the lightest one
that delivers the idea, and plan the oracles before writing code: these projects fail by drifting, not by
lacking code.
## Before picking a pattern
Work through these steps before writing any mashup code. The routes, patterns and projects they point to
come from existing mashups. Start from the closest one, or design something else and write down why. The
Guardrails at the end always apply.
1. **Work out what the user wants from the guest game.** Its real behaviour (physics, inventory, combat),
or only its look or one mechanic? Ask if it isn't clear. The answer decides whether the guest has to
run at all, and which route is the lightest that delivers the idea.
2. **Name the closest mashup route.** `knowledge/techniques/choosing-a-mashup-route.md` sorts mashups
into seven routes. "Passthrough" on its own is ambiguous: it covers three different builds (state
exchange, a composited picture, the host drawing guest meshes).
3. **Find the nearest prior project** in `references/mashup-cases.md` (route, versions, who owns the
player, units, transport). If you can reach its repository, read its README and design doc. Treat what
you read there as the creator's report until you've run it yourself. Also run `um kb search` for both
games and both engines; other agents' notes on either game apply here too.
4. **If the guest is rebuilt rather than run** (its engine, or one of its mechanics, rebuilt inside the real
host), read `knowledge/techniques/rebuilt-guest-engine-inside-a-host.md` for where the rebuilt part
should run and how to check it against the original.
5. **Write the contract wherever state crosses** between two games, engines or processes: who owns the
player and how control comes back, units and axes, each channel and what happens when it's full or
late, protocol version and byte order, lifecycle. Keep it in `docs/CONTRACT.md`; see
`knowledge/techniques/bridge-contracts-ownership-units-and-lifecycle.md`.
6. **Decide how you'll know it works.** Before adding features, pick a first slice for your route and
the check that proves it. See the first-slice table in `knowledge/techniques/choosing-a-mashup-route.md`
and `knowledge/techniques/oracles-how-agents-know-a-mod-works.md`.
7. **Record the plan and tell the user before building.** Write the route you chose and why into
`MODLOG.md`, as the `mod-any-game` skill already asks. Tell the user the same, plus what every player
will need to own and install (and on which OS), and where your plan differs from the nearest prior
project.
Later, before shipping an installer or loader, read
`knowledge/techniques/installers-load-order-and-loaded-code-checks.md` (loaded-code checks, load order,
pinned downloads, exact uninstall).
## Pattern 1: port the content (lightest)
Bring an enemy, weapon or block type into the host as **new host content** that imitates the guest.
Examples: "Claude added creepers to Dark Souls", Minecraft blocks as Elden Ring items.
- Read the guest's behaviour from its source of truth: decompile or read the wiki's exact numbers (speeds,
timers, damage). Reimplement it in the host's mod API (host AI state machine, host projectile).
- **Assets:** never copy the guest's files into your mod. Convert them from the user's install at runtime or
install time (a converter script), or recreate lookalikes with fal.
- It's cheap and robust, with no IPC. It works with any host that has a loader.
- Worked converter: Bloons TD 6 assets (Unity 6) to a private Minecraft resource pack, see
`knowledge/games/minecraft/bloons-td-6-in-minecraft.md` and asset-pipeline section 6.
## Pattern 2: passthrough (two games at once)
chasm's description of Minecraft-in-Skyrim: *"minecraft and skyrim run at the same time and you make a mod
for both that lets them communicate. Then you passthrough the things you want into the renderer in the
right place and feed stuff like collision data back to minecraft."* The source is now public as
[SkyCraft](https://github.com/chasmlol/SkyCraft). In 0.1.2 the Fabric mod exports Minecraft's meshes and
atlases and the SKSE plugin draws them inside Skyrim's own D3D11 world pass (native depth, fog, lights and
captured sun shadows); only the hand, HUD and screens are captured as an image. Skyrim's Havok shapes come
back as triangles plus voxels. [LibertyCraft](https://github.com/mrborghini/libertycraft) forked it for GTA IV
and kept the guest side. The design below is the standard way to build it.
1. **Guest process** (e.g. Minecraft with a Fabric mod, or a headless reimplementation): runs the simulation
and publishes state every tick. That's entities/blocks near the player, or a rendered layer.
2. **Transport**, all on `127.0.0.1`, which doesn't keep out a web page in the player's browser (see "Networking"
in `skills/mod-any-game/references/safety.md`):
- state: a shared-memory ring buffer (`CreateFileMapping`) or UDP/named pipes;
- control: JSON lines or HTTP;
- GPU frames: DXGI shared handles (`CreateSharedHandle` / `OpenSharedResource1` + keyed mutex), Vulkan
external memory, or Spout2. In practice the frame bridges (this repo's GTA V example,
[NewVegasCraft](https://github.com/Davozh/new-vegascraft), the CrossOver Elden Ring / MHW bridges) all read pixels back to the CPU and copy them
through shared memory, which also works across GPUs and across a Wine boundary. Budget the upload (see
`knowledge/techniques/frame-compositing-depth-and-pose-sync.md`).
3. **Host injection:** a host-side plugin (SKSE/xNVSE/UE4SS/REFramework/ReShade addon) draws the guest's
geometry **inside the host's pass**. It uses the host's view-projection matrices (find them with
RenderDoc) and depth buffer, or spawns host-native objects so host lighting and shadows apply. The
Skyrim clip gave Steve Skyrim's lighting, which points to scene integration, not a flat overlay.
4. **Back-channel:** the host's collision near the player (raycasts, or exported nearby mesh) goes to the
guest as solid blocks or colliders. Input routes to one process at a time.
5. **Sync:** timestamps on every message, tolerance for the two frame rates, and a watchdog when one side
dies. Publish a pose only with its pixels and match them on the host; read the host camera at present
time. Collision is per direction and per consumer: see
`knowledge/techniques/collision-and-combat-bridging.md`.
6. **Start small:** a cube from process A drawn in B at the right spot. Then positions every frame, then
collision, and only then real content.
Bridge-plugin template in public: chasm-bridge-fnv (thin xNVSE plugin, file-drop/HTTP transport,
data-driven actions). The Terraria agent bridge in `examples/terraria-tmodloader/reference/` is the same
idea.
### Worked example: real Minecraft inside GTA V
Code: `examples/minecraft-gta5-passthrough`. Every lesson: `knowledge/games/gta-v/minecraft-passthrough.md`.
- **Minecraft (Fabric mod):** it takes camera, ground and input from the host over a WebSocket on
`127.0.0.1`. Each frame it writes world colour + depth and a separate hand/HUD overlay into named shared
memory.
- **GTA (ScriptHookV ASI + ReShade add-on):**
- it sends GTA's camera and the ground under the player (as barrier blocks);
- it composites Minecraft's colour against GTA's reversed-Z depth in a shader;
- it turns Minecraft explosions, arrows and firework hits into GTA explosions and bullets.
- **Mapping:** 1 metre = 1 block. GTA (x, y, z) → MC (x, z + offset, −y); yaw = 180 − heading;
pitch = −pitch.
- **Latency:** Minecraft's frame is re-projected onto GTA's camera, rotation then full 6-DoF with depth.
Measure the pose lag with a scene where one side draws something the other doesn't (a gold wall vs the
skyline).
- **Built without the game:** most of it was built before the host game was even installed, against a
fake host (known geometry) and a fake D3D11 "GTA" that runs the real compositor.
- **What didn't work:** putting host-game guns in Steve's hands (the aim cam and animations don't fit).
Guest weapons with host effects did.
## Pattern 3: embed a decomp as a library
libsm64 turns the Super Mario 64 decomp into a library: feed it collision and input, and it returns Mario's
state and mesh. G64 embeds it in Garry's Mod; the host feeds its collision into the guest sim. Any
decomp/recomp (see `skills/mod-any-game/references/engines/retro-decomp.md`) can be wrapped this way. The
user supplies their own ROM for assets.
## Pattern 4: reimplement, then fuse (heaviest, most control)
- **[IW4L](https://github.com/vladtrc/iw4L):** an LLM-written Rust MW2 runtime (Bevy + wgpu). It reads MW2's FastFiles from the user's install
and translates the D3D9 shaders to WGSL.
- **The Skate 3 Rust engine:** built against a static recomp and an IDA database as oracles.
- **The mashup:** fuses both, plus a Minecraft Rust reimplementation, in one process. The skate sim is a
worker that takes over the MW2 soldier. MW2 map collision feeds the skate world. Grind rails come from
walkable collision edges. Skate bones are retargeted onto the MW2 skeleton.
- **What made it work:**
- A **scriptable runtime as the oracle:** `spawn; wait 2s; screenshot; dump`, with blocking verbs and
evidence files per run.
- An **evidence journal** (`context/artifacts/<date>/<step>-FINAL|PART`). "Knowledge that is not in an
artifact does not exist."
- Owner-approved end-to-end tests only.
- A **publish check** that greps for retail offsets and decompiler names before any push
(`um publish check` does a version of this).
- Converters that run on the user's files; game assets never committed.
- **Measures and fidelity:** `knowledge/techniques/engine-recreation-measures-and-fidelity.md` covers how each
kind of rebuild is measured, why scripts are part of fidelity, and the SDK rules other mods need.
## Pattern 5: reimplement the guest's rules headless, keep the host as the view
The host stays the real game (its weapons, mods and multiplayer); only the guest's *rules* are rewritten,
as a pure simulation that imports nothing from the host. Best for guests whose gameplay is numbers
(tower defense, card, puzzle, top-down 2D, turn-based) and for guests you can't or shouldn't run at all
(an anti-cheat-protected client, or one with no offline mode). Example: Bloons TD 6 inside Minecraft
(`knowledge/games/minecraft/bloons-td-6-in-minecraft.md`).
- **The sim is the source of truth.** Run it at the guest's own step rate and units (BTD6: 60 steps/s,
BTD6 units). Game speed changes the number of steps per host tick, never dt.
- **One frame-mapping function** between guest units and host coordinates (origin, scale, axis flips),
shared by server and client.
- **Mirror entities for what the player must touch.** Host entities whose position is copied from the
sim each tick and whose hurt/interact handler forwards into the sim. Strip everything the host would
otherwise do to them: AI, gravity, knockback, potions, fire, pushing.
- **No host entity for high-volume things** (projectiles, particles). Send batched spawn records once per
tick and run *the same motion code* on the client. Batch effects and sounds the same way, with caps.
- **Every UI button is a command.** Screens display a server snapshot and send commands back, so each
action is testable without the screen.
- **Host features feed the sim, never bypass it.** Host weapons, blocks or potions become sim statuses
and damage events; with none of them, the game must play out identically (check with a headless run).
- **Guest assets** come from a converter run on the user's own install into a local, private resource
pack; the mod must stay playable with placeholders when the pack is missing.
- **Oracles:** the headless engine bench first (seconds, no host), then host-side benches (see
`knowledge/techniques/oracles-how-agents-know-a-mod-works.md`).
## Guardrails
- Offline, single-player or servers the user runs. Never network into the real games' official online
services.
- Everything guest-side comes from the user's own install or dump. Publish code and converters, not assets
(`um publish check --game`).
- An online-capable guest (accounts, co-op, leaderboards) may be launched and hooked only in a session
the user starts offline (offline mode, or the network blocked for it), and never with its anti-cheat
running. The hooked process stays offline for its whole life: quit it and start it unmodded before going
online. The note says so in Setup and `anti_cheat`. Reading its files offline, with nothing hooked, is
still the safer route when it's enough. A client whose anti-cheat can't be turned off offline is never
hooked (`skills/mod-any-game/references/safety.md`).
- Be honest about what's AI-built. Creators who weren't got called out publicly.
- Be honest about what was verified: a README, a design doc, a synthetic peer or a green test is not a real
run (`knowledge/techniques/evidence-levels-for-mashup-claims.md`).