castle-web-cli 0.4.129 → 0.4.130

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

@@ -0,0 +1,439 @@
+// The three.js side of the .pxmodel editor: one model on the world3d stage,
+// orbit camera, part picking, a selection box on the picked part, and
+// move/rotate gizmos that write back part-local placement. The react chrome
+// (PxModelEditor.jsx) owns the file text, part list, and saving.
+import * as THREE from 'three';
+import { OrbitControls, TransformControls } from 'three/examples/jsm/Addons.js';
+import { makeWorld3D, resizeWorld, renderWorld, disposeWorld } from './world3d';
+import { buildModelNode } from './pxmodel';
+import { buildMeshGeometry, faceVertexIndices } from './meshops';
+import { disposeNode } from './materials';
+
+const CLICK_SLOP = 5;
+
+export function createModelEditorWorld(canvas, callbacks) {
+  const world = makeWorld3D(canvas);
+  world.camera.position.set(3, 2.4, 3);
+  const orbit = new OrbitControls(world.camera, canvas);
+  orbit.enableDamping = true;
+  orbit.dampingFactor = 0.12;
+  orbit.target.set(0, 0.7, 0);
+  const gizmo = new TransformControls(world.camera, canvas);
+  gizmo.setTranslationSnap(0.01);
+  gizmo.setRotationSnap(THREE.MathUtils.degToRad(5));
+  world.scene.add(gizmo.getHelper());
+
+  const med = {
+    world,
+    orbit,
+    gizmo,
+    canvas,
+    callbacks,
+    modelNode: null,
+    partGroups: null,
+    mode: 'select',
+    selectedPartId: null,
+    gizmoDragging: false,
+    walk: false,
+    walkClock: 0,
+    box: null,
+    raf: 0,
+    model: null,
+    edit: null, // { partId, mode: 'face'|'vertex', selection: [indices] }
+    editVis: null,
+    editProxy: null,
+    editDrag: null,
+  };
+
+  gizmo.addEventListener('dragging-changed', (event) => {
+    if (!event.value) med.gizmoDraggedUntil = performance.now() + 150;
+    med.gizmoDragging = event.value;
+    med.orbit.enabled = !event.value;
+    if (med.edit) {
+      if (event.value) beginEditDrag(med);
+      else endEditDrag(med);
+    } else if (!event.value) {
+      commitGizmo(med);
+    }
+  });
+  gizmo.addEventListener('objectChange', () => {
+    if (med.edit && med.gizmoDragging) applyEditDrag(med);
+  });
+
+  let downAt = null;
+  canvas.addEventListener('pointerdown', (event) => {
+    downAt = { x: event.clientX, y: event.clientY };
+  });
+  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 || med.gizmoDragging) return;
+    if (performance.now() < (med.gizmoDraggedUntil ?? 0)) return;
+    if (med.edit) med.callbacks.onEditPick(pickMeshElement(med, event), event.shiftKey);
+    else med.callbacks.onPickPart(pickPart(med, event));
+  });
+
+  startModelLoop(med);
+  return med;
+}
+
+export function setEditorModel(med, model, sprites) {
+  clearEditVisuals(med);
+  if (med.modelNode) {
+    med.gizmo.detach();
+    med.world.scene.remove(med.modelNode);
+    disposeNode(med.modelNode);
+  }
+  // A private clone: edit-mode drags mutate this copy live (the parse cache
+  // shares model objects with the play runtime, so never mutate those).
+  med.model = model ? structuredClone(model) : null;
+  med.modelNode = med.model ? buildModelNode(med.model, sprites) : null;
+  med.partGroups = med.modelNode?.userData.modelParts ?? null;
+  if (med.modelNode) med.world.scene.add(med.modelNode);
+}
+
+export function disposeModelEditorWorld(med) {
+  cancelAnimationFrame(med.raf);
+  med.resizeObserver?.disconnect();
+  clearSelectionBox(med);
+  med.gizmo.detach();
+  med.gizmo.dispose();
+  med.orbit.dispose();
+  if (med.modelNode) disposeNode(med.modelNode);
+  disposeWorld(med.world);
+}
+
+function screenRaycaster(med, event) {
+  const rect = med.canvas.getBoundingClientRect();
+  const ndc = new THREE.Vector2(
+    ((event.clientX - rect.left) / rect.width) * 2 - 1,
+    -((event.clientY - rect.top) / rect.height) * 2 + 1
+  );
+  const raycaster = new THREE.Raycaster();
+  raycaster.setFromCamera(ndc, med.world.camera);
+  return raycaster;
+}
+
+function pickPart(med, event) {
+  if (!med.modelNode) return null;
+  const hits = screenRaycaster(med, event).intersectObject(med.modelNode, true);
+  for (const hit of hits) {
+    let object = hit.object;
+    while (object && object.userData.partId === undefined) object = object.parent;
+    if (object?.userData.partId) return object.userData.partId;
+  }
+  return null;
+}
+
+function commitGizmo(med) {
+  const group = med.gizmo.object;
+  if (!group || !group.userData.partId) return;
+  const r = (v) => Math.round(v * 100) / 100;
+  const deg = (v) => Math.round(THREE.MathUtils.radToDeg(v) * 10) / 10;
+  med.callbacks.onCommitPart(group.userData.partId, {
+    position: [r(group.position.x), r(group.position.y), r(group.position.z)],
+    rotation: [deg(group.rotation.x), deg(group.rotation.y), deg(group.rotation.z)],
+  });
+}
+
+function clearSelectionBox(med) {
+  if (!med.box) return;
+  med.world.scene.remove(med.box.helper);
+  med.box.helper.dispose();
+  med.box = null;
+}
+
+function syncSelection(med) {
+  if (med.edit) {
+    clearSelectionBox(med);
+    return;
+  }
+  const group = med.selectedPartId ? (med.partGroups?.get(med.selectedPartId) ?? null) : null;
+  if (!group || med.box?.group !== group) clearSelectionBox(med);
+  if (group && !med.box) {
+    med.box = { helper: new THREE.BoxHelper(group, 0xffffff), group };
+    med.world.scene.add(med.box.helper);
+  }
+  med.box?.helper.update();
+  const wantGizmo = group && (med.mode === 'move' || med.mode === 'rotate');
+  if (wantGizmo) {
+    med.gizmo.mode = med.mode === 'move' ? 'translate' : 'rotate';
+    if (med.gizmo.object !== group) med.gizmo.attach(group);
+  } else if (med.gizmo.object) {
+    med.gizmo.detach();
+  }
+}
+
+// A canned stride so the walk toggle can preview the animation conventions
+// without anything actually moving.
+function previewWalk(med, dt) {
+  if (!med.walk || !med.partGroups) return;
+  med.walkClock += dt;
+  const swing = Math.sin(med.walkClock * 7) * 0.6;
+  const set = (id, rx) => {
+    const group = med.partGroups.get(id);
+    if (group) group.rotation.x = rx;
+  };
+  set('legL', swing);
+  set('legR', -swing);
+  set('armL', -swing * 0.75);
+  set('armR', swing * 0.75);
+  const torso = med.partGroups.get('torso');
+  if (torso) {
+    const base = (torso.userData.editBaseY ??= torso.position.y);
+    torso.position.y = base + Math.abs(Math.sin(med.walkClock * 7)) * 0.05;
+  }
+}
+
+function startModelLoop(med) {
+  const fit = () => resizeWorld(med.world, med.canvas.clientWidth, med.canvas.clientHeight);
+  med.resizeObserver = new ResizeObserver(fit);
+  med.resizeObserver.observe(med.canvas);
+  fit();
+  let previous = performance.now();
+  const tick = (now) => {
+    const dt = Math.min(0.033, (now - previous) / 1000);
+    previous = now;
+    med.orbit.update();
+    previewWalk(med, dt);
+    syncSelection(med);
+    syncMeshEdit(med);
+    renderWorld(med.world);
+    med.raf = requestAnimationFrame(tick);
+  };
+  med.raf = requestAnimationFrame(tick);
+}
+
+//
+// Mesh edit mode
+//
+
+function editContext(med) {
+  const edit = med.edit;
+  const part = edit ? med.model?.parts.find((candidate) => candidate.id === edit.partId) : null;
+  const group = edit ? (med.partGroups?.get(edit.partId) ?? null) : null;
+  const meshObj = group?.children.find((child) => child.isMesh) ?? null;
+  if (!edit || !part || part.kind !== 'mesh' || !group || !meshObj) return null;
+  return { edit, part, group, meshObj };
+}
+
+function pickMeshElement(med, event) {
+  const ctx = editContext(med);
+  if (!ctx) return null;
+  const rect = med.canvas.getBoundingClientRect();
+  if (ctx.edit.mode === 'face') {
+    const hit = screenRaycaster(med, event).intersectObject(ctx.meshObj, false)[0];
+    if (!hit || hit.faceIndex === undefined) return null;
+    return ctx.meshObj.userData.triFaces?.[hit.faceIndex] ?? null;
+  }
+  // Vertex mode: nearest projected vertex within a small screen radius.
+  const world = new THREE.Vector3();
+  let best = null;
+  let bestDist = 14;
+  for (let index = 0; index < ctx.part.vertices.length; index++) {
+    const v = ctx.part.vertices[index];
+    world
+      .set(v[0] + ctx.part.offset[0], v[1] + ctx.part.offset[1], v[2] + ctx.part.offset[2])
+      .applyMatrix4(ctx.group.matrixWorld)
+      .project(med.world.camera);
+    const sx = ((world.x + 1) / 2) * rect.width;
+    const sy = ((1 - world.y) / 2) * rect.height;
+    const dist = Math.hypot(sx - (event.clientX - rect.left), sy - (event.clientY - rect.top));
+    if (dist < bestDist) {
+      bestDist = dist;
+      best = index;
+    }
+  }
+  return best;
+}
+
+function selectedVertexIndices(ctx) {
+  return ctx.edit.mode === 'face'
+    ? faceVertexIndices(ctx.part, ctx.edit.selection)
+    : ctx.edit.selection;
+}
+
+function beginEditDrag(med) {
+  const ctx = editContext(med);
+  if (!ctx || !med.editProxy) return;
+  med.editDrag = {
+    start: med.editProxy.position.clone(),
+    vertices: structuredClone(ctx.part.vertices),
+  };
+}
+
+function applyEditDrag(med) {
+  const ctx = editContext(med);
+  if (!ctx || !med.editDrag || !med.editProxy) return;
+  const delta = med.editProxy.position.clone().sub(med.editDrag.start);
+  for (const index of selectedVertexIndices(ctx)) {
+    const v = med.editDrag.vertices[index];
+    if (v) ctx.part.vertices[index] = [v[0] + delta.x, v[1] + delta.y, v[2] + delta.z];
+  }
+  rebuildEditGeometry(med, ctx);
+}
+
+function endEditDrag(med) {
+  const ctx = editContext(med);
+  const drag = med.editDrag;
+  med.editDrag = null;
+  if (!ctx || !drag) return;
+  const round3 = (v) => Math.round(v * 1000) / 1000;
+  med.callbacks.onCommitMeshVertices(
+    ctx.edit.partId,
+    ctx.part.vertices.map((v) => v.map(round3))
+  );
+}
+
+function rebuildEditGeometry(med, ctx) {
+  const { geometry, triFaces } = buildMeshGeometry(ctx.part);
+  ctx.meshObj.geometry.dispose();
+  ctx.meshObj.geometry = geometry;
+  ctx.meshObj.userData.triFaces = triFaces;
+  refreshEditVisuals(med, ctx, true);
+}
+
+function disposeEditVisObjects(med) {
+  if (!med.editVis) return;
+  for (const object of Object.values(med.editVis.objects)) {
+    object.parent?.remove(object);
+    object.geometry?.dispose();
+    object.material?.dispose();
+  }
+  med.editVis = null;
+}
+
+function clearEditVisuals(med) {
+  disposeEditVisObjects(med);
+  if (med.editProxy) {
+    if (med.gizmo.object === med.editProxy) med.gizmo.detach();
+    med.editProxy.parent?.remove(med.editProxy);
+    med.editProxy = null;
+  }
+}
+
+function editVisSignature(ctx) {
+  return JSON.stringify([ctx.edit.mode, ctx.edit.selection, ctx.part.vertices.length]);
+}
+
+// Per-frame edit overlays: vertex dots, selected-face tint, and the translate
+// proxy the gizmo drives. Rebuilt only when the selection/mesh changes.
+function syncMeshEdit(med) {
+  const ctx = editContext(med);
+  if (!ctx) {
+    clearEditVisuals(med);
+    return;
+  }
+  const sig = editVisSignature(ctx);
+  if (med.editVis?.sig !== sig && !med.gizmoDragging) {
+    clearEditVisuals(med);
+    med.editVis = { sig, objects: buildEditVisuals(med, ctx) };
+    syncEditProxy(med, ctx);
+  }
+  const wantGizmo = (med.mode === 'move' || med.mode === 'rotate') && ctx.edit.selection.length > 0;
+  if (wantGizmo && med.editProxy) {
+    med.gizmo.mode = 'translate';
+    if (med.gizmo.object !== med.editProxy) med.gizmo.attach(med.editProxy);
+  } else if (med.gizmo.object && !med.gizmoDragging) {
+    med.gizmo.detach();
+  }
+}
+
+function refreshEditVisuals(med, ctx, keepProxy) {
+  disposeEditVisObjects(med);
+  med.editVis = { sig: editVisSignature(ctx), objects: buildEditVisuals(med, ctx) };
+  if (!keepProxy) syncEditProxy(med, ctx);
+}
+
+function syncEditProxy(med, ctx) {
+  if (!med.editProxy) {
+    med.editProxy = new THREE.Object3D();
+    ctx.group.add(med.editProxy);
+  } else if (med.editProxy.parent !== ctx.group) {
+    med.editProxy.parent?.remove(med.editProxy);
+    ctx.group.add(med.editProxy);
+  }
+  const indices = selectedVertexIndices(ctx);
+  if (indices.length === 0) return;
+  const c = [0, 0, 0];
+  for (const index of indices) {
+    const v = ctx.part.vertices[index] ?? [0, 0, 0];
+    c[0] += v[0];
+    c[1] += v[1];
+    c[2] += v[2];
+  }
+  med.editProxy.position.set(
+    c[0] / indices.length + ctx.part.offset[0],
+    c[1] / indices.length + ctx.part.offset[1],
+    c[2] / indices.length + ctx.part.offset[2]
+  );
+}
+
+function buildEditVisuals(med, ctx) {
+  const objects = {};
+  const offset = ctx.part.offset;
+  const positions = [];
+  for (const v of ctx.part.vertices) {
+    positions.push(v[0] + offset[0], v[1] + offset[1], v[2] + offset[2]);
+  }
+  const allGeometry = new THREE.BufferGeometry();
+  allGeometry.setAttribute('position', new THREE.Float32BufferAttribute(positions, 3));
+  objects.points = new THREE.Points(
+    allGeometry,
+    new THREE.PointsMaterial({ color: 0x8a92a8, size: 6, sizeAttenuation: false, depthTest: false })
+  );
+  objects.points.renderOrder = 10;
+  ctx.group.add(objects.points);
+
+  const selectedVerts = selectedVertexIndices(ctx);
+  if (selectedVerts.length) {
+    const selPositions = [];
+    for (const index of selectedVerts) {
+      const v = ctx.part.vertices[index] ?? [0, 0, 0];
+      selPositions.push(v[0] + offset[0], v[1] + offset[1], v[2] + offset[2]);
+    }
+    const selGeometry = new THREE.BufferGeometry();
+    selGeometry.setAttribute('position', new THREE.Float32BufferAttribute(selPositions, 3));
+    objects.selectedPoints = new THREE.Points(
+      selGeometry,
+      new THREE.PointsMaterial({
+        color: 0xffffff,
+        size: 10,
+        sizeAttenuation: false,
+        depthTest: false,
+      })
+    );
+    objects.selectedPoints.renderOrder = 11;
+    ctx.group.add(objects.selectedPoints);
+  }
+
+  if (ctx.edit.mode === 'face' && ctx.edit.selection.length) {
+    const facePositions = [];
+    for (const faceIndex of ctx.edit.selection) {
+      const face = ctx.part.faces[faceIndex];
+      if (!face) continue;
+      for (let i = 1; i + 1 < face.length; i++) {
+        for (const index of [face[0], face[i], face[i + 1]]) {
+          const v = ctx.part.vertices[index] ?? [0, 0, 0];
+          facePositions.push(v[0] + offset[0], v[1] + offset[1], v[2] + offset[2]);
+        }
+      }
+    }
+    const faceGeometry = new THREE.BufferGeometry();
+    faceGeometry.setAttribute('position', new THREE.Float32BufferAttribute(facePositions, 3));
+    objects.faceOverlay = new THREE.Mesh(
+      faceGeometry,
+      new THREE.MeshBasicMaterial({
+        color: 0xffe066,
+        transparent: true,
+        opacity: 0.3,
+        side: THREE.DoubleSide,
+        depthTest: false,
+      })
+    );
+    objects.faceOverlay.renderOrder = 9;
+    ctx.group.add(objects.faceOverlay);
+  }
+  return objects;
+}

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

@@ -0,0 +1,139 @@
+// `.pxmodel` files in the live deck file map. The imported engine's file
+// globs are compile-time literals that don't know this kit's model format, so
+// this module (a) adds its own glob so models are seeded at build time and
+// inlined into the published bundle, and (b) forks the imported
+// useLiveDeckFiles with `.pxmodel` treated as a DATA file -- edited live over
+// the files API instead of forcing a context reload (the glob puts models in
+// vite's module graph, which the imported hook would read as "code changed").
+import { useEffect, useRef, useState } from 'react';
+import { onFilesChanged, requestReload } from 'castle-web-sdk';
+import { initialFiles, initialMedia, isImageFile } from '@imports/castle.physics-2d/engine/files';
+import { parseFull } from '@imports/castle.physics-2d/engine/pxart';
+import { imageArt } from '@imports/castle.physics-2d/engine/art';
+
+// Both the deck's own models and every import's -- same shape as the imported
+// engine's own file globs: when this kit is itself an import, its models live
+// under imports/<alias>/models/ in the deck being served, and a map without
+// them can't resolve a kit blueprint's Model ref.
+const modelModules = import.meta.glob(['/models/**/*.pxmodel', '/imports/*/models/**/*.pxmodel'], {
+  query: '?raw',
+  import: 'default',
+  eager: true,
+});
+
+export const initialFiles3D = {
+  ...initialFiles,
+  ...Object.fromEntries(
+    Object.entries(modelModules).map(([globPath, text]) => [globPath.replace(/^\//, ''), text])
+  ),
+};
+
+const DATA_EXTS = ['.scene', '.pxart', '.drawing', '.pxmodel'];
+const CODE_EXTS = ['.js', '.jsx', '.ts', '.tsx', '.css'];
+
+export function isDataFile3D(path) {
+  return DATA_EXTS.some((ext) => path.endsWith(ext));
+}
+
+function needsContextReload(change) {
+  if (isDataFile3D(change.path)) return false;
+  if (change.path.endsWith('.html')) return true;
+  if (change.affected.length > 0) return true;
+  if (change.event !== 'change') return CODE_EXTS.some((ext) => change.path.endsWith(ext));
+  return false;
+}
+
+async function readDeckFile(path) {
+  const res = await fetch(`/__castle/files/read?path=${encodeURIComponent(path)}`);
+  if (!res.ok) throw new Error(`read failed: ${res.status}`);
+  const data = await res.json();
+  return typeof data.contents === 'string' ? data.contents : '';
+}
+
+async function applyDataChanges(changes, setFiles, setDataVersion) {
+  const updates = await Promise.all(
+    changes.map(async (change) => {
+      if (change.event === 'delete') return { path: change.path, text: null };
+      try {
+        return { path: change.path, text: await readDeckFile(change.path) };
+      } catch {
+        return null; // read raced a delete / serve hiccup -- skip this path
+      }
+    })
+  );
+  const applied = updates.filter(Boolean);
+  if (applied.length === 0) return;
+  setFiles((current) => {
+    const next = { ...current };
+    for (const { path, text } of applied) {
+      if (text === null) delete next[path];
+      else next[path] = text;
+    }
+    return next;
+  });
+  setDataVersion((version) => version + 1);
+}
+
+// Live deck files including models. Same contract as the imported
+// useLiveDeckFiles: `shouldSkipPath` keeps an editor's in-flight writes from
+// being clobbered by their own fs echo; `dataVersion` bumps on applied data
+// changes.
+export function useLiveDeckFiles3D({ shouldSkipPath } = {}) {
+  const [files, setFiles] = useState(initialFiles3D);
+  const [dataVersion, setDataVersion] = useState(0);
+  const skipRef = useRef(shouldSkipPath);
+  skipRef.current = shouldSkipPath;
+
+  useEffect(
+    () =>
+      onFilesChanged((event) => {
+        if (event.changes.some(needsContextReload)) {
+          requestReload();
+          return;
+        }
+        const dataChanges = event.changes.filter(
+          (change) => isDataFile3D(change.path) && !skipRef.current?.(change.path)
+        );
+        if (dataChanges.length === 0) return;
+        void applyDataChanges(dataChanges, setFiles, setDataVersion);
+      }),
+    []
+  );
+
+  return { files, setFiles, dataVersion };
+}
+
+// The sprites map with parsed pxarts CACHED BY TEXT: re-parsing every file on
+// every edit would mint new art objects, changing every node signature and
+// rebuilding the whole three scene per keystroke. Only a pxart whose text
+// actually changed re-parses. Shared by the scene and model editors.
+export function useStableSprites(files) {
+  const cacheRef = useRef(new Map());
+  const sprites = {};
+  for (const [path, url] of Object.entries(initialMedia)) {
+    if (isImageFile(path)) sprites[path] = imageArt(path, url);
+  }
+  for (const [path, text] of Object.entries(files)) {
+    if (!path.endsWith('.pxart')) continue;
+    let cached = cacheRef.current.get(path);
+    if (!cached || cached.text !== text) {
+      const art = parseFull(text);
+      if (!art) continue;
+      cached = { text, art };
+      cacheRef.current.set(path, cached);
+    }
+    sprites[path] = cached.art;
+  }
+  return sprites;
+}
+
+// One-shot fetch for a path the build-time glob missed (a model created after
+// the last reload); folds it into files state.
+export async function fetchMissingFile(path, setFiles) {
+  try {
+    const text = await readDeckFile(path);
+    setFiles((current) => (current[path] === undefined ? { ...current, [path]: text } : current));
+  } catch {
+    // stays missing; the editor shows its error state
+  }
+}