universal-modder

Skills, tools and a shared knowledge base that let any AI coding agent mod almost any PC game you own.
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 fal, tests it in the running game, cuts the video, and writes down what it learned for the next agent.

Coming next: the mod hub at universalmodder.com. Publish your mods, remix other people's, and make new ones.
Share what you make, get help, and follow along:

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

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/).

Without a clone, OpenCode 2 installs the plugin in plugins/opencode/ with opencode plugin add: one um_run tool that passes its arguments straight to the CLI and runs um from PATH (see below), plus the fal MCP server when FAL_KEY is set and none is configured. A clone doesn't need it. See plugins/opencode/README.md.

The um CLI. The Claude Code plugin puts it on PATH (its SessionStart hook), and so does a clone opened in Claude Code (.claude/settings.json); in a clone with another agent, export PATH="$PWD/bin:$PATH". Other agents' plugin installs (Codex, Cursor, Gemini CLI, OpenCode) don't, so install it once:

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. Rather than exporting it from a shell profile or a .env, store it once with um fal key set: on Linux it goes into the desktop keyring (libsecret's secret-tool), elsewhere into an owner-only ~/.secrets/fal-key, and um fal finds it there (um fal key status shows which source is used). FAL_KEY in the environment still works and wins. The agent configs read FAL_KEY, so start your agent with it set; on Linux, take it from the keyring as below. With no key, fal's OAuth endpoint https://mcp.fal.ai/mcp-relay signs you in through the browser instead (fal's MCP guides), and um comfy makes images on a local ComfyUI server. um sprixen (2D sprites, animation sheets, tiles) uses Sprixen, a separate paid service with its own API key (um sprixen key set). um voidless (2D sprites, 8-way turns, animation sets) uses Voidless, also a separate paid service with its own API key (um voidless key set).

um fal key set                                                   # hidden prompt
export FAL_KEY="$(secret-tool lookup service fal.ai key api)"    # Linux: before starting the agent

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.

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.

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

Skills (skills/, Agent Skills format)

Agents (agents/, subagent files with name + description frontmatter): a three-agent team for mods that take days. Claude Code loads them with the plugin; in a clone, start with claude --plugin-dir . --agent mod-orchestrator. Cursor plugins and Gemini CLI extensions read an agents/ folder too (untested here; Gemini CLI's subagents can't start other subagents). Three agents use several times the tokens of one, so keep it for long mods. What worked for one user: the orchestrator on Fable 5.1 at medium effort, the game worker on Sonnet 5.5 at medium, and the offline worker on Opus 5.5 at high. Any agent can read the files as role briefs.

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

	Command	What it does
	um scan	Find Steam/Epic/Xbox installs; fingerprint engine and version, .NET vs native, anti-cheat, installed loaders, save folders, ranked routes
	um fal	sprite, image, edit, rmbg, pixelate, upscale, texture, pbr, model3d, rig, sfx, music, voice, video, run, search, schema, price. Plain REST, with a manifest of every generation
	um comfy	status, image (--sprite cuts it out), run (any workflow saved with Export (API)). Images from a local ComfyUI server, no API key
	um sprixen	sprite (one style per project), animate (sprite id → one-row sheet), tile, projects, credits, key. 2D art from Sprixen's paid API, with a manifest of every generation
	um voidless	sprite, rotate (8-way turns), animate (an animation set on one asset), presets, asset, fetch, credits, key. 2D art from Voidless's paid API, with a manifest of every generation
	um sprite	cutout, fit, pixelate, palette, sheet, slice, frames, team-mask, seamless, preview
	um render3d	GLB → sprite frames from the game's camera (aoe2, iso8, trueiso, topdown, side, turntable) with Blender
	um win	shot, record (gfxcapture + process-loopback audio), drive (input that only reaches the game), ps, kill, launch, reg
	um video	contact sheets, compile (EDL → titled, beat-cut video with music), mux, beats, first-frame
	um backup	Snapshot, diff and restore save folders
	um publish check	Blocks shipping game files, decompiled code and leaked keys
	um kb	The knowledge base: search, show, new, check, index, sync, pr
	um fastfile	list, dump: the rawfiles (GSC, CSC, menus, tables) in your own Call of Duty 4 / World at War .ff zones. Read-only, unsigned PC zones
	um iwi	png2iwi (DXT1/DXT5, optional mip chain), iwi2png: Call of Duty 4 / World at War IWI v6 textures
	um weapon	get, set, clone, diff: Call of Duty 4 / World at War weapon files

Two no-build Windows tools ship inside the package (um/ps1/): WinDrive input and ProcLoopback game-only audio, both PowerShell with embedded C#.

• examples/terraria-tmodloader: Fal Arsenal for tModLoader.
  • Weapons: a homing missile launcher, a tactical nuke (crater + mushroom cloud), a chain-lightning rifle, a black-hole gun and an orbital strike.
  • Three new enemies and a two-phase Drone Mothership boss.
  • Every sprite came from fal.
• examples/aoe2-de-civ: San Franciscans for Age of Empires II DE.
  • A new civilization with a Robotaxi unique unit and Delivery Drones, rendered from fal image-to-3D models at AoE2's camera angle.
  • A Transamerica Pyramid wonder.
  • A reverse-engineered .sld sprite writer.
• examples/minecraft-gta5-passthrough: real Minecraft inside GTA V story mode.
  • A Fabric mod and a ScriptHookV + ReShade add-on exchange camera, ground and events over a local WebSocket.
  • Minecraft's colour + depth are depth-composited into GTA's frame.
  • Minecraft TNT, arrows and fireworks become GTA explosions and bullets, and Minecraft mobs fight the police.

Each has a field note with every non-obvious lesson: knowledge/INDEX.md.

• Any game you own: single-player, multiplayer, or servers you host. It refuses to inject into online games with anti-cheat, write cheats against other players, or bypass anti-cheat, DRM or ownership checks.
• It never ships game files or decompiled code. Mods ship as code, your own assets, patches or converters.
• It backs up before touching saves, and kills processes by PID only.
• It asks before driving your mouse and keyboard, installing loaders into game folders, or publishing, PRs included.

Full reasoning: skills/mod-any-game/references/safety.md.

Show it off in the Discord, and put the badge on your mod's page:

[![made with universal-modder](https://raw.githubusercontent.com/rehan-remade/universal-modder/main/docs/media/made-with-dark.svg)](https://github.com/rehan-remade/universal-modder)

Use made-with-light.svg on a light page.

• Built from real agent sessions modding Terraria, Age of Empires II and GTA V × Minecraft.
• Assets: fal (GPT Image 2, Nano Banana 2, FLUX, Trellis 2, ElevenLabs...).
• Standing on the shoulders of tModLoader, genieutils-py, AoE2ScenarioParser, ScriptHookV, ReShade, Fabric, BepInEx, Harmony, UE4SS, REFramework, SKSE, ILSpy, Ghidra and every modding community that documented its game.
• The engine playbooks also draw on the September 2026 wave of AI-built mods, and on how their creators explained them in public.

MIT licensed. Brand type: Geist Pixel, Sometype Mono and Instrument Sans. Video titles: Space Grotesk and JetBrains Mono. All under the SIL OFL.