@vgai/engine 0.2.0 → 0.3.0

package/dist/scene/user-data.d.ts

@@ -0,0 +1,171 @@
+/**
+ * Typed registry for `Object3D.userData` keys used by the engine and editor.
+ *
+ * Three.js lets any code stash arbitrary values on `object.userData`, and over
+ * time the engine + editor accumulated ~20 stringly-typed keys that together
+ * form a *parallel object model* — meaning carried entirely in undocumented
+ * string literals. This module is the ONE documented place that lists every
+ * such key, its value type, and what it means. All engine/editor-internal
+ * `userData` access for these keys must go through {@link getUserData} /
+ * {@link setUserData} / {@link hasUserData} / {@link deleteUserData} so the key
+ * strings live in exactly one place and are type-checked at every call site.
+ *
+ * NOTE: This covers engine/editor *internal* keys only. User game code in the
+ * example template may stash its own ad-hoc keys; those are out of scope.
+ *
+ * ## Key reference
+ *
+ * Serialization / identity (load-bearing — editor identity + scene I/O):
+ * - `entity`              — the full {@link SceneEntity} descriptor backing this
+ *                           Object3D. Source of truth the editor reads/writes and
+ *                           the serializer walks to rebuild `.vscn.json`.
+ * - `entityId`            — the entity's stable string id. Presence also marks an
+ *                           Object3D as a "real" entity (vs editor helper/env object).
+ *
+ * Runtime scene-query overrides (read by `scene-query.ts`):
+ * - `tags`                — string[] tag override; falls back to `entity.tags`.
+ * - `components`          — component record or name[] override; falls back to
+ *                           `entity.components`.
+ *
+ * Runtime gameplay metadata (set by the scene loader):
+ * - `navRole`             — `'walkable' | 'obstacle'` navmesh role; collected at runtime.
+ * - `pivot`              — `[x,y,z]` local-space pivot for rotate/scale-around-pivot.
+ * - `splineCurve`         — resolved THREE curve built from the entity's spline.
+ * - `_camera`             — THREE.Camera owned by a camera entity (collected on load).
+ * - `_particleSystem`     — three.quarks ParticleSystem (scene-sync registration + census).
+ *
+ * Animation (load-bearing — ED5 disposal contract):
+ * - `_animMixer`          — THREE.AnimationMixer driving this subtree's clips.
+ * - `_animClips`          — Map<string, AnimationClip> discovered on the GLTF (E5 —
+ *                           lets a GameComponent build its own XState-driven
+ *                           binding via `bindXStateAnimation` over the SAME
+ *                           mixer; see xstate-animation-binding.ts).
+ * - `_availableClips`     — string[] of clip names discovered on the GLTF
+ *                           (inspector dropdown; same names as `_animClips`' keys).
+ *
+ * Disposal contract:
+ * - `__sharedGeometry`    — `true` when a mesh's geometry is shared/cached and MUST
+ *                           NOT be disposed by per-object cleanup (P0.2 contract).
+ *
+ * Editor shading overrides (editor-only, see `scene-sync.ts`):
+ * - `__shadeOrig`         — original material(s) stashed before a shading override.
+ * - `__shadeUnlit`        — generated unlit material(s) for the unlit view mode.
+ *
+ * Custom-shader materials (see `material-registry.ts`):
+ * - `__matDef`            — name of the registered custom-material definition.
+ * - `__uniforms`          — authored uniform values passed to the def's update().
+ *
+ * Instancing (see `instance-registry.ts`):
+ * - `__instancer`         — name of the registered instancer that built the mesh.
+ *
+ * Unmodified-game ingestion (editor-only, see `editor/src/ingest/`):
+ * - `__ingest`            — `true` on every Object3D minted by ingestion (vs the
+ *                           first-party scene loader); routes edits to live
+ *                           mutation instead of descriptor rebuild.
+ * - `__ingestNextId`      — monotonic id counter stashed on the captured Scene
+ *                           root so re-reflects keep minting unique ids.
+ *
+ * Editor scene-graph tagging (editor-only):
+ * - `engineInternal`      — `true` on engine-owned infrastructure in the game scene
+ *                           (particle BatchedRenderer, debug-draw + its subtree).
+ *                           The editor's play-mode hierarchy skips these so they
+ *                           don't show up as selectable "entities".
+ * - `liveObject`          — `true` on a runtime/procedural Object3D that the editor
+ *                           surfaced in the play-mode hierarchy with a *synthetic*
+ *                           descriptor (it has no `.vscn` record). Marks it as
+ *                           ephemeral: selectable/movable for testing, never saved.
+ * - `editorHelper`        — `true` for editor-only helper objects (gizmos, wireframes).
+ * - `editorHelperType`    — which kind of helper (lights/particles/pivot/navmesh/...).
+ * - `editorIcon`          — `true` for editor billboard icon sprites.
+ * - `envObject`           — `true` for environment objects (ambient light, etc.).
+ * - `splineControlPoint`  — index of a spline control-point drag handle.
+ * - `vcDirIdx`            — view-cube face direction index (0=+X,1=-X,2=+Y,...).
+ */
+import type * as THREE from 'three';
+import type { ParticleSystem } from 'three.quarks';
+import type { SceneEntity } from './scene-types';
+/** The kinds of editor helper objects tagged via `editorHelperType`. */
+export type EditorHelperType = 'lights' | 'cameras' | 'audio' | 'colliders' | 'splines' | 'particles' | 'pivot' | 'navmesh';
+/**
+ * Maps each canonical accessor name to its value type. This is the single
+ * source of truth for what every known `userData` key holds.
+ */
+export interface UserDataSchema {
+    entity: SceneEntity;
+    entityId: string;
+    tags: string[];
+    components: Record<string, unknown> | string[];
+    navRole: 'walkable' | 'obstacle';
+    pivot: [number, number, number];
+    splineCurve: THREE.Curve<THREE.Vector3>;
+    splineControlPoint: number;
+    _camera: THREE.Camera;
+    _particleSystem: ParticleSystem;
+    _animMixer: THREE.AnimationMixer;
+    _animClips: Map<string, THREE.AnimationClip>;
+    _availableClips: string[];
+    __sharedGeometry: boolean;
+    __shadeOrig: THREE.Material | THREE.Material[];
+    __shadeUnlit: THREE.Material[];
+    __matDef: string;
+    __uniforms: Record<string, unknown>;
+    __instancer: string;
+    __ingest: boolean;
+    __ingestNextId: number;
+    engineInternal: boolean;
+    liveObject: boolean;
+    editorHelper: boolean;
+    editorHelperType: EditorHelperType;
+    editorIcon: boolean;
+    envObject: boolean;
+    vcDirIdx: number;
+}
+/** Any key in the typed registry. */
+export type UserDataKey = keyof UserDataSchema;
+/**
+ * Canonical name → literal `userData` string key. The accessor names match the
+ * raw string keys 1:1 (this is the documented set referenced by the AC), so the
+ * literal strings appear in exactly this one place.
+ */
+export declare const UserDataKeys: {
+    readonly entity: "entity";
+    readonly entityId: "entityId";
+    readonly tags: "tags";
+    readonly components: "components";
+    readonly navRole: "navRole";
+    readonly pivot: "pivot";
+    readonly splineCurve: "splineCurve";
+    readonly splineControlPoint: "splineControlPoint";
+    readonly _camera: "_camera";
+    readonly _particleSystem: "_particleSystem";
+    readonly _animMixer: "_animMixer";
+    readonly _animClips: "_animClips";
+    readonly _availableClips: "_availableClips";
+    readonly __sharedGeometry: "__sharedGeometry";
+    readonly __shadeOrig: "__shadeOrig";
+    readonly __shadeUnlit: "__shadeUnlit";
+    readonly __matDef: "__matDef";
+    readonly __uniforms: "__uniforms";
+    readonly __instancer: "__instancer";
+    readonly __ingest: "__ingest";
+    readonly __ingestNextId: "__ingestNextId";
+    readonly engineInternal: "engineInternal";
+    readonly liveObject: "liveObject";
+    readonly editorHelper: "editorHelper";
+    readonly editorHelperType: "editorHelperType";
+    readonly editorIcon: "editorIcon";
+    readonly envObject: "envObject";
+    readonly vcDirIdx: "vcDirIdx";
+};
+/**
+ * Read a typed `userData` value. Returns `undefined` when the key is unset or
+ * when `obj` is nullish (so call sites can pass an optionally-resolved object).
+ */
+export declare function getUserData<K extends UserDataKey>(obj: THREE.Object3D | null | undefined, key: K): UserDataSchema[K] | undefined;
+/** Write a typed `userData` value. */
+export declare function setUserData<K extends UserDataKey>(obj: THREE.Object3D, key: K, value: UserDataSchema[K]): void;
+/** True when `key` is set (not `undefined`) on the object's `userData`. */
+export declare function hasUserData(obj: THREE.Object3D | null | undefined, key: UserDataKey): boolean;
+/** Remove a `userData` key. */
+export declare function deleteUserData(obj: THREE.Object3D, key: UserDataKey): void;
+//# sourceMappingURL=user-data.d.ts.map

package/dist/scene/user-data.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"user-data.d.ts","sourceRoot":"","sources":["../../src/scene/user-data.ts"],"names":[],"mappings":"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"}

package/dist/scene/user-data.js

@@ -0,0 +1,137 @@
+/**
+ * Typed registry for `Object3D.userData` keys used by the engine and editor.
+ *
+ * Three.js lets any code stash arbitrary values on `object.userData`, and over
+ * time the engine + editor accumulated ~20 stringly-typed keys that together
+ * form a *parallel object model* — meaning carried entirely in undocumented
+ * string literals. This module is the ONE documented place that lists every
+ * such key, its value type, and what it means. All engine/editor-internal
+ * `userData` access for these keys must go through {@link getUserData} /
+ * {@link setUserData} / {@link hasUserData} / {@link deleteUserData} so the key
+ * strings live in exactly one place and are type-checked at every call site.
+ *
+ * NOTE: This covers engine/editor *internal* keys only. User game code in the
+ * example template may stash its own ad-hoc keys; those are out of scope.
+ *
+ * ## Key reference
+ *
+ * Serialization / identity (load-bearing — editor identity + scene I/O):
+ * - `entity`              — the full {@link SceneEntity} descriptor backing this
+ *                           Object3D. Source of truth the editor reads/writes and
+ *                           the serializer walks to rebuild `.vscn.json`.
+ * - `entityId`            — the entity's stable string id. Presence also marks an
+ *                           Object3D as a "real" entity (vs editor helper/env object).
+ *
+ * Runtime scene-query overrides (read by `scene-query.ts`):
+ * - `tags`                — string[] tag override; falls back to `entity.tags`.
+ * - `components`          — component record or name[] override; falls back to
+ *                           `entity.components`.
+ *
+ * Runtime gameplay metadata (set by the scene loader):
+ * - `navRole`             — `'walkable' | 'obstacle'` navmesh role; collected at runtime.
+ * - `pivot`              — `[x,y,z]` local-space pivot for rotate/scale-around-pivot.
+ * - `splineCurve`         — resolved THREE curve built from the entity's spline.
+ * - `_camera`             — THREE.Camera owned by a camera entity (collected on load).
+ * - `_particleSystem`     — three.quarks ParticleSystem (scene-sync registration + census).
+ *
+ * Animation (load-bearing — ED5 disposal contract):
+ * - `_animMixer`          — THREE.AnimationMixer driving this subtree's clips.
+ * - `_animClips`          — Map<string, AnimationClip> discovered on the GLTF (E5 —
+ *                           lets a GameComponent build its own XState-driven
+ *                           binding via `bindXStateAnimation` over the SAME
+ *                           mixer; see xstate-animation-binding.ts).
+ * - `_availableClips`     — string[] of clip names discovered on the GLTF
+ *                           (inspector dropdown; same names as `_animClips`' keys).
+ *
+ * Disposal contract:
+ * - `__sharedGeometry`    — `true` when a mesh's geometry is shared/cached and MUST
+ *                           NOT be disposed by per-object cleanup (P0.2 contract).
+ *
+ * Editor shading overrides (editor-only, see `scene-sync.ts`):
+ * - `__shadeOrig`         — original material(s) stashed before a shading override.
+ * - `__shadeUnlit`        — generated unlit material(s) for the unlit view mode.
+ *
+ * Custom-shader materials (see `material-registry.ts`):
+ * - `__matDef`            — name of the registered custom-material definition.
+ * - `__uniforms`          — authored uniform values passed to the def's update().
+ *
+ * Instancing (see `instance-registry.ts`):
+ * - `__instancer`         — name of the registered instancer that built the mesh.
+ *
+ * Unmodified-game ingestion (editor-only, see `editor/src/ingest/`):
+ * - `__ingest`            — `true` on every Object3D minted by ingestion (vs the
+ *                           first-party scene loader); routes edits to live
+ *                           mutation instead of descriptor rebuild.
+ * - `__ingestNextId`      — monotonic id counter stashed on the captured Scene
+ *                           root so re-reflects keep minting unique ids.
+ *
+ * Editor scene-graph tagging (editor-only):
+ * - `engineInternal`      — `true` on engine-owned infrastructure in the game scene
+ *                           (particle BatchedRenderer, debug-draw + its subtree).
+ *                           The editor's play-mode hierarchy skips these so they
+ *                           don't show up as selectable "entities".
+ * - `liveObject`          — `true` on a runtime/procedural Object3D that the editor
+ *                           surfaced in the play-mode hierarchy with a *synthetic*
+ *                           descriptor (it has no `.vscn` record). Marks it as
+ *                           ephemeral: selectable/movable for testing, never saved.
+ * - `editorHelper`        — `true` for editor-only helper objects (gizmos, wireframes).
+ * - `editorHelperType`    — which kind of helper (lights/particles/pivot/navmesh/...).
+ * - `editorIcon`          — `true` for editor billboard icon sprites.
+ * - `envObject`           — `true` for environment objects (ambient light, etc.).
+ * - `splineControlPoint`  — index of a spline control-point drag handle.
+ * - `vcDirIdx`            — view-cube face direction index (0=+X,1=-X,2=+Y,...).
+ */
+/**
+ * Canonical name → literal `userData` string key. The accessor names match the
+ * raw string keys 1:1 (this is the documented set referenced by the AC), so the
+ * literal strings appear in exactly this one place.
+ */
+export const UserDataKeys = {
+    entity: 'entity',
+    entityId: 'entityId',
+    tags: 'tags',
+    components: 'components',
+    navRole: 'navRole',
+    pivot: 'pivot',
+    splineCurve: 'splineCurve',
+    splineControlPoint: 'splineControlPoint',
+    _camera: '_camera',
+    _particleSystem: '_particleSystem',
+    _animMixer: '_animMixer',
+    _animClips: '_animClips',
+    _availableClips: '_availableClips',
+    __sharedGeometry: '__sharedGeometry',
+    __shadeOrig: '__shadeOrig',
+    __shadeUnlit: '__shadeUnlit',
+    __matDef: '__matDef',
+    __uniforms: '__uniforms',
+    __instancer: '__instancer',
+    __ingest: '__ingest',
+    __ingestNextId: '__ingestNextId',
+    engineInternal: 'engineInternal',
+    liveObject: 'liveObject',
+    editorHelper: 'editorHelper',
+    editorHelperType: 'editorHelperType',
+    editorIcon: 'editorIcon',
+    envObject: 'envObject',
+    vcDirIdx: 'vcDirIdx',
+};
+/**
+ * Read a typed `userData` value. Returns `undefined` when the key is unset or
+ * when `obj` is nullish (so call sites can pass an optionally-resolved object).
+ */
+export function getUserData(obj, key) {
+    return obj ? obj.userData[UserDataKeys[key]] : undefined;
+}
+/** Write a typed `userData` value. */
+export function setUserData(obj, key, value) {
+    obj.userData[UserDataKeys[key]] = value;
+}
+/** True when `key` is set (not `undefined`) on the object's `userData`. */
+export function hasUserData(obj, key) {
+    return obj ? obj.userData[UserDataKeys[key]] !== undefined : false;
+}
+/** Remove a `userData` key. */
+export function deleteUserData(obj, key) {
+    delete obj.userData[UserDataKeys[key]];
+}

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,69 @@
+import { EffectComposer } from 'postprocessing';
+import * as THREE from 'three';
+import { type RenderScope } from '../render/render-settings';
+import type { SceneEnvironment } from '../scene/scene-types';
+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
+ * `HostContext.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, COMPOSITION-DESIGN.md 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 worlds 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?: SceneEnvironment, 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":"AACA,OAAO,EAQL,cAAc,EAoBf,MAAM,gBAAgB,CAAC;AAExB,OAAO,KAAK,KAAK,MAAM,OAAO,CAAC;AAC/B,OAAO,EAAE,KAAK,WAAW,EAAyB,MAAM,2BAA2B,CAAC;AAEpF,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,sBAAsB,CAAC;AAE7D,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,CAoBrB;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,gBAAgB,EACtB,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"}