threejs-procedural-vegetation

程序化植被

将植被构建为编译器：稳定的环境成因转化为不可变的放置／拓扑记录，而风力与交互则保留为独立管理的动态状态。规范路径使用 Three.js r185 WebGPURenderer、TSL、NodeMaterial，以及由工作负载选择的计算／存储方案。

1. 定义可观测结果及其所有者

选择 API 前，先对每项所需结果进行分类：

分支	所需可观测结果	植被负责
密集植被群落	草、花、地被植物、重复分布的灌木／树木	放置身份、分页、表示方式、形变绑定
树木生长	树干、根系、枝条、叶片、根系驱动的风响应	生长层级、几何体、结构响应、LOD
地形生态	由地形或场地字段影响的植被群落	物种响应、候选项冲突、稳定性接受

明确坐标系、世界单位、植物特征尺度、目标摄像机／范围、更新频率、输出所有者及外部场字段所有者。地形、天气、水体、接触和光照仍由其对应的所有者管理；植被使用这些所有者提供的带版本样本。

当每项所需可观测结果都有唯一所有者，且每项外部输入都注明其生产者、单位、坐标系／图表、支持／滤波方式、修订版本、有效性、误差和更新频率时，此步骤即告完成。

2. 根据群落规模和投影误差选择表示方式

工作负载	默认表示方式
一棵或少数几棵近景树	在 CPU／工作线程中编译生长结果为索引缓冲区
重复分布的树木或灌木	在空间分页中实例化兼容的物种变体，然后使用几何体 LOD 和广告牌
密集草地或地被植物	使用共享条带／丛状几何体，并采用隐式、紧凑型 CPU 或后备存储的放置数据
放置或拓扑不断变化	仅用计算处理变化的记录，然后进行有界压缩

根据已测量的变化数据量、调度成本、数据流量和驻留情况选择计算方案。由 CPU 生成的静态植被可能是 GPU 成本最低的结果。对于每个近景／中景／远景范围，记录表示方式、过渡误差、扩展包围范围、阴影代理、静态字节数、动态字节数和提交的工作量。

当每个可见范围都只有一种主要表示方式，且每次过渡都具备未抖动的物理像素误差门限、迟滞／驻留时间和同时驻留内存预算时，此步骤即告完成。

3. 编译所选分支

高密度种群

1. 将域划分为确定性区块，使用全局 ID 和固定种子，采用半开区间所有权、保守的变形后边界，并提供可见的边界/LOD 诊断。 世界锚定的记录身份为 (generatorSchemaVersion, globalSeedWords, stableSpeciesIdWords, biasedWorldCellWords, candidateOrdinal)。哈希仅用作紧凑标签、优先级或随机通道；身份由完整元组相等性确定，并由其解决哈希冲突。物种或功能组 ID 必须保持不变，不能取决于其在注册表中的位置。添加其他种群系列或更改区块遍历顺序，都不能重新编号已有记录。
2. 比较隐式重建、群簇记录、紧凑 CPU 属性和存储记录。计算实际对齐后的步长、重复的 LOD 数据以及频繁读取的顶点数据。在 r185 中，computeAsync() 会等待初始化完成后再入队；这并不能证明 GPU 工作已经完成。
3. 生成后保持位置和物种身份不变。使用稳定整数哈希派生安全的变化；只更新风、触碰、湿度、积雪或其他选定的动态字段。
4. 在提交绘制之前，按空间分页执行剔除。使用近景几何体、中景嵌套密度稀疏化，以及远景簇或 impostor 表示。如果可见性掩码仍会提交每个顶点，那它只是外观掩码，而非剔除。
5. 每个分页边界都要扩展地形位移、植物高度和最大活动变形所需的范围。显示、阴影和拾取都使用同一边界。

当相同输入可重现相同 ID、区块顺序不会改变所属植物、位置字节与动态字节相互分离，且不可见分页不再产生已提交的几何体时，高密度编译即告完成。

地形生态

当地形、基质、暴露度、水分、扰动、光照或场地资产影响种植位置时，请阅读 terrain-ecology-and-placement.md。 先执行硬性适生条件筛选，再明确选择 Matérn-II/局部最大值语义或全局优先级贪心语义。严格按照该参考文档的定义，保留区块边缘扩展区、稳定的胜出者键以及嵌套 LOD 稀疏化排名。

当每株被接受的植物都能解析其字段版本、适生条件、响应因子、候选者/胜出者身份、资产和区块所有者，且排除项与接缝检查均无违规时，生态编译即告完成。

结构化树木

生成树干、枝条、根系、叶片或层级风效应时，请阅读 tree-growth-and-wind.md。编译迭代式生长层级，采用旋转最小化标架、显式扭转、物种异速生长、经过验证的连接点、按弧长计算的树皮 UV、稳定的叶片基部，以及共享的显示/阴影形变。

当队列在声明的预算内终止、所有枝条 ID 均唯一、标架和连接点通过连续性/网格检查关卡，且叶片根部、法线、UV 和边界均为有限且可重现的值时，树木编译即告完成。

4. 绑定动态状态与交接

当风、水、天气、接触、加载或其他模拟所有者向植被提供数据时，定义交接，明确单位、坐标系/原点、间隔或采样时刻、采样频率/采样相位、生产者/消费者/版本、作用范围/过滤条件、有效性/过期状态/误差，以及速率与积分量语义。

植被负责结构响应：根部约束、解析弯曲或模态状态、叶片颤动、触碰/负载状态、边界和 LOD 投影。它不负责空气/水/接触的成因。循环状态以固定步长或在路由的模拟阶段推进；渲染从不可变的前一状态和当前状态采样，以保持植物/页面身份稳定。呈现过程将这些状态转换为当前视图，不得修改放置位置。

单向视觉形变只读取源数据，不返回物理反作用。双向路由通过交接中指定的权威求解器传递反作用。驻留在 GPU 上的状态在对帧时间关键的工作期间始终驻留在 GPU 上；CPU 决策使用解析镜像、精简脏区间或带有明确时效/误差声明的保守边界。

当每个动态字段都有唯一的状态所有者、精确的采样/应用时间、稳定的身份/版本、有界的更新范围，以及针对创建、移除、瞬移、槽位复用、拓扑变化、LOD 不连续和提供方不连续的明确重置规则时，此步骤即完成。调整大小会影响屏幕资源/历史记录，不会影响不可变的世界放置位置或结构状态。

5. 渲染并仅呈现一次

在分配 WebGPU 资源之前进行初始化：

import { WebGPURenderer } from 'three/webgpu';

const renderer = new WebGPURenderer({ antialias: false });
await renderer.init();
if (renderer.backend.isWebGPUBackend !== true) {
  throw new Error('WebGPU backend unavailable for the canonical vegetation path.');
}

• 草和树皮使用 MeshStandardNodeMaterial；当蜡质响应需要时，使用物理清漆分支。折射 transmission 并非薄叶漫散射模型；应单独纳入并验证该光照项。
• 使用 alphaTest 或 alphaHash 实现镂空覆盖。在 r185 中，forceSinglePass 会改变透明双面材质的背面/正面绘制提交方式；不透明镂空材质本来就只绘制一次。它不会禁用背面法线光照。选择此优化前，先验证透明排序/覆盖效果。
• 声明实际的颜色编码：对编码后的 sRGB 只解码一次，线性 HDR 保持线性；法线、粗糙度、密度、alpha、风、LUT 等数据字段使用 NoColorSpace。
• 将植物根部固定在支撑锚点上，并将叶片/子级根部附着到移动的父级上。父级形变只应用一次，附着点处的额外局部弯曲权重为零。可见几何体和投射阴影几何体复用同一函数。
• 添加 AO、泛光或时间滤波前，先执行剔除并减少几何体/alpha 覆盖。只请求消费者实际使用的 MRT 信号。
• HDR 缓冲区保持线性，直到由唯一的色调映射/输出转换所有者呈现帧。

当可见、阴影、深度和运动路径都能解析到相同的植物身份与形变状态，所有颜色/数据均使用已声明的空间，并且恰好由一个组件负责色调映射和输出转换时，此步骤即完成。

6. 验证成因、成本和生命周期

检查最终输出/无后处理输出，以及特定分支的诊断信息：

dense: chunk bounds, submitted pages, density rank, LOD/impostor state,
       static versus dynamic storage, projected alpha layers
ecology: input fields, exclusions, response factors, candidate conflicts,
         chunk halo/ownership, accepted and rejected causes
trees: branch levels/frames/junctions, bark UVs, leaf roots/normals,
       wind displacement, swept bounds, shadow parity

记录可见/已提交的页面和实例、已处理但遭拒的顶点数量、 alpha 层的均值/p95、被遮蔽的工作量、对齐后的存储字节数、动态字段的 流量/频率、编译/更新时间、整帧和配对边际 CPU/GPU 的 p50/p95、峰值存活字节数，以及持续运行时的目标行为。

测试固定种子的回放、分块顺序变更、摄像机遍历、LOD 转换、风力/接触冲量、数据提供方不连续、尺寸调整、槽位复用和释放。失败特征包括：栖息地随渲染 LOD 移动、物种随种子变化、根系漂移、帧间螺旋、卡片法线平坦、每帧重新生成布局、屏幕外页面主导提交、阴影变形不一致，或资源/状态在所属对象释放后仍然存留。

只有当每个选定分支都通过成因、确定性、几何、转换、输出、预算、重置和释放检查时，验证才算完成；未选定分支无需载荷或证据。

路由边界

共享环境字段使用 $threejs-procedural-fields，通用网格生成使用 $threejs-procedural-geometry，可复用 PBR 标识使用 $threejs-procedural-materials，自定义阴影系统使用 $threejs-scalable-real-time-shadows，最终 HDR/后处理/输出归属使用 $threejs-image-pipeline。本技能负责植被布局、生长拓扑、枝叶、种群表示，以及扎根结构的响应。