edemaistre/unity-plugin

Scenario for Unity：代理指南

当用户在 Scenario 窗口中启用 “代理可以使用 Scenario 和此项目” 时，Unity 编辑器会提供此 MCP 服务。每个工具都在编辑器内运行：生成的文件会进入项目的 Assets/，场景编辑是可撤销的步骤，付费调用遵循与窗口相同的价格检查和审批规则。

开始

1. scenario_status：账户信息、计费的 Scenario 项目、消费是否开启、你的每次调用限制和会话剩余预算、渲染管线、2D 或 3D、当前活动场景。如果显示已登出，请让用户在 Scenario 窗口中登录；在此之前，其他任何操作都无法进行。
2. scene_info：层级路径、组件、选择。在任何地方使用这些路径作为 target 和 path。

费用

费用以创意单位（CU）计费。

• estimate 是免费的，返回请求的确切价格。当用户关心成本或请求很大（视频、3D、多张图像）时，请在 generate 或 workflow_run 之前调用它。
• generate、workflow_run 和 prompt_spark 是付费的。当用户给了预算时，传递 max_cu：超过该值则不会发送任何内容。
• 超出每次调用限制或会话预算时，调用会等待最多两分钟，等待用户在 Unity 中的 “批准”。告诉用户你正在等待。“未批准”表示未发送任何内容；除非用户要求，否则不要重试。
• 未知结果。 如果付费调用返回“结果未知”，则请求可能已经运行并已计费。切勿为同一请求再次调用它。一分钟后，使用其 local_id 调用 jobs。
• 如果关闭了消费（设置或 SCENARIO_NO_SPEND=1），付费工具会在发送前拒绝。定价、浏览、导入、上传和场景工具仍然有效。
• upload_reference、import_asset、models_find、motions_find、model_schema 和 estimate 是免费的。

选择模型

• 使用 output_type（image、video、model3d、motion、audio、material、skybox）调用 models_find 可列出目录，包括团队自己的训练模型。
• 使用 recommend_for_prompt 调用 models_find 将返回 Scenario 根据提示排序的推荐，包含成本和速度说明。当用户未指定模型时，优先使用此方法。
• model_schema 提供输入：名称、选项、范围、默认值、哪些输入是文件。仅发送架构中列出的参数；在定价前会拒绝未知名称。

生成并放置

generate 对请求进行定价，发送一次，等待，导入文件并放置结果：

output_type	不带 target	带 target
image	纹理（2D 项目中的精灵图）放置在一个新的四边形或精灵图上	设置到目标的 SpriteRenderer、Image、RawImage 或渲染器上
material	为当前活动管线创建的材质及其贴图，放置在一个新的球体上	设置到目标的渲染器及其子对象上
skybox	设置为场景天空盒的 Skybox/Panoramic 材质	同上
model3d	作为预制体导入的 GLB，在场景视图枢轴点处实例化	实例化并放置在目标旁边
motion	带有动画控制器（每个剪辑一个状态）的动画 GLB，在枢轴点处实例化；在播放模式下播放	实例化并放置在目标旁边
audio	放置在新 AudioSource 上的 AudioClip	放置在目标的 AudioSource 上（如缺失则添加）
video	放置在新屏幕四边形上的 VideoClip	放置在目标的 VideoPlayer 上（如缺失则添加）

结果包含 files（Unity 资源路径）、placed（层级路径）、asset_ids（Scenario 的 ID，可重复用作输入）、job_id、quoted_cu 和 charged_cu。设置 place: false 将仅导入而不修改场景。没有调用会阻塞超过 45 秒：3D、视频和长音频通常会用 next 响应（仍在运行）。作业会继续执行，自行导入和放置；使用 local_id 和 wait_seconds 调用 jobs 直到完成，切勿再次生成。对于批处理，使用 wait: false 发送每个请求，然后使用 jobs 跟进它们。

文件输入（参考图像、起始帧、3D 模型、音频）接受 Scenario 资源 ID 或 Unity 资源路径；Unity 文件会上传一次，免费。

3D 结果，预期如下：

• 每个结果一个模型：某些模型添加的 OBJ、MTL 和 PBR 贴图副本会被跳过。FBX、Blender 和 VOX 结果会作为 GLB 到达。
• 返回行走和奔跑文件的绑定（Meshy Rigging、带 includeRiggedModel 的 Tripo）是一个模型，其控制器包含所有剪辑。以厘米为单位的绑定会以 1% 的比例放置。
• 高斯泼溅（TripoSplat、HY World、Marble）保存为 .ply 或 .spz，不会放置：告知用户 Unity 需要高斯泼溅渲染器包。
• Meshy 7.1 默认以相同价格进行 30,000 三角面的重新网格化；发送 shouldRemesh: false 以获取完整网格（约一百万三角面）。

链式步骤

将一个结果通过其文件输入馈送到下一个模型：

• 图像转 3D：先生成一张图像，然后使用该图像的 asset id 调用 model3d 模型（例如 Meshy 7.1 Image to 3D）。
• 图像转材质或天空盒：PATINA Image to Maps、HY World Image to Skybox。
• 图像转视频：使用图像作为起始帧的 img2video 模型。
• 清理：背景移除、升频、矢量化、像素化。
• 3D 纹理：重纹理（Meshy 7 Retexture、Tripo 3.0 Texturing、Tencent Texture Edit、Trellis 2、YVO3D）、UV 展开（Tripo Smart UV、Meshy、Tencent）。
• 3D 形状：通过提示编辑（Claude Opus 5.5 3D、Astra 3D；仅提示，无参考图像）、重新拓扑（Tripo Retopology v3、Hunyuan Polygen）、按多边形数量重新网格化（Meshy Remesh）、从图像细化（UltraShape）。
• 绑定与动画化：绑定角色（Uthana、Meshy、Cartwheel、Tripo）、绑定生物（Tripo Rigging 2.5、rigType）、库动画（Meshy Animation：actionId，例如 30 Casual Walk、106 Confident Walk、4 Attack、22 FunnyDancing 01；motions_find 可按名称或类别搜索全部 656 个）、从提示生成动画（Cartwheel、Uthana）或从视频生成动画（Cartwheel、Uthana）。
• 部件与风格：拆分为部件（Tripo Segmentation v2、Hunyuan 3D Part、Hitem3D Split、Rodin Bang）、风格化（Tripo Stylization：LEGO、体素、Voronoi；Hitem3D Multicolor）。
• 尽管模式显示为可选但 Scenario 需要的输入：Cartwheel 动画需要 characterModel（一个 3D 模型）或 characterFile（一张图像，价格更高）；除非 retexture 为 false，否则 YVO3D 需要 referenceImage。工具会在定价前说明。
• 即使模型只读取 FBX（Tencent Texture Edit），也传递 GLB 资源 ID：插件会免费发送 Scenario 的 FBX 副本。
• 视频：升频、添加声音、重新风格化。音频：变声、语音隔离。

使用 capability（img23d、img2video、3d23d、video23d、video2audio、audio2audio）调用 models_find 可查找替代方案。

工作流

workflows_find（scope：team 或 featured）返回 ID、描述和输入。workflow_run 按名称接受 inputs，遵循与 generate 相同的费用规则；输出按其类型导入。

场景工具

当用户关闭 “代理可以编辑场景” 时，此功能关闭；只读工具（scene_info、object_get、assets_find、console_logs、capture_view）仍正常工作。

• object_create（空对象、基本几何体或预制体）、object_set（name、active、parent、transform、tag、layer、以米为单位的 height、使用 ground 将其放置在下方的地面上）、object_delete。
• component_add、component_set：序列化路径（m_Intensity）或公共属性（intensity）；向量表示为 [x,y,z]，颜色表示为 [r,g,b,a] 或 #RRGGBB，引用表示为资源路径或层级路径。使用 properties: true 调用 object_get 可列出所有可设置的内容。
• material_assign、skybox_set、select、scene_save（未命名的场景需要路径）。
• 使用 label: "Scenario" 调用 assets_find 可列出项目中所有生成的资源。

每次编辑都是一个可撤销的步骤，因此用户可以恢复你做的任何更改。

可漫游世界

从一个提示到一个玩家可以行走的世界：

1. terrain_create：带有碰撞器的地面。使用你先生成的高度图图像（自上而下的灰度高度图，白色代表高）塑造其形状，对建筑区域进行 flat_areas 平整，并使用生成的材质绘制 layers（第一个是基础材质；其他通过 min_height 或 min_slope 设置）。edge_falloff 可以创建岛屿或高原。
2. 生成场景组件，然后使用 height（米）和 ground: true 的 object_set 来调整每个组件的大小并将其放置在地形上。典型高度：人 1.8，门 2.2，房屋 6 到 9，松树 8 到 14，岩石 0.5 到 2。
3. scatter 在地面上（on：地形）重复放置一个模型，带有 height 范围、路径和建筑周围的 keep_clear 区域，以及碰撞器。
4. 角色：生成它，绑定它，动画化待机、行走、奔跑和跳跃（使用 motions_find 查找库 ID），然后使用这些结果调用 make_playable。它会构建控制器、调整角色大小、将速度与剪辑匹配并设置跟随摄像机。
5. 使用 action: "walk" 和路径点（run、jump、wait）调用 play 进行游戏测试：它会报告到达的点、掉落（超过 4 米的落差计为掉落）和跳跃。如果行走时间长于调用时间，则会在 Unity 中继续运行：答案显示 running，并使用 action: "status" 和 wait_seconds 的 play 在结束时返回结果。在再次编辑之前，使用 action: "stop" 的 play；在播放模式下进行的编辑会丢失。record: true（或 action: "record"）会以固定帧率写入主摄像机的 PNG 帧。
6. scene_save。

检查你的工作

• capture_view 渲染场景视图或摄像机并返回图像。在放置结果或编辑场景后查看它。使用 upload: true 时，它还会返回一个 Scenario 资源 ID，因此捕获的图像可以作为下一次生成的参考。
• 在导入或组件更改后，使用 level: "error" 的 console_logs。

良好习惯

• 每次意图一个请求。在批处理或任何超出用户所述预算的操作之前，请先询问。
• 重用先前结果中的 asset_ids，而不是重新上传相同的文件。
• jobs 列出此 Unity 项目中最近的请求；在出错后重新发送任何内容之前，请先检查它。
• 报告你所创建的内容，包括其 Unity 路径和放置的对象。