@volter/editor-threejs 0.5.65 → 0.5.67

package/src/kit/trigger-volume-helper.ts

@@ -0,0 +1,116 @@
+import { EDITOR_LAYER } from '@volter/editor-threejs/viewport/editor-layers';
+import { triggerVolumeOf } from '@volter/editor-threejs/adapter/trigger-volume';
+import { setUserData } from '@volter/editor-threejs/ecs/user-data';
+import * as THREE from 'three';
+
+const RING = new THREE.Color(0x4fd1c5);
+const RING_SELECTED = new THREE.Color(0x9ff0e8);
+const SEGMENTS = 64;
+/** How far the corner ticks rise off the ring, in world units. */
+const TICK_HEIGHT = 0.6;
+
+/**
+ * Editor-only visualization for a project-owned trigger volume — the group
+ * whose radius decides where a hazard fires or a quest arrives. The game's
+ * source says nothing about being authored; it just carries the radius in
+ * `userData`, and this helper draws it: a ground circle in the source's local
+ * XZ plane that extends upward at ±X/±Z, which is what such a volume tests.
+ *
+ * Same contract as `ReflectionProbeHelper`: it follows the live Object3D but
+ * owns every line and material it draws, sits on EDITOR_LAYER, and therefore
+ * never enters the game's tree or its runtime camera.
+ */
+export class TriggerVolumeHelper extends THREE.Group {
+  private signature = '';
+  private selected = false;
+
+  constructor(readonly source: THREE.Object3D) {
+    super();
+    this.name = 'Trigger Volume Helper';
+    this.matrixAutoUpdate = false;
+    this.renderOrder = 998;
+    setUserData(this, 'editorHelper', true);
+    setUserData(this, 'editorHelperType', 'trigger-volumes');
+    this.layers.set(EDITOR_LAYER);
+    this.refresh(true);
+  }
+
+  setSelected(selected: boolean): void {
+    if (this.selected === selected) return;
+    this.selected = selected;
+    this.refresh(true);
+  }
+
+  update(): void {
+    this.refresh(false);
+    this.source.updateWorldMatrix(true, false);
+    this.matrix.copy(this.source.matrixWorld);
+    this.matrixWorldNeedsUpdate = true;
+  }
+
+  dispose(): void {
+    this.clearVisuals();
+    this.removeFromParent();
+  }
+
+  private refresh(force: boolean): void {
+    const volume = triggerVolumeOf(this.source);
+    if (!volume) return;
+    const radius = volume.radius;
+    const next = String(radius);
+    if (!force && next === this.signature) return;
+    this.signature = next;
+    this.clearVisuals();
+
+    const color = this.selected ? RING_SELECTED : RING;
+    const opacity = this.selected ? 1 : 0.62;
+
+    const ring: number[] = [];
+    for (let i = 0; i < SEGMENTS; i += 1) {
+      const angle = (i / SEGMENTS) * Math.PI * 2;
+      ring.push(Math.cos(angle) * radius, 0, Math.sin(angle) * radius);
+    }
+    const ringGeometry = new THREE.BufferGeometry();
+    ringGeometry.setAttribute('position', new THREE.Float32BufferAttribute(ring, 3));
+    const loop = new THREE.LineLoop(ringGeometry, this.lineMaterial(color, opacity));
+    loop.renderOrder = this.renderOrder;
+    this.add(loop);
+
+    const ticks: number[] = [];
+    for (const [x, z] of [
+      [radius, 0],
+      [-radius, 0],
+      [0, radius],
+      [0, -radius],
+    ] as const) {
+      ticks.push(x, 0, z, x, TICK_HEIGHT, z);
+    }
+    const tickGeometry = new THREE.BufferGeometry();
+    tickGeometry.setAttribute('position', new THREE.Float32BufferAttribute(ticks, 3));
+    const tickLines = new THREE.LineSegments(tickGeometry, this.lineMaterial(color, opacity));
+    tickLines.renderOrder = this.renderOrder;
+    this.add(tickLines);
+
+    this.traverse((object) => object.layers.set(EDITOR_LAYER));
+  }
+
+  private lineMaterial(color: THREE.Color, opacity: number): THREE.LineBasicMaterial {
+    return new THREE.LineBasicMaterial({
+      color,
+      depthTest: false,
+      transparent: true,
+      opacity,
+      toneMapped: false,
+    });
+  }
+
+  private clearVisuals(): void {
+    for (const child of [...this.children]) {
+      child.removeFromParent();
+      const line = child as THREE.LineSegments;
+      line.geometry?.dispose();
+      const materials = Array.isArray(line.material) ? line.material : [line.material];
+      for (const material of materials) material?.dispose();
+    }
+  }
+}

package/src/kit/viewport-actions.ts

@@ -0,0 +1,128 @@
+/**
+ * THE THREE VIEWPORT'S PALETTE ENTRIES — tool and space modes, grid, helpers,
+ * stats, snap, shading, the view presets, Frame and the camera verbs. They are
+ * the active three stage's, published as a palette contribution while that
+ * stage is bound (`components/stage-keyboard.tsx`), and they act on that
+ * stage's own store: the same stage its keys drive (`viewport-hotkeys.ts`).
+ */
+import type { ActionContribution, ContributedAction } from '@volter/editor-sdk/chrome';
+import {
+  alignCameraToViewport,
+  cameraAuthoringPresentation,
+  currentCameraAuthoringSubject,
+  leaveCameraView,
+  pilotCamera,
+  subscribeCameraAuthoring,
+  toggleCameraPreviewPin,
+  viewThroughCamera,
+} from './camera-authoring';
+import { registerContributedActions } from '@volter/editor-sdk/kit/chrome-registry';
+import type { EditorShellStore } from './editor-shell-store';
+import { object3DDocumentSession } from './authoring/object3d-document-session-registry';
+import { requestTransformMode } from '@volter/editor-sdk/kit/transform-mode-request';
+import { activeWorkspaceDocumentId } from '@volter/editor-sdk/kit/workspace-document-registry';
+import {
+  setViewGridVisible,
+  viewGridVisible,
+  viewPresentationBinding,
+} from '@volter/editor-sdk/kit/viewport-presentation';
+
+function cameraActions(): ContributedAction[] {
+  const presentation = cameraAuthoringPresentation();
+  if (presentation.view) {
+    return [{ id: 'camera.exitView', label: 'Exit Camera View', execute: leaveCameraView }];
+  }
+  const subject = currentCameraAuthoringSubject();
+  if (!subject) return [];
+  return [
+    {
+      id: 'camera.viewThrough',
+      label: `View Through ${subject.name}`,
+      execute: () => viewThroughCamera(subject),
+    },
+    ...(subject.canAuthorPose
+      ? [
+          { id: 'camera.pilot', label: `Pilot ${subject.name}`, execute: () => pilotCamera(subject) },
+          {
+            id: 'camera.alignToView',
+            label: `Align ${subject.name} to Current View`,
+            execute: () => alignCameraToViewport(subject),
+          },
+        ]
+      : []),
+    {
+      id: 'camera.pinPreview',
+      label: presentation.previewPinned ? 'Unpin Camera Preview' : 'Pin Camera Preview',
+      execute: toggleCameraPreviewPin,
+    },
+  ];
+}
+
+function activeObject3DDocumentSession() {
+  const documentId = activeWorkspaceDocumentId();
+  return documentId ? object3DDocumentSession(documentId) : null;
+}
+
+/** A document stage paints the mode its SESSION holds; the store's is only what the menu shows
+ *  where there is no session (`set-shading-mode` and the shading menu route the same way). */
+function setShading(store: EditorShellStore, mode: Parameters<EditorShellStore['setShadingMode']>[0]): void {
+  const session = activeObject3DDocumentSession();
+  if (session) session.setMode(mode);
+  else store.setShadingMode(mode);
+}
+
+export function registerViewportActions(store: EditorShellStore): () => void {
+  const fixed: ContributedAction[] = [
+    { id: 'mode.select', label: 'Select Tool (no gizmo)', shortcut: 'transform.select', execute: () => requestTransformMode(store.shell, 'select') },
+    { id: 'mode.combined', label: 'Transform Mode (all handles)', shortcut: 'transform.combined', execute: () => requestTransformMode(store.shell, 'combined') },
+    { id: 'mode.translate', label: 'Translate Mode', shortcut: 'transform.translate', execute: () => requestTransformMode(store.shell, 'translate') },
+    { id: 'mode.rotate', label: 'Rotate Mode', shortcut: 'transform.rotate', execute: () => requestTransformMode(store.shell, 'rotate') },
+    { id: 'mode.scale', label: 'Scale Mode', shortcut: 'transform.scale', execute: () => requestTransformMode(store.shell, 'scale') },
+    { id: 'mode.world', label: 'World Space', execute: () => store.shell.setTransformSpace('world') },
+    { id: 'mode.local', label: 'Local Space', execute: () => store.shell.setTransformSpace('local') },
+    {
+      id: 'toggle.grid',
+      label: 'Toggle Grid',
+      execute: () => {
+        // The ACTIVE view's grid switch, one per view (`kit/viewport-presentation`).
+        const viewId = activeWorkspaceDocumentId();
+        if (viewId && viewPresentationBinding(viewId)) setViewGridVisible(viewId, !viewGridVisible(viewId));
+      },
+    },
+    { id: 'toggle.helpers', label: 'Toggle Helpers', execute: () => store.shell.toggleHelpers() },
+    { id: 'toggle.stats', label: 'Toggle Stats Overlay', execute: () => store.toggleStats() },
+    { id: 'toggle.snap', label: 'Toggle Snap', shortcut: 'viewport.toggleSnap', execute: () => store.shell.toggleSnap() },
+    { id: 'toggle.surface-snap', label: 'Toggle Surface Snap', execute: () => store.shell.toggleSnapToSurface() },
+    { id: 'shading.solid', label: 'Material Shading', execute: () => setShading(store, 'solid') },
+    { id: 'shading.clay', label: 'Solid Shading', execute: () => setShading(store, 'clay') },
+    { id: 'shading.wireframe', label: 'Wireframe Shading', execute: () => setShading(store, 'wireframe') },
+    { id: 'shading.unlit', label: 'Unlit Shading', execute: () => setShading(store, 'unlit') },
+    { id: 'shading.normals', label: 'Normal Shading', execute: () => setShading(store, 'normals') },
+    { id: 'shading.overdraw', label: 'Overdraw Shading', execute: () => setShading(store, 'overdraw') },
+    { id: 'view.top', label: 'Top View', shortcut: 'view.top', execute: () => store.shell.setViewPreset('top') },
+    { id: 'view.front', label: 'Front View', shortcut: 'view.front', execute: () => store.shell.setViewPreset('front') },
+    { id: 'view.right', label: 'Right View', shortcut: 'view.right', execute: () => store.shell.setViewPreset('right') },
+    { id: 'view.bottom', label: 'Bottom View', shortcut: 'view.bottom', execute: () => store.shell.setViewPreset('bottom') },
+    { id: 'view.back', label: 'Back View', shortcut: 'view.back', execute: () => store.shell.setViewPreset('back') },
+    { id: 'view.left', label: 'Left View', shortcut: 'view.left', execute: () => store.shell.setViewPreset('left') },
+    { id: 'view.orbitLeft', label: 'Orbit Left', shortcut: 'view.orbitLeft', execute: () => store.shell.stepView('orbit-left') },
+    { id: 'view.orbitRight', label: 'Orbit Right', shortcut: 'view.orbitRight', execute: () => store.shell.stepView('orbit-right') },
+    { id: 'view.orbitUp', label: 'Orbit Up', shortcut: 'view.orbitUp', execute: () => store.shell.stepView('orbit-up') },
+    { id: 'view.orbitDown', label: 'Orbit Down', shortcut: 'view.orbitDown', execute: () => store.shell.stepView('orbit-down') },
+    { id: 'view.opposite', label: 'Opposite View', shortcut: 'view.opposite', execute: () => store.shell.stepView('opposite') },
+    { id: 'view.rollLeft', label: 'Roll Left', shortcut: 'view.rollLeft', execute: () => store.shell.stepView('roll-left') },
+    { id: 'view.rollRight', label: 'Roll Right', shortcut: 'view.rollRight', execute: () => store.shell.stepView('roll-right') },
+    { id: 'view.all', label: 'Frame All', shortcut: 'view.all', execute: () => store.shell.frameAll() },
+    { id: 'view.zoomIn', label: 'Zoom In', shortcut: 'view.zoomIn', execute: () => store.shell.zoomView(1) },
+    { id: 'view.zoomOut', label: 'Zoom Out', shortcut: 'view.zoomOut', execute: () => store.shell.zoomView(-1) },
+    { id: 'view.perspective', label: 'Perspective View', shortcut: 'view.perspective', execute: () => store.shell.setViewPreset('perspective') },
+    { id: 'view.projection', label: 'Perspective/Orthographic', shortcut: 'view.projection', execute: () => store.shell.toggleProjection() },
+    { id: 'view.camera', label: 'Camera View', shortcut: 'view.camera', execute: () => store.shell.toggleCameraView() },
+    { id: 'focus.selected', label: 'Focus Selected', shortcut: 'viewport.frameSelection', execute: () => store.shell.focusOnSelection() },
+  ];
+  const contribution: ActionContribution = {
+    actions: () => [...fixed, ...cameraActions()],
+    subscribe: subscribeCameraAuthoring,
+  };
+  return registerContributedActions(contribution);
+}

package/src/kit/viewport-authoring-policy.ts

@@ -0,0 +1,154 @@
+/**
+ * WHAT THE GIZMO VIEWPORT ASKS THE SHELL — the one collaborator
+ * `editor-viewport.ts` declares and the shell installs at boot.
+ *
+ * ARCHITECTURE-CORE §Editor chrome, "The viewport stack is separable": a
+ * surface below the shell never imports the shell's transport, a world
+ * authoring adapter, or project discovery. The viewport was importing six
+ * `authoring/` modules to ask four questions —
+ *
+ *   · which adapter am I driving, and which one do the shared panels drive?
+ *   · what is under the pointer?
+ *   · which native root owns the current selection, and is it painted here?
+ *   · which three root is world-hidden, and how do I apply that?
+ *
+ * — and every one of those answers is a COMPOSITE fact. `layered-pick.ts`
+ * walks `CompositeAuthoringAdapter.childAdapters()` in manifest z-order;
+ * `panel-authoring.ts` reaches the workspace-document registry;
+ * `world-hidden-viewport.ts` and `viewport-tool-context.ts` resolve the
+ * composite's live three child. The viewport itself knows about none of that:
+ * it raycasts a scene and drags a gizmo. Measured, those six edges were 96 of
+ * its 193 files.
+ *
+ * ## The default is the NO-SHELL answer, and it is deliberate
+ *
+ * {@link DEFAULT_VIEWPORT_AUTHORING_POLICY} is what a viewport mounted with no
+ * shell above it (a bounded host; a fixture) gets: no composite exists,
+ * so there are no layers to walk, no other panel to agree with, no world-group
+ * eye to honour. Each default states that outright rather than half-answering.
+ * The ONE default that is real logic is {@link adapterOnlyToolOwner} — the
+ * structural single-adapter fallback `resolveViewportToolContext` already used
+ * for non-composite adapters, which lives here now and is imported BACK by
+ * `authoring/viewport-tool-context.ts` so there is one copy of it.
+ *
+ * In the editor the shell policy is installed once by `EditorProvider`
+ * (`EditorContext.tsx`), before any viewport mounts — including the Asset Lab
+ * document's own, which is why that document keeps today's behaviour exactly.
+ * The install site is the PROVIDER rather than `the world root's stage` because a
+ * workspace can have an Asset Lab document open with no scene the world root's stage
+ * mounted at all, and that document's viewport must not silently fall to the
+ * defaults.
+ */
+
+import type { AuthoringAdapter } from '@volter/editor-project/adapter';
+import { adapterOnlyToolOwner, type ViewportToolOwner } from '@volter/editor-sdk/kit/authoring/viewport-tool-owner';
+
+export { adapterOnlyToolOwner, type ViewportToolOwner };
+import type * as THREE from 'three';
+import { makeNoAuthoringAdapter } from '@volter/editor-sdk/kit/authoring/no-authoring-adapter';
+import type { ShellStore } from '@volter/editor-sdk/kit/shell-store';
+
+
+export interface ViewportAuthoringPolicy {
+  /** The adapter this viewport drives when its host injected none. */
+  activeAuthoring(store: ShellStore): AuthoringAdapter;
+  /**
+   * The adapter a selection SCOPE is keyed on — the Hierarchy's own resolution,
+   * so a viewport drill-in and the panel breadcrumb name the same scope.
+   */
+  panelAuthoring(store: ShellStore): AuthoringAdapter;
+  /** Topmost-first hit test across every visible, pick-unlocked layer. */
+  pick(
+    store: ShellStore,
+    clientX: number,
+    clientY: number,
+    intent: 'normal' | 'deep',
+  ): string | null;
+  /** Which native root the selection resolves to, or `null` for empty,
+   *  organizational and cross-root selections. */
+  toolOwner(adapter: AuthoringAdapter, selectedIds: Iterable<string>): ViewportToolOwner | null;
+  /** Is that owner's surface actually PAINTED in this viewport right now? */
+  toolOwnerPainted(store: ShellStore, owner: ViewportToolOwner | null): boolean;
+  /** Is a THREE stage painted here at all, selection or not — the gate for
+   *  the grid and axis lines (Blender's floor is persistent; only the gizmos
+   *  need an owner). */
+  threeSurfaceShowing(store: ShellStore, adapter: AuthoringAdapter): boolean;
+  /** The one three world rendered here, for the world-hidden eye. */
+  threeViewportRootId(store: ShellStore): string | null;
+  /** Apply the eye to every entity object (a no-op unless that root is hidden). */
+  applyRootHiddenVisibility(
+    objectMap: ReadonlyMap<string, THREE.Object3D>,
+    threeRootId: string | null,
+  ): void;
+  /** The scene-level half of the eye: background, fog, IBL, env objects. */
+  suppressRootEnvironment(scene: THREE.Scene): void;
+}
+
+
+/** Memoized per store, because the viewport calls `activeAuthoring` per gesture
+ *  and adapter IDENTITY keys the selection scope and the handle cache. Mirrors
+ *  `authoring/active-adapter.ts`'s own per-store memo. */
+const _noAuthoringByStore = new WeakMap<ShellStore, AuthoringAdapter>();
+
+export const DEFAULT_VIEWPORT_AUTHORING_POLICY: ViewportAuthoringPolicy = {
+  activeAuthoring(store) {
+    let adapter = _noAuthoringByStore.get(store);
+    if (!adapter) {
+      adapter = makeNoAuthoringAdapter(store, 'No authoring adapter');
+      _noAuthoringByStore.set(store, adapter);
+    }
+    return adapter;
+  },
+  panelAuthoring(store) {
+    // No shell means no shared panels to agree with.
+    return DEFAULT_VIEWPORT_AUTHORING_POLICY.activeAuthoring(store);
+  },
+  pick() {
+    // No shell means no layer stack to walk. A host that mounts this viewport
+    // for one document supplies its own hit test (`EditorViewportOptions.pick`),
+    // which is what the Asset Lab document does.
+    return null;
+  },
+  toolOwner: adapterOnlyToolOwner,
+  toolOwnerPainted() {
+    // No world-group eyes exist without a composite, so nothing can be hidden.
+    return true;
+  },
+  threeSurfaceShowing(_store, adapter) {
+    return !adapter.rects && typeof adapter.hierarchy.object3D === 'function';
+  },
+  threeViewportRootId() {
+    return null;
+  },
+  applyRootHiddenVisibility() {
+    // Unreachable while `threeViewportRootId` is null — stated rather than
+    // implemented, so the no-shell story is one story.
+  },
+  suppressRootEnvironment() {},
+};
+
+let _policy: ViewportAuthoringPolicy = DEFAULT_VIEWPORT_AUTHORING_POLICY;
+
+/**
+ * Install the shell's composition. One owner, same rule as the store's
+ * `attachHistory`/`attachStatePersistence`: re-installing the SAME policy is a
+ * no-op (React strict-mode double-invokes the provider body), a DIFFERENT one
+ * throws rather than letting two shells disagree about what is under a pointer.
+ */
+export function installViewportAuthoringPolicy(policy: ViewportAuthoringPolicy): void {
+  if (_policy === policy) return;
+  if (_policy !== DEFAULT_VIEWPORT_AUTHORING_POLICY) {
+    throw new Error('A viewport authoring policy is already installed.');
+  }
+  _policy = policy;
+}
+
+/** The installed policy, or the no-shell default. */
+export function viewportAuthoringPolicy(): ViewportAuthoringPolicy {
+  return _policy;
+}
+
+/** Test seam: drop the installed policy. */
+export function __resetViewportAuthoringPolicyForTest(): void {
+  _policy = DEFAULT_VIEWPORT_AUTHORING_POLICY;
+}