Guía de Universal Modder
Crea un cambio pequeño y compruébalo dentro del juego.
Universal Modder es un conjunto de herramientas de código abierto que ayuda a los agentes de programación con IA a investigar, crear y probar mods para juegos de PC. Incluye habilidades, una CLI en Python llamada um, notas sobre juegos concretos y una integración con fal para generar recursos. El proyecto original es rehan-remade/universal-modder en GitHub (en inglés).
Empieza con un cambio pequeño en un juego que tengas: identifica el motor y el cargador de mods, protege una partida de prueba, crea la función con gráficos provisionales y compruébala en el juego. «Universal» describe la amplitud del enfoque; no garantiza que funcione con todos los juegos y versiones.
Fuentes revisadas el 9 de octubre de 2026, con el commit 8370faa y la versión 0.2.0 del paquete. Esta guía se basa en documentación y código fuente. No hemos ejecutado los mods de ejemplo ni verificado un flujo completo con OmniaKey. Las fuentes externas están en inglés.
Qué incluye y qué tienes que aportar
El README del proyecto distingue estos componentes:
| Componente | Para qué sirve | Qué necesitas aparte |
|---|---|---|
| Habilidades del agente | Orientar la investigación, implementación, preparación de recursos y pruebas | Un agente con acceso funcional a un modelo |
CLI um | Analizar instalaciones, procesar sprites, respaldar partidas y ayudar a grabar | Dependencias locales y herramientas del juego |
| Base de conocimiento | Recoger versiones, soluciones y fallos de proyectos anteriores | Verificar los datos con tu versión instalada |
| Integración con fal | Solicitar imágenes, recursos 3D, audio o vídeo | Una clave de fal y un presupuesto de uso propios |
El repositorio ofrece rutas de instalación para Claude Code, Codex, Cursor, Gemini CLI, Copilot y OpenCode. Son formas de integrar el agente, no garantías de que todas las operaciones funcionen en cualquier sistema operativo. Las herramientas de control de juegos de Windows se usan en Windows directamente o mediante WSL.
Cómo instalarlo en Claude Code
El README pide Git, Python 3.10 o posterior y ffmpeg, y recomienda uv. Blender hace falta para renderizar modelos 3D como sprites. Prepara las herramientas que requiera tu proyecto.
Introduce estos comandos dentro de Claude Code, en este orden:
/plugin marketplace add rehan-remade/universal-modder
/plugin install universal-modder@universal-modder
Son comandos de plugins de Claude Code, no del intérprete de comandos del sistema. Revisa el código y los permisos solicitados antes de activarlo. Para otro agente, sigue su apartado del README original.
El proyecto incluye un lanzador de la CLI para las instalaciones como plugin y los repositorios clonados. Si otra terminal no encuentra um, la instalación independiente documentada es:
uv tool install git+https://github.com/rehan-remade/universal-modder
um --help
Esto instala la CLI desde el repositorio; no configura por sí solo el agente ni la cuenta de fal. Hemos contrastado los comandos con las fuentes, pero no los hemos ejecutado para este artículo.
Examina el juego antes de modificarlo
Sustituye Terraria por el nombre del juego o su carpeta de instalación:
um scan --list
um kb search "Terraria"
um scan "Terraria" --json
La guía de reconocimiento explica que el analizador lee archivos y señala indicios del motor, cargadores instalados, ubicaciones de partidas y posibles métodos. Si el juego no aparece en la biblioteca, puedes indicar su carpeta directamente.
El análisis sirve para planificar; no certifica seguridad ni compatibilidad. Las protecciones pueden estar fuera de la carpeta del juego y un lanzador puede confundir la identificación del motor. Consulta también la documentación actual del cargador y la política de mods del juego.
Pide al agente que registre las versiones del juego y del cargador, rutas de partidas y registros, cambios previstos y método de restauración en MODDING_PLAN.md. Guarda el avance en MODLOG.md. Da prioridad a un cargador conocido o una interfaz oficial de mods si permiten realizar la idea.
Un primer encargo con criterios de aceptación
Elige una función pequeña y fácil de observar. Este ejemplo es una plantilla editorial, no un mod probado:
En mi entorno local de pruebas de Terraria, planifica un objeto decorativo nuevo para la versión instalada de tModLoader. Examina primero el juego y el cargador. Usa gráficos provisionales y un mundo desechable. Antes de modificar archivos, enumera las rutas afectadas y los pasos de copia de seguridad y restauración. Explica cómo obtener el objeto, comprobarlo en el juego y retirar el mod. Pregunta antes de generar recursos de pago o publicar algo.
El flujo del proyecto recomienda terminar una función mínima con recursos provisionales antes de ampliar el alcance. Puedes convertirlo en cinco comprobaciones:
- Carga: el juego arranca con el cargador previsto y el registro identifica el mod.
- Aparece: el objeto o cambio se ve en la escena de prueba indicada.
- Funciona: el comportamiento cumple lo pedido; compilar correctamente no basta.
- Se conserva: guardar y volver a cargar el mundo de prueba funciona como se espera.
- Se revierte: desactivar el mod y restaurar la copia devuelve el entorno al estado previsto.
Después puedes preparar los sprites definitivos, el sonido o el vídeo de presentación. Una imagen generada o una compilación correcta no demuestran por sí solas compatibilidad durante el juego.
Juegos con ejemplos en el repositorio
Son puntos de partida sujetos a versiones concretas. Las pruebas descritas por sus autores no sustituyen las de tu equipo.
- Terraria / tModLoader: Fal Arsenal procede de un proyecto para un jugador con Terraria 1.4.4 y tModLoader 2026.07. El README dice expresamente que el multijugador no está probado. Usa un mundo aparte.
- Age of Empires II DE: el ejemplo de civilización incluye gráficos generados y conversión de sprites. Ocupa una plaza de civilización existente; no demuestra que se puedan añadir plazas arbitrariamente.
- Minecraft × GTA V: combina dos juegos en ejecución dentro del modo historia de GTA V. La prueba documentada corresponde a GTA V Legacy en Steam, compilación 3889. No extiendas esa conclusión a GTA Online ni a otras ediciones.
Valora las pruebas en este orden: guía del motor → ejemplo con juego y versión → prueba propia dentro del juego. Una guía de Unity o Unreal no certifica todos los títulos que usan esos motores.
¿Es gratis y hace falta fal?
El código de las herramientas tiene licencia MIT. Un proyecto completo puede generar tres tipos de coste: acceso al modelo de programación, generación de recursos y hardware o herramientas locales para construir y probar.
fal tiene sus propias tarifas por modelo, que dependen del modelo y de los ajustes. Su documentación de autenticación utiliza FAL_KEY. Configura la clave real de forma privada en el entorno desde el que arrancas el agente. Los valores siguientes son marcadores de posición.
En Bash o Zsh:
export FAL_KEY="YOUR_FAL_API_KEY"
En Windows PowerShell:
$env:FAL_KEY = "YOUR_FAL_API_KEY"
Una credencial del modelo, incluida una clave de OmniaKey, no es una clave de fal. Instalar el plugin no unifica las facturas. Antes de autorizar una tanda, comprueba el modelo de recursos y la cantidad de generaciones. No incluyas claves en archivos del mod ni en paquetes publicados.
Puedes empezar con recursos provisionales o propios. La guía de recursos también documenta um comfy para obtener imágenes de un servidor local de ComfyUI sin clave de fal. Sus procedimientos de imagen no sustituyen todo el flujo de audio, 3D y vídeo de fal; debes preparar el hardware y los modelos locales.
Qué revisar cuando algo falla
Cambia una sola capa cada vez:
- No se encuentra
um: revisa PATH y la instalación independiente de la CLI antes de investigar el cargador. - No se detecta el juego: indica la carpeta y contrasta el análisis con la documentación actual de la comunidad.
- Falla la autenticación de fal: comprueba que el proceso del agente recibió
FAL_KEYde la cuenta correcta. Iniciar sesión en el agente no valida fal. - El mod compila pero no carga: revisa versiones, ruta de instalación y registro del cargador antes de regenerar recursos.
- Los gráficos se ven mal: comprueba dimensiones, transparencia, distribución de fotogramas y orientación antes de cambiar el prompt.
Guarda el registro del fallo y una reproducción mínima en las notas del proyecto. Así el siguiente intento tendrá una comprobación concreta.
Uso en línea y distribución
Respeta los límites del proyecto: juegos que poseas, pruebas sin conexión o entornos permitidos que controles, sin eludir sistemas antitrampas, DRM ni comprobaciones de propiedad. Sus reglas rechazan la inyección en clientes en línea protegidos. Un servidor privado no elimina las protecciones del cliente ni las restricciones del editor.
Antes de compartir, revisa las condiciones del juego y las licencias de recursos y herramientas. La licencia MIT del kit no concede derechos para redistribuir archivos del juego, recursos extraídos o código descompilado. Distribuye tu trabajo e indica instalación, versiones probadas y desinstalación.
Para la conexión del modelo, consulta la guía de conexión de Claude Code y las tarifas actuales de OmniaKey. Configúrala por separado de fal y valida después el flujo real del mod en tu entorno.