@vgai/engine 0.5.15 → 0.5.17

package/src/pixi/authoring.ts

@@ -44,11 +44,264 @@ export type Overlay2D = Record<string, Override2D>;
 function kindOf(o: Container): string {
   const ctor = o.constructor?.name?.toLowerCase() ?? 'container';
   if (ctor.includes('animatedsprite')) return 'animatedsprite';
+  if (ctor.includes('nineslice')) return 'nineslicesprite';
+  if (ctor.includes('tiling')) return 'tilingsprite';
   if (ctor.includes('sprite')) return 'sprite';
   if (ctor.includes('text')) return 'text';
+  if (ctor.includes('graphics')) return 'graphics';
   return 'container';
 }
 
+/**
+ * Hierarchy row text — the Pixi sibling of three's `object.name || object.type`.
+ *
+ * Authored `.label` first. Then a GAME name: a field, a bag key, or a class
+ * that owns this `.view`. Stock Pixi types (`Sprite`, `Graphics`, `_Container`)
+ * are not names — they used to win and hide every owner. Then the texture
+ * alias (`Sprite.from('satellite')`). Then a remaining game constructor
+ * (`TitleScreen`, `PrimaryButton`). Bare `new Container()` still reads as
+ * `container` — plus its child count when it has children, because ten
+ * unnamed siblings that all read `container` name nothing at all; the
+ * editor loads games that never labelled anything and the panel still has
+ * to be legible. The count is DISPLAY only (row ids keep using raw
+ * `.label`) and rides only this last fallthrough: a row that earned a real
+ * name is never decorated.
+ */
+function displayLabel(o: Container): string {
+  const authored = authoredLabel(o);
+  if (authored) return authored;
+  const owner = viewOwnerLabel(o);
+  if (owner) return owner;
+  const asset = textureLabel(o);
+  if (asset) return asset;
+  const ctor = usefulCtorName(o);
+  if (ctor) return ctor;
+  const kind = kindOf(o);
+  const childCount = o.children?.length ?? 0;
+  return childCount > 0 ? `${kind} (${childCount})` : kind;
+}
+
+/**
+ * Pixi v8 stamps Sprite/Graphics `.label` with the class name. That is not an
+ * authored name.
+ *
+ * The minified-constructor guard is about the SAME leak: a shipped build's
+ * `_Container` becomes `e`, and that `e` is a class name wearing a label's
+ * clothes. It is only that leak when the label IS this object's own class
+ * name — `container.label = 'fx'` (or 'ui', 'hp') is a name the game
+ * actually authored, and a game gets to be terse.
+ */
+function authoredLabel(o: Container): string | undefined {
+  const authored = o.label?.trim();
+  if (!authored) return undefined;
+  if (isMinifiedCtor(authored) && authored !== o.constructor?.name) return authored;
+  if (isGenericPixiCtor(authored)) return undefined;
+  return authored;
+}
+
+function isMinifiedCtor(name: string): boolean {
+  return name.length <= 2 && name === name.toLowerCase();
+}
+
+/** Pixi's own display types. The shipped build prefixes them `_`. */
+const STOCK_PIXI_CTOR = new Set([
+  'container',
+  'displayobject',
+  'sprite',
+  'animatedsprite',
+  'nineslicesprite',
+  'tilingsprite',
+  'text',
+  'bitmaptext',
+  'htmltext',
+  'graphics',
+  'mesh',
+]);
+
+function isGenericPixiCtor(name: string): boolean {
+  if (isMinifiedCtor(name) || name === 'Object' || name === 'Function') return true;
+  return STOCK_PIXI_CTOR.has(name.replace(/^_+/, '').toLowerCase());
+}
+
+function textureLabel(object: Container): string | undefined {
+  const texture = (object as Container & { texture?: { label?: string } }).texture;
+  const raw = texture?.label?.trim();
+  if (!raw || /^(_?texture)?(empty|white)$/i.test(raw)) return undefined;
+  const leaf = raw.split('/').pop() ?? raw;
+  return leaf.replace(/\.[a-z0-9]+$/i, '') || undefined;
+}
+
+function usefulCtorName(value: object): string | undefined {
+  const name = value.constructor?.name;
+  if (!name || isGenericPixiCtor(name)) return undefined;
+  return name.replace(/^_+/, '') || undefined;
+}
+
+function fieldLabel(key: string): string | undefined {
+  const trimmed = key.replace(/^_+/, '');
+  return trimmed.length > 0 ? trimmed : undefined;
+}
+
+function isPixiDisplay(value: object): boolean {
+  return (
+    'addChild' in value &&
+    typeof (value as { addChild?: unknown }).addChild === 'function' &&
+    'children' in value
+  );
+}
+
+/**
+ * Bubbo-style owner, identity only. TitleScreen keeps `this._cannon` and
+ * parents `this._cannon.view`. A grouping node is the field itself
+ * (`this._bottomAnimContainer`). A pool or atlas lives in a bag — Array,
+ * Map, Set, or an object literal (`_decor[]`, `allSystems`, `_parts[id]`).
+ * Scan each ancestor's own fields first — a flood walk of Pixi internals
+ * never reached `_cannon` inside the budget.
+ */
+function viewOwnerLabel(view: Container): string | undefined {
+  const seen = new WeakSet<object>();
+  let host: unknown = view.parent;
+  for (let hops = 0; hops < 8 && host && typeof host === 'object'; hops++) {
+    const found = labelFromHolder(host, view, seen) ?? findHeldOwner(host, view, 2, seen);
+    if (found) return found;
+    host = (host as { parent?: unknown }).parent;
+  }
+  return undefined;
+}
+
+function isGameFieldKey(key: string): boolean {
+  // Skip display-list indices (`0`, `1`) and Pixi internals (`children`).
+  return /^_?[A-Za-z][A-Za-zA-Z0-9]*$/.test(key) && !PIXI_INTERNAL_KEY.has(key);
+}
+
+const PIXI_INTERNAL_KEY = new Set([
+  'parent',
+  'children',
+  'transform',
+  'position',
+  'scale',
+  'pivot',
+  'skew',
+  'worldTransform',
+  'localTransform',
+]);
+
+function labelFromHolder(host: object, view: Container, seen: WeakSet<object>): string | undefined {
+  if (seen.has(host)) return undefined;
+  seen.add(host);
+  const asBag = nameInBag(host, view, undefined, seen);
+  if (asBag) return asBag;
+  for (const [key, value] of Object.entries(host as Record<string, unknown>)) {
+    if (!isGameFieldKey(key)) continue;
+    const named = nameIfHoldsView(host, key, value, view);
+    if (named) return named;
+    const nested = nameInBag(value, view, key, seen);
+    if (nested) return nested;
+  }
+  return undefined;
+}
+
+function nameInBag(
+  value: unknown,
+  view: Container,
+  fieldKey: string | undefined,
+  seen: WeakSet<object>,
+): string | undefined {
+  const entries = bagEntries(value);
+  if (!entries) return undefined;
+  for (const [itemKey, item] of entries) {
+    const named = nameBagItem(value, item, usableBagKey(itemKey) ?? fieldKey, view, seen);
+    if (named) return named;
+  }
+  return undefined;
+}
+
+function nameBagItem(
+  bag: unknown,
+  item: unknown,
+  key: string | undefined,
+  view: Container,
+  seen: WeakSet<object>,
+): string | undefined {
+  if (key) {
+    const named = nameIfHoldsView(
+      item && typeof item === 'object' ? item : (bag as object),
+      key,
+      item,
+      view,
+    );
+    if (named) return named;
+  } else if (item && typeof item === 'object' && (item as { view?: unknown }).view === view) {
+    const named = usefulCtorName(item);
+    if (named) return named;
+  }
+  if (item && typeof item === 'object' && !isPixiDisplay(item)) {
+    return labelFromHolder(item, view, seen);
+  }
+  return undefined;
+}
+
+function usableBagKey(key: string): string | undefined {
+  if (!key || /^\d+$/.test(key)) return undefined;
+  return isGameFieldKey(key) || key.includes('-') ? (fieldLabel(key) ?? key) : undefined;
+}
+
+function bagEntries(value: unknown): readonly [string, unknown][] | undefined {
+  if (!value || typeof value !== 'object') return undefined;
+  // Game arrays are allowed to be exotic subclasses. Do not dispatch through
+  // their overridable `map`: one shipped Pixi game returns its elements rather
+  // than `[key, value]` pairs there, which made hierarchy labeling throw while
+  // destructuring the result. The authoring seam treats game objects as
+  // untrusted observations, so normalize with indexed reads into our own array.
+  if (Array.isArray(value)) {
+    const entries: [string, unknown][] = [];
+    for (let index = 0; index < value.length; index++) {
+      entries.push([String(index), value[index]]);
+    }
+    return entries;
+  }
+  if (value instanceof Map) return [...value.entries()].map(([key, item]) => [String(key), item]);
+  if (value instanceof Set) return [...value].map((item, index) => [String(index), item]);
+  if (Object.getPrototypeOf(value) !== Object.prototype) return undefined;
+  return Object.entries(value as Record<string, unknown>);
+}
+
+function nameIfHoldsView(
+  host: object,
+  key: string,
+  value: unknown,
+  view: Container,
+): string | undefined {
+  if (value === view) {
+    const field = fieldLabel(key);
+    if (field && field.toLowerCase() !== 'view') {
+      return usefulCtorName(value as object) ?? field;
+    }
+    return usefulCtorName(value as object) ?? usefulCtorName(host) ?? field;
+  }
+  if (value && typeof value === 'object' && (value as { view?: unknown }).view === view) {
+    return usefulCtorName(value) ?? fieldLabel(key);
+  }
+  return undefined;
+}
+
+function findHeldOwner(
+  held: object,
+  view: Container,
+  depth: number,
+  seen: WeakSet<object>,
+): string | undefined {
+  const direct = labelFromHolder(held, view, seen);
+  if (direct) return direct;
+  if (depth <= 0) return undefined;
+  for (const value of Object.values(held as Record<string, unknown>)) {
+    if (!value || typeof value !== 'object' || isPixiDisplay(value)) continue;
+    const found = findHeldOwner(value, view, depth - 1, seen);
+    if (found) return found;
+  }
+  return undefined;
+}
+
 /**
  * WHERE A ROW'S ID COMES FROM — the identity axis of the canvas authoring
  * surface.
@@ -78,11 +331,52 @@ export const STRUCTURAL_CANVAS_IDENTITY: CanvasIdentity = {
   idFor: (object, path) => `w2d:${path.join('/')}:${kindOf(object)}:${object.label ?? ''}`,
 };
 
+/** One remembered row name, with every input it was derived from. */
+interface NameMemo {
+  readonly label: string;
+  readonly kind: string;
+  readonly parent: Container | null;
+  readonly type: unknown;
+  readonly own: string | null;
+  readonly texture: unknown;
+  readonly childCount: number;
+}
+
 export class AuthoringAdapter2D {
   private readonly byId = new Map<string, Container>();
   private overlay: Overlay2D = {};
   private dirty = false;
   private readonly identity: CanvasIdentity;
+  /**
+   * THE ROW-NAME MEMO — what makes a hierarchy read linear instead of a
+   * reflective flood walk per node per read.
+   *
+   * {@link displayLabel} is not a field read. For anything the game did not
+   * label itself it calls `viewOwnerLabel`, which climbs eight ancestors and
+   * reflects over each one's own fields, its bags, and two levels of whatever
+   * those hold — a deliberate search for the game object that owns this
+   * `.view`. Measured 2026-08-20 on a 1822-node `@pixi/react` canvas world,
+   * with the tab VISIBLE and the world rendering, one full projection walk
+   * cost ~800ms, essentially all of it here: once a world has rendered, the
+   * ancestors' own fields include Pixi's live render-group graph, so the
+   * search walks that too and finds nothing, every time, for every node.
+   *
+   * And it was asked four times per node per derivation — the projection
+   * walk, the conformance probe and the hierarchy facet each re-ask — which
+   * is how a status snapshot reached 115,433 `toNode` calls on one tree.
+   *
+   * ## What invalidates a remembered name
+   *
+   * Every input the derivation reads OFF THE OBJECT: its authored `.label`,
+   * its class, its texture, its parent, and how many children it has. Any of
+   * those changing re-derives — so a rename, a reparent, a retexture, and a
+   * sibling added or removed are all seen. What a remembered name does NOT
+   * re-notice is a game reassigning an ANCESTOR's field to point at this view
+   * after the fact, with the tree otherwise untouched; `viewOwnerLabel` is a
+   * naming heuristic, not a verdict, and the alternative is the 800ms walk
+   * above on every read of the tree.
+   */
+  private readonly names = new WeakMap<Container, NameMemo>();
 
   constructor(
     private readonly root: Container,
@@ -143,12 +437,45 @@ export class AuthoringAdapter2D {
     return this.byId.get(id) ?? null;
   }
 
+  /** This object's row name, derived once and remembered until one of the
+   *  inputs it is derived from changes. See {@link names}. */
+  private nameOf(o: Container): NameMemo {
+    const cached = this.names.get(o);
+    const parent = o.parent ?? null;
+    const type = o.constructor;
+    const own = o.label ?? null;
+    const texture = (o as Container & { texture?: unknown }).texture ?? null;
+    const childCount = o.children?.length ?? 0;
+    if (
+      cached &&
+      cached.parent === parent &&
+      cached.type === type &&
+      cached.own === own &&
+      cached.texture === texture &&
+      cached.childCount === childCount
+    ) {
+      return cached;
+    }
+    const derived: NameMemo = {
+      label: displayLabel(o),
+      kind: kindOf(o),
+      parent,
+      type,
+      own,
+      texture,
+      childCount,
+    };
+    this.names.set(o, derived);
+    return derived;
+  }
+
   private toNode(o: Container): EditorNode2D {
     const self = o as Container & { __authId?: string };
+    const { label, kind } = this.nameOf(o);
     return {
       id: self.__authId ?? '',
-      label: o.label ?? kindOf(o),
-      kind: kindOf(o),
+      label,
+      kind,
       parentId: (o.parent as (Container & { __authId?: string }) | null)?.__authId ?? null,
       childIds: o.children.map((c) => (c as Container & { __authId?: string }).__authId ?? ''),
     };

package/src/pixi/ingest.ts

@@ -1,5 +1,9 @@
 import type { VisibleCaptureWindow } from '../adapter/ingest/visible-capture-window';
-import { installSceneCapture2D, type SceneCapture2DHandle } from './scene-capture';
+import {
+  type CapturedRuntime2D,
+  installSceneCapture2D,
+  type SceneCapture2DHandle,
+} from './scene-capture';
 
 /** A registered unmodified PixiJS game (the Pixi analog of `IngestGame`). */
 export interface IngestGame2D {
@@ -39,9 +43,12 @@ export async function mountIngestGame2D(
   opts: {
     captureTimeoutMs?: number;
     onWait?: (wait: VisibleCaptureWindow | null) => void;
+    acceptCapture?: (runtime: CapturedRuntime2D) => boolean;
   } = {},
 ): Promise<IngestMount2D> {
-  const capture = installSceneCapture2D(pixiNamespace);
+  const capture = installSceneCapture2D(pixiNamespace, {
+    ...(opts.acceptCapture ? { accept: opts.acceptCapture } : {}),
+  });
   try {
     await game.load();
   } catch (err) {

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/react/world-state.tsx

@@ -70,6 +70,21 @@ export function useGame(): Game {
   return game;
 }
 
+/**
+ * {@link useGame}'s non-throwing sibling: the `Game` when one hosts this tree,
+ * `null` otherwise.
+ *
+ * For components that legitimately mount BOTH under a running game and under a
+ * host that has none — the editor design-mounts a world to author it, and a
+ * story renders a component with no game at all. Those components must degrade
+ * (a dev/QA surface that simply has nothing to drive) rather than throw during
+ * render, which would take the whole world down with it. Everything else uses
+ * `useGame`, whose throw is the honest report of a wiring bug.
+ */
+export function useOptionalGame(): Game | null {
+  return useContext(GameContext);
+}
+
 /**
  * Subscribe to a selected slice of game state. Re-renders only when the
  * selected value changes: the selector re-runs at most once per completed

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/render/soft-particle-depth.ts

@@ -91,9 +91,9 @@
  *   callers are `registerParticleSystem` / `unregisterParticleSystem`.
  * - The render target and override material belong to the
  *   {@link SoftParticleDepthPass} instance and die with its `dispose()`. The
- *   pass itself is owned by whichever adapter mount created it (the R3F adapter
- *   and `setup-three-root-adapter`), and that mount's teardown is the one path
- *   allowed to end it.
+ *   pass is owned by the renderer loop that calls it: an adapter mount for a
+ *   runtime renderer, or the editor Scene viewport for its renderer. That
+ *   owner's teardown is the one path allowed to end it.
  */
 
 import * as THREE from 'three';
@@ -203,16 +203,11 @@ function drawsIntoDepth(object: THREE.Object3D): boolean {
  * The three renderer members this prepass CANNOT do without — the render-target
  * swap it draws through, and the buffer size it sizes that target from.
  *
- * A real `WebGLRenderer` has all of them. A DESIGN-TIME settle does not: a
- * stand-in that only has to answer `render` mounts a world so the editor can
- * read it, and reaching for `getDrawingBufferSize` on one threw
- * `renderer.getDrawingBufferSize is not a function` out of the first driven
- * frame — so a world whose particles merely *declare* a proximity fade could
- * not be settled at all. A prepass is an EFFECT: with no renderer to run it on,
- * the right answer is the inert far-depth default every batch is already bound
- * to (see {@link farDepthTexture}), which is pixel-identical to a batch that
- * never asked for soft particles. So this degrades, loudly and once, instead of
- * taking the frame down with it.
+ * A real `WebGLRenderer` has all of them. A design-time stand-in that only has
+ * to answer `render` may mount a world so another host can read it, but cannot
+ * run this effect. The editor does not pass that stand-in here: its real
+ * viewport renderer owns its own pass. Other incomplete hosts still degrade
+ * loudly and once instead of taking the frame down.
  */
 const REQUIRED_RENDERER_MEMBERS = [
   'getDrawingBufferSize',