@vgai/editor 0.2.0

package/src/entity-factory.ts

@@ -0,0 +1,221 @@
+import { buildClipMap } from '@engine/animation/clip-map';
+// GLTF/texture load+cache is shared with the runtime (A2). DRACO (CB2)
+// is wired on the shared gltfLoader inside this module, and `loadGLTF` returns a
+// disposal-safe clone (own materials + `__sharedGeometry` tags) — the same
+// clone-safety contract the runtime relies on.
+import { loadGLTF, resolveGltfNode } from '@engine/scene/asset-loaders';
+import { DEFAULTS } from '@engine/scene/defaults';
+import { deleteUserData, getUserData, setUserData } from '@engine/scene/user-data';
+import '@engine/scene/geometries';
+import '@engine/scene/instancers';
+import { buildInstancedMesh } from '@engine/scene/instance-registry';
+// createLight/createCamera are shared with the runtime scene-loader (T1.13) so
+// the editor preview builds exactly the light/camera the game renders — same
+// reasoning as createGeometry/createMaterial below (one source of truth).
+import { createCamera, createLight } from '@engine/scene/light-camera-factory';
+// createGeometry/createMaterial are shared with the runtime scene-loader so the
+// editor preview renders exactly what the game renders (one source of truth).
+import { createGeometry, createMaterial } from '@engine/scene/material-factory';
+import '@engine/scene/materials';
+import { createParticleSystemFromData } from '@engine/scene/particles-factory';
+import type { SceneEntity } from '@engine/scene/scene-types';
+import * as THREE from 'three';
+
+/**
+ * Load a GLTF and return a disposal-safe clone + its animation clips for the
+ * inspector. Thin wrapper over the shared {@link loadGLTF} (A2): the clone gets
+ * its own materials and every mesh is tagged `__sharedGeometry`, so editor
+ * disposal (scene-sync) never frees the cached source geometry.
+ */
+function loadGltfWithClips(
+  src: string,
+): Promise<{ clone: THREE.Group; animations: THREE.AnimationClip[] }> {
+  return loadGLTF(src).then(({ scene, animations }) => ({ clone: scene, animations }));
+}
+
+/** Set up animation on a GLTF entity group after the model has loaded. */
+function setupAnimation(
+  group: THREE.Group,
+  clone: THREE.Group,
+  animations: THREE.AnimationClip[],
+  autoplay?: string,
+  loop?: boolean,
+): void {
+  if (animations.length === 0) return;
+  const clipMap = buildClipMap(animations);
+
+  // Expose available clip names for the inspector dropdown
+  setUserData(group, '_availableClips', [...clipMap.keys()]);
+
+  if (autoplay) {
+    // Simple clip autoplay (no state machine — GameComponent-driven XState
+    // animation, E5's replacement for the removed AnimGraph, only runs in
+    // Play mode, not this static editor preview)
+    const clip = clipMap.get(autoplay);
+    if (clip) {
+      const mixer = new THREE.AnimationMixer(clone);
+      const action = mixer.clipAction(clip);
+      const effectiveLoop = loop ?? DEFAULTS.animation.loop;
+      action.setLoop(effectiveLoop ? THREE.LoopRepeat : THREE.LoopOnce, Infinity);
+      action.clampWhenFinished = !effectiveLoop;
+      action.play();
+      setUserData(group, '_animMixer', mixer);
+    }
+  }
+}
+
+/**
+ * Stop and release the AnimationMixer attached to a (GLTF) entity object, if any
+ * (ED5). Called when an entity's preview object is rebuilt or removed so the
+ * prior mixer + its cached clip actions don't leak. Safe to call on any object.
+ */
+export function disposeEntityAnimation(obj: THREE.Object3D): void {
+  const mixer = getUserData(obj, '_animMixer') as THREE.AnimationMixer | undefined;
+  if (mixer) {
+    mixer.stopAllAction();
+    const root = mixer.getRoot() as THREE.Object3D | undefined;
+    if (root) mixer.uncacheRoot(root);
+    deleteUserData(obj, '_animMixer');
+  }
+}
+
+// --- Collider wireframe helpers ---
+
+/**
+ * Creates a Three.js Object3D from a SceneEntity for editor preview.
+ * No ECS, no physics — just visuals + light helpers.
+ */
+// biome-ignore lint/complexity/noExcessiveCognitiveComplexity: straightforward type-based switch with fallback args
+export function createEntityObject(entity: SceneEntity): THREE.Object3D {
+  let obj: THREE.Object3D = new THREE.Group();
+
+  if (entity.mesh) {
+    if (entity.mesh.type === 'gltf' && entity.mesh.src) {
+      // GLTF: return a group, async-load the model and add it as a child
+      const group = new THREE.Group();
+      const src = entity.mesh.src;
+
+      const gltfPromise = loadGltfWithClips(src);
+
+      const autoplay = entity.animation?.autoplay;
+      const loop = entity.animation?.loop;
+
+      const nodeName = entity.mesh.node;
+      const lod = entity.mesh.lod;
+      gltfPromise.then(({ clone, animations }) => {
+        if (!group.parent) return;
+        // F4 — mesh.node: resolve a single sub-node to instantiate as this
+        // entity's geometry instead of the whole file (shared geometry, no
+        // copy — see resolveGltfNode). Mirrors the runtime scene-loader.
+        let content: THREE.Object3D = clone;
+        if (nodeName) {
+          content = resolveGltfNode(clone, nodeName, src);
+          // group.add() below detaches `content` from the glTF hierarchy.
+          // Reset its local transform to identity — the entity's own
+          // transform (applied to `group` further down) is the sole
+          // positioner.
+          content.position.set(0, 0, 0);
+          content.rotation.set(0, 0, 0);
+          content.scale.set(1, 1, 1);
+        } else if (lod?.length) {
+          // F7 — mesh.lod: the editor is a fixed-detail authoring view, so it
+          // shows ONLY the closest (highest-detail) level — no THREE.LOD, no
+          // distance switching while authoring. Mutually exclusive with
+          // `nodeName` (schema guarantees this).
+          const closest = [...lod].sort((a, b) => a.distance - b.distance)[0]!;
+          content = resolveGltfNode(clone, closest.node, src);
+          content.position.set(0, 0, 0);
+          content.rotation.set(0, 0, 0);
+          content.scale.set(1, 1, 1);
+        }
+        group.add(content);
+        // The shared loadGLTF already gave the clone its own materials and tagged
+        // every mesh `__sharedGeometry` (so editor disposal in scene-sync never
+        // frees the cached source geometry). Tag the remaining non-mesh nodes
+        // (root group / bones) too, so the whole subtree is uniformly skipped.
+        content.traverse((n) => {
+          setUserData(n, '__sharedGeometry', true);
+        });
+        setupAnimation(group, clone, animations, autoplay, loop);
+      });
+      obj = group;
+    } else {
+      const geometry = createGeometry(entity.mesh);
+      const material = createMaterial(entity.material);
+      const mesh = entity.mesh.instancer
+        ? buildInstancedMesh(
+            geometry,
+            material,
+            entity.mesh.instancer,
+            entity.mesh.instancerParams ?? {},
+          )
+        : new THREE.Mesh(geometry, material);
+      if (entity.shadow?.enabled) {
+        mesh.castShadow = true;
+        mesh.receiveShadow = true;
+      }
+      obj = mesh;
+    }
+  }
+
+  if (entity.light) {
+    const light = createLight(entity.light);
+    if (entity.shadow?.enabled && 'shadow' in light) {
+      (light as THREE.DirectionalLight).castShadow = true;
+      // A1: default to DEFAULTS.shadow.mapSize so editor matches runtime.
+      (light as THREE.DirectionalLight).shadow.mapSize.setScalar(
+        entity.shadow.mapSize ?? DEFAULTS.shadow.mapSize,
+      );
+    }
+    obj = light;
+  }
+
+  if (entity.camera) {
+    const camera = createCamera(entity.camera);
+    obj = new THREE.Group();
+    obj.add(camera);
+    setUserData(obj, '_camera', camera);
+  }
+
+  // Particle system
+  if (entity.particles) {
+    try {
+      const { emitter, system } = createParticleSystemFromData(entity.particles);
+      setUserData(emitter, 'editorHelper', true);
+      setUserData(emitter, 'editorHelperType', 'particles');
+      obj.add(emitter);
+      // Stash for scene-sync to register with BatchedRenderer
+      setUserData(obj, '_particleSystem', system);
+    } catch {
+      // Invalid particle data — skip silently in editor preview
+    }
+  }
+
+  // Apply transform
+  const pos = entity.transform?.position ?? DEFAULTS.transform.position;
+  const rot = entity.transform?.rotation ?? DEFAULTS.transform.rotation;
+  const scl = entity.transform?.scale ?? DEFAULTS.transform.scale;
+  obj.position.set(pos[0], pos[1], pos[2]);
+  obj.quaternion.set(rot[0], rot[1], rot[2], rot[3]);
+  obj.scale.set(scl[0], scl[1], scl[2]);
+
+  // Pivot metadata + visual indicator
+  const pivot = entity.pivot ?? DEFAULTS.entity.pivot;
+  setUserData(obj, 'pivot', pivot);
+  const hasPivot = pivot[0] !== 0 || pivot[1] !== 0 || pivot[2] !== 0;
+  if (hasPivot) {
+    const pivotHelper = new THREE.AxesHelper(0.15);
+    pivotHelper.position.set(pivot[0], pivot[1], pivot[2]);
+    setUserData(pivotHelper, 'editorHelper', true);
+    setUserData(pivotHelper, 'editorHelperType', 'pivot');
+    obj.add(pivotHelper);
+  }
+
+  obj.name = entity.name;
+  setUserData(obj, 'entityId', entity.id as string);
+  // Store the full entity descriptor as the source of truth for this object.
+  // Inspector, hierarchy, serializer, and undo all read from this.
+  setUserData(obj, 'entity', JSON.parse(JSON.stringify(entity)) as SceneEntity);
+
+  return obj;
+}

package/src/game-globals-prelude.ts

@@ -0,0 +1,27 @@
+/**
+ * The lexical shadow prepended to every project/game module so `window` and
+ * `document` resolve to the editor's gated proxies instead of the real, shared
+ * globals — this is how a raw `window.addEventListener('keydown', …)` in game
+ * code gets focus-gated without touching the editor's own listeners.
+ *
+ * It lives in its own module, apart from `gated-globals.ts`, because it has THREE
+ * consumers spanning two TypeScript programs:
+ *   - `gated-globals.ts` (browser) re-exports it, and installs the proxies;
+ *   - `browser-transpile.ts` (browser) prepends it to client-transpiled source;
+ *   - `vite-plugin-game-globals.ts` (Node) prepends it at transform time, and is
+ *     reachable from `tsconfig.server.json` via `server/dev.ts`.
+ *
+ * That last one is the constraint: the server program compiles without the DOM
+ * lib, so it cannot pull in `gated-globals.ts` (whose proxy code names `window`,
+ * `document`, and `EventListenerOrEventListenerObject`). This module names none
+ * of them, so both programs can import the ONE definition. The dev server used to
+ * keep a hand-copied duplicate policed by a source-text sync test; extracting the
+ * constant deletes the copy and the test with it.
+ *
+ * Safe ahead of a module's own `import` statements: ESM imports are hoisted, so a
+ * leading `const window = …` still shadows for the whole module body. See
+ * `gated-globals.ts` for the proxy semantics it reaches.
+ */
+export const GAME_GLOBALS_PRELUDE =
+  'const window=(globalThis.__vgaiGameWindow||globalThis.window),' +
+  'document=(globalThis.__vgaiGameDocument||globalThis.document);\n';

package/src/gated-globals.ts

@@ -0,0 +1,131 @@
+/**
+ * Gated game globals — "pipe window/document into the game's context".
+ *
+ * Arbitrary game code can reach for the real, shared `window`
+ * (`window.addEventListener('keydown', …)`), which fires regardless of whether
+ * the game viewport is focused — so keystrokes leak into the editor while you
+ * work in it. There is no cooperative way to stop that in a shared JS context.
+ *
+ * Instead of patching the real global (blunt, collateral damage to the editor's
+ * own listeners), we pipe a *scoped* global into game code: the dev server
+ * lexically shadows `window`/`document` in every project module (prepending
+ * `const window = globalThis.__vgaiGameWindow …`), and this module provides that
+ * value — a Proxy that forwards everything to the real global EXCEPT input
+ * listener registration, which it gates on {@link setGameInputGate}. Only game
+ * modules see the proxy; the editor's own `window` is untouched, so there is no
+ * collateral (OrbitControls, editor shortcuts, Escape-to-stop all keep working).
+ *
+ * Shared-context best-effort: property handlers (`el.onkeydown = …`) and
+ * listeners on other targets are out of scope. True cooperation-free isolation
+ * would need a separate browsing context (iframe) — rejected (breaks the
+ * shared heap the engine/editor singletons rely on; see T6.3 task notes).
+ */
+
+/** The one-line prelude the transpile layer prepends to every project module.
+ *  Defined in a DOM-free module so the Node-side Vite plugin can import the same
+ *  constant — see `game-globals-prelude.ts`. Re-exported here for the browser
+ *  callers that already reach for it alongside the proxies. */
+export { GAME_GLOBALS_PRELUDE } from './game-globals-prelude';
+
+/** Event types that constitute "game input" and are focus-gated. */
+const INPUT_EVENT_TYPES = new Set<string>([
+  'keydown',
+  'keyup',
+  'keypress',
+  'mousedown',
+  'mouseup',
+  'mousemove',
+  'wheel',
+  'pointerdown',
+  'pointerup',
+  'pointermove',
+]);
+
+/** Predicate deciding whether game input listeners currently fire. */
+let inputGate: () => boolean = () => true;
+
+/**
+ * Set the gate that decides whether game input listeners fire right now. The
+ * editor host sets this so the game only receives input while its viewport is
+ * the active surface; reset it to always-true when no game is running.
+ */
+export function setGameInputGate(fn: () => boolean): void {
+  inputGate = fn;
+}
+
+/** Build a Proxy over `real` that gates input-listener registration.
+ *  Exported for unit tests (build a proxy over a stub EventTarget). */
+export function makeGatedProxy<T extends EventTarget>(real: T): T {
+  // original listener → gated wrapper, keyed by type, so removeEventListener
+  // detaches the wrapper actually registered.
+  const wrappedByType = new Map<string, Map<EventListener, EventListener>>();
+
+  const gatedAdd = (
+    type: string,
+    listener: EventListenerOrEventListenerObject | null,
+    options?: boolean | AddEventListenerOptions,
+  ): void => {
+    if (INPUT_EVENT_TYPES.has(type) && typeof listener === 'function') {
+      let m = wrappedByType.get(type);
+      if (!m) {
+        m = new Map();
+        wrappedByType.set(type, m);
+      }
+      const inner = listener as EventListener;
+      let wrapped = m.get(inner);
+      if (!wrapped) {
+        wrapped = function (this: unknown, e: Event) {
+          if (inputGate()) return (inner as (this: unknown, e: Event) => unknown).call(this, e);
+          return undefined;
+        };
+        m.set(inner, wrapped);
+      }
+      real.addEventListener(type, wrapped, options);
+      return;
+    }
+    real.addEventListener(type, listener, options);
+  };
+
+  const gatedRemove = (
+    type: string,
+    listener: EventListenerOrEventListenerObject | null,
+    options?: boolean | EventListenerOptions,
+  ): void => {
+    if (INPUT_EVENT_TYPES.has(type) && typeof listener === 'function') {
+      const m = wrappedByType.get(type);
+      const wrapped = m?.get(listener as EventListener);
+      if (wrapped) {
+        m?.delete(listener as EventListener);
+        real.removeEventListener(type, wrapped, options);
+        return;
+      }
+    }
+    real.removeEventListener(type, listener, options);
+  };
+
+  return new Proxy(real, {
+    get(target, prop) {
+      if (prop === 'addEventListener') return gatedAdd;
+      if (prop === 'removeEventListener') return gatedRemove;
+      // Resolve against the real target (this === target), so window/document
+      // getters (innerWidth, body, …) and methods (rAF, setTimeout) work.
+      const value = Reflect.get(target, prop);
+      return typeof value === 'function' ? value.bind(target) : value;
+    },
+  }) as T;
+}
+
+let installed = false;
+
+/**
+ * Install the gated `window`/`document` proxies on `globalThis` so the prelude
+ * prepended to project modules resolves to them. Idempotent; no-op outside a
+ * browser (the dev server never calls this).
+ */
+export function installGatedGameGlobals(): void {
+  if (installed || typeof window === 'undefined' || typeof document === 'undefined') return;
+  installed = true;
+  const g = globalThis as unknown as Record<string, unknown>;
+  g['__vgaiGameWindow'] = makeGatedProxy(window);
+  g['__vgaiGameDocument'] = makeGatedProxy(document);
+}

package/src/generated/setup-by-example.generated.ts

@@ -0,0 +1,53 @@
+/**
+ * GENERATED by scripts/bundle-project-scripts.mjs — do not edit by hand.
+ *
+ * exampleId → example setup, derived from each example folder's
+ * `vgai.game.json` manifest (the single source of truth — see
+ * docs/EXAMPLES-AS-PROJECTS-DESIGN.md §4). Regenerate with
+ * `node scripts/bundle-project-scripts.mjs` (also runs automatically before
+ * the `--mode web` build). A freshness test
+ * (packages/editor/test/setup-by-scene-generation.test.ts) fails CI if this
+ * file drifts from the manifests.
+ *
+ * Included: example manifests that declare a world with BOTH `scene` and
+ * `entry`, and do NOT have a manifest-level `server` — server-room entries
+ * (e.g. the third-person-arena example) need a Colyseus server the static
+ * host doesn't run, so they fall through to the generic scene loader instead.
+ * Entries missing `scene` or `entry` (`hp-hud`; every world of
+ * `tri-world`) aren't scene-dispatchable and are skipped too.
+ */
+
+import type { GameCleanup, GameContext } from '@engine/runtime/types';
+
+import { setup as editorTutorial } from '../../../../examples/editor-tutorial/src/index';
+import { setup as featureScenes } from '../../../../examples/feature-scenes/src/index';
+import { setup as fps } from '../../../../examples/fps/src/index';
+import { setup as ik } from '../../../../examples/ik/src/index';
+import { setup as learnJoints } from '../../../../examples/learn-joints/src/index';
+import { setup as learnMatfiles } from '../../../../examples/learn-matfiles/src/index';
+import { setup as learnSplines } from '../../../../examples/learn-splines/src/index';
+import { setup as learnTriggers } from '../../../../examples/learn-triggers/src/index';
+import { setup as littlestTokyo } from '../../../../examples/littlest-tokyo/src/index';
+import { setup as rts } from '../../../../examples/rts/src/index';
+import { setup as starfighter } from '../../../../examples/starfighter/src/index';
+import { setup as thirdPerson } from '../../../../examples/third-person/src/index';
+import { setup as vehicle } from '../../../../examples/vehicle/src/index';
+
+export type ExampleSetup = (ctx: GameContext) => Promise<GameCleanup>;
+
+/** Mirrors the example folders' `vgai.game.json` manifests, but STATIC (see browser-play-entry.ts). */
+export const SETUP_BY_EXAMPLE_ID: Record<string, ExampleSetup> = {
+  'editor-tutorial': editorTutorial,
+  'feature-scenes': featureScenes,
+  fps: fps,
+  ik: ik,
+  'learn-joints': learnJoints,
+  'learn-matfiles': learnMatfiles,
+  'learn-splines': learnSplines,
+  'learn-triggers': learnTriggers,
+  'littlest-tokyo': littlestTokyo,
+  rts: rts,
+  starfighter: starfighter,
+  'third-person': thirdPerson,
+  vehicle: vehicle,
+};