Log inGet started
Package

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

fielddefaultwhat
gradetruecolour grade per time and weather (one full-screen pass)
hazetrueforest haze: height-fog density and colour per time, thicker at dawn and in rain
shaftstruesun shafts through the canopy (engine volumetric lighting, half-resolution march)
shaftSteps16march samples per ray; lower is cheaper (12-32)
bloomfalsesoft bloom on sky and sunlit leaves (one extra multi-pass effect)
ambiencetrueforest ambience (below)
ambienceVolume10-2
footstepstrueforest 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 }; RAIN holds the rain grade and haze. Edit these to retune.
  • lookFor(weights, rain) (pure) and current() 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 synced WorldClock when the scene has none (sky look beechwood), for a script running on the authority at play time. In a scene's build.luau, spawn the clock yourself as in the setup above.
  • SKY holds { 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 forest bed 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 from Ambience.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, log use this package's recordings (3 takes × shoe/boot/barefoot); grass, stone, water use 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:
    1. a forestSurface attribute on the hit collider or a parent ("ground" means: the forest ground at that point);
    2. soundstage's marks (a Surface component or a surface attribute);
    3. a ForestProp kind (log or stump → log, rock or stone → stone);
    4. the forest ground: a collider under a TerrainStream takes Ground.surfaceAt(x, z), whatever its tiles are called;
    5. a surface word in the entity's name, read up to the forest's root (the root's own name says nothing);
    6. Ground.surfaceAt(x, z) anywhere inside the active forest;
    7. outside a forest, soundstage's own reading of the floor, with leaves as the default.
  • Other players' steps are heard at their position, on the surface under them. soundstage tracks every walker and this resolver serves them all. tick puts 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 forest day bed, the songbird chirps ss_creatures_bird_1-3, footsteps on grass, stone and water, and (through worldClockKit) the rain, wind and night beds.
  • 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" })).