@vgai/engine 0.5.39 → 0.5.41

package/dist/runtime/game.d.ts

@@ -89,8 +89,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
@@ -405,8 +406,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
@@ -449,13 +450,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
@@ -495,6 +500,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

package/dist/runtime/game.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"game.d.ts","sourceRoot":"","sources":["../../src/runtime/game.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"game.d.ts","sourceRoot":"","sources":["../../src/runtime/game.ts"],"names":[],"mappings":"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"}

package/dist/runtime/game.js

@@ -282,6 +282,7 @@ export function createGame(opts) {
     const debugRegistry = createDebugRegistry({
         getTick: () => tick,
         getSimT: () => simT,
+        getFixedDt: () => opts.loop.fixedDt,
         // D15/T-D15.5 — "the manifest's first/default world" for the debug
         // registry's world-addressed input-target surface. Every
         // first-party root now registers the SAME game-owned InputManager, but the
@@ -435,7 +436,12 @@ export function createGame(opts) {
                     reportGateShortfallOnce('loop', world.id, 'self-driven world, adapter declares no setPaused capability');
                 }
             }
-            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);
             }
@@ -643,11 +649,19 @@ 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);
+                        }
                     }
                 }
             }
@@ -746,6 +760,28 @@ 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/dist/world3d-react/frame-delta.d.ts

@@ -0,0 +1,15 @@
+/**
+ * The exact host-owned delta for the synchronous R3F frame currently being dispatched.
+ *
+ * Fiber's `frameloop: 'never'` API accepts an absolute timestamp and reconstructs the frame
+ * delta by subtracting its previous timestamp. Once that timestamp is large enough, ordinary
+ * floating-point cancellation can turn an exact host `1 / 60` into either adjacent double. The
+ * host still owns the original exact `dt`; adapter-boundary runtimes that must reproduce another
+ * engine's clock can read it here instead of mistaking Fiber's reconstruction residue for game
+ * time. The seat exists only for the synchronous `advance(...)` call and is cleared immediately
+ * afterwards, so an async consumer can never read a stale frame.
+ */
+export declare function setHostFrameDelta(state: object, delta: number): void;
+export declare function clearHostFrameDelta(state: object): void;
+export declare function hostFrameDelta(state: object, fiberDelta: number): number;
+//# sourceMappingURL=frame-delta.d.ts.map

package/dist/world3d-react/frame-delta.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"frame-delta.d.ts","sourceRoot":"","sources":["../../src/world3d-react/frame-delta.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAIH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI,CAEpE;AAED,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAEvD;AAED,wBAAgB,cAAc,CAAC,KAAK,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,MAAM,CAExE"}

package/dist/world3d-react/frame-delta.js

@@ -0,0 +1,21 @@
+/**
+ * The exact host-owned delta for the synchronous R3F frame currently being dispatched.
+ *
+ * Fiber's `frameloop: 'never'` API accepts an absolute timestamp and reconstructs the frame
+ * delta by subtracting its previous timestamp. Once that timestamp is large enough, ordinary
+ * floating-point cancellation can turn an exact host `1 / 60` into either adjacent double. The
+ * host still owns the original exact `dt`; adapter-boundary runtimes that must reproduce another
+ * engine's clock can read it here instead of mistaking Fiber's reconstruction residue for game
+ * time. The seat exists only for the synchronous `advance(...)` call and is cleared immediately
+ * afterwards, so an async consumer can never read a stale frame.
+ */
+const hostFrameDeltas = new WeakMap();
+export function setHostFrameDelta(state, delta) {
+    hostFrameDeltas.set(state, delta);
+}
+export function clearHostFrameDelta(state) {
+    hostFrameDeltas.delete(state);
+}
+export function hostFrameDelta(state, fiberDelta) {
+    return hostFrameDeltas.get(state) ?? fiberDelta;
+}

package/dist/world3d-react/r3f-root-factory.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"r3f-root-factory.d.ts","sourceRoot":"","sources":["../../src/world3d-react/r3f-root-factory.tsx"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AAWH,OAAO,KAAK,EAAoB,WAAW,EAAoB,MAAM,YAAY,CAAC;AAelF,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,uBAAuB,CAAC;AAsZnE;;;;;;;;;;;GAWG;AACH,wBAAgB,sBAAsB,CAAC,WAAW,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,GAAG,WAAW,GAAG,IAAI,CAI/F;AAED;;GAEG;AACH,eAAO,MAAM,cAAc,EAAE,qBAO5B,CAAC"}
+{"version":3,"file":"r3f-root-factory.d.ts","sourceRoot":"","sources":["../../src/world3d-react/r3f-root-factory.tsx"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AAWH,OAAO,KAAK,EAAoB,WAAW,EAAoB,MAAM,YAAY,CAAC;AAelF,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,uBAAuB,CAAC;AAmanE;;;;;;;;;;;GAWG;AACH,wBAAgB,sBAAsB,CAAC,WAAW,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,GAAG,WAAW,GAAG,IAAI,CAI/F;AAED;;GAEG;AACH,eAAO,MAAM,cAAc,EAAE,qBAO5B,CAAC"}

package/dist/world3d-react/r3f-root-factory.js

@@ -45,6 +45,7 @@ import { WorldProvider } from '../react/world-state';
 import { getDebugRegistry } from '../runtime/debug-registry';
 import { devBuildEnabled } from '../runtime/dev-build';
 import { DEFAULT_INPUT_MAP_PATH, wireGameInputSeams } from '../runtime/game-input-seams';
+import { clearHostFrameDelta, setHostFrameDelta } from './frame-delta';
 /**
  * Build the `RootAdapter` for one default-exported R3F world. Mounts through
  * react-three-fiber, gated entirely by the host's own loop and rendering
@@ -291,11 +292,10 @@ function threeWorldAdapter(id, component) {
             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
@@ -327,6 +327,14 @@ function threeWorldAdapter(id, component) {
                     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`.
@@ -334,8 +342,12 @@ function threeWorldAdapter(id, component) {
                 update(dt) {
                     elapsed += dt;
                     const current = live();
-                    renderDebugWiring?.beforeRender();
+                    // Fiber receives an ABSOLUTE timestamp and reconstructs `delta` by subtraction. Publish
+                    // the exact host-owned dt beside the synchronous advance so compatibility adapters that
+                    // reproduce another engine's frame clock do not inherit one-ulp cancellation residue.
+                    setHostFrameDelta(current, dt);
                     try {
+                        renderDebugWiring?.beforeRender();
                         const profiler = host.game?.profiler;
                         if (!profiler?.enabled) {
                             advance(elapsed, true, current);
@@ -374,6 +386,7 @@ function threeWorldAdapter(id, component) {
                         }
                     }
                     finally {
+                        clearHostFrameDelta(current);
                         renderDebugWiring?.afterRender();
                     }
                 },

package/package.json

@@ -2,7 +2,7 @@
   "name": "@vgai/engine",
   "author": "Volter AI, Inc.",
   "license": "Apache-2.0",
-  "version": "0.5.39",
+  "version": "0.5.41",
   "description": "Readable TypeScript game engine and universal host for Three.js, PixiJS, and React games.",
   "keywords": [
     "game-engine",

package/src/adapter/authoring.ts

@@ -110,6 +110,12 @@ export interface EditorNode {
   typeLabel?: string;
   parentId: string | null;
   childIds: string[];
+  /** Opaque project-owned identity shared by authored rows across adapter roots. */
+  crossSurfaceId?: string;
+  /** Optional authored parent identity resolved against another row's cross-surface id. */
+  crossSurfaceParentId?: string;
+  /** Source-owned sibling ordinal used only when native rows are joined across surfaces. */
+  crossSurfaceOrder?: number;
 }
 
 export interface PropertyDescriptor {

package/src/adapter/root-adapter.ts

@@ -65,6 +65,23 @@ export interface MountedRootBase {
    */
   readonly drivesOwnLoop: boolean;
 
+  /**
+   * Which host clock owns an opaque mounted root's single `update(dt)` hook.
+   *
+   * `fixed` (the default) preserves the adapter seam's original contract:
+   * the callback runs once per consumed simulation substep. `display` is for
+   * a reconciler whose one native advance is inseparably BOTH its callbacks
+   * and its draw (React Three Fiber's `advance()` is the measured case). The
+   * real host then withholds it from fixed catch-up substeps and invokes it
+   * exactly once from the display pass. A direct/offline `runFrame` that does
+   * not skip render phases still invokes it once, preserving capture and
+   * explicit-tick semantics.
+   *
+   * Absent means `fixed`. This changes no foreign/ingest adapter unless that
+   * adapter opts in explicitly.
+   */
+  readonly updateCadence?: 'fixed' | 'display';
+
   update?(dt: number): void; // host-driven only
   fixedUpdate?(dt: number): void;
   setPaused?(paused: boolean): void; // capability, not promise — see loop-model note above

package/src/adapter/root-seam-contract.ts

@@ -18,6 +18,7 @@ export const ROOT_ADAPTER_SHAPE = defineSeamShape<RootAdapter<AdapterSurface>>()
 
 export const MOUNTED_ROOT_BASE_SHAPE = defineSeamShape<MountedRootBase>()({
   drivesOwnLoop: { optional: false, kind: 'value', required: 'shape' },
+  updateCadence: { optional: true, kind: 'value', required: 'shape' },
   update: { optional: true, kind: 'function', required: 'effect' },
   fixedUpdate: { optional: true, kind: 'function', required: 'effect' },
   setPaused: { optional: true, kind: 'function', required: 'effect' },