Game Asset Generator

Genera activos de juegos en 2D y 3D utilizando modelos de IA alojados en Hugging Face Spaces.

Documentación

El propietario del proyecto revisará este repositorio pronto, espera una actualización en JUNIO de 2026

Generador de Activos de Juego usando MCP y Hugging Face Spaces

Este proyecto es una herramienta innovadora que simplifica la creación de activos de juego aprovechando la generación impulsada por IA. Ya seas un desarrollador de juegos que busca prototipos rápidos o un entusiasta de la IA que explora modelos generativos, esta herramienta te permite crear activos de juego 2D y 3D a partir de indicaciones de texto sin esfuerzo. Integra modelos de IA de Hugging Face Spaces, impulsados por "gokaygokay/Flux-2D-Game-Assets-LoRA", "gokaygokay/Flux-Game-Assets-LoRA-v2" y uno de tres espacios de generación de modelos 3D (InstantMesh, Hunyuan3D-2 o Hunyuan3D-2mini-Turbo, que debes duplicar en tu cuenta), y utiliza el Protocolo de Contexto de Modelo (MCP) para una interacción fluida con asistentes de IA como Claude Desktop.

Descripción General del Proyecto

El Generador de Activos de Juego (versión 0.3.0) aprovecha la IA para optimizar la creación de activos de juego. Admite la generación de activos 2D (por ejemplo, sprites de arte pixelado) y activos 3D (por ejemplo, modelos OBJ y GLB) a partir de indicaciones de texto, integrándose con Hugging Face Spaces y el Protocolo de Contexto de Modelo (MCP). Esta versión introduce soporte para múltiples espacios de generación de modelos 3D—InstantMesh, Hunyuan3D-2 y Hunyuan3D-2mini-Turbo—ofreciendo flexibilidad y rendimiento mejorado. Construido con Node.js y el SDK de TypeScript de MCP (v1.7.0), proporciona una solución robusta y multiplataforma para la generación de activos.

Características

Generación de Activos 2D: Crea arte pixelado, sprites u otros activos 2D a partir de indicaciones de texto (por ejemplo, "espada de arte pixelado").
Generación de Activos 3D: Genera modelos 3D (formatos OBJ y GLB) a partir de descripciones de texto, con conversión automática de imagen a modelo.
Múltiples Espacios de Modelos 3D: Admite InstantMesh, Hunyuan3D-2 y Hunyuan3D-2mini-Turbo para diversos flujos de trabajo de generación 3D.
Integración MCP: Interactúa sin problemas con la herramienta a través de clientes compatibles con MCP como Claude Desktop.
Gestión de Archivos: Guarda y organiza automáticamente los activos en un directorio local assets con URIs de recursos (por ejemplo, asset://{type}/{id}).
Validación de Entrada Robusta: Utiliza Zod para un procesamiento de entrada seguro y confiable.
Soporte Multi-Cliente: Maneja múltiples conexiones simultáneas a través del transporte SSE.
Acceso Remoto Seguro: Soporte opcional de HTTPS para comunicación remota segura.
Backend Extensible: Diseño modular para facilitar la integración de nuevos modelos o características.
Multiplataforma: Compatible con Windows, macOS y Linux usando Node.js.
Generación 3D Configurable: Personaliza parámetros como pasos de inferencia, escala de guía y modo turbo a través de variables de entorno.

Cómo Funciona

El Generador de Activos de Juego transforma indicaciones de texto en activos listos para juegos a través de un proceso automatizado:

Entrada del Usuario: Envía una indicación de texto (por ejemplo, "espada de arte pixelado" o "castillo 3D isométrico").
Servidor MCP: Enruta la indicación a la herramienta apropiada (generate_2d_asset o generate_3d_asset).
Interacción con el Modelo de IA:
- Activos 2D: Utiliza la API de Inferencia de Hugging Face con "gokaygokay/Flux-2D-Game-Assets-LoRA" (50 pasos).
- Activos 3D:
  - Genera una imagen inicial usando "gokaygokay/Flux-Game-Assets-LoRA-v2" (30 pasos).
  - Convierte la imagen a un modelo 3D usando uno de:
    - InstantMesh: Proceso de múltiples pasos (/preprocess, /generate_mvs, /make3d).
    - Hunyuan3D-2: Proceso de un solo paso (/generation_all).
    - Hunyuan3D-2mini-Turbo: Proceso de un solo paso (/generation_all) con modos turbo configurables.
Salida de Archivos: Guarda los activos (PNG para 2D, OBJ/GLB para 3D) en el directorio assets.
Respuesta: Devuelve URIs de recursos (por ejemplo, asset://3d_model/filename.glb) para uso inmediato.

Diagrama del Flujo de Trabajo

User Prompt → MCP Server → AI Model(s) → Local File → Resource URI Response

Las indicaciones se mejoran automáticamente con "altamente detallado, objeto completo, no recortado, fondo blanco sólido" para una calidad óptima.

Requisitos Previos

Node.js: Versión 16+ (incluye npm).
Git: Para clonar el repositorio.
Acceso a Internet: Requerido para la conectividad con la API de Hugging Face.
Cuenta de Hugging Face: Necesaria para el acceso a la API; obtén tu token en huggingface.co/settings/tokens.
Paquetes NPM:
- @gradio/client: Interactúa con Hugging Face Spaces.
- @huggingface/inference: Para inferencia directa de modelos.
- @modelcontextprotocol/sdk: Implementa el servidor MCP.
- dotenv: Carga variables de entorno.
- express: Habilita el transporte SSE.
- zod: Asegura la validación de entrada.
- sharp: Maneja el procesamiento de imágenes.
Opcional: Claude Desktop (u otro cliente MCP) para una interacción mejorada.

Instalación

Clonar el Repositorio:

git clone https://github.com/yourusername/game-asset-mcp.git
cd game-asset-mcp

Instalar Dependencias:
```
npm install
```
Configurar el Entorno:
- Copia el archivo de ejemplo .env:
```
cp .env.example .env
```
- Edita .env con tu token de API de Hugging Face y el MODEL_SPACE duplicado. Consulta Configuración para más detalles.
Ejecutar el Servidor:
- Local (transporte stdio):
```
npm start
```
- Directorio de Trabajo Personalizado:
```
node src/index.js /path/to/directory
```
- Remoto (transporte SSE):
```
node src/index.js --sse
```
- Remoto con HTTPS:
```
node src/index.js --sse --https
```
  Requiere ssl/key.pem y ssl/cert.pem (consulta ssl/README.md).

Nota: Utiliza módulos ES ("type": "module" en package.json). Asegúrate de tener Node.js 16+ instalado (node --version).

Uso

Interactúa con el servidor a través de un cliente MCP (por ejemplo, Claude Desktop) o programáticamente:

Generar un Activo 2D:
- Comando: generate_2d_asset prompt:"pixel art sword"
- Salida: Guarda un archivo PNG (por ejemplo, 2d_asset_generate_2d_asset_1698765432.png) y devuelve su URI.
Generar un Activo 3D:
- Comando: generate_3d_asset prompt:"isometric 3D castle"
- Salida: Guarda archivos OBJ/GLB e imágenes intermedias, devolviendo sus URIs. Proporciona un ID de operación para tareas de larga duración.

Ejemplos de Indicaciones

Interacción Natural:
- generate_2d_sprite prompt:"pixel art sword"
- generate_3d_model prompt:"isometric 3D castle"

Con Claude Desktop

Después de configurar (consulta Configuración), escribe comandos directamente en la interfaz.

Configuración

Personaliza el servidor a través del archivo .env:

Configuración Requerida

HF_TOKEN: Token de API de Hugging Face.
```
HF_TOKEN=your_hf_token
```
MODEL_SPACE: Tu espacio de modelo 3D duplicado (por ejemplo, your-username/InstantMesh).
- Duplica uno de:
```
MODEL_SPACE=your-username/InstantMesh
```

Configuración Opcional del Modelo 3D

Variable	Descripción	Rango Válido/Valor Predeterminado
`MODEL_3D_STEPS`	Pasos de inferencia	Varía según el espacio (ver abajo)
`MODEL_3D_GUIDANCE_SCALE`	Qué tan cerca sigue el modelo la indicación	0.0-100.0 (predeterminado: 5.0-5.5)
`MODEL_3D_OCTREE_RESOLUTION`	Nivel de detalle del modelo 3D	Varía según el espacio (ver abajo)
`MODEL_3D_SEED`	Control de aleatoriedad	0-10000000 (predeterminado: varía)
`MODEL_3D_REMOVE_BACKGROUND`	Eliminar fondo de imagen	`true`/`false` (predeterminado: `true`)
`MODEL_3D_TURBO_MODE`	Modo de generación (solo Hunyuan3D-2mini-Turbo)	`Turbo`, `Fast`, `Standard` (predeterminado: `Turbo`)
`MODEL_SPACE_TYPE`	Anular detección de tipo de espacio	`instantmesh`, `hunyuan3d`, `hunyuan3d_mini_turbo`

Valores Predeterminados Específicos del Espacio

InstantMesh:
- Pasos: 30-75 (predeterminado: 75)
- Semilla: Predeterminada 42
Hunyuan3D-2:
- Pasos: 20-50 (predeterminado: 20)
- Escala de Guía: Predeterminada 5.5
- Resolución de Octree: 256, 384, 512 (predeterminado: 256)
- Semilla: Predeterminada 1234
Hunyuan3D-2mini-Turbo:
- Pasos: 1-100 (predeterminado: 5 para Turbo, 10 para Fast, 20 para Standard)
- Escala de Guía: Predeterminada 5.0
- Resolución de Octree: 16-512 (predeterminado: 256)
- Semilla: Predeterminada 1234

Configuración del Transporte

PORT: Puerto del transporte SSE (predeterminado: 3000).
```
PORT=3000
```

Configuración de Claude Desktop

Edita el archivo de configuración:

MacOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "game-asset-generator": {
      "command": "node",
      "args": ["/full/path/to/game-asset-mcp/src/index.js"]
    }
  }
}

Reinicia Claude Desktop después de editar.

Gestión de Archivos

Ubicación de Almacenamiento: Los activos se guardan en ./assets dentro del directorio de trabajo.
Convención de Nombres: Los archivos usan un prefijo, nombre de herramienta, marca de tiempo e ID único (por ejemplo, 2d_asset_generate_2d_asset_1698765432_abcd1234.png).
Personalización: Establece un directorio personalizado:
```
node src/index.js /path/to/custom/directory
```
Acceso a Recursos: Usa URIs de MCP (por ejemplo, asset://2d_asset/filename.png) para listar o leer activos.

Integración MCP

El Protocolo de Contexto de Modelo (MCP) permite que esta herramienta sirva a clientes de IA de forma segura:

Herramientas: generate_2d_asset, generate_3d_asset.
Recursos: Gestionados a través de URIs asset://.
Indicaciones: generate_2d_sprite, generate_3d_model.
Compatibilidad: Funciona con Claude Desktop y otros clientes MCP.

Solución de Problemas

Errores de API: Verifica la conectividad de red o los límites de tasa; revisa ./logs/server.log.
Problemas de Autenticación: Verifica HF_TOKEN y MODEL_SPACE en .env.
Error de Módulos ES: Asegúrate de tener Node.js 16+ (node --version).
Registros: Inspecciona los registros detallados:
```
tail -f ./logs/server.log
```

Avanzado

Puntos Finales de API e Integración

Generación de Activos 2D: Utiliza "gokaygokay/Flux-2D-Game-Assets-LoRA" (50 pasos).
Generación de Imágenes para Activos 3D: Utiliza "gokaygokay/Flux-Game-Assets-LoRA-v2" (30 pasos).
Conversión de Modelos 3D:
- InstantMesh: Multi-paso (/check_input_image, /preprocess, /generate_mvs, /make3d).
- Hunyuan3D-2: Un solo paso (/generation_all).
- Hunyuan3D-2mini-Turbo: Un solo paso (/generation_all) con modos turbo.

Versionado

Versión Actual: 0.3.0 (Se agregó soporte para Hunyuan3D-2mini-Turbo).
Versión del SDK de MCP: 1.7.0.
Formato: MAJOR.MINOR.PATCH (SemVer).

Arquitectura del Backend

Archivo Principal: src/index.js.
Dependencias: Consulta package.json.
Seguridad: Validación Zod, prevención de recorrido de rutas, soporte HTTPS, limitación de tasa.
Rendimiento: Procesamiento asíncrono, reintento con retroceso, manejo de cuotas de GPU.

Contribuciones

¡Damos la bienvenida a las contribuciones! Para participar:

Haz un Fork del Repositorio: Crea tu copia en GitHub.
Haz Cambios: Agrega características, corrige errores o mejora la documentación.
Envía una Solicitud de Extracción: Detalla tus cambios.
Abre Problemas: Reporta errores o sugiere mejoras.

Sigue las convenciones de codificación estándar e incluye pruebas cuando corresponda.

Licencia

Licenciado bajo la Licencia MIT. Consulta el archivo LICENCIA para más detalles.