@vgai/engine 0.5.12 → 0.5.14

package/src/render/voxel-surface.ts

@@ -0,0 +1,358 @@
+/**
+ * A face-culled surface mesh for a dense grid of cubic cells, as one real `THREE.BufferGeometry`.
+ *
+ * A game that stores its world as a grid of cubes — terrain a player digs, a builder's block
+ * palette, a level authored as a 3D tilemap — cannot draw a `BoxGeometry` per cell: a modest
+ * 80×7×80 volume is 44 800 boxes, and the ones buried inside the solid are invisible forever. The
+ * fix is a single surface built from only the faces that touch an empty neighbour. That is what
+ * this file is, and it is the whole of it.
+ *
+ * ## It is a HELPER, not a wrapper
+ *
+ * `buildVoxelSurface` takes plain arrays and hands back three's own `BufferGeometry`. Every call
+ * after it is three's API — pick your own material, wrap it in a `Mesh` or an `InstancedMesh`,
+ * `.translate()` it, hand it to Rapier's trimesh collider. Nothing here holds a scene, a camera, a
+ * frame loop or a cache, and nothing here is a class you inherit from.
+ *
+ * ## The rung audit that put ~200 lines here instead of a dependency (2026-08-14)
+ *
+ * Checked against the npm registry on the day this landed, not from memory:
+ *
+ *  - **`voxel-mesh` 0.3.0** (voxel.js) — last publish **2013-06-13**. Its `index.js` builds a
+ *    `THREE.Geometry` out of `THREE.Face3`, both REMOVED from three in r125. It cannot run against
+ *    this repo's three at all.
+ *  - **`voxel-mesher` 0.14.4** (2016-03-26) and **`greedy-mesher` 1.0.3** (2016-02-12) — the
+ *    voxel.js meshing pair. Both are `ndarray`-shaped, untyped, and stop at a list of quads: the
+ *    `BufferGeometry` is still yours to write. `voxel-mesher` additionally pulls a WebGL1 buffer
+ *    stack (`gl-buffer`, `gl-vao`) that has nothing to do with three.
+ *  - **`voxel-engine` 0.20.2** (2015-04-11) — a whole game framework (20 dependencies, its own
+ *    camera, controls and physics). The thing this rule bans.
+ *  - **`@voxelize/core` 3.0.0** (2026-08-03) — the one MAINTAINED option, and the one to say no to
+ *    deliberately. It is a client for a multiplayer voxel platform: `socket.io-client`, its own
+ *    wire protocol, its own physics engine and a WASM mesher fed by its own chunk/world objects.
+ *    You do not call its mesher; you build your game inside it. Adopting it to draw a static grid
+ *    would put a platform between the game and three.
+ *
+ * So: every maintained option is an ENGINE you build inside, and every option that is a helper died
+ * with voxel.js a decade ago against a three that no longer exists. The general shape *is* ready —
+ * "cull the hidden faces of a dense grid" has been settled since 2012 — it is the packaging that is
+ * not. Hence a helper here, in host vocabulary, that hands back three's own object.
+ *
+ * ## What is deliberately NOT here
+ *
+ * **Greedy meshing.** Merging coplanar same-type faces into larger quads is the standard next step
+ * and it does not fall out of this one: it needs a per-slice sweep with its own visited mask and
+ * its own bugs, and it changes the vertex↔cell relationship that per-face culling keeps exact.
+ * Per-face culling already removes the interior, which is the order-of-magnitude win. Add greedy
+ * meshing the day a measured frame budget asks for it, as its own function beside this one.
+ *
+ * **Lighting, ambient occlusion, textures, atlases, transparency sorting and chunking.** Each is a
+ * real decision a game makes for itself; this returns geometry and gets out of the way.
+ */
+import { BufferAttribute, BufferGeometry, Color } from 'three';
+
+/**
+ * A dense grid of cubic cells.
+ *
+ * `cells` is indexed **Y-major, then Z, then X** — `((y * sizeZ) + z) * sizeX + x`. Y outermost is
+ * the ordering that makes each horizontal LAYER contiguous, which is what lets a mostly-flat world
+ * ship as a handful of runs (see {@link expandVoxelRuns}) instead of a megabyte of literals.
+ */
+export interface VoxelVolume {
+  /** Cell counts along X, Y and Z. */
+  readonly size: readonly [number, number, number];
+  /** `sizeX * sizeY * sizeZ` type ids. `0` is empty unless {@link VoxelSurfaceOptions.emptyType}. */
+  readonly cells: ArrayLike<number>;
+  /** World position of the volume's minimum corner. Defaults to the origin. */
+  readonly origin?: readonly [number, number, number];
+  /** World edge length of one cell. Defaults to 1. */
+  readonly cellSize?: number;
+}
+
+export interface VoxelSurfaceOptions {
+  /**
+   * Type id → `0xRRGGBB`, written into the geometry's `color` attribute. Supply it and the mesh
+   * draws with `vertexColors: true` in one draw call; omit it and the geometry carries no colour
+   * attribute at all. A solid type absent from the map is an ERROR, not a silent default: a
+   * missing colour is the shape of a forgotten row, and a mesh that quietly paints it white looks
+   * like a lighting bug three files away.
+   */
+  readonly colors?: ReadonlyMap<number, number>;
+  /** The type id that means "no cell here". Defaults to `0`. */
+  readonly emptyType?: number;
+  /**
+   * Whether cells just outside the volume count as solid. `false` (the default) walls the volume
+   * in — the right answer for a standalone model. `true` leaves the boundary open, which is what a
+   * chunk meshed beside its neighbours wants.
+   */
+  readonly closedBoundary?: boolean;
+}
+
+export interface VoxelSurface {
+  /** Indexed, with `position`, `normal` and (when colours were supplied) `color`. */
+  readonly geometry: BufferGeometry;
+  /** Faces that survived culling. `vertices` is `4 ×` this, `triangles` `2 ×`. */
+  readonly quads: number;
+  readonly vertices: number;
+  readonly triangles: number;
+  /** Cells whose type is not the empty type — the input's own size, for a sanity check. */
+  readonly solidCells: number;
+  /** Faces contributed per type id, in ascending id order. */
+  readonly quadsByType: ReadonlyMap<number, number>;
+}
+
+export class VoxelSurfaceError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = 'VoxelSurfaceError';
+  }
+}
+
+/**
+ * The six faces of the unit cell, each as four corners in counter-clockwise order seen from
+ * OUTSIDE — which is the winding three's default `FrontSide` draws.
+ */
+const FACES: readonly {
+  readonly normal: readonly [number, number, number];
+  readonly corners: readonly (readonly [number, number, number])[];
+}[] = [
+  {
+    normal: [1, 0, 0],
+    corners: [
+      [1, 0, 1],
+      [1, 0, 0],
+      [1, 1, 0],
+      [1, 1, 1],
+    ],
+  },
+  {
+    normal: [-1, 0, 0],
+    corners: [
+      [0, 0, 0],
+      [0, 0, 1],
+      [0, 1, 1],
+      [0, 1, 0],
+    ],
+  },
+  {
+    normal: [0, 1, 0],
+    corners: [
+      [0, 1, 1],
+      [1, 1, 1],
+      [1, 1, 0],
+      [0, 1, 0],
+    ],
+  },
+  {
+    normal: [0, -1, 0],
+    corners: [
+      [0, 0, 0],
+      [1, 0, 0],
+      [1, 0, 1],
+      [0, 0, 1],
+    ],
+  },
+  {
+    normal: [0, 0, 1],
+    corners: [
+      [0, 0, 1],
+      [1, 0, 1],
+      [1, 1, 1],
+      [0, 1, 1],
+    ],
+  },
+  {
+    normal: [0, 0, -1],
+    corners: [
+      [1, 0, 0],
+      [0, 0, 0],
+      [0, 1, 0],
+      [1, 1, 0],
+    ],
+  },
+];
+
+/**
+ * Expand `[count, type, count, type, …]` run pairs into a dense cell array.
+ *
+ * A voxel volume is enormous and almost entirely repetitive, so the compact form is what a game
+ * SHIPS — in a source file, in a save, over the wire — and the dense form is what it meshes. The
+ * total of the counts must be exactly `cellCount`: a short or long run list is a corrupt volume,
+ * and silently padding it with empties would mesh a plausible wrong world.
+ */
+export function expandVoxelRuns(
+  runs: ArrayLike<number>,
+  cellCount: number,
+): Uint16Array | Uint32Array {
+  if (runs.length % 2 !== 0) {
+    throw new VoxelSurfaceError(
+      `a run list is [count, type] pairs, so its length must be even; got ${runs.length}`,
+    );
+  }
+  let widest = 0;
+  let total = 0;
+  for (let pair = 0; pair < runs.length; pair += 2) {
+    const count = runs[pair] as number;
+    if (!Number.isInteger(count) || count <= 0) {
+      throw new VoxelSurfaceError(`run ${pair / 2} has a count of ${count}; counts are positive`);
+    }
+    total += count;
+    widest = Math.max(widest, runs[pair + 1] as number);
+  }
+  if (total !== cellCount) {
+    throw new VoxelSurfaceError(`the runs cover ${total} cells; the volume holds ${cellCount}`);
+  }
+  const cells = widest > 0xffff ? new Uint32Array(cellCount) : new Uint16Array(cellCount);
+  let at = 0;
+  for (let pair = 0; pair < runs.length; pair += 2) {
+    const count = runs[pair] as number;
+    cells.fill(runs[pair + 1] as number, at, at + count);
+    at += count;
+  }
+  return cells;
+}
+
+/** The volume's size, after checking that the cell array is exactly the size it claims. */
+function assertVolumeShape(volume: VoxelVolume): readonly [number, number, number] {
+  const [sizeX, sizeY, sizeZ] = volume.size;
+  if (sizeX <= 0 || sizeY <= 0 || sizeZ <= 0) {
+    throw new VoxelSurfaceError(`a volume needs a positive size on every axis; got ${volume.size}`);
+  }
+  const cellCount = sizeX * sizeY * sizeZ;
+  if (volume.cells.length !== cellCount) {
+    throw new VoxelSurfaceError(
+      `a ${sizeX}×${sizeY}×${sizeZ} volume holds ${cellCount} cells; got ${volume.cells.length}`,
+    );
+  }
+  return [sizeX, sizeY, sizeZ];
+}
+
+/** Every array the walk appends to, so the per-cell step is a plain function. */
+interface SurfaceBuffers {
+  readonly positions: number[];
+  readonly normals: number[];
+  readonly colors: number[];
+  readonly indices: number[];
+  readonly quadsByType: Map<number, number>;
+}
+
+/** The linear-space vertex colour for one type, or `undefined` when colours were not asked for. */
+function vertexColor(
+  colors: ReadonlyMap<number, number> | undefined,
+  type: number,
+  where: string,
+  into: Color,
+): Color | undefined {
+  if (colors === undefined) return undefined;
+  const hex = colors.get(type);
+  if (hex === undefined) {
+    throw new VoxelSurfaceError(
+      `no colour for type ${type}, which cell ${where} holds — every solid type in the volume ` +
+        'needs a row, so a forgotten one fails here rather than drawing white',
+    );
+  }
+  // `setHex` defaults to `SRGBColorSpace` and converts INTO the working space itself, which is
+  // exactly what a material does with a colour uniform. Do not convert again on top of it: an
+  // extra `convertSRGBToLinear()` here squared the conversion and drew a mid-green world in near
+  // black, with every channel still plausible enough to read as a lighting problem.
+  return into.setHex(hex);
+}
+
+/** Append the faces of one solid cell that face an empty neighbour. Returns how many. */
+function emitCellFaces(
+  buffers: SurfaceBuffers,
+  cell: readonly [number, number, number],
+  type: number,
+  color: Color | undefined,
+  solidAt: (x: number, y: number, z: number) => boolean,
+  place: (x: number, y: number, z: number) => [number, number, number],
+): number {
+  const [x, y, z] = cell;
+  let emitted = 0;
+  for (const face of FACES) {
+    const [nx, ny, nz] = face.normal;
+    if (solidAt(x + nx, y + ny, z + nz)) continue;
+    const base = buffers.positions.length / 3;
+    for (const [cx, cy, cz] of face.corners) {
+      buffers.positions.push(...place(x + cx, y + cy, z + cz));
+      buffers.normals.push(nx, ny, nz);
+      if (color !== undefined) buffers.colors.push(color.r, color.g, color.b);
+    }
+    buffers.indices.push(base, base + 1, base + 2, base, base + 2, base + 3);
+    buffers.quadsByType.set(type, (buffers.quadsByType.get(type) ?? 0) + 1);
+    emitted += 1;
+  }
+  return emitted;
+}
+
+/**
+ * Build the visible surface of a voxel volume: one indexed `BufferGeometry` carrying every face
+ * that touches an empty neighbour, and nothing else.
+ */
+export function buildVoxelSurface(
+  volume: VoxelVolume,
+  options: VoxelSurfaceOptions = {},
+): VoxelSurface {
+  const [sizeX, sizeY, sizeZ] = assertVolumeShape(volume);
+  const empty = options.emptyType ?? 0;
+  const openBoundary = options.closedBoundary !== true;
+  const scale = volume.cellSize ?? 1;
+  const [originX, originY, originZ] = volume.origin ?? [0, 0, 0];
+  const cells = volume.cells;
+
+  const at = (x: number, y: number, z: number): number =>
+    cells[(y * sizeZ + z) * sizeX + x] as number;
+  const solidAt = (x: number, y: number, z: number): boolean => {
+    const outsideVolume = x < 0 || y < 0 || z < 0 || x >= sizeX || y >= sizeY || z >= sizeZ;
+    return outsideVolume ? !openBoundary : at(x, y, z) !== empty;
+  };
+  const place = (x: number, y: number, z: number): [number, number, number] => [
+    originX + x * scale,
+    originY + y * scale,
+    originZ + z * scale,
+  ];
+
+  const buffers: SurfaceBuffers = {
+    positions: [],
+    normals: [],
+    colors: [],
+    indices: [],
+    quadsByType: new Map(),
+  };
+  const scratch = new Color();
+  let solidCells = 0;
+  let quads = 0;
+  for (let y = 0; y < sizeY; y += 1) {
+    for (let z = 0; z < sizeZ; z += 1) {
+      for (let x = 0; x < sizeX; x += 1) {
+        const type = at(x, y, z);
+        if (type === empty) continue;
+        solidCells += 1;
+        const color = vertexColor(options.colors, type, `(${x}, ${y}, ${z})`, scratch);
+        quads += emitCellFaces(buffers, [x, y, z], type, color, solidAt, place);
+      }
+    }
+  }
+
+  const geometry = new BufferGeometry();
+  geometry.setAttribute('position', new BufferAttribute(new Float32Array(buffers.positions), 3));
+  geometry.setAttribute('normal', new BufferAttribute(new Float32Array(buffers.normals), 3));
+  if (options.colors !== undefined) {
+    geometry.setAttribute('color', new BufferAttribute(new Float32Array(buffers.colors), 3));
+  }
+  const vertices = buffers.positions.length / 3;
+  const indices =
+    vertices > 0xffff ? new Uint32Array(buffers.indices) : new Uint16Array(buffers.indices);
+  geometry.setIndex(new BufferAttribute(indices, 1));
+  geometry.computeBoundingSphere();
+  geometry.computeBoundingBox();
+
+  return {
+    geometry,
+    quads,
+    vertices,
+    triangles: quads * 2,
+    solidCells,
+    quadsByType: new Map([...buffers.quadsByType].sort(([a], [b]) => a - b)),
+  };
+}

package/src/runtime/create-runtime.ts

@@ -832,6 +832,13 @@ async function createRootsGameRuntime(config: RootsRuntimeConfig): Promise<GameS
     const isReact = kindById.get(entry.id) === 'dom';
     const surface = document.createElement(isReact ? 'div' : 'canvas') as HTMLElement;
     surface.dataset['vgaiRootSurface'] = 'true';
+    // WHICH ROOT THIS SURFACE PRESENTS — the host mounted it, so the host
+    // knows, and stamping it here is the difference between a declaration and
+    // the guess every late reader had to make instead ("the first <canvas> in
+    // DOM order is the game's"). Read by `packages/editor/src/presentation-
+    // surface.ts`, which is the one door the capture/staleness/screenshot
+    // sites now ask (ARCHITECTURE-CORE §The editor protocol, zero inference).
+    surface.dataset['vgaiRootId'] = entry.id;
     // The capture's marker (`composite-screenshot.ts` reads exactly this
     // attribute): a dev layer is excluded from a play capture unless the
     // capture asks for it, because a contaminated "does the game look right"

package/src/runtime/debug-bridge.ts

@@ -104,10 +104,10 @@ export interface VgaiDebugInputHandle {
  *  `state` from another). */
 export interface VgaiDebugSnapshot {
   /** `loopLiveness` (issue #175): the REAL `GameLoop.liveness` behind this
-   *  session — `'hidden-paused'` while the T2.1 idle throttle has stopped
-   *  the loop (tab hidden), `null` only when no loop is wired at all (a
-   *  bare debug-registry test stand-in with no real `Game`). Never a
-   *  fabricated `'running'`. */
+   *  session — `'loop-starved'` when no recent host rAF progress was observed,
+   *  `null` only when no loop is wired at all (a bare debug-registry test
+   *  stand-in with no real `Game`). Never a fabricated `'running'` and never
+   *  a conclusion about tab visibility. */
   time: { simSeconds: number; tick: number; loopLiveness: GameLoopLiveness | null };
   state: Record<string, unknown>;
   events: TickStampedEvent[];
@@ -233,28 +233,29 @@ const HOLD_FOR_POLL_MS = 50;
  *  the same neighborhood. */
 const HOLD_FOR_STALL_POLL_LIMIT = 100;
 
-/** Ticks driven per synchronous hidden-tab batch. Sized like
+/** Ticks driven per synchronous starved-loop batch. Sized like
  *  `fast-forward.ts`'s own batching rationale: big enough that per-batch
  *  bookkeeping is negligible, small enough that one batch of a complex game's
  *  phases stays a short synchronous burst. */
-const HIDDEN_DRIVE_BATCH_TICKS = 60;
+const STARVED_DRIVE_BATCH_TICKS = 60;
 
-/** Hard ceiling on hidden-drive batches for ONE hold — `HIDDEN_DRIVE_BATCH_TICKS
+/** Hard ceiling on starved-drive batches for ONE hold — `STARVED_DRIVE_BATCH_TICKS
  *  * this` ≈ 33 sim-minutes. A bound, not a timeout: it exists so a
  *  `runTicks` target that advances the tick counter without advancing the sim
  *  clock can never spin forever, and it is far past any honest hold. */
-const HIDDEN_DRIVE_MAX_BATCHES = 2000;
+const STARVED_DRIVE_MAX_BATCHES = 2000;
 
-/** The message a hold gets when the loop is hidden-paused and NOTHING can
+/** The message a hold gets when the loop is loop-starved and NOTHING can
  *  drive it — the one case where the platform genuinely prevents the verb
  *  from working. Names the cause and the fix rather than expiring into a
  *  generic stall (which reported the wrong cause: "play stopped during
  *  hold"). One exported constant so both doors and their tests read the same
  *  string. */
-export const HOLD_HIDDEN_NO_DRIVER_REASON =
-  'the editor tab is hidden and this session has no way to drive ticks — the engine ' +
-  'hidden-pauses its loop while document.hidden, so zero ticks are happening. Bring the ' +
-  'editor tab to the foreground (or start play, which wires the run-ticks target) and retry.';
+export const HOLD_STARVED_NO_DRIVER_REASON =
+  "the host loop reported liveness 'loop-starved' and this session has no way to drive " +
+  'ticks — no recent rAF progress was observed. Check `vgai status` for the separate ' +
+  'visibility readings; foreground/reload the editor, or start play to wire the run-ticks ' +
+  'target, then retry.';
 
 /** What `adapter.state('time')` returns for the two fields this loop reads,
  *  plus the liveness the hidden path branches on. */
@@ -279,8 +280,8 @@ interface HoldClockReading {
  *   `HOLD_FOR_POLL_MS` and gives up after `HOLD_FOR_STALL_POLL_LIMIT`
  *   consecutive unchanged-tick polls (`stalled: true` — play stopped/paused).
  *
- * - **Hidden-paused**: the host loop has stopped outright (T2.1's idle
- *   throttle), so sim time only moves if this drives it. It therefore drives
+ * - **Loop-starved**: no recent host rAF progress is observable, so sim time
+ *   only moves reliably if this drives it. It therefore drives
  *   the WHOLE remaining budget in synchronous batches, yielding a MICROTASK
  *   between them — never a timer. That distinction is load-bearing, not
  *   stylistic: a hidden tab clamps `setTimeout` to ~1s (and to ~1/minute under
@@ -293,35 +294,35 @@ interface HoldClockReading {
  *   are not throttled, so the hidden path now costs sim-work time and nothing
  *   else.
  *
- * The regime is re-read every iteration, so a tab foregrounded (or hidden)
- * mid-hold crosses over without restarting the budget.
+ * The regime is re-read every iteration, so an rAF chain that resumes or
+ * becomes starved mid-hold crosses over without restarting the budget.
  *
- * `hiddenWithoutDriver: true` is the one honest refusal: hidden-paused with
- * no `driveHiddenTicks` hook means nothing in this process can advance the
+ * `starvedWithoutDriver: true` is the one honest refusal: loop-starved with
+ * no `driveStarvedTicks` hook means nothing in this process can advance the
  * clock, so it reports that IMMEDIATELY (see
- * {@link HOLD_HIDDEN_NO_DRIVER_REASON}) instead of burning the stall guard
+ * {@link HOLD_STARVED_NO_DRIVER_REASON}) instead of burning the stall guard
  * and then blaming a stopped game.
  */
 export async function waitForHoldBudget(
   adapter: DebugAdapter,
   simSeconds: number,
-  driveHiddenTicks?: (n: number) => void,
-): Promise<{ stalled: boolean; hiddenWithoutDriver?: boolean }> {
+  driveStarvedTicks?: (n: number) => void,
+): Promise<{ stalled: boolean; starvedWithoutDriver?: boolean }> {
   const readTime = () => adapter.state('time') as HoldClockReading;
   const start = readTime();
   let lastTick = start.tick;
   let stalledPolls = 0;
-  let hiddenBatches = 0;
+  let starvedBatches = 0;
 
   for (;;) {
     const current = readTime();
     if (current.simSeconds - start.simSeconds >= simSeconds) return { stalled: false };
 
-    if (current.loopLiveness === 'hidden-paused') {
-      if (!driveHiddenTicks) return { stalled: true, hiddenWithoutDriver: true };
-      if (hiddenBatches >= HIDDEN_DRIVE_MAX_BATCHES) return { stalled: true };
-      hiddenBatches += 1;
-      driveHiddenTicks(HIDDEN_DRIVE_BATCH_TICKS);
+    if (current.loopLiveness === 'loop-starved') {
+      if (!driveStarvedTicks) return { stalled: true, starvedWithoutDriver: true };
+      if (starvedBatches >= STARVED_DRIVE_MAX_BATCHES) return { stalled: true };
+      starvedBatches += 1;
+      driveStarvedTicks(STARVED_DRIVE_BATCH_TICKS);
       const after = readTime();
       // A batch that moved neither the tick counter nor the sim clock means
       // the drive is a no-op (paused game, torn-down runtime) — the same
@@ -333,7 +334,7 @@ export async function waitForHoldBudget(
       lastTick = after.tick;
       stalledPolls = 0;
       // Yield so the page can service other work between batches, WITHOUT
-      // handing control to a clock a hidden tab is allowed to starve.
+      // handing control to the same timer lane the browser may be starving.
       await Promise.resolve();
       continue;
     }
@@ -481,7 +482,7 @@ function buildDebugHandle(opts: {
           : { delivered: false };
       }
       const runTicksTarget = registry.getRunTicksTarget();
-      const { stalled, hiddenWithoutDriver } = await waitForHoldBudget(
+      const { stalled, starvedWithoutDriver } = await waitForHoldBudget(
         adapter,
         simSeconds,
         runTicksTarget ? (n) => runTicksTarget.runTicks(n, { render: 'last' }) : undefined,
@@ -490,7 +491,7 @@ function buildDebugHandle(opts: {
       if (!stalled) return { delivered: true };
       return {
         delivered: false,
-        reason: hiddenWithoutDriver ? HOLD_HIDDEN_NO_DRIVER_REASON : 'play stopped during hold',
+        reason: starvedWithoutDriver ? HOLD_STARVED_NO_DRIVER_REASON : 'play stopped during hold',
       };
     },
     uninstall() {

package/src/runtime/game.ts

@@ -987,8 +987,7 @@ export function createGame(opts: {
     // Other native `console.warn`/`console.error` call sites in this file are
     // unsuppressed and already counted in the lint baseline (see `runFrame`'s
     // impl below); this one is a NEW site, so it's suppressed to keep this
-    // task's diff at zero NEW warnings (same reasoning as `achieved-tier.ts`'s
-    // identical suppression).
+    // task's diff at zero NEW warnings.
     // biome-ignore lint/suspicious/noConsole: see comment above
     console.warn(message);
   }

package/src/setup/setup-particles.ts

@@ -1,5 +1,6 @@
 import type * as THREE from 'three';
 import { BatchedRenderer } from 'three.quarks';
+import { farDepthTexture } from '../render/soft-particle-depth';
 
 export interface ParticlesContext {
   batchedRenderer: BatchedRenderer;
@@ -17,6 +18,14 @@ export interface ParticlesContext {
  */
 export function setupParticles(scene: THREE.Scene): ParticlesContext {
   const batchedRenderer = new BatchedRenderer();
+  // Seed the soft-particle depth sampler BEFORE any batch exists, so every
+  // batch this renderer later builds inherits it (`BatchedRenderer.addSystem`
+  // applies `this.depthTexture` to each new batch). A `softParticles` batch
+  // whose `depthTexture` uniform is still `null` samples black and multiplies
+  // every particle away; the far-depth default makes that same batch render
+  // exactly as an unfaded one until a real depth pass supplies the scene's own.
+  // See `render/soft-particle-depth.ts`.
+  batchedRenderer.setDepthTexture(farDepthTexture());
   scene.add(batchedRenderer);
 
   return { batchedRenderer };

package/src/world3d-react/r3f-adapter.tsx

@@ -25,8 +25,9 @@ import {
   extend,
   events as pointerEvents,
   type RootState,
+  useFrame,
 } from '@react-three/fiber';
-import { createElement, type ReactNode } from 'react';
+import { createElement, Fragment, type ReactNode, useEffect, useMemo } from 'react';
 import type { MountedThreeRoot, RootAdapter, ThreeHostContext } from '../adapter';
 import { type RenderVitalsRegistration, registerRenderVitals } from '../dev/register-render-vitals';
 import {
@@ -38,6 +39,7 @@ import { collectRenderMemory } from '../dev/render-memory';
 import { RENDER_SUBMIT_PHASE } from '../dev/render-vitals';
 import { createWebGLFrameCapture } from '../dev/webgl-frame-capture';
 import { WorldProvider } from '../react/world-state';
+import { createSoftParticleDepthPass } from '../render/soft-particle-depth';
 import { devLayersEnabled } from '../runtime/dev-layers';
 import { EngineBridge, type EngineBridgeValue } from './engine-bridge';
 import { applyWorldRendererConfig, type WorldRendererConfig } from './renderer-config';
@@ -52,6 +54,37 @@ interface RendererCounters {
   readonly memory: { readonly geometries: number; readonly textures: number };
 }
 
+/**
+ * Scene depth for any soft-particle system this world mounted, drawn between
+ * gameplay and the draw.
+ *
+ * `useFrame`'s priority is the whole reason this is a component rather than an
+ * engine phase: `systems.run(dt)` below finishes BEFORE `advance()`, and
+ * `advance()` is where every `useFrame` gameplay callback moves the frame's
+ * transforms — depth taken from an engine phase would be one frame stale.
+ * Priority `0` puts it after every negative-priority callback (fiber sorts
+ * subscribers by priority) and before both a positive-priority composer and
+ * fiber's own `state.gl.render` — and, unlike a positive priority, it does NOT
+ * flip fiber into manual-render mode (`internal.priority` only counts
+ * subscribers with `priority > 0`), so mounting it can never stop an ordinary
+ * world from drawing itself.
+ *
+ * Rendered as the LAST child of the adapter's tree so its subscription lands
+ * after the world's own (React completes children before siblings, and fiber's
+ * sort is stable) — the tie-break among priority-0 callbacks is insertion
+ * order.
+ *
+ * Costs nothing while no soft-particle system is armed — see
+ * `../render/soft-particle-depth.ts` for what "armed" means and what the pass
+ * spends when it is.
+ */
+function SoftParticleDepth(): null {
+  const pass = useMemo(() => createSoftParticleDepthPass(), []);
+  useEffect(() => () => pass.dispose(), [pass]);
+  useFrame(({ gl, scene, camera }) => pass.render(gl, scene, camera), 0);
+  return null;
+}
+
 /** What {@link createR3FAdapter} needs to build one `RootAdapter`. */
 export interface CreateR3FAdapterOptions {
   /** Stable id (telemetry/registry/conformance) — `RootAdapter.id`. */
@@ -266,11 +299,19 @@ export function createR3FAdapter(options: CreateR3FAdapterOptions): RootAdapter
       // hosts, so the provider is conditional and those hooks stay the inert
       // no-ops they already document themselves to be.
       const game = runtime.ctx.game;
+      // `SoftParticleDepth` trails the world's own tree deliberately — see its
+      // docblock for why the subscription must land last.
+      const world = createElement(
+        Fragment,
+        null,
+        content,
+        createElement(SoftParticleDepth, { key: 'vgai-soft-particle-depth' }),
+      );
       root.render(
         createElement(
           EngineBridge.Provider,
           { value: bridge },
-          game ? createElement(WorldProvider, { game }, content) : content,
+          game ? createElement(WorldProvider, { game }, world) : world,
         ),
       );
       // A reconcile-time crash (e.g. a missing `extend` catalogue entry)
@@ -474,6 +515,11 @@ export function createR3FAdapter(options: CreateR3FAdapterOptions): RootAdapter
           return live().camera;
         },
         drivesOwnLoop: false,
+        // REPORTED for a host that draws this scene with a renderer other than
+        // the one it mounted us against — see `MountedThreeRoot.rendererConfig`.
+        // It is the same object already applied to `host.renderer` above; the
+        // report never applies anything itself.
+        rendererConfig: rendererConfig,
         // Adapter surface: `debug` (the shared game registry) and, when a real
         // WebGL2 context exists, `renderDebug` are engine-seeded. Game code
         // adds its own capabilities via `ctx.registerSystemAdapter` exactly