@vgai/engine 0.5.40 → 0.5.42

package/src/ai/navigation.ts

@@ -67,6 +67,37 @@ export interface NavMeshBuildParams {
   mergeRegionArea?: number | undefined;
 }
 
+/** One authored Detour polygon. Vertex order is clockwise in the engine's XZ world basis. */
+export interface NavMeshPolygon {
+  readonly vertices: readonly number[];
+  readonly flags?: number | undefined;
+  readonly area?: number | undefined;
+}
+
+/** Detail-row offsets/counts for the polygon at the same index. */
+export interface NavMeshDetailMesh {
+  readonly vertexBase: number;
+  readonly triangleBase: number;
+  readonly vertexCount: number;
+  readonly triangleCount: number;
+}
+
+/**
+ * An already-authored polygon mesh, before Detour's ABI-specific tile serialization.
+ *
+ * This is the direct-data sibling of {@link buildFromMeshes}: use it when a source ecosystem has
+ * already baked navigation. Re-rasterizing an editor bake is lossy—the polygon borders and detail
+ * heights are the output, not another input mesh.
+ */
+export interface NavMeshPolygonData {
+  readonly vertices: readonly (readonly [number, number, number])[];
+  readonly polygons: readonly NavMeshPolygon[];
+  readonly detailMeshes: readonly NavMeshDetailMesh[];
+  readonly detailVertices: readonly (readonly [number, number, number])[];
+  /** Three local vertex indices plus Detour edge flags; all four values are uint8. */
+  readonly detailTriangles: readonly (readonly [number, number, number, number])[];
+}
+
 let wasmInitialized = false;
 
 export async function initNavigation(): Promise<void> {
@@ -103,24 +134,47 @@ function reverseTriangleWinding(geometry: BufferGeometry): void {
   index.needsUpdate = true;
 }
 
+/** Signed world-up area across a geometry's triangles. Closed obstacle meshes cancel to zero;
+ * broad walkable surfaces retain the winding Recast uses for its slope test. */
+function upwardTriangleArea(geometry: BufferGeometry): number {
+  const position = geometry.getAttribute('position');
+  const index = geometry.getIndex();
+  const vertexAt = (offset: number): number => index?.getX(offset) ?? offset;
+  let area = 0;
+  const count = index?.count ?? position.count;
+  for (let triangle = 0; triangle + 2 < count; triangle += 3) {
+    const a = vertexAt(triangle);
+    const b = vertexAt(triangle + 1);
+    const c = vertexAt(triangle + 2);
+    const ux = position.getX(b) - position.getX(a);
+    const uz = position.getZ(b) - position.getZ(a);
+    const vx = position.getX(c) - position.getX(a);
+    const vz = position.getZ(c) - position.getZ(a);
+    area += uz * vx - ux * vz;
+  }
+  return area;
+}
+
 function recastInputMeshes(meshes: Mesh[]): {
   readonly meshes: Mesh[];
   readonly temporaryGeometries: BufferGeometry[];
 } {
   const temporaryGeometries: BufferGeometry[] = [];
-  const mirroredGeometries = new WeakMap<BufferGeometry, BufferGeometry>();
-  const geometryForMatrix = (source: BufferGeometry, matrix: Matrix4): BufferGeometry => {
-    if (matrix.determinant() >= 0) return source;
-    const cached = mirroredGeometries.get(source);
-    if (cached !== undefined) return cached;
-    const geometry = source.clone();
-    reverseTriangleWinding(geometry);
-    mirroredGeometries.set(source, geometry);
-    temporaryGeometries.push(geometry);
-    return geometry;
-  };
   const proxyAt = (geometry: BufferGeometry, matrix: Matrix4): Mesh => {
-    const proxy = new Mesh(geometryForMatrix(geometry, matrix));
+    if (matrix.determinant() < 0) {
+      // Bake the complete mirrored transform into this clone. Passing a negative-determinant
+      // matrix through `@recast-navigation/three` after reversing the source indices still lets
+      // its geometry merge recalculate the triangle orientation from that matrix. An identity
+      // proxy over already-world-space vertices has exactly one winding decision.
+      const transformed = geometry.clone().applyMatrix4(matrix);
+      // A negative determinant alone is insufficient: reflecting across a plane's normal axis
+      // leaves every vertex in place, while reflecting an in-plane axis reverses its triangles.
+      // Inspect the transformed walkable area instead of guessing from the 3D transform.
+      if (upwardTriangleArea(transformed) < 0) reverseTriangleWinding(transformed);
+      temporaryGeometries.push(transformed);
+      return new Mesh(transformed);
+    }
+    const proxy = new Mesh(geometry);
     // The proxy has no parent, so its local matrix is the source mesh's complete world matrix.
     // The recast bridge calls updateMatrixWorld() itself; disabling auto-update preserves it.
     proxy.matrixAutoUpdate = false;
@@ -148,6 +202,224 @@ function recastInputMeshes(meshes: Mesh[]): {
   return { meshes: corrected, temporaryGeometries };
 }
 
+const NAV_MESH_SET_MAGIC = 0x4d53_4554;
+const NAV_MESH_SET_VERSION = 1;
+const DETOUR_NAV_MESH_MAGIC = 0x444e_4156;
+const DETOUR_NAV_MESH_VERSION = 7;
+
+function nextPowerOfTwo(value: number): number {
+  let result = 1;
+  while (result < value) result *= 2;
+  return result;
+}
+
+/** Serialize portable polygon/detail arrays as one ordinary Detour tile. */
+function polygonNavMeshData(data: NavMeshPolygonData, params?: NavMeshBuildParams): Uint8Array {
+  const vertexCount = data.vertices.length;
+  const polygonCount = data.polygons.length;
+  if (vertexCount === 0 || polygonCount === 0) {
+    throw new Error('NavMeshManager.buildFromPolygons: vertices and polygons must be non-empty');
+  }
+  if (vertexCount > 0xffff) {
+    throw new Error(
+      `NavMeshManager.buildFromPolygons: ${vertexCount} vertices exceed Detour's uint16 tile index`,
+    );
+  }
+  if (data.detailMeshes.length !== polygonCount) {
+    throw new Error(
+      `NavMeshManager.buildFromPolygons: ${polygonCount} polygons require the same number of detail rows`,
+    );
+  }
+
+  const neighbours = data.polygons.map((polygon) => polygon.vertices.map(() => 0));
+  const edges = new Map<string, readonly [number, number]>();
+  let maxLinkCount = 0;
+  for (let polygonIndex = 0; polygonIndex < polygonCount; polygonIndex += 1) {
+    const polygon = data.polygons[polygonIndex] as NavMeshPolygon;
+    if (polygon.vertices.length < 3 || polygon.vertices.length > 6) {
+      throw new Error(
+        `NavMeshManager.buildFromPolygons: polygon ${polygonIndex} has ` +
+          `${polygon.vertices.length} vertices; Detour permits 3..6`,
+      );
+    }
+    maxLinkCount += polygon.vertices.length;
+    for (let edgeIndex = 0; edgeIndex < polygon.vertices.length; edgeIndex += 1) {
+      const from = polygon.vertices[edgeIndex] as number;
+      const to = polygon.vertices[(edgeIndex + 1) % polygon.vertices.length] as number;
+      if (
+        !Number.isInteger(from) ||
+        !Number.isInteger(to) ||
+        from < 0 ||
+        to < 0 ||
+        from >= vertexCount ||
+        to >= vertexCount
+      ) {
+        throw new Error(
+          `NavMeshManager.buildFromPolygons: polygon ${polygonIndex} references an invalid vertex`,
+        );
+      }
+      const directed = `${from},${to}`;
+      if (edges.has(directed)) {
+        throw new Error(
+          `NavMeshManager.buildFromPolygons: directed edge ${directed} occurs more than once`,
+        );
+      }
+      const reverse = edges.get(`${to},${from}`);
+      if (reverse === undefined) {
+        edges.set(directed, [polygonIndex, edgeIndex]);
+      } else {
+        const [otherPolygon, otherEdge] = reverse;
+        neighbours[polygonIndex]![edgeIndex] = otherPolygon + 1;
+        neighbours[otherPolygon]![otherEdge] = polygonIndex + 1;
+      }
+    }
+  }
+
+  for (let polygonIndex = 0; polygonIndex < polygonCount; polygonIndex += 1) {
+    const row = data.detailMeshes[polygonIndex] as NavMeshDetailMesh;
+    if (
+      row.vertexBase < 0 ||
+      row.vertexCount < 0 ||
+      row.vertexBase + row.vertexCount > data.detailVertices.length ||
+      row.triangleBase < 0 ||
+      row.triangleCount < 0 ||
+      row.triangleBase + row.triangleCount > data.detailTriangles.length ||
+      row.vertexCount > 0xff ||
+      row.triangleCount > 0xff
+    ) {
+      throw new Error(
+        `NavMeshManager.buildFromPolygons: polygon ${polygonIndex} has an invalid detail row`,
+      );
+    }
+  }
+  for (const triangle of data.detailTriangles) {
+    if (triangle.some((value) => !Number.isInteger(value) || value < 0 || value > 0xff)) {
+      throw new Error(
+        'NavMeshManager.buildFromPolygons: detail triangles must contain uint8 values',
+      );
+    }
+  }
+
+  const boundsMin = [Number.POSITIVE_INFINITY, Number.POSITIVE_INFINITY, Number.POSITIVE_INFINITY];
+  const boundsMax = [Number.NEGATIVE_INFINITY, Number.NEGATIVE_INFINITY, Number.NEGATIVE_INFINITY];
+  for (const vertex of [...data.vertices, ...data.detailVertices]) {
+    for (let component = 0; component < 3; component += 1) {
+      const value = vertex[component] as number;
+      if (!Number.isFinite(value)) {
+        throw new Error('NavMeshManager.buildFromPolygons: every vertex component must be finite');
+      }
+      boundsMin[component] = Math.min(boundsMin[component] as number, value);
+      boundsMax[component] = Math.max(boundsMax[component] as number, value);
+    }
+  }
+
+  // Detour's in-memory structs are emitted in its stable 32-bit serialized layout. `importNavMesh`
+  // owns the ABI boundary and recreates live WASM objects from these ordinary bytes.
+  const headerBytes = 100;
+  const polygonBytes = 32;
+  const linkBytes = 12;
+  const detailMeshBytes = 12;
+  const detailTriangleBytes = 4;
+  const tileBytes =
+    headerBytes +
+    vertexCount * 12 +
+    polygonCount * polygonBytes +
+    maxLinkCount * linkBytes +
+    polygonCount * detailMeshBytes +
+    data.detailVertices.length * 12 +
+    data.detailTriangles.length * detailTriangleBytes;
+  const bytes = new Uint8Array(48 + tileBytes);
+  const view = new DataView(bytes.buffer);
+  let offset = 0;
+  const uint8 = (value: number): void => {
+    view.setUint8(offset, value);
+    offset += 1;
+  };
+  const uint16 = (value: number): void => {
+    view.setUint16(offset, value, true);
+    offset += 2;
+  };
+  const uint32 = (value: number): void => {
+    view.setUint32(offset, value, true);
+    offset += 4;
+  };
+  const int32 = (value: number): void => {
+    view.setInt32(offset, value, true);
+    offset += 4;
+  };
+  const float32 = (value: number): void => {
+    view.setFloat32(offset, value, true);
+    offset += 4;
+  };
+
+  const maxPolygons = nextPowerOfTwo(polygonCount);
+  uint32(NAV_MESH_SET_MAGIC);
+  uint32(NAV_MESH_SET_VERSION);
+  uint32(1);
+  for (const value of boundsMin) float32(value);
+  float32(Math.max((boundsMax[0] as number) - (boundsMin[0] as number), Number.EPSILON));
+  float32(Math.max((boundsMax[2] as number) - (boundsMin[2] as number), Number.EPSILON));
+  uint32(1);
+  uint32(maxPolygons);
+  // With one tile, Detour's first valid salt occupies the bits above maxPolygons.
+  uint32(maxPolygons);
+  uint32(tileBytes);
+
+  uint32(DETOUR_NAV_MESH_MAGIC);
+  uint32(DETOUR_NAV_MESH_VERSION);
+  int32(0);
+  int32(0);
+  int32(0);
+  uint32(0);
+  uint32(polygonCount);
+  uint32(vertexCount);
+  uint32(maxLinkCount);
+  uint32(polygonCount);
+  uint32(data.detailVertices.length);
+  uint32(data.detailTriangles.length);
+  uint32(0);
+  uint32(0);
+  uint32(polygonCount);
+  const defaults = DEFAULTS.navigation;
+  float32(params?.walkableHeight ?? defaults.walkableHeight);
+  float32(params?.walkableRadius ?? defaults.walkableRadius);
+  float32(params?.walkableClimb ?? defaults.walkableClimb);
+  for (const value of boundsMin) float32(value);
+  for (const value of boundsMax) float32(value);
+  float32(1 / (params?.cellSize ?? defaults.cellSize));
+
+  for (const vertex of data.vertices) for (const value of vertex) float32(value);
+  for (let polygonIndex = 0; polygonIndex < polygonCount; polygonIndex += 1) {
+    const polygon = data.polygons[polygonIndex] as NavMeshPolygon;
+    uint32(0xffff_ffff);
+    for (let index = 0; index < 6; index += 1) uint16(polygon.vertices[index] ?? 0);
+    for (let index = 0; index < 6; index += 1) {
+      uint16(neighbours[polygonIndex]?.[index] ?? 0);
+    }
+    uint16(polygon.flags ?? 1);
+    uint8(polygon.vertices.length);
+    uint8((polygon.area ?? 0) & 0x3f);
+  }
+  // `dtNavMesh::addTile` turns this zeroed capacity into its free-list, then populates the
+  // internal links from the polygon neighbour indices above.
+  offset += maxLinkCount * linkBytes;
+  for (const row of data.detailMeshes) {
+    uint32(row.vertexBase);
+    uint32(row.triangleBase);
+    uint8(row.vertexCount);
+    uint8(row.triangleCount);
+    uint16(0);
+  }
+  for (const vertex of data.detailVertices) for (const value of vertex) float32(value);
+  for (const triangle of data.detailTriangles) for (const value of triangle) uint8(value);
+  if (offset !== bytes.length) {
+    throw new Error(
+      `NavMeshManager.buildFromPolygons: encoded ${offset} bytes into a ${bytes.length}-byte allocation`,
+    );
+  }
+  return bytes;
+}
+
 export class NavMeshManager {
   private navMesh: NavMesh | null = null;
   private query: NavMeshQuery | null = null;
@@ -187,7 +459,10 @@ export class NavMeshManager {
     try {
       result =
         params?.tiled === true || input.meshes.length > 256 || triangleCount > 10_000
-          ? threeToTiledNavMesh(input.meshes, { ...config, tileSize: params?.tileSize ?? 256 })
+          ? threeToTiledNavMesh(input.meshes, {
+              ...config,
+              tileSize: params?.tileSize ?? 256,
+            })
           : threeToSoloNavMesh(input.meshes, config);
     } finally {
       for (const geometry of input.temporaryGeometries) geometry.dispose();
@@ -202,6 +477,16 @@ export class NavMeshManager {
     return true;
   }
 
+  /** Load an authored polygon/detail mesh directly, without a second rasterization. */
+  buildFromPolygons(data: NavMeshPolygonData, params?: NavMeshBuildParams): boolean {
+    try {
+      this.loadFromData(polygonNavMeshData(data, params));
+      return true;
+    } catch {
+      return false;
+    }
+  }
+
   /**
    * Destroy all live recast handles (crowd, query, navmesh) and dispose the
    * debug helper. Recast objects live on the WASM heap and are NOT GC'd —

package/src/ecs/user-data.ts

@@ -82,6 +82,9 @@
  *                           association; unlike the label, never user-facing copy.
  * - `authoringDocument`   — generic reference to the project-tool document
  *                           that owns this scene instance's authored asset.
+ * - `authoringHierarchyId`, `authoringHierarchyParentId`,
+ *   `authoringHierarchyOrder` — source-owned semantic identity, parent identity,
+ *                           and sibling ordinal shared across native surfaces.
  * - `editorHelper`        — `true` for editor-only helper objects (gizmos, wireframes).
  *
  * Hierarchy-presentation convention (written by GAME code, read by the editor —
@@ -193,6 +196,12 @@ export interface UserDataSchema {
     readonly name: string;
     readonly title: string;
   };
+  /** Project-owned identity used to join authored hierarchy rows across adapter roots. */
+  authoringHierarchyId: string;
+  /** Project-owned parent identity when the authored parent can live on another surface. */
+  authoringHierarchyParentId: string;
+  /** Source-owned sibling ordinal used when hierarchy rows cross native roots. */
+  authoringHierarchyOrder: number;
   editorHelper: boolean;
   editorHelperType: EditorHelperType;
   editorIcon: boolean;
@@ -249,6 +258,9 @@ export const UserDataKeys = {
   vgaiBodyOwner: 'vgaiBodyOwner',
   authoringComponent: 'authoringComponent',
   authoringDocument: 'authoringDocument',
+  authoringHierarchyId: 'authoringHierarchyId',
+  authoringHierarchyParentId: 'authoringHierarchyParentId',
+  authoringHierarchyOrder: 'authoringHierarchyOrder',
   editorHelper: 'editorHelper',
   editorHelperType: 'editorHelperType',
   editorIcon: 'editorIcon',

package/src/render/environment-capture.ts

@@ -10,7 +10,7 @@
  * game altered.
  *
  * Consumers today: the `reflections` capability's native probe system, and
- * `godot-compat`'s Godot 3 `ReflectionProbe`.
+ * `godot-compat`'s versioned Godot `ReflectionProbe` binding.
  */
 import type { Light, Object3D, Scene, WebGLRenderer } from 'three';
 
@@ -88,6 +88,35 @@ export function withCaptureShadows(scene: Scene, enabled: boolean, capture: () =
   }
 }
 
+/**
+ * Include or suppress the scene's global sky/environment for one cube capture.
+ *
+ * This is renderer plumbing rather than a Godot policy: the caller decides whether the capture is
+ * interior. Clearing both properties is necessary because Three uses `background` for the cube's
+ * visible pixels and `environment` for the materials being photographed. Restoring only one makes
+ * a nominally isolated capture retain half of the outside lighting.
+ */
+export function withCaptureSceneEnvironment(
+  scene: Scene,
+  enabled: boolean,
+  capture: () => void,
+): void {
+  if (enabled) {
+    capture();
+    return;
+  }
+  const background = scene.background;
+  const environment = scene.environment;
+  scene.background = null;
+  scene.environment = null;
+  try {
+    capture();
+  } finally {
+    scene.background = background;
+    scene.environment = environment;
+  }
+}
+
 /**
  * Whether this renderer can run an environment capture at all.
  *

package/src/render/ibl-override-material.ts

@@ -24,10 +24,19 @@
  * 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
+ * `godot-compat`'s Godot `ReflectionProbe`, whose per-fragment models are
  * deliberately different renderers over this one splice.
  */
-import { type Mesh, type MeshStandardMaterial, ShaderChunk } from 'three';
+import {
+  CubeUVReflectionMapping,
+  DataTexture,
+  type Mesh,
+  type MeshStandardMaterial,
+  RGBAFormat,
+  ShaderChunk,
+  type Texture,
+  UnsignedByteType,
+} from 'three';
 
 /** The shader object three hands to `onBeforeCompile`. */
 export type IblOverrideShader = Parameters<MeshStandardMaterial['onBeforeCompile']>[0];
@@ -67,6 +76,27 @@ export function standardMaterialsOf(mesh: Mesh): readonly MeshStandardMaterial[]
   );
 }
 
+/**
+ * A black native texture whose only job is to compile Three's IBL branch.
+ *
+ * Local reflection systems can light a scene from captured probes when neither
+ * `scene.environment` nor a material `envMap` exists. Three removes both IBL
+ * entry points from that program unless one native input is present, so the
+ * caller temporarily assigns this neutral texture and restores what it found.
+ */
+export function createIblSentinelTexture(): Texture {
+  const texture = new DataTexture(
+    new Uint8Array(16 * 16 * 4),
+    16,
+    16,
+    RGBAFormat,
+    UnsignedByteType,
+  );
+  texture.mapping = CubeUVReflectionMapping;
+  texture.needsUpdate = true;
+  return texture;
+}
+
 export interface IblOverrideOptions {
   /**
    * The GLSL that replaces `#include <envmap_physical_pars_fragment>`. Read at

package/src/runtime/debug-bridge.ts

@@ -246,10 +246,13 @@ const HOLD_FOR_POLL_MS = 50;
  *  the same neighborhood. */
 const HOLD_FOR_STALL_POLL_LIMIT = 100;
 
-/** Ticks driven per synchronous starved-loop batch. Sized like
+/** Maximum 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. */
+ *  phases stays a short synchronous burst. The actual batch is capped to the
+ *  hold's remaining fixed-tick budget below; otherwise a one-tick `tap()` in a
+ *  hidden tab becomes a 60-tick hold and releases only after short gameplay
+ *  interactions have already completed. */
 const STARVED_DRIVE_BATCH_TICKS = 60;
 
 /** Hard ceiling on starved-drive batches for ONE hold — `STARVED_DRIVE_BATCH_TICKS
@@ -276,6 +279,9 @@ interface HoldClockReading {
   simSeconds: number;
   tick: number;
   loopLiveness?: GameLoopLiveness | null;
+  /** Present for every real Game-backed debug registry. Optional only because a bare adapter
+   *  stand-in can omit it; that case drives one conservative tick at a time. */
+  fixedDt?: number;
 }
 
 /**
@@ -335,7 +341,19 @@ export async function waitForHoldBudget(
       if (!driveStarvedTicks) return { stalled: true, starvedWithoutDriver: true };
       if (starvedBatches >= STARVED_DRIVE_MAX_BATCHES) return { stalled: true };
       starvedBatches += 1;
-      driveStarvedTicks(STARVED_DRIVE_BATCH_TICKS);
+      const remaining = simSeconds - (current.simSeconds - start.simSeconds);
+      const fixedDt = current.fixedDt;
+      // A real Game publishes its fixed timestep, so drive exactly the number of whole ticks
+      // still needed (up to the throughput cap). Subtract a tiny ratio tolerance before `ceil`:
+      // repeated floating-point additions can leave an integer tick budget a few ulps above its
+      // mathematical value, and that must not manufacture one extra held-input frame. A bare
+      // adapter that does not publish `fixedDt` takes the conservative path: one tick, re-read,
+      // repeat. Exact input duration matters more than batching a non-Game test stand-in.
+      const ticksForRemaining =
+        fixedDt !== undefined && Number.isFinite(fixedDt) && fixedDt > 0
+          ? Math.max(1, Math.ceil(remaining / fixedDt - 1e-9))
+          : 1;
+      driveStarvedTicks(Math.min(STARVED_DRIVE_BATCH_TICKS, ticksForRemaining));
       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

package/src/runtime/game.ts

@@ -122,8 +122,9 @@ export type AdapterSurface = AdapterSurfaceLeaf;
  * A world's per-phase frame hooks.
  * Populated on a `RootInstance` only for first-party mounts — an opaque/
  * foreign mount has no phase-partitioned entry point, so it stays
- * `undefined` and the Game's frame executor (`GameInternal.runFrame`) falls
- * back to calling its single `mounted.update(dt)` once per substep instead.
+ * `undefined` and the Game's frame executor falls back to its single
+ * `mounted.update(dt)`. The mount's `updateCadence` chooses fixed-substep
+ * (the default) or display-rate dispatch.
  */
 export interface RootFrameHooks {
   /** Run this world's engine systems + component ticks + world-bound game
@@ -639,8 +640,8 @@ export interface Game {
    * sway, a cosmetic bob. It is NOT a gameplay hook: it can fire twice
    * between two fixed substeps (120 Hz display, 60 Hz sim) and zero times
    * across a `runTicks` fast-forward, so anything that must be deterministic
-   * belongs in a fixed phase (`ctx.systems.add`, a `useFrame` hook, a
-   * `useFrame`) instead.
+   * belongs in a fixed engine phase (`ctx.systems.add`) instead. Ecosystem
+   * presentation hooks such as R3F's `useFrame` share this display clock.
    *
    * Reached from game code as `ctx.game?.onRenderStep(...)`. Returns an
    * unsubscribe function; pass `opts.signal` to unsubscribe with the same
@@ -685,13 +686,17 @@ export interface GameInternal extends Game {
    * for world in roots:                       // after ALL phases
    *   if world.mounted.drivesOwnLoop: continue
    *   if world.frame: world.frame.endFrame?.()
-   *   else: world.mounted.update?.(dt)          // opaque world fallback
+   *   else if updateCadence != 'display' OR render phases are included:
+   *     world.mounted.update?.(dt)              // opaque world fallback
    * ```
    *
    * A single first-party world and its direct `mounted.update(dt)` entry run
    * the same `SystemRunner` and `postFrame` work. A `drivesOwnLoop` world is
    * never ticked here. An opaque host-driven world (no `frame`) gets exactly
-   * one `update(dt)` call per substep, after the phase loop.
+   * one `update(dt)` call per substep after the phase loop by default. A
+   * display-cadence opaque world is withheld when `skipRenderPhases` is true;
+   * the matching host calls it once from {@link runRenderFrame}. A direct
+   * `runFrame` with render phases included still calls it once.
    *
    * D10/T7.6 play-state addendum: when `Game.play.paused` is true, every
    * `pausable` (and non-`drivesOwnLoop`) world skips every phase EXCEPT
@@ -729,6 +734,8 @@ export interface GameInternal extends Game {
    *   for world in roots (declaration order):
    *     if world.mounted.drivesOwnLoop: continue
    *     world.frame?.runPhase(phase, frozen ? 0 : displayDt)
+   * for opaque world with updateCadence == 'display':
+   *   world.mounted.update?.(frozen ? 0 : displayDt)
    * ```
    *
    * Advances NOTHING: no `tick`, no `simT`, no sim-clock flush, no state-bridge
@@ -1081,7 +1088,12 @@ export function createGame(opts: {
           );
         }
       }
-      const audio = world.mounted.systems?.audio;
+      // A native entry's static `systems` export is this root's primary
+      // declaration surface. `computeSystemAdapters()` already gives it
+      // precedence over a substrate-seeded mounted adapter; pause must read
+      // the same source or a valid entry-declared audio graph is visible to
+      // the editor yet paradoxically reported as ungateable here.
+      const audio = declaredSystemAdapters.get(world.id)?.audio ?? world.mounted.systems?.audio;
       if (audio) {
         audio.setMuted(next);
       } else if (
@@ -1288,10 +1300,21 @@ export function createGame(opts: {
           // Checklist item 2: same isolation for the opaque-world fallback —
           // one foreign mount's `update` throwing must not starve its
           // siblings' `endFrame`/`update` calls this same loop.
-          try {
-            world.mounted.update?.(dt);
-          } catch (err) {
-            console.error(`[game] world "${world.id}" (kind: ${world.kind}) update() threw:`, err);
+          // A display-cadence opaque update is the root's indivisible native
+          // presentation (R3F `advance()` is callbacks + draw). The real
+          // rAF host withholds render phases from EVERY fixed catch-up step;
+          // withhold this update beside them, then run it once in
+          // `runRenderFrameImpl`. A direct/offline `runFrame` includes render
+          // phases and therefore still advances the root exactly once.
+          if (!(skipRenderPhases && world.mounted.updateCadence === 'display')) {
+            try {
+              world.mounted.update?.(dt);
+            } catch (err) {
+              console.error(
+                `[game] world "${world.id}" (kind: ${world.kind}) update() threw:`,
+                err,
+              );
+            }
           }
         }
       }
@@ -1390,6 +1413,27 @@ export function createGame(opts: {
       profiler.endPhase(phase);
     }
 
+    // An opaque display-cadence root cannot expose phase hooks because its
+    // native advance is inseparable. It still belongs to THIS presentation
+    // frame, once — never to every fixed catch-up substep that preceded it.
+    // A frozen world redraws at dt=0, preserving the established pause rule.
+    for (let i = 0; i < n; i++) {
+      const world = roots[i]!;
+      if (world.disposed) continue;
+      if (world.mounted.drivesOwnLoop) continue;
+      if (world.frame) continue;
+      if (world.mounted.updateCadence !== 'display') continue;
+      const frozen = paused && world.pausable;
+      try {
+        world.mounted.update?.(frozen ? 0 : displayDt);
+      } catch (err) {
+        console.error(
+          `[game] world "${world.id}" (kind: ${world.kind}) update() threw (display frame):`,
+          err,
+        );
+      }
+    }
+
     profiler.endFrame();
     if (rngTrapEnabled) rngTrap.disable();
   }

package/src/world3d-react/r3f-root-factory.tsx

@@ -348,11 +348,10 @@ function threeWorldAdapter(id: string, component: ComponentType): RootAdapter {
       if (renderDebugWiring) systemAdapters.renderDebug = renderDebugWiring.adapter;
 
       // The engine drives every `useFrame` through the mounted world's
-      // `update(dt)` hook, never off a raw host-loop callback. That is the
-      // whole pause story: `runFrameImpl` (`runtime/game.ts`) calls
-      // `mounted.update?.(dt)` per substep for a host-driven world and SKIPS
-      // it while that world is frozen, and `Game.play.step()` ticks it exactly
-      // once.
+      // `update(dt)` hook, never off a raw Fiber loop. This mount declares
+      // that indivisible Fiber advance at DISPLAY cadence below: the real
+      // host calls it once per presentation, a paused world gets dt=0, and an
+      // explicit `Game.play.step()` still ticks it exactly once.
       //
       // `advance(timestamp, runGlobalEffects, state)`'s `timestamp` is
       // consumed as `THREE.Clock.elapsedTime` DIRECTLY when
@@ -385,6 +384,14 @@ function threeWorldAdapter(id: string, component: ComponentType): RootAdapter {
           return live().camera;
         },
         drivesOwnLoop: false,
+        // Fiber's `advance()` cannot separate its `useFrame` callbacks from
+        // its WebGL draw. Running this opaque update in every fixed catch-up
+        // substep renders N complete frames inside one rAF callback: once a
+        // scene costs more than 16.7ms, the accumulator asks for more draws,
+        // those draws make the next gap larger, and the loop spirals to its
+        // max-substep ceiling. The host's display pass is the one clock that
+        // must own this inseparable native advance.
+        updateCadence: 'display',
         // Adapter surface: `debug` (the shared game registry) and, when a real
         // WebGL2 context exists, `renderDebug` are engine-seeded. The game's
         // own capabilities arrive as the entry module's declared `systems`.