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 執行捆綁的客戶端。兩者都公開相同的兩個操作。
- 如果你還不知道目前的工作區路徑,請執行
pwd。 - 如果計劃生成 3 個或更多素材,或者這是執行緒中首次生成素材,請檢查就緒狀態(
<skill-dir>是此技能目錄):
node <skill-dir>/scripts/game-assets-mcp.mjs readiness --cwd "$(pwd)"
- 生成 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-caseid、role、name、prompt,以及可選的assetKind。force:僅在使用者明確要求重新生成素材時使用。- 該命令在輪詢遠端作業時會阻塞(通常每批次 1-3 分鐘),並輸出 JSON 結果;退出碼 1 表示批次失敗。
- 命令返回後,從
cwd讀取asset_manifest.json。將該檔案視為事實來源。 - 使用 Three.js
GLTFLoader將manifest.assets接入遊戲程式碼。 - 為每個生成的素材保留一個本機基本幾何後備方案。遊戲必須在 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 中記錄跳過的階段。
- 部分成功:使用成功生成的素材,並為其餘部分使用後備幾何形狀。