3dMVP/blobit-cli-skill-pack

Blobit CLI

當遊戲應使用託管的 Blobit 場景時，請使用 blobit 作為資產後端，以及場景/發佈後端。

• 使用 blobit 來：
  • 建立專案
  • 上傳圖片
  • 生成或重複使用 3D 資產
  • 檢查放置中繼資料
  • 組合與驗證場景
  • 發佈清單
• 對於瀏覽器遊戲，使用一般程式碼工具來規劃、建立架構、實作、執行，並以視覺方式驗證可遊玩的遊戲。
• 在遊戲專案中，Blobit 負責執行階段的資產生成。遊戲邏輯、UI、輸入、攝影機、物理和遊戲狀態則保留在遊戲的程式碼庫中。
• 對於瀏覽器遊戲，已發佈的清單模式是預設的資產傳遞路徑：使用 blobit publish create 回傳的 manifest_url，並透過 @blobit/sdk 載入它。

使用時機

當使用者要求以下事項時，請使用此技能：

• 建立或管理 Blobit 專案與資產
• 從圖片生成 3D 模型
• 使用語意放置指令來佈局場景
• 發佈 Blobit 場景以供瀏覽器使用
• 將已發佈的 Blobit 內容透過 SDK 整合至網頁遊戲
• 建立或更新一個瀏覽器遊戲，且 Blobit 應生成或提供執行階段的資產

規則

• 當需要解析指令輸出時，優先使用 blobit --json。
• 優先使用語意場景指令，而非手動編輯原始變換矩陣。
• 對於新資產，除非使用者明確提供現有模型供重複使用，否則優先使用 Blobit 圖片生成、圖片上傳，或本機圖片上傳並加上模型/世界生成。
• 對於模型和世界生成指令，除非任務需要透過 --provider 進行一次性覆寫，否則優先使用儲存的預設提供者。
• 優先使用 blobit config set-provider <provider>，而非告訴使用者手動編輯 Blobit 設定檔。
• 請勿在新指令中使用舊的提供者別名 --endpoint-type；請使用 --provider。
• 當資產的原點、佔地面積或地面接觸不明確時，請先檢查放置中繼資料，再進行排列或取景。
• 在進行重大佈局更改前後，執行 scene analyze。
• 在發佈前執行 scene validate。
• 當任務變更了可見的場景幾何，且本機預覽或檢視器可用時，請擷取螢幕截圖並檢查是否有明顯的視覺問題。
• 對於瀏覽器遊戲，避免下載資產，應在執行階段載入已發佈的 Blobit 清單。
• 僅在使用者明確要求捆綁、離線、靜態或本機檔案資產時，才使用 blobit assets download。
• 請勿詢問或報告金錢資產預算。目前的 Blobit CLI 不會回傳資產生成的支出；請改為詢問資產範圍、資產數量與優先順序。
• 對於高品質遊戲，預設使用審查閘門模式：簡短提問、生成視覺目標、撰寫 PLAN.md、生成或指派 Blobit 資產、建立可玩的第一版、擷取證明，然後根據回饋進行迭代。
• 在規劃遊戲實作之前，請詢問或記錄碰撞/物理的架構選擇：自訂街機碰撞、Babylon/Havok 物理，或混合式。
• 當任務要求使用 Blobit 製作的資產時，請勿使用非 Blobit 的資產生成供應商或腳本。
• 將 Blobit 視為僅供資產和場景使用的後端；請使用儲存庫的一般程式碼工具來建構遊戲邏輯和渲染。
• 對於已發佈的執行階段內容，請使用 blobit publish create 回傳的 manifest_url，並透過 @blobit/sdk 載入它。

產出項目

• 一個 Blobit project_id
• 已上傳的來源圖片資產 ID，或重複使用的來源資產 ID
• 已生成的模型資產 ID，以及在適用的情況下，已完成的任務 ID
• 一個包含已放置模型、攝影機狀態，以及已套用的語意佈局操作的持久化場景
• scene analyze 和 scene validate 的結果
• 一個已發佈的 manifest_url，以及相關的發佈中繼資料，例如 publish_id 和 viewer_url
• 在網頁應用程式中，@blobit/sdk 載入已發佈清單的執行階段整合點
• 對於遊戲任務，若專案工作流程支援，則包含 PLAN.md、STRUCTURE.md、ASSETS.md，以及來自執行中瀏覽器遊戲的視覺證明

管線

1. 檢查或建立 Blobit 專案。
2. 上傳來源圖片並生成模型，或重複使用明確的現有資產。
3. 在進行場景佈局決策前，檢查已生成或重複使用的資產，特別是放置中繼資料。
4. 將模型新增至場景。
5. 套用語意放置操作，例如 drop-to-floor、place-near、arrange、align、avoid-overlap、distribute、snap 和 frame-camera。
6. 執行 scene analyze，檢閱重疊、邊界和警告，並根據需要調整場景。
7. 在發佈前執行 scene validate，並將驗證警告視為阻斷問題，除非使用者明確接受它們。
8. 發佈並擷取 manifest_url 以及任何相關的檢視器或發佈中繼資料。
9. 在遊戲客戶端中，透過 @blobit/sdk 載入該清單。
10. 使用一般的專案技術棧來建置或更新實際的遊戲邏輯與渲染。

對於可玩的瀏覽器遊戲，請在規劃或編碼之前閱讀 references/game-workflow.md。它定義了一個專為純 Blobit 資產調整的規劃與實作循環。 若想了解該遊戲工作流程背後的 Godogen 衍生理論，請僅在更新技能或調解工作流程決策時閱讀 references/godogen-patterns.md。

執行階段驗證

• 在進行重大佈局或攝影機變更後，若本機遊戲、預覽或 Blobit 檢視器可用，請執行它們。
• 當渲染的幾何形狀至關重要時，請擷取螢幕截圖，並檢查是否有浮動模型、剪裁、縮放錯誤、方向錯誤、攝影機取景不當，以及語意檢查可能遺漏的重疊。
• 將螢幕截圖審查視為 scene analyze 和 scene validate 的輔助，而非替代。
• 若無執行階段預覽可用，則依賴 CLI 驗證，並明確註明已跳過視覺驗證。

場景注意事項

• 當物件應明顯放置於舞台或地面平面上時，請使用 drop-to-floor。
• 在新增、移除或重新排列模型後，或當目前的攝影機可能無法正確框住主體時，請使用 frame-camera。
• 當物件的原點、支撐面或佔地面積不明確時，請在執行 arrange 或 place-near 之前先檢查資產放置中繼資料。
• 優先使用語意場景操作，而非直接編輯變換矩陣；僅在需要精確的最終調整或使用者明確要求時，才使用直接變換。
• 在進行大量排列或重疊解決處理後，執行 scene analyze 以確認場景符合預期。

預期輸出/交接

• 關鍵 ID 和 URL：project_id、相關的資產 ID、任務 ID、publish_id、manifest_url 和 viewer_url（若適用）
• 已套用的場景操作及最終驗證狀態的簡短摘要
• 應用程式透過 @blobit/sdk 載入已發佈清單的準確執行階段整合點
• 關於是否執行了執行階段螢幕截圖驗證及其發現的註記
• 任何仍需跟進的未解決佈局、驗證或執行階段的限制

核心指令

• blobit --json projects list
• blobit --json projects create --name ...
• blobit --json assets generate-image ...
• blobit --json assets upload-image ...
• blobit --json jobs model-from-image ... --wait
• blobit --json jobs model-from-prompt ... --wait
• blobit --json jobs world-from-prompt ... --wait
• blobit --json assets inspect <asset_id>
• blobit --json assets download <asset_id> --out ...
• blobit --json scene add-model <project_id> <asset_id>
• blobit --json scene add-world <project_id> <asset_id>
• blobit --json scene analyze <project_id>
• blobit --json scene place-near ...
• blobit --json scene arrange ...
• blobit --json scene validate <project_id>
• blobit --json publish create <project_id> --allowed-origin ...

請閱讀 references/workflows.md 以取得端到端的指令食譜。 請閱讀 references/game-workflow.md 以取得瀏覽器遊戲規劃、實作、資產清單和視覺證明的指引。