Game Asset Generator

Gere ativos de jogos 2D e 3D usando modelos de IA hospedados no Hugging Face Spaces.

Documentação

O proprietário do projeto analisará este repositório em breve, espere uma atualização em JUNHO de 2026

Game Asset Generator usando MCP e Hugging Face Spaces

Este projeto é uma ferramenta inovadora que simplifica a criação de assets de jogos por meio da geração impulsionada por IA. Seja você um desenvolvedor de jogos em busca de protótipos rápidos ou um entusiasta de IA explorando modelos generativos, esta ferramenta permite criar assets de jogos 2D e 3D a partir de prompts de texto sem esforço. Ela integra modelos de IA do Hugging Face Spaces—alimentados por "gokaygokay/Flux-2D-Game-Assets-LoRA", "gokaygokay/Flux-Game-Assets-LoRA-v2" e um dos três espaços de geração de modelos 3D (InstantMesh, Hunyuan3D-2 ou Hunyuan3D-2mini-Turbo, que você deve duplicar para sua conta)—e usa o Model Context Protocol (MCP) para interação perfeita com assistentes de IA como o Claude Desktop.

Visão Geral do Projeto

O Game Asset Generator (versão 0.3.0) utiliza IA para simplificar a criação de assets de jogos. Ele suporta a geração de assets 2D (por exemplo, sprites em pixel art) e assets 3D (por exemplo, modelos OBJ e GLB) a partir de prompts de texto, integrando-se ao Hugging Face Spaces e ao Model Context Protocol (MCP). Esta versão introduz suporte a múltiplos espaços de geração de modelos 3D—InstantMesh, Hunyuan3D-2 e Hunyuan3D-2mini-Turbo—oferecendo flexibilidade e desempenho aprimorado. Construído com Node.js e o MCP TypeScript SDK (v1.7.0), fornece uma solução robusta e multiplataforma para geração de assets.

Recursos

Geração de Assets 2D: Crie pixel art, sprites ou outros assets 2D a partir de prompts de texto (por exemplo, "espada em pixel art").
Geração de Assets 3D: Gere modelos 3D (formatos OBJ e GLB) a partir de descrições de texto, com conversão automática de imagem para modelo.
Múltiplos Espaços de Modelos 3D: Suporta InstantMesh, Hunyuan3D-2 e Hunyuan3D-2mini-Turbo para fluxos de trabalho variados de geração 3D.
Integração MCP: Interaja perfeitamente com a ferramenta por meio de clientes compatíveis com MCP, como o Claude Desktop.
Gerenciamento de Arquivos: Salva e organiza automaticamente os assets em um diretório local assets com URIs de recursos (por exemplo, asset://{type}/{id}).
Validação Robusta de Entrada: Usa Zod para processamento seguro e confiável de entradas.
Suporte a Múltiplos Clientes: Lida com múltiplas conexões simultâneas via transporte SSE.
Acesso Remoto Seguro: Suporte opcional a HTTPS para comunicação remota segura.
Backend Extensível: Design modular para fácil integração de novos modelos ou recursos.
Multiplataforma: Compatível com Windows, macOS e Linux usando Node.js.
Geração 3D Configurável: Personalize parâmetros como etapas de inferência, escala de orientação e modo turbo por meio de variáveis de ambiente.

Como Funciona

O Game Asset Generator transforma prompts de texto em assets prontos para jogos por meio de um pipeline automatizado:

Entrada do Usuário: Envie um prompt de texto (por exemplo, "espada em pixel art" ou "castelo 3D isométrico").
Servidor MCP: Roteia o prompt para a ferramenta apropriada (generate_2d_asset ou generate_3d_asset).
Interação com Modelos de IA:
- Assets 2D: Utiliza a Hugging Face Inference API com "gokaygokay/Flux-2D-Game-Assets-LoRA" (50 etapas).
- Assets 3D:
  - Gera uma imagem inicial usando "gokaygokay/Flux-Game-Assets-LoRA-v2" (30 etapas).
  - Converte a imagem em um modelo 3D usando um dos seguintes:
    - InstantMesh: Processo de múltiplas etapas (/preprocess, /generate_mvs, /make3d).
    - Hunyuan3D-2: Processo de etapa única (/generation_all).
    - Hunyuan3D-2mini-Turbo: Processo de etapa única (/generation_all) com modos turbo configuráveis.
Saída de Arquivos: Salva os assets (PNG para 2D, OBJ/GLB para 3D) no diretório assets.
Resposta: Retorna URIs de recursos (por exemplo, asset://3d_model/filename.glb) para uso imediato.

Diagrama do Fluxo de Trabalho

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

Os prompts são automaticamente aprimorados com "alto detalhamento, objeto completo, sem cortes, fundo branco sólido" para qualidade ideal.

Pré-requisitos

Node.js: Versão 16+ (inclui npm).
Git: Para clonar o repositório.
Acesso à Internet: Necessário para conectividade com a API do Hugging Face.
Conta Hugging Face: Necessária para acesso à API; obtenha seu token em huggingface.co/settings/tokens.
Pacotes NPM:
- @gradio/client: Interage com o Hugging Face Spaces.
- @huggingface/inference: Para inferência direta de modelos.
- @modelcontextprotocol/sdk: Implementa o servidor MCP.
- dotenv: Carrega variáveis de ambiente.
- express: Habilita o transporte SSE.
- zod: Garante validação de entrada.
- sharp: Lida com processamento de imagens.
Opcional: Claude Desktop (ou outro cliente MCP) para interação aprimorada.

Instalação

Clone o Repositório:

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

Instale as Dependências:
```
npm install
```
Configure o Ambiente:
- Copie o arquivo de exemplo .env:
```
cp .env.example .env
```
- Edite .env com seu token da API Hugging Face e o MODEL_SPACE duplicado. Consulte Configuração para detalhes.
Execute o Servidor:
- Local (transporte stdio):
```
npm start
```
- Diretório de Trabalho Personalizado:
```
node src/index.js /path/to/directory
```
- Remoto (transporte SSE):
```
node src/index.js --sse
```
- Remoto com HTTPS:
```
node src/index.js --sse --https
```
  Requer ssl/key.pem e ssl/cert.pem (consulte ssl/README.md).

Nota: Usa módulos ES ("type": "module" em package.json). Certifique-se de que o Node.js 16+ esteja instalado (node --version).

Uso

Interaja com o servidor por meio de um cliente MCP (por exemplo, Claude Desktop) ou programaticamente:

Gerar um Asset 2D:
- Comando: generate_2d_asset prompt:"pixel art sword"
- Saída: Salva um arquivo PNG (por exemplo, 2d_asset_generate_2d_asset_1698765432.png) e retorna seu URI.
Gerar um Asset 3D:
- Comando: generate_3d_asset prompt:"isometric 3D castle"
- Saída: Salva arquivos OBJ/GLB e imagens intermediárias, retornando seus URIs. Fornece um ID de operação para tarefas de longa duração.

Exemplos de Prompts

Interação Natural:
- generate_2d_sprite prompt:"pixel art sword"
- generate_3d_model prompt:"isometric 3D castle"

Com o Claude Desktop

Após a configuração (consulte Configuração), digite comandos diretamente na interface.

Configuração

Personalize o servidor por meio do arquivo .env:

Configurações Obrigatórias

HF_TOKEN: Token da API Hugging Face.
```
HF_TOKEN=your_hf_token
```
MODEL_SPACE: Seu espaço de modelo 3D duplicado (por exemplo, your-username/InstantMesh).
- Duplique um dos seguintes:
```
MODEL_SPACE=your-username/InstantMesh
```

Configurações Opcionais do Modelo 3D

Variável	Descrição	Intervalo Válido/Padrão
`MODEL_3D_STEPS`	Etapas de inferência	Varia por espaço (veja abaixo)
`MODEL_3D_GUIDANCE_SCALE`	Quão próximo o modelo segue o prompt	0.0-100.0 (padrão: 5.0-5.5)
`MODEL_3D_OCTREE_RESOLUTION`	Nível de detalhe do modelo 3D	Varia por espaço (veja abaixo)
`MODEL_3D_SEED`	Controle de aleatoriedade	0-10000000 (padrão: varia)
`MODEL_3D_REMOVE_BACKGROUND`	Remove o fundo da imagem	`true`/`false` (padrão: `true`)
`MODEL_3D_TURBO_MODE`	Modo de geração (apenas Hunyuan3D-2mini-Turbo)	`Turbo`, `Fast`, `Standard` (padrão: `Turbo`)
`MODEL_SPACE_TYPE`	Substitui a detecção de tipo de espaço	`instantmesh`, `hunyuan3d`, `hunyuan3d_mini_turbo`

Padrões Específicos por Espaço

InstantMesh:
- Etapas: 30-75 (padrão: 75)
- Seed: Padrão 42
Hunyuan3D-2:
- Etapas: 20-50 (padrão: 20)
- Escala de Orientação: Padrão 5.5
- Resolução de Octree: 256, 384, 512 (padrão: 256)
- Seed: Padrão 1234
Hunyuan3D-2mini-Turbo:
- Etapas: 1-100 (padrão: 5 para Turbo, 10 para Fast, 20 para Standard)
- Escala de Orientação: Padrão 5.0
- Resolução de Octree: 16-512 (padrão: 256)
- Seed: Padrão 1234

Configurações de Transporte

PORT: Porta do transporte SSE (padrão: 3000).
```
PORT=3000
```

Configuração do Claude Desktop

Edite o arquivo de configuração:

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"]
    }
  }
}

Reinicie o Claude Desktop após a edição.

Gerenciamento de Arquivos

Local de Armazenamento: Os assets são salvos em ./assets dentro do diretório de trabalho.
Convenção de Nomenclatura: Os arquivos usam um prefixo, nome da ferramenta, timestamp e ID exclusivo (por exemplo, 2d_asset_generate_2d_asset_1698765432_abcd1234.png).
Personalização: Defina um diretório personalizado:
```
node src/index.js /path/to/custom/directory
```
Acesso a Recursos: Use URIs MCP (por exemplo, asset://2d_asset/filename.png) para listar ou ler assets.

Integração MCP

O Model Context Protocol (MCP) permite que esta ferramenta atenda clientes de IA com segurança:

Ferramentas: generate_2d_asset, generate_3d_asset.
Recursos: Gerenciados por meio de URIs asset://.
Prompts: generate_2d_sprite, generate_3d_model.
Compatibilidade: Funciona com Claude Desktop e outros clientes MCP.

Solução de Problemas

Erros de API: Verifique a conectividade de rede ou limites de taxa; revise ./logs/server.log.
Problemas de Autenticação: Verifique HF_TOKEN e MODEL_SPACE em .env.
Erro de Módulos ES: Certifique-se de que o Node.js 16+ esteja instalado (node --version).
Logs: Inspecione logs detalhados:
```
tail -f ./logs/server.log
```

Avançado

Endpoints de API e Integração

Geração de Assets 2D: Usa "gokaygokay/Flux-2D-Game-Assets-LoRA" (50 etapas).
Geração de Imagem para Assets 3D: Usa "gokaygokay/Flux-Game-Assets-LoRA-v2" (30 etapas).
Conversão de Modelos 3D:
- InstantMesh: Múltiplas etapas (/check_input_image, /preprocess, /generate_mvs, /make3d).
- Hunyuan3D-2: Etapa única (/generation_all).
- Hunyuan3D-2mini-Turbo: Etapa única (/generation_all) com modos turbo.

Versionamento

Versão Atual: 0.3.0 (Adicionado suporte ao Hunyuan3D-2mini-Turbo).
Versão do MCP SDK: 1.7.0.
Formato: MAJOR.MINOR.PATCH (SemVer).

Arquitetura do Backend

Arquivo Principal: src/index.js.
Dependências: Consulte package.json.
Segurança: Validação Zod, prevenção de travessia de caminho, suporte a HTTPS, limitação de taxa.
Desempenho: Processamento assíncrono, nova tentativa com backoff, gerenciamento de cota de GPU.

Contribuindo

Aceitamos contribuições! Para participar:

Faça um Fork do Repositório: Crie sua cópia no GitHub.
Faça Alterações: Adicione recursos, corrija bugs ou melhore a documentação.
Envie um Pull Request: Detalhe suas alterações.
Abra Issues: Relate bugs ou sugira melhorias.

Siga as convenções de codificação padrão e inclua testes quando aplicável.

Licença

Licenciado sob a MIT License. Consulte o arquivo LICENSE para detalhes.