@jgengine/core 0.24.0 → 0.26.0

package/dist/nav/navRuntime.js

@@ -0,0 +1,256 @@
+import { devtools } from "../devtools/devtools.js";
+import { createNavMeshQuery, } from "./navMesh.js";
+const DEFAULT_LINK_COSTS = { door: 0.5, ladder: 4, jump: 1.5, link: 0 };
+const DEFAULT_SNAP_RADIUS = 2;
+function finiteNumbers(value) {
+    return Array.isArray(value) && value.every((entry) => typeof entry === "number" && Number.isFinite(entry));
+}
+function isPolygonList(value, vertexCount) {
+    if (!Array.isArray(value))
+        return false;
+    return value.every((ring) => Array.isArray(ring) &&
+        ring.length >= 3 &&
+        ring.every((index) => typeof index === "number" && Number.isInteger(index) && index >= 0 && index < vertexCount));
+}
+/**
+ * Read the named navigation bake an editor wrote onto a scene document. Returns `null` when the
+ * document holds no such bake yet, and throws when the stored bake is not a valid nav mesh — a
+ * corrupt bake should fail at load, not as agents walking through walls.
+ *
+ * @capability navmesh-from-scene read the editor's baked nav mesh off a scene document
+ */
+export function navMeshFromBake(bakes, id = "main") {
+    const bake = bakes?.find((entry) => entry.kind === "nav" && entry.id === id);
+    if (bake === undefined)
+        return null;
+    if (bake.data === null || typeof bake.data !== "object")
+        throw new Error(`nav bake "${id}" has no data object`);
+    const data = bake.data;
+    if (!finiteNumbers(data.verts) || data.verts.length % 3 !== 0) {
+        throw new Error(`nav bake "${id}" verts must be finite xyz triples`);
+    }
+    const vertexCount = data.verts.length / 3;
+    if (!isPolygonList(data.polys, vertexCount))
+        throw new Error(`nav bake "${id}" polys must index its verts`);
+    if (data.links !== undefined && !Array.isArray(data.links))
+        throw new Error(`nav bake "${id}" links must be an array`);
+    const links = (data.links ?? []).map((link) => ({
+        from: link.from,
+        to: link.to,
+        ...(link.cost === undefined ? {} : { cost: link.cost }),
+        ...(link.start === undefined ? {} : { start: link.start }),
+        ...(link.end === undefined ? {} : { end: link.end }),
+    }));
+    for (const link of links) {
+        if (!Number.isInteger(link.from) || !Number.isInteger(link.to))
+            throw new Error(`nav bake "${id}" links need polygon ids`);
+    }
+    const areas = data.areas;
+    const validAreas = finiteNumbers(areas) && areas.length === data.polys.length;
+    return { verts: [...data.verts], polys: data.polys.map((ring) => [...ring]), links, ...(validAreas ? { areas: [...areas] } : {}) };
+}
+function round(value) {
+    return Math.round(value * 1e4) / 1e4;
+}
+function vertexKey(x, y, z) {
+    return `${round(x)}|${round(y)}|${round(z)}`;
+}
+/** Order-independent handle for "the same polygon": its corner positions, rotated to a fixed start. */
+function polySignature(mesh, ring) {
+    if (ring.length === 0)
+        return "";
+    const keys = [];
+    let best = 0;
+    for (let i = 0; i < ring.length; i += 1) {
+        const index = ring[i];
+        const key = vertexKey(mesh.verts[index * 3] ?? 0, mesh.verts[index * 3 + 1] ?? 0, mesh.verts[index * 3 + 2] ?? 0);
+        keys.push(key);
+        if (key < keys[best])
+            best = i;
+    }
+    return [...keys.slice(best), ...keys.slice(0, best)].join(";");
+}
+function linkCost(link, costs) {
+    if (link.cost !== undefined && Number.isFinite(link.cost) && link.cost >= 0)
+        return link.cost;
+    const kind = link.kind ?? "link";
+    const cost = costs[kind] ?? DEFAULT_LINK_COSTS[kind];
+    return Number.isFinite(cost) && cost >= 0 ? cost : DEFAULT_LINK_COSTS[kind];
+}
+function samePoint(a, b) {
+    if (a === undefined || b === undefined)
+        return a === b;
+    return a[0] === b[0] && a[1] === b[1] && a[2] === b[2];
+}
+function sameLinks(a, b) {
+    if (a.length !== b.length)
+        return false;
+    for (let i = 0; i < a.length; i += 1) {
+        const left = a[i];
+        const right = b[i];
+        if (left.from !== right.from || left.to !== right.to || left.cost !== right.cost)
+            return false;
+        if (!samePoint(left.start, right.start) || !samePoint(left.end, right.end))
+            return false;
+    }
+    return true;
+}
+/**
+ * Route agents over the nav mesh an editor baked. Wraps {@link createNavMeshQuery}, resolves authored
+ * off-mesh links (doors, ladders, jumps) onto the current surface, and exchanges the mesh one scene
+ * region at a time so untouched polygons keep their ids and the agents routing over them keep their paths.
+ *
+ * @capability nav-runtime route agents on an editor-baked nav mesh with authored links and re-bakes that keep polygon identity
+ */
+export function createNavRuntime(options) {
+    let authored = (options.links ?? []).map((link) => ({ ...link }));
+    let linkCosts = { ...(options.linkCosts ?? {}) };
+    let snapRadius = Math.max(0, options.linkSnapRadius ?? DEFAULT_SNAP_RADIUS);
+    let resolved = [];
+    let unresolved = [];
+    let rebuildCount = 0;
+    let planCount = 0;
+    let lastPlanMs = 0;
+    let mesh = options.mesh;
+    const queryOptions = {
+        ...(options.areaCosts === undefined ? {} : { areaCosts: { ...options.areaCosts } }),
+        ...(options.maxNodes === undefined ? {} : { maxNodes: options.maxNodes }),
+    };
+    let query = createNavMeshQuery(mesh, queryOptions);
+    function resolveLinks() {
+        const base = mesh;
+        const out = [];
+        const missing = [];
+        const seen = new Set();
+        for (const link of authored) {
+            const from = query.findPolygon(link.from);
+            const to = query.findPolygon(link.to);
+            if (from === null || to === null || from === to) {
+                missing.push(link.id);
+                continue;
+            }
+            const startSurface = query.closestPoint(link.from);
+            const endSurface = query.closestPoint(link.to);
+            if (startSurface === null || endSurface === null) {
+                missing.push(link.id);
+                continue;
+            }
+            const startGap = Math.hypot(link.from[0] - startSurface[0], link.from[1] - startSurface[1], link.from[2] - startSurface[2]);
+            const endGap = Math.hypot(link.to[0] - endSurface[0], link.to[1] - endSurface[1], link.to[2] - endSurface[2]);
+            if (startGap > snapRadius || endGap > snapRadius) {
+                missing.push(link.id);
+                continue;
+            }
+            const pair = `${from}>${to}`;
+            if (seen.has(pair))
+                continue;
+            seen.add(pair);
+            out.push({ from, to, cost: linkCost(link, linkCosts), start: link.from, end: link.to });
+        }
+        resolved = out;
+        unresolved = missing;
+        if (!sameLinks(base.links, out))
+            mesh = { ...base, links: out };
+        query = createNavMeshQuery(mesh, query.snapshot());
+    }
+    function probeLine() {
+        const partial = planCount === 0 ? "no plans" : `${lastPlanMs.toFixed(2)} ms last`;
+        return `${mesh.polys.length} polys ${resolved.length} links ${unresolved.length} unresolved ${rebuildCount} rebuilds ${planCount} plans ${partial}`;
+    }
+    const unregister = options.devtoolsName === undefined ? null : devtools.probes.register(options.devtoolsName, () => probeLine());
+    resolveLinks();
+    return {
+        get mesh() {
+            return mesh;
+        },
+        plan(from, to) {
+            const started = performance.now();
+            const path = query.findPath(from, to);
+            planCount += 1;
+            lastPlanMs = performance.now() - started;
+            return path;
+        },
+        findPolygon: (point) => query.findPolygon(point),
+        closestPoint: (point) => query.closestPoint(point),
+        raycast: (from, to) => query.raycast(from, to),
+        applyMesh(next) {
+            const previous = mesh;
+            const remap = new Int32Array(previous.polys.length).fill(-1);
+            const swapped = {
+                verts: [...next.verts],
+                polys: next.polys.map((ring) => [...ring]),
+                links: [],
+                ...(next.areas === undefined ? {} : { areas: [...next.areas] }),
+            };
+            // Polygon identity is matched on geometry, not array order: a bake numbers its polygons from
+            // scratch, so the only stable handle a route can hold is where the polygon actually is.
+            const bySignature = new Map();
+            for (let p = 0; p < swapped.polys.length; p += 1) {
+                const key = polySignature(swapped, swapped.polys[p]);
+                if (!bySignature.has(key))
+                    bySignature.set(key, p);
+            }
+            let kept = 0;
+            let removed = 0;
+            for (let p = 0; p < previous.polys.length; p += 1) {
+                const match = bySignature.get(polySignature(previous, previous.polys[p]));
+                if (match === undefined)
+                    removed += 1;
+                else {
+                    remap[p] = match;
+                    kept += 1;
+                }
+            }
+            mesh = swapped;
+            rebuildCount += 1;
+            resolveLinks();
+            return { added: Math.max(0, swapped.polys.length - kept), removed, kept, remap };
+        },
+        links: () => resolved,
+        unresolvedLinks: () => unresolved,
+        rebuilds: () => rebuildCount,
+        retune(patch) {
+            if (patch.areaCosts !== undefined || patch.maxNodes !== undefined) {
+                query.retune({
+                    ...(patch.areaCosts === undefined ? {} : { areaCosts: { ...patch.areaCosts } }),
+                    ...(patch.maxNodes === undefined ? {} : { maxNodes: patch.maxNodes }),
+                });
+            }
+            let relink = false;
+            if (patch.links !== undefined) {
+                authored = patch.links.map((link) => ({ ...link }));
+                relink = true;
+            }
+            if (patch.linkCosts !== undefined) {
+                linkCosts = { ...patch.linkCosts };
+                relink = true;
+            }
+            if (patch.linkSnapRadius !== undefined) {
+                snapRadius = Math.max(0, patch.linkSnapRadius);
+                relink = true;
+            }
+            if (relink)
+                resolveLinks();
+        },
+        snapshot() {
+            const tuning = query.snapshot();
+            return {
+                areaCosts: { ...tuning.areaCosts },
+                maxNodes: tuning.maxNodes,
+                links: authored.map((link) => ({ ...link })),
+                linkCosts: { ...linkCosts },
+                linkSnapRadius: snapRadius,
+            };
+        },
+        restore(next) {
+            authored = next.links.map((link) => ({ ...link }));
+            linkCosts = { ...next.linkCosts };
+            snapRadius = Math.max(0, next.linkSnapRadius);
+            query.restore({ areaCosts: { ...next.areaCosts }, maxNodes: next.maxNodes });
+            resolveLinks();
+        },
+        dispose() {
+            unregister?.();
+        },
+    };
+}

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];