Communitygithub.com

3D 遊戲素材技能

為 3D 遊戲生成具體、可辨識的 GLB 素材,而非僅使用基本幾何形狀。此技能負責端到端工作流程:選擇路由、生成少量重點素材、讀寫 asset_manifest.json,並將 GLB 整合到遊戲中並提供後備方案。

3D 遊戲素材技能 是什麼?

此技能主要為 3D 遊戲開發提供高品質、可辨識的 GLB 素材生成與整合能力。它會根據遊戲提示中的角色、敵人、收集品等實體,自動判斷是否需要生成素材,並預設只生成 1 到 3 個最關鍵的素材(如玩家角色或核心敵人)。技能支援三種生成路由:'tripo' 適合快速迭代通用道具;'gemini_reference' 適合需要精確控制視覺效果的角色或物品;'auto' 則讓伺服器自行選擇。此外,它會自動管理 asset_manifest.json 清單、避免重新生成既有素材,並強制使用基本幾何作為 GLB 載入失敗時的後備方案,確保遊戲始終可玩。該技能支援透過 MCP 工具或命令列執行,並提供運行時整合規範,包括 GLB 標準化縮放、碰撞檢測分離、動畫混合器設定等。當 API 不可用或餘額不足時,它會優雅降級,保留後備素材並記錄狀態。

相容平台~Claude Code✓Codex CLI~Cursor✓Gemini CLI
npx skills add 674345386/agent-skills

在你喜歡的 AI 中提問

開啟一個已預先載入此 Agent Skill 的新對話。

說明文件

3D 遊戲素材

當 3D 遊戲需要具體、可辨識的 GLB 素材,而非僅使用基本幾何形狀時,請使用此技能。此技能負責端到端工作流程:選擇路由、生成少量重點素材、讀寫 asset_manifest.json,並將 GLB 整合到遊戲中並提供後備方案。

必要的行為

  • 如果遊戲提示中包含明確或隱含的實體,例如玩家、角色、敵人、收集品、載具、武器、障礙物、頭目、吉祥物、關鍵道具或環境物件,當工具可用時,GLB 生成是必經階段。
  • 預設情況下,僅生成 1-3 個關鍵素材。優先生成玩家/主要角色,然後是對遊戲玩法至關重要的敵人、收集品、載具、危險物或關鍵道具。不要生成裝飾性的填充物。
  • 僅在素材待生成期間使用基本的 Three.js 幾何作為臨時佔位符,並在 GLB 載入失敗時作為運行時後備方案。
  • 除非使用者明確要求,否則不要重新生成現有素材。如果 asset_manifest.json 已包含可載入的素材,請重複使用它。
  • 避免使用受版權保護的角色、品牌名稱、標誌和名人肖像。請改寫為原創設計。

路由選擇

使用 tripo 作為快速路由:直接將文字提示轉換為 Tripo3D 文字轉模型。這最適合通用道具、敵人、收集品、載具、障礙物和快速迭代。

當視覺控制很重要時,使用 gemini_reference:Gemini 首先建立一個純白背景的參考圖像,然後 Tripo 圖像轉模型建立 GLB。當使用者提到 Gemini、Nano Banana、T-pose、白色背景、參考圖像、圖像轉模型、角色表、風格一致性,或需要控制關鍵角色的輪廓時,優先使用此路由。

僅當你對伺服器根據提示自行選擇感到滿意時,才使用 auto。如果有疑問,請自行選擇路由並明確傳遞它。

環境

生成客戶端與此技能捆綁在 scripts/game-assets-mcp.mjs 中(Node >= 20,零依賴)。它與預設的遠端素材 API 通訊,位於 http://54.81.110.182:3001。

  • GAME_ASSETS_API_URL — 用於覆蓋素材 API 基礎 URL 的選用環境變數
  • GAME_ASSETS_API_TOKEN — 每個使用者的存取權杖

如果缺少權杖且服務需要驗證,請要求使用者在生成前設定 GAME_ASSETS_API_TOKEN。僅在使用者需要覆蓋預設服務時,才要求設定 GAME_ASSETS_API_URL。永遠不要詢問 Tripo 或 Gemini API 金鑰;它們存在於伺服器端。

工具工作流程

如果工作階段中有名為 mcp__game_assets__* 的 MCP 工具可用,則優先使用它們。否則透過 Bash 執行捆綁的客戶端。兩者都公開相同的兩個操作。

  1. 如果你還不知道目前的工作區路徑,請執行 pwd。
  2. 如果計劃生成 3 個或更多素材,或者這是執行緒中首次生成素材,請檢查就緒狀態(<skill-dir> 是此技能目錄):
node <skill-dir>/scripts/game-assets-mcp.mjs readiness --cwd "$(pwd)"
  1. 生成 1-3 個素材(批次最大 4 個)。將參數作為一個 JSON 物件傳遞:
node <skill-dir>/scripts/game-assets-mcp.mjs generate --cwd "$(pwd)" --params '{
  "gamePrompt": "...",
  "route": "tripo",
  "assets": [{ "id": "...", "role": "player", "name": "...", "prompt": "..." }]
}'
  • route:tripo、gemini_reference 或 auto。
  • assets:1-3 個物件,包含穩定的 kebab-case id、role、name、prompt,以及可選的 assetKind。
  • force:僅在使用者明確要求重新生成素材時使用。
  • 該命令在輪詢遠端作業時會阻塞(通常每批次 1-3 分鐘),並輸出 JSON 結果;退出碼 1 表示批次失敗。
  1. 命令返回後,從 cwd 讀取 asset_manifest.json。將該檔案視為事實來源。
  2. 使用 Three.js GLTFLoader 將 manifest.assets 接入遊戲程式碼。
  3. 為每個生成的素材保留一個本機基本幾何後備方案。遊戲必須在 GLB 載入失敗時仍可遊玩。

範例 --params JSON:

{
  "cwd": "/absolute/path/to/project",
  "gamePrompt": "3D runner with an astronaut cat collecting crystals and dodging patrol robots",
  "route": "gemini_reference",
  "assets": [
    {
      "id": "astronaut-cat",
      "role": "player",
      "name": "Astronaut Cat",
      "assetKind": "character",
      "prompt": "original low-poly astronaut cat hero, round helmet, compact readable silhouette, blue and white suit, friendly arcade game character"
    },
    {
      "id": "energy-crystal",
      "role": "collectible",
      "name": "Energy Crystal",
      "assetKind": "prop",
      "prompt": "bright cyan faceted energy crystal pickup, clean silhouette, game collectible"
    }
  ]
}

運行時整合規則

  • 使用 THREE.Box3().setFromObject() 標準化每個載入的 GLB:縮放到目標大小、水平置中、將底部置於 y = 0,並套用穩定的朝向偏移。
  • 將視覺效果與遊戲碰撞框分開。碰撞應使用穩定的遊戲玩法尺寸,而非原始模型邊界或網格原點。
  • 如果 manifest.assets 包含 rigged、rigType 或 animations,請在聲稱存在原生動畫之前檢查已載入的 gltf.animations。
  • 當存在原生片段時,建立一個 THREE.AnimationMixer,透過不區分大小寫的子字串(如 idle、walk、run、jump)對應片段,並在每個影格呼叫 mixer.update(delta)。
  • 如果沒有原生片段,則使用整體擺動/傾斜/旋轉或明確標記的程序化片段作為後備動畫。
  • 新增一個簡短的 README.md 章節,名為 3D Asset Pipeline 或 3D 素材流水線,描述生成了哪些素材、使用了哪個路由,以及使用了什麼運行時動畫來源。

失敗處理

  • 素材 API 無法連線(就緒狀態報告 unreachable):說明遠端模型生成不可用,要求使用者檢查預設素材服務、網路存取以及 GAME_ASSETS_API_TOKEN(如果需要);僅在覆蓋預設服務時才要求設定 GAME_ASSETS_API_URL。保留基本幾何後備方案並繼續讓遊戲可玩。
  • 伺服器在 gemini_reference 路由上缺少 Gemini 金鑰:如果可以接受,切換到 tripo,或者告知使用者伺服器操作員必須設定 Gemini 金鑰。
  • Tripo 餘額為零:不要在迴圈中重試。保留後備方案並在 README 中記錄跳過的階段。
  • 部分成功:使用成功生成的素材,並為其餘部分使用後備幾何形狀。

相關技能