@volter/editor-threejs 0.5.212 → 0.5.214

package/src/kit/play-camera-flight.ts

@@ -1,291 +0,0 @@
-/**
- * THE PLAY ENTRY CAMERA FLIGHT — the Three integration's half of Play's immersive entry
- * (`@volter/sdk/play-camera-flight`). The kit's transition owns the phases and the
- * chrome; this owns the camera: the editor viewport flies along a Catmull-Rom spline from its
- * preview pose to the AUTHORED game camera's pose, retargets to the game's live camera once it
- * boots so the cross-fade is pixel-continuous, and restores the preview pose when Play ends. The
- * flight reads the authored viewport's rig through the viewport door and rides its frame hook, so
- * flight pacing rides the editor's own frame clock.
- */
-import { registerPlayCameraFlight, type LiveCameraLookup } from '@volter/sdk/play-camera-flight';
-import { onViewportFrame, viewportRig } from '../viewport-door';
-import * as THREE from 'three';
-import { threeStoreForHost } from './three-state';
-
-/** Flight time scales mildly with distance so short hops feel snappy and
- *  cross-scene flights stay graceful, clamped to a tight band. */
-export function flightDurationMs(distance: number): number {
-  return Math.min(1600, Math.max(800, 900 + distance * 25));
-}
-
-export function easeInOutCubic(t: number): number {
-  return t < 0.5 ? 4 * t * t * t : 1 - (-2 * t + 2) ** 3 / 2;
-}
-
-/**
- * Control points for the camera flight spline: start, two interior points
- * forming a gentle arc, end. The arc lifts along world-up and bows slightly
- * sideways, both proportional to (but clamped against) the travel distance —
- * a short hop barely arcs, a long flight gets a visible swoop, and a
- * degenerate zero-length flight returns a straight (stationary) curve.
- */
-export function computeFlightControlPoints(
-  start: THREE.Vector3,
-  end: THREE.Vector3,
-  up: THREE.Vector3 = new THREE.Vector3(0, 1, 0),
-): THREE.Vector3[] {
-  const travel = new THREE.Vector3().subVectors(end, start);
-  const distance = travel.length();
-  if (distance < 1e-6) {
-    return [start.clone(), start.clone(), end.clone(), end.clone()];
-  }
-  const lift = Math.min(distance * 0.18, 6);
-  // Side bias perpendicular to travel and up — gives the arc a slight bank
-  // instead of a purely vertical hump. Falls back to zero when travel is
-  // parallel to up (straight vertical flights just lift).
-  const side = new THREE.Vector3().crossVectors(travel, up);
-  if (side.lengthSq() > 1e-9) side.normalize().multiplyScalar(Math.min(distance * 0.08, 2.5));
-  else side.set(0, 0, 0);
-  const liftVec = up.clone().normalize().multiplyScalar(lift);
-  const p1 = start.clone().addScaledVector(travel, 0.3).add(liftVec).add(side);
-  const p2 = end
-    .clone()
-    .addScaledVector(travel, -0.3)
-    .addScaledVector(liftVec, 0.6)
-    .addScaledVector(side, 0.5);
-  return [start.clone(), p1, p2, end.clone()];
-}
-
-/** The narrow store surface `resolveAuthoredCameraTarget` reads. */
-export interface PlayCameraSourceStore {
-  readonly objectMap: ReadonlyMap<string, THREE.Object3D>;
-}
-
-export interface AuthoredCameraTarget {
-  entityId: string;
-  position: [number, number, number];
-  quaternion: [number, number, number, number];
-  fov: number;
-}
-
-/** Editor-only overlays (helpers, gizmos) live on layer 31 — never flight targets. */
-const EDITOR_ONLY_LAYER_MASK = 1 << 31;
-
-function isEditorOnlyOrGizmo(obj: THREE.Object3D): boolean {
-  return (obj.layers.mask & EDITOR_ONLY_LAYER_MASK) !== 0 || /gizmo/i.test(obj.name);
-}
-
-/** Depth-first search for the first real camera in a subtree, skipping
- *  editor-only/gizmo branches wholesale. */
-function findCameraInSubtree(obj: THREE.Object3D): THREE.Camera | null {
-  if (isEditorOnlyOrGizmo(obj)) return null;
-  if ((obj as Partial<THREE.Camera>).isCamera) return obj as THREE.Camera;
-  for (const child of obj.children) {
-    const found = findCameraInSubtree(child);
-    if (found) return found;
-  }
-  return null;
-}
-
-function targetFromObject(
-  entityId: string,
-  obj: THREE.Object3D,
-  fov: number,
-): AuthoredCameraTarget {
-  const position = new THREE.Vector3();
-  const quaternion = new THREE.Quaternion();
-  obj.getWorldPosition(position);
-  obj.getWorldQuaternion(quaternion);
-  return {
-    entityId,
-    position: position.toArray() as [number, number, number],
-    quaternion: quaternion.toArray() as [number, number, number, number],
-    fov,
-  };
-}
-
-/**
- * Find the authored camera in the current editor scene outside editor-only and gizmo branches, and
- * return its live world transform. Return null when the mapped object graph contains no camera.
- */
-export function resolveAuthoredCameraTarget(
-  store: PlayCameraSourceStore,
-): AuthoredCameraTarget | null {
-  for (const [id, obj] of store.objectMap) {
-    const camera = findCameraInSubtree(obj);
-    if (!camera) continue;
-    const perspective = camera as Partial<THREE.PerspectiveCamera>;
-    return targetFromObject(id, camera, perspective.isPerspectiveCamera ? perspective.fov! : 60);
-  }
-  return null;
-}
-
-interface FlightRuntime {
-  startPos: THREE.Vector3;
-  startQuat: THREE.Quaternion;
-  startFov: number;
-  endPos: THREE.Vector3;
-  endQuat: THREE.Quaternion;
-  endFov: number;
-  curve: THREE.CatmullRomCurve3;
-  startedAt: number;
-  durationMs: number;
-  landed: boolean;
-}
-
-function rebuildCurve(flight: FlightRuntime): void {
-  flight.curve = new THREE.CatmullRomCurve3(
-    computeFlightControlPoints(flight.startPos, flight.endPos),
-  );
-}
-
-interface ActiveFlight {
-  readonly runtime: FlightRuntime;
-  readonly snapshot: { position: THREE.Vector3; target: THREE.Vector3; up: THREE.Vector3; fov: number };
-  readonly onLanded: () => void;
-  /** Live camera, registered at live-ready — the flight retargets to it
-   *  each frame so the hand-off converges on whatever the project actually does
-   *  with its camera during boot (follow rigs, SceneCamera components…). */
-  getLiveCamera: LiveCameraLookup | null;
-  /** Driving the camera: from `begin` until the game is on screen (`settle`) or Play ends. */
-  driving: boolean;
-}
-
-let _flight: ActiveFlight | null = null;
-
-function begin(onLanded: () => void): boolean {
-  const viewport = viewportRig();
-  const objects = threeStoreForHost()?.objectMap;
-  const target = objects ? resolveAuthoredCameraTarget({ objectMap: objects }) : null;
-  if (!target || !viewport) return false;
-  const startPos = viewport.camera.position.clone();
-  const endPos = new THREE.Vector3().fromArray(target.position);
-  _flight = {
-    runtime: {
-      startPos,
-      startQuat: viewport.camera.quaternion.clone(),
-      startFov: viewport.camera.fov,
-      endPos,
-      endQuat: new THREE.Quaternion().fromArray(target.quaternion),
-      endFov: target.fov,
-      curve: new THREE.CatmullRomCurve3(computeFlightControlPoints(startPos, endPos)),
-      startedAt: performance.now(),
-      durationMs: flightDurationMs(startPos.distanceTo(endPos)),
-      landed: false,
-    },
-    snapshot: {
-      position: viewport.camera.position.clone(),
-      target: viewport.orbit.target.clone(),
-      up: viewport.camera.up.clone(),
-      fov: viewport.camera.fov,
-    },
-    onLanded,
-    getLiveCamera: null,
-    driving: true,
-  };
-  viewport.orbit.enabled = false;
-  return true;
-}
-
-/** After the flight, leave OrbitControls in a sane state at the landed pose
- *  so the viewport still orbits correctly during play. */
-function settle(): void {
-  const viewport = viewportRig();
-  const active = _flight;
-  if (!active) return;
-  active.driving = false;
-  if (!viewport) return;
-  const camera = viewport.camera;
-  const forward = new THREE.Vector3(0, 0, -1).applyQuaternion(camera.quaternion);
-  const distance = Math.max(1, active.snapshot.position.distanceTo(active.snapshot.target));
-  viewport.orbit.target.copy(camera.position).addScaledVector(forward, distance);
-  // The orbit re-aims with the camera's up: the landed pose's own, so its roll stands.
-  camera.up.set(0, 1, 0).applyQuaternion(camera.quaternion);
-  viewport.orbit.enabled = true;
-}
-
-/** Restore the pre-play camera pose. */
-function end(): void {
-  const active = _flight;
-  if (!active) return;
-  _flight = null;
-  const viewport = viewportRig();
-  if (!viewport) return;
-  const snap = active.snapshot;
-  viewport.camera.position.copy(snap.position);
-  viewport.orbit.target.copy(snap.target);
-  viewport.camera.up.copy(snap.up);
-  viewport.camera.lookAt(snap.target);
-  if (viewport.camera.fov !== snap.fov) {
-    viewport.camera.fov = snap.fov;
-    viewport.camera.updateProjectionMatrix();
-  }
-  viewport.orbit.enabled = true;
-  viewport.orbit.update();
-}
-
-const _liveCamPos = new THREE.Vector3();
-const _liveCamQuat = new THREE.Quaternion();
-
-/**
- * Per-frame flight driver — called from the world root's stage's RAF loop right after
- * `viewport.update(dt)` so the flight has final say over the camera pose.
- */
-onViewportFrame(playTransitionFrame);
-
-function playTransitionFrame(): void {
-  const active = _flight;
-  const viewport = viewportRig();
-  if (!active || !viewport || !active.driving) return;
-  const flight = active.runtime;
-
-  // Retarget to the live game camera once it exists (`track`).
-  // The kit hands the lane's lookup over unread; only an `Object3D` is a camera to converge on.
-  const found = active.getLiveCamera?.() ?? null;
-  const liveCamera = (found as Partial<THREE.Object3D> | null)?.isObject3D ? (found as THREE.Object3D) : null;
-  if (liveCamera) {
-    liveCamera.getWorldPosition(_liveCamPos);
-    liveCamera.getWorldQuaternion(_liveCamQuat);
-    if (_liveCamPos.distanceToSquared(flight.endPos) > 1e-8) {
-      flight.endPos.copy(_liveCamPos);
-      rebuildCurve(flight);
-    }
-    flight.endQuat.copy(_liveCamQuat);
-    const liveFov = (liveCamera as THREE.PerspectiveCamera).fov;
-    if (typeof liveFov === 'number') flight.endFov = liveFov;
-  }
-
-  const camera = viewport.camera;
-  if (flight.landed) {
-    // Holding/cross-fading: pin to the (possibly live-tracked) end pose.
-    camera.position.copy(flight.endPos);
-    camera.quaternion.copy(flight.endQuat);
-    if (camera.fov !== flight.endFov) {
-      camera.fov = flight.endFov;
-      camera.updateProjectionMatrix();
-    }
-    return;
-  }
-
-  const t = Math.min(1, (performance.now() - flight.startedAt) / flight.durationMs);
-  const eased = easeInOutCubic(t);
-  camera.position.copy(flight.curve.getPoint(eased));
-  camera.quaternion.slerpQuaternions(flight.startQuat, flight.endQuat, eased);
-  camera.fov = flight.startFov + (flight.endFov - flight.startFov) * eased;
-  camera.updateProjectionMatrix();
-  if (t >= 1) {
-    flight.landed = true;
-    active.onLanded();
-  }
-}
-
-export function registerThreePlayCameraFlight(): () => void {
-  return registerPlayCameraFlight({
-    begin,
-    track: (liveCamera) => {
-      if (_flight) _flight.getLiveCamera = liveCamera;
-    },
-    settle,
-    end,
-  });
-}

package/src/kit/scene-document-viewport.ts

@@ -1,51 +0,0 @@
-/**
- * THE SCENE'S VIEWPORT (`@volter/sdk/document-viewports`): the world
- * stage draws the Scene through the session store's own camera, shading and
- * grid, and frames the shell's selection. It keeps no selection of its own, so a
- * view's selection is the shell's.
- */
-import type { DocumentViewport } from '@volter/sdk/document-viewports';
-import type { EditorShellStore } from './editor-shell-store';
-import { viewGridVisible } from '@volter/sdk/viewport-presentation';
-
-type ShadingMode = Parameters<EditorShellStore['setShadingMode']>[0];
-
-const SCENE_MODES = new Set<string>(['solid', 'clay', 'unlit', 'wireframe', 'normals', 'overdraw']);
-
-export function sceneDocumentViewport(store: EditorShellStore, documentId: string): DocumentViewport {
-  return {
-    read: () => {
-      const pose = store.cameraPose;
-      if (!pose) return null;
-      const { position, target } = pose;
-      return {
-        camera: {
-          position: { x: position.x, y: position.y, z: position.z },
-          target: { x: target.x, y: target.y, z: target.z },
-          ...(pose.fov ? { fov: pose.fov } : {}),
-        },
-        diagnostic: store.shadingMode,
-        grid: viewGridVisible(documentId),
-      };
-    },
-    setDiagnostic: (diagnostic) => {
-      if (!SCENE_MODES.has(diagnostic)) return false;
-      store.setShadingMode(diagnostic as ShadingMode);
-      return true;
-    },
-    setCamera: (camera) => {
-      if (typeof camera !== 'string') {
-        store.shell.setCameraPose(camera.position, camera.target, camera.fov);
-        return true;
-      }
-      if (camera === 'isometric') return false;
-      store.shell.setViewPreset(camera);
-      return true;
-    },
-    frame: (target) => {
-      if (target === 'document') return false;
-      store.shell.focusOnSelection();
-      return true;
-    },
-  };
-}

package/src/kit/viewport-surface-status.tsx

@@ -1,44 +0,0 @@
-/**
- * The 3D board's empty-viewport vocabulary, reused by every other design
- * surface that would otherwise sit blank while it builds. Scene's root-aware
- * loading/failure/empty states live in `SurfaceStateOverlay`; this compact
- * label remains for object/board construction whose subject is already known.
- *
- * Idle / building / ready is viewport STATE, not a new overlay channel —
- * the board already owns this shape (`ThreeBoardDocument`: idle "Open this
- * tab…", building "Settling N stories…"). Scene's first design
- * mount and `Object3DDocumentViewport`'s first construct are the same wait
- * with different subjects. Copy names the subject being prepared; it does not
- * claim a narrower phase (such as physics settling) while indexing, mounting,
- * bounds/layout, or renderer setup is actually in flight.
- */
-
-import { themeVars } from '@volter/sdk/widgets';
-import type { ReactNode } from 'react';
-
-/** Fixed construct tail after the board scene exists — viewport-bind, not settle. */
-export const OBJECT3D_SURFACE_BUILDING = 'Preparing the viewport…';
-
-export function ViewportSurfaceStatus({
-  testId,
-  children,
-}: {
-  readonly testId: string;
-  readonly children: ReactNode;
-}) {
-  return (
-    <div
-      data-testid={testId}
-      style={{
-        position: 'absolute',
-        inset: 0,
-        padding: 16,
-        fontSize: 12,
-        color: themeVars.content.muted,
-        pointerEvents: 'none',
-      }}
-    >
-      {children}
-    </div>
-  );
-}