Community影像github.com

blender-gamepipe

將 Blender 資產(樹木、草地、岩石、道具、建築)與程序化 PBR 紋理轉換為經驗證、可直接用於遊戲的 GLB /紋理組,包含 LOD 與 KTX2/meshopt 壓縮,並證明它們能在 three.js 中渲染。包含可重用的 three.js 運行時(地形生態系、隨風搖曳的草、實例化樹木 LOD、天空)與世界交付工具。

blender-gamepipe 是什麼?

blender-gamepipe 是一個用於遊戲與 Web 引擎的 Blender 資產管線。它強制執行從規格到最終輸出的確定性流程:lint、建構、驗證、匯出,並在 three.js 中進行引擎檢查。支援的資產類型包括程序化紋理、樹木、岩石、草地、建築物與角色。其關鍵功能是閘門(gate):除非資產通過所有閘門檢查(預算、UV、紋理、網格有效性、匯出完整性)且能在 three.js 檢視器中正確渲染,否則不會被視為完成。該工具組包括用於生成紋理集的 CLI 命令(bin/gp textures)、建構資產(bin/gp build)、透過程式碼產生的生成器(generators/*.py)、以及一個可複製到遊戲專案中的 three.js 運行時資料夾(runtime/)。透過 tools/export_world.py 進行世界交付可確保僅包含通過閘門的資產。

相容平台~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/RNT56/agent-skill-blender-export-three.js/tree/HEAD/skills/blender-gamepipe

Installed? Explore more 影像 skills: steipete/songsee, affaan-m/frontend-design, mattpocock/improve-codebase-architecture · View all 6 →

在你喜歡的 AI 中提問

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

說明文件

blender-gamepipe 是做什麼的?

一個確定性的繞著 Blender 的循環:規格 -> lint -> 建構 -> 驗證 -> 匯出 -> 檢查 GLB -> 引擎檢查。 代理人提供判斷(配方、修復、藝術方向);腳本提供閘門。除非閘門通過,否則任何東西都不會出貨。

唯一規則

永遠不要僅憑自己對渲染或日誌的解讀就聲明資產已完成。 完成意味著以下全部:

  1. bin/gp build <spec> 退出碼為 0 且 out/<asset>/manifest.json 顯示 "passed": true。
  2. 你打開了一張預覽/QA 圖片並親自查看(無聲失敗在日誌中看起來正常:空白烘焙、翻轉的紋理、突出的幾何體)。
  3. 引擎檢查成功(檔案在 three.js 中載入、紋理已壓縮、無控制台錯誤、在實際光照下看起來正確)。 如果任何步驟失敗或跳過,請如實說明。

快速入門

bin/gp test                                  # 測試一切(需要 Blender;約 5 分鐘)
bin/gp textures specs/biomes.json            # 11 套可平鋪 PBR 紋理(7 個生態系 + 4 種建築材料)+ 接縫檢查 -> out/textures/
bin/gp generate generators/samurai_keep.py   # 程序化生成城堡 -> fixtures/samurai_keep.blend(需要先有紋理)
bin/gp build specs/samurai_keep_01.json      # 配方 -> 閘門 -> GLB -> 檢查 -> manifest -> 預覽   (-> out/<asset>/)
bin/gp build specs/grass_blades.json         # 可隨風搖擺的草葉包(無需原始場景)
bin/gp build specs/tree_maple_01.json        # 樹木 LOD0-3 包含替換物(impostor)
bin/gp lint my_script.py                     # 在執行 bpy 程式碼前捕捉 Blender 陷阱
bin/gp glb out/<asset>/*.glb                 # 無需 Blender 檢查匯出檔案
bin/gp view                                  # 單一資產檢視器:http://localhost:8765/viewer/?asset=<name>
python3 tools/export_world.py --dest ../my-game --models ... --biomes ...   # 組合遊戲資料夾(拒絕失敗的資產)

Blender 在 macOS 上會自動偵測;否則請設定 export BLENDER=/path/to/Blender。

管線圖

需求工具輸出
可平鋪地面/生態系/建築 PBR(13 套:7 個生態系、石頭、灰泥、2 種木材、屋瓦、茅草)gp textures (gp_texgen.py)<name>_albedo.jpg、_normal.png、_orm.png + contact sheet + 接縫報告
主樹 -> LOD + 替換物配方 tree<asset>_LOD0..3.glb(自有紋理)
岩石/道具(程序化材質)配方 prop共用一個烘焙 PBR 紋理組的 LOD
草地配方 grassgrass_blades.glb(3 種變體 x 2 個 LOD,30 個三角形;uv.y = 沿著草葉的高度)
建築物(多材質,作者定義的 LOD)generators/{samurai_keep,minka,teahouse}.py(共用 gen_common.py)然後配方 buildingONE GLB 包含 LOD0-2,紋理共用
蒙皮、動畫角色generators/samurai_unit.py(kit 在 generators/samurai/)然後配方 character一個 GLB 中包含蒙皮 LOD0-2 + 武器節點,每個片段一個動畫,clips.json;先閱讀 docs/character.md
引擎runtime/*.js(three.js ES 模組)地形生態系、隨風草、實例化森林、天空、玩家
交付tools/export_world.py自包含的遊戲資料夾

工作流程

  1. 規格(specs/*.json):名稱、類型、recipe、source_blend、預算、recipe_cfg、glb_expect、export。複製一個鄰近的作為模板。
  2. Lint 你寫的任何 bpy 程式碼(bin/gp lint)。修復每個 error。
  3. 無頭建構。切勿在 live Blender 會話中烘焙/渲染(參見 Entry points)。
  4. 閱讀報告,而不僅僅是退出碼:out/<asset>/*.report.json 包含穩定的發現 code。
  5. 修復並重建。 除非使用者同意,否則不要為了通過而提高預算。
  6. 查看:打開 *.preview.png(以及生成器的 --render QA 視圖)。判斷輪廓、材質、比例。
  7. 引擎檢查(如下),然後報告每個 LOD 的三角形數、大小、驗證了什麼以及未驗證什麼。

Entry points

  • 無頭模式(預設): bin/gp build ... = blender -b <source.blend> -P gamepipe/gp_cli.py -- <spec>。
  • 透過 MCP 的 Live Blender: gp_live.run_headless_from_live(spec) 儲存目前打開場景的副本並以無頭模式執行(在 live 會話中烘焙/渲染會超時並凍結 UI)。execute_blender_code 片段必須賦值 result = {...}(一個字典)。

引擎檢查(three.js)- 必需

單一資產:bin/gp view,打開 http://localhost:8765/viewer/?asset=<name>,等待 >= 5 秒(KTX2 在 worker 上進行轉碼),然後 JSON.stringify({state: window.__state, report: window.report})。預期 tris 與 manifest 相符,mapIsCompressed:true,樹皮 normalMap/aoMap/roughnessFromMap:true,葉子 alphaTest:0.5,無控制台錯誤。 整個世界:使用 runtime/(參見 runtime/index.js);透過組合這些模組(地形 + 生態系、草地、森林、水體、天空、後處理)來建立世界;tools/export_world.py 組合遊戲資料夾。 使用 EXT_disjoint_timer_query_webgl2 測量真實 GPU 時間(gl.finish() 在 Metal 上無效);rAF 在背景/未聚焦的 頁籤中會被節流,因此來自嵌入式瀏覽器的 fps 是下限,而非精確測量。

配方(gamepipe/recipes/*.py)- 合約在 recipes/__init__.py 中

META = {name, version, needs} + build(spec, out_dir) -> [derived specs](每個:name,type,include_objects,budgets.max_tris,export)。配方建立新的物件。新增一個:模組 + 規格 + 測試(複製 tests/test_recipes.py)。

配方輸入說明
tree樹皮網格 + 葉子網格(每個葉片一個島,第一個頂點 = 葉片基部)烘焙 albedo/normal/ORM,葉片卡片在生成的圖集上,LOD1-2 減面,LOD3 替換物(impostor);leaf_palette:綠色/秋天/櫻花
prop一個帶程序化材質的網格減面後的 LOD,共用烘焙紋理組;平坦的法線貼圖會被省略
grass無(生成)草葉 UV:u 橫向,v = 高度 0..1;Blender Z-up -> glTF Y-up,朝 -Z 彎曲
building名為 <x>_LOD<n>_<Material> 的作者定義 LOD 物件的集合直接傳遞到閘門;lod_budgets 強制每個 LOD 的三角形數;一個 GLB
character一個骨架 + 蒙皮 LOD 網格 + Actions(由 generators/samurai_unit.py 建構)閘門新增 SKIN_* / RIG_BONE_BUDGET / ANIM_* 碼;匯出皮膚 + 每個 Action 一個動畫;將 clips.json 寫入 manifest。參見 docs/character.md

生成器(generators/*.py)- 用於透過程式碼建構的資產

samurai_keep.py:在石垣(ishigaki)基底上的天守(tenshu),約 23 公尺高。方法 = 用於輪廓的幾何體 + 固定世界尺度紋素密度的可平鋪 PBR (UV 是世界空間平面投影:石頭/灰泥 3 公尺、木材 1.5 公尺、瓦片 1.6 公尺重複一次)。三角形數:LOD0 57k、LOD1 16k、LOD2 4.5k。 使用 --render out/_keep.png --no-save 渲染 QA 視圖並查看它們。得來不易的規則:開放的屋頂表面必須朝上;牆壁必須跟隨屋頂表面(而非一個盒子),否則會突出;傾斜的隅石需配合牆壁的傾斜度;僅使用世界空間 UV。

目前已建構的建築物(全部為程序化,全部通過同一個閘門)

資產內容三角形數 LOD0/1/2說明
samurai_keep_01石垣基底上的城堡天守,約 23 公尺57k / 16k / 4.5k5 種材質,包含金色裝飾物
minka_01茅草屋頂農舍,四坡屋頂,障子陽台12k / 3.4k / 0.9k茅草 = 凹凸不平的高度場;牆壁在其下下沉 0.22 公尺
teahouse_01位於 28 根支柱上的水邊茶屋 + 碼頭 + 燈籠20k / 6.5k / 0.8k原點 = 水面,+Y = 朝向岸邊;需要 origin_tolerance 3.6(支柱)
每個生成器:bin/gp generate generators/<x>.py [--render out/_x.png --no-save] -> 查看 QA 渲染 -> 儲存 fixture -> bin/gp build specs/<x>_01.json。

運行時(runtime/*.js)- 透過 export_world 複製到遊戲中

assets.js(GLB 載入器,支援 meshopt+KTX2,生態系紋理陣列) - terrain.js(7 生態系疊加、抗重複、切線框架、遠處秋冠層 + 雪線) - grass.js + grass_clump.js(分塊層級、GPU 風、踩踏效果;clumps: true = 帶種子穗的高大稻田叢) - water.js + water_waves.js(共用 GPU / CPU 波浪模型、烘焙岸線 + 泡沫、吸收、焦散、平面反射、漣漪;heightAt/normalAt/depthAt 用於浮動物件) - post.js(MSAA HDR -> 泛光 -> ACES -> 色彩分級) - foliage.js/trees.js(實例化 LOD 分組、搖擺、半透明) - sky.js(3 階梯度、太陽光暈、發光的積雲 + 卷雲) - look.js(共用 looks/*.json,包含補光) - player.js - scatter.js - quality.js(自適應解析度) - noise.js - noisetex.js(一個可平鋪的 4 通道噪聲紋理) - 晝 / 夜、季節、天氣:env_clock.js(太陽 + 月球天文學),env_atmosphere.js(根據太陽高度角從 looks/atmosphere.json 取關鍵幀),env_seasons.js(草地 / 葉子 / 地面 / 積雪狀態 + 應用器),env_weather.js,env_sky.js,env_lighting.js,env_grade.js - 生命:aquatic.js(蘆葦、睡蓮葉、漂浮物、岸邊岩石),fauna.js(錦鯉、鴨子、蜻蜓)。 looks/golden_hour.json 外觀是一個秋季低太陽外觀(太陽從西方 16 度,溫暖的天空,冷色調補光,泛光 + 色彩分級)。色彩創作:look JSON 中的顏色是場景線性(它們不是 sRGB);草地色調以顯示顏色創作並在著色器中平方。

驗證器碼(修復,不要靜默忽略)

BUDGET_TRIS/BUDGET_LOD_TRIS/BUDGET_FILE_SIZE/BUDGET_MATERIALS(超出預算) | UV_MISSING | MAT_PROCEDURAL(烘焙它) | TEX_BLANK(烘焙無聲失敗) | TEX_TOO_LARGE | ALPHA_BLENDED/GLB_ALPHA_BLEND(透過 Math Round 將 alpha 路由 -> MASK) | XFORM_NEG_SCALE/NONUNIFORM | ORIGIN_NOT_AT_BASE | MESH_ZERO_AREA/NON_MANIFOLD | MOD_GEONODES | GLB_*(匯出檔案中的問題)。紋理生成器:NOT_TILEABLE, TEX_FLAT, ALBEDO_RANGE, NORMAL_TOO_STRONG。

陷阱

在撰寫 bpy 或著色器程式碼前請閱讀 GOTCHAS.md。重點:節點上使用 == 而非 is;烘焙需要一個啟用且選中的圖片節點;Blender 影像是 底部向上(在 IO 時翻轉,否則每個法線貼圖都會反轉);ORM/法線貼圖必須是 PNG(JPEG 色度子取樣會損壞資料通道); glTF alpha 模式來自一個 Round 節點;KTX2 會匯出兩次,除非被移除;永遠不要相信背景頁籤中的 fps。

未涵蓋的內容(請誠實)

動作捕捉/手工打磨動畫(character 配方的片段由程式碼創作,參見 docs/character.md)、河流/水下、地形串流/碰撞(超出圓形碰撞器)、音訊、剛體物理(浮動物件的水面物理已涵蓋)、降水(天氣狀態確實攜帶 precip 以備使用)。較低的樹木 LOD 重複使用 LOD0 的法線貼圖。 粗糙度由 albedo 亮度推導而來。程序化建模不具備手工雕刻/掃描的真實感。KTX2 在一個瀏覽器/GPU(Apple M4 / Metal)上驗證。

相關技能