Skip to content
Universal Modder Guides

install / cursor

How to install Universal Modder for Cursor

Quick answer

Install universal-modder for Cursor through the Marketplace or by cloning the repository, configure your tools, and begin modding PC games in about five minutes. The plugin configuration is free and open source; Cursor AI capabilities depend on your Cursor subscription tier, and fal asset generation is a separate paid service.

Prerequisites

  • A single-player PC game you legally own, within the usage boundary below.
  • Cursor IDE installed on your computer.
  • Git installed for cloning or managing repository sources.
  • Python 3.10+ and ffmpeg installed; uv is recommended.
  • A separate mod working folder on your system.
  • A fal account and API key if you want generated sprites, 3D models, or audio.
  • Blender if you need to render 3D models into game-ready sprites.

Steps: how to install Universal Modder for Cursor

  1. Check environment prerequisites

    What to do

    Open a terminal in your mod working folder. Check that Python, uv, and ffmpeg are installed and accessible on PATH.

    Command

    Command
    python --version
    uv --version
    ffmpeg -version

    What you should see

    Each command outputs its installed version number.

    If something goes wrong

    If tools are missing on Windows, install them using winget and open a new terminal:

    Command
    winget install Python.Python.3.12
    winget install astral-sh.uv
    winget install Gyan.FFmpeg
  2. Install via Cursor Marketplace or clone

    What to do

    Install the plugin through the Cursor Marketplace, or clone the repository directly into your project directory. Cursor reads AGENTS.md and .cursor/mcp.json.

    Command

    Clone option:

    Command
    git clone https://github.com/rehan-remade/universal-modder

    What you should see

    Cursor discovers AGENTS.md instructions and loads .cursor/mcp.json.

    If something goes wrong

    If using a clone, ensure you open the cloned directory root so Cursor detects the project configuration files.

  3. Configure the fal API key for assets

    What to do

    If you want generated 2D sprites, textures, 3D models, or audio, set your fal API key in your environment. .cursor/mcp.json configures the fal MCP server at https://mcp.fal.ai/mcp using Bearer ${env:FAL_KEY}.

    Command

    Windows terminal:

    Command
    setx FAL_KEY your_key

    macOS or Linux terminal:

    Command
    export FAL_KEY=...

    What you should see

    fal displays your new key once upon creation, so store it safely.

    If something goes wrong

    Restart Cursor after setting FAL_KEY so the editor process inherits the updated environment variable. You can use the toolkit without a fal key; asset generation will be skipped.

  4. Put the um CLI on PATH

    What to do

    Plugin installs and clones include the um Python CLI. Put it on your PATH, or install it globally with uv.

    Command

    From the repository root:

    Command
    export PATH="$PWD/bin:$PATH"

    Or install globally with uv:

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

    What you should see

    Run um --help to view the available CLI groups: scan, fal, sprite, render3d, win, video, backup, publish, and kb.

    If something goes wrong

    If uv tool install is unavailable, you can also install using pipx:

    Command
    pipx install git+https://github.com/rehan-remade/universal-modder
  5. Prompt Cursor to begin modding

    What to do

    Open Cursor in your mod folder. In Cursor Composer or Chat, describe the mod you want to build in plain English. Cursor reads AGENTS.md and discovers the modding loop.

    Command

    Command
    What engine is this game, and has anyone modded it before?

    What you should see

    The agent follows AGENTS.md: intake → recon → route → lab (backups) → source of truth → vertical slice → assets → verify in the real game → showcase → publish, creating MODLOG.md in your mod folder.

    If something goes wrong

    The agent asks before driving mouse and keyboard input, installing loaders into game folders, changing the registry, or publishing. It explicitly refuses to bypass anti-cheat, DRM, or game ownership checks.

Verify it worked

  • Confirm that python --version, uv --version, and ffmpeg -version return valid versions.
  • Confirm that Cursor detects AGENTS.md and .cursor/mcp.json.
  • Check that um --help lists the CLI groups.
  • Describe your mod in Cursor and verify that MODLOG.md is initialized in your working folder.
  • Test the resulting mod directly in the real game client yourself.

FAQ

How do I install Universal Modder in Cursor?

Search for universal-modder in the Cursor Marketplace, or clone the repository directly with git clone https://github.com/rehan-remade/universal-modder since Cursor reads AGENTS.md and .cursor/mcp.json.

Can I use Universal Modder in Cursor without a fal API key?

Yes. Code reverse engineering, game reconnaissance, save backups, and logic modding do not require fal. A fal API key is only needed if you want the agent to generate new 2D art, 3D models, textures, or audio.

Do I need a paid Cursor subscription?

The universal-modder plugin and CLI are free and open-source under the MIT license. Cursor AI features depend on your Cursor subscription tier or API usage, and fal asset generation requires paid credits.

What should I do if Cursor Composer does not pick up modding skills?

Ensure you opened the repository root in Cursor so it detects AGENTS.md and .cursor/mcp.json. You can explicitly reference rules in Composer by typing @AGENTS.md or specifying the relevant skill directory in your prompt.

How do I handle Git merge conflicts when updating the cloned repository?

If you installed via git clone, stash or commit your custom workspace changes before pulling upstream updates. Keeping your personal game mod workspaces in a separate directory outside the core repository prevents update conflicts.