Communitygithub.com

Ativos 3D para Jogos

Quando um jogo 3D precisa de ativos GLB concretos e reconhecíveis, em vez de apenas geometria primitiva, esta skill gerencia todo o fluxo: escolha da rota, geração de um conjunto focado, escrita/leitura do `asset_manifest.json` e integração dos GLBs com fallbacks.

O que é Ativos 3D para Jogos?

Esta skill capacita agentes de IA (como Claude Code, Cursor, Codex) a gerar e integrar ativos 3D prontos para jogos no formato GLB, substituindo a geometria primitiva por modelos reconhecíveis. Ela suporta duas rotas principais: `tripo` para geração rápida a partir de texto (ideal para props genéricos, inimigos, colecionáveis) e `gemini_reference` para controle visual (usa Gemini para criar uma imagem de referência, depois faz a conversão para modelo 3D). O fluxo prioriza os ativos mais importantes (jogador, inimigo crítico, colecionável) em lotes de 1 a 3, lê/atualiza o arquivo `asset_manifest.json` como fonte da verdade e integra os GLBs no código do jogo usando `GLTFLoader` com fallbacks primitivos. Em caso de falha (API indisponível, saldo Tripo zerado, chave Gemini faltando), a skill mantém a jogabilidade com geometria primitiva e registra o ocorrido no README. A skill também gerencia animações nativas ou procedurais (bob/tilt/rotação) e normaliza os modelos (escala, centralização, posição em y=0) para integração consistente.

Funciona com~Claude Code✓Codex CLI~Cursor✓Gemini CLI
npx skills add 674345386/agent-skills

Perguntar na sua IA favorita

Abre um novo chat com esta habilidade de agente já pré-carregada.

Documentação

O que Ativos 3D para Jogos faz?

Use esta skill quando um jogo 3D precisar de ativos GLB concretos e reconhecíveis, em vez de apenas geometria primitiva. A skill gerencia todo o fluxo: escolha da rota, geração de um conjunto focado de ativos, escrita/leitura do asset_manifest.json e integração dos GLBs no jogo com fallbacks.

Comportamento obrigatório

  • Se o prompt do jogo contiver entidades explícitas ou implícitas, como um jogador, personagem, inimigo, colecionável, veículo, arma, obstáculo, chefe, mascote, objeto chave ou objeto de ambiente, a geração de GLB é uma etapa obrigatória quando a ferramenta estiver disponível.
  • Gere apenas 1 a 3 ativos principais por padrão. Priorize o jogador/personagem principal primeiro, depois o inimigo crítico para a jogabilidade, colecionável, veículo, perigo ou objeto chave. Não gere enchimento decorativo.
  • Use geometria primitiva do Three.js apenas como espaço reservado provisório enquanto os ativos estão pendentes e como fallback em tempo de execução se um GLB falhar ao carregar.
  • Não regenere ativos existentes a menos que o usuário peça explicitamente. Se o asset_manifest.json já tiver ativos carregáveis, reutilize-o.
  • Evite personagens protegidos por direitos autorais, marcas registradas, logotipos e semelhanças com celebridades. Reescreva em designs originais.

Escolha da rota

Use tripo para a rota rápida: prompt de texto direto para modelo 3D do Tripo3D. Esta é a melhor opção para props genéricos, inimigos, colecionáveis, veículos, obstáculos e iteração rápida.

Use gemini_reference quando o controle visual for importante: Gemini primeiro cria uma imagem de referência com fundo branco puro, depois o Tripo image-to-model cria o GLB. Prefira esta rota quando o usuário mencionar Gemini, Nano Banana, posição T, fundo branco, imagem de referência, image-to-model, ficha de personagem, consistência de estilo ou quando a silhueta de um personagem chave precisar ser controlada.

Use auto apenas quando você estiver confortável com o servidor escolhendo a partir do prompt. Em caso de dúvida, escolha a rota você mesmo e passe-a explicitamente.

Ambiente

O cliente de geração está incluído nesta skill em scripts/game-assets-mcp.mjs (Node >= 20, zero dependências). Ele se comunica com a API de ativos remota padrão em http://54.81.110.182:3001.

  • GAME_ASSETS_API_URL — substituição opcional para a URL base da API de ativos
  • GAME_ASSETS_API_TOKEN — token de acesso por usuário

Se o token estiver faltando e o serviço exigir autenticação, peça ao usuário para definir GAME_ASSETS_API_TOKEN antes de gerar. Peça por GAME_ASSETS_API_URL apenas quando o usuário precisar substituir o serviço padrão. Nunca peça por chaves de API do Tripo ou Gemini; elas residem no servidor.

Fluxo de trabalho da ferramenta

Se ferramentas MCP chamadas mcp__game_assets__* estiverem disponíveis em sua sessão, prefira-as. Caso contrário, execute o cliente incluído via Bash. Ambos expõem as mesmas duas operações.

  1. Execute pwd se você ainda não souber o caminho do workspace atual.
  2. Se estiver planejando 3 ou mais ativos, ou se esta for a primeira geração de ativos no thread, verifique a prontidão (<skill-dir> é o diretório desta skill):
node <skill-dir>/scripts/game-assets-mcp.mjs readiness --cwd "$(pwd)"
  1. Gere de 1 a 3 ativos (máximo do lote: 4). Passe os parâmetros como um objeto JSON:
node <skill-dir>/scripts/game-assets-mcp.mjs generate --cwd "$(pwd)" --params '{
  "gamePrompt": "...",
  "route": "tripo",
  "assets": [{ "id": "...", "role": "player", "name": "...", "prompt": "..." }]
}'
  • route: tripo, gemini_reference ou auto.
  • assets: 1 a 3 objetos com id em kebab-case estável, role, name, prompt e opcionalmente assetKind.
  • force: apenas quando o usuário pediu explicitamente para regenerar ativos.
  • O comando bloqueia enquanto polla o job remoto (normalmente de 1 a 3 minutos por lote) e imprime um resultado JSON; código de saída 1 significa que o lote falhou.
  1. Após o comando retornar, leia o asset_manifest.json do cwd. Trate esse arquivo como a fonte da verdade.
  2. Integre manifest.assets no código do jogo com o GLTFLoader do Three.js.
  3. Mantenha um fallback primitivo local para cada ativo gerado. O jogo deve permanecer jogável quando um GLB falhar ao carregar.

Exemplo de JSON --params:

{
  "cwd": "/caminho/absoluto/para/projeto",
  "gamePrompt": "Corredor 3D com um gato astronauta coletando cristais e desviando de robôs patrulheiros",
  "route": "gemini_reference",
  "assets": [
    {
      "id": "gato-astronauta",
      "role": "player",
      "name": "Gato Astronauta",
      "assetKind": "character",
      "prompt": "herói gato astronauta low-poly original, capacete redondo, silhueta compacta e legível, terno azul e branco, personagem amigável de jogo arcade"
    },
    {
      "id": "cristal-de-energia",
      "role": "collectible",
      "name": "Cristal de Energia",
      "assetKind": "prop",
      "prompt": "cristal de energia facetado ciano brilhante para coleta, silhueta limpa, colecionável de jogo"
    }
  ]
}

Regras de integração em tempo de execução

  • Normalize cada GLB carregado com THREE.Box3().setFromObject(): dimensione para o tamanho alvo, centralize horizontalmente, coloque a parte inferior em y = 0 e aplique um deslocamento de orientação estável.
  • Separe os visuais das hitboxes de jogabilidade. A colisão deve usar dimensões de jogabilidade estáveis, não os limites brutos do modelo ou origens da malha.
  • Se manifest.assets contiver rigged, rigType ou animations, inspecione o gltf.animations carregado antes de afirmar que existe animação nativa.
  • Quando clipes nativos existirem, crie um THREE.AnimationMixer, mapeie clipes por substrings insensíveis a maiúsculas/minúsculas como idle, walk, run e jump, e chame mixer.update(delta) a cada quadro.
  • Se não existirem clipes nativos, use balanço/inclinação/rotação do grupo inteiro ou clipes procedurais explicitamente rotulados como animação de fallback.
  • Adicione uma seção curta no README.md chamada 3D Asset Pipeline ou 3D 素材流水线 descrevendo quais ativos foram gerados, qual rota foi usada e qual fonte de animação em tempo de execução é utilizada.

Tratamento de falhas

  • API de ativos inacessível (prontidão reporta unreachable): explique que a geração de modelos remota está indisponível, peça ao usuário para verificar o serviço de ativos padrão, acesso à rede e GAME_ASSETS_API_TOKEN se necessário; peça por GAME_ASSETS_API_URL apenas ao substituir o serviço padrão. Mantenha fallbacks primitivos e continue o jogo jogável.
  • Servidor sem chave Gemini na rota gemini_reference: mude para tripo se aceitável, ou informe ao usuário que o operador do servidor deve configurar a chave Gemini.
  • Saldo Tripo zerado: não tente novamente em loop. Mantenha fallbacks e registre a etapa ignorada no README.
  • Sucesso parcial: use os ativos gerados que tiveram sucesso e geometria de fallback para o restante.

Habilidades Relacionadas