@jgengine/core 0.25.0 → 0.27.0

package/dist/render/colorPipeline.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Calibration of the output pipeline, in linear scene luminance (1.0 = a white-looking surface at
+ * exposure 1).
+ *
+ * `WHITE_POINT` is the luminance the pipeline prints as display white under AgX. Everything above it
+ * is highlight headroom the tone curve rolls off, so a material meant to read as white is authored at
+ * 1.0 rather than at whatever the sun happened to be set to.
+ * `MID_GREY` is an 18% grey card — the metering target. Clamped auto-exposure drives the frame's key
+ * luminance here, which is what makes one material read the same in a street at noon and a lamp-lit
+ * room. There is one white point and one metering target; a second copy anywhere would make a grade
+ * depend on which stage read it.
+ */
+export declare const WHITE_POINT = 1;
+/** Linear scene luminance of an 18% grey card — the auto-exposure metering target. */
+export declare const MID_GREY = 0.18;
+/**
+ * Pixels count toward metering up to this multiple of {@link WHITE_POINT}. A window or a sun disc sits
+ * far above it and would otherwise pull the whole frame down to a silhouette.
+ */
+export declare const METERING_HIGHLIGHT_CEILING: number;
+/** Bounds and adaptation policy for clamped auto-exposure. */
+export interface AutoExposureConfig {
+    /** Lowest exposure multiplier the meter may reach. Default 0.6 (0.7 stops down). */
+    min?: number;
+    /** Highest exposure multiplier the meter may reach. Default 2.5 (1.3 stops up). */
+    max?: number;
+    /** Seconds for the meter to cover ~63% of a gap to a new key luminance. Default 0.6. */
+    adaptationSeconds?: number;
+}
+/**
+ * Default clamped auto-exposure. The range is deliberately asymmetric: a bright street is already
+ * readable after AgX's shoulder, while a lamp-lit interior is the case that crushes, so the meter may
+ * lift 1.3 stops but only darken 0.7 — an artist's exposure survives.
+ */
+export declare const DEFAULT_AUTO_EXPOSURE: Readonly<Required<AutoExposureConfig>>;
+/**
+ * Exposure that places a frame whose key luminance is `keyLuminance` on {@link MID_GREY}, bounded by
+ * the authored range. A dark interior asks for more than `max` and gets `max`; a blown-out exterior
+ * asks for less than `min` and gets `min`, so the frame never runs away at either end.
+ */
+export declare function exposureForKey(keyLuminance: number, config?: AutoExposureConfig): number;
+/**
+ * Frame-rate independent blend of `current` toward `target`, exponential in time so a hitch does not
+ * overshoot and a steady view settles. `deltaSeconds` may be 0..∞; a zero-length step keeps `current`.
+ */
+export declare function adaptExposure(current: number, target: number, deltaSeconds: number, adaptationSeconds?: number): number;
+/**
+ * Key luminance of a metered frame: the median of its samples, each clamped to
+ * {@link METERING_HIGHLIGHT_CEILING}. A median rather than a mean because a bright sky, a window or a
+ * lamp is a large minority of the frame: averaging those in drags an interior down to a silhouette,
+ * where the median still reports the room.
+ */
+export declare function keyLuminanceFromSamples(samples: ArrayLike<number>): number;

package/dist/render/colorPipeline.js

@@ -0,0 +1,79 @@
+/**
+ * Calibration of the output pipeline, in linear scene luminance (1.0 = a white-looking surface at
+ * exposure 1).
+ *
+ * `WHITE_POINT` is the luminance the pipeline prints as display white under AgX. Everything above it
+ * is highlight headroom the tone curve rolls off, so a material meant to read as white is authored at
+ * 1.0 rather than at whatever the sun happened to be set to.
+ * `MID_GREY` is an 18% grey card — the metering target. Clamped auto-exposure drives the frame's key
+ * luminance here, which is what makes one material read the same in a street at noon and a lamp-lit
+ * room. There is one white point and one metering target; a second copy anywhere would make a grade
+ * depend on which stage read it.
+ */
+export const WHITE_POINT = 1;
+/** Linear scene luminance of an 18% grey card — the auto-exposure metering target. */
+export const MID_GREY = 0.18;
+/**
+ * Pixels count toward metering up to this multiple of {@link WHITE_POINT}. A window or a sun disc sits
+ * far above it and would otherwise pull the whole frame down to a silhouette.
+ */
+export const METERING_HIGHLIGHT_CEILING = WHITE_POINT * 8;
+/**
+ * Default clamped auto-exposure. The range is deliberately asymmetric: a bright street is already
+ * readable after AgX's shoulder, while a lamp-lit interior is the case that crushes, so the meter may
+ * lift 1.3 stops but only darken 0.7 — an artist's exposure survives.
+ */
+export const DEFAULT_AUTO_EXPOSURE = {
+    min: 0.6,
+    max: 2.5,
+    adaptationSeconds: 0.6,
+};
+/**
+ * Exposure that places a frame whose key luminance is `keyLuminance` on {@link MID_GREY}, bounded by
+ * the authored range. A dark interior asks for more than `max` and gets `max`; a blown-out exterior
+ * asks for less than `min` and gets `min`, so the frame never runs away at either end.
+ */
+export function exposureForKey(keyLuminance, config = {}) {
+    const min = config.min ?? DEFAULT_AUTO_EXPOSURE.min;
+    const max = config.max ?? DEFAULT_AUTO_EXPOSURE.max;
+    const low = Math.min(min, max);
+    const high = Math.max(min, max);
+    if (!Number.isFinite(keyLuminance) || keyLuminance <= 0)
+        return high;
+    return Math.min(high, Math.max(low, MID_GREY / keyLuminance));
+}
+/**
+ * Frame-rate independent blend of `current` toward `target`, exponential in time so a hitch does not
+ * overshoot and a steady view settles. `deltaSeconds` may be 0..∞; a zero-length step keeps `current`.
+ */
+export function adaptExposure(current, target, deltaSeconds, adaptationSeconds = DEFAULT_AUTO_EXPOSURE.adaptationSeconds) {
+    if (!Number.isFinite(target))
+        return current;
+    if (!(deltaSeconds > 0))
+        return current;
+    if (!(adaptationSeconds > 0))
+        return target;
+    const blend = 1 - Math.exp(-deltaSeconds / adaptationSeconds);
+    return current + (target - current) * blend;
+}
+/**
+ * Key luminance of a metered frame: the median of its samples, each clamped to
+ * {@link METERING_HIGHLIGHT_CEILING}. A median rather than a mean because a bright sky, a window or a
+ * lamp is a large minority of the frame: averaging those in drags an interior down to a silhouette,
+ * where the median still reports the room.
+ */
+export function keyLuminanceFromSamples(samples) {
+    if (samples.length === 0)
+        return MID_GREY;
+    const values = [];
+    for (let index = 0; index < samples.length; index += 1) {
+        const value = samples[index];
+        if (!(value > 0) || !Number.isFinite(value))
+            continue;
+        values.push(Math.min(value, METERING_HIGHLIGHT_CEILING));
+    }
+    if (values.length === 0)
+        return 0;
+    values.sort((a, b) => a - b);
+    return values[Math.floor((values.length - 1) / 2)];
+}

package/dist/render/lightProbes.d.ts

@@ -0,0 +1,97 @@
+/**
+ * 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 declare const SH_COEFFICIENTS = 9;
+/** Floats stored per probe: {@link SH_COEFFICIENTS} × RGB. */
+export declare const PROBE_STRIDE: number;
+/** One irradiance volume authored on a scene document. */
+export interface IrradianceVolume {
+    id: string;
+    /** World-space centre of the grid. */
+    center: readonly [number, number, number];
+    /** World-space extent of the grid. */
+    size: readonly [number, number, number];
+    /** Probe count per axis; at least 1. */
+    resolution: readonly [number, number, number];
+    /**
+     * `PROBE_STRIDE` floats per probe, row-major (x fastest, then y, then z). Absent until baked, so a
+     * freshly authored volume renders nothing rather than a fabricated ambient.
+     */
+    samples?: readonly number[];
+}
+/** Authored bake inputs stored beside the samples so a volume can be re-baked without the editor. */
+export interface IrradianceBakeSettings {
+    /** How much sky reaches the region: 0 fully enclosed, 1 fully open. */
+    skyVisibility: number;
+    /** Radiance above the horizon for an open region. Default the sky's own horizon colour. */
+    skyColor?: string;
+    /** Radiance below the horizon (ground bounce). */
+    groundColor?: string;
+    /** Fill colour of an enclosed region's ceiling; keeps a room from baking to black. */
+    ceilingColor?: string;
+    /** Fill colour of an enclosed region's floor. */
+    floorColor?: string;
+    /** Multiplier on the enclosed fill. Default 1. */
+    fillIntensity?: number;
+    /** Authored lamps folded into the bake. */
+    lights?: readonly {
+        position: readonly [number, number, number];
+        color?: string;
+        intensity?: number;
+        distance?: number;
+    }[];
+}
+/**
+ * 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 declare function shDirection(x: number, y: number, z: number, out: Float64Array | number[]): void;
+/** World-space position of probe `(ix, iy, iz)`; the outer probes sit on the box faces.
+ * @internal
+ */
+export declare function probePosition(volume: Pick<IrradianceVolume, "center" | "size" | "resolution">, ix: number, iy: number, iz: number): [number, number, number];
+/** Everything a bake needs for one volume: where the grid sits, how much sky reaches it, and what fills the dark. */
+export interface IrradianceBakeInput {
+    /** Stable volume id, copied onto the baked volume. */
+    id: string;
+    center: readonly [number, number, number];
+    size: readonly [number, number, number];
+    resolution: readonly [number, number, number];
+    settings: IrradianceBakeSettings;
+    /** Direction samples per probe. Default 64. */
+    samples?: number;
+}
+/**
+ * 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 declare function bakeIrradianceVolume(input: IrradianceBakeInput): IrradianceVolume;
+/**
+ * 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 declare function selectIrradianceVolume(volumes: readonly IrradianceVolume[], position: readonly [number, number, number]): IrradianceVolume | undefined;
+/**
+ * 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 declare function sampleIrradianceVolume(volume: IrradianceVolume, position: readonly [number, number, number], out: Float32Array): boolean;
+/**
+ * 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 declare function radianceAlong(sh: ArrayLike<number>, normal: readonly [number, number, number]): [number, number, number];

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);
+}