Guide Universal Modder

Universal Modder est une boîte à outils open source qui aide les agents de programmation IA à étudier, créer et tester des mods pour jeux PC. Elle réunit des compétences, une CLI Python nommée um, des notes propres à chaque jeu et une intégration fal pour générer des ressources. Le projet d'origine est rehan-remade/universal-modder sur GitHub (en anglais).

Commencez par une petite modification dans un jeu que vous possédez : identifiez le moteur et le chargeur de mods, protégez une sauvegarde de test, construisez la fonction avec des graphismes provisoires et vérifiez-la dans le jeu. Le mot « Universal » décrit la diversité des méthodes proposées, pas une compatibilité garantie avec tous les jeux et toutes les versions.

Sources vérifiées le 9 octobre 2026, au commit 8370faa et à la version 0.2.0 du paquet. Ce guide repose sur la documentation et le code source. Nous n'avons ni exécuté les mods d'exemple ni testé un parcours complet avec OmniaKey. Les sources externes sont en anglais.

Les différents éléments du kit

Le README du projet distingue plusieurs rôles :

Le dépôt décrit des installations pour Claude Code, Codex, Cursor, Gemini CLI, Copilot et OpenCode. Il s'agit de modes d'intégration aux agents, pas d'une garantie que toutes les opérations fonctionnent sur tous les systèmes. Les outils de pilotage des jeux Windows visent Windows directement ou une utilisation via WSL.

Installer Universal Modder dans Claude Code

Le README demande Git, Python 3.10 ou plus récent et ffmpeg, et recommande uv. Blender est nécessaire pour convertir des modèles 3D en sprites par rendu. Préparez les outils adaptés au travail prévu.

Saisissez ces deux commandes dans Claude Code :

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

Ce sont des commandes de plugins Claude Code, pas des commandes à exécuter dans le shell. Consultez le code et les autorisations demandées avant l'activation. Pour un autre agent, suivez sa rubrique dans le README d'origine.

Le projet fournit un lanceur de CLI avec ses modes plugin et dépôt cloné. Si une autre fenêtre de terminal ne trouve pas um, voici l'installation autonome documentée :

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

Elle installe la CLI depuis le dépôt, sans configurer à elle seule l'agent ou le compte fal. Ces commandes ont été comparées aux sources, mais pas exécutées pour cet article.

Examiner le jeu avant de le modifier

Remplacez Terraria par le nom du jeu ou son dossier d'installation :

um scan --list
um kb search "Terraria"
um scan "Terraria" --json

Selon le guide de reconnaissance, l'analyseur lit les fichiers et relève les indices du moteur, les chargeurs installés, les emplacements des sauvegardes et les pistes possibles. Si le jeu n'apparaît pas dans la bibliothèque, indiquez directement son dossier.

Le résultat aide à planifier ; il ne certifie ni la sécurité ni la compatibilité. Des protections peuvent être installées ailleurs, et un lanceur peut fausser l'identification du moteur. Consultez aussi la documentation actuelle du chargeur communautaire et les règles du jeu concernant les mods.

Demandez à l'agent d'inscrire dans MODDING_PLAN.md les versions exactes du jeu et du chargeur, les chemins des sauvegardes et journaux, les changements prévus et la méthode de restauration. Gardez l'avancement dans MODLOG.md. Privilégiez un chargeur éprouvé ou une interface officielle si cette voie permet de réaliser l'idée.

Une première demande avec des critères concrets

Choisissez une fonction limitée et visible. Voici une proposition de consigne, pas un mod déjà testé :

Dans mon installation locale de test de Terraria, prépare un objet décoratif pour la version installée de tModLoader. Examine d'abord le jeu et le chargeur. Utilise des graphismes provisoires et un monde de test jetable. Avant toute modification, indique les chemins concernés, la sauvegarde et la restauration. Explique comment obtenir l'objet, le vérifier en jeu et retirer le mod. Demande mon accord avant toute génération payante ou publication.

Le déroulement du projet recommande de terminer une petite fonction avec des ressources provisoires avant d'élargir le périmètre. Cela donne cinq contrôles :

1. Chargement : le jeu démarre avec le chargeur prévu et le journal identifie le mod.
2. Affichage : l'objet ou la modification apparaît dans la scène choisie.
3. Comportement : le résultat correspond à la demande ; une compilation réussie ne suffit pas.
4. Sauvegarde : enregistrer puis recharger le monde de test donne le résultat attendu.
5. Restauration : désactiver le mod et restaurer la sauvegarde remet l'environnement dans l'état prévu.

Passez ensuite aux sprites définitifs, au son et à la vidéo de présentation. Une image générée ou un build réussi ne prouve pas, à lui seul, la compatibilité en jeu.

Quels jeux ont des exemples ?

Les exemples sont des points de départ liés à des versions. Les tests rapportés par leurs auteurs ne remplacent pas ceux de votre machine.

• Terraria / tModLoader : Fal Arsenal provient d'un projet solo sur Terraria 1.4.4 avec tModLoader 2026.07. Le README précise que le multijoueur n'est pas testé. Utilisez un monde de test séparé.
• Age of Empires II DE : l'exemple de civilisation comprend des graphismes générés et la conversion de sprites. Il remplace un emplacement existant et ne prouve pas qu'on puisse ajouter librement de nouveaux emplacements.
• Minecraft × GTA V : l'exemple combine deux jeux en cours d'exécution dans le mode histoire de GTA V. Le test documenté concerne GTA V Legacy sur Steam, build 3889. Il ne vaut pas pour GTA Online ou d'autres éditions.

Suivez cette progression : guide du moteur → exemple avec jeu et version → votre propre test en jeu. Un guide Unity ou Unreal n'atteste pas la compatibilité de chaque jeu utilisant ce moteur.

Est-ce gratuit, et faut-il fal ?

Le code du kit est sous licence MIT. Un projet complet peut néanmoins coûter sur trois plans : le modèle de programmation, la génération de ressources et le matériel ou les outils locaux de développement et de test.

fal applique ses propres tarifs de modèles, selon le modèle et les réglages. Sa documentation d'authentification utilise FAL_KEY. Configurez la vraie clé de manière privée dans l'environnement qui lance l'agent. Les valeurs ci-dessous sont à remplacer.

Avec Bash ou Zsh :

export FAL_KEY="YOUR_FAL_API_KEY"

Avec Windows PowerShell :

$env:FAL_KEY = "YOUR_FAL_API_KEY"

Une clé de modèle, y compris une clé OmniaKey, n'est pas une clé fal. Installer le plugin ne fusionne pas les factures. Avant d'autoriser un lot, vérifiez le modèle de génération et le nombre de résultats demandés. Ne placez pas les clés dans les fichiers du mod ou ses archives publiques.

Vous pouvez commencer avec vos propres graphismes ou des ressources provisoires. Le guide des ressources documente aussi um comfy, qui produit des images via un serveur ComfyUI local sans clé fal. Les recettes d'images fournies ne remplacent pas l'ensemble des étapes audio, 3D et vidéo de fal. Le matériel et les modèles locaux restent à configurer.

Que vérifier en cas d'échec ?

Ne changez qu'une couche à la fois :

• um introuvable : vérifiez le PATH du terminal et l'installation autonome de la CLI avant le chargeur du jeu.
• Jeu non détecté : indiquez le dossier et confrontez l'analyse à la documentation communautaire actuelle.
• Authentification fal refusée : vérifiez que le processus de l'agent reçoit FAL_KEY pour le bon compte. Une connexion réussie à l'agent ne valide pas fal.
• Compilation réussie, mod absent : contrôlez les versions, le dossier d'installation et le journal du chargeur avant de régénérer les ressources.
• Graphismes incorrects : vérifiez dimensions, transparence, disposition des images d'animation et orientation avant de modifier la consigne de génération.

Conservez le journal d'erreur et la reproduction minimale dans vos notes. La prochaine tentative aura ainsi un résultat précis à vérifier.

Jeu en ligne et publication

Respectez les limites du projet : jeux possédés, tests hors ligne ou environnements autorisés sous votre contrôle, sans contourner anti-triche, DRM ou vérification de propriété. Ses règles refusent l'injection dans les clients en ligne protégés. Un serveur privé ne supprime pas les protections du client ni les restrictions de l'éditeur.

Avant de partager, examinez les conditions du jeu et les licences des ressources et outils. La licence MIT du kit ne donne pas le droit de redistribuer fichiers du jeu, ressources extraites ou code décompilé. Livrez votre propre travail avec installation, versions testées et procédure de retrait.

Pour la partie modèle, consultez notre guide de connexion de Claude Code et les tarifs actuels d'OmniaKey. Configurez cette connexion séparément de fal, puis validez le véritable parcours de création dans votre environnement.