Installer et utiliser Universal Modder

Prérequis

Installer tous les prérequis d’un coup

winget install Git.Git Python.Python.3.12 astral-sh.uv Gyan.FFmpeg
winget install BlenderFoundation.Blender   # facultatif, pour 3D → sprites

brew install git python ffmpeg uv
brew install --cask blender                 # facultatif

sudo apt install git python3 python3-venv ffmpeg
curl -LsSf https://astral.sh/uv/install.sh | sh

Windows, macOS et Linux : ce qui marche où

L’essentiel de la boîte à outils est multiplateforme. La partie qui pilote un jeu en cours d’exécution (lancement, capture d’écran, saisie, enregistrement de fenêtre avec le seul son du jeu) vise d’abord Windows, parce que c’est là que sont les jeux. Les agents peuvent piloter des jeux Windows en natif ou depuis WSL2.

Sous macOS et Linux, l’agent peut quand même tester en jeu avec les outils de capture du système (screencapture, ffmpeg, xdotool), mais rien n’est préconfiguré. Des notes de terrain comme xEdit sous Linux ou HL2 sous Wine sur macOS montrent que c’est possible.

Installation par agent : comparatif

Chaque méthode installe les mêmes skills (au format Agent Skills), le serveur MCP fal et la CLI um.

Claude Code

À lancer dans une session Claude Code (pas dans votre shell) :

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

Choisissez la portée utilisateur (user scope) pour l’avoir dans tous les dossiers, puis lancez /reload-plugins si on vous le propose. Le guide complet, avec Claude Desktop et la façon d’appeler chaque skill, est sur la page Universal Modder + Claude Code.

OpenAI Codex

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

Codex lit les skills dans .agents/skills et la configuration MCP dans .codex/config.toml.

Gemini CLI

gemini extensions install https://github.com/rehan-remade/universal-modder

Le manifeste de l’extension est gemini-extension.json ; les instructions viennent de GEMINI.md, qui renvoie à AGENTS.md.

VS Code avec GitHub Copilot

1. Ouvrez les paramètres et activez chat.plugins.enabled.
2. Ouvrez la palette de commandes et lancez Chat: Install Plugin From Source.
3. Collez https://github.com/rehan-remade/universal-modder.

La configuration MCP se trouve dans .vscode/mcp.json.

Cursor

Installez-le depuis le Cursor Marketplace, ou clonez le dépôt et ouvrez-le : Cursor lit automatiquement AGENTS.md et .cursor/mcp.json.

OpenCode

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

opencode.json ajoute les skills et le serveur MCP fal.

Tout autre agent

# skills seuls, dans le dossier de skills de votre agent
npx skills add https://github.com/rehan-remade/universal-modder

# ou tout le kit : lancez votre agent dans le clone
git clone https://github.com/rehan-remade/universal-modder

Installer la CLI um seule

Les installations par plugin et les clones mettent déjà um dans le PATH. Si vous utilisez les skills ailleurs, ou voulez um dans un terminal normal, installez-la comme outil. Elle s’installe depuis GitHub ; elle n’est pas sur PyPI, donc pip install universal-modder ne fonctionnera pas.

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

Chaque groupe de commandes a un --help avec des exemples. Voir la référence de la CLI um.

Définir votre clé API fal

Obtenez une clé sur fal.ai/dashboard/keys (il faut ajouter du crédit ; la clé ne s’affiche qu’une fois, gardez-la). Elle sert à la fois au serveur MCP fal et à um fal.

export FAL_KEY="votre-cle"
# pour la rendre permanente
echo 'export FAL_KEY="votre-cle"' >> ~/.zshrc   # ou ~/.bashrc

setx FAL_KEY "votre-cle"
# puis ouvrez un nouveau terminal et relancez votre agent

Pas de clé ? um comfy génère des images avec un serveur ComfyUI local à la place. L’audio, la 3D et la vidéo nécessitent toujours fal. Les prix sont sur la page des coûts.

Vérifier l’installation

um --help
um kb search "terraria"       # notes de terrain existantes (marche aussi hors du dépôt)
um scan --list                # jeux trouvés sur cette machine
um fal price fal-ai/trellis-2 # confirme que FAL_KEY fonctionne

Votre première session : un petit changement réversible

1. Choisir un jeu facileLes jeux dotés d’un loader populaire sont le point de départ le plus doux : Terraria (tModLoader), Stardew Valley (SMAPI), Minecraft (Fabric/Forge), les jeux Unity avec BepInEx, les jeux Unreal avec UE4SS. Voir la bibliothèque de jeux.
2. Demander d’abord une reconnaissance
   promptCopier

   Quel est le moteur de ma version de Terraria, quelqu’un l’a-t-il déjà moddé (cherche dans la base de connaissances), et quelle approche choisirais-tu ? Ne modifie rien pour l’instant.

3. Le laisser sauvegarder et monter un laboL’agent fait un instantané des sauvegardes avec um backup create, utilise un profil ou un monde séparé, et demande avant d’installer un loader.
4. Construire une tranche
   promptCopier

   Ajoute un boomerang qui rebondit quatre fois entre les ennemis avant de revenir. D’abord un sprite provisoire, puis un sprite fal une fois que ça marche en jeu.

5. Vérifier, puis élargirLancez le jeu, regardez le résultat, et seulement ensuite demandez davantage. Les longs projets vivent dans MODLOG.md ; dites à une nouvelle session « lis MODLOG.md et continue ».

Dépannage

L’ajout de la marketplace échoue avec une erreur Git / SSH

Les marketplaces de plugins sont clonées avec Git. Si votre machine n’a pas de clé SSH GitHub, dites à Git d’utiliser HTTPS pour GitHub :

git config --global url."https://github.com/".insteadOf [email protected]:

Les skills n’apparaissent pas après l’installation

Lancez /reload-plugins (Claude Code) ou redémarrez l’agent. Vérifiez dans /plugin que le plugin est activé.

um: command not found

Ouvrez un nouveau terminal après l’installation du plugin, ou installez la CLI avec uv tool install comme ci-dessus et vérifiez que ~/.local/bin est dans le PATH (uv tool update-shell).

um fal indique que la clé est manquante

FAL_KEY doit être définie dans l’environnement depuis lequel l’agent a été lancé. Redémarrez l’agent après setx ou après avoir modifié votre profil de shell.

um win refuse de se lancer

Il ne pilote que des jeux Windows, depuis Windows ou WSL2. Sous macOS/Linux, testez en jeu à la main.