@pascal-app/viewer 1.0.4 → 1.0.5

package/dist/lib/underground-ambiance.d.ts

@@ -0,0 +1,168 @@
+import type { AmbientLight, DirectionalLight, HemisphereLight } from 'three';
+import type { GroundMode } from '../store/use-viewer';
+/**
+ * Diving under the ground is the scene's own dark mode, as going under water is in a game: the
+ * moment the eye crosses the ground surface the backdrop, the far site, the screen's edges and
+ * the sky's light go to the dark theme's slate, and crossing back up brings the day back. Above
+ * the ground nothing changes, whatever level is shown (a veiled basement seen from above is the
+ * veil as it was). The shown level is not touched: its materials keep their colours and the
+ * eye's own light keeps its rooms as readable as ever. Dark around, not dark inside.
+ *
+ * One factor drives all of it: `0` is the world as it is, `1` is the dark mode. The factor eases
+ * between the two over {@link AMBIANCE_SECONDS}, never pops, and is instant when the person's
+ * animation setting is Off. It lives here as a shader uniform (the pipeline and the veil read
+ * it with no rebuild); the store keeps only whether it is above 0 (`ambianceActive`).
+ */
+/** How long the crossing takes, in and out. */
+export declare const AMBIANCE_SECONDS = 0.7;
+/** The simple fade's crossing (`UndergroundTransition` `fade`), in and out. */
+export declare const FADE_SECONDS = 0.4;
+/** The thin rim along the cut of the hole in the ground, from above. */
+export declare const UNDERGROUND_RIM: "#3c3c3c";
+/** The grade ring, where the ground meets the level below grade: a light rim in the dark mode. */
+export declare const UNDERGROUND_RING: "#b4b4b4";
+/** The corners the vignette closes in to. */
+export declare const UNDERGROUND_VIGNETTE: "#0c0c0c";
+/** The sky's ambient and hemisphere light, as a share of what the theme gives. */
+export declare const SKY_LIGHT_SCALE = 0.65;
+/**
+ * The eye's own light at full ambiance: the veil's own fill (1) and as much again as the sky's
+ * comes down, so the rooms keep their light. It rides the factor, from the veil's own fill (or
+ * from nothing where no veil stands), so it neither steps on nor off.
+ */
+export declare const EYE_FILL_INTENSITY = 2.4;
+/** The sky light's tint pulls this much toward the palette's neutral light grey. */
+export declare const SKY_LIGHT_TINT = 0.15;
+/** Fog begins this far past the shown level's box and has taken the site by the second. */
+export declare const FOG_START = 3;
+export declare const FOG_END = 24;
+/** The screen's corners darken by this much at most. */
+export declare const VIGNETTE_STRENGTH = 0.42;
+/**
+ * How far the eye goes under (or back over) the ground before the flag turns, in metres: it dives
+ * 0.10 m below the ground and surfaces 0.10 m above it, a 0.20 m band in all, so an orbit
+ * grazing the surface does not flicker.
+ */
+export declare const EYE_BAND = 0.1;
+/**
+ * Whether the world beyond the walls is the earth's: only the eye under the ground, and never on
+ * Solid (the person's own override). What level is shown, or whether the ground is veiled, is not
+ * in it. The backdrop and, outside the walkthrough, the whole dark mode follow this edge.
+ */
+export declare function earthTarget(state: {
+    eyeUnderGround: boolean;
+    groundMode: GroundMode;
+}): 0 | 1;
+/**
+ * The edge the dark mode (fog, vignette, the sky's light and the eye's own) is wanted by: the
+ * earth's edge, except in the walkthrough, where the rooms keep their normal light as the person
+ * walks down a stair, and only what is seen outside (the backdrop) turns to earth.
+ */
+export declare function ambianceTarget(state: {
+    eyeUnderGround: boolean;
+    groundMode: GroundMode;
+    walkthroughMode?: boolean;
+}): 0 | 1;
+/**
+ * Whether the eye lies under the ground, with a small band so a camera resting on the ground
+ * plane does not chatter: it goes under {@link EYE_BAND} below the ground and comes back
+ * {@link EYE_BAND} above it.
+ */
+export declare function eyeUnderTheGround(previous: boolean, eyeY: number, groundY: number): boolean;
+/**
+ * One step of the crossing: `progress` moves toward `target` (0 or 1) in a straight line over
+ * `seconds`, and is exactly the target once it has arrived. `seconds <= 0` is instant.
+ */
+export declare function stepAmbianceProgress(progress: number, target: number, dt: number, seconds: number): number;
+/** The eased factor of a straight-line progress: slow in, slow out. */
+export declare function easeAmbiance(progress: number): number;
+/** The factor as shaders read it: zero while a capture holds the ambiance off. */
+export declare function undergroundAmbianceNode(): import("three/webgpu").UniformNode<"float", number>;
+/** How far the backdrop is the earth's, as shaders read it: zero while a capture holds the ambiance off. */
+export declare function undergroundEarthNode(): import("three/webgpu").UniformNode<"float", number>;
+/** How far the ground's hole is open, as shaders read it: 0 while a capture holds the world plain. */
+export declare function groundHoleOpenNode(): import("three/webgpu").UniformNode<"float", number>;
+/** How far the ground's hole is open now (0 while a capture holds the world plain). */
+export declare function groundHoleOpenNow(): number;
+/** Sets how much the crossing is the noise mask (1) rather than a uniform fade (0); the system's word. */
+export declare function setDiveGrainWeight(next: number): void;
+/** Sets the live opening of the ground's hole (the system's word). */
+export declare function setGroundHoleOpen(next: number): void;
+/** The factor the shown frame wears now: the eased value, or `0` while a capture holds it off. */
+export declare function ambianceNow(): number;
+/** How far the backdrop is the earth's now: the eased value, or `0` while a capture holds it off. */
+export declare function earthNow(): number;
+/** Sets the live factor (the system's word); shaders and lights follow the held value. */
+export declare function setAmbianceFactor(next: number): void;
+/** Sets the live earth factor of the backdrop (the system's word). */
+export declare function setEarthFactor(next: number): void;
+/**
+ * The shown frame without the ambiance, for one capture: an agent's picture of a level below
+ * grade is read for its rooms, so it is taken in the world's own light, and the person's hole in
+ * the ground is not in it (a capture sets its own ground: the plain veil over a level below
+ * grade, solid for an exterior). The returned function gives the person's view back.
+ */
+export declare function temporarilyWithoutAmbiance(): () => void;
+/** The box the fog keeps clear: the shown level's, or a cube about the eye when none is shown. */
+export declare function setAmbianceFocus(box: {
+    min: readonly number[];
+    max: readonly number[];
+} | null, eye: {
+    x: number;
+    y: number;
+    z: number;
+}): void;
+/** The box the fog keeps clear now (what {@link setAmbianceFocus} last set). */
+export declare function ambianceFocus(): {
+    min: number[];
+    max: number[];
+};
+/**
+ * The dark mode's backdrop for a view direction: the theme backdrop's own gradient, in the dark
+ * theme's colours. The fog dissolves into this same colour per pixel, so what is far leaves no seam.
+ */
+export declare function undergroundBackdrop(dirY: any): any;
+/**
+ * How far a world position stands in the dark mode's fog, 0 to 1, from its distance outside the
+ * shown box (the box itself, and what stands close about it, stays clear). Not scaled by the
+ * factor: the pipeline weighs it with {@link undergroundDissolve}.
+ */
+export declare function undergroundFogAmount(worldPosition: any): any;
+/**
+ * The noise the crossing's mask is cut from: two screen-space perlin octaves, 0 to 1. Computed once
+ * a pixel and handed to every {@link undergroundDissolve} that needs it.
+ */
+export declare function undergroundDissolveGrain(uv?: any): any;
+/**
+ * The crossing as a noise mask closing over the screen: a per-pixel weight, 0 to 1, that goes
+ * from 0 everywhere at `amount` 0 (the factor, by default) to 1 everywhere at 1, through soft
+ * blobs of the dark world spreading (a fine perlin mask in screen space, not a cross-fade). Weighs
+ * the backdrop, the fog and the vignette; above and below the crossing it is exactly 0 and 1.
+ * With the simple fade chosen (`grainWeightNode` 0) it is `amount` itself, the same everywhere.
+ */
+export declare function undergroundDissolve(uv?: any, amount?: any, grain?: any): any;
+/** The world position of the pixel at `uv` from the scene pass's raw depth. */
+export declare function worldPositionFromDepth(rawDepth: any, projectionInverse: any, cameraWorld: any, uv?: any): any;
+/** The screen's edges closing in: 0 at the centre, 1 at the corners (weigh it with the dissolve). */
+export declare function undergroundVignette(uv?: any): any;
+type SkyLights = {
+    ambient: AmbientLight | null;
+    hemisphere: HemisphereLight | null;
+    /** The light from the eye (`UndergroundFill`), when it is mounted. */
+    fill: DirectionalLight | null;
+    /** What the fill shines at with no ambiance: the veil's own 1 over a veiled ground, else 0. */
+    fillRest: number;
+};
+/** The lights the ambiance moves: `Lights` offers the sky's ambient and hemisphere and the eye's fill. */
+export declare function registerSkyLights(source: () => SkyLights): () => void;
+/**
+ * Brings the sky's lights down and tints them by `amount`, and brings the eye's fill up, for the
+ * frame about to be drawn. Their neutral state is kept and given back by
+ * {@link restoreSkyLights} before the next frame lerps them, so the theme's own smoothing never
+ * fights the ambiance. With no ambiance (or none registered) the fill is simply set to its rest.
+ */
+export declare function applyAmbianceToSkyLights(amount: number): void;
+/** Gives the sky's lights back as the theme set them, and the eye's fill its rest. */
+export declare function restoreSkyLights(): void;
+export {};
+//# sourceMappingURL=underground-ambiance.d.ts.map

package/dist/lib/underground-ambiance.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"underground-ambiance.d.ts","sourceRoot":"","sources":["../../src/lib/underground-ambiance.ts"],"names":[],"mappings":"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"}

package/dist/lib/underground-ambiance.js

@@ -0,0 +1,334 @@
+import { Color, Vector3 } from 'three';
+import { abs, clamp, color, float, getViewPosition, max, mix, mx_noise_float, screenUV, smoothstep, uniform, vec2, vec3, vec4, } from 'three/tsl';
+import { backdropGradient } from './backdrop';
+import { UNDERGROUND_PALETTE } from './scene-themes';
+/**
+ * Diving under the ground is the scene's own dark mode, as going under water is in a game: the
+ * moment the eye crosses the ground surface the backdrop, the far site, the screen's edges and
+ * the sky's light go to the dark theme's slate, and crossing back up brings the day back. Above
+ * the ground nothing changes, whatever level is shown (a veiled basement seen from above is the
+ * veil as it was). The shown level is not touched: its materials keep their colours and the
+ * eye's own light keeps its rooms as readable as ever. Dark around, not dark inside.
+ *
+ * One factor drives all of it: `0` is the world as it is, `1` is the dark mode. The factor eases
+ * between the two over {@link AMBIANCE_SECONDS}, never pops, and is instant when the person's
+ * animation setting is Off. It lives here as a shader uniform (the pipeline and the veil read
+ * it with no rebuild); the store keeps only whether it is above 0 (`ambianceActive`).
+ */
+/** How long the crossing takes, in and out. */
+export const AMBIANCE_SECONDS = 0.7;
+/** The simple fade's crossing (`UndergroundTransition` `fade`), in and out. */
+export const FADE_SECONDS = 0.4;
+/**
+ * The dark mode's palette is one place, beside the scene theme tokens
+ * (`UNDERGROUND_PALETTE` in `lib/scene-themes.ts`): neutral anthracite, no blue cast. The backdrop
+ * is the theme backdrop's own gradient (`lib/backdrop.ts`) in its stops.
+ */
+const BACKDROP = {
+    background: UNDERGROUND_PALETTE.background,
+    haze: UNDERGROUND_PALETTE.haze,
+    sky: UNDERGROUND_PALETTE.sky,
+    skyDeep: UNDERGROUND_PALETTE.skyDeep,
+};
+/** The thin rim along the cut of the hole in the ground, from above. */
+export const UNDERGROUND_RIM = UNDERGROUND_PALETTE.rim;
+/** The grade ring, where the ground meets the level below grade: a light rim in the dark mode. */
+export const UNDERGROUND_RING = UNDERGROUND_PALETTE.ring;
+/** The corners the vignette closes in to. */
+export const UNDERGROUND_VIGNETTE = UNDERGROUND_PALETTE.vignette;
+/** The sky's ambient and hemisphere light, as a share of what the theme gives. */
+export const SKY_LIGHT_SCALE = 0.65;
+/**
+ * The eye's own light at full ambiance: the veil's own fill (1) and as much again as the sky's
+ * comes down, so the rooms keep their light. It rides the factor, from the veil's own fill (or
+ * from nothing where no veil stands), so it neither steps on nor off.
+ */
+export const EYE_FILL_INTENSITY = 2.4;
+/** The sky light's tint pulls this much toward the palette's neutral light grey. */
+export const SKY_LIGHT_TINT = 0.15;
+const TINT = UNDERGROUND_PALETTE.tint;
+/** Fog begins this far past the shown level's box and has taken the site by the second. */
+export const FOG_START = 3;
+export const FOG_END = 24;
+/** What remains of the far site when the fog is complete. */
+const FOG_CAP = 0.97;
+/** The screen's corners darken by this much at most. */
+export const VIGNETTE_STRENGTH = 0.42;
+/**
+ * How far the eye goes under (or back over) the ground before the flag turns, in metres: it dives
+ * 0.10 m below the ground and surfaces 0.10 m above it, a 0.20 m band in all, so an orbit
+ * grazing the surface does not flicker.
+ */
+export const EYE_BAND = 0.1;
+/**
+ * Whether the world beyond the walls is the earth's: only the eye under the ground, and never on
+ * Solid (the person's own override). What level is shown, or whether the ground is veiled, is not
+ * in it. The backdrop and, outside the walkthrough, the whole dark mode follow this edge.
+ */
+export function earthTarget(state) {
+    if (state.groundMode !== 'auto')
+        return 0;
+    return state.eyeUnderGround ? 1 : 0;
+}
+/**
+ * The edge the dark mode (fog, vignette, the sky's light and the eye's own) is wanted by: the
+ * earth's edge, except in the walkthrough, where the rooms keep their normal light as the person
+ * walks down a stair, and only what is seen outside (the backdrop) turns to earth.
+ */
+export function ambianceTarget(state) {
+    return state.walkthroughMode === true ? 0 : earthTarget(state);
+}
+/**
+ * Whether the eye lies under the ground, with a small band so a camera resting on the ground
+ * plane does not chatter: it goes under {@link EYE_BAND} below the ground and comes back
+ * {@link EYE_BAND} above it.
+ */
+export function eyeUnderTheGround(previous, eyeY, groundY) {
+    return previous ? eyeY < groundY + EYE_BAND : eyeY < groundY - EYE_BAND;
+}
+/**
+ * One step of the crossing: `progress` moves toward `target` (0 or 1) in a straight line over
+ * `seconds`, and is exactly the target once it has arrived. `seconds <= 0` is instant.
+ */
+export function stepAmbianceProgress(progress, target, dt, seconds) {
+    if (seconds <= 0 || dt >= seconds)
+        return target;
+    const step = dt / seconds;
+    return target > progress ? Math.min(target, progress + step) : Math.max(target, progress - step);
+}
+/** The eased factor of a straight-line progress: slow in, slow out. */
+export function easeAmbiance(progress) {
+    const p = Math.min(1, Math.max(0, progress));
+    return p * p * (3 - 2 * p);
+}
+// ── The shared factor ────────────────────────────────────────────────────────────────────────
+const factorNode = uniform(0);
+/**
+ * How far what is seen beyond the walls (the sky) has turned to earth, 0 to 1. The same as the
+ * factor in the overview; in the walkthrough the factor stays 0 (no fog, no vignette, the rooms'
+ * own light) and this one alone follows the eye under the ground.
+ */
+const earthNode = uniform(0);
+/**
+ * How far the hole in the ground is open (0 closed, 1 open): over a level below grade seen from
+ * above, the ground stays solid and a hole with a noise-eroded edge opens over the below-grade
+ * footprint. Eased like the factor; 0 in a capture, whose own ground it keeps (see
+ * {@link temporarilyWithoutAmbiance}).
+ */
+const holeNode = uniform(0);
+/**
+ * How much of the crossing is the noise mask: 1 the blobs of the dark world spreading, 0 the whole
+ * frame fading at once (`UndergroundTransition`). A uniform, so the two share one pipeline.
+ */
+const grainWeightNode = uniform(1);
+let hole = 0;
+let factor = 0;
+let earth = 0;
+let held = false;
+/** The factor as shaders read it: zero while a capture holds the ambiance off. */
+export function undergroundAmbianceNode() {
+    return factorNode;
+}
+/** How far the backdrop is the earth's, as shaders read it: zero while a capture holds the ambiance off. */
+export function undergroundEarthNode() {
+    return earthNode;
+}
+/** How far the ground's hole is open, as shaders read it: 0 while a capture holds the world plain. */
+export function groundHoleOpenNode() {
+    return holeNode;
+}
+/** How far the ground's hole is open now (0 while a capture holds the world plain). */
+export function groundHoleOpenNow() {
+    return holeNode.value;
+}
+/** Sets how much the crossing is the noise mask (1) rather than a uniform fade (0); the system's word. */
+export function setDiveGrainWeight(next) {
+    grainWeightNode.value = next;
+}
+/** Sets the live opening of the ground's hole (the system's word). */
+export function setGroundHoleOpen(next) {
+    hole = next;
+    holeNode.value = held ? 0 : next;
+}
+/** The factor the shown frame wears now: the eased value, or `0` while a capture holds it off. */
+export function ambianceNow() {
+    return held ? 0 : factor;
+}
+/** How far the backdrop is the earth's now: the eased value, or `0` while a capture holds it off. */
+export function earthNow() {
+    return held ? 0 : earth;
+}
+/** Sets the live factor (the system's word); shaders and lights follow the held value. */
+export function setAmbianceFactor(next) {
+    factor = next;
+    factorNode.value = held ? 0 : next;
+}
+/** Sets the live earth factor of the backdrop (the system's word). */
+export function setEarthFactor(next) {
+    earth = next;
+    earthNode.value = held ? 0 : next;
+}
+/**
+ * The shown frame without the ambiance, for one capture: an agent's picture of a level below
+ * grade is read for its rooms, so it is taken in the world's own light, and the person's hole in
+ * the ground is not in it (a capture sets its own ground: the plain veil over a level below
+ * grade, solid for an exterior). The returned function gives the person's view back.
+ */
+export function temporarilyWithoutAmbiance() {
+    const wasHeld = held;
+    held = true;
+    factorNode.value = 0;
+    earthNode.value = 0;
+    holeNode.value = 0;
+    restoreSkyLights();
+    return () => {
+        held = wasHeld;
+        factorNode.value = held ? 0 : factor;
+        earthNode.value = held ? 0 : earth;
+        holeNode.value = held ? 0 : hole;
+    };
+}
+// ── The shown level's box: where the world stays clear ──────────────────────────────────────
+const focusMin = uniform(new Vector3(-20, -20, -20));
+const focusMax = uniform(new Vector3(20, 20, 20));
+/** The box the fog keeps clear: the shown level's, or a cube about the eye when none is shown. */
+export function setAmbianceFocus(box, eye) {
+    if (box) {
+        focusMin.value.set(box.min[0], box.min[1], box.min[2]);
+        focusMax.value.set(box.max[0], box.max[1], box.max[2]);
+        return;
+    }
+    const half = 20;
+    focusMin.value.set(eye.x - half, eye.y - half, eye.z - half);
+    focusMax.value.set(eye.x + half, eye.y + half, eye.z + half);
+}
+/** The box the fog keeps clear now (what {@link setAmbianceFocus} last set). */
+export function ambianceFocus() {
+    return { min: focusMin.value.toArray(), max: focusMax.value.toArray() };
+}
+// ── The pipeline's pieces (TSL) ──────────────────────────────────────────────────────────────
+/**
+ * The dark mode's backdrop for a view direction: the theme backdrop's own gradient, in the dark
+ * theme's colours. The fog dissolves into this same colour per pixel, so what is far leaves no seam.
+ */
+export function undergroundBackdrop(dirY) {
+    return backdropGradient({
+        dirY,
+        background: color(BACKDROP.background),
+        haze: color(BACKDROP.haze),
+        sky: color(BACKDROP.sky),
+        skyDeep: color(BACKDROP.skyDeep),
+    });
+}
+/**
+ * How far a world position stands in the dark mode's fog, 0 to 1, from its distance outside the
+ * shown box (the box itself, and what stands close about it, stays clear). Not scaled by the
+ * factor: the pipeline weighs it with {@link undergroundDissolve}.
+ */
+export function undergroundFogAmount(worldPosition) {
+    const centre = focusMin.add(focusMax).mul(0.5);
+    const half = focusMax.sub(focusMin).mul(0.5);
+    const outside = max(abs(worldPosition.sub(centre)).sub(half), vec3(0)).length();
+    return smoothstep(float(FOG_START), float(FOG_END), outside).mul(FOG_CAP);
+}
+/**
+ * The noise the crossing's mask is cut from: two screen-space perlin octaves, 0 to 1. Computed once
+ * a pixel and handed to every {@link undergroundDissolve} that needs it.
+ */
+export function undergroundDissolveGrain(uv = screenUV) {
+    // Perlin is centred on 0 with a short spread: stretch it so the mask covers 0..1.
+    const grain = mx_noise_float(vec3(uv.mul(vec2(9, 5.8)), 0.37))
+        .mul(0.62)
+        .add(mx_noise_float(vec3(uv.mul(vec2(21, 13.5)), 1.91)).mul(0.22));
+    return clamp(grain.add(0.5), 0, 1);
+}
+/**
+ * The crossing as a noise mask closing over the screen: a per-pixel weight, 0 to 1, that goes
+ * from 0 everywhere at `amount` 0 (the factor, by default) to 1 everywhere at 1, through soft
+ * blobs of the dark world spreading (a fine perlin mask in screen space, not a cross-fade). Weighs
+ * the backdrop, the fog and the vignette; above and below the crossing it is exactly 0 and 1.
+ * With the simple fade chosen (`grainWeightNode` 0) it is `amount` itself, the same everywhere.
+ */
+export function undergroundDissolve(uv = screenUV, amount = factorNode, grain = undergroundDissolveGrain(uv)) {
+    const softness = 0.32;
+    const t = amount.mul(1 + 2 * softness).sub(softness);
+    return mix(amount, smoothstep(grain.sub(softness), grain.add(softness), t), grainWeightNode);
+}
+/** The world position of the pixel at `uv` from the scene pass's raw depth. */
+export function worldPositionFromDepth(rawDepth, projectionInverse, cameraWorld, uv = screenUV) {
+    const viewPosition = getViewPosition(uv, rawDepth, projectionInverse);
+    return cameraWorld.mul(vec4(viewPosition, 1)).xyz;
+}
+/** The screen's edges closing in: 0 at the centre, 1 at the corners (weigh it with the dissolve). */
+export function undergroundVignette(uv = screenUV) {
+    const radial = uv.sub(0.5).length().mul(2);
+    return smoothstep(float(0.55), float(1.45), radial).mul(VIGNETTE_STRENGTH);
+}
+let skyLightSource = null;
+let saved = null;
+const tint = new Color(TINT);
+/** The lights the ambiance moves: `Lights` offers the sky's ambient and hemisphere and the eye's fill. */
+export function registerSkyLights(source) {
+    skyLightSource = source;
+    return () => {
+        if (skyLightSource === source) {
+            restoreSkyLights();
+            skyLightSource = null;
+        }
+    };
+}
+/**
+ * Brings the sky's lights down and tints them by `amount`, and brings the eye's fill up, for the
+ * frame about to be drawn. Their neutral state is kept and given back by
+ * {@link restoreSkyLights} before the next frame lerps them, so the theme's own smoothing never
+ * fights the ambiance. With no ambiance (or none registered) the fill is simply set to its rest.
+ */
+export function applyAmbianceToSkyLights(amount) {
+    restoreSkyLights();
+    if (!skyLightSource)
+        return;
+    const { ambient, hemisphere, fill, fillRest } = skyLightSource();
+    saved = { fill: null, ambient: null, hemisphere: null };
+    if (fill) {
+        saved.fill = { light: fill, intensity: fillRest };
+        fill.intensity = fillRest + (EYE_FILL_INTENSITY - fillRest) * Math.max(0, amount);
+    }
+    if (amount <= 0)
+        return;
+    const scale = 1 + (SKY_LIGHT_SCALE - 1) * amount;
+    const warmth = SKY_LIGHT_TINT * amount;
+    if (ambient) {
+        saved.ambient = { light: ambient, intensity: ambient.intensity, color: ambient.color.clone() };
+        ambient.intensity *= scale;
+        ambient.color.lerp(tint, warmth);
+    }
+    if (hemisphere) {
+        saved.hemisphere = {
+            light: hemisphere,
+            intensity: hemisphere.intensity,
+            color: hemisphere.color.clone(),
+            groundColor: hemisphere.groundColor.clone(),
+        };
+        hemisphere.intensity *= scale;
+        hemisphere.color.lerp(tint, warmth);
+        hemisphere.groundColor.lerp(tint, warmth);
+    }
+}
+/** Gives the sky's lights back as the theme set them, and the eye's fill its rest. */
+export function restoreSkyLights() {
+    if (!saved)
+        return;
+    const { fill, ambient, hemisphere } = saved;
+    saved = null;
+    if (fill)
+        fill.light.intensity = fill.intensity;
+    if (ambient) {
+        ambient.light.intensity = ambient.intensity;
+        ambient.light.color.copy(ambient.color);
+    }
+    if (hemisphere) {
+        hemisphere.light.intensity = hemisphere.intensity;
+        hemisphere.light.color.copy(hemisphere.color);
+        hemisphere.light.groundColor.copy(hemisphere.groundColor);
+    }
+}