scenario-3d

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Scenario 3D Asset Workflows

Scenario 3D资产工作流

Overview

概述

Scenario runs text-to-3D, image-to-3D, and 3D-to-3D models behind the same MCP generation loop used for images. The most reliable pipeline generates a concept image first, then feeds it to an image-to-3D model; direct text-to-3D exists (

txt23d

) but image-to-3D has the larger catalog and more art direction control. Per-family contracts:

scenario-meshy

scenario-rodin

scenario-sparc3d

. Walkable scenes and Gaussian splats:

scenario-3d-worlds

. Retexturing a finished mesh or scene with PBR materials:

scenario-patina-retexture

. Connection and the core generation loop: see the

scenario

skill. If a sibling skill named here is missing from your available skills, ask the user to install it (

npx skills add scenario-labs/skills --skill <name>

); unattended, proceed from tool schemas and flag the gap.

Scenario在与图像生成相同的MCP生成循环背后运行text-to-3D、image-to-3D和3D-to-3D模型。最可靠的工作流是先生成概念图，再将其输入image-to-3D模型；虽然存在直接的text-to-3D功能（

txt23d

），但image-to-3D的模型目录更丰富，美术方向控制力更强。各模型系列对应的技能为：

scenario-meshy

、

scenario-rodin

、

scenario-sparc3d

。可漫游场景和高斯溅射：

scenario-3d-worlds

。使用PBR材质对已完成的网格或场景进行重纹理处理：

scenario-patina-retexture

。连接方式和核心生成循环请参考

scenario

技能。如果你的可用技能中缺少此处提到的兄弟技能，请让用户安装（

npx skills add scenario-labs/skills --skill <name>

）；若处于无人值守场景，请基于工具Schema继续处理并标记该缺失项。

Quick reference

快速参考

Step	Tool	Notes
Find 3D models	`recommend` with the capability and the user's own words ( `search` for a name)	Capabilities: `txt23d` , `img23d` , `3d23d`
Inspect inputs	`model_schema_get`	Always call before `model_run`
Generate	`model_run`	Pass reference images as asset IDs
Wait	`jobs_wait`	Any `job_id` returned without assets ( `in_progress` after a timed-out wait, `queued` or `in-progress` after `wait=false` ) goes in `job_ids` ; never poll `job_get` in a loop
Preview	`asset_display`	Interactive GLB/FBX/VOX/OBJ viewer on MCP App hosts
Download	`asset_download`	Returns a URL; save with `curl -L`

步骤	工具	说明
查找3D模型	结合能力类型和用户的自然语言描述调用 `recommend` （按名称搜索用 `search` ）	能力类型： `txt23d` 、 `img23d` 、 `3d23d`
检查输入参数	`model_schema_get`	调用 `model_run` 前必须先调用此接口
生成	`model_run`	参考图像需以资产ID形式传入
等待	`jobs_wait`	任何未返回资产的 `job_id` （等待超时后状态为 `in_progress` ，或设置 `wait=false` 后状态为 `queued` / `in-progress` ）都需放入 `job_ids` ；切勿循环调用 `job_get` 轮询
预览	`asset_display`	在支持MCP App的主机上提供交互式GLB/FBX/VOX/OBJ查看器
下载	`asset_download`	返回URL；使用 `curl -L` 保存文件

Worked example: concept image to game-ready mesh

实操示例：从概念图到游戏就绪网格

A realistic sequence for "make a 3D treasure chest prop":

Generate the concept: pick a text-to-image model via
```
recommend
```
with the user's own words as
```
prompt
```
, then
```
model_schema_get
```
and
```
model_run
```
with a prompt describing a single centered subject on a plain background. If the user has a reference,
```
upload_asset
```
it (plus
```
upload_asset_complete
```
when multipart) and pass that asset ID instead.
```
recommend
```
with
```
capability="img23d"
```
and the user's own words as
```
prompt
```
. Live members include the Hunyuan 3D, Meshy, Tripo, and Trellis families, and Scenario's own GPT-6 Astra 3D, which reconstructs one object from 1 to 8 photos or renders into an editable mesh with named parts and per-part PBR materials. Astra is built for props and hard-surface subjects, not characters, and its schema carries the cost levers a game team asks about first:
```
buildEffort
```
and
```
refineSteps
```
move the price (both
```
cost_impact
```
), and
```
faceBudget
```
caps the delivered triangle count at export (10k to 50k for a game-ready asset; the default keeps fine detail and is not that). A refinement pass on a previous output was not exposed at authoring time: an edit is a new run with the corrected references.
```
model_schema_get
```
on the chosen model. 3D schemas vary widely: single image vs multi-view arrays, polycount targets, PBR toggles, topology choices.
```
model_run
```
with
```
parameters={"image": "asset_xxx", ...}
```
and
```
wait=false
```
(
```
dry_run=true
```
first to price a batch), then
```
jobs_wait
```
with
```
job_ids=["<job_id>"]
```
(re-call it with the returned
```
pending_job_ids
```
as
```
job_ids
```
if it times out). A downstream step (rig, retexture) has no payload to
```
dry_run
```
until its input mesh exists: quote it from
```
recommend
```
as an estimate, then re-price it with
```
dry_run
```
on the real asset before launching.

asset_display

with the output

asset_id

to preview, then

asset_download

and

curl -L -o chest.glb "<url>"

for engine import.

Multi-view models accept several images of one subject from different angles; the count and the ordering vary per model, so take both from

model_schema_get

(the first image is usually the front view).

实现「制作3D宝箱道具」的实际流程如下：

生成概念图：通过
```
recommend
```
结合用户的自然语言描述作为
```
prompt
```
选择text-to-image模型，然后调用
```
model_schema_get
```
和
```
model_run
```
，提示词描述为「纯色背景上的单个居中主体」。如果用户有参考图，先调用
```
upload_asset
```
上传（分片上传需额外调用
```
upload_asset_complete
```
），然后传入该资产ID即可。
调用
```
recommend
```
，设置
```
capability="img23d"
```
并传入用户的自然语言描述作为
```
prompt
```
。当前可用的模型系列包括Hunyuan 3D、Meshy、Tripo、Trellis，以及Scenario自研的GPT-6 Astra 3D——后者可通过1到8张照片或渲染图重建单个物体，生成带有命名部件和逐部件PBR材质的可编辑网格。Astra专为道具和硬表面物体设计，不支持角色；其Schema包含游戏团队最先关注的成本控制参数：
```
buildEffort
```
和
```
refineSteps
```
会影响价格（均为
```
cost_impact
```
字段），
```
faceBudget
```
会限制导出时的三角形数量（游戏就绪资产通常为1万到5万面；默认值会保留精细细节，并非该范围）。在本文撰写时，暂不支持对已有输出进行细化迭代：修改需要使用校正后的参考图重新运行生成。
对选中的模型调用
```
model_schema_get
```
。3D模型的Schema差异很大：包括单图/多视图数组、面数目标、PBR开关、拓扑选项等。
调用
```
model_run
```
，传入
```
parameters={"image": "asset_xxx", ...}
```
并设置
```
wait=false
```
（批量生成前可先设置
```
dry_run=true
```
预估成本），然后调用
```
jobs_wait
```
并传入
```
job_ids=["<job_id>"]
```
（如果超时，使用返回的
```
pending_job_ids
```
作为
```
job_ids
```
重新调用）。下游步骤（绑定、重纹理）在输入网格存在之前无法进行
```
dry_run
```
：可先通过
```
recommend
```
给出预估价格，启动前再基于实际资产调用
```
dry_run
```
重新定价。
调用
```
asset_display
```
传入输出的
```
asset_id
```
进行预览，然后调用
```
asset_download
```
获取下载链接，使用
```
curl -L -o chest.glb "<url>"
```
保存文件以便导入引擎。

多视图模型支持传入同一物体不同角度的多张图像；数量和顺序因模型而异，因此需从

model_schema_get

的返回结果中获取Schema信息（第一张图通常为正面视图）。

Texture and lighting controls

纹理与光照控制

Several image-to-3D families split texture from geometry, and each dial is one

model_schema_get

away, so read them before promising a look. Authoring-time examples from the Tripo members:

```
texture: false
```
returns a bare mesh with no texture and is a
```
cost_impact
```
field, the cheap path when the user will texture in a DCC.
```
textureQuality
```
(
```
fast
```
,
```
standard
```
,
```
detailed
```
,
```
extreme
```
) also moves the price, and a texture version picker, left empty, keeps the provider's default.
```
delight
```
strips lighting and shadows baked into the reference image so the mesh lights correctly in the user's engine. It defaulted to on; turn it off only when the painted shading is the art style, as on a hand-painted prop. The export stays a lit material either way, so for no engine relighting at all the user sets an unlit shader on import.
The
```
pbr
```
flag's description said PBR on, its default, ignores the texture parameters. A texture setting the user asked for is honored only with
```
pbr: false
```
there, so read that description on the chosen member and say which one won.
Geometry and texture take separate seeds (
```
seed
```
,
```
textureSeed
```
): hold
```
seed
```
and the image fixed and vary
```
textureSeed
```
alone for texture variants on one shape.
```
autoSize
```
scales the output to real-world meters and defaulted to off: set it to
```
true
```
for a real-scale engine import, or the mesh keeps its native size. The asset's
```
dimensions
```
still read the unit-normalized mesh (longest side 1.0) because the meters sit in the GLB's node scale, so
```
dimensions
```
is not proof it failed.

部分image-to-3D模型系列将纹理与几何分离，每个调节参数都可以通过

model_schema_get

获取对应Schema，因此在承诺效果前请先查阅参数。以下是撰写本文时Tripo系列模型的示例：

```
texture: false
```
返回无纹理的裸网格，属于
```
cost_impact
```
字段，适用于用户将在DCC软件中自行制作纹理的低成本场景。
```
textureQuality
```
（
```
fast
```
、
```
standard
```
、
```
detailed
```
、
```
extreme
```
）也会影响价格，若留空纹理版本选择器，则使用服务商的默认设置。
```
delight
```
参数会去除参考图中烘焙的光照和阴影，使网格在用户的引擎中能正确受光。该参数默认开启；仅当绘制的阴影是美术风格的一部分时（例如手绘道具）才关闭。无论如何设置，导出的都是带光照的材质，因此如果完全不需要引擎重新光照，用户需在导入时设置无光照着色器。
```
pbr
```
标志的描述显示，默认开启PBR时会忽略纹理参数。用户要求的纹理设置仅在
```
pbr: false
```
时才会生效，因此请查阅所选模型的Schema描述，明确告知用户哪个参数优先级更高。
几何和纹理使用独立的种子值（
```
seed
```
、
```
textureSeed
```
）：保持
```
seed
```
和输入图像不变，仅修改
```
textureSeed
```
即可生成同一形状的不同纹理版本。
```
autoSize
```
会将输出缩放到真实世界米制单位，默认关闭：若要导入真实比例的引擎，请设置为
```
true
```
，否则网格将保留其原始尺寸。资产的
```
dimensions
```
字段仍返回单位归一化的网格尺寸（最长边为1.0），因为米制比例存储在GLB的节点缩放中，因此
```
dimensions
```
值不对不等于功能失效。

Inspecting results

检查结果

asset_display

renders 3D assets in an interactive viewer (GLB, FBX, VOX, OBJ) on hosts that support MCP Apps; other hosts get the

app_url

dashboard link. The viewer's capture button calls

capture_3d_view

, an app-only tool: it uploads the current camera view as a new image asset and posts the

asset_id

back into the conversation. Use that capture as a reference image for follow-up generations or similarity

search

. Never call

capture_3d_view

yourself; it requires PNG canvas data only the viewer has.

在支持MCP Apps的主机上，

asset_display

会在交互式查看器中渲染3D资产（支持GLB、FBX、VOX、OBJ格式）；其他主机会返回

app_url

仪表板链接。查看器的截图按钮会调用

capture_3d_view

（仅限App端的工具）：它会将当前相机视图作为新的图像资产上传，并将

asset_id

返回到对话中。可将该截图用作后续生成的参考图或用于相似性

search

。切勿自行调用

capture_3d_view

；它需要仅查看器端才有的PNG画布数据。

Refining meshes

网格优化

3D-to-3D utilities (

3d23d

capability) cover retexturing, remeshing, UV unwrapping, and part segmentation. Find them with

recommend

capability="3d23d"

plus the operation in the user's own words. Most take the source

asset_id

in a

kind: "3d"

file field, usually named

model

(also

mesh

file3d

); 400

Input model is required

Provide a reference image or a 3D model

means the mesh went in under another name (an image field, or a URL), never that the tool wants something else.

Splitting a finished mesh into parts is a contested lane, so it stays a

recommend

pick: at authoring time several vendors offered mesh segmentation with a granularity control, one combined the split with a PBR retexture, and image-to-parts members build the parts from the picture instead. A convincing mesh is not a game-ready one: part separation, joint placement, materials, and animation are each their own pass, and polygon caps differ by topology on the members that offer both (a quad cap sat well under the triangle cap on one), so read the slider's

max

off the schema instead of promising a count. A named provider feature is a valid

search

target, but an empty result or one member's body-plan enum does not prove a capability is absent platform-wide. For an unmet need such as a hinged prop, use

recommend

with that need and inspect the returned schemas; if none exposes it, report it as unverified in the inspected models, without inventing a call from the provider's own site.

3D-to-3D工具（

3d23d

能力）涵盖重纹理、重网格化、UV展开和部件分割。可通过

recommend

查找：设置

capability="3d23d"

并加上用户描述的操作。大多数工具要求在

kind: "3d"

类型的文件字段中传入源

asset_id

，字段名通常为

model

（也可能是

mesh

、

file3d

）；如果返回400错误

Input model is required

或

Provide a reference image or a 3D model

，说明网格是通过其他名称传入的（比如图像字段或URL），绝非工具需要其他内容。

将已完成的网格拆分为部件是一个竞争激烈的领域，因此仍需通过

recommend

选择合适的模型：在本文撰写时，多家服务商提供了带粒度控制的网格分割功能，其中一家将拆分与PBR重纹理结合，而image-to-parts类模型则是从图像直接生成带部件的模型。效果逼真的网格不等于游戏就绪网格：部件分离、关节放置、材质、动画都需要单独处理，而且同时支持两种拓扑的模型中，多边形上限因拓扑类型而异（某款模型的四边面上限远低于三角面上限），因此请从Schema中读取参数的

max

值，不要随意承诺面数。服务商的特定功能名称可以作为

search

的有效目标，但空结果或单个模型的身体结构枚举不能证明整个平台都不具备该能力。对于未满足的需求（例如带铰链的道具），请使用

recommend

结合该需求查询并检查返回的Schema；如果没有模型支持该功能，请在已检查的模型中标记为未验证，不要编造服务商官网的接口。

Rigging and animation

绑定与动画

Rigging is a separate

3d23d

step run on a finished mesh, not a flag on the generator. Find the models with

recommend

capability="3d23d"

plus the rigging need in the user's own words.

Body plan picks the model. Humanoid models take the mesh and little else (a front-facing hint, or an approximate height, depending on the model) and infer a biped skeleton. Non-biped work goes to a model exposing

rigType

, whose values cover

quadruped

hexapod

octopod

avian

serpentine

, and

aquatic

Three schema details decide whether the output is usable:

Formats. Rigging models accept GLB, and often OBJ, FBX, or STL. None exposes an output-format field, so the rig comes back as GLB or FBX and most descriptions do not say which: expect a DCC pass when the engine needs the other.
Size ceiling. A
```
max_size
```
on the file input is the exception rather than the rule (one humanoid rigging model caps at 30 MB). Check the schema before assuming a large mesh needs decimating.
Animation versus rig. Where a rigger exposes
```
animation
```
it retargets a preset clip, and its
```
allowed_values
```
are rig-type prefixed (
```
quadruped:walk
```
), so read them rather than guess. By default only the retarget file comes back: set
```
includeRiggedModel
```
to keep the plain rigged mesh too (the two come back as separate assets with identical
```
metadata
```
, so
```
asset_get
```
tells them apart: the retarget has
```
properties.hasAnimations
```
true and an
```
animationFrameCount
```
, the plain rig false and null, and their order is not guaranteed).

When only motion is wanted, motion-transfer video models animate a still character image with no skeleton at all: see

scenario-video

. Video-to-motion models that auto-rig an uploaded mesh are the one place an

outputFormat

enum picks the engine target.

绑定是在已完成网格上运行的独立

3d23d

步骤，而非生成器的一个参数标志。可通过

recommend

查找模型：设置

capability="3d23d"

并加上用户描述的绑定需求。

身体结构决定了所选模型。人形模型仅需网格和少量额外信息（根据模型不同，可能是正面朝向提示或大致身高）即可推断出两足骨骼。非两足角色需要使用支持

rigType

的模型，其取值包括

quadruped

（四足）、

hexapod

（六足）、

octopod

（八足）、

avian

（鸟类）、

serpentine

（蛇形）和

aquatic

（水生）。

三个Schema细节决定了输出是否可用：

格式。 绑定模型支持GLB格式，通常也支持OBJ、FBX或STL。没有模型提供输出格式字段，因此绑定结果会返回GLB或FBX格式，大多数描述不会说明具体是哪种：如果引擎需要另一种格式，预计需要在DCC软件中转换。
大小上限。 文件输入的
```
max_size
```
限制是例外而非普遍规则（某款人形绑定模型的上限为30 MB）。在假设大网格需要减面之前，请先检查Schema。
动画与绑定。 如果绑定工具提供
```
animation
```
参数，说明它支持重定向预设动画片段，其
```
allowed_values
```
以绑定类型为前缀（例如
```
quadruped:walk
```
），因此请查阅参数而不是猜测。默认情况下仅返回重定向文件：设置
```
includeRiggedModel
```
可同时保留纯绑定网格（两者作为独立资产返回，
```
metadata
```
相同，因此可通过
```
asset_get
```
区分：重定向文件的
```
properties.hasAnimations
```
为
```
true
```
且有
```
animationFrameCount
```
值，纯绑定网格为
```
false
```
且值为
```
null
```
，返回顺序不保证）。

如果只需要动作效果，动作迁移视频模型可以完全不需要骨骼，直接让静态角色图像动起来：参见

scenario-video

。支持对上传网格自动绑定的视频转动作模型，是唯一提供

outputFormat

枚举来选择目标引擎的场景。

Common mistakes

常见错误

Running
```
model_run
```
without
```
model_schema_get
```
: 3D model parameters differ far more between models than image models do.
Passing a local file path as an image input:
```
upload_asset
```
first, then pass the returned asset ID.
Hardcoding model IDs: catalogs rotate (a
```
deprecated:<replacement_id>
```
tag names the successor). Re-discover each session,
```
recommend
```
for the need or
```
search
```
for a name.
Pasting raw asset URLs into chat instead of calling
```
asset_display
```
.
Forgetting
```
-L
```
with curl: download URLs may redirect before serving the file.
Promising a named skeleton, an influence count, or bones for wings and extra limbs: pick the closest body plan, then finish the rest in a DCC.
Sending a biped to a
```
rigType
```
model: the enum has no biped value, because humanoids have their own rigging models.

未调用
```
model_schema_get
```
就直接运行
```
model_run
```
：3D模型之间的参数差异远大于图像模型。
传入本地文件路径作为图像输入：请先调用
```
upload_asset
```
上传，再传入返回的资产ID。
硬编码模型ID：模型目录会更新（
```
deprecated:<replacement_id>
```
标签会指明替代模型）。每个会话都应重新发现模型，通过
```
recommend
```
匹配需求或通过
```
search
```
按名称查找。
在聊天中粘贴原始资产URL，而不是调用
```
asset_display
```
。
使用curl时忘记加
```
-L
```
参数：下载URL可能会重定向后才返回文件。
承诺特定的骨骼命名、影响体数量，或翅膀、额外肢体的骨骼：请选择最接近的身体结构，其余部分在DCC软件中完成。
将两足角色发送到
```
rigType
```
模型：该枚举没有两足选项，因为人形角色有专门的绑定模型。