@vgai/engine 0.5.21 → 0.5.22

package/dist/render/directional-shadow-fit.d.ts

@@ -0,0 +1,88 @@
+/**
+ * Fit a directional light's orthographic shadow box to the camera, for one
+ * frame — the geometry three does not supply.
+ *
+ * `DirectionalLightShadow` is an ordinary `OrthographicCamera` parented to the
+ * light, and it sits wherever the light's authored transform puts it, forever.
+ * That is fine for a scene the authored box contains and wrong for every game
+ * whose camera travels: the moment the player walks past the box, the casters
+ * out there stop having shadows, and no bias, map size or intensity fixes it
+ * because the geometry is simply outside the frustum. Three's own addon CSM is
+ * the multi-cascade answer to a different question and supplies neither of the
+ * two pieces below.
+ *
+ * ## The box is the frustum slice's BOUNDING SPHERE
+ *
+ * The standard fit, and the reason it cannot be authored as a constant: take
+ * the eight corners of the camera's frustum between its near plane and
+ * `maxDistance`, put the box centre at their centroid, and size the box to the
+ * largest distance from that centroid to a corner. That radius is decided by
+ * the camera's FIELD OF VIEW and aspect as much as by `maxDistance` — at a
+ * 70-degree vertical fov over 1024x600, a 40-unit slice has half-extents of
+ * 47.8 x 28.0 at its far plane and the sphere around it has radius ~58.9,
+ * nearly three times `maxDistance / 2`. A bounding SPHERE (rather than the
+ * tight box) is what makes the radius independent of camera yaw, so turning in
+ * place cannot resize the shadow.
+ *
+ * The corners are read through the camera's own `projectionMatrixInverse`, so
+ * a perspective and an orthographic camera are exact with no branch on type —
+ * and an asymmetric frustum (`setViewOffset`) is fitted over its real corners
+ * rather than an assumed centre.
+ *
+ * ## Texel snapping is not a polish detail
+ *
+ * A shadow box that follows a camera continuously re-rasterizes the same
+ * static geometry at sub-texel offsets, and the depth-test result flips along
+ * every shadow edge from frame to frame — the edges CRAWL, which is far more
+ * distracting than the missing shadows the fit is for. Quantizing the centre
+ * to whole shadow texels, in the LIGHT's own basis (the shadow map's u/v axes
+ * are the light's local x/y), makes the rasterized footprint of a static
+ * caster identical between frames. Depth (local z) is deliberately NOT snapped:
+ * it does not affect which texel a fragment lands in.
+ *
+ * ## What the caller keeps
+ *
+ * This is one pure function over three's own objects: it reads a camera and a
+ * quaternion and returns three numbers-and-a-vector. It moves nothing, and in
+ * particular it does not touch the light — how a fitted centre reaches the
+ * shadow camera is the caller's, because three derives the shadow camera's
+ * placement FROM the light every frame (`LightShadow.updateMatrices` copies the
+ * light's world position and looks at `light.target`), so the thing that has to
+ * move is the light NODE and only the caller knows how its light is parented,
+ * aimed and torn down. The depth range (`shadow.camera.near`/`far`) is the
+ * caller's for the same reason: it is what `shadow.bias` is normalized against.
+ *
+ * {@link DirectionalShadowFit.texelWorldSize} is published because everything
+ * sized in texels moves with the box — a receiver-side `shadow.normalBias`
+ * derived from a stale texel is wrong by exactly the factor the box grew, and
+ * it surfaces as self-shadow acne on curved casters rather than as anything a
+ * reviewer would call a shadow bug.
+ *
+ * Consumers today: `top-down-strategy`'s camera-fitted sun, and
+ * `godot-compat`'s Godot 3 `SHADOW_ORTHOGONAL` fit.
+ */
+import { type Camera, Quaternion, Vector3 } from 'three';
+/** The box a directional shadow is rendered through for one frame. */
+export interface DirectionalShadowFit {
+    /** WORLD-space centre of the box, quantized to whole shadow texels in the light's basis. */
+    readonly center: Vector3;
+    /** Half-extent on both lateral axes — the frustum slice's bounding-sphere radius. */
+    readonly radius: number;
+    /** One shadow texel in world units at this radius: `2 * radius / mapSize`. */
+    readonly texelWorldSize: number;
+}
+/**
+ * The bounding sphere of `camera`'s frustum between its near plane and
+ * `maxDistance`, with the centre quantized to whole shadow texels in the
+ * LIGHT's basis.
+ *
+ * `camera` is read through its own `projectionMatrix`/`projectionMatrixInverse`/`matrixWorld`, so a
+ * caller must have brought those up to date (three does this for every rendered camera).
+ * `maxDistance` is the view depth the shadow covers, measured from the camera and clamped to its
+ * far plane — there is nothing to shadow past the geometry the camera draws.
+ * `lightOrientation` is the light's WORLD quaternion, whose local x/y are the shadow map's own axes
+ * and therefore the axes the snap quantizes along. A `mapSize` of zero or less disables snapping
+ * rather than dividing by it.
+ */
+export declare function fitDirectionalShadowToCamera(camera: Camera, lightOrientation: Quaternion, maxDistance: number, mapSize: number): DirectionalShadowFit;
+//# sourceMappingURL=directional-shadow-fit.d.ts.map

package/dist/render/directional-shadow-fit.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"directional-shadow-fit.d.ts","sourceRoot":"","sources":["../../src/render/directional-shadow-fit.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8DG;AACH,OAAO,EAAE,KAAK,MAAM,EAAE,UAAU,EAAE,OAAO,EAAE,MAAM,OAAO,CAAC;AAEzD,sEAAsE;AACtE,MAAM,WAAW,oBAAoB;IACnC,4FAA4F;IAC5F,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC;IACzB,qFAAqF;IACrF,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,8EAA8E;IAC9E,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;CACjC;AAoBD;;;;;;;;;;;;GAYG;AACH,wBAAgB,4BAA4B,CAC1C,MAAM,EAAE,MAAM,EACd,gBAAgB,EAAE,UAAU,EAC5B,WAAW,EAAE,MAAM,EACnB,OAAO,EAAE,MAAM,GACd,oBAAoB,CA4CtB"}

package/dist/render/directional-shadow-fit.js

@@ -0,0 +1,133 @@
+/**
+ * Fit a directional light's orthographic shadow box to the camera, for one
+ * frame — the geometry three does not supply.
+ *
+ * `DirectionalLightShadow` is an ordinary `OrthographicCamera` parented to the
+ * light, and it sits wherever the light's authored transform puts it, forever.
+ * That is fine for a scene the authored box contains and wrong for every game
+ * whose camera travels: the moment the player walks past the box, the casters
+ * out there stop having shadows, and no bias, map size or intensity fixes it
+ * because the geometry is simply outside the frustum. Three's own addon CSM is
+ * the multi-cascade answer to a different question and supplies neither of the
+ * two pieces below.
+ *
+ * ## The box is the frustum slice's BOUNDING SPHERE
+ *
+ * The standard fit, and the reason it cannot be authored as a constant: take
+ * the eight corners of the camera's frustum between its near plane and
+ * `maxDistance`, put the box centre at their centroid, and size the box to the
+ * largest distance from that centroid to a corner. That radius is decided by
+ * the camera's FIELD OF VIEW and aspect as much as by `maxDistance` — at a
+ * 70-degree vertical fov over 1024x600, a 40-unit slice has half-extents of
+ * 47.8 x 28.0 at its far plane and the sphere around it has radius ~58.9,
+ * nearly three times `maxDistance / 2`. A bounding SPHERE (rather than the
+ * tight box) is what makes the radius independent of camera yaw, so turning in
+ * place cannot resize the shadow.
+ *
+ * The corners are read through the camera's own `projectionMatrixInverse`, so
+ * a perspective and an orthographic camera are exact with no branch on type —
+ * and an asymmetric frustum (`setViewOffset`) is fitted over its real corners
+ * rather than an assumed centre.
+ *
+ * ## Texel snapping is not a polish detail
+ *
+ * A shadow box that follows a camera continuously re-rasterizes the same
+ * static geometry at sub-texel offsets, and the depth-test result flips along
+ * every shadow edge from frame to frame — the edges CRAWL, which is far more
+ * distracting than the missing shadows the fit is for. Quantizing the centre
+ * to whole shadow texels, in the LIGHT's own basis (the shadow map's u/v axes
+ * are the light's local x/y), makes the rasterized footprint of a static
+ * caster identical between frames. Depth (local z) is deliberately NOT snapped:
+ * it does not affect which texel a fragment lands in.
+ *
+ * ## What the caller keeps
+ *
+ * This is one pure function over three's own objects: it reads a camera and a
+ * quaternion and returns three numbers-and-a-vector. It moves nothing, and in
+ * particular it does not touch the light — how a fitted centre reaches the
+ * shadow camera is the caller's, because three derives the shadow camera's
+ * placement FROM the light every frame (`LightShadow.updateMatrices` copies the
+ * light's world position and looks at `light.target`), so the thing that has to
+ * move is the light NODE and only the caller knows how its light is parented,
+ * aimed and torn down. The depth range (`shadow.camera.near`/`far`) is the
+ * caller's for the same reason: it is what `shadow.bias` is normalized against.
+ *
+ * {@link DirectionalShadowFit.texelWorldSize} is published because everything
+ * sized in texels moves with the box — a receiver-side `shadow.normalBias`
+ * derived from a stale texel is wrong by exactly the factor the box grew, and
+ * it surfaces as self-shadow acne on curved casters rather than as anything a
+ * reviewer would call a shadow bug.
+ *
+ * Consumers today: `top-down-strategy`'s camera-fitted sun, and
+ * `godot-compat`'s Godot 3 `SHADOW_ORTHOGONAL` fit.
+ */
+import { Quaternion, Vector3 } from 'three';
+const _inverseLight = new Quaternion();
+const _corner = new Vector3();
+const _centroid = new Vector3();
+const _ndc = new Vector3();
+/** The four lateral NDC corners; the slice's eight are these at two depths. */
+const NDC_CORNERS = [
+    [-1, -1],
+    [-1, 1],
+    [1, -1],
+    [1, 1],
+];
+/** View-space depth `-z` as this camera's NDC z, through the camera's OWN projection — so the
+ *  slice is exact for a perspective and an orthographic camera alike, with no branch on type. */
+function ndcDepthOf(camera, viewDepth) {
+    return _ndc.set(0, 0, -viewDepth).applyMatrix4(camera.projectionMatrix).z;
+}
+/**
+ * The bounding sphere of `camera`'s frustum between its near plane and
+ * `maxDistance`, with the centre quantized to whole shadow texels in the
+ * LIGHT's basis.
+ *
+ * `camera` is read through its own `projectionMatrix`/`projectionMatrixInverse`/`matrixWorld`, so a
+ * caller must have brought those up to date (three does this for every rendered camera).
+ * `maxDistance` is the view depth the shadow covers, measured from the camera and clamped to its
+ * far plane — there is nothing to shadow past the geometry the camera draws.
+ * `lightOrientation` is the light's WORLD quaternion, whose local x/y are the shadow map's own axes
+ * and therefore the axes the snap quantizes along. A `mapSize` of zero or less disables snapping
+ * rather than dividing by it.
+ */
+export function fitDirectionalShadowToCamera(camera, lightOrientation, maxDistance, mapSize) {
+    const frustum = camera;
+    const camNear = typeof frustum.near === 'number' ? frustum.near : 0;
+    const camFar = typeof frustum.far === 'number' ? frustum.far : maxDistance;
+    // The two clamps are degenerate-input guards: far at least a hair past near, near never past far.
+    let far = Math.min(maxDistance, camFar);
+    far = Math.max(far, camNear + 0.001);
+    const near = Math.min(camNear, far);
+    const nearNdc = ndcDepthOf(camera, near);
+    const farNdc = ndcDepthOf(camera, far);
+    // The centroid of the eight corners. Both planes contribute four symmetric corners, so for an
+    // ordinary camera this is `(near + far) / 2` down -Z — but it is computed rather than assumed,
+    // because `setViewOffset` makes a frustum asymmetric and the fit is over the real corners.
+    _centroid.set(0, 0, 0);
+    for (const ndcZ of [nearNdc, farNdc]) {
+        for (const [x, y] of NDC_CORNERS) {
+            _centroid.add(_corner.set(x, y, ndcZ).applyMatrix4(camera.projectionMatrixInverse));
+        }
+    }
+    _centroid.multiplyScalar(1 / 8);
+    let radius = 0;
+    for (const ndcZ of [nearNdc, farNdc]) {
+        for (const [x, y] of NDC_CORNERS) {
+            radius = Math.max(radius, _corner.set(x, y, ndcZ).applyMatrix4(camera.projectionMatrixInverse).distanceTo(_centroid));
+        }
+    }
+    // One texel of margin, so the snapped box never clips its own outermost texel: the snap below
+    // moves the centre by up to half a texel on each lateral axis.
+    if (mapSize > 2)
+        radius *= mapSize / (mapSize - 2);
+    const center = _centroid.clone().applyMatrix4(camera.matrixWorld);
+    const texelWorldSize = mapSize > 0 ? (2 * radius) / mapSize : 0;
+    if (texelWorldSize > 0) {
+        center.applyQuaternion(_inverseLight.copy(lightOrientation).invert());
+        center.x = Math.round(center.x / texelWorldSize) * texelWorldSize;
+        center.y = Math.round(center.y / texelWorldSize) * texelWorldSize;
+        center.applyQuaternion(lightOrientation);
+    }
+    return { center, radius, texelWorldSize };
+}

package/dist/render/environment-capture.d.ts

@@ -0,0 +1,68 @@
+/**
+ * Restricting a scene for the duration of ONE environment capture, and asking
+ * a renderer whether it can run one at all.
+ *
+ * A cube capture renders the live scene into an offscreen target, so whatever
+ * it must exclude has to be turned off and turned back on around that single
+ * render — never left flipped, and never flipped through a renderer-wide
+ * switch (see {@link withCaptureShadows} for the measured reason). Both
+ * helpers restore in a `finally`, so a capture that throws does not leave the
+ * game altered.
+ *
+ * Consumers today: the `reflections` capability's native probe system, and
+ * `godot-compat`'s Godot 3 `ReflectionProbe`.
+ */
+import type { Scene, WebGLRenderer } from 'three';
+/**
+ * Hide everything a capture's cull mask excludes, for exactly one capture.
+ *
+ * The object's side of the test is three's OWN `Object3D.layers.mask`, never a
+ * parallel `userData` copy. An engine whose own per-object visibility layers
+ * are a 32-bit mask (Godot's `VisualInstance.layers` is the worked case) writes
+ * the authored mask straight onto the object and this reads it back. Both
+ * default an unannotated object to `1`, which no default mask excludes, so an
+ * ordinary scene is untouched.
+ */
+export declare function withCaptureMask(scene: Scene, mask: number, capture: () => void): void;
+/**
+ * Suppress every shadow-casting light for the duration of ONE capture — as
+ * per-light `LightShadow.intensity`, never as `renderer.shadowMap.enabled`.
+ *
+ * **The distinction is not stylistic; the global flag silently deletes every
+ * shadow in the game.** `renderer.shadowMap.enabled` is a program PARAMETER
+ * (`WebGLPrograms.getParameters` → `shadowMapEnabled`), and
+ * `WebGLRenderer.setProgram`'s `needsProgramChange` list does NOT watch it —
+ * three requires a material version bump for a flip to reach a material that is
+ * already compiled. So flipping it around the capture does nothing for compiled
+ * materials and everything for the one material compiling INSIDE the window —
+ * and a probe system installing a shader override sets `material.needsUpdate =
+ * true` in the same `update()` call that runs the capture, so every patched
+ * material links with `USE_SHADOWMAP` absent and keeps that program for the
+ * rest of the run.
+ *
+ * Measured on the real Godot 3.6 binary against that lane's emitted port (a
+ * white ground, a floating box, one straight-down `DirectionalLight`,
+ * PanoramaSky ambient, Filmic white 6): with NO probe the port's shadow pixel
+ * is `92,109,181` against Godot's `92,109,181`; adding ONE `ReflectionProbe`
+ * moved the port's shadow pixel to `218,222,232` — byte-identical to its own
+ * LIT ground, i.e. the shadow was gone — while Godot's moved to `109,146,201`.
+ * Asking the capture not to touch shadows at all restored `108,146,200`, which
+ * is what named the mechanism. The defect was Godot-shaped; the mechanism is a
+ * three.js contract, which is why the fix lives here.
+ *
+ * `LightShadow.intensity` is a UNIFORM (`shadowmap_pars_fragment`:
+ * `mix(1.0, shadow, shadowIntensity)`), refreshed from the light on every
+ * `renderer.render()`, so zeroing it for the capture costs no recompile and
+ * cannot outlive the `finally` that restores it.
+ */
+export declare function withCaptureShadows(scene: Scene, enabled: boolean, capture: () => void): void;
+/**
+ * Whether this renderer can run an environment capture at all.
+ *
+ * The editor's still design-time tree and headless runtimes deliberately supply
+ * no GPU. They must keep the authored scene and gameplay; only the
+ * renderer-owned capture is unavailable, so a probe system asks this and skips
+ * the capture rather than refusing to mount.
+ */
+export declare function canCaptureEnvironment(renderer: WebGLRenderer): boolean;
+//# sourceMappingURL=environment-capture.d.ts.map

package/dist/render/environment-capture.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"environment-capture.d.ts","sourceRoot":"","sources":["../../src/render/environment-capture.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AACH,OAAO,KAAK,EAAmB,KAAK,EAAE,aAAa,EAAE,MAAM,OAAO,CAAC;AAEnE;;;;;;;;;GASG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,KAAK,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,IAAI,GAAG,IAAI,CAYrF;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,KAAK,EAAE,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,IAAI,GAAG,IAAI,CAiB5F;AAED;;;;;;;GAOG;AACH,wBAAgB,qBAAqB,CAAC,QAAQ,EAAE,aAAa,GAAG,OAAO,CAGtE"}

package/dist/render/environment-capture.js

@@ -0,0 +1,90 @@
+/**
+ * Hide everything a capture's cull mask excludes, for exactly one capture.
+ *
+ * The object's side of the test is three's OWN `Object3D.layers.mask`, never a
+ * parallel `userData` copy. An engine whose own per-object visibility layers
+ * are a 32-bit mask (Godot's `VisualInstance.layers` is the worked case) writes
+ * the authored mask straight onto the object and this reads it back. Both
+ * default an unannotated object to `1`, which no default mask excludes, so an
+ * ordinary scene is untouched.
+ */
+export function withCaptureMask(scene, mask, capture) {
+    const hidden = [];
+    scene.traverse((object) => {
+        if ((object.layers.mask & mask) !== 0)
+            return;
+        hidden.push({ object, visible: object.visible });
+        object.visible = false;
+    });
+    try {
+        capture();
+    }
+    finally {
+        for (const entry of hidden)
+            entry.object.visible = entry.visible;
+    }
+}
+/**
+ * Suppress every shadow-casting light for the duration of ONE capture — as
+ * per-light `LightShadow.intensity`, never as `renderer.shadowMap.enabled`.
+ *
+ * **The distinction is not stylistic; the global flag silently deletes every
+ * shadow in the game.** `renderer.shadowMap.enabled` is a program PARAMETER
+ * (`WebGLPrograms.getParameters` → `shadowMapEnabled`), and
+ * `WebGLRenderer.setProgram`'s `needsProgramChange` list does NOT watch it —
+ * three requires a material version bump for a flip to reach a material that is
+ * already compiled. So flipping it around the capture does nothing for compiled
+ * materials and everything for the one material compiling INSIDE the window —
+ * and a probe system installing a shader override sets `material.needsUpdate =
+ * true` in the same `update()` call that runs the capture, so every patched
+ * material links with `USE_SHADOWMAP` absent and keeps that program for the
+ * rest of the run.
+ *
+ * Measured on the real Godot 3.6 binary against that lane's emitted port (a
+ * white ground, a floating box, one straight-down `DirectionalLight`,
+ * PanoramaSky ambient, Filmic white 6): with NO probe the port's shadow pixel
+ * is `92,109,181` against Godot's `92,109,181`; adding ONE `ReflectionProbe`
+ * moved the port's shadow pixel to `218,222,232` — byte-identical to its own
+ * LIT ground, i.e. the shadow was gone — while Godot's moved to `109,146,201`.
+ * Asking the capture not to touch shadows at all restored `108,146,200`, which
+ * is what named the mechanism. The defect was Godot-shaped; the mechanism is a
+ * three.js contract, which is why the fix lives here.
+ *
+ * `LightShadow.intensity` is a UNIFORM (`shadowmap_pars_fragment`:
+ * `mix(1.0, shadow, shadowIntensity)`), refreshed from the light on every
+ * `renderer.render()`, so zeroing it for the capture costs no recompile and
+ * cannot outlive the `finally` that restores it.
+ */
+export function withCaptureShadows(scene, enabled, capture) {
+    if (enabled) {
+        capture();
+        return;
+    }
+    const restored = [];
+    scene.traverse((object) => {
+        const light = object;
+        if (!light.isLight || light.shadow === undefined)
+            return;
+        restored.push({ shadow: light.shadow, intensity: light.shadow.intensity });
+        light.shadow.intensity = 0;
+    });
+    try {
+        capture();
+    }
+    finally {
+        for (const entry of restored)
+            entry.shadow.intensity = entry.intensity;
+    }
+}
+/**
+ * Whether this renderer can run an environment capture at all.
+ *
+ * The editor's still design-time tree and headless runtimes deliberately supply
+ * no GPU. They must keep the authored scene and gameplay; only the
+ * renderer-owned capture is unavailable, so a probe system asks this and skips
+ * the capture rather than refusing to mount.
+ */
+export function canCaptureEnvironment(renderer) {
+    const candidate = renderer;
+    return typeof candidate.compile === 'function' && candidate.coordinateSystem !== undefined;
+}

package/dist/render/ibl-override-material.d.ts

@@ -0,0 +1,97 @@
+/**
+ * Replace Three's image-based-lighting functions on a `MeshStandardMaterial`,
+ * per fragment, without forking three.
+ *
+ * A local-probe system cannot express itself as `material.envMap`: one envMap
+ * per object picks ONE environment for the whole draw, and the decisive work —
+ * which probe volume contains this fragment, how it fades at the boundary,
+ * what happens where volumes overlap — is per-fragment and can differ across a
+ * single `InstancedMesh`. Every such system therefore does the same three
+ * things to three's own program, and this module is that shared mechanism:
+ *
+ *   1. take `ShaderChunk.envmap_physical_pars_fragment` and rename its two
+ *      entry points, so the caller's replacement can still call them as its
+ *      fallback ({@link baseIblFunctions});
+ *   2. publish the fragment's world position as a varying, spliced into
+ *      `<worldpos_vertex>` under `USE_ENVMAP` ({@link IBL_WORLD_POSITION});
+ *   3. swap the fragment chunk for the caller's own GLSL and extend the
+ *      program cache key so the variant is not shared with an unpatched
+ *      material ({@link overrideMaterialIbl}).
+ *
+ * What the caller keeps is exactly what makes its system ITS system: the
+ * lighting model in the GLSL body, the uniforms behind it, and how probes are
+ * discovered, scheduled and captured. This module decides none of that — it
+ * hands back three's own shader object and gets out of the way.
+ *
+ * Consumers today: the `reflections` capability's native probe system, and
+ * `godot-compat`'s Godot 3 `ReflectionProbe`, whose per-fragment models are
+ * deliberately different renderers over this one splice.
+ */
+import { type Mesh, type MeshStandardMaterial } from 'three';
+/** The shader object three hands to `onBeforeCompile`. */
+export type IblOverrideShader = Parameters<MeshStandardMaterial['onBeforeCompile']>[0];
+/**
+ * The `varying vec3` the vertex splice publishes and the fragment body reads.
+ *
+ * It is ONE name across every consumer on purpose: the splice that declares it
+ * lives here, so a per-consumer name would be a string two files have to agree
+ * on with nothing checking that they do.
+ */
+export declare const IBL_WORLD_POSITION = "vgaiIblWorldPosition";
+/**
+ * Three's own IBL chunk with `getIBLIrradiance`/`getIBLRadiance` renamed to
+ * `getBaseIBLIrradiance`/`getBaseIBLRadiance`.
+ *
+ * A replacement chunk defines the original names itself; calling the renamed
+ * pair is how it falls back to the scene environment where no probe applies.
+ */
+export declare function baseIblFunctions(): string;
+/**
+ * Every material a mesh draws with that {@link overrideMaterialIbl} accepts.
+ *
+ * `isMeshStandardMaterial` is true for `MeshPhysicalMaterial` too, which is the
+ * intent: both compile the physical IBL chunk this module replaces.
+ */
+export declare function standardMaterialsOf(mesh: Mesh): readonly MeshStandardMaterial[];
+export interface IblOverrideOptions {
+    /**
+     * The GLSL that replaces `#include <envmap_physical_pars_fragment>`. Read at
+     * COMPILE time, not at install time, so a caller whose probe count is still
+     * settling does not have to reinstall to change it.
+     */
+    readonly fragment: () => string;
+    /**
+     * Appended to the material's own `customProgramCacheKey`, after a `|`. Must
+     * distinguish every shape of {@link IblOverrideOptions.fragment} the caller
+     * can produce — a probe COUNT belongs in here, because it changes the
+     * declared uniform array sizes.
+     */
+    readonly cacheKey: () => string;
+    /**
+     * Runs at the end of `onBeforeCompile`, with the shader three is compiling.
+     * Seed uniforms here: this is the only moment the caller is handed the
+     * object whose `uniforms` map the program will read.
+     */
+    readonly onCompile?: (shader: IblOverrideShader) => void;
+}
+export interface IblOverride {
+    readonly material: MeshStandardMaterial;
+    /**
+     * The shader three compiled this material with, or null before the first
+     * compile and after {@link IblOverride.restore}. Uniform writes go through
+     * `shader.uniforms`.
+     */
+    readonly shader: IblOverrideShader | null;
+    /** Put the material's own `onBeforeCompile`/`customProgramCacheKey` back. */
+    restore(): void;
+}
+/**
+ * Install the override. The returned handle is the only way to reach the
+ * compiled shader or to undo the patch; the material is otherwise untouched
+ * (in particular this never assigns `envMap`, which stays the caller's).
+ *
+ * The caller's own `onBeforeCompile` runs FIRST and its result is what gets
+ * spliced, so an override composes over a material that already had one.
+ */
+export declare function overrideMaterialIbl(material: MeshStandardMaterial, options: IblOverrideOptions): IblOverride;
+//# sourceMappingURL=ibl-override-material.d.ts.map

package/dist/render/ibl-override-material.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ibl-override-material.d.ts","sourceRoot":"","sources":["../../src/render/ibl-override-material.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,OAAO,EAAE,KAAK,IAAI,EAAE,KAAK,oBAAoB,EAAe,MAAM,OAAO,CAAC;AAE1E,0DAA0D;AAC1D,MAAM,MAAM,iBAAiB,GAAG,UAAU,CAAC,oBAAoB,CAAC,iBAAiB,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;AAEvF;;;;;;GAMG;AACH,eAAO,MAAM,kBAAkB,yBAAyB,CAAC;AAEzD;;;;;;GAMG;AACH,wBAAgB,gBAAgB,IAAI,MAAM,CAIzC;AAED;;;;;GAKG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,IAAI,GAAG,SAAS,oBAAoB,EAAE,CAK/E;AAED,MAAM,WAAW,kBAAkB;IACjC;;;;OAIG;IACH,QAAQ,CAAC,QAAQ,EAAE,MAAM,MAAM,CAAC;IAChC;;;;;OAKG;IACH,QAAQ,CAAC,QAAQ,EAAE,MAAM,MAAM,CAAC;IAChC;;;;OAIG;IACH,QAAQ,CAAC,SAAS,CAAC,EAAE,CAAC,MAAM,EAAE,iBAAiB,KAAK,IAAI,CAAC;CAC1D;AAED,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,QAAQ,EAAE,oBAAoB,CAAC;IACxC;;;;OAIG;IACH,QAAQ,CAAC,MAAM,EAAE,iBAAiB,GAAG,IAAI,CAAC;IAC1C,6EAA6E;IAC7E,OAAO,IAAI,IAAI,CAAC;CACjB;AAED;;;;;;;GAOG;AACH,wBAAgB,mBAAmB,CACjC,QAAQ,EAAE,oBAAoB,EAC9B,OAAO,EAAE,kBAAkB,GAC1B,WAAW,CAsCb"}

package/dist/render/ibl-override-material.js

@@ -0,0 +1,114 @@
+/**
+ * Replace Three's image-based-lighting functions on a `MeshStandardMaterial`,
+ * per fragment, without forking three.
+ *
+ * A local-probe system cannot express itself as `material.envMap`: one envMap
+ * per object picks ONE environment for the whole draw, and the decisive work —
+ * which probe volume contains this fragment, how it fades at the boundary,
+ * what happens where volumes overlap — is per-fragment and can differ across a
+ * single `InstancedMesh`. Every such system therefore does the same three
+ * things to three's own program, and this module is that shared mechanism:
+ *
+ *   1. take `ShaderChunk.envmap_physical_pars_fragment` and rename its two
+ *      entry points, so the caller's replacement can still call them as its
+ *      fallback ({@link baseIblFunctions});
+ *   2. publish the fragment's world position as a varying, spliced into
+ *      `<worldpos_vertex>` under `USE_ENVMAP` ({@link IBL_WORLD_POSITION});
+ *   3. swap the fragment chunk for the caller's own GLSL and extend the
+ *      program cache key so the variant is not shared with an unpatched
+ *      material ({@link overrideMaterialIbl}).
+ *
+ * What the caller keeps is exactly what makes its system ITS system: the
+ * lighting model in the GLSL body, the uniforms behind it, and how probes are
+ * discovered, scheduled and captured. This module decides none of that — it
+ * hands back three's own shader object and gets out of the way.
+ *
+ * Consumers today: the `reflections` capability's native probe system, and
+ * `godot-compat`'s Godot 3 `ReflectionProbe`, whose per-fragment models are
+ * deliberately different renderers over this one splice.
+ */
+import { ShaderChunk } from 'three';
+/**
+ * The `varying vec3` the vertex splice publishes and the fragment body reads.
+ *
+ * It is ONE name across every consumer on purpose: the splice that declares it
+ * lives here, so a per-consumer name would be a string two files have to agree
+ * on with nothing checking that they do.
+ */
+export const IBL_WORLD_POSITION = 'vgaiIblWorldPosition';
+/**
+ * Three's own IBL chunk with `getIBLIrradiance`/`getIBLRadiance` renamed to
+ * `getBaseIBLIrradiance`/`getBaseIBLRadiance`.
+ *
+ * A replacement chunk defines the original names itself; calling the renamed
+ * pair is how it falls back to the scene environment where no probe applies.
+ */
+export function baseIblFunctions() {
+    return ShaderChunk.envmap_physical_pars_fragment
+        .replaceAll('getIBLIrradiance', 'getBaseIBLIrradiance')
+        .replaceAll('getIBLRadiance', 'getBaseIBLRadiance');
+}
+/**
+ * Every material a mesh draws with that {@link overrideMaterialIbl} accepts.
+ *
+ * `isMeshStandardMaterial` is true for `MeshPhysicalMaterial` too, which is the
+ * intent: both compile the physical IBL chunk this module replaces.
+ */
+export function standardMaterialsOf(mesh) {
+    const materials = Array.isArray(mesh.material) ? mesh.material : [mesh.material];
+    return materials.filter((material) => Boolean(material.isMeshStandardMaterial));
+}
+/**
+ * Install the override. The returned handle is the only way to reach the
+ * compiled shader or to undo the patch; the material is otherwise untouched
+ * (in particular this never assigns `envMap`, which stays the caller's).
+ *
+ * The caller's own `onBeforeCompile` runs FIRST and its result is what gets
+ * spliced, so an override composes over a material that already had one.
+ */
+export function overrideMaterialIbl(material, options) {
+    const previousCompile = material.onBeforeCompile;
+    const previousCacheKey = material.customProgramCacheKey;
+    let compiled = null;
+    material.onBeforeCompile = (shader, renderer) => {
+        previousCompile.call(material, shader, renderer);
+        requireChunk(shader.vertexShader, '#include <worldpos_vertex>');
+        requireChunk(shader.fragmentShader, '#include <envmap_physical_pars_fragment>');
+        shader.vertexShader = `varying vec3 ${IBL_WORLD_POSITION};\n${shader.vertexShader.replace('#include <worldpos_vertex>', `#include <worldpos_vertex>
+#if defined(USE_ENVMAP)
+  ${IBL_WORLD_POSITION} = worldPosition.xyz;
+#endif`)}`;
+        shader.fragmentShader = `varying vec3 ${IBL_WORLD_POSITION};\n${shader.fragmentShader.replace('#include <envmap_physical_pars_fragment>', options.fragment())}`;
+        compiled = shader;
+        options.onCompile?.(shader);
+    };
+    material.customProgramCacheKey = () => `${previousCacheKey.call(material)}|${options.cacheKey()}`;
+    material.needsUpdate = true;
+    return {
+        material,
+        get shader() {
+            return compiled;
+        },
+        restore() {
+            material.onBeforeCompile = previousCompile;
+            material.customProgramCacheKey = previousCacheKey;
+            material.needsUpdate = true;
+            compiled = null;
+        },
+    };
+}
+/**
+ * A missing chunk is a NAMED error rather than a silent no-op.
+ *
+ * `String.replace` with no match returns the string unchanged, which would
+ * leave the varying declared and never assigned — a shader that links and
+ * renders the wrong thing. The only way to reach this today is a preceding
+ * `onBeforeCompile` in the same chain having already replaced the chunk (two
+ * IBL overrides stacked on one material), and that is worth a message naming
+ * the chunk instead of a black frame.
+ */
+function requireChunk(source, chunk) {
+    if (source.includes(chunk))
+        return;
+    throw new Error(`overrideMaterialIbl needs three's ${chunk} shader chunk, and this material's program no longer contains it.`);
+}

package/dist/runtime/game-input-seams.d.ts

@@ -0,0 +1,51 @@
+/**
+ * The GAME-SCOPED input wiring one world mount owns — HOST work performed from
+ * outside the world's own tree, shared verbatim by the three and canvas lanes
+ * (a project has ONE input map and one bot-input doctrine, whatever surface
+ * reads them).
+ *
+ * Two things happen here:
+ *
+ *  1. the project's input map is loaded through `Game.loadInputMap` (game-owned,
+ *     load-once), so the actions the project declared exist;
+ *  2. this root's seams are registered on the game-scoped debug registry
+ *     (`setVirtualInputTarget`/`setInputActionsSource`/`setInputTraceSource`),
+ *     which is what makes `game.input.hold/tap/...` (the bot/`vgai eval` input
+ *     doctrine) and the built-in `input.actions`/`input.trace` providers
+ *     resolve to this world instead of throwing `DEBUG_INPUT_UNAVAILABLE`.
+ *
+ * A world's React tree receives no vgai context — this wiring is precisely the
+ * part that never needed one: every closure below reads GAME-scoped state the
+ * host owns (`game.input`, `game.loop.fixedDt`, the game's seed).
+ *
+ * `optionalInputMap` is the CONVENTIONAL-PATH probe used when the project
+ * never named a map: an absent file is the ordinary state of a brand-new
+ * project, so it resolves quietly instead of printing an error on every boot.
+ * A map that exists and fails to parse is as loud as ever.
+ *
+ * LIFETIME, honestly: `registry.strip(id)` runs on the mount's dispose, but it
+ * walks providers/commands only — the three seams set here survive it, keyed
+ * by this world's id, until a remount of the same id overwrites them. That
+ * residue is inert rather than hidden: every closure reads game-scoped state,
+ * so a stale entry actuates exactly what a live one would. What it can still
+ * do is name a dead world in `DEBUG_INPUT_WORLD_NOT_FOUND`'s registered list.
+ * Do not write "the strip clears the input seams" anywhere without changing
+ * `strip` to actually do it.
+ */
+import type { DebugRegistry } from './debug-registry';
+import type { GameInternal } from './game';
+/** The conventional input-map location every scaffolded project ships
+ *  (`public/inputmaps/default.inputmap.json`). */
+export declare const DEFAULT_INPUT_MAP_PATH = "/inputmaps/default.inputmap.json";
+/** The slice of a host context this wiring reads — satisfied structurally by
+ *  both `ThreeHostContext` and `CanvasHostContext`. */
+export interface GameInputSeamHost {
+    readonly game?: GameInternal | null | undefined;
+    readonly headless?: boolean | undefined;
+}
+export declare function wireGameInputSeams(host: GameInputSeamHost, registry: DebugRegistry, options: {
+    readonly id: string;
+    readonly inputMapPath?: string | null | undefined;
+    readonly optionalInputMap?: boolean | undefined;
+}): Promise<void>;
+//# sourceMappingURL=game-input-seams.d.ts.map

package/dist/runtime/game-input-seams.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"game-input-seams.d.ts","sourceRoot":"","sources":["../../src/runtime/game-input-seams.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AAGH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AACtD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,QAAQ,CAAC;AAE3C;kDACkD;AAClD,eAAO,MAAM,sBAAsB,qCAAqC,CAAC;AAEzE;uDACuD;AACvD,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,IAAI,CAAC,EAAE,YAAY,GAAG,IAAI,GAAG,SAAS,CAAC;IAChD,QAAQ,CAAC,QAAQ,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;CACzC;AAED,wBAAgB,kBAAkB,CAChC,IAAI,EAAE,iBAAiB,EACvB,QAAQ,EAAE,aAAa,EACvB,OAAO,EAAE;IACP,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,CAAC;IAClD,QAAQ,CAAC,gBAAgB,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;CACjD,GACA,OAAO,CAAC,IAAI,CAAC,CAiDf"}