blender-environment-kits

环境套件

执行模型位于 blender-core。自定义 GN 工具位于 blender-geometry-nodes，材质位于 blender-texturing（饰条、顶点混合），氛围/天气位于 blender-time-of-day/blender-weather-fx。

每项各调用一次

scripts/terrain.py -- --size 400 --res 513 --height 60 --type ridged --erosion 30 --flatten 0 0 40 --material
scripts/terrain.py -- --heightmap //hm.png --size 1000 --res 1009 --height 120 --export-splat //T_Splat.png
scripts/scatter.py -- --target Terrain --collection Trees --density 0.02 --min-distance 5 --max-slope 25 --height-max 45
scripts/scatter.py -- --target Terrain --collection Rocks --density 0.05 --max-slope 70 --align 0.8 --name ENV_Rocks
scripts/kit_check.py -- --objects SM_Wall_4m SM_Floor_4m SM_Door_4m --grid 0.5 --fix

地形（terrain.py）

• 在 --size m 的范围内生成 --res² 个顶点的网格。Unity 使用 2^n + 1（513/1025/2049，.raw 16 位 LE），UE Landscape 推荐使用这些尺寸（505/1009/2017/4033，16 位 PNG）。超过 1025 时进行分块。
• --type fbm（起伏地形）、ridged（山脉）、hills（异质地形）。--scale = 特征尺寸，单位为 m。--erosion N = 热侵蚀步数（休止角 33°）：坡面逐渐平缓，碎屑填充山谷。--terrace m = 阶梯状平地。--flatten X Y R = 平整的游戏/建造区域，并通过 smoothstep 与周围地形平滑融合。
• 写入 ENV_Slope（度数/90）和 ENV_Height（0–1）点属性。--material 根据这些属性生成草地/岩石/雪地：超过 35° 的区域生成岩石；坡度低于约 40° 且高度超过 75% 的区域生成雪地，并用噪声打散边缘。
• 引擎：--export-heightmap（PNG = 16 位灰度，.raw = 16 位小端，行 0 = −Y 边缘；如果在 Unity 中镜像，需垂直翻转），另加 heightmap_z_scale_m 设置导入时的 Z 轴缩放。--export-splat = 16 位 RGBA 权重（R 草地、G 岩石、B 雪地，总和为 1），用于地形图层。两者均以 Raw 格式写入（无显示变换）：往返误差实测小于 0.001。

散布（scatter.py）

• 每个图层使用一个 GN 修改器：泊松圆盘（--density 每平方米的最大密度，--min-distance m），仅在插值后的表面法线位于 --max-slope 范围内且 Z 位于 --height-min/max 范围内（对象空间）时保留。--mask = 顶点组或浮点属性，作为密度系数（可绘制该属性，或使用 ENV_Height）。
• 集合子项以各自原点为基准进行实例化，具有随机偏航角、--scale 范围和 --align（0 = 直立的树，0.6–1 = 贴合坡面的岩石）。源集合从视图层中排除。
• 结果会根据真实表面检查每个实例（slope_max_deg、height_range），并按来源统计数量。实例会保留为实例。仅在导出器或布尔运算需要真实网格时使用 --realize。
• 密度：森林树木 0.01–0.05/m²（最小距离 4–8 m）、灌木 0.05–0.2、岩石 0.01–0.1、草丛 2–20/m²（仅在摄像机附近）。按从大到小的顺序分层：树木，然后是避开树干的灌木，最后是草。
• 引擎：glTF export_gpu_instances=True（EXT_mesh_gpu_instancing），或使用 --export-points file.json（世界变换、Z 朝上，单位 m，wxyz 四元数）供 UE foliage/PCG 或 Unity 实例化脚本使用。FBX 需要先实现几何体，或为每个实例创建一个对象。

模块化套件（kit_check.py）

• 先确定度量标准：选择网格（0.5 m 吸附、1/2/4 m 模块）并始终保持一致。室内墙高 3–4 m（玩家眼高约 1.8 m，门高 ≥ 1 × 2.2 m），地板 4 × 4 m，楼梯高 0.18 m、深 0.28 m。UE 使用 cm（导入时 ×100），Unity 使用 m。
• 轴心约定（默认 --pivot corner，还可选 bottom-center、center），以便按增量对齐部件。占地长度必须是网格的整数倍。薄于一个网格单元的尺寸（墙厚、饰条）可以不对齐网格。
• 仅允许部件外侧面（接缝）存在开放边；内部的孔洞属于错误。接缝顶点必须位于网格上，以便相邻部件视觉上无缝连接。纹素密度与套件中位数的偏差不得超过 25%（--texture px）。使用 SM_ 名称（--prefix）。
• --fix 会应用旋转/缩放，并将各对象原点移动到轴心，同时不移动几何体。链接副本共享网格数据，因此只需修复一次源对象。
• 使用饰条和贴花（blender-texturing）、顶点颜色混合以及旋转/镜像变体来打破重复感（镜像会翻转法线，因此请使用 blender-asset-qa 检查）。用覆盖接缝的饰条部件隐藏连接处。

注意事项

• 散布前先应用地形／套件的缩放。密度和坡度均以世界空间为准。
• 散布高度基于目标对象空间。将地形保持在原点，或调整 --height-*。
• 过大的泊松数量会导致运行缓慢。按瓦片／区域进行散布，或在视口中降低密度、在渲染时再提高。
• 使用 blender-asset-qa（检查悬崖上的悬浮实例、Z-fighting 贴花）和 blender-game-optimization（检查实例、LOD、绘制调用）验证地形和散布。