@vgai/engine 0.5.16 → 0.5.18

package/package.json

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

package/schemas/engine-capabilities.json

@@ -15,7 +15,7 @@
       ],
       "notes": "Grepped packages/engine/src for ccd/CCD/setCcdEnabled: zero matches. The engine constructs no rigid bodies itself — games build their own descs via ctx.RAPIER — and nothing engine-side ever enables ccd. Workaround: keep dynamic-body per-step travel small relative to the thinnest collider, or add intermediate colliders; a game may also call setCcdEnabled on its own bodies directly.",
       "evidenceHashes": {
-        "packages/engine/src/adapter/setup-three-root-adapter.ts": "98fb35199a246d99fe752ea467d48a30c71da7f4d4e6f06efa372b0c6abb5456"
+        "packages/engine/src/adapter/setup-three-root-adapter.ts": "14cef0975f38ecceb25b607ef62232c1002bdd172a3456571f50aa9e39263c0c"
       }
     },
     {
@@ -43,7 +43,7 @@
       "notes": "gamepad disconnect/reconnect needs no special-cased code: poll() re-reads navigator.getGamepads() and every read skips a null slot, so a disconnected gamepad's actions go neutral with a correct isJustReleased edge for free — see input-device-backends-f2.test.ts.",
       "evidenceHashes": {
         "packages/engine/src/input/input-types.ts": "62d9005609a72b55a8214c869d1b27825b1a17b9389f3f3f5d0b04725331b382",
-        "packages/engine/src/input/input-manager.ts": "41b1255eb18c74c022b3cc87f6e050d3fb7ee6883215e3888337ff0d94defa63"
+        "packages/engine/src/input/input-manager.ts": "7d34683759d7ab7fd20ca6f5b5e646eb76a31b00c77977816f4ef863ccb06e62"
       }
     },
     {
@@ -73,7 +73,7 @@
       "notes": "Limits: ARCHITECTURE-CORE.md. Any editor capability a mount does not reach stands warned per capability until it works.",
       "evidenceHashes": {
         "vendor/games/verify-unaltered.mjs": "257a362030a10f4d72a3280815069fbd83f436e1619391635b6f8df2ddd6c339",
-        "packages/engine/src/manifest/schema.ts": "65500eb1594bd2333418bf073858131d449f0a17e0b584fc4dedc15bf01970bf"
+        "packages/engine/src/manifest/schema.ts": "ce385bc9181b82f9d5044da6a41a025a5cb8ba1fc7156263665080c9fdf2b11c"
       }
     },
     {

package/schemas/vgai-project.schema.json

@@ -193,11 +193,6 @@
             "description": "Whether play-mode pause/step applies to this root",
             "type": "boolean"
           },
-          "dev": {
-            "default": false,
-            "description": "Marks this root as a DEV LAYER: the game's own dev GUI, not shipped game content. Four readers act on it. `mountManifestRoots` mounts it only when dev layers are enabled (`devLayersEnabled`, runtime/dev-layers.ts), so a production build carries no dev GUI; the host stacks every dev root ABOVE every non-dev root (a dev layer sits topmost, and as a DOM layer it steals no input from the game while closed); the play compositor EXCLUDES dev layers from a capture unless the capture asks for them; and the editor mounts a dev root as edit-time CHROME rather than authorable content (no hierarchy entry, no OID stamping, no JSX write-back, not selectable).",
-            "type": "boolean"
-          },
           "loop": {
             "default": "gated",
             "description": "gated: host-driven loop (default). self-driven: this root drives its own loop (composited, unsynchronized)",
@@ -214,7 +209,7 @@
         ],
         "additionalProperties": false
       },
-      "description": "The Game's explicit, non-empty adapter-root composition. There is no implicit root. Root ids are unique, and a project declares at most ONE world root per medium — one `three`, one `dom`, one canvas-surface root (first-party canvas, canvas ingest and canvas module are the same medium). A `dev: true` root is counted in its own band: a dev layer is chrome stacked above the game, not content competing for the medium, so a game may declare a `dom` HUD and a `dom` dev layer — but not two of either."
+      "description": "The Game's explicit, non-empty adapter-root composition. There is no implicit root. Root ids are unique, and a project declares at most ONE world root per medium — one `three`, one `dom`, one canvas-surface root (first-party canvas, canvas ingest and canvas module are the same medium)."
     },
     "authoring": {
       "description": "Editor-only authoring metadata; never runtime ownership",
@@ -336,7 +331,7 @@
       "properties": {
         "antialias": {
           "type": "boolean",
-          "description": "Whether every three root is built with a multisampled drawing buffer. This is the ONE render property a world cannot declare for itself (world3d-react/renderer-config.ts): a WebGL context fixes its sample count at CREATION from this boolean, long before a world mounts, so it belongs to the PROJECT. The runtime reader is mount-manifest.ts, which threads it into createHostRenderer for each three root. WebGL exposes no sample COUNT — the implementation picks one (4x on every desktop browser measured), so a source engine that authored 8x/16x gets multisampling but not its exact count."
+          "description": "Whether every three root is built with a multisampled drawing buffer. This is the ONE render property a world cannot declare for itself (adapter/renderer-config.ts): a WebGL context fixes its sample count at CREATION from this boolean, long before a world mounts, so it belongs to the PROJECT. The runtime reader is mount-manifest.ts, which threads it into createHostRenderer for each three root. WebGL exposes no sample COUNT — the implementation picks one (4x on every desktop browser measured), so a source engine that authored 8x/16x gets multisampling but not its exact count."
         }
       },
       "required": [

package/src/adapter/adapter-module.ts

@@ -100,18 +100,6 @@ export interface AdapterRegion {
   readonly id: string;
   /** What the host hands this root. */
   readonly surface: AdapterSurface;
-  /**
-   * `true` = this region grades the game's own DEV LAYER (the manifest root's
-   * `dev: true`), not shipped game content.
-   *
-   * Carried here because a dev root occupies the same MEDIUM as the content
-   * root beside it — a dev GUI is a `dom` root next to the HUD's `dom` root —
-   * and anything that maps a subject to "the region on this surface" would
-   * otherwise be choosing between them by array order. A region consumer that
-   * means shipped content says so by skipping `dev` regions (the loader's
-   * `regionForSurface` does), rather than by guessing which one matched.
-   */
-  readonly dev: boolean;
   /** Projection library, by name. */
   readonly projector: ProjectorName;
   /**
@@ -235,12 +223,6 @@ const AdapterRegionSchema = z
   .object({
     id: z.string().min(1).describe('Manifest root id this region grades'),
     surface: z.enum(['three', 'canvas', 'dom']).describe('Render surface the host hands this root'),
-    dev: z
-      .boolean()
-      .describe(
-        "true = this region grades the game's own dev layer, not shipped content (the " +
-          "manifest root's `dev: true`)",
-      ),
     projector: z.enum(PROJECTOR_NAMES).describe('Projection library serving this surface, by name'),
     dialect: z
       .string()
@@ -431,7 +413,6 @@ export function unmatchedRegionIncludeIds(
 /** One root's region, before any declared parameters are merged onto it. */
 function derivedRegion(root: ResolvedAdapterRoot): AdapterRegion {
   const surface = root.surface;
-  const dev = root.dev;
   const firstParty = root.adapter.type === 'builtin';
   const projector: ProjectorName = surface === 'canvas' ? 'pixi' : surface;
   const basis = NATIVE_REGION_BASIS;
@@ -439,7 +420,6 @@ function derivedRegion(root: ResolvedAdapterRoot): AdapterRegion {
     return {
       id: root.id,
       surface,
-      dev,
       projector,
       dialect: null,
       anchors: ['live-only'] as const,
@@ -450,7 +430,6 @@ function derivedRegion(root: ResolvedAdapterRoot): AdapterRegion {
     return {
       id: root.id,
       surface,
-      dev,
       projector,
       dialect: 'jsx',
       anchors: ['source-prop', 'source-structure'] as const,
@@ -460,7 +439,6 @@ function derivedRegion(root: ResolvedAdapterRoot): AdapterRegion {
   return {
     id: root.id,
     surface,
-    dev,
     projector,
     dialect: surface === 'three' ? 'r3f' : 'pixi-react',
     anchors: ['source-prop', 'source-structure', 'construction-literal'] as const,
@@ -474,9 +452,7 @@ function derivedRegion(root: ResolvedAdapterRoot): AdapterRegion {
 
 /**
  * The rule form of a finder's region targeting: every region the host mounts
- * from an exported composition (a root with an `entry`) that is not a declared
- * DEV layer. A dev root is the game's own dev GUI — the manifest already says
- * so (`dev: true`), so skipping it reads a declaration rather than guessing.
+ * from an exported composition — a root with an `entry`.
  */
 export const EXPORTED_COMPOSITION_REGIONS = 'exported-composition-regions';
 

package/src/adapter/finders/scenes-from-entrypoint-selection.ts

@@ -53,8 +53,6 @@ export interface EntrypointSource {
   readonly path: string;
   /** The module's bytes; `null` when they could not be read. */
   readonly source: string | null;
-  /** The root's declared `dev` flag — a dev layer is the game's own dev GUI. */
-  readonly dev: boolean;
 }
 
 export interface ScenesFromEntrypointSelectionInput {
@@ -284,11 +282,8 @@ function sourceFor(
 /**
  * Which entrypoints this selection targets.
  *
- * The RULE form is every exported-composition region that is not a declared
- * DEV layer. Reading `dev` is reading the manifest's own declaration — the dev
- * GUI is edit-time chrome, not authorable game content — never a name
- * heuristic. A named region with no matching entrypoint becomes a note, not a
- * silent omission.
+ * The RULE form is every exported-composition region. A named region with no
+ * matching entrypoint becomes a note, not a silent omission.
  */
 function targetedEntrypoints(
   params: ScenesFromEntrypointSelectionParams,
@@ -296,7 +291,7 @@ function targetedEntrypoints(
   notes: string[],
 ): EntrypointSource[] {
   if (params.regions === EXPORTED_COMPOSITION_REGIONS) {
-    return entrypoints.filter((entrypoint) => !entrypoint.dev);
+    return [...entrypoints];
   }
   const found: EntrypointSource[] = [];
   for (const regionId of params.regions) {

package/src/adapter/renderer-config.ts

@@ -0,0 +1,178 @@
+/**
+ * adapter/renderer-config.ts — the seam a WORLD uses to state how its own frame is rendered.
+ *
+ * It lives in the ADAPTER SEAM, not in a surface entry, because `WorldRendererConfig` IS part of
+ * the root contract: `MountedThreeRoot.rendererConfig` reports it (`./root-adapter.ts`) and
+ * `./root-seam-contract.ts` already lists it as a contract field. The seam defines the shape; the
+ * surface entries and the editor CONFORM to it — `world3d-react/r3f-adapter.tsx` is the declarer,
+ * `runtime/create-runtime.ts` the host, `editor/src/components/ViewportPanel.tsx` the editor's
+ * applier. Do NOT move it back under `world3d-react/`: nothing here touches react, and a core
+ * adapter file reaching into a react entry is exactly what `react-core-import-ban.test.ts` forbids
+ * (that ban carries no type-only carve-out on purpose — unlike its pixi sibling, whose carve-out
+ * exists only because `PIXI.Container` is a third-party type core cannot relocate).
+ *
+ * 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.
+ */
+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]?.();
+  };
+}

package/src/adapter/root-adapter.ts

@@ -9,10 +9,10 @@
 
 import type { Container } from 'pixi.js';
 import type * as THREE from 'three';
-import type { WorldRendererConfig } from '../world3d-react/renderer-config';
 import type { AdapterSurface } from './adapter-surface';
 import type { AuthoringAdapter } from './authoring';
 import type { HostContextFor } from './host-context';
+import type { WorldRendererConfig } from './renderer-config';
 import type { SystemAdapters } from './system-adapter';
 
 /**
@@ -72,6 +72,10 @@ export interface MountedRootBase {
 
   resize?(width: number, height: number): void;
   dispose(): void;
+  /** Resolves after an asynchronous native reconciler has run every component
+   * cleanup started by {@link dispose}. Omitted by synchronously-disposing
+   * roots. Hosts use this before auditing/reclaiming realm-owned resources. */
+  readonly disposeComplete?: Promise<void>;
 
   /** Optional capability providers — absence = "not supported", host degrades. */
   readonly authoring?: AuthoringAdapter;
@@ -94,7 +98,7 @@ export interface MountedThreeRoot extends MountedRootBase {
   /**
    * The colour pipeline this world was authored for, REPORTED rather than
    * applied — the adapter has already applied it to the renderer its own host
-   * handed it (`world3d-react/renderer-config.ts`).
+   * handed it (`./renderer-config.ts`).
    *
    * It is here because the host that MOUNTS a world is not always the host
    * that DRAWS it. The editor's design session mounts against a

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

@@ -24,6 +24,7 @@ export const MOUNTED_ROOT_BASE_SHAPE = defineSeamShape<MountedRootBase>()({
   step: { optional: true, kind: 'function', required: 'effect' },
   resize: { optional: true, kind: 'function', required: 'effect' },
   dispose: { optional: false, kind: 'function', required: 'effect' },
+  disposeComplete: { optional: true, kind: 'value', required: 'effect' },
   authoring: { optional: true, kind: 'value', required: 'operation' },
   systems: { optional: true, kind: 'value', required: 'operation' },
   observe: { optional: true, kind: 'value', required: 'effect' },

package/src/adapter/setup-three-root-adapter.ts

@@ -64,7 +64,7 @@ import {
   type DebugRegistry,
   getDebugRegistry,
 } from '../runtime/debug-registry';
-import { devLayersEnabled } from '../runtime/dev-layers';
+import { devBuildEnabled } from '../runtime/dev-build';
 import { disposeDebrisSubtree, type RootFrameHooks } from '../runtime/game';
 import type { EditorPreview, GameCleanup, GameContext, GameSetupFn } from '../runtime/types';
 import { type AudioContext as GameAudio, setupAudio } from '../setup/setup-audio';
@@ -591,8 +591,8 @@ export class SetupThreeRootAdapter implements RootAdapter {
     // registry, with no capability to install and nothing for a game to write.
     //
     // THE GATE, in one place. Three conditions, and the reason for each:
-    //  1. `devLayersEnabled()` — the ONE owner of "is this a dev/editor
-    //     context" (`runtime/dev-layers.ts`). A ship build registers nothing,
+    //  1. `devBuildEnabled()` — the ONE owner of "is this a dev/editor
+    //     context" (`runtime/dev-build.ts`). A ship build registers nothing,
     //     subscribes to nothing, and never enables the profiler.
     //  2. a `Game` shell exists — the readings are folded out of that game's
     //     profiler frames, and a bare mount has no profiler to fold.
@@ -620,12 +620,12 @@ export class SetupThreeRootAdapter implements RootAdapter {
       // The packaged runtime bakes `import.meta.env.DEV = false` into its
       // prebuilt bundle, which is a fact about how the EDITOR was built, not
       // about whether this mount is a dev session — found live: a
-      // package-native project's vitals never seeded while its dev menu,
-      // capabilities, and every project-graph dev layer ran fine. The
-      // override argument is dev-layers' own documented seam for exactly
-      // this caller-knows-better case; a standalone/ship mount (no
-      // editorPreview) still resolves purely from the build env.
-      if (!host.game || headless || !devLayersEnabled(editorPreview ? true : undefined)) return;
+      // package-native project's vitals never seeded while its capabilities
+      // and every other project-graph module ran fine. The override argument
+      // is `devBuildEnabled`'s own documented seam for exactly this
+      // caller-knows-better case; a standalone/ship mount (no editorPreview)
+      // still resolves purely from the build env.
+      if (!host.game || headless || !devBuildEnabled(editorPreview ? true : undefined)) return;
       renderVitals?.dispose();
       host.game.profiler.enabled = true;
       renderVitals = registerRenderVitals({