@vgai/editor 0.2.0

package/src/gizmo-registry.ts

@@ -0,0 +1,608 @@
+/**
+ * Gizmo registry — maps entity types to their editor visual representation.
+ *
+ * Inspired by Godot's EditorNode3DGizmoPlugin pattern: each entity type
+ * registers a gizmo definition that describes:
+ *   - icon: a clickable billboard sprite (for selecting non-mesh entities)
+ *   - helpers: wireframe visualizations (frustums, ranges, collider outlines)
+ *
+ * Icons are raycastable (for click-to-select). Helpers are visual-only.
+ * Both live on EDITOR_LAYER so the game camera never sees them.
+ */
+
+import {
+  type ColliderWorldDimensions,
+  computeColliderWorldDimensions,
+} from '@engine/scene/collider-dimensions';
+import { DEFAULTS } from '@engine/scene/defaults';
+import type {
+  SceneCollider,
+  SceneEntity,
+  SceneLight,
+  SceneSpline,
+} from '@engine/scene/scene-types';
+import { getUserData, setUserData } from '@engine/scene/user-data';
+import * as THREE from 'three';
+import { EDITOR_LAYER } from './editor-layers';
+
+// ---------------------------------------------------------------------------
+// Registry types
+// ---------------------------------------------------------------------------
+
+/** A gizmo definition for a particular entity feature. */
+interface GizmoEntry {
+  /**
+   * Test whether this gizmo applies to the given entity.
+   * Returning false skips both icon and helpers.
+   */
+  test(entity: SceneEntity, obj: THREE.Object3D): boolean;
+
+  /**
+   * Create a clickable icon billboard.
+   * The sprite is NOT tagged editorHelper — it participates in raycast selection.
+   */
+  createIcon(): THREE.Sprite;
+
+  /**
+   * Create wireframe helper objects (frustums, ranges, outlines, etc.).
+   * Each returned object is tagged editorHelper and excluded from raycasts.
+   */
+  createHelpers(entity: SceneEntity, obj: THREE.Object3D): THREE.Object3D[];
+}
+
+// ---------------------------------------------------------------------------
+// Icon billboard factory (shared by all entries)
+// ---------------------------------------------------------------------------
+
+const iconTextureCache = new Map<string, THREE.Texture>();
+
+function makeIconSprite(symbol: string, cacheKey: string): THREE.Sprite {
+  let texture = iconTextureCache.get(cacheKey);
+  if (!texture) {
+    const size = 64;
+    const c = document.createElement('canvas');
+    c.width = size;
+    c.height = size;
+    const ctx = c.getContext('2d')!;
+    ctx.font = '48px system-ui, -apple-system, sans-serif';
+    ctx.textAlign = 'center';
+    ctx.textBaseline = 'middle';
+    ctx.fillText(symbol, size / 2, size / 2);
+    texture = new THREE.CanvasTexture(c);
+    iconTextureCache.set(cacheKey, texture);
+  }
+  const mat = new THREE.SpriteMaterial({ map: texture, transparent: true, depthTest: false });
+  const sprite = new THREE.Sprite(mat);
+  sprite.scale.set(0.5, 0.5, 0.5);
+  setUserData(sprite, 'editorIcon', true);
+  sprite.layers.set(EDITOR_LAYER);
+  return sprite;
+}
+
+// ---------------------------------------------------------------------------
+// Shared geometry helpers
+// ---------------------------------------------------------------------------
+
+function createCircleGeometry(radius: number, segments = 32): THREE.BufferGeometry {
+  const pts: THREE.Vector3[] = [];
+  for (let i = 0; i <= segments; i++) {
+    const angle = (i / segments) * Math.PI * 2;
+    pts.push(new THREE.Vector3(Math.cos(angle) * radius, Math.sin(angle) * radius, 0));
+  }
+  return new THREE.BufferGeometry().setFromPoints(pts);
+}
+
+function createSemiArcGeometry(
+  radius: number,
+  centerY: number,
+  plane: 'xz' | 'yz',
+  top: boolean,
+  segments = 16,
+): THREE.BufferGeometry {
+  const pts: THREE.Vector3[] = [];
+  const startAngle = top ? 0 : Math.PI;
+  for (let i = 0; i <= segments; i++) {
+    const angle = startAngle + (i / segments) * Math.PI;
+    const h = Math.cos(angle) * radius;
+    const v = centerY + Math.sin(angle) * radius;
+    if (plane === 'xz') {
+      pts.push(new THREE.Vector3(h, v, 0));
+    } else {
+      pts.push(new THREE.Vector3(0, v, h));
+    }
+  }
+  return new THREE.BufferGeometry().setFromPoints(pts);
+}
+
+// ---------------------------------------------------------------------------
+// Light gizmo
+// ---------------------------------------------------------------------------
+
+const COLLIDER_COLOR = 0x00ff88;
+const SENSOR_COLOR = 0xffcc00;
+
+function createLightHelper(light: THREE.Light, def: SceneLight): THREE.Object3D | null {
+  switch (def.type) {
+    case 'directional':
+      return new THREE.DirectionalLightHelper(light as THREE.DirectionalLight, 1);
+    case 'point':
+      return new THREE.PointLightHelper(light as THREE.PointLight, 0.5);
+    case 'spot':
+      return new THREE.SpotLightHelper(light as THREE.SpotLight);
+    default:
+      return null;
+  }
+}
+
+function createLightRangeHelper(distance: number, color: string): THREE.Object3D {
+  const mat = new THREE.LineBasicMaterial({
+    color: color,
+    transparent: true,
+    opacity: 0.3,
+    depthTest: false,
+  });
+  const group = new THREE.Group();
+  group.add(new THREE.Line(createCircleGeometry(distance, 48), mat));
+  const xzRing = new THREE.Line(createCircleGeometry(distance, 48), mat);
+  xzRing.rotation.x = -Math.PI / 2;
+  group.add(xzRing);
+  const yzRing = new THREE.Line(createCircleGeometry(distance, 48), mat);
+  yzRing.rotation.y = Math.PI / 2;
+  group.add(yzRing);
+  return group;
+}
+
+const lightGizmo: GizmoEntry = {
+  test: (entity) => !!entity.light,
+
+  createIcon: () => makeIconSprite('☀', 'light'),
+
+  createHelpers(entity, obj) {
+    const helpers: THREE.Object3D[] = [];
+    const lightDef = entity.light!;
+
+    if (obj instanceof THREE.Light) {
+      const helper = createLightHelper(obj, lightDef);
+      if (helper) helpers.push(helper);
+    }
+
+    if ((lightDef.type === 'point' || lightDef.type === 'spot') && lightDef.distance) {
+      helpers.push(
+        createLightRangeHelper(lightDef.distance, lightDef.color ?? DEFAULTS.light.color),
+      );
+    }
+
+    return helpers;
+  },
+};
+
+// ---------------------------------------------------------------------------
+// Camera gizmo
+// ---------------------------------------------------------------------------
+
+function createFrustumHelper(camera: THREE.Camera): THREE.LineSegments {
+  const inv = camera.projectionMatrixInverse;
+  const ndc = [
+    [-1, -1, -1],
+    [1, -1, -1],
+    [1, 1, -1],
+    [-1, 1, -1],
+    [-1, -1, 1],
+    [1, -1, 1],
+    [1, 1, 1],
+    [-1, 1, 1],
+  ];
+  const c = ndc.map(([x, y, z]) => new THREE.Vector3(x, y, z).applyMatrix4(inv));
+  const [n0, n1, n2, n3, f0, f1, f2, f3] = c as [
+    THREE.Vector3,
+    THREE.Vector3,
+    THREE.Vector3,
+    THREE.Vector3,
+    THREE.Vector3,
+    THREE.Vector3,
+    THREE.Vector3,
+    THREE.Vector3,
+  ];
+  const verts: number[] = [];
+  function line(a: THREE.Vector3, b: THREE.Vector3) {
+    verts.push(a.x, a.y, a.z, b.x, b.y, b.z);
+  }
+  line(n0, n1);
+  line(n1, n2);
+  line(n2, n3);
+  line(n3, n0);
+  line(f0, f1);
+  line(f1, f2);
+  line(f2, f3);
+  line(f3, f0);
+  line(n0, f0);
+  line(n1, f1);
+  line(n2, f2);
+  line(n3, f3);
+
+  const geo = new THREE.BufferGeometry();
+  geo.setAttribute('position', new THREE.Float32BufferAttribute(verts, 3));
+  return new THREE.LineSegments(
+    geo,
+    new THREE.LineBasicMaterial({ color: 0xffaa00, depthTest: false }),
+  );
+}
+
+const cameraGizmo: GizmoEntry = {
+  test: (entity) => !!entity.camera,
+
+  createIcon: () => makeIconSprite('📷', 'camera'),
+
+  createHelpers(entity, obj) {
+    // Find existing Three.js camera (editor entities wrap in a Group with a Camera child)
+    let camera: THREE.Camera | null = null;
+    if (obj instanceof THREE.Camera) {
+      camera = obj;
+    } else {
+      obj.traverse((child) => {
+        if (!camera && child instanceof THREE.Camera) camera = child;
+      });
+    }
+
+    // Game scene objects don't have a Three.js Camera — build a temporary one from the entity def
+    if (!camera && entity.camera) {
+      const def = entity.camera;
+      const dCam = DEFAULTS.camera;
+      const aspect = (def.width ?? dCam.width) / (def.height ?? dCam.height);
+      if (def.type === 'orthographic') {
+        const size = def.orthoSize ?? dCam.orthoSize;
+        const ortho = new THREE.OrthographicCamera(
+          -size * aspect,
+          size * aspect,
+          size,
+          -size,
+          def.near ?? dCam.near,
+          def.far ?? dCam.far,
+        );
+        ortho.updateProjectionMatrix();
+        camera = ortho;
+      } else {
+        const persp = new THREE.PerspectiveCamera(
+          def.fov ?? dCam.fov,
+          aspect,
+          def.near ?? dCam.near,
+          def.far ?? dCam.far,
+        );
+        persp.updateProjectionMatrix();
+        camera = persp;
+      }
+    }
+
+    return camera ? [createFrustumHelper(camera)] : [];
+  },
+};
+
+// ---------------------------------------------------------------------------
+// Audio gizmo
+// ---------------------------------------------------------------------------
+
+function createAudioHelper(
+  spatial: boolean,
+  refDistance: number,
+  maxDistance: number,
+): THREE.Object3D {
+  const group = new THREE.Group();
+  const mat = new THREE.LineBasicMaterial({
+    color: 0x44bbff,
+    transparent: true,
+    opacity: 0.6,
+    depthTest: false,
+  });
+
+  // Small speaker cone indicator
+  const speakerVerts: number[] = [];
+  speakerVerts.push(-0.1, -0.15, 0, -0.1, 0.15, 0);
+  speakerVerts.push(-0.1, 0.15, 0, -0.1, -0.15, 0);
+  speakerVerts.push(-0.1, 0.15, 0, 0.2, 0.3, 0);
+  speakerVerts.push(-0.1, -0.15, 0, 0.2, -0.3, 0);
+  speakerVerts.push(0.2, 0.3, 0, 0.2, -0.3, 0);
+  const speakerGeo = new THREE.BufferGeometry();
+  speakerGeo.setAttribute('position', new THREE.Float32BufferAttribute(speakerVerts, 3));
+  group.add(new THREE.LineSegments(speakerGeo, mat));
+
+  if (spatial) {
+    const refMat = new THREE.LineBasicMaterial({
+      color: 0x44bbff,
+      transparent: true,
+      opacity: 0.4,
+      depthTest: false,
+    });
+    const refRing = new THREE.Line(createCircleGeometry(refDistance, 32), refMat);
+    refRing.rotation.x = -Math.PI / 2;
+    group.add(refRing);
+
+    if (maxDistance < 10000) {
+      const maxMat = new THREE.LineBasicMaterial({
+        color: 0x44bbff,
+        transparent: true,
+        opacity: 0.15,
+        depthTest: false,
+      });
+      const maxRing = new THREE.Line(createCircleGeometry(maxDistance, 48), maxMat);
+      maxRing.rotation.x = -Math.PI / 2;
+      group.add(maxRing);
+    }
+  }
+
+  return group;
+}
+
+const audioGizmo: GizmoEntry = {
+  test: (entity) => !!entity.audio,
+
+  createIcon: () => makeIconSprite('🔊', 'audio'),
+
+  createHelpers(entity) {
+    const audioDef = entity.audio!;
+    const spatial = audioDef.spatial !== false;
+    return [
+      createAudioHelper(
+        spatial,
+        audioDef.refDistance ?? DEFAULTS.audio.refDistance,
+        audioDef.maxDistance ?? DEFAULTS.audio.maxDistance,
+      ),
+    ];
+  },
+};
+
+// ---------------------------------------------------------------------------
+// Collider gizmo (no icon — colliders are on mesh entities)
+// ---------------------------------------------------------------------------
+
+/**
+ * Build the collider wireframe from WORLD-SCALED dimensions (T1.2) — the same
+ * numbers the runtime physics loader bakes into the actual Rapier collider
+ * (see `computeColliderWorldDimensions` in `@engine/scene/collider-dimensions`).
+ * `dims` already has the entity's composed world scale (self × ancestors)
+ * applied, so this function itself must NOT apply any further scale.
+ */
+function createColliderHelper(
+  collider: SceneCollider,
+  dims: ColliderWorldDimensions,
+): THREE.Object3D | null {
+  const mat = new THREE.LineBasicMaterial({
+    color: collider.isSensor ? SENSOR_COLOR : COLLIDER_COLOR,
+    transparent: true,
+    opacity: 0.7,
+    depthTest: false,
+  });
+  const group = new THREE.Group();
+
+  switch (collider.type) {
+    case 'cuboid': {
+      const he = dims.halfExtents!;
+      const geo = new THREE.BoxGeometry(he[0] * 2, he[1] * 2, he[2] * 2);
+      group.add(new THREE.LineSegments(new THREE.EdgesGeometry(geo), mat));
+      break;
+    }
+    case 'ball': {
+      const r = dims.radius!;
+      group.add(new THREE.Line(createCircleGeometry(r), mat));
+      const xzRing = new THREE.Line(createCircleGeometry(r), mat);
+      xzRing.rotation.x = -Math.PI / 2;
+      group.add(xzRing);
+      const yzRing = new THREE.Line(createCircleGeometry(r), mat);
+      yzRing.rotation.y = Math.PI / 2;
+      group.add(yzRing);
+      break;
+    }
+    case 'capsule': {
+      const r = dims.radius!;
+      const hh = dims.halfHeight!;
+      const topRing = new THREE.Line(createCircleGeometry(r), mat);
+      topRing.rotation.x = -Math.PI / 2;
+      topRing.position.y = hh;
+      group.add(topRing);
+      const botRing = new THREE.Line(createCircleGeometry(r), mat);
+      botRing.rotation.x = -Math.PI / 2;
+      botRing.position.y = -hh;
+      group.add(botRing);
+      for (const [x, z] of [
+        [r, 0],
+        [-r, 0],
+        [0, r],
+        [0, -r],
+      ] as [number, number][]) {
+        const lineGeo = new THREE.BufferGeometry().setFromPoints([
+          new THREE.Vector3(x, -hh, z),
+          new THREE.Vector3(x, hh, z),
+        ]);
+        group.add(new THREE.Line(lineGeo, mat));
+      }
+      group.add(new THREE.Line(createSemiArcGeometry(r, hh, 'xz', true), mat));
+      group.add(new THREE.Line(createSemiArcGeometry(r, hh, 'yz', true), mat));
+      group.add(new THREE.Line(createSemiArcGeometry(r, -hh, 'xz', false), mat));
+      group.add(new THREE.Line(createSemiArcGeometry(r, -hh, 'yz', false), mat));
+      break;
+    }
+    default:
+      return null;
+  }
+
+  return group.children.length > 0 ? group : null;
+}
+
+const colliderGizmo: GizmoEntry = {
+  test: (entity) => !!entity.physics?.collider,
+  createIcon: () => makeIconSprite('⬡', 'collider'),
+  createHelpers(entity, obj) {
+    const collider = entity.physics?.collider;
+    if (!collider) return [];
+
+    // T1.2: size the wireframe from the entity's composed WORLD scale (self ×
+    // ancestors) via the SAME helper the runtime physics loader uses, so the
+    // gizmo always matches the actual Rapier collider. `obj.updateWorldMatrix`
+    // forces this entity's (and its ancestors') matrixWorld to be current
+    // right now, rather than trusting whatever the last render pass left.
+    obj.updateWorldMatrix(true, false);
+    const worldScaleVec = obj.getWorldScale(new THREE.Vector3());
+    const worldScale: [number, number, number] = [
+      worldScaleVec.x,
+      worldScaleVec.y,
+      worldScaleVec.z,
+    ];
+
+    let dims: ColliderWorldDimensions;
+    try {
+      dims = computeColliderWorldDimensions(collider, worldScale, entity.name);
+    } catch {
+      // Invalid configuration (e.g. non-uniform scale on a round collider) —
+      // this throws a loud load error at Play time. Don't crash the editor
+      // over a config the user hasn't fixed yet; just don't render a
+      // misleading shape.
+      return [];
+    }
+
+    const helper = createColliderHelper(collider, dims);
+    if (!helper) return [];
+
+    // `helper` is added as a CHILD of `obj` below (applyEntityGizmos), so
+    // Three's normal hierarchy would otherwise apply `obj`'s (self + ancestor)
+    // world scale a SECOND time on top of the world-scaled dimensions just
+    // baked into `dims` above. Cancel that inherited scale here so the
+    // dimensions above are the only place scale is applied (avoid
+    // double-scaling).
+    if (worldScaleVec.x !== 0 && worldScaleVec.y !== 0 && worldScaleVec.z !== 0) {
+      helper.scale.set(1 / worldScaleVec.x, 1 / worldScaleVec.y, 1 / worldScaleVec.z);
+    }
+
+    // R1c: render the wireframe at the collider's WORLD-SCALED offset (the
+    // runtime physics loader bakes `offset * worldScale` into the Rapier
+    // collider's translation — see `computeColliderWorldOffset`). `helper` is
+    // a CHILD of `obj` (added below by applyEntityGizmos), so Three's normal
+    // parent-child matrix composition ALREADY multiplies a child's local
+    // `position` by the parent's world scale when computing its world
+    // position — unlike geometry vertices (handled above), a child's own
+    // `position` is untouched by `helper.scale` (that only affects further
+    // descendants' vertices). So setting `helper.position` to the RAW
+    // authored (unscaled) offset already renders at the correct world-scaled
+    // offset; scaling it again here would double-apply worldScale.
+    if (collider.offset) {
+      helper.position.set(collider.offset[0], collider.offset[1], collider.offset[2]);
+    }
+
+    return [helper];
+  },
+};
+
+// ---------------------------------------------------------------------------
+// Spline gizmo
+// ---------------------------------------------------------------------------
+
+function createSplineHelper(spline: SceneSpline): THREE.Object3D {
+  const group = new THREE.Group();
+  if (spline.points.length < 2) return group;
+
+  const points = spline.points.map((p) => new THREE.Vector3(p[0], p[1], p[2]));
+  const curve = new THREE.CatmullRomCurve3(
+    points,
+    spline.closed ?? false,
+    spline.curveType,
+    spline.tension ?? 0.5,
+  );
+  const resolution = spline.resolution ?? 50;
+  const samples = curve.getPoints(resolution);
+
+  const lineGeo = new THREE.BufferGeometry().setFromPoints(samples);
+  const lineMat = new THREE.LineBasicMaterial({
+    color: 0x00ccff,
+    depthTest: false,
+    transparent: true,
+    opacity: 0.8,
+  });
+  const line = new THREE.Line(lineGeo, lineMat);
+  line.renderOrder = 997;
+  group.add(line);
+
+  const dotGeo = new THREE.SphereGeometry(0.06, 8, 8);
+  const dotMat = new THREE.MeshBasicMaterial({
+    color: 0xffaa00,
+    depthTest: false,
+    transparent: true,
+    opacity: 0.9,
+  });
+  for (let i = 0; i < spline.points.length; i++) {
+    const dot = new THREE.Mesh(dotGeo, dotMat);
+    const p = spline.points[i]!;
+    dot.position.set(p[0], p[1], p[2]);
+    dot.renderOrder = 998;
+    setUserData(dot, 'splineControlPoint', i);
+    group.add(dot);
+  }
+
+  return group;
+}
+
+const splineGizmo: GizmoEntry = {
+  test: (entity) => !!entity.spline,
+  createIcon: () => makeIconSprite('〰', 'spline'),
+  createHelpers(entity) {
+    return [createSplineHelper(entity.spline!)];
+  },
+};
+
+// ---------------------------------------------------------------------------
+// Registry
+// ---------------------------------------------------------------------------
+
+const GIZMO_REGISTRY: GizmoEntry[] = [
+  lightGizmo,
+  cameraGizmo,
+  audioGizmo,
+  colliderGizmo,
+  splineGizmo,
+];
+
+/**
+ * Apply all matching gizmos to an entity object.
+ *
+ * Adds clickable icon billboards and non-clickable wireframe helpers.
+ * Idempotent — skips objects that already have gizmo children.
+ */
+export function applyEntityGizmos(obj: THREE.Object3D): void {
+  const entity = getUserData(obj, 'entity') as SceneEntity | undefined;
+  if (!entity) return;
+
+  // Idempotent: skip if gizmos already applied
+  if (obj.children.some((c) => getUserData(c, 'editorHelper') || getUserData(c, 'editorIcon')))
+    return;
+
+  let added = false;
+  for (const entry of GIZMO_REGISTRY) {
+    if (!entry.test(entity, obj)) continue;
+
+    // Icon billboard — clickable, on EDITOR_LAYER
+    const icon = entry.createIcon();
+    obj.add(icon);
+
+    // Helper wireframes — visual only, not clickable
+    const helpers = entry.createHelpers(entity, obj);
+    for (const helper of helpers) {
+      setUserData(helper, 'editorHelper', true);
+      setUserData(
+        helper,
+        'editorHelperType',
+        entry === lightGizmo
+          ? 'lights'
+          : entry === cameraGizmo
+            ? 'cameras'
+            : entry === audioGizmo
+              ? 'audio'
+              : entry === colliderGizmo
+                ? 'colliders'
+                : 'splines',
+      );
+      helper.traverse((child) => child.layers.set(EDITOR_LAYER));
+      obj.add(helper);
+    }
+    added = true;
+  }
+
+  // Force matrix computation so helpers render at the correct position immediately
+  if (added) obj.updateMatrixWorld(true);
+}