Log inGet started
Package

environment.module

Newest version

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 running
  • drawnSky.state() -> State: what the follower last saw and did

State fields:

  • following: boolean: whether the follower is running
  • material: string?: the material the sky pass draws from at the last look, nil when no sky is drawn
  • captured: boolean: whether the sky slot held a capture at the last look
  • requests: number: captures this follower has asked for
  • claimed: boolean: whether the sky-visibility claim is held