environment.module
This package holds more than this page lists. See all of its files in its world.
README.md
environment.drawnSky
Keeps the sky the scene draws as the light the scene is lit and reflected by,
whatever draws it: a sky component, an ecs.Sky row content inserted itself, a
content sky shader, or the engine's fallback sky.
Purpose
The environment's sky slot is the fallback every surface reflects where no
reflection probe covers it, the sky light matte surfaces take, and the source
environment lighting (EnvironmentLighting) is built from. The follower looks
at the sky pass four times a second (renderer.reflectionEnvironment()): when
a sky is drawn and the slot holds no capture of it, it captures the sky into the
slot (environment.captureSky), which arms the sky fallback. From then on the
renderer retakes the slot itself as the sky changes. A capture waits while the
sky's material compiles, and the follower asks again after two seconds when no
capture has landed.
While a sky is drawn the follower holds a claim on the sky-visibility field
(@builtin::systems.skyVisibility.skyVisibility), so the sky lights only what
can see it, and releases the claim when no sky is drawn.
The scene loader starts the follower at the first root scene load, once the renderer is up, so a scene reflects and is lit by its sky with no call from content.
Usage
local drawnSky = require("modules.api.engine.environment.drawnSky")
-- Start following (idempotent; the scene loader already does this).
drawnSky.follow()
-- What the follower last saw and did.
local s = drawnSky.state()
print(s.material, s.captured, s.requests, s.claimed)
-- Retake the sky slot from scratch: the follower captures the sky again.
environment.releaseSky()
Exports
drawnSky.follow() -> boolean: start the follower for the life of this VM; true when this call started it, false when it was already runningdrawnSky.state() -> State: what the follower last saw and did
State fields:
following: boolean: whether the follower is runningmaterial: string?: the material the sky pass draws from at the last look, nil when no sky is drawncaptured: boolean: whether the sky slot held a capture at the last lookrequests: number: captures this follower has asked forclaimed: boolean: whether the sky-visibility claim is held