Upgrade guide

Package identifier migration in 26.9.0

Kiwi Grass 26.9.0 changes the UPM package identifier and package root from com.kiwistudios.kiwigrass to net.kiwistudios.kiwigrass. The public C# namespaces, assembly names, type names, serialized identifiers, and all existing asset GUIDs remain unchanged.

Do not install both identifiers in one project. They contain the same assemblies and assets, so keeping both can create duplicate-assembly and duplicate-GUID errors.

For an Asset Store or registry installation:

1. Commit or back up the project and close any open scenes that are still importing.
2. Record whether Kiwi Grass is installed from the Asset Store, a registry, Git, disk, or as an embedded package.
3. Remove com.kiwistudios.kiwigrass through Package Manager. If it is embedded, remove only Packages/com.kiwistudios.kiwigrass after confirming project-owned profiles, control maps, and persistent bake payloads are outside that folder.
4. Install net.kiwistudios.kiwigrass from the same authorized source and allow Unity to finish resolving and importing packages.
5. Confirm Package Manager shows only net.kiwistudios.kiwigrass, open representative scenes, and verify that renderers, profiles, materials, TerrainLayers, control maps, and persistent bake references remain assigned.

For a directly edited Packages/manifest.json, replace the dependency key com.kiwistudios.kiwigrass with net.kiwistudios.kiwigrass and update a file path or Git reference if it includes the old package-root name. Let Unity regenerate Packages/packages-lock.json; do not keep both dependency keys.

If scripts appear missing after the change, first confirm the old package is fully removed, the new package has resolved without compiler errors, and only the KiwiStudios.KiwiGrass runtime and editor assemblies are present. Restore the backup before making scene or prefab changes if references remain unresolved.

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.

Existing renderers

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.

Existing one-species fields

Simple mode remains the exact one-species path. An unchanged format-2 bake does not become stale solely because Kiwi Grass 26.8.0 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.