Communitygithub.com

activos-3d

Genera activos GLB concretos para juegos 3D (personajes, enemigos, coleccionables) usando Tripo3D o Gemini+Tripo, con respaldos primitivos y un manifiesto de activos.

¿Qué es activos-3d?

Esta habilidad es ideal para desarrolladores de juegos 3D que necesitan activos visuales reconocibles en formato GLB en lugar de simple geometría primitiva. Soporta plataformas como Claude Code, Cursor y Codex, y gestiona todo el flujo de trabajo desde la selección de la ruta de generación (Tripo3D para rapidez o Gemini+Tripo para control visual) hasta la integración en el código del juego. El sistema utiliza un manifiesto (`asset_manifest.json`) para evitar regenerar activos existentes, prioriza la generación de 1-3 activos clave por lote, y proporciona respaldos con geometría primitiva de Three.js si un GLB falla. También maneja fallos como API no disponible o saldo insuficiente, manteniendo el juego jugable. La habilidad incluye un cliente MCP empaquetado y recomienda herramientas MCP cuando están disponibles, o usa Bash como alternativa.

Compatible con~Claude Code✓Codex CLI~Cursor✓Gemini CLI
npx skills add 674345386/agent-skills

Preguntar en tu IA favorita

Abre un nuevo chat con esta habilidad de agente ya precargada.

Documentación

Activos 3D

Usa esta habilidad cuando un juego 3D necesite activos GLB concretos y reconocibles en lugar de solo geometría primitiva. La habilidad gestiona el flujo de trabajo completo: elegir la ruta, generar un conjunto pequeño y enfocado de activos, escribir/leer asset_manifest.json, y conectar los GLB en el juego con respaldos.

Comportamiento requerido

  • Si el prompt del juego contiene entidades explícitas o implícitas, como un jugador, personaje, enemigo, coleccionable, vehículo, arma, obstáculo, jefe, mascota, accesorio clave u objeto del entorno, la generación de GLB es una etapa requerida cuando la herramienta está disponible.
  • Genera solo 1-3 activos clave por defecto. Prioriza primero al jugador/personaje principal, luego al enemigo crítico para la jugabilidad, coleccionable, vehículo, peligro o accesorio clave. No generes relleno decorativo.
  • Usa geometría primitiva de Three.js solo como marcador de posición provisional mientras los activos están pendientes y como respaldo en tiempo de ejecución si un GLB falla al cargar.
  • No regeneres activos existentes a menos que el usuario lo solicite explícitamente. Si asset_manifest.json ya contiene activos cargables, reutilízalo.
  • Evita personajes con derechos de autor, nombres de marca, logotipos y apariencias de celebridades. Reescribe en diseños originales.

Elección de ruta

Usa tripo para la ruta rápida: prompt de texto directo a Tripo3D text-to-model. Esto es mejor para accesorios genéricos, enemigos, coleccionables, vehículos, obstáculos e iteración rápida.

Usa gemini_reference cuando el control visual importe: Gemini primero crea una imagen de referencia con fondo blanco puro, luego Tripo image-to-model crea el GLB. Prefiere esta ruta cuando el usuario mencione Gemini, Nano Banana, T-pose, fondo blanco, imagen de referencia, image-to-model, hoja de personaje, consistencia de estilo, o cuando la silueta de un personaje clave deba controlarse.

Usa auto solo cuando te sientas cómodo con que el servidor elija según el prompt. En caso de duda, elige la ruta tú mismo y pásala explícitamente.

Entorno

El cliente de generación está incluido con esta habilidad en scripts/game-assets-mcp.mjs (Node >= 20, cero dependencias). Se comunica con la API de activos remota predeterminada en http://54.81.110.182:3001.

  • GAME_ASSETS_API_URL — anulación opcional para la URL base de la API de activos
  • GAME_ASSETS_API_TOKEN — token de acceso por usuario

Si falta el token y el servicio requiere autenticación, pide al usuario que establezca GAME_ASSETS_API_TOKEN antes de generar. Solo pregunta por GAME_ASSETS_API_URL cuando el usuario necesite anular el servicio predeterminado. Nunca pidas claves de API de Tripo o Gemini; residen en el servidor.

Flujo de trabajo de la herramienta

Si las herramientas MCP llamadas mcp__game_assets__* están disponibles en tu sesión, prefierelas. De lo contrario, ejecuta el cliente incluido a través de Bash. Ambos exponen las mismas dos operaciones.

  1. Ejecuta pwd si aún no conoces la ruta del espacio de trabajo actual.
  2. Si planeas 3 o más activos, o si esta es la primera generación de activos en el hilo, verifica la disponibilidad (<skill-dir> es el directorio de esta habilidad):
node <skill-dir>/scripts/game-assets-mcp.mjs readiness --cwd "$(pwd)"
  1. Genera 1-3 activos (máximo de lote 4). Pasa los parámetros como un 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 o auto.
  • assets: 1-3 objetos con id en kebab-case estable, role, name, prompt y opcionalmente assetKind.
  • force: solo cuando el usuario pidió explícitamente regenerar activos.
  • El comando bloquea mientras sondea el trabajo remoto (normalmente 1-3 minutos por lote) e imprime un resultado JSON; el código de salida 1 significa que el lote falló.
  1. Después de que el comando regrese, lee asset_manifest.json de cwd. Trata ese archivo como la fuente de verdad.
  2. Conecta manifest.assets en el código del juego con GLTFLoader de Three.js.
  3. Mantén un respaldo primitivo local para cada activo generado. El juego debe seguir siendo jugable cuando un GLB falla al cargar.

Ejemplo de JSON --params:

{
  "cwd": "/ruta/absoluta/al/proyecto",
  "gamePrompt": "Corredor 3D con un gato astronauta que recolecta cristales y esquiva robots patrulla",
  "route": "gemini_reference",
  "assets": [
    {
      "id": "gato-astronauta",
      "role": "player",
      "name": "Gato Astronauta",
      "assetKind": "character",
      "prompt": "héroe gato astronauta low-poly original, casco redondo, silueta compacta y legible, traje azul y blanco, personaje amigable de juego arcade"
    },
    {
      "id": "cristal-energia",
      "role": "collectible",
      "name": "Cristal de Energía",
      "assetKind": "prop",
      "prompt": "recogible cristal de energía facetado cian brillante, silueta limpia, coleccionable de juego"
    }
  ]
}

Reglas de integración en tiempo de ejecución

  • Normaliza cada GLB cargado con THREE.Box3().setFromObject(): escala al tamaño objetivo, centra horizontalmente, coloca la parte inferior en y = 0 y aplica un desplazamiento de orientación estable.
  • Separa los aspectos visuales de las hitboxes de jugabilidad. La colisión debe usar dimensiones de jugabilidad estables, no los límites del modelo sin procesar ni los orígenes de la malla.
  • Si manifest.assets contiene rigged, rigType o animations, inspecciona los gltf.animations cargados antes de afirmar que existe animación nativa.
  • Cuando existan clips nativos, crea un THREE.AnimationMixer, asigna clips por subcadenas que no distinguen mayúsculas/minúsculas como idle, walk, run y jump, y llama a mixer.update(delta) cada fotograma.
  • Si no existen clips nativos, usa balanceo/inclinación/rotación de todo el grupo o clips procedurales explícitamente etiquetados como animación de respaldo.
  • Agrega una sección corta README.md llamada 3D Asset Pipeline o 3D 素材流水线 que describa qué activos se generaron, qué ruta se usó y qué fuente de animación en tiempo de ejecución se utiliza.

Manejo de fallos

  • API de activos inalcanzable (readiness informa unreachable): explica que la generación remota de modelos no está disponible, pide al usuario que verifique el servicio de activos predeterminado, el acceso a la red y GAME_ASSETS_API_TOKEN si es necesario; solo pregunta por GAME_ASSETS_API_URL al anular el servicio predeterminado. Mantén los respaldos primitivos y continúa con el juego jugable.
  • Clave Gemini faltante en el servidor para la ruta gemini_reference: cambia a tripo si es aceptable, o dile al usuario que el operador del servidor debe configurar la clave Gemini.
  • Saldo de Tripo cero: no reintentes en un bucle. Mantén los respaldos y registra la etapa omitida en el README.
  • Éxito parcial: usa los activos generados que tuvieron éxito y geometría de respaldo para el resto.

Skills relacionados