blender-gamepipe 是做什麼的?
一個確定性的繞著 Blender 的循環:規格 -> lint -> 建構 -> 驗證 -> 匯出 -> 檢查 GLB -> 引擎檢查。 代理人提供判斷(配方、修復、藝術方向);腳本提供閘門。除非閘門通過,否則任何東西都不會出貨。
唯一規則
永遠不要僅憑自己對渲染或日誌的解讀就聲明資產已完成。 完成意味著以下全部:
bin/gp build <spec>退出碼為 0 且out/<asset>/manifest.json顯示"passed": true。- 你打開了一張預覽/QA 圖片並親自查看(無聲失敗在日誌中看起來正常:空白烘焙、翻轉的紋理、突出的幾何體)。
- 引擎檢查成功(檔案在 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 |
| 草地 | 配方 grass | grass_blades.glb(3 種變體 x 2 個 LOD,30 個三角形;uv.y = 沿著草葉的高度) |
| 建築物(多材質,作者定義的 LOD) | generators/{samurai_keep,minka,teahouse}.py(共用 gen_common.py)然後配方 building | ONE 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 | 自包含的遊戲資料夾 |
工作流程
- 規格(
specs/*.json):名稱、類型、recipe、source_blend、預算、recipe_cfg、glb_expect、export。複製一個鄰近的作為模板。 - Lint 你寫的任何 bpy 程式碼(
bin/gp lint)。修復每個error。 - 無頭建構。切勿在 live Blender 會話中烘焙/渲染(參見 Entry points)。
- 閱讀報告,而不僅僅是退出碼:
out/<asset>/*.report.json包含穩定的發現code。 - 修復並重建。 除非使用者同意,否則不要為了通過而提高預算。
- 查看:打開
*.preview.png(以及生成器的--renderQA 視圖)。判斷輪廓、材質、比例。 - 引擎檢查(如下),然後報告每個 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.5k | 5 種材質,包含金色裝飾物 |
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)上驗證。