@vgai/engine 0.5.17 → 0.5.19

package/src/pixi/authoring.ts

@@ -159,43 +159,125 @@ function isPixiDisplay(value: object): boolean {
  * never reached `_cannon` inside the budget.
  */
 function viewOwnerLabel(view: Container): string | undefined {
-  const seen = new WeakSet<object>();
+  const search: OwnerSearch = { seen: new WeakSet<object>(), budget: OWNER_SEARCH_BUDGET };
   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 (search.budget <= 0) return undefined;
+    const found = labelFromHolder(host, view, search) ?? findHeldOwner(host, view, 2, search);
     if (found) return found;
     host = (host as { parent?: unknown }).parent;
   }
   return undefined;
 }
 
+/**
+ * THE CEILING ON ONE NODE'S OWNER HUNT — what keeps a hierarchy read LINEAR in
+ * the size of the tree instead of quadratic in it.
+ *
+ * The hunt below is a search of the GAME's object graph, and a game's object
+ * graph is small: `this._cannon`, `allSystems.get('hud')`, `_decor[3]` are all
+ * found within a few dozen examinations. What is not small is anything the
+ * search can leak into — Pixi's own live render graph is the measured one, and
+ * naming a key blacklist is a fix for the leak you already found, not for the
+ * class. So every examination is charged against this budget and the search
+ * simply gives up when it runs out: the node then falls through to its texture
+ * alias / constructor / kind name, which is the same honest answer it gets
+ * today whenever the hunt finds nothing.
+ *
+ * MEASURED (2026-08-20, `packages/editor/scripts/scale-harness`): entering play
+ * on a 20 000-node `@pixi/react` world blocked the main thread for 199.5
+ * SECONDS in one synchronous run, 69% of all profiler samples inside this
+ * search, because `parentRenderGroup` reaches an array of every node in the
+ * tree and the search walked it once per unlabeled node. `vgai play`,
+ * `screenshot` and `stop` all timed out against a tab that was heartbeating
+ * normally the whole time.
+ */
+const OWNER_SEARCH_BUDGET = 2_000;
+
+/** One node's owner hunt: what it has already looked at, and what it has left. */
+interface OwnerSearch {
+  readonly seen: WeakSet<object>;
+  /** Counts DOWN. Zero ends the hunt for this node, wherever it has reached. */
+  budget: number;
+}
+
+/** Charge one examination. `false` means the hunt is over. */
+function spend(search: OwnerSearch): boolean {
+  if (search.budget <= 0) return false;
+  search.budget -= 1;
+  return true;
+}
+
 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);
+  // The membership test is on the UNDERSCORED-STRIPPED key because that is how
+  // Pixi v8 spells most of them (`_position`, `_bounds`, `_texture`), and a
+  // set listing the bare names was silently matching none of those.
+  if (!/^_?[A-Za-z][A-Za-zA-Z0-9]*$/.test(key)) return false;
+  return !PIXI_INTERNAL_KEY.has(key.replace(/^_+/, ''));
 }
 
+/**
+ * Field names that belong to Pixi (or to its EventEmitter base), never to the
+ * game. Read off a live `pixi.js` v8 `Container`/`Sprite`'s own keys, so this
+ * is a transcription rather than a guess — but it is the OPTIMIZATION, not the
+ * correctness boundary: {@link OWNER_SEARCH_BUDGET} is what bounds the search
+ * on a Pixi version whose internals this list has never heard of. Spending the
+ * budget on plausible game fields instead of on the render graph is what keeps
+ * the heuristic's hit rate while it is bounded.
+ *
+ * `view` is deliberately absent: `.view` is the very field the hunt is looking
+ * for.
+ */
 const PIXI_INTERNAL_KEY = new Set([
   'parent',
   'children',
   'transform',
   'position',
+  'origin',
   'scale',
   'pivot',
   'skew',
+  'anchor',
   'worldTransform',
   'localTransform',
+  'groupTransform',
+  'relativeGroupTransform',
+  // The render graph — the measured leak. `parentRenderGroup` is on every
+  // container once a world has rendered and reaches every node in the tree.
+  'renderGroup',
+  'parentRenderGroup',
+  'parentRenderGroupIndex',
+  'parentRenderLayer',
+  'relativeRenderGroupDepth',
+  'renderPipeId',
+  'instructionSet',
+  'childrenToUpdate',
+  'childrenRenderablesToUpdate',
+  'effects',
+  'filters',
+  'mask',
+  'bounds',
+  'boundsArea',
+  'visualBounds',
+  'gpuData',
+  'texture',
+  'events',
+  'eventsCount',
+  'updateFlags',
 ]);
 
-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);
+function labelFromHolder(host: object, view: Container, search: OwnerSearch): string | undefined {
+  if (search.seen.has(host)) return undefined;
+  search.seen.add(host);
+  const asBag = nameInBag(host, view, undefined, search);
   if (asBag) return asBag;
   for (const [key, value] of Object.entries(host as Record<string, unknown>)) {
+    if (!spend(search)) return undefined;
     if (!isGameFieldKey(key)) continue;
     const named = nameIfHoldsView(host, key, value, view);
     if (named) return named;
-    const nested = nameInBag(value, view, key, seen);
+    const nested = nameInBag(value, view, key, search);
     if (nested) return nested;
   }
   return undefined;
@@ -205,12 +287,13 @@ function nameInBag(
   value: unknown,
   view: Container,
   fieldKey: string | undefined,
-  seen: WeakSet<object>,
+  search: OwnerSearch,
 ): 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 (!spend(search)) return undefined;
+    const named = nameBagItem(value, item, usableBagKey(itemKey) ?? fieldKey, view, search);
     if (named) return named;
   }
   return undefined;
@@ -221,7 +304,7 @@ function nameBagItem(
   item: unknown,
   key: string | undefined,
   view: Container,
-  seen: WeakSet<object>,
+  search: OwnerSearch,
 ): string | undefined {
   if (key) {
     const named = nameIfHoldsView(
@@ -236,7 +319,7 @@ function nameBagItem(
     if (named) return named;
   }
   if (item && typeof item === 'object' && !isPixiDisplay(item)) {
-    return labelFromHolder(item, view, seen);
+    return labelFromHolder(item, view, search);
   }
   return undefined;
 }
@@ -246,22 +329,40 @@ function usableBagKey(key: string): string | undefined {
   return isGameFieldKey(key) || key.includes('-') ? (fieldLabel(key) ?? key) : undefined;
 }
 
-function bagEntries(value: unknown): readonly [string, unknown][] | undefined {
+function* indexedBagEntries(value: ArrayLike<unknown>): Generator<[string, unknown]> {
+  for (let index = 0; index < value.length; index++) yield [String(index), value[index]];
+}
+
+function* mapBagEntries(value: Map<unknown, unknown>): Generator<[string, unknown]> {
+  for (const [key, item] of value.entries()) yield [String(key), item];
+}
+
+function* setBagEntries(value: Set<unknown>): Generator<[string, unknown]> {
+  let index = 0;
+  for (const item of value) {
+    yield [String(index), item];
+    index += 1;
+  }
+}
+
+/**
+ * A bag's entries, LAZILY.
+ *
+ * Lazy because the caller is budgeted ({@link OWNER_SEARCH_BUDGET}) and must be
+ * able to stop: materializing the pairs first made a 20 000-element array cost
+ * 20 000 allocations before the first one was even looked at, which is a cost
+ * no budget above it can decline.
+ */
+function bagEntries(value: unknown): Iterable<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]);
+  // untrusted observations, so normalize with indexed reads of our own.
+  if (Array.isArray(value)) return indexedBagEntries(value as ArrayLike<unknown>);
+  if (value instanceof Map) return mapBagEntries(value);
+  if (value instanceof Set) return setBagEntries(value);
   if (Object.getPrototypeOf(value) !== Object.prototype) return undefined;
   return Object.entries(value as Record<string, unknown>);
 }
@@ -289,14 +390,23 @@ function findHeldOwner(
   held: object,
   view: Container,
   depth: number,
-  seen: WeakSet<object>,
+  search: OwnerSearch,
 ): string | undefined {
-  const direct = labelFromHolder(held, view, seen);
+  const direct = labelFromHolder(held, view, search);
   if (direct) return direct;
   if (depth <= 0) return undefined;
-  for (const value of Object.values(held as Record<string, unknown>)) {
+  // BY KEY, exactly like `labelFromHolder`'s own scan. Iterating `Object.values`
+  // here was the leak that made a hierarchy read quadratic: `parentRenderGroup`
+  // sits on EVERY container once a world has rendered, and descending into it
+  // reaches `childrenToUpdate[depth].list` — an array of every node in the
+  // tree — so the search for one node's owner walked the whole tree, for every
+  // unlabeled node. `isGameFieldKey` already knows which keys belong to Pixi
+  // rather than to the game; this scan simply has to ask it too.
+  for (const [key, value] of Object.entries(held as Record<string, unknown>)) {
+    if (!spend(search)) return undefined;
+    if (!isGameFieldKey(key)) continue;
     if (!value || typeof value !== 'object' || isPixiDisplay(value)) continue;
-    const found = findHeldOwner(value, view, depth - 1, seen);
+    const found = findHeldOwner(value, view, depth - 1, search);
     if (found) return found;
   }
   return undefined;

package/src/runtime/mount-manifest.ts

@@ -412,7 +412,7 @@ export async function mountManifestRoots(opts: MountManifestOptions): Promise<Ga
     headless: opts.headless,
     // `rendering.antialias` reaches the WebGL context at CONSTRUCTION and can be honoured
     // nowhere else — see the manifest schema's own `rendering` block and
-    // `world3d-react/renderer-config.ts`'s header for why it is not a world-level declaration.
+    // `adapter/renderer-config.ts`'s header for why it is not a world-level declaration.
     ...(manifest.rendering === undefined ? {} : { antialias: manifest.rendering.antialias }),
     seed: resolvedSeed,
     playtest: opts.playtest,

package/src/world3d-react/index.ts

@@ -40,15 +40,15 @@
  * contract to `react`/`@react-three/fiber`/`three` alone.
  */
 
-export { EngineBridge, type EngineBridgeValue, useGameContext } from './engine-bridge';
-export { type CreateR3FAdapterOptions, createR3FAdapter } from './r3f-adapter';
-export { r3fRootFactory, resolveR3FEntryAdapter } from './r3f-root-factory';
 export {
   applyWorldRendererConfig,
   type WorldOutputColorSpace,
   type WorldRendererConfig,
   type WorldToneMapping,
-} from './renderer-config';
+} from '../adapter/renderer-config';
+export { EngineBridge, type EngineBridgeValue, useGameContext } from './engine-bridge';
+export { type CreateR3FAdapterOptions, createR3FAdapter } from './r3f-adapter';
+export { r3fRootFactory, resolveR3FEntryAdapter } from './r3f-root-factory';
 export {
   createR3FRootContext,
   DEFAULT_INPUT_MAP_PATH,

package/src/world3d-react/r3f-adapter.tsx

@@ -30,6 +30,7 @@ import {
 } from '@react-three/fiber';
 import { createElement, Fragment, type ReactNode, useEffect, useMemo } from 'react';
 import type { MountedThreeRoot, RootAdapter, ThreeHostContext } from '../adapter';
+import { applyWorldRendererConfig, type WorldRendererConfig } from '../adapter/renderer-config';
 import type { SystemAdapters } from '../adapter/system-adapter';
 import { type RenderVitalsRegistration, registerRenderVitals } from '../dev/register-render-vitals';
 import {
@@ -45,7 +46,6 @@ import { createSoftParticleDepthPass } from '../render/soft-particle-depth';
 import { getDebugRegistry } from '../runtime/debug-registry';
 import { devBuildEnabled } from '../runtime/dev-build';
 import { EngineBridge, type EngineBridgeValue } from './engine-bridge';
-import { applyWorldRendererConfig, type WorldRendererConfig } from './renderer-config';
 import { createR3FRootContext, DEFAULT_INPUT_MAP_PATH, wireGameInputSeams } from './world-context';
 
 /** The slice of `WebGLRenderer.info` the vitals reporter reads. Declared
@@ -117,7 +117,7 @@ export interface CreateR3FAdapterOptions {
   /** The colour pipeline this world was AUTHORED for, applied to the host's renderer for the life
    *  of the mount and restored on dispose. Omit it (every world here does) to keep the host's own
    *  defaults; declare it when the world's colours were picked against a different engine's
-   *  pipeline — see `./renderer-config.ts`. */
+   *  pipeline — see `../adapter/renderer-config.ts`. */
   readonly renderer?: WorldRendererConfig | undefined;
 }
 

package/src/world3d-react/renderer-config.ts

@@ -1,168 +1,11 @@
 /**
- * world3d-react/renderer-config.ts — the seam a WORLD uses to state how its own frame is rendered.
+ * `@engine/world3d-react/renderer-config` — a published entry point.
  *
- * The host owns the `WebGLRenderer` (`ThreeHostContext.renderer`) and configures it with this
- * engine's defaults: ACES tone mapping, sRGB output, PCF-soft shadows. Those defaults are right for
- * a world authored against them and WRONG for a world that was authored against a different
- * engine's pipeline — an imported Godot 3 GLES2 game does gamma-space lighting with no tonemapper
- * at all, so ACES quietly desaturates and darkens every colour its author picked.
- *
- * So a world may DECLARE the pipeline it was authored for, and `createR3FAdapter` applies it to the
- * host's renderer for the life of the mount, restoring what it found on dispose. Three properties
- * of that shape are load-bearing:
- *
- *  - **It is per-renderer, never engine-wide.** Every field here is a `WebGLRenderer` instance
- *    property, and a play root gets its own renderer (`create-runtime.ts`). Nothing here reaches a
- *    module-level three global, so one world's declaration cannot change how the editor's own
- *    viewport, another root, or a thumbnail bake renders.
- *  - **Absent means "leave the host's value alone".** Every field is optional and an omitted one
- *    is never written, so declaring a tone mapping does not silently reset the clear colour.
- *  - **It is restored on dispose.** The renderer outlives the mount, so a world that did not put
- *    back what it found would leak its pipeline into whatever mounts next.
- *
- * This is deliberately NOT a general render-settings system. It carries what a world can honestly
- * state about its own colour pipeline and nothing else; a property the host fixes at CONSTRUCTION
- * (the WebGL context's `antialias` attribute, and therefore the MSAA sample count) cannot be
- * declared here, because there would be no honest moment to apply it.
- */
-
-import type * as THREE from 'three';
-
-/** The tone-mapping operators three exposes, named as data rather than as three's numeric enum. */
-export type WorldToneMapping =
-  | 'none'
-  | 'linear'
-  | 'reinhard'
-  | 'cineon'
-  | 'aces'
-  | 'agx'
-  | 'neutral';
-
-/**
- * The output transfer function the frame is written with.
- *
- *  - `srgb` — three's own default and this engine's: linear lighting, sRGB encode on output.
- *  - `srgb-linear` — NO output transform. This is what a gamma-space renderer needs: the shading
- *    result is already in display space and encoding it a second time washes the frame out.
- */
-export type WorldOutputColorSpace = 'srgb' | 'srgb-linear';
-
-/**
- * The shadow-map filter, named as data rather than as three's numeric enum.
- *
- * This is a renderer INSTANCE property (`WebGLRenderer.shadowMap.type`), not a context attribute,
- * so unlike MSAA it has an honest moment at which a world can ask for it — which is the whole test
- * this file's header states. A source engine that declares its own shadow filter (Godot 3's
- * `rendering/quality/shadows/filter_mode`) would otherwise inherit whatever the host built with.
- */
-export type WorldShadowMapType = 'basic' | 'pcf' | 'pcf-soft' | 'vsm';
-
-/** What a world may declare about the renderer that draws it. Every field is optional; see header. */
-export interface WorldRendererConfig {
-  readonly toneMapping?: WorldToneMapping | undefined;
-  readonly toneMappingExposure?: number | undefined;
-  readonly outputColorSpace?: WorldOutputColorSpace | undefined;
-  /**
-   * `WebGLRenderer.shadowMap.type`. Writing it after a shadow map has already been built needs
-   * `shadowMap.needsUpdate`, which this function sets — three caches the compiled depth material
-   * per type and would otherwise keep filtering with the previous one.
-   */
-  readonly shadowMapType?: WorldShadowMapType | undefined;
-  /**
-   * The colour the frame is cleared to, as a CSS hex string. The renderer's existing clear ALPHA
-   * is preserved: a stacked canvas is transparent on purpose (`create-runtime.ts` gives every
-   * non-bottom root `alpha: true`), and forcing it opaque here would hide every layer below.
-   */
-  readonly clearColor?: string | undefined;
-}
-
-/**
- * Apply `config` to `renderer`, returning the restore function that puts back what was there.
- *
- * `three` is passed in rather than imported for values so the enum constants come from the HOST's
- * three instance — the same identity rule `r3f-adapter.tsx` follows for the scene and camera.
+ * The engine package's export map is the wildcard `"./*"`, so every file under
+ * `packages/engine/src/` is an entry point a game outside this repo can import by path. The module
+ * itself now lives in the adapter seam (`@engine/adapter/renderer-config`, which its header
+ * explains), and this file keeps the path that shipped resolving to it. Import the seam path in
+ * new code.
  */
-export function applyWorldRendererConfig(
-  three: typeof THREE,
-  renderer: THREE.WebGLRenderer,
-  config: WorldRendererConfig,
-): () => void {
-  // A host that mounts a world WITHOUT rasterizing it hands the adapter a duck-typed renderer —
-  // the editor's design session (`createDesignTimeRenderer`: four members, deliberately never
-  // widened) and jsdom test harnesses both do. Such a surface has no colour pipeline to configure:
-  // the frame the user sees is drawn by a DIFFERENT renderer (the editor's own), so applying the
-  // world's config there is meaningless — and calling `getClearColor` on it is a TypeError that
-  // unmounts the whole world at edit time (measured: every Godot port's edit viewport blanked with
-  // '"world" failed to mount — renderer.getClearColor is not a function'). Detect the real
-  // `WebGLRenderer` surface by the one method this function must call, and no-op otherwise.
-  if (typeof renderer.getClearColor !== 'function') {
-    return () => {};
-  }
-  const toneMappings: Record<WorldToneMapping, THREE.ToneMapping> = {
-    none: three.NoToneMapping,
-    linear: three.LinearToneMapping,
-    reinhard: three.ReinhardToneMapping,
-    cineon: three.CineonToneMapping,
-    aces: three.ACESFilmicToneMapping,
-    agx: three.AgXToneMapping,
-    neutral: three.NeutralToneMapping,
-  };
-  const colorSpaces: Record<WorldOutputColorSpace, THREE.ColorSpace> = {
-    srgb: three.SRGBColorSpace,
-    'srgb-linear': three.LinearSRGBColorSpace,
-  };
-  const shadowMapTypes: Record<WorldShadowMapType, THREE.ShadowMapType> = {
-    basic: three.BasicShadowMap,
-    pcf: three.PCFShadowMap,
-    'pcf-soft': three.PCFSoftShadowMap,
-    vsm: three.VSMShadowMap,
-  };
-
-  const restores: (() => void)[] = [];
-
-  if (config.toneMapping !== undefined) {
-    const previous = renderer.toneMapping;
-    renderer.toneMapping = toneMappings[config.toneMapping];
-    restores.push(() => {
-      renderer.toneMapping = previous;
-    });
-  }
-  if (config.toneMappingExposure !== undefined) {
-    const previous = renderer.toneMappingExposure;
-    renderer.toneMappingExposure = config.toneMappingExposure;
-    restores.push(() => {
-      renderer.toneMappingExposure = previous;
-    });
-  }
-  if (config.outputColorSpace !== undefined) {
-    const previous = renderer.outputColorSpace;
-    renderer.outputColorSpace = colorSpaces[config.outputColorSpace];
-    restores.push(() => {
-      renderer.outputColorSpace = previous;
-    });
-  }
-  if (config.shadowMapType !== undefined && renderer.shadowMap !== undefined) {
-    const previous = renderer.shadowMap.type;
-    renderer.shadowMap.type = shadowMapTypes[config.shadowMapType];
-    renderer.shadowMap.needsUpdate = true;
-    restores.push(() => {
-      renderer.shadowMap.type = previous;
-      renderer.shadowMap.needsUpdate = true;
-    });
-  }
-  if (config.clearColor !== undefined) {
-    const previousColor = new three.Color();
-    renderer.getClearColor(previousColor);
-    // Alpha is READ BACK and re-passed, never assumed: see `clearColor`'s doc above.
-    const alpha = renderer.getClearAlpha();
-    renderer.setClearColor(new three.Color(config.clearColor), alpha);
-    restores.push(() => {
-      renderer.setClearColor(previousColor, alpha);
-    });
-  }
 
-  return () => {
-    // Reverse order, so a field written twice (it cannot be, today) unwinds correctly.
-    for (let i = restores.length - 1; i >= 0; i--) restores[i]?.();
-  };
-}
+export * from '../adapter/renderer-config';