add-3d-assets

性能说明

• 请花时间彻底完成
• 质量比速度更重要
• 不要跳过验证步骤

添加 3D 资源

将基本几何形状（BoxGeometry、SphereGeometry）替换为真实的 3D 模型。角色使用 Meshy AI 生成的自定义模型，并添加骨骼绑定和动画。世界物体则使用生成的模型或从免费资源库获取。

说明

分析 $ARGUMENTS 中的游戏（如果未提供路径，则分析当前目录）。

首先，加载 game-3d-assets 技能和 meshyai 技能，了解完整的模型流程、AssetLoader 模式、Meshy 生成方式和集成模式。

步骤 1：获取 Meshy API 密钥

检查是否已设置 MESHY_API_KEY。先检查 .env： test -f .env && grep -q '^MESHY_API_KEY=.' .env && echo "found" 如果找到，则使用 set -a; . .env; set +a 导出并跳过提示。

如果未设置，请询问用户：

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

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

在下方粘贴密钥，格式如下：MESHY_API_KEY=your-key-here （密钥将保存到 .env，并自动从此对话中隐藏。）

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

步骤 2：审查

• 阅读 package.json，确认这是 Three.js 游戏（而非 Phaser；2D 游戏请使用 /add-assets）
• 阅读 src/core/Constants.js，了解实体类型、尺寸和颜色
• 阅读实体文件（src/gameplay/*.js、src/entities/*.js），查找 BoxGeometry、SphereGeometry 等
• 阅读 src/level/LevelBuilder.js，了解环境中的基本几何体
• 列出所有使用几何形状的实体
• 确定哪个实体是玩家角色（需要动画模型）

步骤 3：规划

将实体分为两类：

动画角色（玩家、带有 AI 的敌人）——使用 Meshy AI 生成：

实体	Meshy 提示词	备注
玩家	"a heroic knight, low poly game character, full body, t-pose"	生成 → 绑定骨骼 → 添加动画
敌人	"a goblin warrior with a club, low poly game character"	生成 → 绑定骨骼 → 添加动画

如果 Meshy 不可用，则使用 assets/3d-characters/：

• Soldier — 写实风格的军人（Idle、Walk、Run）——最佳默认选择
• Xbot — 风格化人偶（idle、walk、run + 叠加姿势）
• RobotExpressive — 卡通机器人（Idle、Walking、Running、Dance、Jump + 另外 8 种）
• Fox — 低多边形动物（Survey、Walk、Run）——缩放 0.02

世界物体（建筑、道具、场景、可收集物）——使用 Meshy 生成或搜索免费资源库：

实体	Meshy 提示词	备用来源
树	"a low poly stylized tree, game asset"	Poly Haven
房屋	"a medieval house, low poly game asset"	Poly Haven
木桶	"a wooden barrel, low poly game asset"	Poly Haven
硬币	"a gold coin, game collectible item"	Sketchfab

步骤 4：生成 / 下载

使用 Meshy（优先）：

# Generate characters
MESHY_API_KEY=<key> node <plugin-root>/scripts/meshy-generate.mjs \
  --mode text-to-3d \
  --prompt "a heroic knight, low poly game character, full body" \
  --polycount 15000 --pbr \
  --output public/assets/models/ --slug player

# Rig characters for animation
MESHY_API_KEY=<key> node <plugin-root>/scripts/meshy-generate.mjs \
  --mode rig --task-id <refine-task-id> --height 1.7 \
  --output public/assets/models/ --slug player-rigged

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

不使用 Meshy（备用方案）：

# Characters — copy from library
cp <plugin-root>/assets/3d-characters/models/Soldier.glb public/assets/models/

# World objects — search and download
node <plugin-root>/scripts/find-3d-asset.mjs --query "barrel" --source polyhaven \
  --output public/assets/models/ --slug barrel

步骤 5：集成

1. 创建 src/level/AssetLoader.js —— 动画模型请使用 SkeletonUtils.clone()（从 three/addons/utils/SkeletonUtils.js 导入）。普通的 .clone() 会破坏骨骼绑定，导致模型变成 T 姿。
2. 在 Constants.js 中添加 CHARACTER，包含 path、scale、facingOffset、clipMap
3. 为静态模型添加 ASSET_PATHS 和 MODEL_CONFIG
4. 更新 Player.js：
   • 使用 THREE.Group 作为位置锚点
   • 添加 loadAnimatedModel() + AnimationMixer
   • 使用 fadeToAction() 实现 idle/walk/run 动画交叉淡入淡出
   • 使用 applyAxisAngle(_up, cameraAzimuth) 实现相机相对的 WASD 移动
   • 模型朝向：atan2(v.x, v.z) + CHARACTER.facingOffset
   • 使用 model.quaternion.rotateTowards(targetQuat, turnSpeed * delta)
5. 更新 Game.js：
   • 添加 OrbitControls —— 让第三人称相机绕玩家旋转
   • 相机跟随：按玩家位移同时移动 orbitControls.target 和 camera.position
   • 将 orbitControls.getAzimuthalAngle() 传递给 Player，以实现相机相对移动
6. 使用 loadModel() 调用替换环境中的基础几何体，并添加 .catch() 回退处理
7. 添加 THREE.GridHelper，作为可见的移动参照
8. 启动时使用 preloadAll() 预加载所有模型，实现即时加载

步骤 6：调整并验证

• 运行 npm run dev —— 使用 WASD 四处移动，并用鼠标旋转相机
• 确认角色动画正常（停止时播放 Idle，移动时播放 Walk，按住 Shift 时播放 Run）
• 按模型调整 MODEL_CONFIG 的值（scale、rotationY、offsetY）
• 运行 npm run build，确认没有错误
• 根据 .meta.json 文件生成 ATTRIBUTION.md

使用示例

使用 Meshy AI

/add-3d-assets examples/space-explorer

结果：通过 Meshy 生成自定义骑士模型 → 绑定骨骼并添加动画（Idle/Walk/Run）→ 用带动画的 GLB 替换 BoxGeometry 玩家模型 → 添加 OrbitControls 相机 → 使用免费素材库中的物件装饰世界。

不使用 Meshy（回退方案）

/add-3d-assets examples/3d-platformer

结果：从角色素材库复制 Soldier.glb → 配置 SkeletonUtils.clone() → 使用 fadeToAction 实现动画交叉淡入淡出 → 将所有基础几何体替换为素材库或下载的模型。

故障排查

模型卡在 T 姿（没有动画）

原因： 对动画 GLB 模型使用 .clone(true) 而非 SkeletonUtils.clone()，会破坏骨骼绑定。 解决方法： 对所有带动画的模型，始终使用从 three/addons/utils/SkeletonUtils.js 导入的 SkeletonUtils.clone()。普通的 .clone() 会复制网格，但不会复制骨骼绑定。

Meshy AI 生成失败或质量较低

原因： 提示词模糊，或选择了错误的生成模式。 解决方法： 使用具体、描述清晰的提示词（例如“低多边形中世纪木制宝箱，游戏素材”，而不是“宝箱”）。生成角色时，使用带参考图的图生 3D 模式。将美术风格设为 “game-asset” 或 “low-poly”，以便更好地集成到游戏中。

生成模型的骨骼绑定失败

原因： 模型几何体不适合自动绑定骨骼（过于复杂、非流形或不是人形）。 解决方法： 简化提示词，以生成更简洁的几何体。确保模型是处于人形姿势的单个连通网格。非人形模型（物件、载具）不应进行骨骼绑定，应改作静态素材使用。

加载时出现 meshopt 解码器错误

原因： 部分 GLB 文件使用 meshopt 压缩，需要加载默认未加载的解码器。 解决方法： 加载前添加 meshopt 解码器：import { MeshoptDecoder } from 'three/addons/libs/meshopt_decoder.module.js'; loader.setMeshoptDecoder(MeshoptDecoder);

模型朝向错误

原因： 不同模型来源使用的前向方向不同。Mixamo 模型朝向 -Z，其他一些模型朝向 +Z。 解决方法： 为每个角色模型单独设置 facingOffset。将其与移动角度相加，应用为 model.rotation.y = facingOffset + movementAngle。常用值：Soldier/Xbot 使用 +Math.PI，Robot/Fox 使用 +0。

下一步

告诉用户：

你的 3D 游戏现在有自定义模型了！角色由 Meshy AI 生成（或从模型库获取），并经过绑定和动画处理。世界中的物体从 GLB 文件加载。

创建的文件：

• src/level/AssetLoader.js — 使用 SkeletonUtils 的模型加载器
• public/assets/models/ — 生成和下载的 GLB 模型
• OrbitControls 第三人称摄像机

控制方式： 使用 WASD 移动，按 Shift 奔跑，拖动鼠标旋转摄像机，滚动滚轮缩放。 运行游戏即可查看实际效果。调整 Constants.js 中的 MODEL_CONFIG，微调比例和朝向。