@jgengine/core 0.25.0 → 0.26.0

package/dist/devtools/types.d.ts

@@ -100,12 +100,48 @@ export interface LatencyStats {
 }
 /** Severity level for a captured devtools log entry. */
 export type DevtoolsLogLevel = "log" | "info" | "warn" | "error";
-/** A single captured log line with timestamp, level, and formatted message. */
+/** A single captured log line with timestamp, level, owning system tag, and formatted message. */
 export interface DevtoolsLogEntry {
     at: number;
     level: DevtoolsLogLevel;
+    /** System that wrote the line, e.g. `needs`, `nav`, `render/culling`, `console`, `runtime`. */
+    system: string;
     message: string;
 }
+/** What one system reports about itself: totals it keeps anyway, named timings, and one state line. */
+export interface SystemProbe {
+    /** Monotonic or gauge numbers a system already tracks (counts, queue depths, cache hits). */
+    counters?(): Record<string, number>;
+    /** Named timings in milliseconds the system accumulated (spatial query, path solve, tick). */
+    timers?(): Record<string, number>;
+    /** One short line a human reads in the report, e.g. `visible 120/800 · culled 680`. */
+    state?(): string;
+}
+/** One system's probe read out on demand; missing sections stay empty rather than absent. */
+export interface SystemProbeReading {
+    counters: Record<string, number>;
+    timers: Record<string, number>;
+    state: string;
+}
+/** Bounded log ring with per-system tags, a warning/error ring, and lifetime counts. */
+export interface DevtoolsLogs {
+    /** Tagged write for a system's own lines; allocation-free apart from the message itself. */
+    write(level: DevtoolsLogLevel, system: string, message: string): void;
+    /** Untagged convenience write; `system` defaults to `console`. */
+    push(level: DevtoolsLogLevel, message: string, system?: string): void;
+    captureConsole(): void;
+    list(): readonly DevtoolsLogEntry[];
+    severe(): readonly DevtoolsLogEntry[];
+    counts(): import("./logBus.js").LogBusCounts;
+    dropped(): number;
+    snapshot(): import("./logBus.js").LogBusSnapshot;
+    clear(): void;
+}
+/** Latency samples recorded by instrumented transport methods. */
+export interface DevtoolsLatency {
+    record(ms: number): void;
+    stats(): LatencyStats | null;
+}
 /** A control auto-discovered by scanning an object/table, with its binding metadata and current reader. */
 export interface DiscoveredEntry {
     readonly id: string;
@@ -131,6 +167,8 @@ export interface DevtoolsSnapshot {
     longFrames: readonly LongFrameEvent[];
     logs: readonly DevtoolsLogEntry[];
     probes: Record<string, unknown>;
+    /** Per-system probe readings (`counters`/`timers`/`state`), keyed by system id. */
+    systems: Record<string, SystemProbeReading>;
     controls: readonly {
         name: string;
         kind: DevtoolsControlKind;
@@ -172,16 +210,8 @@ export interface Devtools {
         record(sample: RenderSample): void;
         latest(): RenderSample | null;
     };
-    logs: {
-        push(level: DevtoolsLogLevel, message: string): void;
-        captureConsole(): void;
-        list(): readonly DevtoolsLogEntry[];
-        clear(): void;
-    };
-    latency: {
-        record(ms: number): void;
-        stats(): LatencyStats | null;
-    };
+    logs: DevtoolsLogs;
+    latency: DevtoolsLatency;
     controls: {
         register<T>(name: string, initial: T, options?: TunableOptions<T>): Tunable<T>;
         list(): readonly DevtoolsControl[];
@@ -206,6 +236,13 @@ export interface Devtools {
     probes: {
         register(name: string, read: () => unknown): () => void;
         read(): Record<string, unknown>;
+        /**
+         * Register a system's own counters, timers and state line. Returns its dispose; registering the
+         * same id again replaces the earlier one (the last live instance wins).
+         */
+        registerSystem(id: string, probe: SystemProbe): () => void;
+        /** Read every registered system probe. Allocates; call on demand, never per frame. */
+        systems(): Record<string, SystemProbeReading>;
     };
     signal: ChangeSignal;
     snapshot(): DevtoolsSnapshot;

package/dist/editor/document.js

@@ -5,6 +5,17 @@ import { parseStaticPrefabBake } from "./staticPrefab.js";
 import { cloneEditorUiDocument, decodeEditorUiDocument } from "../ui/hudDocument.js";
 import { migrateTerrainSnapshot } from "../world/terraform.js";
 import { cloneGridLayer, migrateGridLayer, } from "./grid.js";
+import { PROBE_STRIDE } from "../render/lightProbes.js";
+function cloneLightProbes(probes) {
+    return probes.map((probe) => ({
+        ...probe,
+        center: [...probe.center],
+        size: [...probe.size],
+        resolution: [...probe.resolution],
+        ...(probe.samples === undefined ? {} : { samples: [...probe.samples] }),
+        ...(probe.bake === undefined ? {} : { bake: { ...probe.bake, ...(probe.bake.lights === undefined ? {} : { lights: probe.bake.lights.map((light) => ({ ...light, position: [...light.position] })) }) } }),
+    }));
+}
 /** Copies a baked minimap so a document's PNG + bounds are never shared by reference across rebuilds. */
 function cloneMinimapBake(minimap) {
     return { background: minimap.background, bounds: { ...minimap.bounds } };
@@ -26,6 +37,14 @@ function cloneEnvironment(environment) {
         ...(environment.sunAzimuth === undefined ? {} : { sunAzimuth: environment.sunAzimuth }),
         ...(environment.sunElevation === undefined ? {} : { sunElevation: environment.sunElevation }),
         ...(environment.fog === undefined ? {} : { fog: { ...environment.fog } }),
+        ...(environment.grading === undefined ? {} : { grading: cloneGrading(environment.grading) }),
+        ...(environment.probes === undefined ? {} : { probes: cloneLightProbes(environment.probes) }),
+    };
+}
+function cloneGrading(grading) {
+    return {
+        ...grading,
+        ...(grading.autoExposure === undefined ? {} : { autoExposure: { ...grading.autoExposure } }),
     };
 }
 function cloneEnvironmentSource(source) {
@@ -1123,6 +1142,28 @@ function decodeEnvironment(value, path, errors) {
             }));
         }
     }
+    if (value.probes !== undefined) {
+        if (!Array.isArray(value.probes)) {
+            errors.push({ path: `${path}.probes`, message: "expected an array" });
+            failed = true;
+        }
+        else if (value.probes.length > 16) {
+            errors.push({ path: `${path}.probes`, message: "at most 16 irradiance volumes" });
+            failed = true;
+        }
+        else {
+            const probes = [];
+            for (const [index, entry] of value.probes.entries()) {
+                const probe = decodeLightProbe(entry, `${path}.probes[${index}]`, errors);
+                if (probe === undefined)
+                    failed = true;
+                else
+                    probes.push(probe);
+            }
+            if (probes.length > 0)
+                env.probes = probes;
+        }
+    }
     if (value.preset !== undefined) {
         if (typeof value.preset === "string" && SKY_PRESETS.has(value.preset)) {
             env.preset = value.preset;
@@ -1195,10 +1236,179 @@ function decodeEnvironment(value, path, errors) {
                 env.fog = fog;
         }
     }
+    if (value.grading !== undefined) {
+        const grading = decodeGrading(value.grading, `${path}.grading`, errors);
+        if (grading === undefined)
+            failed = true;
+        else
+            env.grading = grading;
+    }
     if (failed)
         return undefined;
     return env;
 }
+/**
+ * Validates an authored colour grade. Swatches must be hex colours and every number finite, because
+ * the runtime bakes the LUT straight from these values; unknown junk is rejected with its path rather
+ * than silently grading to something the author did not pick.
+ */
+function decodeGrading(value, path, errors) {
+    if (!isPlainObject(value)) {
+        errors.push({ path, message: "expected an object" });
+        return undefined;
+    }
+    let failed = false;
+    const grading = {};
+    const swatch = (key) => {
+        const entry = value[key];
+        if (entry === undefined)
+            return;
+        if (typeof entry === "string" && /^#?([0-9a-f]{3}|[0-9a-f]{6})$/i.test(entry)) {
+            grading[key] = entry.startsWith("#") ? entry : `#${entry}`;
+        }
+        else {
+            errors.push({ path: `${path}.${key}`, message: "expected a hex colour such as #2a3a52" });
+            failed = true;
+        }
+    };
+    swatch("shadows");
+    swatch("midtones");
+    swatch("highlights");
+    if (value.size !== undefined) {
+        if (typeof value.size === "number" && Number.isInteger(value.size) && value.size >= 2 && value.size <= 16)
+            grading.size = value.size;
+        else {
+            errors.push({ path: `${path}.size`, message: "expected an integer cube size from 2 to 16" });
+            failed = true;
+        }
+    }
+    for (const key of ["tint", "saturation", "contrast"]) {
+        const entry = value[key];
+        if (entry === undefined)
+            continue;
+        if (typeof entry === "number" && Number.isFinite(entry))
+            grading[key] = entry;
+        else {
+            errors.push({ path: `${path}.${key}`, message: "expected a finite number" });
+            failed = true;
+        }
+    }
+    if (value.autoExposure !== undefined) {
+        if (!isPlainObject(value.autoExposure)) {
+            errors.push({ path: `${path}.autoExposure`, message: "expected an object" });
+            failed = true;
+        }
+        else {
+            const exposure = {};
+            for (const key of ["min", "max"]) {
+                const entry = value.autoExposure[key];
+                if (entry === undefined)
+                    continue;
+                if (typeof entry === "number" && Number.isFinite(entry) && entry > 0)
+                    exposure[key] = entry;
+                else {
+                    errors.push({ path: `${path}.autoExposure.${key}`, message: "expected a positive finite exposure multiplier" });
+                    failed = true;
+                }
+            }
+            if (Object.keys(exposure).length > 0)
+                grading.autoExposure = exposure;
+        }
+    }
+    if (failed)
+        return undefined;
+    return Object.keys(grading).length === 0 ? undefined : grading;
+}
+/**
+ * Validates one authored irradiance volume. Probes are bounded (16 volumes, 16³ probes each) so a
+ * scene document cannot turn into an accidental multi-megabyte bake, and every sample must be a
+ * finite number because the renderer writes them straight into SH uniforms.
+ */
+function decodeLightProbe(value, path, errors) {
+    if (!isPlainObject(value)) {
+        errors.push({ path, message: "expected an object" });
+        return undefined;
+    }
+    const vec3 = (entry) => {
+        if (!Array.isArray(entry) || entry.length !== 3)
+            return null;
+        if (entry.some((component) => typeof component !== "number" || !Number.isFinite(component)))
+            return null;
+        return [...entry];
+    };
+    let failed = false;
+    const id = value.id;
+    if (typeof id !== "string" || id.length === 0) {
+        errors.push({ path: `${path}.id`, message: "expected a non-empty string" });
+        failed = true;
+    }
+    const center = vec3(value.center);
+    const size = vec3(value.size);
+    const resolution = vec3(value.resolution);
+    if (center === null) {
+        errors.push({ path: `${path}.center`, message: "expected three finite numbers" });
+        failed = true;
+    }
+    if (size === null || (size !== null && size.some((extent) => extent <= 0))) {
+        errors.push({ path: `${path}.size`, message: "expected three positive extents" });
+        failed = true;
+    }
+    if (resolution === null || (resolution !== null && resolution.some((count) => count < 1 || count > 16 || !Number.isInteger(count)))) {
+        errors.push({ path: `${path}.resolution`, message: "expected 1-16 whole probes per axis" });
+        failed = true;
+    }
+    let samples;
+    if (value.samples !== undefined) {
+        const expected = resolution === null ? 0 : PROBE_STRIDE * resolution[0] * resolution[1] * resolution[2];
+        if (!Array.isArray(value.samples) || value.samples.length !== expected || value.samples.some((sample) => typeof sample !== "number" || !Number.isFinite(sample))) {
+            errors.push({ path: `${path}.samples`, message: `expected ${expected} finite numbers for this resolution` });
+            failed = true;
+        }
+        else {
+            samples = [...value.samples];
+        }
+    }
+    if (failed || center === null || size === null || resolution === null || typeof id !== "string")
+        return undefined;
+    const bake = isPlainObject(value.bake) ? decodeLightProbeBake(value.bake) : undefined;
+    return {
+        id,
+        center,
+        size,
+        resolution,
+        ...(samples === undefined ? {} : { samples }),
+        ...(typeof value.label === "string" ? { label: value.label } : {}),
+        ...(bake === undefined ? {} : { bake }),
+    };
+}
+function decodeLightProbeBake(value) {
+    if (typeof value.skyVisibility !== "number" || !Number.isFinite(value.skyVisibility))
+        return undefined;
+    const color = (entry) => (typeof entry === "string" ? entry : undefined);
+    const lights = Array.isArray(value.lights)
+        ? value.lights.flatMap((light) => {
+            if (!isPlainObject(light) || !Array.isArray(light.position) || light.position.length !== 3)
+                return [];
+            if (light.position.some((n) => typeof n !== "number" || !Number.isFinite(n)))
+                return [];
+            return [{
+                    position: [...light.position],
+                    ...(color(light.color) === undefined ? {} : { color: color(light.color) }),
+                    ...(typeof light.intensity === "number" && Number.isFinite(light.intensity) ? { intensity: light.intensity } : {}),
+                    ...(typeof light.distance === "number" && Number.isFinite(light.distance) ? { distance: light.distance } : {}),
+                }];
+        })
+        : undefined;
+    return {
+        skyVisibility: Math.max(0, Math.min(1, value.skyVisibility)),
+        ...(color(value.skyColor) === undefined ? {} : { skyColor: color(value.skyColor) }),
+        ...(color(value.groundColor) === undefined ? {} : { groundColor: color(value.groundColor) }),
+        ...(color(value.ceilingColor) === undefined ? {} : { ceilingColor: color(value.ceilingColor) }),
+        ...(color(value.floorColor) === undefined ? {} : { floorColor: color(value.floorColor) }),
+        ...(typeof value.fillIntensity === "number" && Number.isFinite(value.fillIntensity) ? { fillIntensity: value.fillIntensity } : {}),
+        ...(lights === undefined || lights.length === 0 ? {} : { lights }),
+    };
+}
 const GRID_AXES = new Set(["xz", "xy"]);
 function decodeGridPaletteEntry(item, path, errors) {
     if (!isPlainObject(item)) {

package/dist/editor/environment.d.ts

@@ -2,7 +2,9 @@ import type { SkyEnvironmentConfig, WorldBounds } from "../world/features.js";
 import type { AvoidZone } from "../world/geometry.js";
 import { type ClearanceOptions } from "../world/scatterRegion.js";
 import type { TerraformSnapshot } from "../world/terraform.js";
-import type { EditorDocument, EditorEnvironment } from "./types.js";
+import type { EditorAutoExposure, EditorColorGrading, EditorDocument, EditorEnvironment, EditorLightProbe } from "./types.js";
+import { type IrradianceVolume } from "../render/lightProbes.js";
+import type { LutCube } from "../render/postProcessing.js";
 import type { LightingConfig } from "../game/playableGame.js";
 /**
  * World-authoring convergence (#1018, epic #1006 Phase 4): derive the **coordinate/placement**
@@ -47,6 +49,51 @@ export declare function skyFromDocument(doc: EditorDocument): SkyEnvironmentConf
  * @internal
  */
 export declare function skyConfigFromEnvironment(env: EditorEnvironment): SkyEnvironmentConfig;
+/**
+ * The baked irradiance volumes a scene document authored, flattened for the renderer.
+ * @capability light-probes read the scene document's baked irradiance volumes at runtime
+ */
+export declare function lightProbesFromDocument(doc: EditorDocument): readonly IrradianceVolume[];
+/**
+ * Bakes an authored grade into a display-space LUT cube. Contrast and saturation work around
+ * luma, then each band pulls its share of the frame toward the authored swatch, scaled to the
+ * pixel's own brightness so a swatch tints a band instead of painting over it. Pure and
+ * deterministic, so the editor's preview and the runtime produce the same bytes.
+ * @capability color-grading bake an authored grade into a display-space LUT cube
+ */
+export declare function lutCubeFromGrading(grading: EditorColorGrading): LutCube;
+/** The renderer-facing result of a document's authored grade. */
+export interface DocumentColorGrade {
+    /** Display-space LUT baked from the authored bands, saturation and contrast. */
+    lut?: LutCube;
+    /** Authored clamped auto-exposure range, when the document set one. */
+    autoExposure?: EditorAutoExposure;
+}
+/**
+ * The colour grade a scene document authored, baked for the renderer. `undefined` when the document
+ * authored no grade at all, so an ungraded game keeps its own post chain untouched. The shell folds
+ * this into the post config the same way {@link lightProbesFromDocument} feeds the irradiance
+ * volumes, so a game's grade is authored data rather than a pass wired in its config.
+ * @capability color-grading read the scene document's authored grade at runtime
+ */
+export declare function colorGradeFromDocument(doc: EditorDocument): DocumentColorGrade | undefined;
+/**
+ * The lamps a bake should include: authored light markers plus the environment's point lights.
+ * @capability light-probes fold the document's authored lamps into a probe bake
+ */
+export declare function authoredLightsFromDocument(doc: EditorDocument): readonly {
+    position: readonly [number, number, number];
+    color?: string;
+    intensity?: number;
+    distance?: number;
+}[];
+/**
+ * Bakes one authored irradiance volume from its own settings and the document's lamps: sky where
+ * the region is open, an authored ceiling/floor fill where it is enclosed, and the authored lamps
+ * on top. Pure and deterministic, so the editor's Bake button and a script produce the same samples.
+ * @capability light-probes bake a scene document's irradiance volume from its authored lamps
+ */
+export declare function bakeLightProbe(probe: EditorLightProbe, doc: EditorDocument): EditorLightProbe;
 /** Converts authored `light` markers into the runtime lighting contract. */
 export declare function lightingFromDocument(doc: EditorDocument): LightingConfig | undefined;
 /**

package/dist/editor/environment.js

@@ -1,5 +1,6 @@
 import { clearanceZonesFrom, DEFAULT_CLEARANCE_KINDS } from "../world/scatterRegion.js";
 import { editorDocumentBounds } from "./document.js";
+import { bakeIrradianceVolume } from "../render/lightProbes.js";
 /**
  * Maps the scene document's serializable environment bag onto the runtime sky config consumed by
  * `sky()` / `environment({ sky })`. Returns `undefined` when the document has no environment field
@@ -36,6 +37,166 @@ export function skyConfigFromEnvironment(env) {
         ...(env.fog === undefined ? {} : { fog: { ...env.fog } }),
     };
 }
+/**
+ * The baked irradiance volumes a scene document authored, flattened for the renderer.
+ * @capability light-probes read the scene document's baked irradiance volumes at runtime
+ */
+export function lightProbesFromDocument(doc) {
+    return doc.environment?.probes ?? [];
+}
+const GRADING_LUMA = [0.2126, 0.7152, 0.0722];
+/** Cube sizes outside this bake either alias (2) or stop being a small authored file (16+). */
+const MIN_LUT_SIZE = 2;
+const MAX_LUT_SIZE = 16;
+const DEFAULT_LUT_SIZE = 8;
+function clamp01(value) {
+    return value < 0 ? 0 : value > 1 ? 1 : value;
+}
+/** Parses `#rgb`/`#rrggbb` into 0..1 display RGB; `undefined` when the swatch is not a colour. */
+function displayRgb(hex) {
+    const body = hex.startsWith("#") ? hex.slice(1) : hex;
+    const expanded = body.length === 3 ? body.split("").map((digit) => digit + digit).join("") : body;
+    if (expanded.length !== 6 || !/^[0-9a-f]{6}$/i.test(expanded))
+        return undefined;
+    const value = Number.parseInt(expanded, 16);
+    return [((value >> 16) & 0xff) / 255, ((value >> 8) & 0xff) / 255, (value & 0xff) / 255];
+}
+function luma(rgb) {
+    return rgb[0] * GRADING_LUMA[0] + rgb[1] * GRADING_LUMA[1] + rgb[2] * GRADING_LUMA[2];
+}
+function smoothstep(edge0, edge1, x) {
+    const t = clamp01((x - edge0) / (edge1 - edge0));
+    return t * t * (3 - 2 * t);
+}
+/** True when the authored grade would leave every colour unchanged, so no LUT is worth baking. */
+function gradingIsIdentity(grading) {
+    const saturation = grading.saturation ?? 1;
+    const contrast = grading.contrast ?? 1;
+    const tint = grading.tint ?? 0.45;
+    const bands = grading.shadows !== undefined || grading.midtones !== undefined || grading.highlights !== undefined;
+    return saturation === 1 && contrast === 1 && (!bands || tint <= 0);
+}
+/**
+ * Bakes an authored grade into a display-space LUT cube. Contrast and saturation work around
+ * luma, then each band pulls its share of the frame toward the authored swatch, scaled to the
+ * pixel's own brightness so a swatch tints a band instead of painting over it. Pure and
+ * deterministic, so the editor's preview and the runtime produce the same bytes.
+ * @capability color-grading bake an authored grade into a display-space LUT cube
+ */
+export function lutCubeFromGrading(grading) {
+    const size = Math.round(Math.min(MAX_LUT_SIZE, Math.max(MIN_LUT_SIZE, grading.size ?? DEFAULT_LUT_SIZE)));
+    const saturation = grading.saturation ?? 1;
+    const contrast = grading.contrast ?? 1;
+    const tint = clamp01(grading.tint ?? 0.45);
+    const bands = [
+        { color: grading.shadows === undefined ? undefined : displayRgb(grading.shadows), weight: (l) => 1 - smoothstep(0, 0.5, l) },
+        // Band weights partition the frame: shadows fade out by mid-grey, highlights fade in from it, and
+        // midtones are whatever is left (`s1 - s2`, which the naive `1 - wS - wH` double-counts).
+        { color: grading.midtones === undefined ? undefined : displayRgb(grading.midtones), weight: (l) => smoothstep(0, 0.5, l) - smoothstep(0.5, 1, l) },
+        { color: grading.highlights === undefined ? undefined : displayRgb(grading.highlights), weight: (l) => smoothstep(0.5, 1, l) },
+    ].filter((band) => band.color !== undefined);
+    const data = new Uint8Array(size * size * size * 3);
+    const levels = size - 1;
+    for (let blue = 0; blue < size; blue += 1) {
+        for (let green = 0; green < size; green += 1) {
+            for (let red = 0; red < size; red += 1) {
+                const input = [red / levels, green / levels, blue / levels];
+                const bandLuma = luma(input);
+                const curved = input.map((channel) => clamp01((channel - 0.5) * contrast + 0.5));
+                const curvedLuma = luma(curved);
+                let color = curved.map((channel) => curvedLuma + (channel - curvedLuma) * saturation);
+                for (const band of bands) {
+                    const weight = clamp01(band.weight(bandLuma));
+                    if (weight <= 0)
+                        continue;
+                    // The swatch at the pixel's brightness: a #2a3a52 shadow tint darkens and cools, it does
+                    // not raise every shadow to mid-blue.
+                    const swatchLuma = Math.max(luma(band.color), 1e-3);
+                    const target = band.color.map((channel) => clamp01((channel * bandLuma) / swatchLuma));
+                    const amount = tint * weight;
+                    color = color.map((channel, index) => channel + (target[index] - channel) * amount);
+                }
+                const offset = (blue * size * size + green * size + red) * 3;
+                data[offset] = Math.round(clamp01(color[0]) * 255);
+                data[offset + 1] = Math.round(clamp01(color[1]) * 255);
+                data[offset + 2] = Math.round(clamp01(color[2]) * 255);
+            }
+        }
+    }
+    return { size, data };
+}
+/**
+ * The colour grade a scene document authored, baked for the renderer. `undefined` when the document
+ * authored no grade at all, so an ungraded game keeps its own post chain untouched. The shell folds
+ * this into the post config the same way {@link lightProbesFromDocument} feeds the irradiance
+ * volumes, so a game's grade is authored data rather than a pass wired in its config.
+ * @capability color-grading read the scene document's authored grade at runtime
+ */
+export function colorGradeFromDocument(doc) {
+    const grading = doc.environment?.grading;
+    if (grading === undefined)
+        return undefined;
+    const lut = gradingIsIdentity(grading) ? undefined : lutCubeFromGrading(grading);
+    if (lut === undefined && grading.autoExposure === undefined)
+        return undefined;
+    return {
+        ...(lut === undefined ? {} : { lut }),
+        ...(grading.autoExposure === undefined ? {} : { autoExposure: grading.autoExposure }),
+    };
+}
+/**
+ * The lamps a bake should include: authored light markers plus the environment's point lights.
+ * @capability light-probes fold the document's authored lamps into a probe bake
+ */
+export function authoredLightsFromDocument(doc) {
+    const lamps = [];
+    for (const marker of doc.markers) {
+        if (marker.kind !== "light" || marker.position === undefined)
+            continue;
+        const meta = marker.meta ?? {};
+        lamps.push({
+            position: [marker.position.x, marker.position.y, marker.position.z],
+            ...(typeof meta.color === "string" ? { color: meta.color } : {}),
+            ...(typeof meta.intensity === "number" ? { intensity: meta.intensity } : {}),
+            ...(typeof meta.range === "number" ? { distance: meta.range } : {}),
+        });
+    }
+    for (const light of doc.environment?.pointLights ?? []) {
+        lamps.push({
+            position: light.position,
+            ...(light.color === undefined ? {} : { color: light.color }),
+            ...(light.intensity === undefined ? {} : { intensity: light.intensity }),
+            ...(light.distance === undefined ? {} : { distance: light.distance }),
+        });
+    }
+    return lamps;
+}
+/**
+ * Bakes one authored irradiance volume from its own settings and the document's lamps: sky where
+ * the region is open, an authored ceiling/floor fill where it is enclosed, and the authored lamps
+ * on top. Pure and deterministic, so the editor's Bake button and a script produce the same samples.
+ * @capability light-probes bake a scene document's irradiance volume from its authored lamps
+ */
+export function bakeLightProbe(probe, doc) {
+    const bake = probe.bake ?? { skyVisibility: 0 };
+    const lamps = bakedLampsFor(probe, doc);
+    return {
+        ...probe,
+        samples: bakeIrradianceVolume({
+            id: probe.id,
+            center: probe.center,
+            size: probe.size,
+            resolution: probe.resolution,
+            settings: { ...bake, lights: lamps },
+        }).samples,
+    };
+}
+/** Lamps folded into a probe: its own bake lights when authored, else the document's lamps. */
+function bakedLampsFor(probe, doc) {
+    if (probe.bake?.lights !== undefined && probe.bake.lights.length > 0)
+        return probe.bake.lights;
+    return authoredLightsFromDocument(doc);
+}
 /** Converts authored `light` markers into the runtime lighting contract. */
 export function lightingFromDocument(doc) {
     const points = [];

package/dist/editor/index.d.ts

@@ -5,7 +5,9 @@ export type { EditorTerrain } from "./types.js";
 /** A baked top-down minimap (PNG data URI + world bounds) persisted on the scene document. */
 export type { EditorMinimapBake } from "./types.js";
 /** Scene-document sky/fog/lighting bag edited by the lighting workspace. */
-export type { EditorEnvironment, EditorFogConfig, EditorSkyPreset, PointLightingConfig } from "./types.js";
+export type { EditorEnvironment, EditorFogConfig, EditorLightProbe, EditorSkyPreset, PointLightingConfig } from "./types.js";
+/** Authored per-game colour grade: band tints, saturation/contrast and the clamped exposure range. */
+export type { EditorAutoExposure, EditorColorGrading } from "./types.js";
 /** Declarative HDRI, cube, or gradient environment source used by the shell. */
 export type { EnvironmentSource } from "../render/environment.js";
 /** Per-kind show/hide flags for the editor's layer panel. */
@@ -64,9 +66,11 @@ export { WORLD_BASE_SHARD_ID, WORLD_MANIFEST_KIND, decodeWorldManifest, exportWo
 export type { DecodeWorldManifestResult, SplitWorldOptions, SplitWorldResult, WorldGrid, WorldManifest, WorldManifestShard, WorldQuery, WorldShardBounds, WorldShardResidency, WorldShardResolver, WorldStreamingConfig, } from "./world.js";
 /** Result of {@link decodeEditorDocument}: a typed document, or every diagnostic collected while decoding it. */
 export type { DecodeEditorDocumentResult } from "./document.js";
-export { environmentContentFromDocument, lightingFromDocument, skyConfigFromEnvironment, skyFromDocument, terrainBoundsFromDocument, } from "./environment.js";
+export { authoredLightsFromDocument, bakeLightProbe, colorGradeFromDocument, environmentContentFromDocument, lightProbesFromDocument, lightingFromDocument, lutCubeFromGrading, skyConfigFromEnvironment, skyFromDocument, terrainBoundsFromDocument, } from "./environment.js";
 /** Coordinate/placement content of an `environment()` world derived from the scene document. */
 export type { EnvironmentContent, EnvironmentContentOptions } from "./environment.js";
+/** A scene document's authored grade, baked for the renderer. */
+export type { DocumentColorGrade } from "./environment.js";
 export { bakeMinimapFromDocument, documentBakeZones } from "./minimap.js";
 /** Editor-side minimap bake from the scene document (footprint + biome-tint zones). */
 export type { DocumentBakeOptions } from "./minimap.js";

package/dist/editor/index.js

@@ -3,7 +3,7 @@ export { ENTITY_CATALOG_ID, entityDefinitionSchema, entityEntryFromCatalog, reso
 export { WELL_KNOWN_MARKER_KINDS, WELL_KNOWN_PATH_KINDS, WELL_KNOWN_VOLUME_KINDS, } from "./types.js";
 export { applyEditorDocumentOverlay, cloneEditorDocument, collectDescendants, createEmptyEditorDocument, createPrefabFragment, decodeEditorDocument, editorChildren, editorDocumentBounds, editorDocumentExtras, editorDocumentSize, editorMarkerPosition, editorMarkerXZ, editorParentOf, editorRoots, exportEditorDocumentJson, extractEditorFragment, findEditorCatalog, findEditorCatalogEntry, findEditorCollection, findEditorMarker, findEditorNote, findEditorPath, findEditorPrefab, findEditorVolume, importEditorDocumentJson, isEditorObjectCollectionLocked, isEditorObjectHidden, isEditorObjectLocked, isEditorObjectSelfLocked, listEditorKinds, mergeEditorDocuments, normalizeEditorLayers, requireEditorMarker, seedEditorCatalogs, wouldCreateCycle, } from "./document.js";
 export { WORLD_BASE_SHARD_ID, WORLD_MANIFEST_KIND, decodeWorldManifest, exportWorldManifestJson, loadWorldDocument, selectWorldShards, shardMatchesQuery, singleShardWorldManifest, splitEditorDocumentIntoShards, } from "./world.js";
-export { environmentContentFromDocument, lightingFromDocument, skyConfigFromEnvironment, skyFromDocument, terrainBoundsFromDocument, } from "./environment.js";
+export { authoredLightsFromDocument, bakeLightProbe, colorGradeFromDocument, environmentContentFromDocument, lightProbesFromDocument, lightingFromDocument, lutCubeFromGrading, skyConfigFromEnvironment, skyFromDocument, terrainBoundsFromDocument, } from "./environment.js";
 export { bakeMinimapFromDocument, documentBakeZones } from "./minimap.js";
 export { createWorldStreamer, shardDistance } from "./streamer.js";
 export { applyDirectiveOverlay, materializeDirective, materializeDirectives, materializePopulationDirective, materializeScatterDirective, resolveDirectiveFootprint, } from "./directives.js";