@jgengine/core 0.24.0 → 0.26.0

package/dist/render/lightProbes.js

@@ -0,0 +1,221 @@
+import { hexToRgb, mixHex } from "./color.js";
+/**
+ * Baked irradiance volume: a grid of second-order (9-coefficient, RGB) spherical-harmonic probes
+ * over a box region, sampled at runtime for ambient lighting. It is the datum an interior has that
+ * a hemisphere light cannot: a room's fill is its own, not the sky's, and it varies across the space.
+ *
+ * Serializable and pure; the bake is deterministic heuristics (sky visibility, authored lamps and
+ * bounce colours), not a path tracer.
+ */
+/** SH coefficients per channel for the second band — 3 bands, real basis. */
+export const SH_COEFFICIENTS = 9;
+/** Floats stored per probe: {@link SH_COEFFICIENTS} × RGB. */
+export const PROBE_STRIDE = SH_COEFFICIENTS * 3;
+const SH_BAND_0 = 0.282095;
+const SH_BAND_1 = 0.488603;
+const SH_BAND_2_0 = 1.092548;
+const SH_BAND_2_1 = 0.315392;
+const SH_BAND_2_2 = 0.546274;
+/**
+ * Real-basis SH values for a unit direction, into `out` (length 9):
+ * `[Y00, Y1-1, Y10, Y11, Y2-2, Y2-1, Y20, Y21, Y22]`.
+ * @internal
+ */
+export function shDirection(x, y, z, out) {
+    out[0] = SH_BAND_0;
+    out[1] = SH_BAND_1 * y;
+    out[2] = SH_BAND_1 * z;
+    out[3] = SH_BAND_1 * x;
+    out[4] = SH_BAND_2_0 * x * y;
+    out[5] = SH_BAND_2_0 * y * z;
+    out[6] = SH_BAND_2_1 * (3 * z * z - 1);
+    out[7] = SH_BAND_2_0 * x * z;
+    out[8] = SH_BAND_2_2 * (x * x - y * y);
+}
+/** Fibonacci sphere direction `index` of `count`, in the renderer's Y-up frame. */
+function sphereDirection(index, count) {
+    const y = 1 - (2 * (index + 0.5)) / count;
+    const radius = Math.sqrt(Math.max(0, 1 - y * y));
+    const theta = index * 2.399963229728653;
+    return [Math.cos(theta) * radius, y, Math.sin(theta) * radius];
+}
+function scaledRgb(color, scale) {
+    const [r, g, b] = hexToRgb(color);
+    return [(r / 255) * scale, (g / 255) * scale, (b / 255) * scale];
+}
+/** World-space position of probe `(ix, iy, iz)`; the outer probes sit on the box faces.
+ * @internal
+ */
+export function probePosition(volume, ix, iy, iz) {
+    const [nx, ny, nz] = volume.resolution;
+    const t = (index, count) => (count <= 1 ? 0.5 : index / (count - 1));
+    return [
+        volume.center[0] + (t(ix, nx) - 0.5) * volume.size[0],
+        volume.center[1] + (t(iy, ny) - 0.5) * volume.size[1],
+        volume.center[2] + (t(iz, nz) - 0.5) * volume.size[2],
+    ];
+}
+/**
+ * Bakes an irradiance volume from authored inputs: sky radiance where the region is open, an
+ * authored ceiling/floor fill where it is enclosed, plus inverse-square lamp radiance. Each probe
+ * projects its directional radiance into L2 SH, so ambient varies across the grid and keeps a lit
+ * side instead of flattening to one number.
+ * @capability light-probes bake an irradiance volume from authored sky, fill and lamp inputs
+ */
+export function bakeIrradianceVolume(input) {
+    const { settings } = input;
+    const count = Math.max(8, Math.min(256, Math.floor(input.samples ?? 64)));
+    const [nx, ny, nz] = input.resolution.map((value) => Math.max(1, Math.floor(value)));
+    const visibility = Math.max(0, Math.min(1, settings.skyVisibility));
+    const fill = Math.max(0, settings.fillIntensity ?? 1);
+    const sky = settings.skyColor ?? "#9ec4e8";
+    const ground = settings.groundColor ?? "#4c4a42";
+    const ceiling = settings.ceilingColor ?? "#8d8a80";
+    const floor = settings.floorColor ?? "#4a4438";
+    const lamps = settings.lights ?? [];
+    const samples = new Array(PROBE_STRIDE * nx * ny * nz).fill(0);
+    const basis = new Float64Array(SH_COEFFICIENTS);
+    const accum = new Float64Array(PROBE_STRIDE);
+    for (let iz = 0; iz < nz; iz += 1) {
+        for (let iy = 0; iy < ny; iy += 1) {
+            for (let ix = 0; ix < nx; ix += 1) {
+                const position = probePosition({ center: input.center, size: input.size, resolution: [nx, ny, nz] }, ix, iy, iz);
+                accum.fill(0);
+                for (let s = 0; s < count; s += 1) {
+                    const [dx, dy, dz] = sphereDirection(s, count);
+                    shDirection(dx, dy, dz, basis);
+                    const radiance = radianceIn(position, dx, dy, dz, { visibility, fill, sky, ground, ceiling, floor, lamps });
+                    for (let band = 0; band < SH_COEFFICIENTS; band += 1) {
+                        const weighted = basis[band] * (4 * Math.PI) / count;
+                        accum[band * 3] += radiance[0] * weighted;
+                        accum[band * 3 + 1] += radiance[1] * weighted;
+                        accum[band * 3 + 2] += radiance[2] * weighted;
+                    }
+                }
+                const offset = ((iz * ny + iy) * nx + ix) * PROBE_STRIDE;
+                for (let index = 0; index < PROBE_STRIDE; index += 1)
+                    samples[offset + index] = accum[index];
+            }
+        }
+    }
+    return { id: input.id, center: [...input.center], size: [...input.size], resolution: [nx, ny, nz], samples };
+}
+function radianceIn(position, dx, dy, dz, inputs) {
+    const open = inputs.visibility;
+    const enclosed = 1 - inputs.visibility;
+    let color;
+    let scale;
+    if (dy >= 0) {
+        // Above the horizon an open probe sees sky; an enclosed one sees its own ceiling.
+        color = mixHex(inputs.ceiling, inputs.sky, open);
+        scale = 0.55 + 0.45 * dy;
+    }
+    else {
+        // Below the horizon: ground bounce outside, floor bounce inside.
+        color = mixHex(inputs.floor, inputs.ground, open);
+        scale = 0.55 + 0.45 * -dy;
+    }
+    scale *= enclosed * inputs.fill + open;
+    const radiance = scaledRgb(color, scale);
+    for (const lamp of inputs.lamps) {
+        const lx = lamp.position[0] - position[0];
+        const ly = lamp.position[1] - position[1];
+        const lz = lamp.position[2] - position[2];
+        const distanceSquared = lx * lx + ly * ly + lz * lz;
+        if (distanceSquared < 1e-4)
+            continue;
+        const reach = lamp.distance ?? 0;
+        if (reach > 0 && distanceSquared > reach * reach)
+            continue;
+        const distance = Math.sqrt(distanceSquared);
+        const facing = (dx * lx + dy * ly + dz * lz) / distance;
+        if (facing <= 0)
+            continue;
+        const falloff = (lamp.intensity ?? 1) / (distanceSquared + 1) * Math.pow(facing, 6);
+        const lampRadiant = scaledRgb(lamp.color ?? "#ffd6a0", falloff);
+        radiance[0] += lampRadiant[0];
+        radiance[1] += lampRadiant[1];
+        radiance[2] += lampRadiant[2];
+    }
+    return radiance;
+}
+/**
+ * The volume that governs a world position: the one whose box contains it, else the nearest by
+ * centre. A scene usually authors one volume per interior plus one for the exterior shell.
+ * @internal
+ */
+export function selectIrradianceVolume(volumes, position) {
+    let nearest;
+    let nearestDistance = Infinity;
+    for (const volume of volumes) {
+        if (volume.samples === undefined)
+            continue;
+        const dx = Math.abs(position[0] - volume.center[0]) - volume.size[0] / 2;
+        const dy = Math.abs(position[1] - volume.center[1]) - volume.size[1] / 2;
+        const dz = Math.abs(position[2] - volume.center[2]) - volume.size[2] / 2;
+        const outside = Math.max(dx, dy, dz);
+        if (outside <= 0)
+            return volume;
+        const distance = Math.hypot(Math.max(dx, 0), Math.max(dy, 0), Math.max(dz, 0));
+        if (distance < nearestDistance) {
+            nearestDistance = distance;
+            nearest = volume;
+        }
+    }
+    return nearest;
+}
+/**
+ * Trilinearly samples the volume's SH at a world position, writing {@link PROBE_STRIDE} floats into
+ * `out`. Positions outside the grid clamp to its faces, so a probe volume never pops to black at its
+ * edge. Returns false when the volume has no baked samples.
+ * @internal
+ */
+export function sampleIrradianceVolume(volume, position, out) {
+    const samples = volume.samples;
+    if (samples === undefined || samples.length < PROBE_STRIDE)
+        return false;
+    const [nx, ny, nz] = volume.resolution;
+    const axis = (value, center, size, count) => {
+        if (count <= 1 || size === 0)
+            return { low: 0, high: 0, t: 0 };
+        const normalized = ((value - center) / size + 0.5) * (count - 1);
+        const clamped = Math.max(0, Math.min(count - 1, normalized));
+        const low = Math.floor(clamped);
+        return { low, high: Math.min(count - 1, low + 1), t: clamped - low };
+    };
+    const x = axis(position[0], volume.center[0], volume.size[0], nx);
+    const y = axis(position[1], volume.center[1], volume.size[1], ny);
+    const z = axis(position[2], volume.center[2], volume.size[2], nz);
+    out.fill(0);
+    const weights = [];
+    for (const [ix, wx] of [[x.low, 1 - x.t], [x.high, x.t]]) {
+        for (const [iy, wy] of [[y.low, 1 - y.t], [y.high, y.t]]) {
+            for (const [iz, wz] of [[z.low, 1 - z.t], [z.high, z.t]]) {
+                const weight = wx * wy * wz;
+                if (weight <= 0)
+                    continue;
+                weights.push([ix, iy, iz]);
+                const offset = ((iz * ny + iy) * nx + ix) * PROBE_STRIDE;
+                for (let index = 0; index < PROBE_STRIDE; index += 1)
+                    out[index] += (samples[offset + index] ?? 0) * weight;
+            }
+        }
+    }
+    return weights.length > 0;
+}
+/**
+ * Radiance along a direction from the SH, `Σ coeff·basis` clamped at zero. Used by tests and by
+ * tooling that previews a volume without a renderer.
+ * @internal
+ */
+export function radianceAlong(sh, normal) {
+    const basis = new Float64Array(SH_COEFFICIENTS);
+    shDirection(normal[0], normal[1], normal[2], basis);
+    const rgb = [0, 0, 0];
+    for (let band = 0; band < SH_COEFFICIENTS; band += 1) {
+        rgb[0] += (sh[band * 3] ?? 0) * basis[band];
+        rgb[1] += (sh[band * 3 + 1] ?? 0) * basis[band];
+        rgb[2] += (sh[band * 3 + 2] ?? 0) * basis[band];
+    }
+    return [Math.max(0, rgb[0]), Math.max(0, rgb[1]), Math.max(0, rgb[2])];
+}

package/dist/render/lookPreset.js

@@ -4,7 +4,7 @@ export const LOOK_PRESETS = ["neutral", "photoreal", "cinematic", "toon", "comic
 export const CINEMATIC_SKY = { preset: "day" };
 /** Tuned tone-map + bloom + gentle SSAO + vignette/grade stack — the shipped-game post look. */
 export const CINEMATIC_POST_PROCESSING = {
-    toneMapping: "aces",
+    toneMapping: "agx",
     bloom: {},
     ao: { intensity: 1.4 },
     grade: {},
@@ -17,7 +17,7 @@ export const NEUTRAL_POST_PROCESSING = {
 };
 /** High-contrast physically based presentation for authored HDR environments. */
 export const PHOTOREAL_POST_PROCESSING = {
-    toneMapping: "aces",
+    toneMapping: "agx",
     bloom: { strength: 0.28, radius: 0.58, threshold: 0.9 },
     ao: { intensity: 1.25, radius: 1.6 },
     grade: { saturation: 1.04, vignette: 0.08, grain: 0.004 },
@@ -31,7 +31,7 @@ export const TOON_POST_PROCESSING = {
 };
 /** Ink outlines, four cel bands and a punchy grade — a hand-inked comic look on any model. */
 export const COMIC_POST_PROCESSING = {
-    toneMapping: "aces",
+    toneMapping: "agx",
     exposure: 1.05,
     aa: "msaa",
     bloom: { strength: 0.12, radius: 0.4, threshold: 1 },
@@ -41,7 +41,7 @@ export const COMIC_POST_PROCESSING = {
 };
 /** Chunky pixels and posterized colour with no smoothing — a low-resolution retro look. */
 export const RETRO_POST_PROCESSING = {
-    toneMapping: "aces",
+    toneMapping: "agx",
     aa: false,
     bloom: false,
     ao: false,

package/dist/render/physicalSky.d.ts

@@ -0,0 +1,39 @@
+/** Peak moonlight as a fraction of the authored sunlight, at the moon's highest point.
+ * Real moonlight is ~2.5e-6 of daylight; every game exaggerates it to stay readable, and this is
+ * the exaggeration, not a measurement. Games override it through `SkyEnvironmentConfig.moon`. */
+export declare const MOONLIGHT_PEAK = 0.12;
+/** Moonlight's colour: scattered sunlight, blue-shifted because the eye's scotopic response peaks there. */
+export declare const MOONLIGHT_COLOR = "#a9c3e8";
+/** Fog color once the sun is gone: the night sky's own haze, lifted enough to keep silhouettes readable. */
+export declare const NIGHT_FOG_COLOR = "#0a0e16";
+/** Elevation of a world-space direction in degrees; a zero vector reads as overhead. */
+export declare function elevationOf(direction: readonly [number, number, number]): number;
+/**
+ * Relative air mass along a line of sight at `elevationDeg` - Kasten & Young (1989). 1 at the
+ * zenith, ~38 at the horizon, and clamped below the horizon so a set sun does not run away.
+ * @internal
+ */
+export declare function airMass(elevationDeg: number): number;
+/**
+ * Fraction of each RGB channel of sunlight that survives the atmosphere at `elevationDeg`:
+ * `exp(-τ · air mass)`. High sun keeps nearly all of it; a low sun loses the short wavelengths
+ * first, which is the red sunset.
+ * @internal
+ */
+export declare function sunTransmission(elevationDeg: number): [number, number, number];
+/**
+ * The sun's colour at `elevationDeg`, normalised so its brightest channel is full: white overhead,
+ * orange at the horizon, moon-blue once it has set. Intensity stays the authored cycle's job.
+ */
+export declare function sunlightColor(elevationDeg: number): string;
+/** Perceived brightness (Rec. 709 luma) of a `#rrggbb` color, 0–1.
+ * @internal
+ */
+export declare function luminanceOf(color: string): number;
+/**
+ * Moonlight at `sunElevationDeg`'s opposite point: full at the top of the moon's arc, zero while
+ * the moon is below the horizon, scaled by `peak` (a fraction of the authored sun intensity).
+ */
+export declare function moonIllumination(moonElevationDeg: number, peak?: number): number;
+/** How visible the stars are: none in daylight, half at the first hint of a set sun, full once it is 6° under. */
+export declare function starOpacity(sunElevationDeg: number): number;

package/dist/render/physicalSky.js

@@ -0,0 +1,89 @@
+import { rgbToHex, hexToRgb } from "./color.js";
+/**
+ * Analytic atmosphere for the day/night sky: Rayleigh air mass, sunlight reddening, moonlight and
+ * star visibility. The engine keeps a game's authored sky colors as its noon keyframe; these
+ * functions supply the parts a color table cannot — the sun's own tint as it drops toward the
+ * horizon, the moon that replaces it after sunset, and how much starlight shows.
+ *
+ * Pure and deterministic so the whole cycle is testable without a renderer.
+ */
+/**
+ * Rayleigh scattering coefficient per RGB channel in m^-1 (680, 550, 440 nm, the standard
+ * β_R ∝ 1/λ⁴ curve) times an 8000 m scale height — the zenith optical depth `τ` of each channel.
+ */
+const RAYLEIGH_DEPTH = [0.0464, 0.108, 0.2648];
+/** Peak moonlight as a fraction of the authored sunlight, at the moon's highest point.
+ * Real moonlight is ~2.5e-6 of daylight; every game exaggerates it to stay readable, and this is
+ * the exaggeration, not a measurement. Games override it through `SkyEnvironmentConfig.moon`. */
+export const MOONLIGHT_PEAK = 0.12;
+/** Moonlight's colour: scattered sunlight, blue-shifted because the eye's scotopic response peaks there. */
+export const MOONLIGHT_COLOR = "#a9c3e8";
+/** Fog color once the sun is gone: the night sky's own haze, lifted enough to keep silhouettes readable. */
+export const NIGHT_FOG_COLOR = "#0a0e16";
+const DEG = Math.PI / 180;
+function clamp01(value) {
+    return value < 0 ? 0 : value > 1 ? 1 : value;
+}
+function smoothstep(edge0, edge1, value) {
+    const t = clamp01((value - edge0) / (edge1 - edge0));
+    return t * t * (3 - 2 * t);
+}
+/** Elevation of a world-space direction in degrees; a zero vector reads as overhead. */
+export function elevationOf(direction) {
+    const length = Math.hypot(direction[0], direction[1], direction[2]);
+    if (length === 0)
+        return 90;
+    return Math.asin(Math.max(-1, Math.min(1, direction[1] / length))) / DEG;
+}
+/**
+ * Relative air mass along a line of sight at `elevationDeg` - Kasten & Young (1989). 1 at the
+ * zenith, ~38 at the horizon, and clamped below the horizon so a set sun does not run away.
+ * @internal
+ */
+export function airMass(elevationDeg) {
+    const zenithDeg = 90 - Math.max(elevationDeg, 0);
+    if (zenithDeg >= 90)
+        return 38;
+    return 1 / (Math.cos(zenithDeg * DEG) + 0.50572 * Math.pow(96.07995 - zenithDeg, -1.6364));
+}
+/**
+ * Fraction of each RGB channel of sunlight that survives the atmosphere at `elevationDeg`:
+ * `exp(-τ · air mass)`. High sun keeps nearly all of it; a low sun loses the short wavelengths
+ * first, which is the red sunset.
+ * @internal
+ */
+export function sunTransmission(elevationDeg) {
+    const mass = airMass(elevationDeg);
+    return [0, 1, 2].map((channel) => Math.exp(-RAYLEIGH_DEPTH[channel] * mass));
+}
+/**
+ * The sun's colour at `elevationDeg`, normalised so its brightest channel is full: white overhead,
+ * orange at the horizon, moon-blue once it has set. Intensity stays the authored cycle's job.
+ */
+export function sunlightColor(elevationDeg) {
+    if (elevationDeg <= -6)
+        return MOONLIGHT_COLOR;
+    const transmission = sunTransmission(Math.max(elevationDeg, 0));
+    const brightest = Math.max(transmission[0], transmission[1], transmission[2], 1e-6);
+    return rgbToHex((transmission[0] / brightest) * 255, (transmission[1] / brightest) * 255, (transmission[2] / brightest) * 255);
+}
+/** Perceived brightness (Rec. 709 luma) of a `#rrggbb` color, 0–1.
+ * @internal
+ */
+export function luminanceOf(color) {
+    const [r, g, b] = hexToRgb(color);
+    return (0.2126 * r + 0.7152 * g + 0.0722 * b) / 255;
+}
+/**
+ * Moonlight at `sunElevationDeg`'s opposite point: full at the top of the moon's arc, zero while
+ * the moon is below the horizon, scaled by `peak` (a fraction of the authored sun intensity).
+ */
+export function moonIllumination(moonElevationDeg, peak = MOONLIGHT_PEAK) {
+    if (moonElevationDeg <= 0)
+        return 0;
+    return Math.sin(Math.min(moonElevationDeg, 90) * DEG) * Math.max(0, peak);
+}
+/** How visible the stars are: none in daylight, half at the first hint of a set sun, full once it is 6° under. */
+export function starOpacity(sunElevationDeg) {
+    return 1 - smoothstep(-6, 0, sunElevationDeg);
+}

package/dist/render/postProcessing.d.ts

@@ -1,5 +1,27 @@
-/** Renderer tone-mapping curve applied by the post chain's output stage. */
+import type { AutoExposureConfig } from "./colorPipeline.js";
+/**
+ * Renderer tone-mapping curve applied by the post chain's output stage. `"agx"` is the pipeline
+ * default: it keeps hue in saturated highlights and rolls a sun-lit surface off gradually, where
+ * `"aces"` skews bright colours toward white.
+ */
 export type ToneMappingMode = "aces" | "agx" | "reinhard" | "cineon" | "linear" | "none";
+/**
+ * A baked display-space LUT cube: `size³` RGB entries with red varying fastest, three bytes per entry
+ * in 0..255. Kept as plain data so a scene document can author one and a test can assert on it.
+ */
+export interface LutCube {
+    /** Edge length of the cube, 2..16. */
+    size: number;
+    /** `size³ × 3` bytes, red fastest, then green, then blue. */
+    data: Uint8Array;
+}
+/** A grade's LUT: a strip PNG (one `size`-wide tile per blue slice) or a baked cube. */
+export type GradeLut = {
+    url: string;
+    size?: number;
+} | {
+    cube: LutCube;
+};
 /** UnrealBloom stage — soft HDR glow around bright pixels (sun, glints, emissive). */
 export interface BloomConfig {
     /** Glow intensity. Default 0.32. */
@@ -26,11 +48,12 @@ export interface AoConfig {
 }
 /** Final colour-grade stage: lift/gain/gamma, saturation, vignette, film grain — applied in display space after tone mapping. */
 export interface GradeConfig {
-    /** Optional 2D strip LUT URL. The strip contains size square tiles, one tile per blue slice. */
-    lut?: {
-        url: string;
-        size?: number;
-    };
+    /**
+     * Colour LUT applied after the numeric grade, in display space. Either a strip PNG (one
+     * `size`-wide tile per blue slice, trilinearly sampled) or a baked {@link LutCube} such as the one
+     * a scene document's authored grading produces.
+     */
+    lut?: GradeLut;
     /** Additive shadow tint (RGB, ~0..0.1). Default cool [0.012, 0.010, 0.018]. */
     lift?: readonly [number, number, number];
     /** Multiplicative highlight tint (RGB, ~1). Default warm [1.05, 1.02, 0.98]. */
@@ -99,10 +122,19 @@ export type PostAaMode = "smaa" | "msaa" | false;
 export interface PostProcessingConfig {
     /** Master switch; a config object with `enabled: false` mounts nothing. Default true. */
     enabled?: boolean;
-    /** Tone-mapping curve the output stage applies. Default "aces". */
+    /** Tone-mapping curve the output stage applies. Default "agx". */
     toneMapping?: ToneMappingMode;
-    /** Exposure multiplier applied before tone mapping. Default 1. */
+    /**
+     * Exposure multiplier applied before tone mapping. Default 1. With `autoExposure` on this is the
+     * baseline the meter corrects around, not a fixed value.
+     */
     exposure?: number;
+    /**
+     * Clamped auto-exposure: meters the rendered frame and adapts exposure toward
+     * {@link import("./colorPipeline.js").MID_GREY}, bounded by `min`/`max`. Omitted uses
+     * {@link import("./colorPipeline.js").DEFAULT_AUTO_EXPOSURE} on every tier; `false` pins `exposure`.
+     */
+    autoExposure?: AutoExposureConfig | false;
     /**
      * Antialiasing. Default `"smaa"` (plus a light MSAA resolve on the beauty target).
      * Set `"msaa"` to skip the SMAA pass, or `false` for neither.

package/dist/render/postProcessing.js

@@ -7,7 +7,7 @@ export const DEFAULT_AO = { radius: 1.3, intensity: 1.3, distanceFalloff: 2.8, b
  * is left off by default (it needs a per-scene focus distance); set `dof` to enable it.
  */
 export const STUDIO_STAGE_POST = {
-    toneMapping: "aces",
+    toneMapping: "agx",
     exposure: 1.05,
     bloom: { strength: 0.28, radius: 0.6, threshold: 0.8 },
     ao: { radius: 1.1, intensity: 1.5, distanceFalloff: 3, blend: 1 },

package/dist/render/skyOwnedLighting.d.ts

@@ -0,0 +1,31 @@
+import type { LightingConfig } from "../game/playableGame.js";
+import type { SkyEnvironmentConfig } from "../world/features.js";
+/**
+ * Which half of a game's authored `lighting` a time-of-day sky takes over.
+ *
+ * A time-of-day sky has to move the sun or the whole world stays lit like noon after dark: the
+ * dome turns black while the ground keeps its midday key light. So under a day cycle the first
+ * directional light is the **sun**, and `ambient`/`hemisphere` are the **noon keyframes** of the
+ * ambient fill — the same convention the sky already uses for `horizonColor`/`zenithColor`. Every
+ * other light (fill directionals, point and spot lamps) stays exactly as authored.
+ */
+export interface SkyOwnedLighting {
+    /** Sun + ambient terms the sky now drives from the day cycle; intensities read as noon values. */
+    sky: LightingConfig;
+    /** Lights the sky does not own; mounted as authored. */
+    rest: LightingConfig;
+}
+/**
+ * Splits authored lighting into the sun/ambient terms a time-of-day sky drives and the rest.
+ * Returns an empty `sky` when the game authored no lighting, so callers can keep engine defaults.
+ * @capability day-night-sky hand the sun and ambient fill to the day cycle while authored lamps keep running
+ */
+export declare function splitSkyOwnedLighting(lighting: LightingConfig | undefined): SkyOwnedLighting;
+/**
+ * The authored `lighting` as the day cycle's **noon keyframes**, filling only the sky fields the
+ * game left unset. A game's midday sun, fill and fog therefore become the peak the cycle scales
+ * and cross-fades from, so an authored world gets a sunset and a night without re-authoring the
+ * same numbers in the sky. Authored sky fields always win over the lighting config.
+ * @capability day-night-sky read authored lighting as the day cycle's noon keyframe
+ */
+export declare function skyNoonKeyframes<T extends SkyEnvironmentConfig>(sky: T, lighting: LightingConfig | undefined, fogColor?: string): T;

package/dist/render/skyOwnedLighting.js

@@ -0,0 +1,46 @@
+/**
+ * Splits authored lighting into the sun/ambient terms a time-of-day sky drives and the rest.
+ * Returns an empty `sky` when the game authored no lighting, so callers can keep engine defaults.
+ * @capability day-night-sky hand the sun and ambient fill to the day cycle while authored lamps keep running
+ */
+export function splitSkyOwnedLighting(lighting) {
+    if (lighting === undefined)
+        return { sky: {}, rest: {} };
+    const directional = lighting.directional ?? [];
+    const [sun, ...fill] = directional;
+    const sky = {
+        ...(sun === undefined ? {} : { directional: [sun] }),
+        ...(lighting.ambient === undefined ? {} : { ambient: lighting.ambient }),
+        ...(lighting.hemisphere === undefined ? {} : { hemisphere: lighting.hemisphere }),
+    };
+    const rest = {
+        ...(fill.length === 0 ? {} : { directional: fill }),
+        ...(lighting.point === undefined ? {} : { point: lighting.point }),
+        ...(lighting.spot === undefined ? {} : { spot: lighting.spot }),
+        ...(lighting.maxDynamicLights === undefined ? {} : { maxDynamicLights: lighting.maxDynamicLights }),
+        ...(lighting.iblAmbientScale === undefined ? {} : { iblAmbientScale: lighting.iblAmbientScale }),
+        ...(lighting.fallbackKey === undefined ? {} : { fallbackKey: lighting.fallbackKey }),
+    };
+    return { sky, rest };
+}
+/**
+ * The authored `lighting` as the day cycle's **noon keyframes**, filling only the sky fields the
+ * game left unset. A game's midday sun, fill and fog therefore become the peak the cycle scales
+ * and cross-fades from, so an authored world gets a sunset and a night without re-authoring the
+ * same numbers in the sky. Authored sky fields always win over the lighting config.
+ * @capability day-night-sky read authored lighting as the day cycle's noon keyframe
+ */
+export function skyNoonKeyframes(sky, lighting, fogColor) {
+    const sun = lighting?.directional?.[0];
+    const fill = lighting?.hemisphere?.intensity ?? lighting?.ambient?.intensity;
+    const noon = { ...sky };
+    if (noon.sunIntensity === undefined && sun?.intensity !== undefined)
+        noon.sunIntensity = sun.intensity;
+    if (noon.ambientIntensity === undefined && fill !== undefined)
+        noon.ambientIntensity = fill;
+    if (noon.sunColor === undefined && sun?.color !== undefined)
+        noon.sunColor = sun.color;
+    if (noon.fogColor === undefined && fogColor !== undefined)
+        noon.fogColor = fogColor;
+    return noon;
+}

package/dist/sensor/perception.d.ts

@@ -25,11 +25,17 @@ export interface PerceptionCandidate {
 /** A remembered target and its linearly decaying confidence. */
 export interface PerceptionMemory {
     targetId: string;
+    /** When the fact was observed, on the same clock `observe` is given; its age is `now − lastSeenAt`. */
     lastSeenAt: number;
     lastKnownPos: PerceptionPosition;
+    /** 1 at the moment of the sighting, falling to 0 across `memorySeconds`. */
     confidence: number;
+    /** Whose senses produced the fact: this observer's id for its own sighting, a squadmate's for a shared one. */
+    sourceId: string;
+    /** Observe pass that recorded the fact, so a shared sighting is attributable to the tick it arrived. */
+    sourceTick: number;
 }
-/** Configuration for sight, hearing, memory decay, and optional occlusion. */
+/** Configuration for sight, hearing, memory decay, squad sharing and optional occlusion. */
 export interface PerceptionConfig {
     sightRange: number;
     sightConeDeg: number;
@@ -37,7 +43,43 @@ export interface PerceptionConfig {
     memorySeconds: number;
     /** Most stimuli retained at once; the oldest are dropped first. Default 256. */
     maxStimuli?: number;
-    occluded?: (from: PerceptionPosition, to: PerceptionPosition) => boolean;
+    /**
+     * Cheap "nothing blocks the segment from `from` to `to`" test, supplied by the game's collision
+     * layer. Only called for pairs already inside range and cone, so the costly test sees the pruned
+     * set. Omit for open ground.
+     */
+    isSegmentClear?: (from: PerceptionPosition, to: PerceptionPosition) => boolean;
+    /**
+     * The other members of an observer's squad, by id. A sighting one member makes is written into
+     * each mate's memory with the seeing member's id and the pass it happened on. Omit for lone
+     * observers. Keep the returned set small — the roster is the caller's, so the caller bounds it.
+     */
+    squadMates?: (observerId: string) => Iterable<string>;
+    /** Most sighting shares one pass may write, so a large squad cannot blow the tick budget. Default 64. */
+    maxSharesPerTick?: number;
+    /** Register a devtools probe under this name so the overlay shows perception work and memory. */
+    devtoolsName?: string;
+}
+/** Counters a perf test or a devtools probe reads. Reset with {@link PerceptionService.resetStats}. */
+export interface PerceptionStats {
+    /** Observe passes run. Keeps counting across `resetStats`, since it is also the recorded tick. */
+    passes: number;
+    /** `(observer, candidate)` pairs examined — one check per pair per pass. */
+    pairChecks: number;
+    /** Pairs rejected by distance before any cone or occlusion work. */
+    rangeCulled: number;
+    /** Pairs inside sight range, so they paid the cone test. */
+    coneTests: number;
+    /** Calls into the injected `isSegmentClear`. */
+    occlusionChecks: number;
+    /** Pairs that produced the observer's own sighting. */
+    sightings: number;
+    /** Sound and damage stimuli an observer resolved inside its hearing range. */
+    heard: number;
+    /** Sightings written into a squadmate's memory. */
+    shares: number;
+    /** Sightings the per-pass share cap kept from being broadcast. */
+    shareDropped: number;
 }
 /** Serializable state for a perception service. */
 export interface PerceptionSnapshot {
@@ -52,19 +94,38 @@ export interface PerceptionSnapshot {
     /** Per observer, the last stimulus sequence number it has already judged. Absent in older saves. */
     heard?: Record<string, number>;
     nextSeq?: number;
+    /** Observe passes recorded, which is also the tick a memory carries. Absent in older saves. */
+    passes?: number;
 }
 /** Stateful perception API with retuning and save/restore support. */
 export interface PerceptionService {
     pushStimulus(stimulus: PerceptionStimulus): void;
     observe(observer: PerceptionObserver, candidates: readonly PerceptionCandidate[], nowMs: number): void;
     memory(observerId: string): PerceptionMemory[];
+    /** One remembered target with its confidence now, or `null` when never seen or already faded. */
+    memoryOf(observerId: string, targetId: string): PerceptionMemory | null;
     /** Drop one remembered target, or everything an observer remembers (despawn, reset, disguise). */
     forget(observerId: string, targetId?: string): void;
-    retune(patch: Partial<PerceptionConfig>): void;
+    stats(): PerceptionStats;
+    /** Zero the work counters, keeping the pass count that memories are stamped with. */
+    resetStats(): void;
+    retune(patch: Partial<Omit<PerceptionConfig, "devtoolsName">>): void;
     snapshot(): PerceptionSnapshot;
     restore(snapshot: PerceptionSnapshot): void;
+    /** Drop the devtools probe registered by `devtoolsName`. Safe to call twice. */
+    dispose(): void;
 }
-/** Creates a deterministic sight, sound, and damage perception service with expiring target memory.
- * @capability perception-service retain sight, sound, and damage observations with range, cone, occlusion, and decay policy
+/**
+ * Creates a deterministic sight, sound, and damage perception service with expiring target memory.
+ * Signals are judged in the order the caller supplies them, never from the wall clock.
+ *
+ * A sighting needs range, cone and a clear line; a sound carries `hearingRange × loudness` and
+ * fades with the distance it crossed, so a distant footstep is inaudible while a near gunshot is
+ * not. Memory is the only record of "seen recently": each fact fades linearly over `memorySeconds`
+ * and is then gone. With `squadMates` injected, a sighting one member makes lands in every mate's
+ * memory stamped with the seeing member and the pass, which is what lets a squad react to one pair
+ * of eyes without each member re-seeing anything.
+ *
+ * @capability perception-service retain sightings, sounds and damage with cone, range, occlusion, decaying memory and shared squad knowledge
  */
 export declare function createPerception(initial: PerceptionConfig): PerceptionService;