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/P Panoramic 材質	同上
model3d	GLB 匯入為預置物件，在場景視圖樞紐處建立實例	放置在目標旁邊的實例
motion	帶有動畫控制器的 GLB（每個片段一個狀態），在樞紐處建立實例；在播放模式下會播放	放置在目標旁邊的實例
audio	在新的 AudioSource 上建立 AudioClip	設定在目標的 AudioSource 上（若無則新增）
video	在新的螢幕四邊形上建立 VideoClip	設定在目標的 VideoPlayer 上（若無則新增）

結果包含 files（Unity 資產路徑）、placed（階層路徑）、asset_ids（Scenario 識別碼，可重複用作輸入）、job_id、quoted_cu 和 charged_cu。place: false 會匯入但不影響場景。任何呼叫的阻塞時間不超過 45 秒：3D、影片和較長音訊通常會以 next（仍在執行）回應。作業會持續進行、自行匯入與放置；請使用 local_id 和 wait_seconds 呼叫 jobs 直到完成，切勿再次生成相同內容。對於批次處理，請使用 wait: false 發送每個請求，然後使用 jobs 追蹤它們。

檔案輸入（參考圖片、起始幀、3D 模型、音訊）接受 Scenario 資產識別碼或 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 預設會以相同價格進行三萬三角形的重新網格化；若需要完整網格（約一百萬三角形），請發送 shouldRemesh: false。

鏈式步驟

將一個結果輸入下一個模型的檔案輸入：

• 圖片轉 3D：先 generate 一張圖片，然後使用該圖片的資產識別碼呼叫 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、voxel、Voronoi；Hitem3D Multicolor）。
• 即使綱要標記為可選，Scenario 仍需要的輸入：Cartwheel 動作需要 characterModel（3D 模型）或 characterFile（圖片，價格貴很多）；YVO3D 需要 referenceImage，除非 retexture 為 false。工具在定價前會說明。
• 即使模型僅讀取 FBX（Tencent Texture Edit），也請傳入 GLB 資產識別碼：外掛程式會免費發送 Scenario 對應的 FBX 複本。
• 影片：放大、加入音效、重新風格化。音訊：變聲、聲音隔離。

使用 能力（img23d、img2video、3d23d、video23d、video2audio、audio2audio）呼叫 models_find 可尋找替代方案。

工作流程

workflows_find（scope：team 或 featured）會回傳識別碼、描述與輸入。workflow_run 接受以名稱指定 inputs，其費用規則與 generate 相同；輸出會按其類型匯入。

場景工具

當使用者關閉代理程式可編輯場景時，此功能關閉；但讀取工具（scene_info、object_get、assets_find、console_logs、capture_view）仍可繼續運作。

• object_create（空的、基本幾何體或預置物件）、object_set（名稱、啟用狀態、父物件、變換、標籤、圖層、以公尺為單位的 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 尋找資料庫識別碼），然後使用這些結果呼叫 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 資產識別碼，因此捕捉畫面可以作為下次生成的參考。
• 在匯入或元件變更後，使用 level: "error" 檢查 console_logs。

良好習慣

• 每次意圖只發送一個請求。在批次處理或執行任何超過使用者設定預算的操作之前，先詢問使用者。
• 重複使用先前結果中的 asset_ids，而不是再次上傳相同檔案。
• jobs 會列出此 Unity 專案最近的請求；在發生錯誤後重新發送任何內容之前，請先檢查它。
• 使用 Unity 路徑和放置的物件來報告您製作的內容。