forestKit.package
This package holds more than this page lists. See all of its files in its world.
README.md
forestKit: atmosphere and sound
Time of day, weather, the forest's look in the air, and its sound, all on worldClockKit's shared clock and soundstage. Every player sees the same hour and weather. Each machine draws the grade, haze and shafts, and plays the ambience around its own player.
Set it up (scene build.luau, inside content())
local Atmosphere = require("@root::forestKit.Atmosphere")
-- the shared clock: one per scene, on a synced entity (skip if the scene already has one),
-- lit with the forest's sky look and turning the engine's sky through the day
local clock = Atmosphere.ensureClock({
dayLengthMinutes = 24, startHour = 11, sky = Atmosphere.LOOK, skyMode = "engine",
})
-- light, air and sound for every machine; when the scene has no ProceduralSky of its
-- own, this also provides one (temporary, never saved) that greys over in rain
entity.spawn("ForestAtmosphere").component.add("forestKit.atmosphere.ForestAtmosphere", {})
-- footsteps: soundstage's Footsteps component on the player's body (or the PlayerPrototype)
-- e.g. require("forestKit.Footsteps").give(playerBody, "boot")
Change time and weather for everyone, from any script or the console:
local Atmosphere = require("forestKit.Atmosphere")
Atmosphere.setTime("dusk") -- "dawn" | "midday" | "dusk" | "night"
Atmosphere.setTime("midday", { hold = true }) -- and stop the clock there
Atmosphere.setWeather("rain") -- "clear" | "rain" (fades over 6 s; { fade = 0 } snaps)
print(Atmosphere.timeOfDay(), Atmosphere.weather(), Atmosphere.rainAmount())
Mark a walkable collider so steps on it sound right: entity.attribute.set("forestSurface", "log") (or "stone", or any forest surface). It counts for every child entity too.
ForestAtmosphere component
| field | default | what |
|---|---|---|
grade | true | colour grade per time and weather (one full-screen pass) |
haze | true | forest haze: height-fog density and colour per time, thicker at dawn and in rain |
shafts | true | sun shafts through the canopy (engine volumetric lighting, half-resolution march) |
shaftSteps | 16 | march samples per ray; lower is cheaper (12-32) |
bloom | false | soft bloom on sky and sunlit leaves (one extra multi-pass effect) |
ambience | true | forest ambience (below) |
ambienceVolume | 1 | 0-2 |
footsteps | true | forest surfaces for soundstage footsteps |
Atmosphere (forestKit.Atmosphere)
setTime(name, { hold }?),setWeather(name, { fade }?): shared, for every player (sent through worldClockKit's owner).timeOfDay()returns the nearest preset;weights()returns{ dawn, midday, dusk, night }(sums to 1, blends as the clock runs);weather();rainAmount()(0-1, fades included).PRESETS[name]holds{ solar, grade, haze, hazeTint, shafts };RAINholds the rain grade and haze. Edit these to retune.lookFor(weights, rain)(pure) andcurrent()give the blended look.report()says what this machine shows.configure{ grade, haze, shafts, bloom, look, shaftSteps, shaftShadowSteps };start(),stop(),tick(dt)(the component calls these).ensureClock(fields)spawns a syncedWorldClockwhen the scene has none (sky lookbeechwood), for a script running on the authority at play time. In a scene'sbuild.luau, spawn the clock yourself as in the setup above.SKYholds{ exposure, turbidity, rainExposure, rainTurbidity }for the engine sky the component provides when the scene has none; rain fades it toward the rain values.hourForSolar(solar)gives the clock hour of a solar hour today (sunrise = 6, sunset = 18).
What each preset looks like:
- dawn: low gold sun, gold mist (thickest haze), soft contrast.
- midday: warm high sun, sun shafts, green-pushed foliage, cool blue-green shade, light green haze.
- dusk: amber-rose sun low through the trunks, violet shade.
- night: cool blue moonlight, exposure lifted to stay readable, stars.
- rain: keeps the time's exposure, then greys and desaturates toward grey-green, thickens the haze, removes the shafts; worldClockKit adds falling rain, wet ground and the rain bed.
How it fits worldClockKit: the beechwood sky look (Sky.define) sets the sun, fill and fog colours the director lights the scene with. The forest haze goes into the director's own fog evaluation through a wrapper on Director.evaluate, so there is a single fog writer. The grade is the post-process effect forestKit.grade (atmosphere/forestGrade.shader). Shafts use @builtin::systems.volumetrics.volumetricLighting.
Ambience (forestKit.Ambience)
- Beds follow the time and weather: dawn chorus at dawn; soundstage's
forestbed by day; crickets at dusk and night; wind in the leaves always, more with wind and rain. worldClockKit adds the rain, wind and night beds. - The brook is a looping 3D source placed at the nearest point of the stream within 28 m. It reads
Ground.streamDistance, or a polyline fromAmbience.setStream({ {x, z}, ... }). - One-shot calls are placed in 3D around the listener:
- songbirds (blackbird, robin, wren, chaffinch, soundstage chirps), most at dawn;
- woodpecker drumming and wood pigeons by day;
- tawny owls at night;
- canopy gusts at any time.
- Rain quietens the birds. Tune the rates in
Ambience.SCHEDULE. start{ volume },stop(),tick(dt),levelsFor(weights, rain, wind)(pure),report(),logCalls(on)/log().- Each machine hears the forest around its own player, so random calls are not synced (by design).
Footsteps (forestKit.Footsteps)
- Surfaces:
leaves,moss,mud,path,loguse this package's recordings (3 takes × shoe/boot/barefoot);grass,stone,wateruse soundstage's. - The surface under each walker is decided per step, from where it stands, by a soundstage surface resolver (
soundstage.footsteps.setResolver, key"forestKit"). The first of these that answers wins:- a
forestSurfaceattribute on the hit collider or a parent ("ground"means: the forest ground at that point); - soundstage's marks (a
Surfacecomponent or asurfaceattribute); - a
ForestPropkind (log or stump →log, rock or stone →stone); - the forest ground: a collider under a
TerrainStreamtakesGround.surfaceAt(x, z), whatever its tiles are called; - a surface word in the entity's name, read up to the forest's root (the root's own name says nothing);
Ground.surfaceAt(x, z)anywhere inside the active forest;- outside a forest, soundstage's own reading of the floor, with
leavesas the default.
- a
- Other players' steps are heard at their position, on the surface under them. soundstage tracks every walker and this resolver serves them all.
tickputs the resolver back if soundstage reloads or is reset. install{ default }(idempotent),give(body, footwear, volume?),surfaceAt(x, z, entityId?),normalize(word),play{ surface, footwear, at },onStep(fn),logSteps(on)/log(),takes(surface, footwear).- Installing also re-teaches soundstage's word matcher: "moss", "leaf", "mud", "dirt" and "log" name the forest surfaces instead of grass, gravel and wood.
Cost
On desktop with a forest-free test area, the grade is under 0.05 ms of GPU per frame and the height fog about 0.07 ms. Sun shafts (vol_scatter, half resolution) were 0.75-3 ms at 14-16 steps and 1.3-4.3 ms at 28 steps; the medians were inflated by other work on the GPU. Play ran at 81 fps with everything on. For a browser at 30 fps, keep shaftSteps at 12-16, or turn shafts off on low-end machines. Audio is at most 5 beds, 1 spatial stream voice, and a call every few seconds through soundstage's 12-voice emitter pool.
Sounds
- soundstage: the
forestday bed, the songbird chirpsss_creatures_bird_1-3, footsteps ongrass,stoneandwater, and (through worldClockKit) therain,windandnightbeds. - Generated for this package (audio_gen, under
audio/):- 45 footstep takes (leaves, moss, mud, path, log × shoe, boot, barefoot × 3);
- beds: dawn chorus, leaves wind, brook, crickets;
- birds: blackbird, robin, wren, chaffinch, 2 woodpeckers, 2 wood pigeons;
- 3 tawny owls and 2 canopy gusts.
Tests: forestKit.package/tests/atmos.testSuite (tools.use("tests", "run", { suite = "atmos" })).