# Meshy AI — 3D 模型生成、绑定和动画您是使用 Meshy AI 生成自定义 3D 模型并将其集成到 Three.js 浏览器游戏中的专家。 **Meshy 是所有 3D 游戏资产的首选来源** — 它从文本描述或参考图像中准确生成您需要的内容，并具有一致的艺术风格和游戏就绪拓扑。 ## 为什么先网格 * **精确匹配**：精确生成游戏所需的角色、道具或场景 - 毫不妥协 * **一致的风格**：来自同一代管道的所有资产都具有凝聚力的外观 * **自定义角色**：指定人物、品牌角色、独特生物 - 全部按照规格生成 * **完整流程**：生成 → 装备 → 动画，全部通过一个工具完成 * **游戏就绪**：控制多边形计数、拓扑和 PBR 纹理以获得最佳 Three.js 性能 ## 备用源如果“MESHY_API_KEY”不可用并且用户拒绝设置，请按顺序退回到这些：后备|来源 |最适合 ---|---|--- `3d 角色库/` |预建 GLB |快速动画人形机器人（士兵、Xbot、机器人、狐狸） `find-3d-asset.mjs` | Sketchfab、Poly Haven、Poly.pizza |搜索现有的免费模型库程序几何 |代码| BoxGeometry/SphereGeometry 作为最后的手段 ## 身份验证所有 Meshy API 调用都需要“MESHY_API_KEY”。 **在开始任何 3D 资产工作之前始终检查此密钥。**如果环境中未设置该密钥，**立即询问用户**： > 我将使用 Meshy AI 生成自定义 3D 模型以获得最佳结果。您可以在 30 秒内获得免费的 API 密钥： > > 1. 注册 > 2. 前往设置 → API 密钥 > 3.创建新的API密钥 > > > 您的 Meshy API 密钥是什么？（或输入“skip”以使用免费模型库）如果用户提供了密钥，请通过以下方式使用它：`MESHY_API_KEY=节点脚本/meshy-generate.mjs ...` 如果用户跳过，请继续使用后备源（字符库 → Sketchfab → Poly Haven）。 ## CLI 脚本 — `scripts/meshy-generate.mjs` 零依赖 Node.js 脚本。处理完整的生命周期：提交任务→轮询→下载GLB→写入meta.json。 ### 文本转 3D（完整管道）根据文本提示生成 3D 模型。两步过程：预览（几何）→细化（纹理）。 # 完整流程：预览→精炼→下载 MESHY_API_KEY= 节点脚本/meshy-generate.mjs \ --模式文本转3D \ --prompt“拿着剑和盾的卡通骑士”\ --输出公共/资产/模型/ \ ——鼻涕虫骑士 # 仅预览（更快，无纹理 - 适合几何检查） MESHY_API_KEY= 节点脚本/meshy-generate.mjs \ --模式文本转3D \ --提示“一个木桶”\ --仅预览 \ --输出公共/资产/模型/ \ --弹头桶 # 使用 PBR 纹理和特定的多边形计数 MESHY_API_KEY= 节点脚本/meshy-generate.mjs \ --模式文本转3D \ --提示“科幻悬停自行车”\ --pbr \ --polycount 15000 \ --ai-model meshy-6 \ --输出公共/资产/模型/ \ --slug 悬浮自行车 ### 图像转 3D 将参考图像转换为 3D 模型。支持 URL、本地文件和 base64 数据 URI。 # 来自网址 MESHY_API_KEY= 节点脚本/meshy-generate.mjs \ --模式图像转3D \ --image“https://example.com/character-concept.png”\ --输出公共/资产/模型/ \ --蛞蝓字符 # 来自本地文件（自动转换为base64） MESHY_API_KEY= 节点脚本/meshy-generate.mjs \ --模式图像转3D \ --image "./concept-art/hero.png" \ --输出公共/资产/模型/ \ ——蛞蝓英雄 ### Auto-Rig（仅限人形机器人 - 所有双足角色强制）向生成的人形模型添加骨架并**自动下载行走+跑步动画 GLB**。输入任务 ID 来自已完成的文本转 3d 或图像转 3d 任务。 MESHY_API_KEY= 节点脚本/meshy-generate.mjs \ --模式装备\ --task-id <网格任务id> \ --高度1.8 \ --输出公共/资产/模型/ \ ——蛞蝓英雄这会自动生成 3 个文件： * `hero.glb` — 带骨架的装配模型 * `hero-walk.glb` — 行走动画（自动下载） * `hero-run.glb` — 奔跑动画（自动下载） **始终将生成 → 装备链作为人形机器人的一个原子步骤。**切勿将人形角色保留为静态模型。 **限制：** 绑定仅适用于具有明确定义的四肢的纹理人形（双足）模型。不适用于动物、车辆、抽象形状或无纹理的网格。 ### 动画将动画应用于装配模型。需要已完成的装备任务 ID 和动画动作 ID。 MESHY_API_KEY= 节点脚本/meshy-generate.mjs \ --模式动画\ --task-id <装备任务id> \ --action-id 1 \ --输出公共/资产/模型/ \ --蛞蝓英雄行走 ### 检查状态轮询任何任务的当前状态。 MESHY_API_KEY= 节点脚本/meshy-generate.mjs \ --模式状态\ --task-id <任务id> \ --task-type text-to-3d # 或：图像转3d、绑定、动画 ### 非阻塞模式无需等待即可提交任务。在管道中很有用。 MESHY_API_KEY= 节点脚本/meshy-generate.mjs \ --模式文本转3D \ --提示“一把水晶剑”\ --无民意调查 # 后来： MESHY_API_KEY= 节点脚本/meshy-generate.mjs \ --mode status --task-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 ` 更改最大纹理尺寸（默认值：1024） * 首次运行可能需要一些时间，因为 `npx` 下载 `@gltf-transform/cli` * 如果 `gltf-transform` 不可用，脚本会发出警告并继续处理原始文件优化的 GLB 使用 meshopt 压缩，并在运行时需要 `MeshoptDecoder` — 模板 `AssetLoader.js` 自动包含此内容。 # 跳过特定代的优化 MESHY_API_KEY= 节点脚本/meshy-generate.mjs \ --mode text-to-3d --prompt "a木桶" --preview-only \ --no-optimize --output public/assets/models/ --slug 桶 # 自定义纹理大小（例如，移动设备为 512） MESHY_API_KEY= 节点脚本/meshy-generate.mjs \ --mode text-to-3d --prompt "a木桶" --preview-only \ --texture-size 512 --output public/assets/models/ --slug 桶 # 直接重新优化现有的GLB 节点脚本/optimize-glb.mjs public/assets/models/barrel.glb --texture-size 512 ## API 参考基本 URL：`https://api.meshy.ai/openapi` ### 文本转 3D **POST** `/v2/text-to-3d` — 创建预览或优化任务预览有效负载： { “模式”：“预览”， "prompt": "拿着剑和盾的卡通骑士", "ai_model": "最新", “拓扑”：“三角形”， “目标多计数”：10000 } 优化有效负载： { “模式”：“精炼”， "preview_task_id": "<预览任务 ID>", “enable_pbr”：真， "texture_prompt": "手绘奇幻风格" } **GET** `/v2/text-to-3d/:id` — 检索任务（轮询此）完成后的响应： { "id": "任务 uuid", “状态”：“成功”， “进度”：100， “模型网址”：{ "glb": "https://assets.meshy.ai/...", "fbx": "https://assets.meshy.ai/...", "obj": "https://assets.meshy.ai/...", “usdz”：“https://assets.meshy.ai/...” }, “纹理网址”：[ {“base_color”：“https://...”} ], “thumbnail_url”：“https://...” } 可选参数： * `ai_model`: `meshy-5`, `meshy-6`, `latest` (默认: `latest`) * `model_type`: `standard` 或 `lowpoly` * `topology`: `quad` 或 `triangle` (默认: `triangle`) * `target_polycount`：100–300,000（默认值：10,000） * `symmetry_mode`: `off`, `auto`, `on` (默认: `auto`) * `pose_mode`: `a-pose`、`t-pose` 或空字符串 * `enable_pbr`：生成金属、粗糙度和法线贴图 ### 图像转 3D **POST** `/v1/image-to-3d` — 创建任务 { "image_url": "https://example.com/photo.png", "ai_model": "最新", “enable_pbr”：假， “should_texture”：正确， “拓扑”：“三角形”， “目标多计数”：10000 } **GET** `/v1/image-to-3d/:id` — 检索任务支持 `image_url` 作为公共 URL、base64 数据 URI (`data:image/png;base64,...`) 或通过 **POST** `/v1/multi-image-to-3d` 的多图像（来自不同角度的 1-4 个图像）。 ### 索具 **POST** `/v1/rigging` — 创建绑定任务 { "input_task_id": "<文本转 3d 或图像转 3d 任务 ID>", “身高米”：1.7 } **GET** `/v1/rigging/:id` — 检索任务结果包括： * `rigged_character_glb_url` — 为 Three.js 准备的装配 GLB * `rigged_character_fbx_url` — 已操纵的 FBX * `basic_animations` — 免费包含步行/跑步 GLB URL ### 动画 **POST** `/v1/animations` — 创建动画任务 { "rig_task_id": "<装配任务 ID>", “action_id”：1 } **GET** `/v1/animations/:id` — 检索任务结果包括“animation_glb_url”、“animation_fbx_url”。 ### 任务状态所有任务的进展经过：`PENDING`→`IN_PROGRESS`→`SUCCEEDED`/`FAILED`/`CANCELED` 以 5 秒的间隔进行轮询。任务通常在 30 秒到 5 分钟内完成，具体取决于复杂性。 ### 资产保留 Meshy 将生成的资产保留**3 天**（企业版无限制）。赶紧下载吧。 ## 快速参考：静态道具（无需装备）对于非人形资产（道具、布景、建筑物），跳过装配： # 生成 MESHY_API_KEY= 节点脚本/meshy-generate.mjs \ --mode text-to-3d --prompt "木桶，低多边形游戏资产" \ --polycount 5000 --output public/assets/models/ --slug 桶 # 与 loadModel 集成（常规克隆，无 SkeletonUtils） constbarrel=awaitloadModel('assets/models/barrel.glb'); 场景.add(桶); ## 生成后验证（强制）加载任何 Meshy 生成的模型后，**始终验证方向和比例**，然后再继续。网格模型具有不可预测的面向方向和比例。跳过此步骤会导致面朝后的角色和模型溢出其容器。 ### 自动方向检查网格模型通常面向 +Z，但情况有所不同。加载后，**记录边界框并通过 Playwright MCP 或开发工具进行目视验证**： // 加载任何 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(`[模型] ${slug} — 大小：${size.x.toFixed(2)} x ${size.y.toFixed(2)} x ${size.z.toFixed(2)}`); console.log(`[模型] ${slug} — 中心: ${center.x.toFixed(2)}, ${center.y.toFixed(2)}, ${center.z.toFixed(2)}`); **固定朝向：** * 从 `rotationY: Math.PI`（180 度）开始 — 大多数 Meshy 模型需要它面向 -Z * 如果模型默认面向+Z，需要面向相机：`rotationY: 0` * 如有疑问：截取屏幕截图，检查脸部/正面指向哪个方向，进行调整 * 将 `rotationY` 存储在每个模型的 Constants.js 中——切勿在实体文件中进行硬编码 ### 自动缩放拟合模型必须适合其游戏环境。加载后： // 计算比例以适合目标高度 const box = new THREE.Box3().setFromObject(model); const currentHeight = box.max.y - box.min.y; 常量目标高度 = 2.0; // 以世界单位表示的所需高度 const autoScale = 目标高度 / 当前高度； model.scale.setScalar(autoScale); 对于容器配件（例如，环内的机器人）： // 确保模型适合容器边界 const 容器宽度 = RING.PLATFORM_WIDTH * 0.8; // 环宽度的 80% const modelWidth = box.max.x - box.min.x; if (modelWidth * currentScale > 容器宽度) { const fitScale = 容器宽度 / 模型宽度; model.scale.setScalar(Math.min(currentScale, fitScale)); } **模型集成后务必拍摄 Playwright 屏幕截图**以直观地验证： 1.人物面朝正确的方向 2.角色适合他们的环境 3.角色不会穿过地板/墙壁/彼此 ### 地板对齐将模型置于 X/Z 中心并将脚置于 Y=0 上： const box = new THREE.Box3().setFromObject(model); const center = box.getCenter(new THREE.Vector3()); model.position.y = -box.min.y; // 脚着地 model.position.x = -center.x; // 居中 X model.position.z = -center.z; // Z 居中 ## 绑定：人形角色的强制要求 **每个人形角色都必须被操纵。** 静态模型需要看起来很人工的黑客编程动画（移动包装组）。绑定模型获得适当的骨骼动画——行走、跑步、拳击等。 ### 何时装备型号类型|装备？ |为什么 ---|---|--- 人形角色（玩家、NPC、敌人）| **是的——总是** |行走/奔跑/空闲/攻击的骨骼动画有腿的动物| **是** |行走/跑步动画车辆、道具、建筑 |没有 |静态或简单旋转抽象形状，粒子|没有 |程序动画 ### 完整流程：生成→装备→动画→集成 **第1步：生成模型** MESHY_API_KEY= 节点脚本/meshy-generate.mjs \ --模式文本转3D \ --提示“一个程式化的机器人拳击手，低多边形游戏角色，全身”\ --pbr --polycount 15000 \ --output public/assets/models/ --slug 机器人 **第2步：Rig**（自动从meta.json读取refineTaskId） MESHY_API_KEY= 节点脚本/meshy-generate.mjs \ --模式装备\ --task-id \ --高度1.7 \ --output public/assets/models/ --slug 机器人装备索具回报： * `rigged_character_glb_url` — 带骨架的装备 GLB（使用它作为基础模型） * `basic_animations.walking` — 行走动画 GLB（免费，包含） * `basic_animations.running` — 运行动画 GLB（免费，包含） **第 3 步：添加自定义动画**（可选，用于特定于游戏的操作） # 每个action_id对应一个不同的动画 MESHY_API_KEY= 节点脚本/meshy-generate.mjs \ --模式动画\ --task-id <装备任务id> \ --action-id \ --output public/assets/models/ --slug 机器人冲床 **第 4 步：与 `loadAnimatedModel()` \+ `AnimationMixer` 集成**：从'./level/AssetLoader.js'导入{loadAnimatedModel}；从 '三' 导入 * 作为三； // 加载装配模型（SkeletonUtils.clone 保留骨骼绑定） const { 模型，剪辑 } = 等待 loadAnimatedModel('assets/models/robot-rigged.glb'); const mixer = new THREE.AnimationMixer(model); // 记录剪辑名称 - 它们因模型而异 console.log('剪辑:', Clips.map(c => c.name)); // 加载额外的动画 GLB 并将其剪辑添加到同一个混合器中 const walkData =等待loadAnimatedModel('assets/models/robot-walk.glb'); const walkClip = walkData.clips[0]; const walkAction = Mixer.clipAction(walkClip); // fadeToAction 模式用于平滑过渡函数 fadeToAction(nextAction, 持续时间 = 0.3) { if (activeAction) activeAction.fadeOut(持续时间); nextAction.reset().setEffectiveTimeScale(1).setEffectiveWeight(1).fadeIn(duration).play(); 主动动作=下一个动作； } // 在更新循环中：混合器.更新(增量); ## 及时的工程技巧好的提示可以产生更好的模型：目标|提示|为什么 ---|---|--- 游戏角色| “风格化的妖精战士，低多边形游戏角色，全身”| “低多边形”+“游戏角色”=游戏就绪拓扑道具| “一个木制宝箱，程式化，封闭”|简单、具体、单一对象环境片| “梦幻石拱门，低多边形，游戏资产”| “游戏资产”标志着干净的几何结构车辆 | “科幻悬停自行车，侧视图，简洁的拓扑结构”| “干净的拓扑”=更少的工件 **避免：** * 一个提示中有多个对象（“骑士和龙”）——单独生成 * 模糊的提示（“一些很酷的东西”）——具体说明风格和形式 * 室内/建筑场景——网格最适合单个对象 ## 与现有管道集成网格生成的模型插入现有的 3D 资产管道： ┌──────────────────────────────────────────────────────┐ │ 3D 资源来源 │ ├──────────────┬──────────────┬────────────────────────┤ │ 免费库│ 角色库 │ Meshy AI │ │ find-3d-asset │ 3d-char-lib/ │ meshy-generate.mjs │ │ .mjs │ │ 文本/图像 → 3D │ │ │ │ 装备 → 动画 │ ├──────────────┴──────────────┴────────────────────────┤ │ AssetLoader.js │ │ loadModel() / loadAnimatedModel() │ ├──────────────────────────────────────────────────────┤ │ 三.js 游戏 │ └──────────────────────────────────────────────────────┘ 所有源都将 GLB 文件输出到“public/assets/models/”中。 `AssetLoader.js` 并不关心 GLB 来自哪里 - 它以相同的方式加载它们。 ## 清单 *“MESHY_API_KEY”已选中 - 如果未设置，则提示用户，或者用户跳至后备 * 提示是特定的（样式、多边形数量、单个对象） * **所有人形角色都已装配** - 永远不要跳过双足模型的装配 * 在 3 天到期之前下载 GLB * **完成生成后验证** — 检查方向、比例、地板对齐 * **剧作家截图** — 目视确认面朝方向 + 适合环境 * 在 Constants.js 中为每个模型设置 `rotationY` （大多数 Meshy 模型需要 `Math.PI`） * 静态模型使用 `loadModel()` （常规克隆） * 绑定模型使用 `loadAnimatedModel()` (SkeletonUtils.clone) * 记录剪辑名称并为动画模型定义“clipMap” * `.meta.json` 与 GLB 一起保存，并带有任务 ID，以实现可追溯性 * `npm run build` 成功

网状的

包含技能