@vgai/engine 0.2.0

package/src/scene/user-data.ts

@@ -0,0 +1,203 @@
+/**
+ * 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.
+ * - `_animGraph`          — live AnimGraph instance (state machine) for this entity.
+ * - `_animGraphData`      — the AnimGraphFile the graph was built from (inspector cache).
+ * - `_availableClips`     — string[] of clip names discovered on the GLTF.
+ *
+ * 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 { AnimGraph } from '../animation/anim-graph';
+import type { AnimGraphFile } from '../animation/anim-graph-types';
+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;
+  _animGraph: AnimGraph;
+  _animGraphData: AnimGraphFile;
+  _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 const UserDataKeys = {
+  entity: 'entity',
+  entityId: 'entityId',
+  tags: 'tags',
+  components: 'components',
+  navRole: 'navRole',
+  pivot: 'pivot',
+  splineCurve: 'splineCurve',
+  splineControlPoint: 'splineControlPoint',
+  _camera: '_camera',
+  _particleSystem: '_particleSystem',
+  _animMixer: '_animMixer',
+  _animGraph: '_animGraph',
+  _animGraphData: '_animGraphData',
+  _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',
+} as const satisfies Record<UserDataKey, string>;
+
+/**
+ * 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<K extends UserDataKey>(
+  obj: THREE.Object3D | null | undefined,
+  key: K,
+): UserDataSchema[K] | undefined {
+  return obj ? (obj.userData[UserDataKeys[key]] as UserDataSchema[K] | undefined) : undefined;
+}
+
+/** Write a typed `userData` value. */
+export function setUserData<K extends UserDataKey>(
+  obj: THREE.Object3D,
+  key: K,
+  value: UserDataSchema[K],
+): void {
+  obj.userData[UserDataKeys[key]] = value;
+}
+
+/** True when `key` is set (not `undefined`) on the object's `userData`. */
+export function hasUserData(obj: THREE.Object3D | null | undefined, key: UserDataKey): boolean {
+  return obj ? obj.userData[UserDataKeys[key]] !== undefined : false;
+}
+
+/** Remove a `userData` key. */
+export function deleteUserData(obj: THREE.Object3D, key: UserDataKey): void {
+  delete obj.userData[UserDataKeys[key]];
+}

package/src/setup/setup-audio.ts

@@ -0,0 +1,60 @@
+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 function setupAudio(camera: THREE.Camera): AudioContext {
+  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/src/setup/setup-particles.ts

@@ -0,0 +1,23 @@
+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 function setupParticles(scene: THREE.Scene): ParticlesContext {
+  const batchedRenderer = new BatchedRenderer();
+  scene.add(batchedRenderer);
+
+  return { batchedRenderer };
+}

package/src/setup/setup-physics.ts

@@ -0,0 +1,67 @@
+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 function setupPhysics(
+  rapier: typeof RAPIER,
+  scene: THREE.Scene,
+  gravity: { x: number; y: number; z: number } = { x: 0, y: -9.81, z: 0 },
+): PhysicsContext {
+  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: RAPIER.World, debugMesh: THREE.LineSegments) {
+  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') as THREE.BufferAttribute | undefined;
+  if (posAttr && posAttr.array.length === buffers.vertices.length) {
+    (posAttr.array as Float32Array).set(buffers.vertices);
+    posAttr.needsUpdate = true;
+  } else {
+    geom.setAttribute('position', new THREE.BufferAttribute(new Float32Array(buffers.vertices), 3));
+  }
+
+  const colAttr = geom.getAttribute('color') as THREE.BufferAttribute | undefined;
+  if (colAttr && colAttr.array.length === buffers.colors.length) {
+    (colAttr.array as Float32Array).set(buffers.colors);
+    colAttr.needsUpdate = true;
+  } else {
+    geom.setAttribute('color', new THREE.BufferAttribute(new Float32Array(buffers.colors), 4));
+  }
+}