Species architecture

Kiwi Grass keeps species identity at section and command granularity. It does not add a species field to the 24-byte runtime blade record.

runtime sections

Each active species owns one TerrainGrassRuntimeSpeciesSection with stable species identity, material index, contiguous chunk range, contiguous blade range, and contiguous indirect-command range. The renderer may retain these ranges in shared buffers, but every range has one owner and sections may not overlap.

Commands are ordered by species, material/pass, and geometry LOD. A submitted command therefore resolves its species and material before indexing a blade. The shader continues to consume the current species-agnostic 24-byte record.

Terrain sampling, terrain caches, dirty-region tracking, culling inputs, and the stomp field remain shared. Density, blade capacity, command capacity, GPU memory, bake size, and update budgets apply to the combined field rather than being multiplied once per species.

persistent formats

Format 2 already contains one 32-byte TerrainGrassBakeSpeciesHeader with chunk and blade ranges. Formats 1 and 2 continue loading as one-species payloads.

Format 3 is introduced only when a payload contains multiple serialized species or requires additional per-species identity that format 2 cannot validate safely. A format number is never bumped merely because the runtime supports section-based submission.

0.9.0 implementation

TerrainGrassSpeciesComposition keeps simple mode exact and expands to at most three additional entries. TerrainGrassSpeciesBakePlan normalizes shares and splits the existing density and maximum-blade totals before any species bake begins. TerrainGrassFieldBakeOperation combines completed species into contiguous sections, and TerrainGrassRenderLoop performs one culling pass before building per-section LOD command ranges.

The writer keeps one species on format 2 and emits format 3 only when two to four sections exist. The reader accepts formats 1, 2, and 3. Format 1 transcodes its legacy blade representation into the current persistent packing; formats 1 and 2 create one default runtime section. Format 3 validates every section and its deterministic profile and material identity.

invariants

• stable species IDs never depend on list order;
• section chunk, blade, and command ranges are contiguous, non-overlapping, and bounds-checked;
• material identity is resolved per section, never per blade;
• the 24-byte runtime blade record remains unchanged;
• existing formats 1 and 2 map to one default species;
• total field budgets are enforced before per-species shares are assigned;
• per-species diagnostics sum exactly to the total renderer diagnostics.