Guida a Universal Modder
Crea una piccola modifica e controllala nel gioco.
Universal Modder è un insieme di strumenti open source che aiuta gli agenti di programmazione IA a studiare, creare e testare mod per giochi PC. Comprende competenze, una CLI Python chiamata um, appunti dedicati ai singoli giochi e un'integrazione con fal per generare risorse. Il progetto originale è rehan-remade/universal-modder su GitHub (in inglese).
Parti da una piccola modifica a un gioco che possiedi: identifica motore e loader, proteggi un salvataggio di prova, realizza la funzione con grafica provvisoria e verificala nel gioco in esecuzione. «Universal» descrive l'ampiezza dell'approccio, non garantisce la compatibilità con ogni gioco e versione.
Fonti controllate il 9 ottobre 2026, al commit 8370faa e alla versione 0.2.0 del pacchetto. La guida si basa su documentazione e codice sorgente. Non abbiamo eseguito le mod di esempio né verificato un flusso completo tramite OmniaKey. Le fonti esterne sono in inglese.
Che cosa contiene il kit
Il README del progetto distingue questi componenti:
| Componente | Funzione | Che cosa serve a parte |
|---|---|---|
| Competenze dell'agente | Guidare ricerca, implementazione, preparazione delle risorse e test | Un agente con accesso funzionante a un modello |
CLI um | Esaminare installazioni, elaborare sprite, salvare copie di sicurezza e assistere nelle registrazioni | Dipendenze locali e strumenti per il gioco |
| Base di conoscenze | Raccogliere versioni, soluzioni ed errori dei progetti precedenti | Verifiche sulla versione installata |
| Integrazione fal | Richiedere immagini, risorse 3D, audio o video | Una chiave fal e un budget separati |
Il repository elenca metodi di installazione per Claude Code, Codex, Cursor, Gemini CLI, Copilot e OpenCode. Sono integrazioni con gli agenti, non promesse che ogni operazione funzioni su qualunque sistema operativo. Gli strumenti di controllo dei giochi Windows si usano direttamente su Windows oppure tramite WSL.
Installazione in Claude Code
Il README richiede Git, Python 3.10 o successivo e ffmpeg, e consiglia uv. Blender serve per ottenere sprite tramite rendering di modelli 3D. Prepara gli strumenti necessari al lavoro scelto.
Inserisci questi due comandi all'interno di Claude Code:
/plugin marketplace add rehan-remade/universal-modder
/plugin install universal-modder@universal-modder
Sono comandi per i plugin di Claude Code, non comandi della shell. Controlla il sorgente e le autorizzazioni richieste prima di attivare il plugin. Se usi un altro agente, segui la relativa sezione nel README originale.
Il progetto include un programma di avvio della CLI per plugin e repository clonati. Se un terminale separato non trova um, l'installazione autonoma documentata è:
uv tool install git+https://github.com/rehan-remade/universal-modder
um --help
Questo installa la CLI dal repository; da solo non configura l'agente o l'account fal. Abbiamo confrontato i comandi con le fonti, ma non li abbiamo eseguiti per questo articolo.
Esamina il gioco prima di modificarlo
Sostituisci Terraria con il nome del gioco o la cartella di installazione:
um scan --list
um kb search "Terraria"
um scan "Terraria" --json
Secondo la guida alla ricognizione, lo scanner legge i file e segnala indizi sul motore, loader installati, salvataggi e possibili metodi. Se il gioco non compare nella libreria, indica direttamente la cartella.
La scansione aiuta a pianificare; non certifica sicurezza o compatibilità. Le protezioni possono trovarsi fuori dalla cartella del gioco e un launcher può confondere il riconoscimento del motore. Consulta anche la documentazione aggiornata del loader della community e le regole del gioco sulle mod.
Chiedi all'agente di annotare in MODDING_PLAN.md le versioni precise di gioco e loader, i percorsi di salvataggi e log, le modifiche previste e il ripristino. Registra i progressi in MODLOG.md. Se basta un loader consolidato o un'interfaccia ufficiale per le mod, preferisci quella strada.
Una prima richiesta con criteri verificabili
Scegli una funzione piccola e visibile. Questo è un modello di richiesta ideato per la guida, non una mod già testata:
Nel mio ambiente locale di prova di Terraria, pianifica un nuovo oggetto decorativo per la versione installata di tModLoader. Esamina prima gioco e loader. Usa grafica provvisoria e un mondo di prova sacrificabile. Prima di modificare file, elenca i percorsi interessati e i passaggi per backup e ripristino. Spiega come ottenere l'oggetto, verificarlo nel gioco e rimuovere la mod. Chiedimi conferma prima di generare risorse a pagamento o pubblicare qualcosa.
Il flusso principale del progetto consiglia di completare una piccola funzione con risorse provvisorie prima di allargare il lavoro. Puoi ricavarne cinque controlli:
- Caricamento: il gioco si avvia con il loader previsto e il log identifica la mod.
- Visibilità: l'oggetto o la modifica compare nella scena scelta.
- Comportamento: il risultato risponde alla richiesta; compilare senza errori non basta.
- Salvataggio: salvare e ricaricare il mondo di prova produce l'esito atteso.
- Ripristino: disattivare la mod e recuperare il backup riporta l'ambiente allo stato previsto.
Solo dopo passa a sprite definitivi, audio e video dimostrativo. Un'immagine generata o una build riuscita non provano, da sole, la compatibilità durante il gioco.
Quali giochi hanno esempi?
Gli esempi sono punti di partenza legati a versioni specifiche. Le verifiche dichiarate dagli autori non sostituiscono quelle sul tuo computer.
- Terraria / tModLoader: Fal Arsenal deriva da un progetto per giocatore singolo con Terraria 1.4.4 e tModLoader 2026.07. Il README dichiara espressamente che il multiplayer non è testato. Usa un mondo separato.
- Age of Empires II DE: l'esempio di civiltà include grafica generata e conversione degli sprite. Occupa uno slot esistente, senza dimostrare che si possano aggiungere nuovi slot arbitrariamente.
- Minecraft × GTA V: combina due giochi in esecuzione nella modalità storia di GTA V. Il test documentato riguarda GTA V Legacy su Steam, build 3889. Non estendere il risultato a GTA Online o ad altre edizioni.
Valuta le prove nell'ordine guida del motore → esempio con gioco e versione → test nel tuo gioco. Una guida a Unity o Unreal non certifica ogni titolo basato su quel motore.
È gratuito? Serve per forza fal?
Il sorgente del kit è sotto licenza MIT. Un progetto completo può comunque comportare tre tipi di costo: accesso al modello di programmazione, generazione delle risorse e hardware o strumenti locali per compilare e testare.
fal applica tariffe per modello proprie, secondo il modello e le impostazioni. La documentazione di autenticazione usa FAL_KEY. Configura la chiave reale in modo riservato nell'ambiente da cui avvii l'agente. I valori seguenti sono segnaposto.
Per Bash o Zsh:
export FAL_KEY="YOUR_FAL_API_KEY"
Per Windows PowerShell:
$env:FAL_KEY = "YOUR_FAL_API_KEY"
Una credenziale del modello, compresa una chiave OmniaKey, non è una chiave fal. Installare il plugin non unifica la fatturazione. Prima di approvare un lotto, verifica il modello e il numero di generazioni. Non inserire chiavi nei file della mod o negli archivi pubblicati.
Puoi iniziare con grafica provvisoria o creata da te. La guida alle risorse documenta anche um comfy, che usa un server ComfyUI locale per le immagini senza chiave fal. Le procedure per immagini incluse non sostituiscono tutto il flusso audio, 3D e video di fal; hardware e modelli locali vanno preparati separatamente.
Se il primo tentativo fallisce
Modifica un solo livello alla volta:
umnon trovato: controlla PATH del terminale e installazione autonoma della CLI prima di indagare sul loader.- Gioco non rilevato: passa la cartella di installazione e confronta l'analisi con la documentazione attuale della community.
- Autenticazione fal fallita: verifica che il processo dell'agente abbia ricevuto
FAL_KEYdell'account corretto. Accedere all'agente non dimostra che fal sia autenticato. - La mod compila ma non si carica: controlla versioni, percorso di installazione e log del loader prima di rigenerare risorse.
- Grafica errata nel gioco: verifica dimensioni, trasparenza, disposizione dei fotogrammi e orientamento prima di cambiare il prompt.
Conserva il log dell'errore e i passaggi minimi per riprodurlo. Il tentativo successivo avrà così un risultato concreto da verificare.
Uso online e distribuzione
Rispetta i limiti del progetto: giochi posseduti, preferenza per prove offline o ambienti autorizzati sotto il tuo controllo, senza aggirare anti-cheat, DRM o verifiche di proprietà. Il progetto vieta l'iniezione nei client online protetti. Un server privato non elimina le protezioni del client né le restrizioni dell'editore.
Prima di condividere, leggi le condizioni del gioco e le licenze di risorse e strumenti. La licenza MIT del kit non autorizza la redistribuzione di file del gioco, risorse estratte o sorgente decompilato. Distribuisci il tuo lavoro con istruzioni, versioni testate e procedura di rimozione.
Per la parte relativa al modello, consulta la guida di connessione a Claude Code e i prezzi attuali di OmniaKey. Configura questa connessione separatamente da fal e verifica il flusso della mod nel tuo ambiente.