meshyai

Meshy AI — 3D 模型生成、绑定与动画

你是使用 Meshy AI 生成自定义 3D 模型并将其集成到 Three.js 浏览器游戏中的专家。Meshy 是所有 3D 游戏资源的首选来源——它能根据文字描述或参考图像生成你所需的内容，保持统一的美术风格，并提供可直接用于游戏的拓扑结构。

性能注意事项

• 每个步骤都要留足时间。质量比速度更重要。
• 不要跳过验证步骤——它们能及早发现问题。
• 修改前先阅读文件的完整上下文。
• 生成后务必进行验证。切勿假设模型的朝向或缩放比例正确。

参考文件

文件	描述
api-reference.md	完整的 API 端点规范、负载、响应、任务状态和资源保留政策
rigging-pipeline.md	完整的生成 → 绑定 → 动画 → 集成工作流，包含 fadeToAction 模式和代码示例
verification-patterns.md	自动调整朝向、自动适配缩放比例、地面对齐代码模式

为什么优先选择 Meshy

• 精准匹配：生成游戏所需的角色、道具或场景，不必妥协
• 风格统一：通过同一生成流程生成的所有资源都具有协调一致的外观
• 自定义角色：具名角色、品牌角色、独特生物——均可按规格生成
• 完整流程：从一个工具完成生成 → 绑定 → 动画
• 可直接用于游戏：可控制多边形数量、拓扑结构和 PBR 纹理，优化 Three.js 性能

备用来源

如果没有 MESHY_API_KEY，且用户不愿设置，则按以下顺序使用备用来源：

备用方案	来源	适用场景
assets/3d-characters/	预制 GLB	快速获取带动画的人形模型（Soldier、Xbot、Robot、Fox）
find-3d-asset.mjs	Sketchfab、Poly Haven、Poly.pizza	搜索现有的免费模型库
程序化几何体	代码	最后的备选方案：BoxGeometry/SphereGeometry

身份验证

所有 Meshy API 调用都需要 MESHY_API_KEY。开始任何 3D 资源工作前，务必先检查此密钥。

在询问用户前，先检查密钥是否已存在： test -f .env && grep -q '^MESHY_API_KEY=.' .env && echo "found" 如果已找到，使用 set -a; . .env; set +a 导出密钥，并跳过询问。

如果环境或 .env 中未设置密钥，立即询问用户：

我会使用 Meshy AI 生成自定义 3D 模型，以获得最佳效果。你可以在 30 秒内获取免费 API 密钥：

1. 在 https://app.meshy.ai 注册
2. 前往 Settings → API Keys
3. 创建新的 API 密钥

请按以下格式粘贴密钥：MESHY_API_KEY=your-key-here （密钥将保存到 .env，并自动从本次对话中隐藏。）

或输入“skip”，改用免费的模型库。

如果用户提供密钥，使用以下命令：set -a; . .env; set +a && node scripts/meshy-generate.mjs ...

如果用户跳过，则使用备用来源（角色库 → Sketchfab → Poly Haven）。

CLI 脚本 — scripts/meshy-generate.mjs

零依赖的 Node.js 脚本。负责处理完整生命周期：提交任务 → 轮询 → 下载 GLB → 写入 meta.json。

文本转 3D（完整流程）

根据文字提示词生成 3D 模型。分两步完成：预览（几何体）→ 精修（纹理）。

# 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

图像转 3D

将参考图像转换为 3D 模型。支持 URL、本地文件和 base64 数据 URI。

# 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

自动绑定（仅限人形模型——所有双足角色都必须执行）

为生成的人形模型添加骨架，并自动下载行走和跑步动画 GLB 文件。输入任务 ID 来自已完成的文本转 3D 或图像转 3D 任务。

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

此操作会自动生成 3 个文件：

• hero.glb — 带骨架的绑定模型
• hero-walk.glb — 行走动画（自动下载）
• hero-run.glb — 跑步动画（自动下载）

对于人形模型，始终将生成 → 绑定作为一个原子步骤执行。 切勿让人形角色保持为静态模型。

限制： 绑定仅适用于带纹理且四肢轮廓清晰的人形（双足）模型。对动物、车辆、抽象形状或无纹理网格无效。

制作动画

为绑定后的模型应用动画。需要已完成的绑定任务 ID 和动画动作 ID。

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

检查状态

轮询任意任务的当前状态。

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

非阻塞模式

提交任务但不等待结果。适用于工作流。

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

自动优化 GLB

所有下载的 GLB 都会通过 scripts/optimize-glb.mjs 自动优化，文件大小可缩减 80–95%。此流程会将纹理调整为 1024×1024，将其转换为 WebP，并应用 meshopt 压缩。

• 默认情况下，每次下载 GLB 后都会运行优化（文本转 3D、图像转 3D、绑定、制作动画）
• 使用 --no-optimize 跳过优化，保留 Meshy 的原始输出
• 使用 --texture-size <n> 更改纹理的最大尺寸（默认值：1024）
• 首次运行可能需要稍等片刻，因为 npx 会下载 @gltf-transform/cli
• 如果 gltf-transform 不可用，脚本会发出警告并继续使用原始文件

优化后的 GLB 使用 meshopt 压缩，运行时需要 MeshoptDecoder——模板 AssetLoader.js 会自动包含它。

# 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 参考

请参阅 api-reference.md，了解完整的端点规范、负载、响应、任务状态和资源保留策略。

快速参考：静态道具（无需绑定）

对于非人形资源（道具、场景、建筑），可跳过绑定：

# 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);

生成后验证（必须执行）

请参阅 verification-patterns.md，了解自动方向检查、自动缩放适配和地面对齐的代码模式。

绑定：人形角色必须执行

请参阅 rigging-pipeline.md，了解完整的生成 -> 绑定 -> 制作动画 -> 集成流程，包括何时绑定、fadeToAction 模式和集成代码示例。

提示词工程技巧

好的提示词能生成更好的模型：

目标	提示词	原因
游戏角色	"a stylized goblin warrior, low poly game character, full body"	"low poly" + "game character" = 适用于游戏的拓扑结构
道具	"a wooden treasure chest, stylized, closed"	简单、具体的单个物体
环境组件	"a fantasy stone archway, low poly, game asset"	"game asset" 表示几何结构整洁
载具	"a sci-fi hover bike, side view, clean topology"	"clean topology" = 更少瑕疵

避免：

• 在一个提示词中描述多个物体（“a knight AND a dragon”）——分别生成
• 模糊的提示词（“something cool”）——具体说明风格和形态
• 室内或建筑场景——Meshy 最适合生成单个物体

与现有流程集成

Meshy 生成的模型可接入现有的 3D 资源流程：

┌─────────────────────────────────────────────────────┐
│                 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                          │
└─────────────────────────────────────────────────────┘

所有来源都会将 GLB 文件输出到 public/assets/models/。AssetLoader.js 不关心 GLB 的来源——加载方式都相同。

故障排除

问题	原因	解决方法
未设置 MESHY_API_KEY	缺少环境变量	向用户索要密钥，或运行 export MESHY_API_KEY=<key>。可在 https://app.meshy.ai 的 Settings -> API Keys 下获取免费密钥。
任务卡在 PENDING 状态	API 队列积压或参数无效	等待 2-3 分钟，然后轮询状态。如果 5 分钟后仍为 PENDING，请取消任务，并使用更简单的提示词或更低的多边形数量重新提交。
下载资源时返回 404	Meshy 仅保留资源 3 天	重新运行生成流程。任务成功后务必立即下载 GLB。将其存储在本地的 public/assets/models/ 中。
绑定失败或生成的骨架损坏	模型不是清晰的双足人形，或网格没有纹理	确保模型是带纹理且四肢可见的人形。绑定不适用于动物、车辆、抽象形状或仅供预览（无纹理）的网格。使用 --pbr 重新生成，并在提示词中指定“full body humanoid”。
生成的模型与提示词不符	提示词含糊或包含多个对象	使用具体且仅包含单个对象的提示词。添加风格提示（“low poly”“stylized”“game character”），避免组合多个对象。参见提示词工程技巧。

检查清单

• 已检查 MESHY_API_KEY——如果未设置，已向用户索要；或用户选择使用备用方案
• 提示词具体明确（风格、多边形数量、单个对象）
• 所有人形角色均已完成绑定——双足模型绝不跳过绑定
• 已在 3 天过期前下载 GLB
• 已完成生成后验证——已检查方向、比例和地面贴合情况
• 已使用 Playwright 截图——已目视确认朝向和与环境的适配情况
• 已在 Constants.js 中为每个模型设置 rotationY（大多数 Meshy 模型需要 Math.PI）
• 静态模型使用 loadModel()（常规克隆）
• 已绑定模型使用 loadAnimatedModel()（SkeletonUtils.clone）
• 已记录动画片段名称，并为动画模型定义 clipMap
• 已将包含任务 ID 的 .meta.json 与 GLB 一并保存，以便追溯
• npm run build 成功