/game-asset-generator

name: game-asset-generator
promoted_to: game-pipeline
description: "Deterministic palette/matrix pixel art (not AI). Use for procedural tile art, color-quantized output, matrix sprites."
agent: typescript-frontend-engineer
user-invocable: false
command: /game-assets
allowed-tools:
  - Read
  - Write
  - Bash
  - Grep
  - Glob
  - Edit
routing:
  triggers:
    - pixel art
    - tile pattern
    - palette quantize
    - matrix sprite
    - meshy
    - meshyai
    - generate 3d model
    - text to 3d
    - image to 3d
    - world labs
    - gaussian splat
    - splat environment
    - game asset
    - fal ai
    - fal.ai
    - generate texture
    - generate image for game
    - 3d character
    - game model
    - rig model
    - animate model
    - game environment
    - sketchfab
    - poly pizza
    - poly haven
  not_for: "AI-generated pixel art, illustration, or character art (use image-gen) — this skill is deterministic palette/matrix generation, not an AI backend; ad-hoc workflow composition (use workflow skill)"
  pairs_with:
    - threejs-builder
    - typescript-frontend-engineer
  complexity: Medium
  category: game-development

Game Asset Generator Skill

Overview

This skill generates game-ready assets (3D models, Gaussian Splat environments, 2D sprites, images/textures) using AI APIs and free asset sources. It follows a three-phase workflow: DETECT the asset type -> GENERATE via the appropriate API or source -> INTEGRATE into the game. Only the relevant reference is loaded per task -- do not load all references upfront.

**Scope**: Use for AI-generated 3D models, world environments, pixel art sprites, concept art, textures, and sourcing free pre-built assets. Keep game engine scripting, physics, game loop logic, and shader authoring in `threejs-builder` after asset generation.

---

Phase 1: DETECT

**Goal**: Identify the asset type from the request and load the single corresponding reference.

**Step 1: Classify the request**

| Signal in request | Asset Type | Reference to load | |-------------------|-----------|-------------------| | "3D model", "character model", "generate model", GLB, mesh, rig, animate, humanoid | **3D Model** | `references/meshyai.md` | | "environment", "world", "scene background", "gaussian splat", "splat", volumetric | **Environment** | `references/worldlabs.md` | | "sprite", "pixel art", "2D character", "tile", "tileset", canvas sprite | **2D Sprite** | `references/pixel-art-sprites.md` | | "image", "texture", "concept art", "icon", "generate image", chroma key | **Image / Texture** | `references/fal-ai-image.md` | | No API key available, "free asset", "find model", "download asset", generation failed | **Existing Assets** | `references/asset-sources.md` |

If the request is ambiguous between 3D Model and Image, ask: "Do you need a 3D mesh (GLB file for a Three.js scene) or a 2D image/texture?"

**Step 2: Check API key availability**

Before calling any paid API, verify the required key exists:

grep -E "MESHY_API_KEY|WLT_API_KEY|FAL_KEY" ~/.env 2>/dev/null

If the required key is missing, the fallback chain applies -- load `references/asset-sources.md` alongside the primary reference.

**Fallback chain**: Meshy API -> Sketchfab search -> Poly Haven -> Poly.pizza -> BoxGeometry placeholder. All sources output GLB into the same path so game loading code does not change.

**Gate**: Asset type identified, relevant reference loaded. Proceed to Phase 2 only when gate passes.

---

Phase 2: GENERATE

**Goal**: Call the API or source to produce the asset. Follow the loaded reference exactly -- it is the authoritative guide for its API.

**Core constraints (all asset types)**:

• **Download immediately** -- Meshy retains assets only 3 days; World Labs SPZ files expire similarly. Never assume a URL will be valid tomorrow.
• **Output to a stable path** -- write assets to `public/assets/` or an equivalent game-accessible directory so integration code does not need path changes per asset.
• **Save the .meta.json sidecar** -- every generated asset gets a `.meta.json` recording the prompt, model, generation timestamp, and asset ID. Required for regeneration and auditing.
• **Validate the output file** -- after download, confirm file size > 0 and extension matches expected type (GLB, SPZ, PNG, etc.) before proceeding.

**Per-type generation summary** (read the reference for full API details):

**3D Model (Meshy)**: Two-step pipeline -- preview (fast, low quality, confirms prompt works) -> refine (full quality). Auto-rig only for humanoids meeting all criteria: bipedal, textured, clearly defined limbs. Animate rigged models with walk/run/idle presets. Post-process with `scripts/optimize-glb.mjs` for 80-95% size reduction before integration.

**Environment (World Labs)**: Upload reference image (preferred over text-only) -> poll 3-8 minutes -> download SPZ + GLB collider + panorama JPG. Y-axis flip (`rotation.x = Math.PI`) required after loading into Three.js scene.

**2D Sprite (code-only)**: Canvas-based generation -- no API call. Load `references/pixel-art-sprites.md` and generate sprites from the palette and matrix system defined there. Works without any API key.

**Image / Texture (fal.ai)**: Queue-based API -- submit job -> poll for result. Choose model endpoint based on need (GPT Image 1.5 for transparency, Nano Banana 2 for speed). Use `#00FF00` chroma-key background when the asset needs transparency extraction.

**Gate**: Asset file downloaded and validated (size > 0, correct extension). .meta.json saved. Proceed to Phase 3 only when gate passes.

---

Phase 3: INTEGRATE

**Goal**: Load the generated asset into the game scene correctly.

**Core constraint**: Use `SkeletonUtils.clone()` -- never `.clone()` -- for animated models. Regular `.clone()` breaks skeleton bindings and leaves the model in a permanent T-pose. This is the single most common integration failure with rigged GLBs.

import { SkeletonUtils } fro