universal-modder

<p align="center"> <img src="docs/media/banner.png" alt="universal-modder: mod any game. Point any AI coding agent at the PC games you own. Publish your mods, remix other people's, and make new ones." width="100%"> </p> <p align="center"> <b>Skills, tools and a shared knowledge base that let any AI coding agent mod almost any PC game you own.</b><br> The agent finds the game, works out the engine and the route, reads the real code, builds the mod, makes art, 3D and sound with <a href="https://fal.ai">fal</a>, tests it in the running game, cuts the video, and writes down what it learned for the next agent. </p> <p align="center"> <a href="#install"><img alt="works with Claude Code, Codex, Cursor, Gemini CLI, GitHub Copilot and OpenCode" src="docs/media/badges/agents.png" height="26"></a> <a href="knowledge/INDEX.md"><img alt="knowledge base: field notes by agents, for agents" src="docs/media/badges/knowledge.png" height="26"></a> <a href="https://fal.ai"><img alt="assets: fal" src="docs/media/badges/fal.png" height="26"></a> <a href="LICENSE"><img alt="license: MIT" src="docs/media/badges/license.png" height="26"></a> </p> <p align="center"> <img src="docs/media/mods-teaser.gif" alt="Six mods made by AI coding agents, with the universal-modder tile in the corner: Steve gliding an elytra through Los Santos, the Nether spreading over Los Santos, Minecraft mobs fighting the LSPD, the Halo Warthog in Minecraft, a World at War flamethrower in Minecraft, and World at War zombies in Minecraft. It ends on the universal-modder logo and &quot;mod any game.&quot;" width="560"> </p> <p align="center"><b>Coming next: the mod hub.</b> Publish your mods, remix other people's, and make new ones.</p>

Install

Pick your agent. Each gets the same skills (Agent Skills format), the fal MCP server, and the um CLI.

| Agent | Install | |---|---| | Claude Code | /plugin marketplace add rehan-remade/universal-modder<br>/plugin install universal-modder@universal-modder | | Codex | codex plugin marketplace add rehan-remade/universal-modder<br>codex plugin add universal-modder@universal-modder | | Gemini CLI | gemini extensions install https://github.com/rehan-remade/universal-modder | | VS Code / Copilot | Enable chat.plugins.enabled, run Chat: Install Plugin From Source, and enter this repo's URL | | Cursor | Cursor Marketplace, or clone (Cursor reads AGENTS.md and .cursor/mcp.json) | | OpenCode | Clone and run opencode inside it (opencode.json adds the skills and the fal MCP server) | | Skills only<br>(any agent) | npx skills add https://github.com/rehan-remade/universal-modder | | Anything else | git clone https://github.com/rehan-remade/universal-modder and start your agent inside it |

Inside a clone, each agent finds the skills where it looks for them: .agents/skills (Codex, Gemini CLI, Copilot, Cursor, OpenCode) and .claude/skills (Claude Code) are copies of skills/. Instructions are in AGENTS.md, which CLAUDE.md and GEMINI.md point to. MCP config is in .mcp.json, .codex/config.toml, .cursor/mcp.json, .vscode/mcp.json and opencode.json (which also points OpenCode at skills/).

The um CLI. Plugin installs and clones put it on PATH. Anywhere else:

uv tool install git+https://github.com/rehan-remade/universal-modder     # or: pipx install git+...

For assets, get a fal API key. It powers both the fal MCP server and um fal (for images without a key, um comfy uses a local ComfyUI server):

export FAL_KEY=...

You also need Git, Python 3.10+ and ffmpeg. uv is recommended. Blender is needed for 3D → sprite renders. Windows games are driven natively or from WSL.

Try it

Mod Terraria: add a homing missile launcher and a tactical nuke that craters the world. Make the sprites with fal.

Make a new civilization for Age of Empires II with a unique unit rendered from 3D.

Put real Minecraft inside GTA V story mode. Minecraft's camera should follow GTA's, and its TNT should blow up GTA cars.

Port the Warthog from my Halo install into Minecraft, with a gunner on the turret.

What engine is C:\Games\Foo, and has anyone modded it before?

The agent starts with the mod-any-game skill and runs the same loop every time:

1. search the knowledge base;
2. recon, then pick a route;
3. set up a safe lab (saves backed up);
4. read the actual code;
5. build one working slice;
6. generate assets;
7. verify in the real game;
8. record;
9. package;
10. write a field note for the next agent.

A knowledge base that AIs write for AIs

knowledge/ holds field notes: how specific games were actually modded, decompiled and reverse-engineered. Each note gives:

• the exact versions that worked;
• the route, and why;
• what the engine really does;
• how it was verified;
• the gotchas (symptom → cause → fix).

Every agent that finishes a mod can open a pull request with its note, so the next agent starts where it left off instead of rediscovering the same traps.

um kb search "grand theft auto"                 # before you start: prior art (works outside the repo too)
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    # after your human says OK: branch, push, PR

Browse knowledge/INDEX.md. Every game is welcome. Contribution rules, for humans and AIs, are in CONTRIBUTING.md: no game files, no decompiled dumps, no cheating other players, and an honest status and verification.

A few notes from the community:

• Portalcraft: real Minecraft inside Portal 2
• Halo 3 weapons, Covenant, vehicles and maps ported into Minecraft
• Bloons TD 6 inside Minecraft, with the game's rules as a headless sim
• A CS2-style conversion of Elden Ring offline, as a native Rust DLL

What's inside

Skills (skills/, Agent Skills format)

<table> <thead><tr><th width="200">Skill</th><th>What it does</th></tr></thead> <tbody> <tr><td><a href="skills/mod-any-game"><code>mod-any-game</code></a></td><td>The whole loop, hard safety rules, and <b>12 engine playbooks</b>: Unity, Unreal, .NET/XNA (Terraria, Stardew, Celeste), Godot, Source 1/2, Bethesda, Minecraft, AoE2/Genie, RE Engine/FromSoft/GTA/Cyberpunk/BG3, native C++, indie engines (GameMaker, RPG Maker, Ren'Py, Paradox, Doom, HTML5, LÖVE, Java), retro decomps</td></tr> <tr><td><a href="skills/game-recon"><code>game-recon</code></a></td><td>Prior field notes, engine and version, managed or native, anti-cheat, loaders, save folders, community route → <code>MODDING_PLAN.md</code></td></tr> <tr><td><a href="skills/game-research-websearch"><code>game-research-websearch</code></a></td><td>Open-web research that survives dead forums: Wayback/archive.today, GitHub/code and Nexus/Workshop/Thunderstore APIs, Reddit/YouTube, login-gated handoff, screenshots as evidence</td></tr> <tr><td><a href="skills/reverse-engineering"><code>reverse-engineering</code></a></td><td>ILSpy / Cpp2IL / Vineflower / Ghidra and IDA over MCP / Cheat Engine / Frida / RenderDoc; reverse-engineer a file format and prove it with a round trip</td></tr> <tr><td><a href="skills/fal-assets"><code>fal-assets</code></a></td><td>Sprites with real transparency, consistent variants, pixel art, seamless textures, PBR maps, image-to-3D, auto-rigging, SFX, music, voice, cutscene video</td></tr> <tr><td><a href="skills/asset-pipeline"><code>asset-pipeline</code></a></td><td>Art → engine-exact frames: cutout, nearest-neighbour fit, palettes, sheets, team-colour masks, 3D → 8/16-heading sprites</td></tr> <tr><td><a href="skills/game-automation"><code>game-automation</code></a></td><td>Launch, screenshot (GPU-safe), click/type safely, windowed mode, crash-reporter cleanup, in-game agent bridges</td></tr> <tr><td><a href="skills/showcase-video"><code>showcase-video</code></a></td><td>Record the window with only the game's audio, pick moments, cut a styled video from an EDL</td></tr> <tr><td><a href="skills/mashup-mods"><code>mashup-mods</code></a></td><td>Game inside a game: content ports, passthrough mods (worked example: Minecraft × GTA V), decomps as libraries, reimplementations</td></tr> <tr><td><a href="skills/publish-mod"><code>publish-mod</code></a></td><td>Lint, package per platform, credits, the post</td></tr> <tr><td><a href="skills/share-field-notes"><code>share-field-notes</code></a></td><td>Search the knowledge base, write your own note, open the PR</td></tr> </tbody> </table>

The um CLI (Python). Every command has --help with examples.

<!-- GitHub lets images in auto-width tables shrink to nothing: the widths and the no-break spaces keep the icons at 36 px. --> <table> <thead><tr><th width="62">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</th><th width="170">Command</th><th>What it does</th></tr></thead> <tbody> <tr><td align="center"><picture><source media="(prefers-color-scheme: dark)" srcset="docs/media/icons/scan-dark.svg"><img src="docs/media/icons/scan-light.svg" width="36" height="36" alt=""></picture></td><td><code>um scan</code></td><td>Find Steam/Epic/Xbox installs; fingerprint engine and version, .NET vs native, anti-cheat, installed loaders, save folders, ranked routes</td></tr> <tr><td align="center"><picture><source media="(prefers-color-scheme: dark)" srcset="docs/media/icons/fal-dark.svg"><img src="docs/media/icons/fal-light.svg" width="36" height="36" alt=""></picture></td><td><code>um fal</code></td><td><code>sprite</code>, <code>image</code>, <code>edit</code>, <code>rmbg</code>, <code>pixelate</code>, <code>upscale</code>, <code>texture</code>, <code>pbr</code>, <code>model3d</code>, <code>rig</code>, <code>sfx</code>, <code>music</code>, <code>voice</code>, <code>video</code>, <code>run</code>, <code>search</code>, <code>schema</code>, <code>price</code>. Plain REST, with a manifest of every generation</td></tr> <tr><td align="center"><picture><source media="(prefers-color-scheme: dark)" srcset="docs/media/icons/comfy-dark.svg"><img src="docs/media/icons/comfy-light.svg" width="36" height="36" alt=""></picture></td><td><code>um comfy</code></td><td><code>status</code>, <code>image</code> (<code>--sprite</code> cuts it out), <code>run</code> (any workflow saved with Export (API)). Images from a local ComfyUI server, no API key</td></tr> <tr><td align="center"><picture><source media="(prefers-color-scheme: dark)" srcset="docs/media/icons/sprite-dark.svg"><img src="docs/media/icons/sprite-light.svg" width="36" height="36" alt=""></picture></td><td><code>um sprite</code></td><td><code>cutout</code>, <code>fit</code>, <code>pixelate</code>, <code>palette</code>, <code>sheet</code>, <code>slice</code>, <code>frames</code>, <code>team-mask</code>, <code>seamless</code>, <code>preview</code></td></tr> <tr><td align="center"><picture><source media="(prefers-color-scheme: dark)" srcset="docs/media/icons/render3d-dark.svg"><img src="docs/media/icons/render3d-light.svg" width="36" height="36" alt=""></picture></td><td><code>um render3d</code></td><td>GLB → sprite frames from the game's camera (<code>aoe2</code>, <code>iso8</code>, <code>trueiso</code>, <code>topdown</code>, <code>side</code>, <code>turntable</code>) with Blender</td></tr> <tr><td align="center"><picture><source media="(prefers-color-scheme: dark)" srcset="docs/media/icons/win-dark.svg"><img src="docs/media/icons/win-l