blender-gamepipe 是做什么的?
一个围绕 Blender 的确定性循环:规范 -> 检查 -> 构建 -> 验证 -> 导出 -> 审查GLB -> 引擎验证。 代理提供判断(配方、修复、美术方向);脚本提供门控。没有门控通过,任何资产都不能发布。
唯一规则
永远不要仅凭自己阅读渲染图或日志就声称资产已完成。 完成意味着满足以下所有条件:
bin/gp build <spec>的退出码为 0,且out/<asset>/manifest.json中显示"passed": true。- 你打开预览/质量检查图像并亲自查看(日志中可能看起来正常的静默失败:空白烘焙、翻转纹理、突出的几何体)。
- 引擎验证成功(文件在 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 -> 审查 -> 清单 -> 预览 (-> out/<asset>/)
bin/gp build specs/grass_blades.json # 支持风动的草叶片包(无需源场景)
bin/gp build specs/tree_maple_01.json # 树木LOD0-3(含替身)
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 ... # 组装游戏文件夹(拒绝失败的资产)
在 macOS 上 Blender 会被自动检测;否则请设置 export BLENDER=/path/to/Blender。
管线地图
| 需求 | 工具 | 输出 |
|---|---|---|
| 可平铺地面/生物群落/建筑PBR(13套:7种生物群落,石材,灰泥,2种木材,屋顶瓦片,茅草) | gp textures (gp_texgen.py) | <name>_albedo.jpg,_normal.png,_orm.png + 接触片 + 接缝报告 |
| 主树 -> LOD + 替身 | 配方 tree | <asset>_LOD0..3.glb(自带纹理) |
| 带程序化材质的石头/道具 | 配方 prop | LOD共享一套烘焙PBR纹理集 |
| 草地 | 配方 grass | grass_blades.glb(3种变体 x 2个LOD,30个三角形;uv.y = 沿叶片的高度) |
| 建筑(多材质,自定LOD) | generators/{samurai_keep,minka,teahouse}.py(共享 gen_common.py)然后配方 building | 一个GLB包含LOD0-2,纹理共享 |
| 蒙皮动画角色 | generators/samurai_unit.py(套件在 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。复制一个相邻的规格文件。 - 检查你编写的任何bpy代码(
bin/gp lint)。修复所有error。 - 无头构建。切勿在实时Blender会话中烘焙/渲染(参见入口点)。
- 阅读报告,而不仅仅是退出码:
out/<asset>/*.report.json包含稳定的发现code。 - 修复并重建。除非用户同意,否则不要为了提高通过率而增加预算。
- 查看:打开
*.preview.png(对于生成器使用--render质量检查视图)。评估轮廓、材质、比例。 - 引擎验证(见下文),然后报告每个LOD的三角形数、文件大小、已验证和未验证的内容。
入口点
- 无头模式(默认):
bin/gp build ...=blender -b <source.blend> -P gamepipe/gp_cli.py -- <spec>。 - 通过MCP在实时Blender中运行:
gp_live.run_headless_from_live(spec)保存当前场景的一份副本并执行无头构建(在实时会话中烘焙/渲染会超时并冻结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 与清单一致,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) -> [派生规格](每个:name,type,include_objects,budgets.max_tris,export)。配方创建新的对象。添加一个:模块 + 规格 + 测试(复制 tests/test_recipes.py)。
| 配方 | 输入 | 备注 |
|---|---|---|
tree | 树皮网格 + 树叶网格(每个叶片一个孤岛,第一个顶点 = 叶片基部) | 烘焙albedo/normal/ORM,基于生成的图集生成叶片卡片,LOD1-2减面,LOD3替身;leaf_palette:绿色/秋天/樱花 |
prop | 一个带程序化材质的网格 | 减面LOD,共享烘焙纹理集;平坦的法线贴图被省略 |
grass | 无(程序生成) | 叶片UV:u方向横跨,v = 高度 0..1;Blender Z轴向上 -> glTF Y轴向上,向-Z方向弯曲 |
building | 名为 <x>_LOD<n>_<Material> 的自定LOD物体集合 | 直接传递到门控;lod_budgets 强制每个LOD的三角形数限制;一个GLB |
character | 一个骨架 + 蒙皮LOD网格 + 动作(由 generators/samurai_unit.py 构建) | 门控添加 SKIN_* / RIG_BONE_BUDGET / ANIM_* 代码;导出蒙皮 + 每个动作一个动画;将 clips.json 写入清单。参见 docs/character.md |
生成器(generators/*.py)- 适用于通过代码构建的资产
samurai_keep.py:石垣基座上的天守阁,约23米高。方法 = 用于轮廓的几何体 + 固定世界空间纹素密度的可平铺PBR(UV是世界空间平面投影:石材/灰泥 3米,木材 1.5米,瓦片 1.6米每次重复)。三角形数:LOD0 57k,LOD1 16k,LOD2 4.5k。
使用 --render out/_keep.png --no-save 渲染质量检查视图并查看它们。来之不易的规则:开放的屋顶表面必须朝上;墙壁必须跟随屋顶表面(而不是一个盒子),否则会穿透;按墙壁的倾斜度倾斜隅石;仅使用世界空间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] -> 查看质量检查渲染图 -> 保存夹具 -> 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度,温暖天空,冷调补光,泛光 + 调色)。色彩创作:视觉风格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(通过数学取整 -> 遮罩来路由alpha) | 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模式来自一个取整节点;除非剥离,否则KTX2会被导出两次;永远不要相信后台标签页的fps。
未涵盖的内容(请如实说明)
动作捕捉/手工精调的动画(character 配方的动画片段由代码生成,参见 docs/character.md),河流/水下,地形流式加载/碰撞(超出圆形碰撞体范围),音频,刚体物理(漂浮物的水面物理已涵盖),降水(天气状态携带 precip 用于实现)。较低的树LOD复用LOD0的法线贴图。
粗糙度源自albedo亮度。程序化建模并非手工雕刻/扫描的保真度。KTX2在一个浏览器/GPU上验证(Apple M4 / Metal)。