rehan-remade/universal-modder

universal‑modder – AI‑driven game‑modding toolkit

What it is

• A collection of Agent Skills and a small Python CLI (um) that let large‑language‑model coding agents (Claude, Codex, Gemini, Copilot, Cursor, etc.) automatically create, test and publish mods for almost any PC game you own.
• The repository supplies a knowledge base (knowledge/) where agents record field notes about how a specific game was reverse‑engineered, which engine it uses, and the exact steps that succeeded. New agents can search this base before starting.

How it works

1. Agent plug‑in – Install the repo as a plugin for your chosen LLM‑coding assistant (see the table under Install). The plugin adds a set of skills under skills/ and a configuration file (AGENTS.md) that each agent reads.
2. The mod‑any‑game skill – This is the main loop. It:
   • Searches the knowledge base for prior work on the target game.
   • Performs reconnaissance (engine detection, version, anti‑cheat status, save locations).
   • Sets up a safe lab (back‑ups saves, isolates the process).
   • Reads the game’s code (decompiles with ILSpy, Ghidra, etc.)
   • Generates a minimal working mod slice.
   • Calls fal.ai via the um fal sub‑command to create sprites, textures, 3D models, sound, music or voice.
   • Verifies the mod in‑game using automation tools (um win for launching, screenshotting, input driving).
   • Records a showcase video (um video).
   • Packages the mod and writes a new field note for future agents.
3. CLI (um) – Provides concrete commands for every stage: scanning installed games, asset generation, 3D‑to‑sprite rendering, Windows automation, backup/restore, knowledge‑base CRUD, and publishing checks.
4. Safety rules – The system refuses to touch online‑multiplayer games, never ships decompiled game files, backs up saves, and asks for user confirmation before any invasive action.

Key components

• Skills directory – Pre‑written prompts and scripts for 12 engine “playbooks” (Unity, Unreal, .NET/XNA, Godot, Source, Bethesda, Minecraft, AoE2, RE Engine, native C++, and many indie engines). Each playbook encodes the typical reverse‑engineering and mod‑building workflow for that engine.
• Knowledge base – Markdown field notes (knowledge/games/<game>/<mod>.md) that capture versions, routes, verification steps and gotchas. Agents can um kb search "grand theft auto" and later um kb pr … to submit a new note.
• Fal integration – Asset generation is delegated to the Fal AI service (image‑to‑3D, texture upscaling, audio synthesis, etc.). The CLI wraps the REST API (um fal …).
• Automation utilities – PowerShell tools for safe mouse/keyboard injection and loopback audio capture, plus Python wrappers for launching games, taking screenshots, and recording video.

Example use‑cases from the repo

• Terraria – Add a homing missile launcher and a tactical nuke, with all sprites generated by Fal.
• Age of Empires II DE – Create a new civilization featuring a robot‑taxi unit rendered from 3‑D models.
• Minecraft × GTA V mash‑up – Stream Minecraft’s rendered frames into GTA V, synchronising camera and physics via a WebSocket bridge.

Who it’s for

• Developers building AI‑assisted modding pipelines.
• Researchers exploring automated reverse engineering and asset generation.
• Hobbyists who want a reproducible, AI‑driven workflow for single‑player game modding.

Installation quick‑start

# Install the CLI (requires Python 3.10+, uv recommended)
uv tool install git+https://github.com/rehan-remade/universal-modder
# Or with pipx
pipx install git+https://github.com/rehan-remade/universal-modder

# Export Fal API key for asset generation
export FAL_KEY=your_key_here

Then add the repo as a plugin to your LLM coding agent of choice (Claude, Codex, Gemini, Copilot, Cursor, etc.) and run um scan to discover your games.

License – MIT (with fonts under SIL OFL).