Overview

Kiwi Grass is a URP procedural terrain grass package that renders TerrainLayer-driven grass through HLSL, Burst, Jobs, and indirect GPU instancing.

requirements

• Unity 6000.0.0f1 or newer within the declared package range.
• Universal Render Pipeline and Core RP 17.0.3 or newer as bundled with the supported Unity 6 editor.
• Burst, Collections, Mathematics, Core RP, URP, Physics, Terrain, and Wind module dependencies declared in package.json.
• compute shader support for indirect rendering and stomp deformation.

installation

Use the embedded package at Packages/com.kiwistudios.kiwigrass, or install the package from disk by selecting Packages/com.kiwistudios.kiwigrass/package.json in Package Manager.

For the complete first-use path and visual checkpoints, see setup.md. Import the consolidated Cinematic Grass Showcase to exercise Quick Setup guidance, Cinematic Meadow, runtime painting, interaction, and multiple species in the playable scene, then use its package-safe 300 m and 1000 m scenes for the locked performance workflows.

basic setup

Add TerrainGrassRenderer to a Terrain with at least three distinct TerrainLayers: living grass, dead grass, and no grass such as dirt, path, or rock. Then use the contextual Complete Setup with Current Look action or Actions > Setup > Apply Current Look (Default). The explicit action preserves the selected living and no-grass layers, appends the bundled Dead Lawn layer when needed, resolves the bundled material, synchronizes an existing Dryness map, applies the verified embedded look, and starts one regeneration. Untouched placement becomes a candidate-grid-safe lush density, while bundled Mobile profiles retain lower density and cap targets. Automatic Edit Mode Preview is enabled by default from the Kiwi Grass Tools menu, queues one live preview after entering Edit Mode, and never writes a persistent bake.

profile setup

Use Embedded mode for existing serialized renderers. Use Profile mode when multiple renderers should share a grass style, wind setup, and quality policy. Profile mode keeps terrain, TerrainLayer, placement density, seed, chunk size, stomp resources, update timing, and camera layer mask on the renderer.

Bundled profile presets live in Runtime/Profiles/Presets. Create editable copies before changing preset values.

cinematic golden field

Open Actions > Setup > Cinematic Golden Field on a Terrain Grass Renderer to assign Tall Wild Grass, Meadow Breeze, and Cinematic quality in one step. Switch only the Grass Profile to Silver Pampas for the cool silver-beige alternative. Existing renderers can keep their current grass and wind while adopting the Cinematic horizon treatment with Actions > Setup > Apply Cinematic Far Quality.

Import the Cinematic Grass Showcase for a playable 128 m painted field plus the 300 m and 1000 m benchmark scenes used by the fixed-camera silhouette, LOD, backlight, motion, contact, and performance QA workflows.

selecting TerrainLayers

Assign one Living Grass Layer, one Dead Grass Layer, and one No Grass Layer. Living and dead paint both grow grass; the no-grass role is excluded. Add any number of other painted lawn, moss, meadow, or turf assets to Additional Grass Layers. Placement sums their alphamap weights and clamps the result, so blends between grass-bearing layers remain continuously covered without increasing candidate density.

Minimum Patch Width suppresses isolated blades by requiring a supported square of eligible ground around placement candidates. Eligibility combines all configured grass-bearing TerrainLayers, maximum slope, and enabled terrain holes. Set it to 0 to preserve unrestricted micro patches; the tall-grass Quick Setup preset uses 0.5 m and keeps the existing layer-weight density fade at the supported edge.

multiple species

Leave Multiple Species disabled for the exact one-species path. Advanced Field Composition supports three additional species, each with a stable ID, TerrainLayer, grass profile and material, density share, altitude and slope bounds, wind stiffness, interaction response, and quality mask. All active shares are normalized inside the renderer's existing total density and maximum-blade budget. The shared control map, terrain presentation, culling pass, stomp field, and GPU buffers remain field-wide; material and geometry-LOD command ranges remain species-specific. Use Actions > Field Composition > Apply Two-Species Meadow or Apply Four-Species Stress for bundled starting points. See multiple-species.md.

regeneration and live terrain painting

Valid settings and TerrainLayer changes regenerate automatically. Use Actions > Regeneration > Regenerate Now only for an explicit full retry. Runtime TerrainLayer repainting queues dirty regions so Kiwi Grass can patch affected chunks without rebuilding unchanged chunks.

artist control

Assign a Control Map on the Terrain Grass Renderer to author road exclusions, density masks, height transitions, dry zones, and wind-response regions. Create & Paint Control Map makes a project-local 512 x 512 linear RGBA32 map and enables a soft Scene-view brush directly on the Terrain. Dryness simultaneously reshapes and recolours the blades and repaints the same grass coverage between the living and dead TerrainLayers, so the visible ground matches the dead lawn without touching dirt. Use Ctrl/Cmd + scroll for size, Alt + scroll for strength, Shift + scroll for paint value, hold Z + paint to restore neutral, and Esc to finish. Add Kiwi Studios > Kiwi Grass > Artist Control Volume for transformable box, sphere, or capsule overrides including local cross-wind direction. Placement channels patch affected chunks continuously at a bounded live cadence. See artist-control.md for channel values, import requirements, blend order, persistence, and performance behavior.

persistent bakes

Expand Persistent Bake and select Bake Persistent Asset, or use Actions > Persistent Bake > Bake Current Settings. This one-shot action creates and assigns the metadata asset when needed; ordinary previews and dirty terrain updates never rewrite it. New assets default to Assets/ThirdParty/KiwiStudios/Grass/Bakes; choose another Assets subfolder from Actions > Persistent Bake > Storage or Tools > Kiwi Studios > Kiwi Grass > Persistent Bakes. Version 1 and 2 payloads load as one species. New one-species bakes write format 2, while two-to-four-species bakes write format 3 with validated stable section identity. Every format reaches the same 24-byte runtime GPU record without putting a species value in each blade. Stale, corrupt, missing, unsupported, terrain-mismatched, settings-mismatched, and persistent-stride-mismatched payloads are reported by the inspector, validation window, and build validator.

natural variation

Natural variation adds deterministic patch, height, width, color, clump, and domain-warp variation from terrain-local positions. Patch Size controls the scale of coherent regions, while Effective Height Range reports the final regional range after Patch Strength is applied.

wind modes

Simple wind provides broad directional bend. Layered wind adds turbulence and gust detail for richer motion.

stomping

Enable stomping and add Grass Stomp Source (TerrainGrassStompSource) to moving objects. The bundled compute shader resolves automatically unless the renderer has an override. Sources can use collider contact or local manual bounds, and only sources overlapping the terrain grass envelope are accepted. Capsule sources provide default-on grass-tip clearance without replacing the original stomp response or authored soft radius. Scene-view preview is enabled by default and can be toggled from Tools > Kiwi Studios > Kiwi Grass > Live Interaction Preview.

motion vectors

Standard quality uses camera-only motion vectors for temporal effects. Enable Procedural Motion Vectors, as the Cinematic preset does, when URP should evaluate current and previous wind, gust, terrain-offset, and stomp deformation. Kiwi Grass retains the previous stomp texture while interaction is active so new stamps and recovery contribute correct motion history.

performance settings

Tune density, chunk size, max blade count, render distance, ultra-far density, projected width, update step sizes, and dirty chunk limits for the target platform. Terrain LOD uses planar XZ distance so camera height does not prematurely remove field coverage. Standard setup keeps long-range coverage while moving the horizon through a compact camera-facing tuft and into a fuller irregular three-tip, five-triangle ultra-far tuft at 12% density, gradual post-160 m thinning, and a 2% floor. Reciprocal width compensation and bounded overlap preserve continuous coverage. Separate LOD-relative lighting bands stabilize random blade tint from 5%-30% of LOD0, dark root occlusion and tip sheen through 60%, and ribbon normals from a 94% to 100% surface blend before they become close or mid-distance grain. Root-to-tip color retains 47.5% contrast beyond LOD0 while root occlusion retains only 10%, preserving vertical blade texture without dark speckle or a flat color mass. Received main-light shadows keep a 28%-45% distance-aware foliage floor so terrain and structure shadows remain visible without turning grass patches black. Terrain surface normals remain stable at grass height instead of flipping above the camera; only ribbon normals use two-sided facing. The near field retains its authored density. Runtime generation packs its temporary 48-byte CPU blades into 24-byte GPU records. Persistent format 2 retains its 32-byte external record and transcodes directly into the smaller runtime buffer during loading. Standard lighting uses camera-only motion, receives scene shadows without casting every blade into the cascades, and skips depth normals. Quick Setup turns only untouched sparse placement defaults into a terrain-size and cap-aware lush baseline. Opt into the heavier Cinematic passes only when the target shot needs them.

Continue with the sample workflows, optimization guide, compatibility matrix, runtime API, upgrade guide, and troubleshooting. The benchmarks and validation page explains the accepted evidence and its current release boundary.

known limitations

Kiwi Grass is currently URP-focused. It does not include Entities or Entities Graphics. Persistent bakes currently support identity terrain rotation and unit terrain scale.