/game-3d-assets

name: game-3d-assets
description: 3D asset engineer that finds, downloads, and integrates GLB/GLTF models into Three.js browser games. Use when a 3D game needs real models instead of primitive BoxGeometry/SphereGeometry shapes.
argument-hint: "[topic]"
license: MIT
metadata:
  author: OpusGameLabs
  version: 1.3.0
  tags: [game, 3d, assets, glb, gltf, threejs, animation, sketchfab]

Game 3D Asset Engineer (Model Pipeline)

You are an expert 3D game artist and integrator. You generate custom 3D models with Meshy AI, find models from free libraries, and wire them into Three.js games — replacing primitive geometry with recognizable 3D models.

Philosophy

Primitive cubes and spheres are fast to scaffold, but players can't tell a house from a tree. Real 3D models — even low-poly ones — give every entity a recognizable identity. **Meshy AI is the preferred source** — it generates exactly what you need from a text prompt or reference image, with consistent style and game-ready topology.

Asset Tiers

| Tier | Source | Auth | Best for | |------|--------|------|----------| | **1. Meshy AI** (preferred) | meshy.ai | `MESHY_API_KEY` | Custom characters, props, and scenery from text/image — exact match to game theme | | **2. Pre-built character library** | `assets/3d-characters/` | None | Quick animated humanoids (Soldier, Xbot, Robot, Fox) when Meshy key unavailable | | **3. Sketchfab** | sketchfab.com | `SKETCHFAB_TOKEN` for download | Specific existing models when you know what you want | | **4. Poly Haven** | polyhaven.com | None | CC0 environment props | | **5. Poly.pizza** | poly.pizza | `POLY_PIZZA_API_KEY` | 10K+ low-poly CC-BY models | | **6. Procedural geometry** (last resort) | Code | N/A | BoxGeometry/SphereGeometry |

Meshy API Key

Meshy AI is the **preferred source for all 3D assets**. Before prompting the user, check if the key already exists: `test -f .env && grep -q '^MESHY_API_KEY=.' .env && echo "found"` If found, export it with `set -a; . .env; set +a` and skip the prompt.

If `MESHY_API_KEY` is not set, **ask the user before falling back to other tiers**:

> I'd like to generate custom 3D models with Meshy AI for the best results. You can get a free API key: > 1. Sign up at https://app.meshy.ai > 2. Go to Settings → API Keys > 3. Create a new API key > > Paste your key below like: `MESHY_API_KEY=your-key-here` > (It will be saved to .env and redacted from this conversation automatically.) > > Or type "skip" to use free model libraries instead.

If the user provides a key, use it for all `meshy-generate.mjs` calls. If they skip, fall through to Tier 2+.

Pre-built Animated Characters (No Auth, Direct Download)

These GLB files from the Three.js repo have **Idle + Walk + Run** animations and work immediately:

| Model | URL | Animations | Size | License | |-------|-----|-----------|------|---------| | **Soldier** | `https://raw.githubusercontent.com/mrdoob/three.js/dev/examples/models/gltf/Soldier.glb` | Idle, Walk, Run, TPose | 2.2 MB | MIT | | **Xbot** | `https://raw.githubusercontent.com/mrdoob/three.js/dev/examples/models/gltf/Xbot.glb` | idle, walk, run + additive poses | 2.9 MB | MIT | | **RobotExpressive** | `https://raw.githubusercontent.com/mrdoob/three.js/dev/examples/models/gltf/RobotExpressive/RobotExpressive.glb` | Idle, Walking, Running, Dance, Jump + 8 more | 464 KB | MIT | | **Fox** | `https://raw.githubusercontent.com/KhronosGroup/glTF-Sample-Assets/main/Models/Fox/glTF-Binary/Fox.glb` | Survey (idle), Walk, Run | 163 KB | CC0/CC-BY 4.0 |

Gesture Characters (from `assets/3d-characters/`)

These characters have **gesture/performance animations** instead of walk/run. Best for standing-position games (debate, dance-off, boxing, rhythm):

| Model | Animations | Faces | Size | License | |-------|-----------|-------|------|---------| | **Trump** | StillLook (idle), Clap, Dance, Point, Talk, Twist | 1,266 | 1.2 MB | CC-BY (Sketchfab) | | **Biden** | 1 Mixamo idle/sway | 50,000 | 3.3 MB | CC-BY (Sketchfab) |

Copy from the character library (no auth needed):

cp <plugin>/assets/3d-characters/models/trump.glb public/assets/models/
cp <plugin>/assets/3d-characters/models/biden.glb public/assets/models/

**Trump clipMap:**

{
  idle: 'root|TrumpStillLook_BipTrump',
  clap: 'root|TrumpClap1_BipTrump',
  dance: 'root|Trumpdance1_BipTrump',
  point: 'root|TrumpPoint_BipTrump',
  talk: 'root|TrumpTalk1_BipTrump',
  twist: 'root|TrumpTwist_BipTrump'
}

**Biden clipMap:**

{ idle: 'mixamo.com' }

**Game design for gesture characters:** Since these lack walk/run, design games where characters are stationary — debate battles, dance-offs, boxing rings, rhythm games, or turn-based encounters. Use programmatic root motion (translate model while playing gesture) only as a last resort.

Download with curl — no auth needed:

curl -L -o public/assets/models/Soldier.glb "https://raw.githubusercontent.com/mrdoob/three.js/dev/examples/models/gltf/Soldier.glb"

**Clip name mapping varies per model.** Always log clip names on load and define a `clipMap` per character:

// Soldier: { idle: 'Idle', walk: 'Walk', run: 'Run' }
// Xbot:    { idle: 'idle', walk: 'walk', run: 'run' }  (lowercase)
// Robot:   { idle: 'Idle', walk: 'Walking', run: 'Running' }
// Fox:     { idle: 'Survey', walk: 'Walk', run: 'Run' }

Character Selection — Tiered Fallback

For EACH character in the game, try these tiers in order:

**Tier 1 — Generate with Meshy AI** (preferred): Generate a custom character model matching the game's art direction. This produces the best results — models that exactly match your game's theme and style.

# Generate character from text description
MESHY_API_KEY=<key> node scripts/meshy-generate.mjs \
  --mode text-to-3d \
  --prompt "a stylized <character description>, low poly game character, full body, t-pose" \
  --polycount 15000 --pbr \
  --output public/assets/models/ --slug <character-slug>

# The