Grass: the lawn itselfGR

GR1: grass that moves

Cosmetic, so the same on every preset and nothing to sync. The lawn reacts to whatever moves through it, then recovers.

The trample field

• A top-down texture holding a push direction, an amount and an age for the grass round you. Anything moving stamps into it every frame; a fade pass brings it back to zero. Grass.shader reads it next to GM_WindOffset and bends each tuft away from the push, its shadow too (or bent grass casts upright shadows). No chunk rebuilds, one texture read per vertex.
• It is one 51 m window round the local player, ~10 cm a texel, that wraps round as you walk. It covers every lawn near you: client gardens, town front lawns and grandma's lawn seen from the hub (YardGrass reads it too).
• Recovery by height: short grass (≤ 5 cm) is back in ~3 s, 8 cm in ~10 s, tall grass (15 cm+) in ~40 s. A wet lawn recovers ×1.5 slower; a drought-stressed one ×(1 + 3 × scorch) slower (the footprint test, GR2). Each tuft works out its own recovery from its height, so the field never needs to know what grows where.
• The feel: a push eases in over ~0.15 s instead of snapping (a foot stays down 0.2 s, a deck holds its push); the field is blurred a little round each tuft and stamps have soft edges; the blow's lean and the trample add up as vectors. A tuft that gets cut shrinks from its old height to its cut height over 0.45 s instead of popping.

The blade's blow

The air leaves the deck through its openings, like the stones (mowing.md MO3), and makes the grass round the deck lean out and flutter.

• A ring round each running deck (up to 4), worked out in the grass shader: no field channel, so no shimmer trail behind the deck. It is stronger at the front gap on the discharge side with a bag fitted (most of the air goes into the bag: a soft ripple), out of the discharge without one (a blast straight behind), a long jet to the right from a side chute, and the grass ahead blows flat when the deck is tipped up.
• The grass leans out from the deck with the air (up to ~30° at full blow) and flutters a little on top, showing the paler undersides of the blades.
• Strength = (blade speed)², from MowerVisual.BladeSpeed01 (~0.9 s to spin up, ~2.2 s to run down; guests run it from the blades-on flag). It builds as the blade spins up and dies away as it runs down: letting go of the bar fades it over the 2-3 s run-down (engine-stop bar) or in well under a second (brake clutch), and a bogging engine weakens it. ×1.4 with the high-lift blade, ×0.6 on slow throttle.

Mowing stripes

Stripes are light, not geometry. Grass bent away from you shows the long sides of its blades, which catch the sky (a light band); grass bent towards you shows tips and shaded undersides (a dark band). Walk to the other end and every band flips. No new model is needed: it's shading plus a fine record of which way the grass lies.

Why a stripe map, and not the old per-cell lie (each cut cell scaled its colour by 1 + dot(lie, view) × 0.24):

1. Blocky band edges: a deck is ~1.5 cells wide, so edges followed the grid and a diagonal pass became a staircase.
2. Same contrast from every height: real stripes nearly vanish looking straight down and are strongest looking low across the lawn.
3. Flat brightening: real bands get their glow from the sky on the blades and their darkness from shaded undersides, so they read best with a low sun and soften under cloud.
4. A roller looked like a rotary, while real roller stripes are much bolder.

• The stripe map (StripeMap): a top-down texture at 7.5 cm a texel (a 4 × 4 record per cell), direction + amount, written as you push by the deck's cut circle swept along your path. Band edges are straight lines along your real path, diagonals stay clean, an overlap takes the last pass's direction. The grass and the stripe mat sample it per pixel. The per-cell lie in LawnGrid stays the sim's truth (streak, grain, memory); the map is the look.
• Shading, with d = how much the grass lies away from the camera (−1..1) and g = how low you look ((1 − |view.y|)^0.8, floor 0.15):
  • brightness 1 + k × g × light × d (k = 0.30 rotary, 0.60 roller);
  • a sky sheen on light bands (a pale sky tint × 0.12 × d × g) and shaded undersides on dark ones (−10% × |d| × g);
  • light: ×1.2 with a low sun, ×1 at midday, ×0.6 overcast (LawnWeather, DY3's sun).
• Roller ×2 contrast, lasting 4 cm of regrowth.
• Patterns (garden.md GA6: checkerboards, diagonals, circles) come out crisp for free.
• Co-op: each machine draws the stripes of every mower it sees: its own through the cut, the others from their avatars. Cells changed some other way (a merge, the trimmer, lawn care) are brought back in line with the grid after 0.4 s.
• Coming back crisp: the bands are usually gone by the next visit (a rotary's after ~1.5 cm of regrowth, about a day; a roller's after ~4 cm, about three days), but a quick return would show blocky bands rebuilt from per-cell values. A band edge always runs parallel to the stripe, so each cell only needs where the edge crosses it: a 3-bit band-edge offset in lawn memory (eighths of a cell, 0 = no edge). On load the map is rebuilt from the cell directions plus the offsets, with straight edges (bit layout in Tech).

Needs: MO1 · Done when: the bands flip as you walk round a freshly striped lawn, are strongest looking low across it and faint from straight above, a diagonal pattern has clean edges, and leaving and coming back the same day shows the same crisp bands; walking through 15 cm grass leaves a trail that stands back up over about 40 s, the mower pushes a bow wave, the grass shivers round the deck until the blade stops, a morning lawn shows dark dew trails, and the guest's footsteps bend the grass on the host's screen.

GR2: grass condition and scorch

Every cell has a condition, built from the weather, the cell's own grass and its place in the garden. The mower reads the condition, never the weather.

Pluggable to weather: three layers

• Until weather.md WE3, the lawn weather comes from the calendar: wetness from dew and rain, soil moisture from the last ten days' rain, heat 0.35 in a dry streak of 4+ days in spring and summer, heavy rain on half the rain days, a wind direction per day. The sandbox can override it.
• New weather later (a cold snap WE10, a drought WE11) = weather.md fills a lawn-weather value and the matrix gets or tunes a row. No mower code. Heat waves wait for WE11.
• Wet keeps loading the deck through the mower's humidity, as before GR2: the matrix's wet row only drives grip, clog, sound and spray, so job balance doesn't move. "Lush" comes from feed and soaked soil only (thickness already sets the mass).

Every cell has its own condition

The site map, per cell (Garden/GardenSite.cs):

• Sun exposure (0-1, the share of the day in direct sun): six positions of DayCycle's sun arc, a raycast per cell, past the house, trees, hedges, fences and sheds. Tree shade is dappled: a canopy lets ~25% of the light through (deciduous trees far more when bare, with seasons); hedges, walls and houses block it all. Neighbours count: the houses next door and street trees within ~15 m. Shade keeps dew and frost longer and slows growth; sun scorches; damp shade grows moss (GA2).
• Paving edge: lawn within 0.6 m of a hard surface (mowing.md MO2: drive, path, patio, slabs).
• Mound or dip: from the grid's bumps and wet dips.
• Tree roots: within 1.5× a tree's canopy radius.

Scorch: sun-exposed grass browns in dry heat

Real turf lore, kept close: grass browns first where it's hottest and driest, and long grass survives heat best (its blades shade the crown and the soil, and it grows deeper roots). Lawns usually go dormant, not dead: brown, then green again after rain.

Each day, in the daily tick:

scorch += 0.12 × heat × site heat × exposure × (1 − moisture) × shade(height now) × roots(usual height) × torn tips

• Heals with soil moisture: −0.08 × clamp((moisture − 0.3) / 0.4) a day (−0.08 in rain, about −0.04 on a normal day), −0.2 a day watered; never below 0.
• Caps: 0.3 in a dry streak (the mild version, possible now in late spring); 1 in a heat wave.
• Dormant from 0.6: brown but alive, green again 1-3 weeks after rain or watering.
• Dead: lawn memory counts the days fully brown (scorch 1) in dry heat. After 12, the crowns die and the cell goes bare (the existing bare patches): only seed brings it back (GA2 overseeding, the seed shaker). A scalp on dormant turf leaves bare soil too.
• What it adds up to: a week of heat wave in full sun on dry soil reaches ~0.6-0.8 (dormant, recovers). Three weeks at a normal height kill only the hottest strip (the drive edge); cut short, most of the sunny lawn dies; kept long, almost none. The strip in the house's shadow stays green throughout.
• The footprint test (a real gardener's test): on drought-stressed grass, footprints and wheel tracks stay. The trample field recovers ×(1 + 3 × scorch) slower, so at 0.6 your prints last three times as long (the field remembers 180 s). If your footprints stay, the lawn needs water: a hint with no HUD.
• Look: the shader's per-cell dry value is max(dry patch, scorch): straw from ~0.4, brown past 0.75; dormant tufts droop a little; dead cells draw as bare soil.
• Work it creates: clients notice brown patches (and blame the mower if you scalped in the heat); watering (a sprinkler, a hose job: WE14); reseeding dead cells (GA2); feed on scorch above 0.3 burns (GA2).

Sun, shade and growth: an uneven lawn

• Growth follows the sun: each cell's daily growth × (0.6 + 0.4 × exposure), on top of its own vigour and patch growth (dandelions faster, dry patches slower). Density too: thickness × (0.7 + 0.3 × exposure), and the shader pales and thins shady tufts.
• So heights go uneven between visits: on a normal week, ~10 cm of regrowth in full sun against ~7 cm in deep shade, varying smoothly, and every cut levels it again. The mower feels it (load follows the mass), shady corners need mowing less often but look patchier, and moss sets in there (GA2).

Rain-flattened grass (lodging)

• After heavy rain in the last day, uncut grass taller than ~12 cm lies flat in patches (seeded noise), wet and lush cells most, laid the way the wind blew.
• It mows like spring-back's laid grass (mowing.md MO6): each pass along the lay leaves 40-60% of the excess (one try per pass, so a second pass along catches more), tufts popping up minutes later; a pass against the lay takes it all. It stands back up once the rain is two days old.
• Derived from the recent weather and the cell's height: nothing saved. Drawn through the trample field's hold. Storm clean-up work comes with it (WE8).

The response matrix

Each condition has a strength 0-1 (wetness, scorch, weed cover…); a factor f applies as 1 + (f − 1) × strength. Starting numbers, tuned in the sandbox. - = no effect.

• Stacking: mass, bag fill, clog, dust and scalp harm multiply; grip multiplies what's left (−40% and −20% = ×0.48); deck bob takes the largest; wet over 0.3 cancels dust.
• Clean speed isn't a column: it comes from the combined mass (CleanSpeed = optimal / √mass). A dewy, lush, weedy cell at 8:00 (wet 0.6, lush 0.5, weeds 1): mass ×2.9, clean speed ×0.58.
• Mass is per cm of grass removed, so the cell's height already counts. Load and fuel follow the mass; dust wears the air filter (mowing.md MO5); grip feeds the slip on turns; scalp harm scales how long a scalp stays brown.
• Cut sound and off the deck feed CutAudio (its brightness) and MowerVfx (the spray colour), layered by the conditions under the deck, weighted by strength, plus a dust haze over dusty grass. Thatch, moss, frost, leaves and new turf are neutral rows until their ideas come (GA2, seasons, GA5).

The conditions

Feedback, all in the world: dew shows in the dark trails and the squelch; dust as a haze behind the deck; frost as a white sheen; scorch as the straw-brown colour of the cells; drought as footprints that stay.

Needs: GR1, MO2 (paving edges) · Done when: the same lawn mows heavy and clumpy at 8:00 and light at noon by changing only the sandbox's weather, and a sandbox heat wave browns the drive edge and the mound first, leaves the strip in the house's shadow green, thins the grass under the tree, and keeps your footprints; a week after mowing, the sunny side is visibly taller than the shady corner; after a storm, the long grass lies flat with the wind; and a dewy patch squelches while a scorched one crackles.

GR3: the grass look

The chunky tuft matches the art direction (ArtSource/STYLE_GUIDE.md) and the budget, so the style stays. These are targeted additions, each picked by the cell's hash, its state and the chunk's distance (LawnRenderer; YardGrass picks variants by hash and the far tuft by distance, so town front lawns get them too).

Performance target and the grass detail setting

• Target: 60 fps at 1080p with a 4,000 m² lawn in view on the minimum-spec machine (not defined yet; until it is, the dev Mac with the setting on Low).
• Grass detail in Settings (Low / Medium / High; per machine, display only, nothing synced in co-op; older settings read Medium):

• The stripe map stays 7.5 cm on every setting: it's the lawn's look of the sim, and small. The sim never changes with the setting: the same cells, conditions and responses on every machine.

Needs: GR1 · Done when: a freshly cut lawn seen from above shows no repeating pattern, tall grass in spring carries seed heads, a sunny dewy morning glitters, yesterday's clippings look straw-coloured, and a 4,000 m² estate holds 60 fps at 1080p on the min-spec machine (or the dev Mac on Low until min spec is defined).