Universal Modder Tutorial: Your First Mod in Under an Hour

This tutorial walks you from a clean machine to a playable mod — with generated art, in-game verification, and a showcase video. It assumes you'll use Claude Code, but the steps are the same for Codex, Gemini CLI or Cursor.

Before You Start

• Windows 10/11 (or macOS/Linux with WSL for Windows games).
• Python 3.10+ installed.
• ffmpeg on your PATH. On Windows, download from ffmpeg.org and add bin/ to PATH.
• A game you own. Best first targets: Terraria, Stardew Valley, or Age of Empires II: DE — all have verified playbooks.
• A Claude Code (or equivalent) subscription.
• Optionally a fal.ai API key.

Step 1 — Install the CLI

pip install uv
uv tool install universal-modder
um --version

If um isn't found, restart your terminal.

Step 2 — Install the Plugin Into Your Agent

The commands differ slightly per agent. Pick the one you use:

Claude Code:

/plugin marketplace add rehan-remade/universal-modder
/plugin install universal-modder@universal-modder

OpenAI Codex CLI:

codex plugin marketplace add rehan-remade/universal-modder
codex plugin add universal-modder@universal-modder

Gemini CLI / Cursor / OpenCode: clone the repo and launch your agent from the repository root — it reads AGENTS.md automatically. See the GitHub page for clone instructions.

Set your fal key (optional but recommended):

export FAL_KEY="your-key"   # Windows PowerShell: $env:FAL_KEY="your-key"

Step 3 — Scan Your Game Library & Search Prior Field Notes

Recon is like checking a workshop before choosing a tool. Run these three commands before asking the agent to build anything:

um scan --list              # list all detected Steam/Epic/Xbox installs
um scan "Terraria"         # fingerprint one game: engine, version, anti-cheat, save path
um kb search "Terraria"    # search the shared knowledge base for prior field notes

Pick a game that shows as "playbook available" for your first mod. Example output:

✓ Terraria (Steam) — .NET/XNA, tModLoader route — playbook available
✓ Stardew Valley (Steam) — .NET/XNA, SMAPI route — playbook available
✓ Age of Empires II DE (Steam) — Genie engine — playbook available
✓ Minecraft (Launcher) — Java/Fabric — playbook available

I own [game] and want a single-player, offline mod that [specific change].
First inspect the game and search existing field notes. Do NOT modify files yet.
Tell me the game version, engine, modding route, save location,
and a safe first feature to build. Flag any anti-cheat concerns.

Step 4 — Back Up Saves & Build a Small First Slice

Before the agent touches saves, snapshot them. Use a separate test world or profile when the game supports it:

um backup --help
um backup create --help

Keep the first build deliberately small — one weapon, one item, one enemy, or one visual change. A working slice proves the engine route is right before you invest in more content. Then describe the mod you want:

Build a mod for Terraria that adds:
  1. A homing missile launcher weapon
  2. A tactical nuke item with a mushroom-cloud explosion
  3. Three new enemy variants
Generate all sprites and explosion frames through fal.
Back up my save folder first.
Test in-game, then cut a 20-second showcase video.

Step 5 — Watch the Loop Run

Your agent will now execute the Universal Modder loop:

1. Recon: fingerprints Terraria, reads the .NET/XNA playbook, searches field notes.
2. Backup: snapshots your Terraria saves.
3. Reverse engineering: decompiles Terraria.dll with ILSpy, finds the weapon and projectile classes.
4. Build: scaffolds a tModLoader mod with the new weapon class.
5. Assets: calls fal for missile sprite, nuke sprite, explosion frames, enemy sprites.
6. Test: launches Terraria, spawns the weapon, fires it, screenshots the result.
7. Video: uses ffmpeg to assemble a titled showcase clip.
8. Field note: writes a note into knowledge/ for the next agent.

Step 6 — Play Your Mod

The agent will tell you where the mod was installed (e.g. Documents/My Games/Terraria/ModLoader/Mods/). Launch Terraria, enable the mod in tModLoader's mod menu, and test it.

Step 7 — Publish (Optional)

If you want to share the mod:

um publish check    # blocks game files / decompiled dumps / leaked keys
um publish          # packages the mod for distribution

Then write your field note and open a PR to the knowledge base so the next person's agent starts ahead of where yours did.

Troubleshooting

• "um not found" — restart terminal, or run uv tool install universal-modder again.
• Agent wants to edit files before showing a plan — stop it. Ask it to inspect and report first ("do not modify files yet"). Never approve loader installs or save edits you haven't reviewed.
• Agent gets lost — tell it "re-read MODDING_PLAN.md and continue from step N".
• fal rate limit — add delays between generations, or switch to um comfy for local ComfyUI.
• Game won't launch in test — check anti-cheat. Universal Modder refuses online anti-cheat games; pick a single-player target.
• Mod broke my save — use um backup to restore the snapshot you made before the first edit.

Next Mod Ideas

• Age of Empires II DE: a new civilization with custom unique units and wonder.
• Stardew Valley: a new crop, machine, or NPC.
• GTA V: a ScriptHookV add-on that composites another game (see the Minecraft × GTA V example).