Beechwood Brook: A Temperate Forest to Walk, with Trees, Undergrowth and a Forest Builder
README.md
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
-- 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.
qualityscales 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.webQualityin the build options changes that cap. Compareforest.stats.fingerprinton 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
normaldensity) 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.testSuitechecks 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.fingerprintis the same short code on every machine that stands the same forest (the showcase:8069-2792b58a). - Same time and weather: worldClockKit's
WorldClockis 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).