Upgrade guide

Before upgrading

Commit or back up the project, record the installed Kiwi Grass version, preserve project-local profiles and control maps, and keep the previous package available until the upgraded scene reaches Ready. Never overwrite project assets with package preset files.

From 0.7.x

The renderer, TerrainLayer roles, placement seed, and embedded look remain the starting point. Run Complete Setup with Current Look once if the old renderer lacks the living, dead, and no-grass role surface. Create editable profile copies only after the existing embedded look is confirmed.

Format-1 persistent payloads remain readable and transcode their legacy 48-byte records into the current 24-byte runtime GPU representation. Load and validate the old bake before creating a replacement.

Artist Control data

Control maps remain project-local RGBA32 linear, readable, bilinear, and clamped assets. Preserve the stable map asset rather than exporting only its texture. Reassign the map, confirm its neutral values and dry/wind channels, then validate terrain and control-map painting before rebaking.

From 0.8.x

Simple mode remains the exact one-species path. An unchanged 0.8.9 format-2 bake does not become stale solely because 0.9.x supports multiple species. Automatic Hi-Z retains its compatibility fallback; Medium, Low, Off, and bundled mobile profiles resolve it Off.

Add multiple species

Enable Multiple Species only after the one-species field is accepted. Assign each additional entry a unique stable ID, TerrainLayer, profile/material, density share, limits, response, and quality mask. Density shares are normalized inside the existing total candidate and blade budget.

The first multi-species persistent bake writes format 3. Species sections are identified by stable IDs and fingerprints, not inspector order. Do not recycle an ID for a different species.

Persistent formats 1 through 3

Corrupt, incomplete, identity-mismatched, or stride-mismatched payloads are rejected even when the metadata asset still exists. Rebuild rather than editing payload bytes.

Upgrade verification

Run the release validator, static audit, EditMode suite, a domain-reload-enabled and disabled Play Mode cycle, and the representative sample. Confirm fixed-camera near/mid/far color, interaction recovery, runtime paint, persistent load, and the target Development Player baseline before deleting the prior package.