@vgai/engine 0.5.5 → 0.5.7

package/dist/runtime/unexported-game-trap.js

@@ -0,0 +1,80 @@
+/**
+ * THE UNEXPORTED-GAME TRAP: a dev-served standalone game page REFUSES to boot.
+ *
+ * Owner decision (2026-08-09): until a game is EXPORTED, it is never played
+ * outside the editor. The editor is the one authoring, viewing and
+ * verification surface; the standalone page exists to serve the exported
+ * artifact, not to be a second door during development.
+ *
+ * Why this is a trap in CODE and not a rule in prose: the rule already
+ * existed, and it drifted. When an editor session broke mid-task, an agent
+ * "temporarily" switched to `npm run game`, the fallback fed its whole
+ * feedback loop (pixels for screenshots), nothing broken ever pushed it back,
+ * and hours of verification ran outside the editor without anyone deciding
+ * that. A workaround whose cost lands outside the loop that chose it is
+ * sticky; the only fix that holds is for the workaround PATH ITSELF to fail
+ * immediately, loudly, and with the way back in its hands. That is this file.
+ *
+ * The boundary is DEV-SERVED vs EXPORTED, decided by the bundler: a Vite dev
+ * server strips nothing, so `import.meta.env.DEV` is true; a production build
+ * (`vite build` — what `vgai deploy` runs) compiles it false and this module
+ * costs an exported game nothing. Headless contexts (unit tests, playtest's
+ * node leg) have no real browser page and never trip it — the check requires
+ * a document whose `defaultView` is the window, which no test stub wires up.
+ *
+ * There is deliberately NO opt-out flag, env var, or query param. An escape
+ * hatch an agent can reach for is the workaround again, one hop later.
+ */
+/** What the refusal says — one place, so the page and the thrown Error agree. */
+const REFUSAL = [
+    'UNEXPORTED GAME, OUTSIDE THE EDITOR — refusing to mount.',
+    '',
+    'This game has not been exported. Until it is, the ONLY way to run, see,',
+    'or drive it is the editor:',
+    '',
+    '    vgai edit .        open (or reuse) the editor for this project',
+    '    vgai play          enter play mode from the terminal',
+    "    vgai eval '<js>'   drive and read the running game",
+    '',
+    'The standalone page serves EXPORTED builds only (`vgai deploy`, or the',
+    'production build it runs). Do not script around this page — no headless',
+    'browsers, bots, or screenshots against the dev server. Every agent',
+    'workflow goes through the editor session.',
+].join('\n');
+/** True only on a real, dev-served browser page — the one context the trap is for. */
+function isDevServedBrowserPage() {
+    if (typeof window === 'undefined' || typeof document === 'undefined')
+        return false;
+    // Test stubs install a bare `document` object; only a real page has the
+    // document↔window linkage.
+    if (document.defaultView !== window)
+        return false;
+    return Boolean(import.meta.env?.DEV);
+}
+/**
+ * Throws (and paints a full-screen refusal, so a human at the tab sees it as
+ * immediately as a harness watching the console does) when an unexported game
+ * is being mounted on a dev-served page. Called by `mountGameFromManifest`
+ * before any root is resolved; exported builds and headless tests pass
+ * through untouched.
+ */
+export function assertExportedOrInEditor() {
+    if (!isDevServedBrowserPage())
+        return;
+    const screen = document.createElement('pre');
+    screen.textContent = REFUSAL;
+    screen.style.cssText = [
+        'position:fixed',
+        'inset:0',
+        'z-index:2147483647',
+        'margin:0',
+        'padding:48px',
+        'background:#1A0E0E',
+        'color:#FF9B8A',
+        'font:600 15px/1.7 ui-monospace,SFMono-Regular,Menlo,monospace',
+        'white-space:pre-wrap',
+    ].join(';');
+    document.body.appendChild(screen);
+    document.title = 'UNEXPORTED — use the editor';
+    throw new Error(`mountGameFromManifest: ${REFUSAL}`);
+}

package/dist/setup/setup-audio.d.ts

@@ -0,0 +1,20 @@
+import * as THREE from 'three';
+export interface AudioContext {
+    listener: THREE.AudioListener;
+    masterGain: GainNode;
+    buses: {
+        music: GainNode;
+        sfx: GainNode;
+        voice: GainNode;
+    };
+    /** Call this on first user interaction (click/key) to resume audio context */
+    resume: () => void;
+}
+/**
+ * Creates the audio listener and bus hierarchy.
+ *
+ * Bus routing: music/sfx/voice → master → destination
+ * Attach `listener` to the active camera: `camera.add(audioCtx.listener)`.
+ */
+export declare function setupAudio(camera: THREE.Camera): AudioContext;
+//# sourceMappingURL=setup-audio.d.ts.map

package/dist/setup/setup-audio.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"setup-audio.d.ts","sourceRoot":"","sources":["../../src/setup/setup-audio.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,KAAK,MAAM,OAAO,CAAC;AAE/B,MAAM,WAAW,YAAY;IAC3B,QAAQ,EAAE,KAAK,CAAC,aAAa,CAAC;IAC9B,UAAU,EAAE,QAAQ,CAAC;IACrB,KAAK,EAAE;QACL,KAAK,EAAE,QAAQ,CAAC;QAChB,GAAG,EAAE,QAAQ,CAAC;QACd,KAAK,EAAE,QAAQ,CAAC;KACjB,CAAC;IACF,8EAA8E;IAC9E,MAAM,EAAE,MAAM,IAAI,CAAC;CACpB;AAED;;;;;GAKG;AACH,wBAAgB,UAAU,CAAC,MAAM,EAAE,KAAK,CAAC,MAAM,GAAG,YAAY,CAuC7D"}

package/dist/setup/setup-audio.js

@@ -0,0 +1,41 @@
+import * as THREE from 'three';
+/**
+ * Creates the audio listener and bus hierarchy.
+ *
+ * Bus routing: music/sfx/voice → master → destination
+ * Attach `listener` to the active camera: `camera.add(audioCtx.listener)`.
+ */
+export function setupAudio(camera) {
+    const listener = new THREE.AudioListener();
+    camera.add(listener);
+    const ctx = listener.context;
+    const masterGain = ctx.createGain();
+    masterGain.connect(ctx.destination);
+    // Route the Three.js listener through masterGain so that THREE.Audio /
+    // THREE.PositionalAudio objects are also silenced by the mute button.
+    listener.gain.disconnect();
+    listener.gain.connect(masterGain);
+    const musicGain = ctx.createGain();
+    musicGain.gain.value = 0.7;
+    musicGain.connect(masterGain);
+    const sfxGain = ctx.createGain();
+    sfxGain.gain.value = 1.0;
+    sfxGain.connect(masterGain);
+    const voiceGain = ctx.createGain();
+    voiceGain.gain.value = 1.0;
+    voiceGain.connect(masterGain);
+    return {
+        listener,
+        masterGain,
+        buses: {
+            music: musicGain,
+            sfx: sfxGain,
+            voice: voiceGain,
+        },
+        resume() {
+            if (ctx.state === 'suspended') {
+                ctx.resume();
+            }
+        },
+    };
+}

package/dist/setup/setup-particles.d.ts

@@ -0,0 +1,17 @@
+import type * as THREE from 'three';
+import { BatchedRenderer } from 'three.quarks';
+export interface ParticlesContext {
+    batchedRenderer: BatchedRenderer;
+}
+/**
+ * Creates the three.quarks BatchedRenderer for GPU particle systems.
+ *
+ * three.quarks renders all particle systems in a single draw call via instancing.
+ * Add particle systems to the batchedRenderer, not directly to the scene.
+ *
+ * Usage:
+ *   const particles = setupParticles(scene);
+ *   // In render loop: particles.batchedRenderer.update(dt);
+ */
+export declare function setupParticles(scene: THREE.Scene): ParticlesContext;
+//# sourceMappingURL=setup-particles.d.ts.map

package/dist/setup/setup-particles.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"setup-particles.d.ts","sourceRoot":"","sources":["../../src/setup/setup-particles.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,KAAK,KAAK,MAAM,OAAO,CAAC;AACpC,OAAO,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AAE/C,MAAM,WAAW,gBAAgB;IAC/B,eAAe,EAAE,eAAe,CAAC;CAClC;AAED;;;;;;;;;GASG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,KAAK,CAAC,KAAK,GAAG,gBAAgB,CAKnE"}

package/dist/setup/setup-particles.js

@@ -0,0 +1,16 @@
+import { BatchedRenderer } from 'three.quarks';
+/**
+ * Creates the three.quarks BatchedRenderer for GPU particle systems.
+ *
+ * three.quarks renders all particle systems in a single draw call via instancing.
+ * Add particle systems to the batchedRenderer, not directly to the scene.
+ *
+ * Usage:
+ *   const particles = setupParticles(scene);
+ *   // In render loop: particles.batchedRenderer.update(dt);
+ */
+export function setupParticles(scene) {
+    const batchedRenderer = new BatchedRenderer();
+    scene.add(batchedRenderer);
+    return { batchedRenderer };
+}

package/dist/setup/setup-physics.d.ts

@@ -0,0 +1,25 @@
+import type RAPIER from '@dimforge/rapier3d-compat';
+import * as THREE from 'three';
+export interface PhysicsContext {
+    rapierWorld: RAPIER.World;
+    eventQueue: RAPIER.EventQueue;
+    debugMesh: THREE.LineSegments;
+    debugEnabled: boolean;
+}
+/**
+ * Creates the Rapier physics world and debug visualization.
+ *
+ * Call RAPIER.init() before this function.
+ * This is direct Rapier setup — no abstraction. Edit freely.
+ */
+export declare function setupPhysics(rapier: typeof RAPIER, scene: THREE.Scene, gravity?: {
+    x: number;
+    y: number;
+    z: number;
+}): PhysicsContext;
+/**
+ * Update the debug line visualization from Rapier's debug render data.
+ * Call this each frame if debug is enabled.
+ */
+export declare function updatePhysicsDebug(rapierWorld: RAPIER.World, debugMesh: THREE.LineSegments): void;
+//# sourceMappingURL=setup-physics.d.ts.map

package/dist/setup/setup-physics.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"setup-physics.d.ts","sourceRoot":"","sources":["../../src/setup/setup-physics.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,MAAM,MAAM,2BAA2B,CAAC;AACpD,OAAO,KAAK,KAAK,MAAM,OAAO,CAAC;AAE/B,MAAM,WAAW,cAAc;IAC7B,WAAW,EAAE,MAAM,CAAC,KAAK,CAAC;IAC1B,UAAU,EAAE,MAAM,CAAC,UAAU,CAAC;IAC9B,SAAS,EAAE,KAAK,CAAC,YAAY,CAAC;IAC9B,YAAY,EAAE,OAAO,CAAC;CACvB;AAED;;;;;GAKG;AACH,wBAAgB,YAAY,CAC1B,MAAM,EAAE,OAAO,MAAM,EACrB,KAAK,EAAE,KAAK,CAAC,KAAK,EAClB,OAAO,GAAE;IAAE,CAAC,EAAE,MAAM,CAAC;IAAC,CAAC,EAAE,MAAM,CAAC;IAAC,CAAC,EAAE,MAAM,CAAA;CAA6B,GACtE,cAAc,CAiBhB;AAED;;;GAGG;AACH,wBAAgB,kBAAkB,CAAC,WAAW,EAAE,MAAM,CAAC,KAAK,EAAE,SAAS,EAAE,KAAK,CAAC,YAAY,QAuB1F"}

package/dist/setup/setup-physics.js

@@ -0,0 +1,51 @@
+import * as THREE from 'three';
+/**
+ * Creates the Rapier physics world and debug visualization.
+ *
+ * Call RAPIER.init() before this function.
+ * This is direct Rapier setup — no abstraction. Edit freely.
+ */
+export function setupPhysics(rapier, scene, gravity = { x: 0, y: -9.81, z: 0 }) {
+    const rapierWorld = new rapier.World(gravity);
+    const eventQueue = new rapier.EventQueue(true);
+    // Debug visualization (toggled at runtime)
+    const debugGeometry = new THREE.BufferGeometry();
+    const debugMaterial = new THREE.LineBasicMaterial({ color: 0x00ff00, vertexColors: true });
+    const debugMesh = new THREE.LineSegments(debugGeometry, debugMaterial);
+    debugMesh.visible = false;
+    scene.add(debugMesh);
+    return {
+        rapierWorld,
+        eventQueue,
+        debugMesh,
+        debugEnabled: false,
+    };
+}
+/**
+ * Update the debug line visualization from Rapier's debug render data.
+ * Call this each frame if debug is enabled.
+ */
+export function updatePhysicsDebug(rapierWorld, debugMesh) {
+    const buffers = rapierWorld.debugRender();
+    const geom = debugMesh.geometry;
+    // Reuse the existing BufferAttributes whenever the vertex count is stable
+    // (the common case). Allocating a new Float32Array + BufferAttribute every
+    // frame orphaned a fresh GPU buffer each time. We only allocate when the
+    // size actually changes.
+    const posAttr = geom.getAttribute('position');
+    if (posAttr && posAttr.array.length === buffers.vertices.length) {
+        posAttr.array.set(buffers.vertices);
+        posAttr.needsUpdate = true;
+    }
+    else {
+        geom.setAttribute('position', new THREE.BufferAttribute(new Float32Array(buffers.vertices), 3));
+    }
+    const colAttr = geom.getAttribute('color');
+    if (colAttr && colAttr.array.length === buffers.colors.length) {
+        colAttr.array.set(buffers.colors);
+        colAttr.needsUpdate = true;
+    }
+    else {
+        geom.setAttribute('color', new THREE.BufferAttribute(new Float32Array(buffers.colors), 4));
+    }
+}

package/dist/setup/setup-renderer.d.ts

@@ -0,0 +1,82 @@
+import { EffectComposer } from 'postprocessing';
+import * as THREE from 'three';
+import type { RenderEnvironment } from '../asset-formats/render-env';
+import { type RenderScope } from '../render/render-settings';
+export interface RendererContext {
+    renderer: THREE.WebGLRenderer;
+    scene: THREE.Scene;
+    camera: THREE.PerspectiveCamera;
+    composer: EffectComposer;
+}
+/**
+ * Apply the live renderer-level render settings (shadows, resolution scale) from
+ * the resolved cascade. `antialias`/`backend` are reload-only (renderer re-init)
+ * and are handled at construction, not here. Pass the scene `rendering` scope
+ * (e.g. `env.rendering`); absent values fall back to the registry defaults so
+ * behavior is unchanged when a scene omits `rendering`.
+ *
+ * `basePixelRatio` is the call-site's native pixel-ratio policy (the runtime caps
+ * at 2; the editor uses the raw devicePixelRatio); `resolutionScale` multiplies it.
+ */
+export declare function applyRendererSettings(renderer: THREE.WebGLRenderer, rendering?: RenderScope, basePixelRatio?: number): void;
+/**
+ * Create ONLY the WebGL renderer. The HOST owns the renderer (see
+ * `ThreeHostContext.renderer`); the game/adapter owns the scene/camera/composer it
+ * renders into. Split out of `setupRenderer` for the adapter inversion.
+ *
+ * `rendering` is the scene-level render scope (`env.rendering`); it seeds the
+ * reload-only `antialias` option at construction and the live shadow/resolution
+ * settings (via {@link applyRendererSettings}). Absent → registry defaults.
+ *
+ * `opts` is additive (T6.1 slice 1, D5 §1/§4): omitted
+ * entirely, construction is byte-identical to before (no `alpha`/
+ * `preserveDrawingBuffer` keys at all) — the legacy single-canvas host never
+ * passes it. The roots path passes `alpha:true` for every stacked canvas
+ * above the bottom one (so its clear-alpha-0 shows the layer below through
+ * it) and `preserveDrawingBuffer:true` for every stacked canvas (the
+ * recorded capture-tier cost, paid once here rather than re-derived later).
+ */
+export declare function createHostRenderer(canvas: HTMLCanvasElement, width?: number, height?: number, rendering?: RenderScope, opts?: {
+    alpha?: boolean;
+    preserveDrawingBuffer?: boolean;
+}): THREE.WebGLRenderer;
+/**
+ * Create the scene, camera, and postprocessing composer that a first-party game
+ * renders into, given a host-provided renderer. The GPU-only `composer` is
+ * created here; a headless host (no GPU) skips this entirely.
+ */
+export declare function createSceneView(renderer: THREE.WebGLRenderer, width?: number, height?: number): {
+    scene: THREE.Scene;
+    camera: THREE.PerspectiveCamera;
+    composer: EffectComposer;
+};
+/**
+ * Creates the Three.js renderer, scene, camera, and postprocessing pipeline.
+ *
+ * This is direct Three.js setup — no abstraction. Edit freely. (Now a thin
+ * combination of {@link createHostRenderer} + {@link createSceneView}.)
+ */
+export declare function setupRenderer(canvas: HTMLCanvasElement, width?: number, height?: number): RendererContext;
+/**
+ * Rebuild composer passes from scene environment settings.
+ * Scenes without toneMapping default to ACES (the runtime default).
+ * Code can further modify the composer after this call.
+ *
+ * Pass objectMap to enable entity-referencing effects (godRays, outline).
+ * Pass entities to resolve tag-based references (outline).
+ */
+export declare function applyScenePostProcessing(composer: EffectComposer, renderer: THREE.WebGLRenderer, scene: THREE.Scene, camera: THREE.Camera, env?: RenderEnvironment, objectMap?: Map<string, THREE.Object3D>, entityTags?: Map<string, string[]>): void;
+/**
+ * Apply every authored scene-level renderer setting through one path.
+ *
+ * Tone mapping is part of the scene environment, not conditional on the
+ * presence of post-processing effects. Keeping renderer settings and the
+ * composer rebuild together prevents editor/runtime drift for scenes that
+ * only author exposure or a tone-mapping mode.
+ */
+export declare function applySceneRenderPipeline(composer: EffectComposer, renderer: THREE.WebGLRenderer, scene: THREE.Scene, camera: THREE.Camera, env?: RenderEnvironment, options?: {
+    basePixelRatio?: number;
+    objectMap?: Map<string, THREE.Object3D>;
+    entityTags?: Map<string, string[]>;
+}): void;
+//# sourceMappingURL=setup-renderer.d.ts.map

package/dist/setup/setup-renderer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"setup-renderer.d.ts","sourceRoot":"","sources":["../../src/setup/setup-renderer.ts"],"names":[],"mappings":"AAGA,OAAO,EAQL,cAAc,EAoBf,MAAM,gBAAgB,CAAC;AACxB,OAAO,KAAK,KAAK,MAAM,OAAO,CAAC;AAO/B,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,6BAA6B,CAAC;AAGrE,OAAO,EAAE,KAAK,WAAW,EAAyB,MAAM,2BAA2B,CAAC;AAEpF,MAAM,WAAW,eAAe;IAC9B,QAAQ,EAAE,KAAK,CAAC,aAAa,CAAC;IAC9B,KAAK,EAAE,KAAK,CAAC,KAAK,CAAC;IACnB,MAAM,EAAE,KAAK,CAAC,iBAAiB,CAAC;IAChC,QAAQ,EAAE,cAAc,CAAC;CAC1B;AAED;;;;;;;;;GASG;AACH,wBAAgB,qBAAqB,CACnC,QAAQ,EAAE,KAAK,CAAC,aAAa,EAC7B,SAAS,CAAC,EAAE,WAAW,EACvB,cAAc,SAAuC,GACpD,IAAI,CAKN;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,kBAAkB,CAChC,MAAM,EAAE,iBAAiB,EACzB,KAAK,SAAoB,EACzB,MAAM,SAAqB,EAC3B,SAAS,CAAC,EAAE,WAAW,EACvB,IAAI,CAAC,EAAE;IAAE,KAAK,CAAC,EAAE,OAAO,CAAC;IAAC,qBAAqB,CAAC,EAAE,OAAO,CAAA;CAAE,GAC1D,KAAK,CAAC,aAAa,CAwBrB;AAED;;;;GAIG;AACH,wBAAgB,eAAe,CAC7B,QAAQ,EAAE,KAAK,CAAC,aAAa,EAC7B,KAAK,SAAoB,EACzB,MAAM,SAAqB,GAC1B;IAAE,KAAK,EAAE,KAAK,CAAC,KAAK,CAAC;IAAC,MAAM,EAAE,KAAK,CAAC,iBAAiB,CAAC;IAAC,QAAQ,EAAE,cAAc,CAAA;CAAE,CAyBnF;AAED;;;;;GAKG;AACH,wBAAgB,aAAa,CAC3B,MAAM,EAAE,iBAAiB,EACzB,KAAK,SAAoB,EACzB,MAAM,SAAqB,GAC1B,eAAe,CAIjB;AAkBD;;;;;;;GAOG;AACH,wBAAgB,wBAAwB,CACtC,QAAQ,EAAE,cAAc,EACxB,QAAQ,EAAE,KAAK,CAAC,aAAa,EAC7B,KAAK,EAAE,KAAK,CAAC,KAAK,EAClB,MAAM,EAAE,KAAK,CAAC,MAAM,EACpB,GAAG,CAAC,EAAE,iBAAiB,EACvB,SAAS,CAAC,EAAE,GAAG,CAAC,MAAM,EAAE,KAAK,CAAC,QAAQ,CAAC,EACvC,UAAU,CAAC,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC,GACjC,IAAI,CAsVN;AAED;;;;;;;GAOG;AACH,wBAAgB,wBAAwB,CACtC,QAAQ,EAAE,cAAc,EACxB,QAAQ,EAAE,KAAK,CAAC,aAAa,EAC7B,KAAK,EAAE,KAAK,CAAC,KAAK,EAClB,MAAM,EAAE,KAAK,CAAC,MAAM,EACpB,GAAG,CAAC,EAAE,iBAAiB,EACvB,OAAO,CAAC,EAAE;IACR,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,SAAS,CAAC,EAAE,GAAG,CAAC,MAAM,EAAE,KAAK,CAAC,QAAQ,CAAC,CAAC;IACxC,UAAU,CAAC,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC,CAAC;CACpC,GACA,IAAI,CAeN"}