# forestKit
**Drop a temperate deciduous forest into any world.** Pick a size, a density and a seed, each one setting, and ask for a stream if you want one: forestKit builds the ground (forest floor, leaf litter, moss, a footpath, muddy banks), carves a stream with stepping stones, fills it with oak, beech, birch and maple of every age, shrubs, ferns, long grass, wildflowers, moss, fungi, logs, stumps and rocks by a set of woodland rules, and draws it all as a handful of instanced draws with levels of detail. On top: dawn, midday, dusk and night plus rain on worldClockKit's shared clock, a colour grade for each, haze and sun shafts through the canopy, forest ambience that follows the time of day and the stream, and footsteps that sound like leaves, moss, mud, the path, grass, logs, stone or shallow water.
**Install and use:** install forestKit from ZeroMind (it brings forestProps and forestMaterials with it), then put a `forestKit.Forest` component on any entity and set its size, density and seed, or paste the first example below into a scene. Add `forestKit.atmosphere.ForestAtmosphere` for the time of day, rain, ambience and footsteps. `ForestBuilder.build` does the same from code, with your own paths, clearings and hand-placed trees.
Every player builds the same forest from the same settings, sees the same time of day and weather, and hears the others' footsteps.
Version 0.2.27: corrects the 0.2.25 note below. 0.2.26: the opening says how to install and use the kit. 0.2.25: on built-in library 5e6f9ec, the one current engines run. 0.2.24: on built-in library abf2b3b. 0.2.23: on built-in library b605ddd; the editor's long queue of preview pictures after re-baking many props is fixed in the engine, so it is out of the known limits. 0.2.22: the time-of-day looks can no longer be changed in place by anything that reads them (they are frozen and every look is handed out as a copy), so the atmosphere tests pass whatever the weather; the first example's numbers are measured again. 0.2.21: every known limit names its open issue (#5087, #22759, #22760 added). 0.2.20: The same seed and settings give the same forest on every machine, desktop and browser alike: the same props in the same places with the same trunks, rocks and logs to collide with, on ground sampled every half metre everywhere. The browser used to fill 70% as densely and sample its ground every metre, so two players saw trees in different places; now it only draws less far. `forest.stats.fingerprint` (and `ForestBuilder.fingerprint(instances)`) gives a short code two machines can compare. The `webDensity` build option is gone. 0.2.19: its footstep tests read soundstage's prefixed surface ids. 0.2.18: The forest's footstep surfaces are registered with soundstage under prefixed names (forestPath, forestLog and so on), so plain words like "Path" or "Log" elsewhere in a world keep the meaning soundstage ships; on worldClockKit 1.4.7. 0.2.17: declares soundstage 2.1.3. 0.2.16: A player who spawns under the forest floor (on a starter floor, say) is set on top of it; forest footstep words no longer change soundstage's shared word list; on Skyclock worldClockKit 1.4.6 and soundstage 2.1.3, whose tests pass beside forestKit. 0.2.13: Walkable from the first example (the ground is solid under every player), no rebuild on Play, lighter on the web, and the 24 new forestProps kinds in the fill rules (elder, hawthorn and dog rose in the shrub layer; bilberry, tussock grass, ivy, two mosses and two fungi as ground cover; branch litter, twigs and leaf litter on the floor; nettles and cow parsley at edges; rushes, bulrushes and pebbles on the banks; split logs, fallen branches, root plates and ivy stumps as deadwood).
## First example
```luau
-- in scenes/main.scene/build.luau, inside content()
local forest = entity.spawn("Forest")
forest.component.add("forestKit.Forest", { size = 120, density = "normal", seed = 7, stream = true })
local Atmosphere = require("@root::forestKit.Atmosphere")
-- the shared day/night clock (one synced entity), lit with the forest's sky look
Atmosphere.ensureClock({ startHour = 11, skyMode = "engine" })
-- light, air and sound on every machine (it also provides the sky when the scene has none)
entity.spawn("ForestAtmosphere").component.add("forestKit.atmosphere.ForestAtmosphere", {})
```
Save: the ground rises, the stream fills, and the trees and undergrowth fill in. Change `seed`, `density` (`sparse`, `light`, `normal`, `dense`, `lush`), `forestType` (`oakWoodland`, `beechForest`, `birchGrove`, `mixedMaple`, `autumnWood`), `season` or `look` (`real`, `painted`, `toon`) and it rebuilds. `Atmosphere.setTime("dusk")` and `Atmosphere.setWeather("rain")` change the hour and weather for everyone.
Guides: **how to make a forest for my game** (`guides/how-to-make-a-forest.guide`) and **add trees and a stream to my world: a forest walk from an empty world** (`guides/forest-walk-from-an-empty-world.guide`).
## What's inside
| Part | What it does |
|---|---|
| `Forest` component | The one-component forest: size, density, seed, stream, path, clearings, forestType, season, look, quality. Synced fields; every machine builds the same forest. |
| `ForestBuilder` | `ForestBuilder.build{ ... }` from code, with your own path, clearings, spots kept clear and hand-placed hero props (`extras`). Returns the forest (`site`, `instances`, `stats`, `update()`, `destroy()`). |
| `Ground` | The land as pure functions of a seed: rolling relief, a meandering stream in a shallow valley with low muddy banks, the path, clearings, the terrain layer and the footstep surface at any point. `Ground.surfaceAt(x, z)` and `Ground.streamDistance(x, z)` answer for the active forest. |
| `Rules` | How a forest fills in: canopy, understory, deadwood, rocks and stream stones, stepping stones at crossings, shrubs, ferns, grass, flowers (under trees, at edges, in clearings, by the water), moss and fungi. |
| `ForestTypes` | Five ready woodlands, and `define()` for your own. |
| `ForestRender` | Draws the placement as instanced draws (one per prop part per level of detail) and re-sorts instances into near/mid/far as the camera moves, a few groups a frame. |
| `StreamWater` | The stream's flowing water surface (Flux and Flicker's clear river), following its falling level. |
| `ForestAtmosphere` component, `Atmosphere`, `Ambience`, `Footsteps` | Light, air and sound on worldClockKit and soundstage (see `atmosphere/README.md`). |
## How it stays smooth
- Draw calls: one per prop part per level of detail present, a few hundred for the 160 m showcase however many plants it holds.
- Levels of detail by distance: trees 34 / 80 / 900 m, shrubs and logs ~22 / 50 / 120 m, ferns, grass and flowers vanish past ~40 m. `quality` scales them all.
- Shadows: trees cast through their mid-detail mesh, logs, stumps and rocks only up close, ground cover not at all.
- Colliders: one compound for every trunk, one for every rock and stepping stone, a box per log (marked `forestSurface = "log"`).
- Solid ground under every player: the forest makes its ground stand (and collide) under every body that carries a character controller, local or joining later, so the first example above is walkable in a world with nothing else set up. While the ground under a player is still missing it loads with a larger per-frame budget (24 ms instead of 4).
- Built once per session: every ground sample is remembered, so pressing Play (which loads the scene again) stands the same forest from memory. In the showcase the ground under the player stood 0.1 s after Play and the whole forest was back in under a second (desktop).
- Same forest on every machine: what stands and what you can bump into never depends on the machine. On the web build the forest only draws lighter: draw distances are capped at `quality = 0.6`, so far trees switch to their simpler meshes sooner and ground cover fades out nearer. `webQuality` in the build options changes that cap. Compare `forest.stats.fingerprint` on two machines to see that they stand the same forest.
## Measured performance
Desktop: the 160 m showcase walk with the whole forest drawing (about 8,200 placed props in about 1,080 instanced draws, near, middle and far detail levels all in use), walking the marked route in play with real key input for 25 s while the profiler recorded every frame. Native desktop app, debug build, freshly started engine.
| Where | Avg fps | Frame time avg / median / 90th / 99th pct | Hitches | Graphics memory |
|---|---|---|---|---|
| Desktop (`quality = 1`) | 30.4 | 32.9 / 26.1 / 56.8 / 112.2 ms | 215 of 768 frames | 732 MB |
| Desktop with browser settings (`quality = 0.7`, browser shadow settings), measured before the new undergrowth | 32.5 | 30.7 / 28.9 / 46.2 / 64.6 ms | 116 of 815 frames | 815 MB |
| A real browser tab (the showcase, a player standing on the ground, measured by a player) | about 26.6 to 30.2 | | | |
- **In a browser:** the showcase runs at about 26.6 to 30.2 frames a second once it stands, but it takes about 171 seconds to appear, because loading each tree and prop model is slow in the browser build (engine issue #22751). The ground is not the wait any more: it stands under the player first, with a larger per-frame budget while it is missing, and pressing Play stands the forest again from memory. For a web game, a smaller forest (about 120 m at `normal` density) has fewer kinds and ages to load.
- Graphics memory is the whole editor process (scene, editor and tools), not the forest alone.
- The largest script cost while walking is the engine's own walking controller for the player (about 17 ms per frame in a dense forest on desktop). Everything forestKit runs per frame costs under 0.5 ms.
- The first example above (120 m, normal density, seed 7, with a stream) places 4,966 props drawn in 910 instanced draws from the editor's starting view. On a fresh install its first build takes about 3.9 s on desktop, most of it loading and uploading every tree and prop model once; built again in a session that already holds those models, it takes about 1 s (0.96 s measured).
## Multiplayer
Two players walking together see the same forest and the same time and weather:
- **Same forest:** the forest is not sent over the network. Every player builds it from the same settings in the scene, on a desktop or in a browser alike, and the build is deterministic: `tests/forestKit.testSuite` checks the ground and the placement come out the same from the same settings, and that a web build places exactly what a desktop build does. `forest.stats.fingerprint` is the same short code on every machine that stands the same forest (the showcase: `8069-2792b58a`).
- **Same time and weather:** worldClockKit's `WorldClock` is one synced, world-wide entity; its clock, weather and sky are replicated fields.
- **Each other's footsteps:** soundstage plays other players' steps where they walk and forestKit picks the surface under each walker. This was checked with a simulated second walker in one engine, not with two people: a live two-player walk was not possible here (#14448), so treat it as untested with real players.
## Known limits
- **#14448**: two engines on one account collide as one player, so nothing here was tried with two real players.
- **#20946**: the agent that built this cannot open the browser build itself, so the browser numbers above come from a player's own test in a browser tab.
- **#22751**: loading each tree and prop model is slow in the browser, so the showcase takes about 171 seconds to appear there.
- **#21420**: installs with several dependencies are slow; a full forestKit install brings about 11,000 files.
- **#22451**: an install can leave an unused older copy of a dependency (the material library kit lands at two releases beside the collections).
- **#19258**: a package's description on ZeroMind can lag a release, so the store listing may show the previous version's text for a while.
- **#5087**: the engine sky stays clear blue in rain while the forest itself greys and darkens.
- **#22759**: the engine's built-in walking controller costs about 17 ms per frame in a dense forest, the main source of the hitches measured above.
- **#22760**: a long editor session grows by about a gigabyte of memory each time it switches worlds with a forest loaded, until the editor needs a restart. Players are not affected.
## Depends on
forestProps and forestMaterials (this world), Terra Firma (groundMaterials), Heartwood (woodsMaterials), Bedrock (stoneMaterials), Scale and Feather (organicMaterials), Flux and Flicker (animatedMaterials), worldClockKit (Skyclock), soundstage.
## Tests
`tests/forestKit.testSuite` (ground is deterministic, the stream flows downhill in a carved channel, footstep surfaces, placement respects water and path and lays stepping stones, density, forest types, build and teardown) and `tests/atmos.testSuite` (presets, weather, footstep surface mapping).
# forestProps
**61 kinds of temperate forest trees, plants, logs and rocks for any world, each one switched by a single component.** Oak, beech, silver birch and maple from sapling to veteran, a dead snag, a broken tree and a fallen giant, plus ferns, shrubs, grasses, reeds, wildflowers, ivy, mosses, fungi, forest-floor litter, logs, stumps, boulders and pebbles. Every prop has near, middle and far levels of detail, and the same switches work on all of them: `kind`, `age`, `season` (spring, summer, autumn, winter), `look` (real, painted, toon), `variant` and `detail`.
**Install and use:** install forestProps from ZeroMind (it brings forestMaterials, the surfaces it is drawn with), then put a `forestProps.ForestProp` component on any entity and pick the prop. Load the `PropGallery` scene to see every prop side by side. To fill a whole forest with them by woodland rules, install forestKit, which brings forestProps with it.
```luau
entity.spawn("oak").component.add("forestProps.ForestProp", { kind = "oak", age = "veteran", season = "autumn" })
```
Baked, LOD'd props for a temperate deciduous (English / central-European) woodland: oak, beech, silver birch and maple trees at four ages, a standing dead snag, a snapped broken tree and a fallen veteran oak, plus ground cover (ferns, bushes, grass, reeds, flowers, herbs, ivy, moss, fungi, forest-floor litter, logs, stumps, rocks and pebbles): 61 kinds in all. Every mesh is generated once and baked into the package, so installing it costs no generation; one `ForestProp` component switches any prop by kind, age, season, look and variant. Materials come from the `forestMaterials` package (its dependency).
## ForestProp
Put it on any entity; it builds child entities (one `Model` + `MeshLod` per part, swapping LOD0 -> LOD1 -> LOD2 by screen size) and a static collider, all local and unsaved, rebuilt from its synced fields: so every peer builds the same prop and a reload rebuilds it. Changing any field rebuilds.
| Field | Default | Meaning |
|---|---|---|
| `kind` | `"oak"` | any kind `Props.kinds()` lists (`oak`, `beech`, `birch`, `maple`, `deadSnag`, `brokenTree`, `fallenGiant`, and every ground kind below) |
| `age` | `"mature"` | trees: `sapling`, `young`, `mature`, `veteran` (ignored by kinds without ages) |
| `season` | `"summer"` | `spring`, `summer`, `autumn`, `winter` (deciduous trees are bare in winter) |
| `look` | `"real"` | `real`, `painted`, `toon` (toon trees use a clumped-blob crown) |
| `variant` | `1` | baked shape variant, 1..n (wraps) |
| `seed` | `0` | when non-zero, picks the variant and a yaw turn from the seed (for scattering) |
| `detail` | `auto` | `auto` swaps to the cheaper far versions as the prop shrinks on screen; `near`, `mid` or `far` pins one |
| `collide` | `true` | build the catalog entry's static collider (tagged with attribute `forestSurface` when the entry names one) |
## Gallery
Load the `PropGallery` scene (or put a `PropGallery` component on any entity) to see every prop side by side, labelled with its settings: each tree type at every age and shape, every season in every look, near/mid/far/auto detail, dead wood, and every undergrowth, log, stump and rock kind in each shape, season and look.
## Props API
```luau
local Props = require("~forestProps.Props") -- "forestProps.Props" from outside a package
Props.kinds() -> { string } -- every kind, trees first
Props.kindsOf(category) -> { string } -- "tree", "deadtree", "bush", "fern", ...
Props.info(kind) -> Entry? -- { kind, category, ages?, variants, radius, height, collider?, surface?, byAge? }
Props.parts(kind, { age?, season?, look?, variant?, lod? }) -> { { mesh, material } }
Props.normalize(kind, opts) -> opts -- the defaults/clamps parts applies
Props.register(entry, partsFn) -- how a catalog adds kinds (GroundCatalog does)
```
`Props.parts` only hands out baked meshes (read from the generated `BakedTrees` / `BakedGround` literal indexes), each with the forestMaterials material for that season and look. Trees: part 1 is bark, part 2 leaves (absent in winter). Tree entries add `byAge[age] = { radius, height, trunk }` (metres) for spacing and colliders per age.
## Trees
| Kind | Ages | What it is |
|---|---|---|
| `oak` | sapling, young, mature, veteran | English oak: decurrent trunk splitting into gnarled limbs; the veteran has a huge buttressed trunk, low wide-spreading limbs and broken limbs |
| `beech` | sapling, young, mature, veteran | European beech: smooth grey straight leader trunk, tall dense dome, flat layered leaf sprays |
| `birch` | sapling, young, mature, veteran | silver birch: slender white trunk, narrow airy crown, weeping hanging twigs |
| `maple` | sapling, young, mature, veteran | field maple / sycamore: short trunk splitting into ascending limbs, rounded crown |
| `deadSnag` | - | standing dead tree, silver deadwood, broken stub branches and a jagged top |
| `brokenTree` | - | thick trunk snapped low, splintered jagged top with rotten wood in the break |
| `fallenGiant` | - | a veteran oak lying on its side (+X), mossy bark, broken limbs, upturned root plate with soil at the origin |
Three seeded variants each. Trunks and branches are tapered tubes (root flare with buttress lobes, collars at joins, bark UVs at a fixed world scale continued from parent to child); leaves are alpha-cut leaf-cluster cards on the twigs with normals bent outward from the crown centre and RGB darkened toward the crown core. Leaf-card vertex alpha is the wind weight (0 at the twig -> 1 at the card tip); bark is solid, alpha 1. Winter LOD2 uses a branches-only stand-in (`barkw`).
Triangle counts (max over the 3 variants; LOD0/1/2 summer, LOD2 winter, LOD0 toon):
| Tree | LOD0 | LOD1 | LOD2 | LOD2 winter | LOD0 toon |
|---|---|---|---|---|---|
| oak sapling / young / mature / veteran | 1.4k / 5.0k / 11.5k / 19.5k | 0.3k / 1.5k / 3.5k / 5.9k | 174 / 368 / 483 / 530 | <= 600 | 2.0k / 3.4k / 8.0k / 9.7k |
| beech | 1.3k / 5.0k / 11.5k / 19.5k | 0.3k / 1.5k / 3.6k / 5.9k | 164 / 414 / 562 / 600 | <= 600 | 1.8k / 3.3k / 8.3k / 11.2k |
| birch | 1.4k / 4.3k / 11.5k / 17.3k | 0.3k / 1.1k / 3.4k / 3.8k | 180 / 378 / 574 / 592 | <= 600 | 2.2k / 3.4k / 10.2k / 13.9k |
| maple | 1.2k / 5.0k / 11.5k / 19.5k | 0.3k / 1.5k / 3.5k / 5.9k | 164 / 334 / 395 / 482 | <= 600 | 2.0k / 3.9k / 9.4k / 12.6k |
| deadSnag / brokenTree / fallenGiant | 1.3k / 0.5k / 2.3k | 456 / 296 / 720 | 50 / 64 / 102 | - | - |
Budgets (INTERFACES.md): mature LOD0 <= 12k, veteran <= 20k, LOD1 ~25-35% of LOD0, LOD2 <= 600.
Regenerating: edit `TreeGen` (species x age parameters live in its `config` table), then in a task run `require("forestProps.TreeBake").bakeKind("oak")` for each changed kind (or `.bakeAll()`), then `.writeIndex()` (regenerates `BakedTrees`) and `.prune()`. Bakes overwrite in place; nothing duplicates. `tests/trees.testSuite` checks every kind/age/season/look/variant/LOD resolves, winter is leafless, the budgets, and that ForestProp rebuilds.
## Ground props
Fifty-four ground kinds, each with 3-4 seeded shape variants and three LODs, baked as meshes under `meshes/ground/<kind>/` and registered by `GroundCatalog` through `Props.register`, so they switch exactly like trees: by `kind`, `season`, `look` (`real`, `painted`, `toon`, via forestMaterials), `variant` and `lod`.
| Category | Kinds | Made of |
|---|---|---|
| fern | `fernBracken`, `fernMale`, `fernHartsTongue` | one bent alpha card per frond in a radial clump (bracken arching flat, male fern a shuttlecock, hart's tongue wavy straps) |
| bush | `bramble`, `hazel`, `holly` | a stem skeleton (arching bramble canes, a coppiced hazel stool with twigs, a holly trunk with a spiral of branches) carrying leaf-sprig cards |
| grass | `grassClump`, `grassLong` | bent blade-tuft cards leaning out of the clump |
| flower | `bluebell`, `foxglove`, `woodAnemone`, `redCampion`, `buttercup`, `wildGarlic`, `daisy` | a patch of plants, each two or three crossed whole-plant cards |
| moss | `mossCushion` | a lumpy, flat-bottomed cushion |
| fungus | `flyAgaric`, `toadstools`, `bracketFungus` | lathed stems, caps and gills; toadstools on a moss pad; banded bracket shelves on a mossy bark stub |
| log | `logFresh`, `logMossy`, `logHollow`, `logRotten` | displaced bark tubes with saw-cut ring faces or splintered broken ends, branch stubs, a hollow interior, a sagging rotten log with sloughed bark over soft wood, and a moss skin grown over the upper surfaces |
| stump | `stumpCut`, `stumpBroken`, `stumpMossy` | a flared stump with root buttresses: a ringed saw cut, a splintered crater, or a moss dome |
| rock | `boulder`, `mossyRock`, `streamStone`, `steppingStone` | noise-displaced, faceted, flat-bottomed stone with moss on top; a group of wet rounded cobbles; a flat-topped stepping slab |
| bush (2nd wave) | `elder`, `hawthorn`, `dogRose`, `bilberry` | elder: arching grey stems with opposite shoots, pinnate leaf sprays, flat cream umbels (spring, summer) and hanging black-purple berry clusters on red rays (autumn), bare in winter; hawthorn: a short trunk into a dense zig-zag rounded crown of small lobed leaves, white May blossom (spring), dark red haws (autumn, winter); dog rose: long arching green-red canes, small leaflets, pale pink flowers (summer), scarlet hips (autumn, winter); bilberry: a knee-high mound of green stems, small oval leaves, blue-black berries (summer, autumn) |
| grass (2nd wave) | `grassTussock` | tufted hair-grass: a dense fountain of fine arching blades with tall pale flowering stems; straw-coloured in winter |
| reed | `rushClump`, `bulrush` | soft rush: needle-thin upright dark green stems with brown side tufts, evergreen; bulrush: long strap leaves and tall stems with velvety brown sausage heads and a spike (water's edge) |
| flower (2nd wave) | `primrose`, `lesserCelandine`, `cowParsley` | primrose: rosettes of crinkled tongue leaves with pale yellow flowers (spring); lesser celandine: a low carpet of glossy round leaves with butter-yellow star flowers (spring); cow parsley: tall green stems, ferny base leaves and lacy white umbels |
| herb | `nettlePatch` | a stand of upright leafy nettle stems (three crossed cards each), spring to autumn, gone in winter |
| ivy | `ivyGround` (and `ivyStump`, a stump) | evergreen ivy leaf mats on brown runners across the ground; `ivyStump` is an old cut or broken stump with vines spiralling up the bark and leaf mats hugging it (a stump: collider, walks as `log`) |
| moss (2nd wave) | `mossCarpet`, `mossRoots` | feather-moss carpet: a wide thin undulating mat with an irregular edge, feathered with tiny golden-green fronds; a moss-covered root mound: a mossy hump with old roots running out and diving into the ground |
| fungus (2nd wave) | `honeyFungus`, `puffball` | a dense tuft of tawny ringed honey fungus; white pear-shaped puffballs sitting on a moss pad (both gone in winter) |
| litter | `branchLitter`, `twigPile`, `leafLitter` | scattered fallen sticks and forked twigs (four variants); a heaped pile of brash; drifts of fallen oak and beech leaves with a few twigs, brown all year (autumn colours in autumn) |
| log (2nd wave) | `fallenBranch`, `logSplit` | a fallen limb with side branches lying out and a snapped limb sticking up, mossy on top; a split half log, face up, often with its other half lying bark up beside it, sawn end-grain ends |
| stump (2nd wave) | `rootPlate`, `ivyStump` | an upturned root plate (torn soil face, roots and rootlets, leafy mossy top) with its sawn trunk stub lying away along +X |
| rock (2nd wave) | `pebblePatch` | wet rounded pebbles on a patch of stream-bed grit, for stream banks |
Seasons: ferns turn bronze in autumn; bracken and male fern lie collapsed and dead in winter (a baked winter form), hart's tongue stays green. Flowers bloom in spring and summer and return no parts in autumn and winter. Hazel and bramble yellow in autumn; hazel is bare in winter and bramble keeps a sparse set of leaves; holly is evergreen. Fly agaric and toadstools are absent in winter. Logs, stumps, rocks, moss and bracket fungi stay all year. Second wave: elder flowers in spring and summer and fruits in autumn, bare in winter; hawthorn blossoms in spring, carries haws in autumn and winter, bare in winter; dog rose flowers in summer, hips in autumn and winter, bare in winter; bilberry fruits in summer and autumn, bare green stems in winter; primrose and lesser celandine flower in spring only; nettles, honey fungus and puffballs are gone in winter; ivy, soft rush and the feather-moss fronds keep their summer green all year; leaf litter is dry brown all year and in autumn colours in autumn. Per-part rules live in `GroundCatalog.PART_SEASONS` (`GC.showsPart`) and evergreen material locks in `GC.materialSeason`.
No second-wave kind adds a texture: single flower heads and leaves are cropped out of the existing forestMaterials atlas cells with a card `uv` rect (`GroundFlora.CROP`: a wood anemone flower tinted pale yellow is the primrose, tinted pink the dog rose; a daisy head tinted butter-yellow is the celandine; the wild garlic umbel is the elder and cow parsley flower head), berries and hips are small balls on the wet stream-stone and fly-agaric surfaces, and tree leaf textures (maple for ivy, oak for hawthorn, birch for dog rose and bilberry) dress the new shrubs. Generators: `GroundFlora` (plants) and `GroundLitter` (litter, deadwood, pebbles), registered into `GroundGen.SPECS`.
Foliage cards carry vertex alpha 0 at the base rising to 1 at the tips (wind sway) and per-card tint in vertex RGB; solid parts carry alpha 1 (see Mesh contract). Logs, stumps, boulders and stones have colliders (logs and stumps walk as `log`, rocks as `stone`); plants have none. Budgets: ground cover LOD0 <= 600 triangles a clump, LOD1 <= 150, LOD2 empty (culled); bushes LOD0 <= 3000 with a card impostor at LOD2; logs, stumps and rocks LOD0 <= 3000, LOD1 <= 900, LOD2 <= 300.
```luau
local Props = require("~forestProps.Props")
-- a mossy log in autumn, painted look, second variant, near LOD
for _, part in Props.parts("logMossy", { season = "autumn", look = "painted", variant = 2, lod = 0 }) do
local e = entity.spawn("logPart")
e.component.add("Model", { model = part.mesh, material = part.material })
end
print(Props.info("steppingStone").collider.shape, Props.info("steppingStone").surface) --> box stone
```
Regenerating: change a generator in `GroundGen` / `GroundHard`, then run `require("~forestProps.GroundBake").run()` inside a task (or `.run({ kinds = { "boulder" } })`); it rewrites the meshes and `BakedGround`, the literal-resolve table the catalog reads. The `tests/groundProps.testSuite` checks every kind/season/look/variant/LOD resolves, the seasonal rules and the budgets.
## Mesh contract (every baked mesh)
- **Winding**: front faces are counter-clockwise. The bake's finishing pass (`Geo.orient`, run by `Geo.bake` and `GroundBake.finish`) swaps two indices of any triangle whose face normal `(b-a)x(c-a)` points against the sum of its three vertex normals, so no baked mesh draws inside out whatever order a generator emitted its triangles in.
- **Vertex colour RGB** is a tint the material multiplies its albedo by.
- **Vertex colour alpha** is the wind-sway weight on foliage cards only (tree `leaf` / `toon` parts, `TreeCatalog.FOLIAGE_PARTS`; ground parts whose surface is in `GroundCatalog.FOLIAGE`: ferns, grass, flowers and the bramble / hazel / holly leaf sprigs): 0 rigid at the base, 1 full sway at the tips. Every other part (tree bark and `barkw`, dead wood and soil, bush stems, logs, stumps, rocks, stones, moss cushions, fungi) is SOLID and baked with alpha 1 (`Geo.solid`), so a material that multiplies vertex alpha into surface alpha (the engine's `pbr`) draws it opaque. Trunks and stems do not sway.
- **Atlas UVs**: a ground part whose surface has an entry in forestMaterials' `ATLAS` table (ferns, shrub leaves, wildflowers, toadstool caps, bracket shelves) has its 0..1 card UVs remapped into that cell at bake time: `u' = (col + u) / cols`, `v' = (row + v) / rows`, row 0 the top row of the image.