scenario-3d

Scenario 3D 资产工作流

概述

先生成概念图，再运行图像转 3D：它的目录更大，艺术指导也比文本转 3D（txt23d）更丰富。各系列的专属流程：scenario-meshy、scenario-rodin、scenario-sparc3d。可漫游场景和 Gaussian splats：scenario-3d-worlds。对已完成的网格或场景进行 PBR 重新贴图：scenario-patina-retexture。在 Blender 中，通过 Scenario for Blender 扩展使用：scenario-blender。连接和核心工作流程：scenario 技能。如果你可用的技能中缺少此处提到的同级技能，请让用户安装（npx skills add scenario-labs/skills --skill <name>）；如果无法等待用户响应，请根据工具 schema 继续操作，并指出这一缺失。

快速参考

步骤	工具	说明
查找 3D 模型	使用 recommend 并指定功能和用户自己的描述（按名称查找时使用 search）	功能：txt23d、img23d、3d23d
检查输入	model_schema_get	在调用 model_run 前务必先调用
生成	model_run	将参考图像作为资产 ID 传入
等待	jobs_wait	任何返回但未带资产的 job_id 都应放入 job_ids；切勿循环调用 job_get
预览	asset_display	在 MCP App 宿主上交互式查看 GLB/FBX/VOX/OBJ
下载	asset_download	返回一个 URL；使用 curl -L 保存

示例：适用于游戏的宝箱

• 计划检查。 第 1 步之前，先对每个后续步骤运行 recommend（第 2 步，以及任何绑定或重新贴图步骤）。标记为 requires_plan_upgrade 的条目只有在前面的步骤已付费后才会因 403（ModelAccessRestrictedError）而失败；请先升级套餐，或改选其他选项。如果 img23d 调用询问是否已有概念图，请选择概念图分支：第 1 步会生成这些图。
• 批量价格。 基于同一张实际概念图计算每个资产的价格：对每个候选项运行 dry_run（后续环节按第 4 步处理），再乘以数量。撰写本文时，一个基于 LLM 的选项默认工作量报价为 1,300 CU，单图 Tripo 生成器为 45。套餐额度用完后，每个任务所需的等待时间会随成本增加。

1. 生成概念图：使用用户自己的描述作为 prompt，通过 recommend 选择文生图模型，然后调用 model_schema_get 和 model_run。提示词应指定单个居中主体和纯色背景。展示一个非双足生物，视线平齐，采用侧面或四分之三角度，所有腿都应清晰可见且不被身体遮挡：俯视会隐藏腿底和身体高度。若双足生物要用于绑定，请采用“绑定与动画”中的姿势。如果用户有参考图，使用 upload_asset 上传（分片上传时还需调用 upload_asset_complete），并改为传入该素材 ID。

2. 使用用户自己的描述作为 prompt，调用 recommend，并设置 capability="img23d"。当前可用成员包括 Hunyuan 3D、Meshy、Tripo 和 Trellis 系列，以及 Scenario 自有的基于 LLM 的 3D 生成工具：GPT-6 Astra 3D 和 Claude Opus 5.5 3D（撰写本文时后者成本更低；用 dry_run 比较两者）。这两款基于 LLM 的工具仅适用于以下情况：

   • 将 1 到 8 张照片或渲染图中的单个物体重建为可编辑网格，包含命名部件和逐部件 PBR 材质；
   • 适用于道具和硬表面主体，不适用于角色或生物；
   • 按 buildEffort 计价：standard、high（默认值）、maximum；
   • 使用 faceBudget 限制导出三角形数量（游戏范围见步骤 3）；
   • 通过编辑结果来修改它（参见“网格优化”）。

3. 使用 model_schema_get 检查图像输入、多边形数量、PBR 和拓扑控制项。此道具的目标是 10k 到 50k 个三角形；切勿假定默认值符合此预算。仅使用已公开的控制项：

   • **数值字段：**读取 min 和 max；如果没有，则读取说明。
   • **枚举：**读取 allowed_values 及其拓扑和数量含义（scenario-rodin 涉及 qualityMeshOption）。四边形数量不等于三角形数量。
   • **没有面数控制项，或目标低于其范围：**先生成，再按需降低网格面数（参见“网格优化”）。切勿臆造面数相关字段；scenario-sparc3d 涉及没有此类字段的成员。

   检查输出的三角形数量是否符合预算。撰写本文时：

   • Tripo（faceLimit）和 Meshy（targetPolycount，按 scenario-meshy 的说明设置）都能达到预算范围的上下限。在 10k 时，八足生物的每条腿和爪子都得以保留，箱子的挂锁和把手也同样保留。Meshy 的 Smart Topology 成员上限较低，为 15k 或 30k。
   • Hunyuan 3D（faceCount，最低 40k）仅覆盖范围上端，而 Trellis（decimationTarget，最低 100k）的起点更高。只有当目标低于该成员的下限时，才降低网格面数。

4. 使用 parameters={"image": "asset_xxx", ...} 调用 model_run，并设置 dry_run=true 以估算价格。然后设置 wait=false 正式运行，并将其 job_id 传给 jobs_wait（job_ids=["<job_id>"]）；试运行不会创建任务。如果调用超时，使用返回的 pending_job_ids 再次调用 jobs_wait。在输入网格尚不存在时，下游步骤（绑定、重新贴图）没有可用于 dry_run 的有效载荷：通过 recommend 获取报价，然后在实际素材上使用 dry_run 重新计价，再启动任务。切勿使用占位 ID 调用 dry_run：文件 ID 会在检查计划访问权限前解析，因此会返回 404，无法证明任何事情。

5. 对输出的 asset_id 调用 asset_display，然后调用 asset_download，并运行 curl -L -o chest.glb "<url>"。如果 asset_get 显示 properties.format 为 glb，则省略 format：它会逐字节返回存储的原始文件。format 可转换为 glb、fbx 或 obj；对于基于 LLM 的成员，传入 glb，因为它们存储的是 Blender 文件。对于已存储的 GLB，format: "glb" 会重新导出文件：撰写本文时纹理和三角形相同、索引更小，但文件不同。如果 Unity 项目没有 glTF 导入器，则请求 fbx，同时保留 GLB：撰写本文时，FBX 仅嵌入了两张图像，因此可能缺少 PBR 贴图。 仅使用提示词构建。 两个基于 LLM 的成员都支持 txt23d。如果用户不想审核任何概念，可跳过步骤 1。在步骤 2 中，使用 capability="txt23d" 调用 recommend，并将用户的话作为 prompt。后续步骤 3 到 5 中使用 images: []；在 prompt 中描述对象并列出所需部件。宝箱的 lid、body 和 padlock 会以这些节点名称返回。

多视图模型会使用同一主体的多张图像；通过 model_schema_get 查看图像数量和字段。侧面字段应与主体自身的左右侧对应：在 Tripo 的多视图成员中，编写时的 leftImage 指角色自身的左侧（鼻子朝向画面左侧），rightImage 则是镜像侧。按观看者视角标注的图像会颠倒左右；如果一对图像顺序弄反，正面和背面可能会融合成一个外壳。

纹理和光照控制

一些图像转 3D 系列会将纹理与几何体分开处理。承诺特定效果前，先通过 model_schema_get 查看各项参数。以下是编写时来自 Tripo 成员的示例：

• texture: false 会返回没有纹理的网格，并且是一个 cost_impact 字段：适合用户在 DCC 中添加纹理的低成本方案。textureQuality 也会影响价格；如果纹理版本选择器为空，则使用提供方的默认值。
• delight 会去除参考图像中烘焙的光照效果，让网格能在引擎中重新受光。默认开启；只有当绘制式阴影属于美术风格时才将其关闭。无论如何，导出的材质都带有光照：如果完全不需要重新受光，用户应在导入时设置无光照着色器。
• 根据说明，默认开启的 pbr 会忽略纹理参数。只有在此处设置 pbr: false，请求的纹理设置才会生效：请阅读所选成员的说明，并说明最终生效的是哪一项。
• 几何体和纹理使用不同的种子（seed、textureSeed）：固定 seed 和图像，只改变 textureSeed，即可为同一形状生成不同的纹理版本。
• autoSize 会将输出缩放到以米为单位的真实尺寸，默认关闭：设置为 true 可按真实比例导入。dimensions 仍会读取单位归一化后的网格（最长边为 1.0），因为米制缩放存储在 GLB 的节点缩放中：这并非错误。

检查结果

不支持 MCP Apps 的宿主会显示 app_url 链接，而不是查看器。查看器的截图按钮会调用 capture_3d_view，这是一个仅供应用使用的工具：它会将当前视图上传为图像资源，并将其 asset_id 发送到对话中。可将其重新用作生成参考图，或用作相似度 search 图像。切勿自行调用 capture_3d_view：它需要 PNG 画布数据，而只有查看器才有这些数据。

网格细化

3D 到 3D 工具可重新贴图、重建网格、展开 UV 和分割部件：用 recommend，并将 capability="3d23d" 与用户自己的措辞中的操作一并提供。大多数工具会将源 asset_id 放在 kind: "3d" 文件字段中，通常是 model（也可能是 mesh、file3d、sceneFile）。400 错误 Input model is required 或 Provide a reference image or a 3D model 表示网格被放在了其他字段下（图像字段或 URL）。

第 2 步中基于 LLM 的工具也可以编辑现有网格、道具或角色：

• sceneFile 接收其 asset_id（任何 3D 模型，返回格式相同），images 保持为空，prompt 说明要进行的更改。
• buildEffort 应与更改相匹配，而非与对象相匹配：重新着色用 standard，添加或重塑部件用 high 或 maximum。
• 价格取决于 buildEffort，而非网格；在创作时，recommend 不会为编辑报价：对任何项目网格执行 dry_run 即可获取报价。
• 重新着色会保留所有部件名称和面数。重塑不受上限约束（faceBudget 会被忽略）：一个有 4,817 个三角形的猫模型变成了 788,954 个三角形，因此要计划在导入引擎前重新网格化。
• 替换的材质会保留旧名称；只有新增部件会获得新名称。编辑内容由系统生成：请检查提示词未提及的内容，并与源模型对照。
• GPT-6 Astra 3D 的说明还声称支持 Mixamo 命名的骨架、ARKit 面部形状、动画循环、UV 重新展开和模块化套件，因此它也会参与这些 recommend 调用的竞争。

将完成的网格拆分成部件是一个竞争激烈的领域，因此仍通过 recommend 选择。在创作时，多个供应商提供了带粒度控制的分割功能；其中一个还将其与 PBR 重新贴图结合，另一些图像转部件工具则直接从图片构建部件。看起来可信的网格不等于可用于游戏的网格：部件分离、关节、材质和动画都需要分别处理。多边形上限因拓扑而异（某个工具的四边形上限远低于其三角形上限）：请查看滑块的 max 值，不要承诺具体数量。供应商明确命名的功能可以作为 search 目标，但搜索结果为空或某个工具没有对应枚举值，并不能证明整个平台都不具备该能力。用未满足的需求进行 recommend（例如带铰链的道具），检查返回的 schema；如果没有任何工具支持，就说明该能力尚未验证。切勿根据供应商网站编造调用方式。

迈向可用于游戏的分阶段流程

一次图像转 3D 运行会把纹理烘焙到生成器选定的 UV 上。要用于引擎的网格通常还要经过更多步骤，每个输出的 asset_id 都会传给下一个工具的 kind: "3d" 字段：

1. 几何体：有多个角度时，使用多视图成员；在支持的情况下设置 texture: false，并在 pbr 会覆盖纹理设置时同时设置 pbr: false。
2. UV 展开。
3. 根据提示词、图像或风格参考，为展开 UV 的网格重新贴图。
4. 最后再绑定骨骼，针对最终要交付的拓扑进行操作。

第一个步骤之后的每一步，都是一次 3d23d recommend 选择，也都需要单独计费：启动前，先用真实输入运行 dry_run。整个流程中：

• 重新贴图的架构。 避免使用会重建 UV 的设置，否则会丢弃展开结果。检查相同的 pbr 默认值（编写时，Tripo 贴图成员默认启用 PBR）。如果架构未明确说明 UV 设置，优先选择明确提供保留现有 UV 设置的成员。
• 输入上限。 编写时，一个 UV 展开器最多可处理 30,000 个面：将生成器的面数上限设为更低值（Tripo 多视图成员提供了 faceLimit 和 smartLowPoly），或先重新网格化以减少面数。
• 步骤间检查。 对每个输出调用 asset_display。如果没有查看器，就在各步骤之间比较面数、UV 和 asset_get 返回的 dimensions，并检查缩略图资源；它可能会比任务完成晚几秒更新。hasUVs 只能证明 UV 存在，不能证明布局整洁；UV 展开器生成的 “albedo” PNG 可能只是预览，而非纹理图集。
• 继承的缺陷。 渲染时变暗或翻转的面表示法线已翻转，后续步骤会继承这一问题。缩放和轴心点可能会在步骤间发生变化，即使是同一供应商的工具也不例外（如上文的 autoSize）：绑定骨骼前，请在 DCC 中确认两者。
• 同级格式。 除非下一个架构另有要求，或网格为四边面（应保留为 FBX），否则继续使用 GLB。如果没有 GLB，就使用下一个架构列出的 OBJ 或 FBX（dry_run 可能会跳过格式检查，因此真实运行时才能确认），否则通过 asset_download 的 format 进行转换。

手动修复法线、原点或命名属于 DCC 工作，并非 MCP 调用。scenario-blender-expert 技能会驱动 Blender；它需要在本地安装，因此 skill_get 无法获取它。

骨骼绑定与动画

骨骼绑定是针对已完成网格的独立 3d23d 步骤，不是生成器标志：使用 recommend 推荐这项功能，并附上用户用自己的话描述的骨骼绑定需求。

身体类型决定模型。人形骨骼绑定器接收网格，至多再接收一个正面朝向提示或大致身高，并推断双足骨架。非双足模型使用公开 rigType 的模型：quadruped、hexapod、octopod、avian、serpentine、aquatic。静态道具没有身体类型：如果 recommend 返回 ask_user，更接近的步骤是部件分割。

要进行骨骼绑定的双足模型，应从 T 姿或 A 姿概念图开始（全身、正面视图、手臂与躯干分开、纯色背景）：骨骼绑定器会根据姿势推断关节。非双足模型沿用步骤 1 的视图。对于四足模型：

• 选择一个架构支持四边形拓扑的图像转 3D 模型，并设置该选项；默认值为三角形。 在编写本文时，Tripo P2 和 3.1 模型有一个 quad 开关，且面数上限较低； scenario-rodin 和 scenario-meshy 使用各自系列的控制项名称。
• 四边形输出为 FBX。glTF 仅存储三角形，因此 format: "glb" 或仅支持 GLB 的步骤会将其三角化。
• 保留 FBX，并使用文件字段列出 FBX 的模型进行骨骼绑定；在承诺提供四边形网格前，先在 DCC 中检查每个输出的面类型。如果骨骼绑定结果以 GLB 返回，则它已被三角化：同时交付四边形 FBX 并说明这一点。

有三个架构细节决定输出是否可用：

• 格式。 骨骼绑定器接受 GLB，通常也接受 OBJ、FBX 或 STL，且不提供输出格式字段。骨骼绑定结果以 GLB 或 FBX 返回，通常不会提前说明：如果引擎需要另一种格式，请做好使用 DCC 处理的准备。
• 大小上限。 文件的 max_size 很少见（某个人形骨骼绑定器的上限为 30 MB）：请先检查架构，再进行减面。
• 动画与骨骼绑定。 如果骨骼绑定器提供 animation，它会重定向预设动画片段；其 allowed_values 会以骨骼类型为前缀（quadruped:walk），因此请仔细查看。默认情况下只会返回重定向后的文件：设置 includeRiggedModel，同时保留未添加动画的骨骼绑定模型。两者作为独立资源返回，且 metadata 相同，顺序不固定。asset_get 可以区分它们：重定向后的资源中，properties.hasAnimations 为 true，且有 animationFrameCount；未添加动画的骨骼绑定模型中，前者为 false，后者为 null。

如果只需要动作，动作迁移视频模型无需骨架，就能为静态角色图像制作动画：参见 scenario-video。自动为上传网格添加骨骼绑定的视频转动作模型，是唯一会通过 outputFormat 枚举选择引擎目标的情况。

常见错误

• 未调用 model_schema_get 就运行 model_run：3D 参数因模型而异的程度远高于图像参数。
• 将模型 ID 硬编码：目录会轮换（deprecated:<replacement_id> 标签会标出后继模型）。 每个会话都应重新发现模型：按需求使用 recommend，按名称使用 search。
• 承诺所选模型未说明的指定骨架、影响关节数，或翅膀和额外肢体的骨骼：选择最接近的身体类型，然后在 DCC 中完成后续处理。
• 将双足模型交给 rigType 模型：该枚举没有双足选项；人形模型有专用的骨骼绑定器。