Persistent bakes

Persistent bakes let Kiwi Grass load placement data from disk instead of regenerating all blades on startup.

workflow

1. Add TerrainGrassRenderer to a Terrain.
2. Assign the TerrainLayer, material, and optional profiles.
3. Leave Tools > Kiwi Studios > Kiwi Grass > Automatic Edit Mode Preview enabled for live Edit Mode generation. This global editor toggle is enabled by default.
4. When the current settings are ready for players, expand Persistent Bake and select Bake Persistent Asset, or use Actions > Persistent Bake > Bake Current Settings.
5. Keep Load Bake Automatically enabled to reuse the saved data in Edit Mode and Play Mode.

Preview generation never creates or rewrites persistent files. The explicit bake is a one-shot operation: it creates and assigns the metadata asset when needed, regenerates once, writes the result, and then returns to preview-only behavior. Terrain and settings edits mark the saved bake stale until the explicit bake action is used again.

The bake writes two user assets:

• TerrainGrassBakeAsset.asset
• TerrainGrassBakeAsset.kiwigrassbake

Both are created under Assets/ThirdParty/KiwiStudios/Grass/Bakes by default. Change the project-wide location from Tools > Kiwi Studios > Kiwi Grass > Persistent Bakes > Choose Storage Folder, or from Actions > Persistent Bake > Storage on the renderer. Storage must remain inside a subfolder of Assets; existing assigned bake assets are not moved when the setting changes.

validation states

The inspector caches fast header and metadata validation for the assigned asset. Tools/Kiwi Studios/Kiwi Grass/Validate Bake Assets and build validation force a complete streamed checksum check. A player build fails with an actionable message when a required bake is missing, stale, corrupt, or incompatible; valid external payloads are added to StreamingAssets automatically.

• valid bake
• missing bake
• stale bake
• corrupt bake
• unsupported format
• missing binary payload
• terrain mismatch
• settings mismatch
• gpu stride mismatch

Layout and placement changes make a bake stale. Rendering-only changes such as wind, material, lighting, render distance, LOD distance, fog, and shadow tuning do not invalidate the placement payload.

runtime behavior

When Load Bake Automatically is enabled and the bake validates, the renderer restores the Edit Mode preview and uploads the same blade data in Play Mode while allocating draw resources from the current quality settings. Version 1 payloads read their legacy 48-byte blade records and transcode them once into the packed upload path. Version 2 and 3 payloads retain their exact 32-byte persistent record and stream it into native memory without expanding every blade to the 48-byte CPU form. Every supported format Burst-transcodes into the 24-byte runtime GPU buffer and releases the temporary native array after transfer. With both domain and scene reload disabled, an already-ready preview survives the Edit Mode to Play Mode transition and is not loaded or generated again. If the bake is invalid in Play Mode and Runtime Bake Fallback is enabled, normal regeneration is used. If fallback is disabled, the renderer stays not-ready and reports the validation error.

Persistent writes happen only in the editor. Runtime players never write bake assets. Packing, full writes, unchanged-file comparisons, checksums, and validation use bounded streaming buffers instead of duplicating the complete payload in managed memory. The metadata asset stores paths rather than a TextAsset reference, so the binary payload does not stay resident in Unity object memory. Platforms with file-backed StreamingAssets load it directly; URI-backed platforms download it to temporary storage first and then use the same bounded file reader. A newly saved one-species bake upgrades version 1 data to format 2; enabling two or more species regenerates and writes format 3.

The writer, editor validator, local loader, and streamed loader fingerprint the same living-layer set and assigned control map. Changing the map's prebaked placement revision correctly makes the bake stale; an unchanged artist-controlled format-2 bake loads directly instead of falling back to runtime generation.

Format 2 stores one 32-byte species header around species-agnostic blade and chunk ranges. Format 3 repeats that validated header for two to four contiguous species sections. Each header records a stable species ID, profile fingerprint, material identity, chunk range, active blade count, and reserved blade capacity. Formats 1 and 2 map to primary species ID 1. Format 3 rejects zero or duplicate IDs, gaps, overlaps, invalid ranges, mismatched totals, and profile or material identity that does not match the payload fingerprint. Reordering advanced composition entries does not change species identity or invalidate an otherwise unchanged field.

terrain transforms

Blade roots are stored in terrain-local coordinates. The shader reconstructs world roots from the terrain world offset, and runtime chunk bounds shift when the Terrain position changes. Persistent bakes currently reject non-identity terrain rotation and non-unit terrain scale.