Generador de recursos de juego que utiliza MCP y Hugging Face Spaces

Este proyecto es una herramienta innovadora que simplifica la creación de recursos de juegos aprovechando la generación impulsada por IA. Tanto si eres un desarrollador de juegos que busca prototipos rápidos como un entusiasta de la IA que explora modelos generativos, esta herramienta te permite crear recursos de juegos 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 los 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 .

Tabla de contenido

1. Descripción general del proyecto
2. Características
3. Cómo funciona
4. Prerrequisitos
5. Instalación
6. Uso
7. Configuración
8. Gestión de archivos
9. Integración MCP
10. Solución de problemas
11. Avanzado
12. Contribuyendo
13. Licencia

Descripción general del proyecto

El Generador de Recursos de Juego (versión 0.3.0 ) utiliza IA para optimizar la creación de recursos de juego. Permite generar recursos 2D (p. ej., sprites de pixel art) y 3D (p. ej., 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 incorpora compatibilidad con múltiples espacios de generación de modelos 3D ( InstantMesh , Hunyuan3D-2 y Hunyuan3D-2mini-Turbo , lo que ofrece flexibilidad y un rendimiento mejorado. Desarrollado 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 recursos.

Características

• Generación de activos 2D : crea pixel art, sprites u otros activos 2D a partir de indicaciones de texto (por ejemplo, "espada de pixel art").
• Generación de activos 3D : genere 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 variados flujos de trabajo de generación 3D.
• Integración con MCP : interactúe 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 de assets local con URI de recursos (por ejemplo, asset://{type}/{id} ).
• Validación de entrada robusta : utiliza Zod para un procesamiento de entrada seguro y confiable.
• Soporte multicliente : maneja múltiples conexiones simultáneas a través del transporte SSE .
• Acceso remoto seguro : soporte HTTPS opcional para comunicación remota segura.
• Backend extensible : diseño modular para una fácil integración de nuevos modelos o funciones.
• Multiplataforma : compatible con Windows, macOS y Linux mediante Node.js.
• Generación 3D configurable : personalice parámetros como los pasos de inferencia, la escala de guía y el modo turbo a través de variables de entorno.

Cómo funciona

El generador de recursos de juego transforma las indicaciones de texto en recursos listos para el juego a través de un proceso automatizado:

1. Entrada del usuario : envíe un mensaje de texto (por ejemplo, "espada de pixel art" o "castillo 3D isométrico").
2. Servidor MCP : dirige el mensaje a la herramienta adecuada ( generate_2d_asset o generate_3d_asset ).
3. Interacción del modelo de IA :
   • Activos 2D : utiliza la API de inferencia de rostros abrazados con "gokaygokay/Flux-2D-Game-Assets-LoRA" (50 pasos).
   • Activos 3D :
     • Genera una imagen inicial utilizando "gokaygokay/Flux-Game-Assets-LoRA-v2" (30 pasos).
     • Convierte la imagen en un modelo 3D utilizando uno de los siguientes:
       • InstantMesh : proceso de varios 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.
4. Salida de archivo : guarda los activos (PNG para 2D, OBJ/GLB para 3D) en el directorio assets .
5. Respuesta : Devuelve las URI de recursos (por ejemplo, asset://3d_model/filename.glb ) para su uso inmediato.

Diagrama de flujo de trabajo

Las indicaciones se mejoran automáticamente con "objeto completo, muy detallado, sin cortes y con fondo blanco sólido" para lograr una calidad óptima.

Prerrequisitos

• Node.js : Versión 16+ (incluye npm ).
• Git : para clonar el repositorio.
• Acceso a Internet : necesario para la conectividad de la API Hugging Face.
• Cuenta Hugging Face : necesaria para el acceso a la API; obtenga su token en huggingface.co/settings/tokens .
• Paquetes NPM :
  • @gradio/client : Interactúa con espacios de caras abrazadas.
  • @huggingface/inference : Para inferencia directa del modelo.
  • @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 mejor interacción.

Instalación

1. Clonar el repositorio :
   git clone https://github.com/yourusername/game-asset-mcp.git cd game-asset-mcp
2. Instalar dependencias :
   npm install
3. Configurar entorno :
   • Copie el archivo .env de ejemplo:
     cp .env.example .env
   • Edita el .env con tu token de API de Hugging Face y el MODEL_SPACE duplicado. Consulta la configuración para obtener más información.
4. 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 (consulte ssl/README.md ).

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

Uso

Interactúe con el servidor a través de un cliente MCP (por ejemplo, Claude Desktop) o mediante programación:

• 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 URI. 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 (ver Configuración ), escriba los comandos directamente en la interfaz.

Configuración

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

Configuraciones requeridas

• HF_TOKEN : Token de API de cara abrazada.
  HF_TOKEN=your_hf_token
• MODEL_SPACE : Su espacio de modelo 3D duplicado (por ejemplo, your-username/InstantMesh ).
  • Duplica uno de:
    • Malla instantánea
    • Hunyuan3D-2
    • Hunyuan3D-2mini-Turbo GXP10

Configuración opcional del modelo 3D

Valores predeterminados específicos del espacio

• Malla instantánea :
  • Pasos: 30-75 (predeterminado: 75)
  • Semilla: Predeterminado 42
• Hunyuan3D-2 :
  • Pasos: 20-50 (predeterminado: 20)
  • Escala de orientación: valor predeterminado 5,5
  • Resolución de Octree: 256 , 384 , 512 (predeterminado: 256 )
  • Semilla: Predeterminado 1234
• Hunyuan3D-2mini-Turbo :
  • Pasos: 1-100 (predeterminado: 5 para Turbo , 10 para Fast , 20 para Standard )
  • Escala de orientación: valor predeterminado 5.0
  • Resolución de Octree: 16-512 (predeterminado: 256)
  • Semilla: Predeterminado 1234

Configuración de transporte

• PUERTO : puerto de transporte SSE (predeterminado: 3000).
  PORT=3000

Configuración del escritorio de Claude

Editar el archivo de configuración:

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

Reinicie 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 nomenclatura : los archivos utilizan un prefijo, un nombre de herramienta, una marca de tiempo y una identificación única (por ejemplo, 2d_asset_generate_2d_asset_1698765432_abcd1234.png ).
• Personalización : Establezca un directorio personalizado:
  node src/index.js /path/to/custom/directory
• Acceso a recursos : utilice URI de MCP (por ejemplo, asset://2d_asset/filename.png ) para enumerar o leer activos.

Integración MCP

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

• Herramientas : generate_2d_asset , generate_3d_asset .
• Recursos : administrados a través de URI asset:// .
• Indicaciones : generate_2d_sprite , generate_3d_model .
• Compatibilidad : funciona con Claude Desktop y otros clientes MCP.

Solución de problemas

• Errores de API : Verifique la conectividad de la red o los límites de velocidad; revise ./logs/server.log .
• Problemas de autenticación : verificar HF_TOKEN y MODEL_SPACE en .env .
• Error de módulos ES : Asegúrese de Node.js 16+ ( node --version ).
• Registros : Inspeccionar 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 de activos 3D : utiliza "gokaygokay/Flux-Game-Assets-LoRA-v2" (30 pasos).
• Conversión de modelos 3D :
  • InstantMesh : Multipaso ( /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.

Control de versiones

• Versión actual : 0.3.0 (se agregó soporte para Hunyuan3D-2mini-Turbo).
• Versión del SDK de MCP : 1.7.0.
• Formato : MAYOR.MENOR.PARCHE (SemVer).

Arquitectura de backend

• Archivo principal : src/index.js .
• Dependencias : ver package.json .
• Seguridad : validación de Zod, prevención de cruce de ruta, compatibilidad con HTTPS, limitación de velocidad.
• Rendimiento : procesamiento asincrónico, reintento con retroceso, manejo de cuota de GPU.

Contribuyendo

¡Agradecemos sus contribuciones! Para participar:

1. Bifurcar el repositorio : crea tu copia en GitHub.
2. Realizar cambios : agregar funciones, corregir errores o mejorar documentos.
3. Enviar una solicitud de extracción : detalle sus cambios.
4. Problemas abiertos : informar errores o sugerir mejoras.

Siga las convenciones de codificación estándar e incluya pruebas cuando corresponda.

Licencia

Licencia MIT . Consulte el archivo de licencia para más detalles.