@vgai/engine 0.5.15 → 0.5.16

package/src/pixi/scene-capture.ts

@@ -79,12 +79,24 @@ interface PixiLike {
   Application: { prototype: Record<string, unknown> };
 }
 
+export interface SceneCapture2DOptions {
+  /**
+   * Select the runtime owned by this mount when other Pixi Applications share
+   * the page (for example editor prefab previews). Rejected draws still count,
+   * but cannot satisfy {@link SceneCapture2DHandle.waitForCapture}.
+   */
+  accept?: ((runtime: CapturedRuntime2D) => boolean) | undefined;
+}
+
 /**
  * Install the render trap on `pixiNamespace.Application.prototype.render`. Pass the
  * host's `pixi.js` namespace so a shared-instance game is trapped. Install once per
  * ingest session; `uninstall()` on teardown.
  */
-export function installSceneCapture2D(pixiNamespace: unknown): SceneCapture2DHandle {
+export function installSceneCapture2D(
+  pixiNamespace: unknown,
+  options: SceneCapture2DOptions = {},
+): SceneCapture2DHandle {
   const PIXI = pixiNamespace as PixiLike;
   const proto = PIXI.Application.prototype;
 
@@ -102,8 +114,11 @@ export function installSceneCapture2D(pixiNamespace: unknown): SceneCapture2DHan
       drawCount++;
       const stage = this['stage'];
       if (!captured && stage) {
-        captured = { stage, renderer: this['renderer'], app: this };
-        for (const resolve of waiters.splice(0)) resolve(captured);
+        const candidate = { stage, renderer: this['renderer'], app: this };
+        if (options.accept?.(candidate) ?? true) {
+          captured = candidate;
+          for (const resolve of waiters.splice(0)) resolve(captured);
+        }
       }
       return realRender?.apply(this, args);
     },
@@ -138,8 +153,8 @@ export function installSceneCapture2D(pixiNamespace: unknown): SceneCapture2DHan
             reject(
               new Error(
                 `pixi scene capture timed out after ${timeoutMs}ms of VISIBLE time ` +
-                  `(${Math.round(captureWindow.elapsedHiddenMs())}ms hidden, which is not counted — ` +
-                  'a hidden tab cannot render) — the game never rendered, or it bundles its own ' +
+                  `(${Math.round(captureWindow.elapsedHiddenMs())}ms browser-suspended, which is ` +
+                  'not counted because no frame can be presented) — the game never rendered, or it bundles its own ' +
                   '(un-shared) copy of pixi.js.',
               ),
             );

package/src/render/particles-factory.ts

@@ -13,6 +13,7 @@ import {
   ApplyForce,
   ChangeEmitDirection,
   CircleEmitter,
+  type ColorGenerator,
   ColorGeneratorFromJSON,
   ColorOverLife,
   ConeEmitter,
@@ -20,6 +21,7 @@ import {
   type EmitterShape,
   ForceOverLife,
   FrameOverLife,
+  type FunctionColorGenerator,
   GravityForce,
   GridEmitter,
   HemisphereEmitter,
@@ -345,9 +347,9 @@ export interface ParticleSystemResult {
  * This is how a caller with fidelity a plain descriptor cannot express reaches
  * the SAME factory instead of hand-building its own `new ParticleSystem(...)`:
  * a foreign-engine carry (e.g. Godot CPUParticles) supplies its own
- * `EmitterShape` and an instancing geometry here, and expresses everything
- * else — lifecycle, start values, emission, behaviors, material — as descriptor
- * JSON.
+ * `EmitterShape`, start-colour generator, and instancing geometry here, and
+ * expresses everything else — lifecycle, scalar start values, emission,
+ * behaviors, material — as descriptor JSON.
  */
 export interface ParticleSystemObjects {
   /**
@@ -356,6 +358,12 @@ export interface ParticleSystemObjects {
    * present it REPLACES `data.shape`.
    */
   shape?: EmitterShape;
+  /**
+   * A pre-built start-colour generator for a per-particle draw the descriptor's
+   * JSON generator vocabulary cannot express. When present it REPLACES
+   * `data.startColor`.
+   */
+  startColor?: ColorGenerator | FunctionColorGenerator;
   /**
    * The geometry instanced per particle in `RenderMode.Mesh`. A
    * `BufferGeometry` is not JSON-serializable, so `renderMode: 'mesh'` requires
@@ -377,8 +385,9 @@ export interface ParticleSystemObjects {
  * Create a three.quarks ParticleSystem from ParticlesDescriptor JSON data.
  *
  * `objects` carries the pieces a JSON descriptor cannot: a plugin emitter
- * shape, a mesh-mode instancing geometry, and the default-sprite toggle. It is
- * optional and additive — a call with only `data` behaves exactly as before.
+ * shape, a start-colour generator, a mesh-mode instancing geometry, and the
+ * default-sprite toggle. It is optional and additive — a call with only `data`
+ * behaves exactly as before.
  */
 // biome-ignore lint/complexity/noExcessiveCognitiveComplexity: straightforward field-by-field mapping
 export function createParticleSystemFromData(
@@ -410,7 +419,8 @@ export function createParticleSystemFromData(
   if (data.startSpeed) params['startSpeed'] = valueGen(data.startSpeed);
   if (data.startSize) params['startSize'] = valueGen(data.startSize);
   if (data.startRotation) params['startRotation'] = valueGen(data.startRotation);
-  if (data.startColor) params['startColor'] = colorGen(data.startColor);
+  if (objects?.startColor) params['startColor'] = objects.startColor;
+  else if (data.startColor) params['startColor'] = colorGen(data.startColor);
   if (data.startTileIndex) params['startTileIndex'] = valueGen(data.startTileIndex);
 
   // Trail mode requires startLength inside rendererEmitterSettings, not as a top-level param

package/src/runtime/create-runtime.ts

@@ -31,12 +31,11 @@ import type { PlaytestContext } from './types';
  * by `createGameRuntime` and every headless test harness
  * (`test/game-root.test.ts`, `test/frame-order.test.ts`,
  * `test/game-two-roots.test.ts`) so there is exactly one code path for this
- * wiring (T7.1 slice 1, id-generalized in slice 3 for the two-world proof — stage
- * 3) — `physics`/`collisions`/`camera`/ `frame` are populated from the mount's
+ * wiring. `physics`/`collisions`/`camera`/`frame` are populated from the mount's
  * first-party `GameContext`/ `MountedSetupThreeRoot` when available, left
  * `undefined` otherwise (an external adapter's mount has none of these
  * first-party handles — `frame` in particular is what makes
- * `GameInternal.runFrame` (T7.1 slice 2) fall back to a single opaque
+ * `GameInternal.runFrame` fall back to a single opaque
  * `mounted.update` call per substep for such a world).
  */
 function firstPartyExtras(
@@ -53,10 +52,8 @@ function firstPartyExtras(
 
 /**
  * Register a three world onto the Game shell. `opts.id` defaults to
- * `'main'` — the single-world callers (`createGameRuntime`, slice-1/2 tests)
- * are unaffected; a second/third world (T7.1 slice 3's two-world proof, and
- * real multi-world manifests later) pass an explicit id. This is the ONE
- * registration code path for a three world, whatever its id.
+ * `'main'`; multi-root callers pass an explicit id. This is the one
+ * registration path for a three world, whatever its id.
  */
 export function registerThreeRoot(
   game: GameInternal,
@@ -104,13 +101,13 @@ export function registerPixiRoot(
 }
 
 /**
- * Register a react world onto the Game shell (T6.2 slice 1) — the react
+ * Register a React world onto the Game shell — the DOM
  * analog of {@link registerThreeRoot}/{@link registerPixiRoot}. A react
  * world has no `frame` hooks (react's own
  * `createRoot` schedules its commits; `GameInternal.runFrame` correctly
  * leaves a world with no `frame` untouched by its opaque-`update` fallback
  * too, since `MountedReactGame` declares no `update`). `adapter` is typed
- * as the real {@link ReactRootAdapter} shape (T7.5, same reasoning as
+ * as the real {@link ReactRootAdapter} shape (same reasoning as
  * `registerPixiRoot`'s doc comment above) — `RootInstance.adapter` only
  * needs `.id`, so this passes through with zero cast.
  */
@@ -134,12 +131,12 @@ export function registerReactRoot(
 }
 
 /**
- * One world to mount in the {@link RootsRuntimeConfig} roots path (T6.1
- * slice 1) — the host-facing mirror of `manifest/load.ts`'s
- * `ResolvedAdapterRoot` (same `id`/`zOrder`/`pausable`/`loop` fields; the
+ * One world to mount in the universal host — the host-facing mirror of
+ * `manifest/load.ts`'s `ResolvedAdapterRoot` (same identity and presentation
+ * fields; the
  * manifest-to-host translation itself is the editor's job, not this file's).
  *
- * `react` (T6.2 slice 1) mounts as a DOM-root layer `<div>` in the SAME
+ * A `dom` root mounts as a DOM layer `<div>` in the same
  * stack instead of a canvas — see {@link ReactRootMountSpec}/{@link
  * ReactRootAdapter} below.
  */
@@ -168,12 +165,6 @@ export interface RootMountSpecBase {
    * never sees DOM roots at all.
    */
   readonly dev?: boolean | undefined;
-  /** `'gated'` (host-driven, default) or `'self-driven'` (this world drives
-   *  its own loop — D5's "composited, unsynchronized" tier). Carried through
-   *  for parity with `ResolvedAdapterRoot`; T6.1 slice 1 does not yet
-   *  validate it against the mounted adapter's actual `drivesOwnLoop` (that
-   *  cross-check, if ever needed, is T7.6's loop-gate surface). */
-  readonly loop?: 'gated' | 'self-driven' | undefined;
   /**
    * Optional claim predicate for the delegating input router (D5 §2a), over
    * a point RELATIVE TO THE CONTAINER. Absent means: this world claims only
@@ -199,8 +190,8 @@ export interface PixiRootMountSpec extends RootMountSpecBase {
 }
 
 /**
- * A live, mounted react world (T6.2 slice 1) — the react analog of a mounted
- * canvas world. React roots render from game state via the T7.4 bridge
+ * A live, mounted React world — the DOM analog of a mounted canvas world.
+ * React roots render from game state
  * instead of a per-frame `update`, so this shape carries no `update`/`fixedUpdate`/
  * `ctx`/`frame` — `drivesOwnLoop` is always `false` (react's `createRoot`
  * schedules its OWN commits; the host's fixed-step loop never drives it,
@@ -217,10 +208,10 @@ export interface PixiRootMountSpec extends RootMountSpecBase {
  * `kind: 'dom'` (§7.1-15): a react world has no `observe` BY DESIGN — that
  * hook is scoped to `useRootObservation` (the ingested/foreign-world case),
  * not `useWorldState` (`ui/game-state.tsx`), which a react world's own
- * mounted tree uses instead — it reads `Game.state` directly (T7.4's actual
- * bridge for first-party-observable state), never a per-world `observe`.
+ * mounted tree uses instead — it reads `Game.state` directly, never a
+ * per-world `observe`.
  *
- * `kind`/`container` (T7.5) satisfy `MountedReactRoot` (`adapter/
+ * `kind`/`container` satisfy `MountedReactRoot` (`adapter/
  * root-adapter.ts`) — `container` is the SAME `DomHostContext.container` the
  * adapter's `mount` was handed (identity matters, mirroring `threeScene()`/
  * `pixiStage()`'s "same instance the adapter mounted" contract); every
@@ -236,7 +227,7 @@ export interface MountedReactGame extends MountedReactRoot {
  * A react-shaped adapter — the structural contract `RootMountSpec`'s
  * `react` variant requires. Deliberately
  * NOT tied to a concrete implementer here so an editor-resolved adapter (the
- * `default-react` resolver branch, T6.2's editor-side follow-up) can satisfy
+ * `default-react` resolver branch) can satisfy
  * this shape without this file importing react-dom or any editor code.
  *
  * A genuine `RootAdapter<'dom'>` refinement (`HostContextFor<'dom'>` =
@@ -328,37 +319,23 @@ export interface RootsRuntimeConfig {
  *
  * This is the GENERIC host handle — it has no first-party concepts (no
  * `GameContext`, no `GameSetupFn`). First-party features (the live `GameContext`,
- * warm-restart hot reload) are reached by casting `mounted` to `MountedSetupThreeRoot`
+ * warm-restart hot reload) are reached through `game.defaultRoot.mounted`
+ * and narrowed to `MountedSetupThreeRoot`
  * (the editor does this for HMR/physics-sync — those are inherently first-party).
  *
- * `scene`/`camera`/`mounted` alias the Game's `defaultRoot`: it is the first
- * three root (else the first
- * world) by DECLARATION order, per `Game.defaultRoot`'s existing rule —
- * independent of `zOrder`/canvas stacking, which is a rendering-only concern.
+ * Root access is explicit through `game.roots`, `game.world(id)`, and
+ * `game.defaultRoot`; the session does not project a surface-specific alias.
  */
 export interface GameSession {
   stop(): void;
   pause(): void;
   resume(): void;
   step(): void;
-  /** Resize every world's render buffer. `pixelRatio` (W2c device preview)
-   *  optionally re-pins the three renderers' DPR in the same pass; omitted,
-   *  the mount-time ratio is left untouched (legacy behavior). */
+  /** Resize every world's render buffer. `pixelRatio` optionally re-pins the
+   * three renderers' DPR in the same pass. */
   resize(width: number, height: number, pixelRatio?: number): void;
-  readonly scene: THREE.Scene;
-  readonly camera: THREE.PerspectiveCamera;
-  /** The default world's mounted root, as the honest `MountedRoot` union —
-   *  narrow on `.kind` before reaching for a surface's own members (the same
-   *  discriminant `scene`/`camera` above use). This deliberately does NOT
-   *  claim `MountedThreeRoot`: a roots-path session whose default world is
-   *  canvas or dom returns that world's mount, and the old
-   *  `as MountedThreeRoot` cast made every such value a type-level lie. For a
-   *  first-party three mount, narrow to `'three'` and cast to
-   *  `MountedSetupThreeRoot` for the first-party extras. */
-  readonly mounted: MountedRoot;
-  /** The Game root (T6.1 slice 1) — the multi-world entry point
-   *  (`game.roots`/`game.world(id)`/`game.queryByComponent`) for callers
-   *  that need more than the default-world aliases above. */
+  /** The multi-root entry point. Root access stays explicit through
+   * `game.roots`, `game.world(id)`, and `game.defaultRoot`. */
   readonly game: Game;
 }
 
@@ -374,7 +351,7 @@ export async function createGameRuntime(config: RootsRuntimeConfig): Promise<Gam
 }
 
 // ---------------------------------------------------------------------------
-// Worlds path (T6.1 slice 1)
+// Universal root host
 // ---------------------------------------------------------------------------
 
 /** A stand-in `THREE.WebGLRenderer` for headless (`headless:true`) three
@@ -397,7 +374,7 @@ function createHeadlessRendererStub(): THREE.WebGLRenderer {
 
 /** One already-mounted world, tracked for disposal + the router. `element`
  *  is the world's stacked surface — an `HTMLCanvasElement` for three/
- *  canvas, or the DOM-root layer `<div>` for react (T6.2 slice 1) — kept
+ *  canvas, or the DOM-root layer `<div>` for React — kept
  *  under one field name so `fullCleanup`'s disposal loop stays kind-generic
  *  (`container.removeChild(entry.element)` needs no branch). */
 interface MountedAdapterRoot {
@@ -477,11 +454,8 @@ async function mountOneThreeRoot(
   // resize-staleness (the roots-path `resize()` below always calls
   // `setSize(rw, rh, false)`, so nothing else was ever going to update this
   // canvas' CSS after mount). `createHostRenderer`'s own default
-  // (`updateStyle:true`) is intentionally left alone — the LEGACY
-  // single-canvas path (editor play-mode's non-multi-world branch) still
-  // relies on that construction-time stamp + its own later `updateStyle:true`
-  // resizes for byte-identical behavior; this fix touches only the
-  // roots-path canvas, after the fact.
+  // (`updateStyle:true`) is intentionally left alone; the host owns CSS layout
+  // and reasserts the container-relative size after renderer construction.
   canvas.style.width = '100%';
   canvas.style.height = '100%';
   renderer.setPixelRatio(dpr);
@@ -559,7 +533,7 @@ async function mountOnePixiRoot(
 }
 
 /**
- * Mount one react `RootMountSpec` (T6.2 slice 1) — the react sibling of
+ * Mount one React `RootMountSpec` — the DOM sibling of
  * `mountOneThreeRoot`/`mountOnePixiRoot`. Unlike its canvas-backed siblings
  * this returns NO `routerEntry`: a react world's DOM-root layer participates in
  * D5's z-order/box stacking (the caller still creates and positions its `<div>`
@@ -592,7 +566,7 @@ async function mountOneReactRoot(
   // An absolutely-positioned layer with no width/height collapses to zero
   // content size, so a child's
   // own position:absolute offsets resolve against a degenerate containing
-  // block (found by the T6.2 slice-3 e2e — clicks landed outside the game).
+  // block; otherwise clicks land outside the game.
   layer.style.width = '100%';
   layer.style.height = '100%';
   const reactHost: DomHostContext = { container: layer, game };
@@ -613,8 +587,8 @@ async function mountOneReactRoot(
 }
 
 /**
- * The roots-path implementer behind {@link createGameRuntime} (T6.1 slice
- * 1; react roots added T6.2 slice 1). Builds ONE surface per world — a
+ * The universal host implementer behind {@link createGameRuntime}. It builds
+ * one surface per world — a
  * canvas for three/canvas, a DOM-root `<div>` layer for react — stacked
  * per D5 §1, z-order/ties exactly matching
  * `manifest/load.ts`'s sort, ONE `Game`, and registers every world onto it
@@ -628,16 +602,11 @@ async function mountOneReactRoot(
 
 /**
  * Dev/e2e-only `window.__vgaiScene`/`__vgaiCamera` exposure for the roots
- * path's DEFAULT world (E4) — split out of `createRootsGameRuntime` purely
- * to keep that function's own cyclomatic complexity down. Mirrors the
- * legacy single-world path's identical exposure (above, in this same file),
- * using the SAME "first three world, else none" default-world rule the
- * `GameSession.scene`/`.camera` getters alias (`Game.defaultRoot`): a
- * non-threejs default world (or none at all) publishes neither global,
- * exactly like those getters return `undefined` in that case. Returns a
- * retraction callback — identity-guarded (a newer session's globals must
- * never be clobbered by an older session's stop, same reason the legacy
- * path's own cleanup guards it) — that is a no-op when nothing was
+ * path's default world — split out of `createRootsGameRuntime` purely
+ * to keep that function's own cyclomatic complexity down. It uses the
+ * "first three world, else none" rule: a non-Three default world publishes
+ * neither global. Returns an identity-guarded retraction callback so an
+ * older session's stop cannot clobber a newer session's globals. It is a no-op when nothing was
  * published (non-DEV build, or non-threejs default world).
  */
 function installDefaultRootDevGlobals(game: GameInternal): () => void {
@@ -804,8 +773,7 @@ async function createRootsGameRuntime(config: RootsRuntimeConfig): Promise<GameS
   // --- Surface stack (D5 §1): DOM/z-order follows zOrder, ties -> array order
   // — computed FIRST (bottom -> top) so both the z-index assignment below and
   // the router's default-claim rule share one definition. A react world's
-  // DOM-root layer shares this SAME stacking pass (T6.2 slice 1 — "one
-  // stacking model, no special case") even though it is a `<div>`, not a
+  // DOM-root layer shares this SAME stacking pass even though it is a `<div>`, not a
   // canvas, and carries no `hitTest` (the router never sees react entries at
   // all — see the dispatch loop below). ---
   // Dev layers sit TOPMOST, above every non-dev root, whatever zOrder either
@@ -862,7 +830,7 @@ async function createRootsGameRuntime(config: RootsRuntimeConfig): Promise<GameS
     // too (not just in `mountOneThreeRoot`) means every surface, whatever
     // kind, starts container-relative from its very first paint, before any
     // per-kind mount work has even run.
-    // `contain:layout paint` makes each surface the CONTAINING BLOCK for
+    // `contain:layout paint` makes each surface the containing block for
     // `position:fixed` descendants (and clips overflow to the world's
     // rectangle): full-screen game UI written the natural way (`fixed;
     // inset:0`) then fills the WORLD, not the page. Without it, `fixed` UI
@@ -936,17 +904,7 @@ async function createRootsGameRuntime(config: RootsRuntimeConfig): Promise<GameS
   started = true;
   loop.start();
 
-  // Expose scene & camera for dev tools / e2e tests — mirrors the legacy
-  // single-world path's identical dev-only exposure above, generalized to
-  // the roots path's DEFAULT world (E4): `mountGameFromManifest`/
-  // `mountManifestRoots` route every caller (including a
-  // single-threejs-world scaffold project) through THIS path, so a caller
-  // migrating off the legacy `{canvas, adapter}` call must not silently
-  // lose `window.__vgaiScene`/`__vgaiCamera` — real e2e/dev tooling
-  // depends on them
-  // (`packages/editor/e2e/tests/04-standalone-game.spec.ts`). Split into
-  // its own top-level helper (with its retraction counterpart below)
-  // purely to keep this function's own cyclomatic complexity down.
+  // Expose the default Three root's scene and camera for dev/e2e tooling.
   const retractDevGlobals = installDefaultRootDevGlobals(game);
 
   // G3/FT-11 — publish `window.__vgaiRender` for the deterministic capture
@@ -986,12 +944,7 @@ async function createRootsGameRuntime(config: RootsRuntimeConfig): Promise<GameS
 
   return {
     stop: fullCleanup,
-    // D10/T7.6: `Game.play` fans out per-world pausable/loop-gate/audio-gate
-    // semantics itself now (see the legacy path's identical comment above) —
-    // a `pausable: false` world (a menu/HUD world) keeps ticking while every
-    // other world freezes, which the old blind `for (const entry of
-    // mountedEntries) entry.mounted.setPaused?.(true)` fan-out (with no
-    // `pausable` check at all) could never express.
+    // `Game.play` owns per-world pause, loop-gate, and audio-gate semantics.
     pause() {
       game.play.pause();
     },
@@ -1014,24 +967,6 @@ async function createRootsGameRuntime(config: RootsRuntimeConfig): Promise<GameS
         entry.mounted.resize?.(safeWidth, safeHeight);
       }
     },
-    // `GameSession.scene`/`.camera`/`.mounted` alias `Game.defaultRoot` (T6.1
-    // slice 1's "first three world, else first world" rule) — a legacy
-    // convenience shaped for the threejs-only past. T7.5 narrows the read via
-    // the `kind` discriminant instead of a blind `.scene`/`.camera` cast
-    // through a nonexistent property (identical behavior to before: still
-    // `undefined` for a roots-path session whose default world isn't
-    // three — real per-world surface routing for that case is T7.6's).
-    get scene() {
-      const m = game.defaultRoot.mounted;
-      return (m.kind === 'three' ? m.scene : undefined) as THREE.Scene;
-    },
-    get camera() {
-      const m = game.defaultRoot.mounted;
-      return (m.kind === 'three' ? m.camera : undefined) as THREE.PerspectiveCamera;
-    },
-    get mounted() {
-      return game.defaultRoot.mounted;
-    },
     game,
   };
 }