@vgai/engine 0.5.40 → 0.5.41

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`.