castle-web-cli 0.4.129 → 0.4.131

package/kits/physics-3d/engine3d/editorWorld.js

@@ -0,0 +1,249 @@
+// The three.js side of the 3d scene editor: an orbit camera over the same
+// world3d renderer the player uses, raycast picking with click-to-cycle,
+// white selection boxes, and vase-style TransformControls gizmos for move /
+// rotate (multi-select moves as a group). Pure imperative core -- the react
+// chrome in Scene3DEditor.jsx owns file text, selection state, and saving,
+// and talks to this through `ed.callbacks`.
+import * as THREE from 'three';
+import { OrbitControls, TransformControls } from 'three/examples/jsm/Addons.js';
+import { makeWorld3D, resizeWorld, syncActors, renderWorld, disposeWorld } from './world3d';
+import { makeScene } from '@imports/castle.physics-2d/engine/scene';
+
+const CLICK_SLOP_PX = 5;
+
+export function createEditorWorld(canvas, callbacks) {
+  const world = makeWorld3D(canvas);
+  world.camera.position.set(11, 10, 11);
+
+  const orbit = new OrbitControls(world.camera, canvas);
+  orbit.enableDamping = true;
+  orbit.dampingFactor = 0.12;
+  orbit.target.set(0, 0.5, 0);
+
+  const gizmo = new TransformControls(world.camera, canvas);
+  gizmo.setTranslationSnap(0.1);
+  gizmo.setRotationSnap(THREE.MathUtils.degToRad(15));
+  world.scene.add(gizmo.getHelper());
+
+  const ed = {
+    world,
+    orbit,
+    gizmo,
+    canvas,
+    callbacks,
+    runtime: null,
+    sprites: {},
+    mode: 'select',
+    selection: [],
+    boxes: new Map(), // actorId -> THREE.BoxHelper
+    gizmoDragging: false,
+    dragStart: null,
+    raf: 0,
+    lastAppliedText: null,
+  };
+  wireGizmo(ed);
+  wirePointer(ed);
+  startEditorLoop(ed);
+  return ed;
+}
+
+// Swap in fresh scene data (parsed file JSON). The display runtime is never
+// stepped -- actors sit at their authored Transforms; blueprints and default
+// props merge exactly as in play.
+export function setEditorScene(ed, sceneData, behaviors, sprites, files, scenePath) {
+  ed.runtime?.dispose();
+  ed.runtime = makeScene(sceneData, behaviors, sprites, files, scenePath);
+  ed.sprites = sprites;
+}
+
+export function disposeEditorWorld(ed) {
+  cancelAnimationFrame(ed.raf);
+  ed.resizeObserver?.disconnect();
+  for (const entry of ed.boxes.values()) ed.world.scene.remove(entry.helper);
+  ed.boxes.clear();
+  ed.gizmo.detach();
+  ed.gizmo.dispose();
+  ed.orbit.dispose();
+  ed.runtime?.dispose();
+  disposeWorld(ed.world);
+}
+
+// Merged Transform of a selected actor in the display runtime (degrees, live).
+export function editorActorTransform(ed, actorId) {
+  return ed.runtime?.getActor(actorId)?.components?.Transform ?? null;
+}
+
+// Ground-plane (y=0) point under a client-space position, or null when the
+// pointer is off the canvas. Drives hotbar drag-placement and add-clicks.
+export function raycastGroundPoint(ed, clientX, clientY) {
+  const rect = ed.canvas.getBoundingClientRect();
+  if (clientX < rect.left || clientX > rect.right || clientY < rect.top || clientY > rect.bottom) {
+    return null;
+  }
+  const x = ((clientX - rect.left) / rect.width) * 2 - 1;
+  const y = -((clientY - rect.top) / rect.height) * 2 + 1;
+  const raycaster = new THREE.Raycaster();
+  raycaster.setFromCamera(new THREE.Vector2(x, y), ed.world.camera);
+  const point = new THREE.Vector3();
+  const hit = raycaster.ray.intersectPlane(new THREE.Plane(new THREE.Vector3(0, 1, 0), 0), point);
+  return hit ? { x: point.x, z: point.z } : null;
+}
+
+function wireGizmo(ed) {
+  ed.gizmo.addEventListener('dragging-changed', (event) => {
+    if (!event.value) ed.gizmoDraggedUntil = performance.now() + 150;
+    ed.orbit.enabled = !event.value;
+    if (event.value) beginGizmoDrag(ed);
+    else endGizmoDrag(ed);
+  });
+  ed.gizmo.addEventListener('objectChange', () => {
+    if (ed.gizmoDragging) applyGizmoChange(ed);
+  });
+}
+
+function beginGizmoDrag(ed) {
+  ed.gizmoDragging = true;
+  const primaryNode = ed.gizmo.object;
+  const startPositions = new Map();
+  for (const id of ed.selection) {
+    const t = editorActorTransform(ed, id);
+    if (t) startPositions.set(id, { x: t.x, y: t.y, z: t.z });
+  }
+  ed.dragStart = { primary: primaryNode.position.clone(), startPositions };
+}
+
+// The gizmo moves the primary node directly; mirror that into the display
+// runtime's Transforms (position deltas ripple to the rest of the selection in
+// move mode) so the per-frame sync doesn't snap it back.
+function applyGizmoChange(ed) {
+  const primaryId = ed.selection[0];
+  const node = ed.gizmo.object;
+  const t = editorActorTransform(ed, primaryId);
+  if (!node || !t || !ed.dragStart) return;
+  t.x = node.position.x;
+  t.y = node.position.y;
+  t.z = node.position.z;
+  t.rotationX = THREE.MathUtils.radToDeg(node.rotation.x);
+  t.rotationY = THREE.MathUtils.radToDeg(node.rotation.y);
+  t.rotationZ = THREE.MathUtils.radToDeg(node.rotation.z);
+  if (ed.gizmo.mode === 'translate') {
+    const delta = node.position.clone().sub(ed.dragStart.primary);
+    for (const id of ed.selection.slice(1)) {
+      const start = ed.dragStart.startPositions.get(id);
+      const other = editorActorTransform(ed, id);
+      if (!start || !other) continue;
+      other.x = start.x + delta.x;
+      other.y = start.y + delta.y;
+      other.z = start.z + delta.z;
+    }
+  }
+}
+
+function endGizmoDrag(ed) {
+  ed.gizmoDragging = false;
+  ed.dragStart = null;
+  const changes = [];
+  for (const id of ed.selection) {
+    const t = editorActorTransform(ed, id);
+    if (t) changes.push({ id, ...t });
+  }
+  if (changes.length) ed.callbacks.onCommitTransforms(changes);
+}
+
+function wirePointer(ed) {
+  let downAt = null;
+  ed.canvas.addEventListener('pointerdown', (event) => {
+    downAt = { x: event.clientX, y: event.clientY };
+  });
+  ed.canvas.addEventListener('pointerup', (event) => {
+    if (!downAt) return;
+    const travel = Math.hypot(event.clientX - downAt.x, event.clientY - downAt.y);
+    downAt = null;
+    if (travel > CLICK_SLOP_PX || ed.gizmoDragging) return;
+    if (performance.now() < (ed.gizmoDraggedUntil ?? 0)) return;
+    handleClick(ed, event);
+  });
+}
+
+function rayFromEvent(ed, event) {
+  const rect = ed.canvas.getBoundingClientRect();
+  const x = ((event.clientX - rect.left) / rect.width) * 2 - 1;
+  const y = -((event.clientY - rect.top) / rect.height) * 2 + 1;
+  const raycaster = new THREE.Raycaster();
+  raycaster.setFromCamera(new THREE.Vector2(x, y), ed.world.camera);
+  return raycaster;
+}
+
+function handleClick(ed, event) {
+  const raycaster = rayFromEvent(ed, event);
+  if (ed.mode === 'add') {
+    const point = new THREE.Vector3();
+    raycaster.ray.intersectPlane(new THREE.Plane(new THREE.Vector3(0, 1, 0), 0), point);
+    if (point) ed.callbacks.onAddAt({ x: point.x, z: point.z });
+    return;
+  }
+  const nodes = [...ed.world.nodes.values()].map((entry) => entry.node);
+  const intersects = raycaster.intersectObjects(nodes, true);
+  const hits = [];
+  for (const intersect of intersects) {
+    let object = intersect.object;
+    while (object && object.userData.actorId === undefined) object = object.parent;
+    const actorId = object?.userData.actorId;
+    if (actorId !== undefined && !hits.includes(actorId)) hits.push(actorId);
+  }
+  ed.callbacks.onPick(hits, event.shiftKey);
+}
+
+function syncSelectionBoxes(ed) {
+  for (const [id, entry] of ed.boxes) {
+    // Drop a box when its actor is deselected/gone OR its node was rebuilt
+    // (art or shape changed) -- a helper bound to a dead node freezes at the
+    // node's last position instead of following the actor.
+    const nodeEntry = ed.world.nodes.get(id);
+    if (ed.selection.includes(id) && nodeEntry && nodeEntry.node === entry.node) continue;
+    ed.world.scene.remove(entry.helper);
+    entry.helper.dispose();
+    ed.boxes.delete(id);
+  }
+  for (const id of ed.selection) {
+    const nodeEntry = ed.world.nodes.get(id);
+    if (!nodeEntry) continue;
+    let entry = ed.boxes.get(id);
+    if (!entry) {
+      entry = { helper: new THREE.BoxHelper(nodeEntry.node, 0xffffff), node: nodeEntry.node };
+      ed.world.scene.add(entry.helper);
+      ed.boxes.set(id, entry);
+    }
+    entry.helper.update();
+  }
+}
+
+// Keep the gizmo attached to the primary selection whenever a transform mode
+// is active, and detached otherwise.
+function syncGizmo(ed) {
+  const primary = ed.selection[0];
+  const node = primary !== undefined ? ed.world.nodes.get(primary)?.node : null;
+  const wantGizmo = node && (ed.mode === 'move' || ed.mode === 'rotate');
+  if (wantGizmo) {
+    ed.gizmo.mode = ed.mode === 'move' ? 'translate' : 'rotate';
+    if (ed.gizmo.object !== node) ed.gizmo.attach(node);
+  } else if (ed.gizmo.object) {
+    ed.gizmo.detach();
+  }
+}
+
+function startEditorLoop(ed) {
+  const fit = () => resizeWorld(ed.world, ed.canvas.clientWidth, ed.canvas.clientHeight);
+  ed.resizeObserver = new ResizeObserver(fit);
+  ed.resizeObserver.observe(ed.canvas);
+  fit();
+  const tick = () => {
+    ed.orbit.update();
+    if (ed.runtime) syncActors(ed.world, ed.runtime, ed.sprites);
+    syncGizmo(ed);
+    syncSelectionBoxes(ed);
+    renderWorld(ed.world);
+    ed.raf = requestAnimationFrame(tick);
+  };
+  ed.raf = requestAnimationFrame(tick);
+}

package/kits/physics-3d/engine3d/materials.js

@@ -0,0 +1,174 @@
+// Mesh + material construction from a Shape component. Materials are
+// MeshPhysicalMaterial throughout (the vase look): PBR with a small set of
+// knobs, albedo optionally baked from a `.pxart` (or uploaded image) with
+// nearest filtering so pixels stay crisp.
+//
+// `Shape.art` is either one ref for the whole shape, or (boxes only) a per-face
+// object: `{ all, sides, front, back, left, right, top, bottom }`. A ref is a
+// file path with an optional `#<frame>` suffix to pick a frame of a multi-frame
+// pxart -- so one file can carry different faces as frames.
+import * as THREE from 'three';
+import { renderArtFrame, artReady, artFrameCount } from '@imports/castle.physics-2d/engine/art';
+
+// Baked textures cached per art object per frame (sprites are re-parsed only
+// when the file changes, so object identity is a good key).
+const textureCache = new WeakMap();
+
+function albedoTexture(art, frame) {
+  if (!art || !artReady(art)) return null;
+  const frameIndex = Math.max(0, Math.min(frame ?? 0, artFrameCount(art) - 1));
+  let byFrame = textureCache.get(art);
+  if (!byFrame) {
+    byFrame = new Map();
+    textureCache.set(art, byFrame);
+  }
+  const cached = byFrame.get(frameIndex);
+  if (cached) return cached;
+  const canvas = document.createElement('canvas');
+  if (!renderArtFrame(art, frameIndex, canvas)) return null;
+  const texture = new THREE.CanvasTexture(canvas);
+  texture.colorSpace = THREE.SRGBColorSpace;
+  texture.magFilter = THREE.NearestFilter;
+  texture.minFilter = THREE.NearestFilter;
+  texture.generateMipmaps = false;
+  byFrame.set(frameIndex, texture);
+  return texture;
+}
+
+// 'drawings/door.pxart#1' -> { path, frame }
+function parseArtRef(ref) {
+  const hash = ref.lastIndexOf('#');
+  if (hash === -1) return { path: ref, frame: 0 };
+  const frame = Number(ref.slice(hash + 1));
+  if (!Number.isInteger(frame) || frame < 0) return { path: ref, frame: 0 };
+  return { path: ref.slice(0, hash), frame };
+}
+
+export function resolveArtTexture(ref, sprites, repeat) {
+  if (!ref || typeof ref !== 'string') return null;
+  const { path, frame } = parseArtRef(ref);
+  const texture = albedoTexture(sprites?.[path], frame);
+  if (!texture || !repeat) return texture;
+  // Tiling wants its own texture instance -- the cached one is shared by
+  // non-repeating users. clone() shares the underlying image.
+  const tiled = texture.clone();
+  tiled.wrapS = THREE.RepeatWrapping;
+  tiled.wrapT = THREE.RepeatWrapping;
+  tiled.repeat.set(repeat[0] ?? 1, repeat[1] ?? 1);
+  tiled.needsUpdate = true;
+  return tiled;
+}
+
+function artRefsOf(shape) {
+  if (!shape?.art) return [];
+  if (typeof shape.art === 'string') return [shape.art];
+  return Object.values(shape.art).filter((ref) => typeof ref === 'string');
+}
+
+// Stable id per parsed art OBJECT. A repainted pxart re-parses into a fresh
+// object, so identity (not just readiness) has to be part of a signature --
+// otherwise an edited texture never reaches an already-built mesh.
+let artIdCounter = 0;
+const artIds = new WeakMap();
+export function artRefSignature(ref, sprites) {
+  const art = sprites?.[parseArtRef(typeof ref === 'string' ? ref : '').path];
+  if (!art) return '0';
+  let id = artIds.get(art);
+  if (!id) {
+    id = ++artIdCounter;
+    artIds.set(art, id);
+  }
+  return `${id}:${artReady(art)}`;
+}
+
+// What about a Shape (plus the art files it references) requires a mesh
+// rebuild. Cheap to compute every frame; rebuilds only happen when it changes.
+export function shapeSignature(shape, sprites) {
+  if (!shape) return 'none';
+  const arts = artRefsOf(shape).map((ref) => artRefSignature(ref, sprites));
+  return JSON.stringify([shape, arts]);
+}
+
+// Everything that decides what an actor's node LOOKS like: the Shape, plus a
+// Model (which replaces the shape mesh with a .pxmodel rig) -- including the
+// model file's text and the readiness of any art it references. The model
+// pieces are supplied by the caller (world3d) to keep this module below the
+// model format.
+export function nodeSignature(actor, sprites, modelSig = '') {
+  const model = actor.components.Model;
+  return `${shapeSignature(actor.components.Shape, sprites)}|${JSON.stringify(model ?? null)}|${modelSig}`;
+}
+
+function shapeGeometry(shape) {
+  if (shape.kind === 'sphere') return new THREE.SphereGeometry(shape.radius, 24, 16);
+  if (shape.kind === 'capsule') {
+    const mid = Math.max(0, shape.height - 2 * shape.radius);
+    return new THREE.CapsuleGeometry(shape.radius, mid, 8, 16);
+  }
+  if (shape.kind === 'cylinder') {
+    return new THREE.CylinderGeometry(shape.radius, shape.radius, shape.height, 24);
+  }
+  return new THREE.BoxGeometry(shape.width, shape.height, shape.depth);
+}
+
+export function makeMaterial(shape, map) {
+  // A textured face keeps its art's colors; `tint` multiplies over it when
+  // set. Untextured faces (and shapes) are just `color`. Every field falls
+  // back explicitly -- a raw blueprint template has no defaultProps merge, and
+  // `new THREE.Color(undefined)` is WHITE, which once turned every textured
+  // thumbnail into a white-emissive blob.
+  const color = map ? shape.tint || '#ffffff' : (shape.color ?? '#c7cfdd');
+  return new THREE.MeshPhysicalMaterial({
+    color: new THREE.Color(color),
+    map: map ?? null,
+    roughness: shape.roughness ?? 0.7,
+    metalness: shape.metalness ?? 0,
+    clearcoat: shape.clearcoat ?? 0,
+    emissive: new THREE.Color(shape.emissive ?? '#000000'),
+    emissiveIntensity: shape.emissiveIntensity ?? 1,
+  });
+}
+
+// Three's box material order: +x right, -x left, +y top, -y bottom, +z front,
+// -z back. Unnamed faces fall back to `sides` (left/right/back), then `all`,
+// then plain color. `back` deliberately does NOT mirror `front` -- a face
+// texture on a head must not appear on the back of the head; a door that
+// looks the same from both sides just names `back` explicitly.
+function boxFaceMaterials(shape, art, sprites) {
+  const all = art.all;
+  const sides = art.sides ?? all;
+  const refs = [
+    art.right ?? sides,
+    art.left ?? sides,
+    art.top ?? all,
+    art.bottom ?? art.top ?? all,
+    art.front ?? all,
+    art.back ?? sides,
+  ];
+  return refs.map((ref) => makeMaterial(shape, resolveArtTexture(ref, sprites, shape.artRepeat)));
+}
+
+export function makeShapeMesh(shape, sprites) {
+  const art = shape.art;
+  let material;
+  if (art && typeof art === 'object' && shape.kind === 'box') {
+    material = boxFaceMaterials(shape, art, sprites);
+  } else {
+    material = makeMaterial(shape, resolveArtTexture(art, sprites, shape.artRepeat));
+  }
+  const mesh = new THREE.Mesh(shapeGeometry(shape), material);
+  mesh.castShadow = true;
+  mesh.receiveShadow = true;
+  return mesh;
+}
+
+export function disposeNode(node) {
+  node.traverse((child) => {
+    if (child.isMesh) {
+      child.geometry?.dispose();
+      // Textures stay cached (shared across meshes); only the material goes.
+      if (Array.isArray(child.material)) child.material.forEach((m) => m.dispose());
+      else child.material?.dispose();
+    }
+  });
+}

package/kits/physics-3d/engine3d/meshops.js

@@ -0,0 +1,123 @@
+// Pure operations on `kind: "mesh"` pxmodel parts -- an editable polygon mesh
+// (vertices + quad-dominant faces, indices CCW-outward), the flexible core of
+// the model format. Inspired by real modeling workflows (adjacency-aware
+// editing, face extrusion); all code here is original. Faces may be tris,
+// quads, or n-gons; rendering fan-triangulates with flat normals.
+import * as THREE from 'three';
+
+// A unit-ish editable mesh from a box part's size -- the "convert to mesh"
+// seed. 8 vertices, 6 quads, outward CCW winding.
+export function boxMesh(size) {
+  const [w, h, d] = size;
+  const x = w / 2;
+  const y = h / 2;
+  const z = d / 2;
+  const vertices = [
+    [-x, -y, -z],
+    [x, -y, -z],
+    [x, y, -z],
+    [-x, y, -z],
+    [-x, -y, z],
+    [x, -y, z],
+    [x, y, z],
+    [-x, y, z],
+  ];
+  const faces = [
+    [3, 2, 1, 0], // -z back
+    [4, 5, 6, 7], // +z front
+    [1, 2, 6, 5], // +x
+    [0, 4, 7, 3], // -x
+    [3, 7, 6, 2], // +y
+    [0, 1, 5, 4], // -y
+  ];
+  return { vertices, faces };
+}
+
+export function faceCentroid(part, face) {
+  const c = [0, 0, 0];
+  for (const index of face) {
+    const v = part.vertices[index];
+    c[0] += v[0];
+    c[1] += v[1];
+    c[2] += v[2];
+  }
+  return c.map((value) => value / face.length);
+}
+
+export function faceNormal(part, face) {
+  const a = part.vertices[face[0]];
+  const b = part.vertices[face[1]];
+  const c = part.vertices[face[2]];
+  const ab = [b[0] - a[0], b[1] - a[1], b[2] - a[2]];
+  const ac = [c[0] - a[0], c[1] - a[1], c[2] - a[2]];
+  const n = [
+    ab[1] * ac[2] - ab[2] * ac[1],
+    ab[2] * ac[0] - ab[0] * ac[2],
+    ab[0] * ac[1] - ab[1] * ac[0],
+  ];
+  const len = Math.hypot(n[0], n[1], n[2]) || 1;
+  return [n[0] / len, n[1] / len, n[2] / len];
+}
+
+// Extrude one face outward along its normal: the face's vertices are
+// duplicated and pushed out, the face re-points at the duplicates, and a side
+// quad is stitched along each original edge. Adjacent selected faces extrude
+// independently (region extrusion is a planned refinement).
+export function extrudeFace(part, faceIndex, distance) {
+  const face = part.faces[faceIndex];
+  if (!face) return null;
+  const normal = faceNormal(part, face);
+  const start = part.vertices.length;
+  const lifted = face.map((index, i) => {
+    const v = part.vertices[index];
+    part.vertices.push([
+      round3(v[0] + normal[0] * distance),
+      round3(v[1] + normal[1] * distance),
+      round3(v[2] + normal[2] * distance),
+    ]);
+    return start + i;
+  });
+  for (let i = 0; i < face.length; i++) {
+    const j = (i + 1) % face.length;
+    part.faces.push([face[i], face[j], lifted[j], lifted[i]]);
+  }
+  part.faces[faceIndex] = lifted;
+  return part.faces.length ? faceIndex : null;
+}
+
+const round3 = (v) => Math.round(v * 1000) / 1000;
+
+export function roundMeshInPlace(part) {
+  part.vertices = part.vertices.map((v) => v.map(round3));
+}
+
+// Fan-triangulated flat-shaded geometry, plus a map from render triangle
+// index back to the owning face (for raycast picking in the editor).
+export function buildMeshGeometry(part) {
+  const positions = [];
+  const triFaces = [];
+  for (let faceIndex = 0; faceIndex < part.faces.length; faceIndex++) {
+    const face = part.faces[faceIndex];
+    if (!face || face.length < 3) continue;
+    for (let i = 1; i + 1 < face.length; i++) {
+      for (const index of [face[0], face[i], face[i + 1]]) {
+        const v = part.vertices[index] ?? [0, 0, 0];
+        positions.push(v[0], v[1], v[2]);
+      }
+      triFaces.push(faceIndex);
+    }
+  }
+  const geometry = new THREE.BufferGeometry();
+  geometry.setAttribute('position', new THREE.Float32BufferAttribute(positions, 3));
+  geometry.computeVertexNormals();
+  return { geometry, triFaces };
+}
+
+// All vertex indices used by a set of faces.
+export function faceVertexIndices(part, faceIndices) {
+  const out = new Set();
+  for (const faceIndex of faceIndices) {
+    for (const index of part.faces[faceIndex] ?? []) out.add(index);
+  }
+  return [...out];
+}