systemSettings

Which of several components stating one scene-wide system's settings is in force. A scene-wide system (screen-space reflections, ambient occlusion, depth of field, fog, exposure, environment lighting, weather, ...) runs under one set of settings, and more than one component instance can state them at once: two hosts in one scene, an instance and the one replacing it while a script reloads, or the instances a scene module's builder makes while it records a rebuild beside the ones its last build placed.

Each component instance takes a claim on the system and states its settings through it every frame:

local Ssr = require("@builtin::systems.reflections.ssr")
local systemSettings = require("@builtin::modules.systemSettings")

local claim = systemSettings.claim("@builtin::systems.reflections.ssr", {
    push = Ssr.set,       -- puts the settings in force
    release = Ssr.clear,  -- takes the system down
    live = Ssr.active,    -- whether the system is up
})

function update(_dt)
    claim:state(signatureOf(opts()), opts())
end

function onDestroy()
    claim:release()
end

What is in force

The claims on one system are kept in the order they last stated something new, and the newest is in force.

• A claim whose settings changed moves to the newest place and pushes them: the last component edited wins.
• A claim that joins stating exactly what is in force takes the newest place and pushes nothing.
• Releasing a claim while others are live hands the system to the newest of them, which pushes its own settings when they differ. Only the last claim released takes the system down.
• The claim in force pushes again when the system it brought up is no longer up (a script's clear(), a feature torn down from outside), so a component standing in the scene keeps its system running. A push that left the system down, such as a setting that turns it off, is not repeated.

Exports

• systemSettings.claim(key, spec) -> Claim: a claim on the system named key (the path of the module that drives it). spec.push(opts) puts settings in force, spec.release() takes the system down, and the optional spec.live() says whether it is up.
• claim:state(sig, opts): state the settings for this frame. sig is a string that differs whenever opts does.
• claim:release(): let the system go, from onDestroy.
• claim:inForce() -> boolean: whether this claim's settings are in force.
• systemSettings.count(key) -> number: how many live claims state the system.