castle-web-cli 0.4.11 → 0.4.12

package/kits/basic-3d/engine/scene.js

@@ -0,0 +1,502 @@
+import * as THREE from 'three';
+import { applyLightingSettings, createSceneLights, disposeObject3D } from './threeUtil';
+
+// UI overlay design space (see SceneUI) -- world units are separate and
+// unbounded; the ground plane is XZ with +Y up.
+const CARD_WIDTH = 500;
+const CARD_HEIGHT = 700;
+
+export const cardSize = { width: CARD_WIDTH, height: CARD_HEIGHT };
+
+// View used when no Camera behavior runs (and for a scene's first frame).
+export const defaultCameraSpec = {
+  targetX: 0,
+  targetY: 0,
+  targetZ: 0,
+  azimuth: 45,
+  elevation: 35,
+  distance: 24,
+  fov: 50,
+};
+
+// The view a scene's own Camera behavior would start play with -- the editor
+// initializes its edit camera from this so edit and play share a vibe. Null
+// when the scene has no Camera actor.
+export function sceneCameraSpec(sceneData) {
+  for (const actor of sceneData?.actors ?? []) {
+    const camera = actor.components?.Camera;
+    if (!camera) continue;
+    const target = camera.target
+      ? (sceneData.actors ?? []).find((candidate) => candidate.id === camera.target)
+      : null;
+    const transform = target?.components?.Transform;
+    return {
+      targetX: transform?.x ?? 0,
+      targetY: (transform?.y ?? 0) + (camera.lookHeight ?? 0),
+      targetZ: transform?.z ?? 0,
+      azimuth: camera.azimuth ?? defaultCameraSpec.azimuth,
+      elevation: camera.elevation ?? defaultCameraSpec.elevation,
+      distance: camera.distance ?? defaultCameraSpec.distance,
+      fov: camera.fov ?? defaultCameraSpec.fov,
+    };
+  }
+  return null;
+}
+
+const raycaster = new THREE.Raycaster();
+const groundPlane = new THREE.Plane(new THREE.Vector3(0, 1, 0), 0);
+
+export class SceneRuntime {
+  constructor(sceneData, behaviors, models) {
+    this.behaviors = new Map(behaviors.map((Behavior) => [Behavior.behaviorName, Behavior]));
+    this.models = models;
+    this.time = 0;
+    this.keys = new Set();
+    this.pointer = { x: 0, y: 0, down: false, ground: null };
+    this.data = { actors: [] };
+    this.actors = new Map();
+    this.camera = undefined;
+    this.status = undefined;
+    // Three-side state. `three` is the retained scene graph; behaviors attach
+    // objects under their actor's group (see `actorGroup`).
+    this.three = new THREE.Scene();
+    this.actorGroups = new Map();
+    this.lights = createSceneLights();
+    this.three.add(this.lights.group);
+    this.grid = new THREE.GridHelper(100, 100, 0x666666, 0x333333);
+    this.grid.visible = false;
+    this.three.add(this.grid);
+    this.selectionBoxes = new Map();
+    this.placeholders = new Map();
+    // Set by the active viewport every frame; used for pointer raycasts.
+    this.activeCamera = null;
+    this.load(sceneData);
+  }
+
+  load(sceneData) {
+    const next = structuredClone(sceneData);
+    const nextIds = new Set((next.actors ?? []).map((actor) => actor.id));
+    // Reconcile instead of rebuild: keep groups + `runtime` caches for actors
+    // that survive so per-frame mesh caches don't churn on every edit.
+    for (const [id] of this.actors) {
+      if (!nextIds.has(id)) this.removeActorGroup(id);
+    }
+    const previousActors = this.actors;
+    this.data = next;
+    this.actors = new Map();
+    for (const actor of this.data.actors ?? []) {
+      const previous = previousActors.get(actor.id);
+      actor.runtime = previous?.runtime ?? {};
+      this.actors.set(actor.id, actor);
+      for (const [behaviorName, Behavior] of this.behaviors) {
+        const component = actor.components[behaviorName];
+        if (component) {
+          actor.components[behaviorName] = {
+            ...Behavior.defaultProps,
+            ...component,
+          };
+        }
+      }
+      this.ensureActorGroup(actor.id);
+    }
+  }
+
+  dispose() {
+    for (const id of [...this.actorGroups.keys()]) this.removeActorGroup(id);
+    for (const [id] of this.selectionBoxes) this.removeSelectionBox(id);
+    disposeObject3D(this.grid);
+    disposeObject3D(this.lights.group);
+  }
+
+  ensureActorGroup(actorId) {
+    let group = this.actorGroups.get(actorId);
+    if (!group) {
+      group = new THREE.Group();
+      group.userData.actorId = actorId;
+      this.actorGroups.set(actorId, group);
+      this.three.add(group);
+    }
+    return group;
+  }
+
+  removeActorGroup(actorId) {
+    const group = this.actorGroups.get(actorId);
+    if (!group) return;
+    this.three.remove(group);
+    disposeObject3D(group);
+    this.actorGroups.delete(actorId);
+    this.removeSelectionBox(actorId);
+    this.removePlaceholder(actorId);
+  }
+
+  // The actor's retained THREE.Group. Behaviors attach their objects here
+  // from `sync` and cache them on `actor.runtime`.
+  actorGroup(actorOrId) {
+    const id = typeof actorOrId === 'string' ? actorOrId : actorOrId?.id;
+    if (id == null || !this.actors.has(id)) return null;
+    return this.ensureActorGroup(id);
+  }
+
+  clone() {
+    return new SceneRuntime(this.serialize(), [...this.behaviors.values()], this.models);
+  }
+
+  serialize() {
+    const data = structuredClone(this.data);
+    for (const actor of data.actors ?? []) delete actor.runtime;
+    return data;
+  }
+
+  getActor(actorId) {
+    return this.actors.get(actorId);
+  }
+
+  getActors() {
+    return [...this.actors.values()];
+  }
+
+  getComponent(actor, behaviorName) {
+    return actor?.components?.[behaviorName] ?? null;
+  }
+
+  actorWith(behaviorName) {
+    for (const actor of this.actors.values()) {
+      if (actor.components?.[behaviorName]) return actor;
+    }
+    return null;
+  }
+
+  actorsWith(behaviorName) {
+    const out = [];
+    for (const actor of this.getActors()) {
+      if (actor.components?.[behaviorName]) out.push(actor);
+    }
+    return out;
+  }
+
+  // Center-based axis-aligned box from Transform + Collider, or null.
+  colliderBox(actorOrId) {
+    const actor = typeof actorOrId === 'string' ? this.getActor(actorOrId) : actorOrId;
+    return getColliderBox(actor);
+  }
+
+  overlaps(first, second) {
+    const a = this.colliderBox(first);
+    const b = this.colliderBox(second);
+    return Boolean(a && b && intersectsBox(a, b));
+  }
+
+  spawnActor(actor) {
+    const id = actor.id ?? mintActorId(new Set(this.actors.keys()));
+    const components = {};
+    for (const [name, props] of Object.entries(actor.components ?? {})) {
+      const Behavior = this.behaviors.get(name);
+      components[name] = Behavior ? { ...Behavior.defaultProps, ...props } : { ...props };
+    }
+    const next = { ...actor, id, components, runtime: {} };
+    this.data.actors.push(next);
+    this.actors.set(id, next);
+    this.ensureActorGroup(id);
+    return next;
+  }
+
+  despawnActor(actorId) {
+    const actor = this.actors.get(actorId);
+    if (!actor) return false;
+    this.actors.delete(actorId);
+    const idx = this.data.actors.findIndex((a) => a.id === actorId);
+    if (idx !== -1) this.data.actors.splice(idx, 1);
+    this.removeActorGroup(actorId);
+    return true;
+  }
+
+  // Translate a screen-space pointer event into the scene's `pointer`. `x`/`y`
+  // are normalized device coordinates (-1..1); `ground` is the pointer ray's
+  // hit on the y=0 plane in world units (null when looking away from it).
+  // Behaviors read `scene.pointer` -- the runtime owns this mapping so the
+  // standalone player and the editor's play mode agree on it.
+  setPointerFromScreen(canvas, clientX, clientY, down) {
+    const rect = canvas.getBoundingClientRect();
+    this.pointer.x = ((clientX - rect.left) / rect.width) * 2 - 1;
+    this.pointer.y = -(((clientY - rect.top) / rect.height) * 2 - 1);
+    this.pointer.ground = this.raycastGround(this.pointer.x, this.pointer.y);
+    if (down !== undefined) this.pointer.down = down;
+  }
+
+  raycastGround(ndcX, ndcY) {
+    if (!this.activeCamera) return null;
+    raycaster.setFromCamera({ x: ndcX, y: ndcY }, this.activeCamera);
+    const hit = new THREE.Vector3();
+    if (!raycaster.ray.intersectPlane(groundPlane, hit)) return null;
+    return { x: hit.x, z: hit.z };
+  }
+
+  update(dt) {
+    this.time += dt;
+    for (const actor of this.getActors()) {
+      this.forEachBehavior(actor, (instance) => instance.update?.(actor, this, dt));
+    }
+  }
+
+  forEachBehavior(actor, callback) {
+    for (const [behaviorName, props] of Object.entries(actor.components)) {
+      if (!props) continue;
+      const Behavior = this.behaviors.get(behaviorName);
+      if (!Behavior) continue;
+      callback(new Behavior(props));
+    }
+  }
+
+  // Per-frame scene-graph sync -- the retained-mode analog of the 2d kit's
+  // `draw`. Runs every behavior's `sync`, then editor overlays.
+  syncFrame(dt = 0, options = {}) {
+    this.three.background = new THREE.Color(this.data.background ?? '#10131c');
+    applyLightingSettings(this.lights, this.data.lighting);
+    this.grid.visible = !!options.showGrid;
+    for (const actor of this.getActors()) {
+      this.forEachBehavior(actor, (instance) => instance.sync?.(actor, this, dt, options));
+    }
+    this.syncPlaceholders(options.editPlaceholders);
+    this.syncSelectionBoxes(options.selectedActorIds ?? []);
+  }
+
+  // Faint wireframe boxes standing in for actors with nothing visible, edit
+  // mode only -- so empty/logic actors stay selectable.
+  syncPlaceholders(enabled) {
+    const needed = new Set();
+    if (enabled) {
+      for (const actor of this.getActors()) {
+        const group = this.actorGroups.get(actor.id);
+        const transform = actor.components.Transform;
+        if (!group || !transform) continue;
+        if (group.children.some((child) => !child.userData.editorPlaceholder)) continue;
+        needed.add(actor.id);
+        let placeholder = this.placeholders.get(actor.id);
+        if (!placeholder) {
+          placeholder = makePlaceholderBox();
+          this.placeholders.set(actor.id, placeholder);
+          group.add(placeholder);
+        }
+      }
+    }
+    for (const [id] of this.placeholders) {
+      if (!needed.has(id)) this.removePlaceholder(id);
+    }
+  }
+
+  removePlaceholder(actorId) {
+    const placeholder = this.placeholders.get(actorId);
+    if (!placeholder) return;
+    placeholder.parent?.remove(placeholder);
+    disposeObject3D(placeholder);
+    this.placeholders.delete(actorId);
+  }
+
+  syncSelectionBoxes(selectedActorIds) {
+    const selected = new Set(selectedActorIds);
+    for (const [id] of this.selectionBoxes) {
+      if (!selected.has(id)) this.removeSelectionBox(id);
+    }
+    for (const id of selected) {
+      const group = this.actorGroups.get(id);
+      if (!group) continue;
+      let box = this.selectionBoxes.get(id);
+      if (!box) {
+        box = new THREE.BoxHelper(group, 0xffffff);
+        box.userData.editorOverlay = true;
+        this.selectionBoxes.set(id, box);
+        this.three.add(box);
+      }
+      box.setFromObject(group);
+    }
+  }
+
+  removeSelectionBox(actorId) {
+    const box = this.selectionBoxes.get(actorId);
+    if (!box) return;
+    this.three.remove(box);
+    disposeObject3D(box);
+    this.selectionBoxes.delete(actorId);
+  }
+
+  // Topmost actor under a screen point, by raycast. Used for edit-mode
+  // selection -- the 3d analog of the 2d kit's `actorAt`.
+  actorAtScreen(canvas, clientX, clientY) {
+    if (!this.activeCamera) return null;
+    const rect = canvas.getBoundingClientRect();
+    const ndcX = ((clientX - rect.left) / rect.width) * 2 - 1;
+    const ndcY = -(((clientY - rect.top) / rect.height) * 2 - 1);
+    raycaster.setFromCamera({ x: ndcX, y: ndcY }, this.activeCamera);
+    const groups = [...this.actorGroups.values()];
+    const hits = raycaster.intersectObjects(groups, true);
+    for (const hit of hits) {
+      let object = hit.object;
+      while (object && object.userData.actorId == null) object = object.parent;
+      if (object) return this.getActor(object.userData.actorId) ?? null;
+    }
+    return null;
+  }
+
+  // Actors whose projected bounding box overlaps a screen-space rect (rect in
+  // canvas client pixels). Used for marquee selection.
+  actorIdsInScreenRect(canvas, rect) {
+    if (!this.activeCamera) return [];
+    const canvasRect = canvas.getBoundingClientRect();
+    const ids = [];
+    const box = new THREE.Box3();
+    const corner = new THREE.Vector3();
+    for (const [id, group] of this.actorGroups) {
+      box.setFromObject(group);
+      if (box.isEmpty()) continue;
+      let minX = Infinity;
+      let minY = Infinity;
+      let maxX = -Infinity;
+      let maxY = -Infinity;
+      for (let i = 0; i < 8; i++) {
+        corner.set(
+          i & 1 ? box.max.x : box.min.x,
+          i & 2 ? box.max.y : box.min.y,
+          i & 4 ? box.max.z : box.min.z
+        );
+        corner.project(this.activeCamera);
+        const sx = ((corner.x + 1) / 2) * canvasRect.width;
+        const sy = ((1 - corner.y) / 2) * canvasRect.height;
+        minX = Math.min(minX, sx);
+        minY = Math.min(minY, sy);
+        maxX = Math.max(maxX, sx);
+        maxY = Math.max(maxY, sy);
+      }
+      const overlapsRect =
+        maxX >= rect.x &&
+        minX <= rect.x + rect.width &&
+        maxY >= rect.y &&
+        minY <= rect.y + rect.height;
+      if (overlapsRect) ids.push(id);
+    }
+    return ids;
+  }
+}
+
+export function makeScene(sceneData, behaviors, models) {
+  return new SceneRuntime(sceneData, behaviors, models);
+}
+
+function makePlaceholderBox() {
+  const geometry = new THREE.BoxGeometry(1, 1, 1);
+  const edges = new THREE.EdgesGeometry(geometry);
+  geometry.dispose();
+  const material = new THREE.LineBasicMaterial({
+    color: 0xffffff,
+    transparent: true,
+    opacity: 0.3,
+  });
+  const lines = new THREE.LineSegments(edges, material);
+  lines.userData.editorPlaceholder = true;
+  return lines;
+}
+
+export function setActorComponent(sceneData, actorId, behaviorName, nextProps) {
+  const next = structuredClone(sceneData);
+  const actor = next.actors.find((candidate) => candidate.id === actorId);
+  if (!actor) return sceneData;
+  actor.components[behaviorName] = {
+    ...(actor.components[behaviorName] ?? {}),
+    ...nextProps,
+  };
+  return next;
+}
+
+export function removeActorComponent(sceneData, actorId, behaviorName) {
+  const next = structuredClone(sceneData);
+  const actor = next.actors.find((candidate) => candidate.id === actorId);
+  if (!actor || !(behaviorName in actor.components)) return sceneData;
+  delete actor.components[behaviorName];
+  return next;
+}
+
+export function removeActors(sceneData, actorIds) {
+  if (actorIds.length === 0) return sceneData;
+  const toRemove = new Set(actorIds);
+  const next = structuredClone(sceneData);
+  next.actors = next.actors.filter((actor) => !toRemove.has(actor.id));
+  return next.actors.length === sceneData.actors.length ? sceneData : next;
+}
+
+export function duplicateActors(sceneData, actorIds) {
+  if (actorIds.length === 0) return { sceneData, newIds: [] };
+  const next = structuredClone(sceneData);
+  const existingIds = new Set(next.actors.map((actor) => actor.id));
+  const newIds = [];
+  for (const id of actorIds) {
+    const source = next.actors.find((candidate) => candidate.id === id);
+    if (!source) continue;
+    const copy = structuredClone(source);
+    delete copy.runtime;
+    copy.id = mintActorId(existingIds);
+    existingIds.add(copy.id);
+    const transform = copy.components.Transform;
+    if (transform) {
+      copy.components.Transform = {
+        ...transform,
+        x: roundUnits((transform.x ?? 0) + 1),
+        z: roundUnits((transform.z ?? 0) + 1),
+      };
+    }
+    next.actors.push(copy);
+    newIds.push(copy.id);
+  }
+  return { sceneData: next, newIds };
+}
+
+export function addActor(sceneData, _files, models) {
+  const next = structuredClone(sceneData);
+  const existingIds = new Set(next.actors.map((actor) => actor.id));
+  const id = mintActorId(existingIds);
+  const components = {
+    Transform: { x: 0, y: 0.5, z: 0, rotationX: 0, rotationY: 0, rotationZ: 0 },
+  };
+  const modelPath = Object.keys(models ?? {}).sort()[0];
+  if (modelPath) {
+    components.Model = { file: modelPath };
+  }
+  next.actors.push({ id, components });
+  return { sceneData: next, newId: id };
+}
+
+function mintActorId(existing) {
+  for (let attempt = 0; attempt < 64; attempt++) {
+    const candidate = Math.floor(Math.random() * 0xffffffff)
+      .toString(16)
+      .padStart(8, '0');
+    if (!existing.has(candidate)) return candidate;
+  }
+  return `${Date.now().toString(16)}${Math.floor(Math.random() * 0xffff).toString(16)}`;
+}
+
+// World-unit rounding for editor writes -- two decimals keeps scene JSON
+// readable without visible snapping.
+export function roundUnits(value) {
+  return Math.round(value * 100) / 100;
+}
+
+function getColliderBox(actor) {
+  const transform = actor?.components?.Transform;
+  const collider = actor?.components?.Collider;
+  if (!transform || !collider) return null;
+  return {
+    x: (transform.x ?? 0) + (collider.offsetX ?? 0),
+    y: (transform.y ?? 0) + (collider.offsetY ?? 0),
+    z: (transform.z ?? 0) + (collider.offsetZ ?? 0),
+    width: collider.width ?? 1,
+    height: collider.height ?? 1,
+    depth: collider.depth ?? 1,
+  };
+}
+
+function intersectsBox(a, b) {
+  return (
+    Math.abs(a.x - b.x) * 2 < a.width + b.width &&
+    Math.abs(a.y - b.y) * 2 < a.height + b.height &&
+    Math.abs(a.z - b.z) * 2 < a.depth + b.depth
+  );
+}