Meshy AI — 3D Model Generation, Rigging & Animation

You are an expert at generating custom 3D models with Meshy AI and integrating them into Three.js browser games. Meshy is the preferred source for all 3D game assets — it generates exactly what you need from a text description or reference image, with consistent art style and game-ready topology.

Why Meshy First

Exact match: Generate precisely the character, prop, or scenery your game needs — no compromises
Consistent style: All assets from the same generation pipeline share a cohesive look
Custom characters: Named personalities, branded characters, unique creatures — all generated to spec
Full pipeline: Generate → rig → animate, all from one tool
Game-ready: Control polycount, topology, and PBR textures for optimal Three.js performance

Fallback Sources

MESHY_API_KEY

is not available and the user declines to set one up, fall back to these in order:

Fallback	Source	Best for
`3d-character-library/`	Pre-built GLBs	Quick animated humanoids (Soldier, Xbot, Robot, Fox)
`find-3d-asset.mjs`	Sketchfab, Poly Haven, Poly.pizza	Searching existing free model libraries
Procedural geometry	Code	BoxGeometry/SphereGeometry as last resort

Authentication

All Meshy API calls require

MESHY_API_KEY

. Always check for this key before starting any 3D asset work. If the key is not set in the environment, ask the user immediately:

I'll generate custom 3D models with Meshy AI for the best results. You can get a free API key in 30 seconds:

Sign up at https://app.meshy.ai

Go to Settings → API Keys

Create a new API key

What is your Meshy API key? (Or type "skip" to use free model libraries instead)

If the user provides a key, use it via:

MESHY_API_KEY=<key> node scripts/meshy-generate.mjs ...

If the user skips, proceed with fallback sources (character library → Sketchfab → Poly Haven).

CLI Script —

scripts/meshy-generate.mjs

Zero-dependency Node.js script. Handles the full lifecycle: submit task → poll → download GLB → write meta.json.

Text to 3D (full pipeline)

Generates a 3D model from a text prompt. Two-step process: preview (geometry) → refine (texturing).

bash

# Full pipeline: preview → refine → download
MESHY_API_KEY=<key> node scripts/meshy-generate.mjs \
  --mode text-to-3d \
  --prompt "a cartoon knight with sword and shield" \
  --output public/assets/models/ \
  --slug knight

# Preview only (faster, untextured — good for geometry check)
MESHY_API_KEY=<key> node scripts/meshy-generate.mjs \
  --mode text-to-3d \
  --prompt "a wooden barrel" \
  --preview-only \
  --output public/assets/models/ \
  --slug barrel

# With PBR textures and specific polycount
MESHY_API_KEY=<key> node scripts/meshy-generate.mjs \
  --mode text-to-3d \
  --prompt "a sci-fi hover bike" \
  --pbr \
  --polycount 15000 \
  --ai-model meshy-6 \
  --output public/assets/models/ \
  --slug hoverbike

Image to 3D

Turn a reference image into a 3D model. Supports URLs, local files, and base64 data URIs.

bash

# From URL
MESHY_API_KEY=<key> node scripts/meshy-generate.mjs \
  --mode image-to-3d \
  --image "https://example.com/character-concept.png" \
  --output public/assets/models/ \
  --slug character

# From local file (auto-converts to base64)
MESHY_API_KEY=<key> node scripts/meshy-generate.mjs \
  --mode image-to-3d \
  --image "./concept-art/hero.png" \
  --output public/assets/models/ \
  --slug hero

Auto-Rig (humanoids only — MANDATORY for all bipedal characters)

Adds a skeleton to a generated humanoid model and auto-downloads walking + running animation GLBs. The input task ID comes from a completed text-to-3d or image-to-3d task.

bash

MESHY_API_KEY=<key> node scripts/meshy-generate.mjs \
  --mode rig \
  --task-id <meshy-task-id> \
  --height 1.8 \
  --output public/assets/models/ \
  --slug hero

This produces 3 files automatically:

```
hero.glb
```
— rigged model with skeleton
```
hero-walk.glb
```
— walking animation (auto-downloaded)
```
hero-run.glb
```
— running animation (auto-downloaded)

Always chain generate → rig as one atomic step for humanoids. Never leave humanoid characters as static models.

Limitations: Rigging works only on textured humanoid (bipedal) models with clearly defined limbs. Won't work on animals, vehicles, abstract shapes, or untextured meshes.

Animate

Apply an animation to a rigged model. Requires a completed rig task ID and an animation action ID.

bash

MESHY_API_KEY=<key> node scripts/meshy-generate.mjs \
  --mode animate \
  --task-id <rig-task-id> \
  --action-id 1 \
  --output public/assets/models/ \
  --slug hero-walk

Check Status

Poll any task's current status.

bash

MESHY_API_KEY=<key> node scripts/meshy-generate.mjs \
  --mode status \
  --task-id <task-id> \
  --task-type text-to-3d   # or: image-to-3d, rigging, animations

Non-blocking Mode

Submit a task without waiting. Useful in pipelines.

bash

MESHY_API_KEY=<key> node scripts/meshy-generate.mjs \
  --mode text-to-3d \
  --prompt "a crystal sword" \
  --no-poll

# Later:
MESHY_API_KEY=<key> node scripts/meshy-generate.mjs \
  --mode status --task-id <id> --task-type text-to-3d

Automatic GLB Optimization

All downloaded GLBs are automatically optimized via

scripts/optimize-glb.mjs

to reduce file sizes by 80–95%. The pipeline resizes textures to 1024×1024, converts them to WebP, and applies meshopt compression.

Optimization runs by default after every GLB download (text-to-3d, image-to-3d, rig, animate)
Use
```
--no-optimize
```
to skip optimization and keep the raw Meshy output
Use
```
--texture-size <n>
```
to change the max texture dimension (default: 1024)
First run may take a moment as
```
npx
```
downloads
```
@gltf-transform/cli
```
If
```
gltf-transform
```
is unavailable, the script warns and continues with the raw file

Optimized GLBs use meshopt compression and require

MeshoptDecoder

at runtime — the template

AssetLoader.js

includes this automatically.

bash

# Skip optimization for a specific generation
MESHY_API_KEY=<key> node scripts/meshy-generate.mjs \
  --mode text-to-3d --prompt "a barrel" --preview-only \
  --no-optimize --output public/assets/models/ --slug barrel

# Custom texture size (e.g., 512 for mobile)
MESHY_API_KEY=<key> node scripts/meshy-generate.mjs \
  --mode text-to-3d --prompt "a barrel" --preview-only \
  --texture-size 512 --output public/assets/models/ --slug barrel

# Re-optimize an existing GLB directly
node scripts/optimize-glb.mjs public/assets/models/barrel.glb --texture-size 512

API Reference

Base URL:

https://api.meshy.ai/openapi

Text to 3D

POST

/v2/text-to-3d

— Create preview or refine task

Preview payload:

json

{
  "mode": "preview",
  "prompt": "a cartoon knight with sword and shield",
  "ai_model": "latest",
  "topology": "triangle",
  "target_polycount": 10000
}

Refine payload:

json

{
  "mode": "refine",
  "preview_task_id": "<preview-task-id>",
  "enable_pbr": true,
  "texture_prompt": "hand-painted fantasy style"
}

GET

/v2/text-to-3d/:id

— Retrieve task (poll this)

Response when complete:

json

{
  "id": "task-uuid",
  "status": "SUCCEEDED",
  "progress": 100,
  "model_urls": {
    "glb": "https://assets.meshy.ai/...",
    "fbx": "https://assets.meshy.ai/...",
    "obj": "https://assets.meshy.ai/...",
    "usdz": "https://assets.meshy.ai/..."
  },
  "texture_urls": [
    { "base_color": "https://..." }
  ],
  "thumbnail_url": "https://..."
}

Optional parameters:

```
ai_model
```
:
```
meshy-5
```
,
```
meshy-6
```
,
```
latest
```
(default:
```
latest
```
)
```
model_type
```
:
```
standard
```
or
```
lowpoly
```
```
topology
```
:
```
quad
```
or
```
triangle
```
(default:
```
triangle
```
)
```
target_polycount
```
: 100–300,000 (default: 10,000)
```
symmetry_mode
```
:
```
off
```
,
```
auto
```
,
```
on
```
(default:
```
auto
```
)
```
pose_mode
```
:
```
a-pose
```
,
```
t-pose
```
, or empty string
```
enable_pbr
```
: generates metallic, roughness, and normal maps

Image to 3D

POST

/v1/image-to-3d

— Create task

json

{
  "image_url": "https://example.com/photo.png",
  "ai_model": "latest",
  "enable_pbr": false,
  "should_texture": true,
  "topology": "triangle",
  "target_polycount": 10000
}

GET

/v1/image-to-3d/:id

— Retrieve task

Supports

image_url

as public URL, base64 data URI (

data:image/png;base64,...

), or multi-image via POST

/v1/multi-image-to-3d

(1–4 images from different angles).

Rigging

POST

/v1/rigging

— Create rigging task

json

{
  "input_task_id": "<text-to-3d or image-to-3d task id>",
  "height_meters": 1.7
}

GET

/v1/rigging/:id

— Retrieve task

Result includes:

```
rigged_character_glb_url
```
— rigged GLB ready for Three.js
```
rigged_character_fbx_url
```
— rigged FBX
```
basic_animations
```
— walking/running GLB URLs included free

Animation

POST

/v1/animations

— Create animation task

json

{
  "rig_task_id": "<rigging-task-id>",
  "action_id": 1
}

GET

/v1/animations/:id

— Retrieve task

Result includes

animation_glb_url

animation_fbx_url

Task Statuses

All tasks progress through:

PENDING

→

IN_PROGRESS

→

SUCCEEDED

FAILED

CANCELED

Poll at 5-second intervals. Tasks typically complete in 30s–5min depending on complexity.

Asset Retention

Meshy retains generated assets for 3 days (unlimited for Enterprise). Download promptly.

Quick Reference: Static Props (no rig needed)

For non-humanoid assets (props, scenery, buildings), skip rigging:

bash

# Generate
MESHY_API_KEY=<key> node scripts/meshy-generate.mjs \
  --mode text-to-3d --prompt "a wooden barrel, low poly game asset" \
  --polycount 5000 --output public/assets/models/ --slug barrel

# Integrate with loadModel (regular clone, no SkeletonUtils)
const barrel = await loadModel('assets/models/barrel.glb');
scene.add(barrel);

Post-Generation Verification (MANDATORY)

After loading any Meshy-generated model, always verify orientation and scale before proceeding. Meshy models have unpredictable facing directions and scales. Skipping this step leads to backwards-facing characters and models that overflow their containers.

Auto-Orientation Check

Meshy models typically face +Z, but this varies. After loading, log the bounding box and visually verify via Playwright MCP or dev tools:

// Add this immediately after loading any GLB
model.updateMatrixWorld(true);
const box = new THREE.Box3().setFromObject(model);
const size = box.getSize(new THREE.Vector3());
const center = box.getCenter(new THREE.Vector3());
console.log(`[Model] ${slug} — size: ${size.x.toFixed(2)} x ${size.y.toFixed(2)} x ${size.z.toFixed(2)}`);
console.log(`[Model] ${slug} — center: ${center.x.toFixed(2)}, ${center.y.toFixed(2)}, ${center.z.toFixed(2)}`);

Fixing facing direction:

Start with
```
rotationY: Math.PI
```
(180 degrees) — most Meshy models need this to face -Z
If the model faces +Z by default and needs to face the camera:
```
rotationY: 0
```
If in doubt: take a screenshot, check which way the face/front is pointing, adjust
Store
```
rotationY
```
in Constants.js per model — never hardcode in entity files

Auto-Scale Fitting

Models must fit within their game context. After loading:

// Calculate scale to fit a target height
const box = new THREE.Box3().setFromObject(model);
const currentHeight = box.max.y - box.min.y;
const targetHeight = 2.0; // desired height in world units
const autoScale = targetHeight / currentHeight;
model.scale.setScalar(autoScale);

For container fitting (e.g., robots inside a ring):

// Ensure model fits within container bounds
const containerWidth = RING.PLATFORM_WIDTH * 0.8; // 80% of ring width
const modelWidth = box.max.x - box.min.x;
if (modelWidth * currentScale > containerWidth) {
  const fitScale = containerWidth / modelWidth;
  model.scale.setScalar(Math.min(currentScale, fitScale));
}

Always take a Playwright screenshot after model integration to visually verify:

Characters face the correct direction
Characters fit within their environment
Characters don't clip through floors/walls/each other

Floor Alignment

Center the model on X/Z and plant feet on Y=0:

const box = new THREE.Box3().setFromObject(model);
const center = box.getCenter(new THREE.Vector3());
model.position.y = -box.min.y;      // feet on ground
model.position.x = -center.x;       // centered X
model.position.z = -center.z;       // centered Z

Rigging: Mandatory for Humanoid Characters

Every humanoid character MUST be rigged. Static models require hacky programmatic animation (moving wrapper groups) that looks artificial. Rigged models get proper skeletal animation — walk, run, punch, etc.

When to Rig

Model type	Rig?	Why
Humanoid character (player, NPC, enemy)	YES — always	Skeletal animation for walk/run/idle/attack
Animal with legs	YES	Walk/run animations
Vehicle, prop, building	No	Static or simple rotation
Abstract shape, particle	No	Procedural animation

Full Pipeline: Generate → Rig → Animate → Integrate

Step 1: Generate the model

bash

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

Step 2: Rig (reads refineTaskId from meta.json automatically)

bash

MESHY_API_KEY=<key> node scripts/meshy-generate.mjs \
  --mode rig \
  --task-id <refine-task-id-from-meta.json> \
  --height 1.7 \
  --output public/assets/models/ --slug robot-rigged

Rigging returns:

```
rigged_character_glb_url
```
— rigged GLB with skeleton (use this as the base model)
```
basic_animations.walking
```
— walking animation GLB (free, included)
```
basic_animations.running
```
— running animation GLB (free, included)

Step 3: Add custom animations (optional, for game-specific actions)

bash

# Each action_id corresponds to a different animation
MESHY_API_KEY=<key> node scripts/meshy-generate.mjs \
  --mode animate \
  --task-id <rig-task-id> \
  --action-id <id> \
  --output public/assets/models/ --slug robot-punch

Step 4: Integrate with

loadAnimatedModel()

AnimationMixer

import { loadAnimatedModel } from './level/AssetLoader.js';
import * as THREE from 'three';

// Load rigged model (SkeletonUtils.clone preserves bone bindings)
const { model, clips } = await loadAnimatedModel('assets/models/robot-rigged.glb');
const mixer = new THREE.AnimationMixer(model);

// Log clip names — they vary per model
console.log('Clips:', clips.map(c => c.name));

// Load additional animation GLBs and add their clips to the same mixer
const walkData = await loadAnimatedModel('assets/models/robot-walk.glb');
const walkClip = walkData.clips[0];
const walkAction = mixer.clipAction(walkClip);

// fadeToAction pattern for smooth transitions
function fadeToAction(nextAction, duration = 0.3) {
  if (activeAction) activeAction.fadeOut(duration);
  nextAction.reset().setEffectiveTimeScale(1).setEffectiveWeight(1).fadeIn(duration).play();
  activeAction = nextAction;
}

// In update loop:
mixer.update(delta);

Prompt Engineering Tips

Good prompts produce better models:

Goal	Prompt	Why
Game character	"a stylized goblin warrior, low poly game character, full body"	"low poly" + "game character" = game-ready topology
Prop	"a wooden treasure chest, stylized, closed"	Simple, specific, single object
Environment piece	"a fantasy stone archway, low poly, game asset"	"game asset" signals clean geometry
Vehicle	"a sci-fi hover bike, side view, clean topology"	"clean topology" = fewer artifacts

Avoid:

Multiple objects in one prompt ("a knight AND a dragon") — generate separately
Vague prompts ("something cool") — be specific about style and form
Interior/architectural scenes — Meshy is best for single objects

Integration with Existing Pipeline

Meshy-generated models slot into the existing 3D asset pipeline:

┌─────────────────────────────────────────────────────┐
│                 3D Asset Sources                     │
├──────────────┬──────────────┬───────────────────────┤
│ Free Libraries│ Character Lib │     Meshy AI          │
│ find-3d-asset │ 3d-char-lib/ │ meshy-generate.mjs    │
│   .mjs       │              │ text/image → 3D       │
│              │              │ rig → animate         │
├──────────────┴──────────────┴───────────────────────┤
│              AssetLoader.js                         │
│         loadModel() / loadAnimatedModel()           │
├─────────────────────────────────────────────────────┤
│              Three.js Game                          │
└─────────────────────────────────────────────────────┘

All sources output GLB files into

public/assets/models/

. The

AssetLoader.js

doesn't care where the GLB came from — it loads them all the same way.

Checklist

```
MESHY_API_KEY
```
checked — prompted user if not set, or user skipped to fallbacks
Prompt is specific (style, poly count, single object)
All humanoid characters rigged — never skip rigging for bipedal models
Downloaded GLB before 3-day expiration
Post-generation verification done — orientation, scale, floor alignment checked
Playwright screenshot taken — visually confirmed facing direction + fit in environment
```
rotationY
```
set per model in Constants.js (most Meshy models need
```
Math.PI
```
)
Static models use
```
loadModel()
```
(regular clone)
Rigged models use
```
loadAnimatedModel()
```
(SkeletonUtils.clone)
Clip names logged and
```
clipMap
```
defined for animated models
```
.meta.json
```
saved alongside GLB with task IDs for traceability
```
npm run build
```
succeeds

meshyai

NPX Install

Tags

SKILL.md Content

Meshy AI — 3D Model Generation, Rigging & Animation

Why Meshy First

Fallback Sources

Authentication

CLI Script —
`scripts/meshy-generate.mjs`

Text to 3D (full pipeline)

Image to 3D

Auto-Rig (humanoids only — MANDATORY for all bipedal characters)

Animate

Check Status

Non-blocking Mode

Automatic GLB Optimization

API Reference

Text to 3D

Image to 3D

Rigging

Animation

Task Statuses

Asset Retention

Quick Reference: Static Props (no rig needed)

Post-Generation Verification (MANDATORY)

Auto-Orientation Check

Auto-Scale Fitting

Floor Alignment

Rigging: Mandatory for Humanoid Characters

When to Rig

Full Pipeline: Generate → Rig → Animate → Integrate

Prompt Engineering Tips

Integration with Existing Pipeline

Checklist