@vgai/engine 0.5.21 → 0.5.22

package/src/core/deferred-commands.ts

@@ -0,0 +1,174 @@
+/**
+ * `DeferredCommands` — work the caller runs at ONE point it chooses, plus the
+ * subject-keyed disposal that has to land after it.
+ *
+ * The hazard is not exotic and it is not a foreign engine's: it is what a
+ * Rapier world does to anything that mutates it from inside a callback. Disable
+ * a collider while the solver is iterating, or free the node a collision
+ * handler was dispatched ON, and the failure is either a corrupt step or
+ * Rapier's own "recursive use of an object ... unsafe aliasing in rust". The
+ * remedy is always the same shape — write down WHAT to do, do it once the frame
+ * is out of anybody's way — and every caller that needs it was previously
+ * hand-rolling an array.
+ *
+ * ## The one point is the CALLER's, deliberately
+ *
+ * There is no `queueMicrotask`, no `setTimeout(0)`, no `requestAnimationFrame`
+ * and no subscription anywhere in this module. Whoever builds the queue decides
+ * where {@link DeferredCommands.drain} runs — after physics, at the tail of a
+ * world's update, wherever the frame's quiet moment actually is. A queue nobody
+ * drains simply does not run its work, which is a visible failure rather than a
+ * silent reordering onto a timeline the game does not control.
+ *
+ * ## This is NOT `SimClock`, and `after(0)` is not a substitute
+ *
+ * `core/sim-clock.ts` schedules on SIM TIME: `after(0, fn)` scheduled mid-frame
+ * does land in that frame's tail flush (`runtime/game.ts` calls `flush(simT)`
+ * after every phase of every world), so the resemblance is real and worth
+ * naming. Three things make it the wrong tool for deferral:
+ *
+ *  - **A paused world never flushes.** `flush` is inside `runFrameImpl`'s
+ *    `advanced` guard, so a game that pauses between the defer and the drain
+ *    holds the work forever. End-of-frame deferral has to run on the frame,
+ *    not on the clock.
+ *  - **No subject identity.** Deferring destruction needs "this object, once",
+ *    and needs the two questions that fall out of it —
+ *    {@link DeferredCommands.isDisposePending} (a handler must be able to skip
+ *    a subject that is already going away) and
+ *    {@link DeferredCommands.wasDisposed} (an owner sweeping its own indexes
+ *    after the drain). A time-ordered timer set answers neither.
+ *  - **No same-drain re-entry.** A sim timer scheduled during a flush is
+ *    deliberately never due in that flush; a deferred command that defers one
+ *    more command must still land this frame, or the second write arrives a
+ *    frame after the first and the two are no longer atomic.
+ *
+ * ## Ordering, and why disposal goes last
+ *
+ * {@link DeferredCommands.drain} runs every deferred command first, re-draining
+ * until the queue is empty, and only then disposes every pending subject. That
+ * order is not cosmetic: a deferred write to a subject that is ALSO queued for
+ * disposal must still happen — it is what the caller asked for — and disposing
+ * first would make that write operate on a freed handle. A subject queued twice
+ * is disposed once, and the FIRST thunk wins (every caller for one subject
+ * passes the same one).
+ *
+ * The re-drain is bounded by {@link MAX_DRAIN_PASSES}. A command that defers
+ * itself forever is a bug in the caller, and a bounded loop names it in a
+ * millisecond instead of hanging the frame.
+ *
+ * ## Why disposal carries its own thunk
+ *
+ * Disposal is the one thing here that is not surface-neutral. A `PIXI.Container`
+ * ends with `removeFromParent()` + `destroy({ children })`; a `THREE.Object3D`
+ * ends by detaching and disposing the geometries and materials underneath it;
+ * a physics-backed entity has a Rapier body to pull first. This queue does none
+ * of that — it takes the thunk from whoever owns the surface and runs it at the
+ * drain. So the ORDERING lives here once and the surface knowledge stays where
+ * the surface is, which is what lets one queue serve a 2D world and a 3D one.
+ *
+ * ## Resource ownership
+ *
+ * **Owner:** whoever calls {@link createDeferredCommands}, and that owner is
+ * also the only caller of `drain()` — a queue is per-DRAINER, not per-process,
+ * so two mounted games are two queues and neither can see the other's work.
+ * This module registers nothing anywhere: there is no game-scoped slot (unlike
+ * `sim-clock.ts`, which needs one because every world on a Game shares one
+ * clock) and no module-level state at all.
+ * **Sharers:** the queued subjects, by reference, and only until the drain that
+ * disposes them.
+ * **Teardown:** dropping the queue. There is deliberately no `dispose()` —
+ * nothing here holds a handle, a listener or a timer, and a queue dropped with
+ * work still in it has simply not run that work, which is what discarding a
+ * frame means.
+ */
+
+/**
+ * How many times {@link DeferredCommands.drain} re-drains a queue that keeps
+ * refilling itself before declaring the caller's own logic non-terminating.
+ *
+ * A bound that correct code cannot reach (a deferred command that defers one
+ * more, ten deep) while catching the infinite case immediately.
+ */
+export const MAX_DRAIN_PASSES = 16;
+
+/** The queue. Build one per drainer with {@link createDeferredCommands}. */
+export interface DeferredCommands {
+  /**
+   * Run `command` at the next {@link DeferredCommands.drain}.
+   *
+   * ```ts
+   * // inside a collision handler, where the solver still owns the world:
+   * frame.defer(() => collider.setSensor(true));
+   * ```
+   */
+  defer(command: () => void): void;
+  /**
+   * Dispose `subject` at the next drain, after every deferred command has run.
+   * Queuing the same subject twice disposes it once — the first `dispose`
+   * thunk wins.
+   */
+  deferDispose(subject: object, dispose: () => void): void;
+  /**
+   * Is `subject` queued for disposal and not yet disposed? Read by a handler
+   * that must skip a subject already on its way out.
+   */
+  isDisposePending(subject: object): boolean;
+  /**
+   * Has THIS queue already disposed `subject`? Read after a drain by an owner
+   * sweeping its own indexes (a group, a registry, a spatial bucket) — "am I
+   * destroyed" is a surface-specific question that a plain `Object3D` has no
+   * answer to, so the queue is asked instead.
+   */
+  wasDisposed(subject: object): boolean;
+  /** Run every deferred command (re-draining), then dispose every pending
+   *  subject. Called once per frame, by the owner, at the point it chose. */
+  drain(): void;
+}
+
+/** Build one queue. See the module header for who owns it and who drains it. */
+export function createDeferredCommands(): DeferredCommands {
+  let commands: (() => void)[] = [];
+  const doomed = new Map<object, () => void>();
+  const disposed = new WeakSet<object>();
+
+  return {
+    defer(command): void {
+      commands.push(command);
+    },
+
+    deferDispose(subject, dispose): void {
+      if (!doomed.has(subject)) doomed.set(subject, dispose);
+    },
+
+    isDisposePending(subject): boolean {
+      return doomed.has(subject);
+    },
+
+    wasDisposed(subject): boolean {
+      return disposed.has(subject);
+    },
+
+    drain(): void {
+      let passes = 0;
+      while (commands.length > 0) {
+        if (++passes > MAX_DRAIN_PASSES) {
+          throw new Error(
+            `DeferredCommands.drain: still queueing more work after ${MAX_DRAIN_PASSES} passes. ` +
+              'Something passed to defer() defers itself, so this drain would never terminate.',
+          );
+        }
+        const batch = commands;
+        commands = [];
+        for (const command of batch) command();
+      }
+
+      // Subjects last, and only after every deferred command has run — see the
+      // module header's ordering section.
+      for (const [subject, dispose] of doomed) {
+        dispose();
+        disposed.add(subject);
+      }
+      doomed.clear();
+    },
+  };
+}

package/src/core/sim-clock.ts

@@ -105,8 +105,20 @@
  *
  * ## Deliberately absent
  *
- *  - **No `every`/`repeat`/interval.** Nothing needs one, and `after`
- *    re-arming itself is three lines the game owns.
+ *  - **No `every`/`repeat`/interval — that is `core/countdown-timer.ts`.**
+ *    This header used to say an `after` re-arming itself was "three lines the
+ *    game owns"; it is three lines that DRIFT, because re-arming schedules the
+ *    next fire from the moment the callback ran, so every long frame
+ *    permanently lengthens the interval. A repeating interval needs
+ *    overshoot carry and multi-fire on a big step to keep its event count
+ *    right, and it is stepped by its owner rather than by the clock. Both
+ *    belong to a countdown object, not to a sim-time one-shot.
+ *  - **No end-of-frame command queue — that is
+ *    `core/deferred-commands.ts`.** `after(0, fn)` looks like one (the flush
+ *    below does run at the tail of the frame that scheduled it) and is not:
+ *    it holds the work forever across a pause, it has no subject identity, and
+ *    a command it schedules during a flush waits a whole extra frame. See that
+ *    module's header for all three.
  *  - **No fiber kernel, no coroutine emulation, no `task.spawn`.** Calling an
  *    `async function` *is* `task.spawn` — the language already has it.
  *  - **No wall clock.** This module reads no system timer and creates no

package/src/dev/instruments.ts

@@ -25,13 +25,13 @@
  * game registry.
  *
  * ── THE DOOR ────────────────────────────────────────────────────────────────
- * This module is IMPLEMENTATION ONLY. It publishes nothing itself: the dev-tools
- * capability's own registry adopts this list (`installDevToolsInstruments`) and
- * publishes each instrument through the SAME door every declaration in that
- * capability uses — one provider per reading (`instrument.timescale`), one
- * command per action (`instrument.timescale.set`), plus the `dev-tools` index
- * provider. That is deliberate and load-bearing: the registry IS the product,
- * so every reader of an instrument reaches the SAME registration.
+ * The HOST publishes these itself ({@link publishDevInstruments}, called by
+ * the mount install paths): one provider per reading
+ * (`instrument.timescale`), one command per action
+ * (`instrument.timescale.set`), plus the `instruments` index provider. The
+ * registry IS the product, so every reader of an instrument reaches the SAME
+ * registration — and a game writes zero lines and mounts nothing to have
+ * them.
  *
  * ── DEGRADING ───────────────────────────────────────────────────────────────
  * An instrument whose subject this game does not have (no physics adapter ⇒ no
@@ -42,16 +42,17 @@
  *
  * ── RESOURCE OWNERSHIP, STATED ONCE ─────────────────────────────────────────
  * {@link createDevInstruments} owns everything it allocates: the frame-time
- * ring buffer and its ONE `game.onRenderStep` subscription. SHARER: the
- * dev-tools capability's `DevToolsBridge`, which creates one set per mounted
- * game. TEARDOWN: the returned {@link DevInstrumentSet.dispose} — the ONE path
- * that ends it. Nothing else here holds a resource; the time-scale, pause and
+ * ring buffer and its ONE `game.onRenderStep` subscription. SHARER: the host
+ * install path ({@link publishDevInstruments}), which creates one set per
+ * mounted game. TEARDOWN: the returned {@link DevInstrumentSet.dispose} — the
+ * ONE path that ends it. Nothing else here holds a resource; the time-scale, pause and
  * collider instruments only drive state that `Game` already owns.
  */
 
 import { z } from 'zod';
 import { nodeKeyedPhysics } from '../adapter/system-adapter';
 import { clampTimeScale, TIME_SCALE_RANGE } from '../core/frame-pacing';
+import { getDebugRegistry } from '../runtime/debug-registry';
 import type { Game } from '../runtime/game';
 
 /** What shape an instrument's reading is, and what drives it. Data, not
@@ -304,3 +305,99 @@ export function createDevInstruments(game: Game): DevInstrumentSet {
 function now(): number {
   return typeof performance === 'undefined' ? Date.now() : performance.now();
 }
+
+// ---------------------------------------------------------------------------
+// Host publication — the instruments' OWN door
+// ---------------------------------------------------------------------------
+//
+// The HOST publishes these (the editor's mount install path), so every game
+// gets them for literally zero lines — no capability, no bridge component, no
+// mount. One provider per reading (`instrument.timescale`), one command per
+// action (`instrument.timescale.set`), plus ONE index provider
+// (`instruments`) carrying every descriptor with this instant's values, so an
+// outside reader gets the whole panel in one round trip. Naming is unchanged
+// from when the dev-tools capability published them, so every existing reader
+// keeps working; only the publisher moved realms.
+
+/** The index provider's name. */
+export const INSTRUMENTS_PROVIDER = 'instruments';
+
+/** The registry scope the host publishes under. Not a mounted world —
+ *  instruments are game-scoped host furniture, like the hooks' `__react__`. */
+const INSTRUMENTS_WORLD_ID = '__instruments__';
+
+/** One instrument in the index: descriptor plus this instant's value. A
+ *  throwing read is reported as itself, never swallowed. */
+export interface PublishedInstrumentReading {
+  readonly name: string;
+  readonly id: string;
+  readonly label: string;
+  readonly hint: string;
+  readonly unit?: string;
+  readonly control: DevInstrumentControl;
+  readonly actions: readonly {
+    readonly name: string;
+    readonly id: string;
+    readonly label: string;
+    readonly hint: string;
+  }[];
+  readonly value: unknown;
+  readonly error?: string;
+}
+
+function readingOf(instrument: DevInstrument): PublishedInstrumentReading {
+  const base = {
+    name: `instrument.${instrument.id}`,
+    id: instrument.id,
+    label: instrument.label,
+    hint: instrument.hint,
+    ...(instrument.unit === undefined ? {} : { unit: instrument.unit }),
+    control: instrument.control,
+    actions: instrument.actions.map((action) => ({
+      name: `instrument.${instrument.id}.${action.id}`,
+      id: action.id,
+      label: action.label,
+      hint: action.hint,
+    })),
+  };
+  try {
+    return { ...base, value: instrument.read() };
+  } catch (error) {
+    return { ...base, value: null, error: error instanceof Error ? error.message : String(error) };
+  }
+}
+
+/**
+ * Create this game's instrument set and register every door on its debug
+ * registry. Called once per mounted Game by the host install path; the
+ * returned disposer ends the set's one resource (the frame-time
+ * subscription) — the registrations die with the Game itself.
+ */
+export function publishDevInstruments(game: Game): () => void {
+  const registry = getDebugRegistry(game);
+  if (!registry) {
+    throw new Error('Cannot publish dev instruments: mounted Game has no debug registry.');
+  }
+  const set = createDevInstruments(game);
+  const scope = registry.forRoot(INSTRUMENTS_WORLD_ID);
+  for (const instrument of set.instruments) {
+    scope.registerStateProvider(`instrument.${instrument.id}`, () => instrument.read(), {
+      tier: 'assisted',
+    });
+    for (const action of instrument.actions) {
+      scope.registerCommand(
+        `instrument.${instrument.id}.${action.id}`,
+        {
+          description: `${instrument.label}: ${action.label} — ${action.hint}`,
+          locus: 'client',
+          args: action.args,
+        },
+        (...values: unknown[]) => action.run(values),
+      );
+    }
+  }
+  scope.registerStateProvider(INSTRUMENTS_PROVIDER, () => set.instruments.map(readingOf), {
+    tier: 'assisted',
+  });
+  return () => set.dispose();
+}

package/src/input/input-manager.ts

@@ -1797,6 +1797,21 @@ export class InputManager {
     return this.gamepadButtonsJustUp.has(`${index}:${button}`);
   }
 
+  /**
+   * The RAW `Gamepad.axes[axis]` of the first connected pad, gated on `inputActive`.
+   *
+   * Deliberately un-deadzoned, and it must stay that way. The engine's own stick deadzone lives on
+   * the ACTION path (`gamepad_axis` / `gamepad_axis_pair`, default
+   * `GAMEPAD_AXIS_DEFAULT_DEADZONE`), where a game declares it and can override it per binding.
+   * This door exists for a caller that must apply a DIFFERENT rule — every foreign-engine compat
+   * lane does: Unity's `Gamepad.leftStick` carries a `StickDeadzone` processor with its own
+   * 0.125/0.925 (`unity-compat/input-system-device.ts` reproduces it), and Godot's `get_axis`
+   * has its own. Baking one engine's constants in here would silently give every other lane the
+   * wrong feel under its own API name.
+   *
+   * So: a caller that wants "a stick" wants a deadzone and must say WHOSE. A caller that wants
+   * the hardware number calls this.
+   */
   getDeviceGamepadAxis(axis: number): number {
     if (!this.inputActive) return 0;
     const index = this.firstConnectedGamepadIndex();

package/src/render/directional-shadow-fit.ts

@@ -0,0 +1,156 @@
+/**
+ * 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;
+}
+
+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: readonly (readonly [number, number])[] = [
+  [-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: Camera, viewDepth: number): number {
+  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: Camera,
+  lightOrientation: Quaternion,
+  maxDistance: number,
+  mapSize: number,
+): DirectionalShadowFit {
+  const frustum = camera as Camera & { near?: number; far?: number };
+  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/src/render/environment-capture.ts

@@ -0,0 +1,102 @@
+/**
+ * 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 { Light, Object3D, 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 function withCaptureMask(scene: Scene, mask: number, capture: () => void): void {
+  const hidden: { object: Object3D; visible: boolean }[] = [];
+  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: Scene, enabled: boolean, capture: () => void): void {
+  if (enabled) {
+    capture();
+    return;
+  }
+  const restored: { shadow: { intensity: number }; intensity: number }[] = [];
+  scene.traverse((object) => {
+    const light = object as Light & { shadow?: { intensity: number } };
+    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: WebGLRenderer): boolean {
+  const candidate = renderer as WebGLRenderer & { compile?: unknown; coordinateSystem?: unknown };
+  return typeof candidate.compile === 'function' && candidate.coordinateSystem !== undefined;
+}