@volter/editor-game 0.5.65

package/src/three/authoring/reflection-probe-inspector-section.tsx

@@ -0,0 +1,76 @@
+import { useEditorStore } from '@volter/editor-core/editor-runtime';
+import type { InspectorSectionProps } from '@volter/editor-core/inspector-section-registry';
+import type { AuthoringAdapter, EditorNode } from '@volter/editor-project/adapter';
+import { type ReflectionProbeSnapshot, reflectionProbeOf } from '@volter/threejs-runtime/adapter/reflection-probe';
+import { Button, EditorBanner, FieldGroup, FieldRow, Text } from '@volter/editor-sdk/widgets';
+import { useSyncExternalStore } from 'react';
+
+export function matches(node: EditorNode | null, adapter: AuthoringAdapter): boolean {
+  void adapter;
+  return node?.kind === 'reflection-probe';
+}
+
+const STATUS_LABEL: Record<ReflectionProbeSnapshot['status'], string> = {
+  idle: 'Not captured',
+  queued: 'Capture queued',
+  capturing: 'Capturing…',
+  ready: 'Ready',
+  error: 'Capture failed',
+};
+const EMPTY_SNAPSHOT: ReflectionProbeSnapshot = { status: 'idle', lastCapturedAt: null };
+
+export function ReflectionProbeCaptureSection({ adapter, nodeId }: InspectorSectionProps) {
+  const store = useEditorStore();
+  const object = nodeId
+    ? (store.objectMap.get(nodeId) ?? adapter.hierarchy.object3D?.(nodeId))
+    : null;
+  const probe = reflectionProbeOf(object);
+  const snapshot = useSyncExternalStore(
+    (listener) => probe?.subscribe(listener) ?? (() => {}),
+    () => probe?.getSnapshot() ?? EMPTY_SNAPSHOT,
+  );
+  if (!probe) return null;
+  const mode =
+    probe.config.captureMode === 'on-change'
+      ? 'On change'
+      : probe.config.captureMode === 'realtime'
+        ? 'Realtime'
+        : 'Manual';
+  return (
+    <>
+      {snapshot.status === 'error' && snapshot.message ? (
+        <EditorBanner tone="error">{snapshot.message}</EditorBanner>
+      ) : null}
+      <FieldGroup>
+        <FieldRow label="Status">
+          <Text
+            tone={
+              snapshot.status === 'error'
+                ? 'danger'
+                : snapshot.status === 'ready'
+                  ? 'success'
+                  : 'muted'
+            }
+          >
+            {STATUS_LABEL[snapshot.status]}
+          </Text>
+        </FieldRow>
+        <FieldRow label="Update">
+          <Text tone="muted">{mode}</Text>
+        </FieldRow>
+        <FieldRow label="Cubemap">
+          <Text tone="muted">{`${probe.config.resolution} × ${probe.config.resolution}`}</Text>
+        </FieldRow>
+        <FieldRow label="Capture">
+          <Button
+            size="compact"
+            disabled={snapshot.status === 'capturing'}
+            onClick={() => probe.recapture()}
+          >
+            Recapture
+          </Button>
+        </FieldRow>
+      </FieldGroup>
+    </>
+  );
+}

package/src/three/authoring/spatial-audio-handles.ts

@@ -0,0 +1,215 @@
+/**
+ * Positional-audio projection onto the generic spatial-handle seam.
+ *
+ * Web Audio owns every value and Three owns the live object. This module only
+ * translates those native values into world-space guide geometry and turns a
+ * world-space drag point back into one native value. It stores nothing.
+ */
+
+import type { SpatialHandleLayer, SpatialPoint3 } from '@volter/editor-project/adapter';
+import * as THREE from 'three';
+import {
+  applyTypedField,
+  isPositionalAudioObject,
+  type TypedThreeField,
+  typedFieldForPath,
+} from './typed-three-inspector';
+
+const REF_COLOR = '#42c8ff';
+const MAX_COLOR = '#287fb8';
+const INNER_COLOR = '#ffd166';
+const OUTER_COLOR = '#ff9f43';
+const ROUND_TO = 100;
+
+export type AudioHandleId =
+  | 'audio-ref-distance'
+  | 'audio-max-distance'
+  | 'audio-inner-cone'
+  | 'audio-outer-cone';
+
+export interface AudioHandleEdit {
+  readonly field: TypedThreeField;
+  readonly value: number;
+}
+
+function tuple(value: THREE.Vector3): SpatialPoint3 {
+  return [value.x, value.y, value.z];
+}
+
+function worldFrame(object: THREE.Object3D): {
+  origin: THREE.Vector3;
+  forward: THREE.Vector3;
+  right: THREE.Vector3;
+} {
+  object.updateWorldMatrix(true, false);
+  const origin = object.getWorldPosition(new THREE.Vector3());
+  const rotation = object.getWorldQuaternion(new THREE.Quaternion());
+  return {
+    origin,
+    // THREE.PositionalAudio writes this same local +Z orientation into its
+    // PannerNode in updateMatrixWorld().
+    forward: new THREE.Vector3(0, 0, 1).applyQuaternion(rotation).normalize(),
+    right: new THREE.Vector3(1, 0, 0).applyQuaternion(rotation).normalize(),
+  };
+}
+
+function pointOnCone(
+  origin: THREE.Vector3,
+  forward: THREE.Vector3,
+  right: THREE.Vector3,
+  length: number,
+  fullAngleDegrees: number,
+): THREE.Vector3 {
+  const halfAngle = THREE.MathUtils.degToRad(fullAngleDegrees / 2);
+  return origin
+    .clone()
+    .addScaledVector(forward, Math.cos(halfAngle) * length)
+    .addScaledVector(right, Math.sin(halfAngle) * length);
+}
+
+/** Selected-source attenuation and direction, with handles only where the
+ * native parameter currently has visible meaning. Web Audio ignores
+ * maxDistance outside the linear model, so no ring is drawn there. */
+export function positionalAudioHandleLayer(
+  object: THREE.Object3D,
+  writable: (path: string) => boolean,
+): SpatialHandleLayer | null {
+  if (!isPositionalAudioObject(object)) return null;
+  const { origin, forward, right } = worldFrame(object);
+  const refDistance = object.getRefDistance();
+  const maxDistance = object.getMaxDistance();
+  const distanceModel = object.getDistanceModel();
+  const innerAngle = object.panner.coneInnerAngle;
+  const outerAngle = object.panner.coneOuterAngle;
+  const directional = outerAngle < 359.5;
+  const coneLength = Math.max(1, Math.min(8, refDistance * 2.5));
+
+  const guides: SpatialHandleLayer['guides'][number][] = [
+    {
+      kind: 'sphere',
+      center: tuple(origin),
+      radius: refDistance,
+      color: REF_COLOR,
+      opacity: 0.75,
+    },
+  ];
+  const handles: SpatialHandleLayer['handles'][number][] = [
+    {
+      id: 'audio-ref-distance',
+      label: 'Reference distance',
+      position: tuple(origin.clone().addScaledVector(right, refDistance)),
+      color: REF_COLOR,
+      writable: writable('audio.refDistance'),
+    },
+  ];
+
+  if (distanceModel === 'linear') {
+    guides.push({
+      kind: 'sphere',
+      center: tuple(origin),
+      radius: maxDistance,
+      color: MAX_COLOR,
+      opacity: 0.42,
+      dashed: true,
+    });
+    handles.push({
+      id: 'audio-max-distance',
+      label: 'Maximum distance',
+      position: tuple(origin.clone().addScaledVector(right, maxDistance)),
+      color: MAX_COLOR,
+      writable: writable('audio.maxDistance'),
+    });
+  }
+
+  if (directional) {
+    guides.push({
+      kind: 'cone',
+      origin: tuple(origin),
+      direction: tuple(forward),
+      length: coneLength,
+      angle: outerAngle,
+      color: OUTER_COLOR,
+      opacity: 0.72,
+    });
+    handles.push({
+      id: 'audio-outer-cone',
+      label: 'Outer cone angle',
+      position: tuple(pointOnCone(origin, forward, right, coneLength, outerAngle)),
+      color: OUTER_COLOR,
+      writable: writable('audio.coneOuterAngle'),
+    });
+    if (innerAngle < 359.5) {
+      guides.push({
+        kind: 'cone',
+        origin: tuple(origin),
+        direction: tuple(forward),
+        length: coneLength,
+        angle: innerAngle,
+        color: INNER_COLOR,
+        opacity: 0.58,
+        dashed: true,
+      });
+      handles.push({
+        id: 'audio-inner-cone',
+        label: 'Inner cone angle',
+        position: tuple(pointOnCone(origin, forward, right, coneLength, innerAngle)),
+        color: INNER_COLOR,
+        writable: writable('audio.coneInnerAngle'),
+      });
+    }
+  }
+
+  return { id: 'positional-audio', category: 'audio', guides, handles };
+}
+
+function rounded(value: number): number {
+  return Math.round(value * ROUND_TO) / ROUND_TO;
+}
+
+/** Translate a drag point into the one inspector/source field it edits. */
+export function positionalAudioEditFromWorld(
+  object: THREE.Object3D,
+  sourceTag: string | undefined,
+  handleId: string,
+  worldPosition: SpatialPoint3,
+): AudioHandleEdit | null {
+  if (!isPositionalAudioObject(object)) return null;
+  const { origin, forward } = worldFrame(object);
+  const point = new THREE.Vector3(...worldPosition);
+  const delta = point.sub(origin);
+  let path: string;
+  let value: number;
+
+  switch (handleId as AudioHandleId) {
+    case 'audio-ref-distance':
+      path = 'audio.refDistance';
+      value = Math.max(0.01, rounded(delta.length()));
+      break;
+    case 'audio-max-distance':
+      path = 'audio.maxDistance';
+      value = Math.max(object.getRefDistance() + 0.01, rounded(delta.length()));
+      break;
+    case 'audio-inner-cone':
+    case 'audio-outer-cone': {
+      path = handleId === 'audio-inner-cone' ? 'audio.coneInnerAngle' : 'audio.coneOuterAngle';
+      // Keep the signed axial component: angles above 180 degrees place the
+      // cone rim behind the source, and Web Audio legitimately accepts the
+      // full 0..360 range.
+      const axial = delta.dot(forward);
+      const radial = Math.sqrt(Math.max(0, delta.lengthSq() - axial * axial));
+      value = rounded(THREE.MathUtils.radToDeg(Math.atan2(radial, axial)) * 2);
+      break;
+    }
+    default:
+      return null;
+  }
+
+  const field = typedFieldForPath(object, null, path, sourceTag);
+  return field ? { field, value } : null;
+}
+
+/** Apply only to the live native object; source persistence is the adapter's
+ * commit step and happens once at pointer-up. */
+export function previewPositionalAudioEdit(object: THREE.Object3D, edit: AudioHandleEdit): void {
+  applyTypedField(object, null, edit.field, edit.value);
+}

package/src/three/authoring/spatial-collider-handles.ts

@@ -0,0 +1,229 @@
+/** Native Rapier primitive colliders projected onto the generic viewport seam. */
+
+import type {
+  PhysicsColliderShape,
+  PhysicsColliderSnapshot,
+  SpatialHandleLayer,
+  SpatialPoint3,
+} from '@volter/editor-project/adapter';
+import * as THREE from 'three';
+
+const COLLIDER_COLOR = '#00e58a';
+const SENSOR_COLOR = '#c77dff';
+const MIN_DIMENSION = 0.01;
+const ROUND_TO = 1000;
+
+export interface ColliderSourceBinding {
+  readonly sourceOid: string;
+  readonly sourceTag: 'CuboidCollider' | 'BallCollider' | 'CapsuleCollider';
+  readonly snapshot: PhysicsColliderSnapshot;
+  readonly writable: boolean;
+}
+
+export interface ColliderHandleEdit {
+  readonly sourceOid: string;
+  readonly args: readonly number[];
+  readonly shape: PhysicsColliderShape;
+  readonly colliderId: string;
+}
+
+function rounded(value: number): number {
+  return Math.round(value * ROUND_TO) / ROUND_TO;
+}
+
+function tuple(value: THREE.Vector3): SpatialPoint3 {
+  return [value.x, value.y, value.z];
+}
+
+function frame(snapshot: PhysicsColliderSnapshot): {
+  center: THREE.Vector3;
+  rotation: THREE.Quaternion;
+} {
+  return {
+    center: new THREE.Vector3(...snapshot.position),
+    rotation: new THREE.Quaternion(...snapshot.rotation),
+  };
+}
+
+function worldPoint(
+  snapshot: PhysicsColliderSnapshot,
+  local: readonly [number, number, number],
+): SpatialPoint3 {
+  const { center, rotation } = frame(snapshot);
+  return tuple(new THREE.Vector3(...local).applyQuaternion(rotation).add(center));
+}
+
+function handleId(binding: ColliderSourceBinding, part: string): string {
+  return `collider:${encodeURIComponent(binding.sourceOid)}:${part}`;
+}
+
+export function colliderHandleLayer(binding: ColliderSourceBinding): SpatialHandleLayer {
+  const { snapshot } = binding;
+  const color = snapshot.sensor ? SENSOR_COLOR : COLLIDER_COLOR;
+  const common = { color, writable: binding.writable };
+  const guides: SpatialHandleLayer['guides'][number][] = [];
+  const handles: SpatialHandleLayer['handles'][number][] = [];
+
+  switch (snapshot.shape.type) {
+    case 'cuboid': {
+      const halfExtents = snapshot.shape.halfExtents;
+      guides.push({
+        kind: 'box',
+        center: snapshot.position,
+        rotation: snapshot.rotation,
+        halfExtents,
+        color,
+        opacity: 0.78,
+      });
+      for (const [axis, label] of [
+        [0, 'X'],
+        [1, 'Y'],
+        [2, 'Z'],
+      ] as const) {
+        for (const sign of [-1, 1] as const) {
+          const local: [number, number, number] = [0, 0, 0];
+          local[axis] = halfExtents[axis] * sign;
+          handles.push({
+            id: handleId(binding, `${axis}:${sign}`),
+            label: `${label} ${sign > 0 ? 'positive' : 'negative'} half extent`,
+            position: worldPoint(snapshot, local),
+            ...common,
+          });
+        }
+      }
+      break;
+    }
+    case 'ball':
+      guides.push({
+        kind: 'sphere',
+        center: snapshot.position,
+        radius: snapshot.shape.radius,
+        color,
+        opacity: 0.78,
+      });
+      handles.push({
+        id: handleId(binding, 'radius'),
+        label: 'Collider radius',
+        position: worldPoint(snapshot, [snapshot.shape.radius, 0, 0]),
+        ...common,
+      });
+      break;
+    case 'capsule':
+      guides.push({
+        kind: 'capsule',
+        center: snapshot.position,
+        rotation: snapshot.rotation,
+        radius: snapshot.shape.radius,
+        halfHeight: snapshot.shape.halfHeight,
+        color,
+        opacity: 0.78,
+      });
+      handles.push(
+        {
+          id: handleId(binding, 'radius'),
+          label: 'Collider radius',
+          position: worldPoint(snapshot, [snapshot.shape.radius, 0, 0]),
+          ...common,
+        },
+        {
+          id: handleId(binding, 'half-height'),
+          label: 'Collider half height',
+          position: worldPoint(snapshot, [0, snapshot.shape.halfHeight + snapshot.shape.radius, 0]),
+          ...common,
+        },
+      );
+      break;
+    // A shape the physics seam does not project (trimesh, heightfield, hull,
+    // cylinder, cone, …). It gets no guide and no handles because we do not
+    // know its geometry — but it is NOT dropped upstream any more, so a body
+    // carrying one still reports having physics rather than reporting none.
+    case 'unsupported':
+      break;
+  }
+
+  return {
+    id: `collider:${binding.sourceOid}`,
+    category: 'colliders',
+    guides,
+    handles,
+  };
+}
+
+function parseHandleId(handle: string): { oid: string; part: string } | null {
+  if (!handle.startsWith('collider:')) return null;
+  const rest = handle.slice('collider:'.length);
+  const separator = rest.indexOf(':');
+  if (separator < 1) return null;
+  try {
+    return { oid: decodeURIComponent(rest.slice(0, separator)), part: rest.slice(separator + 1) };
+  } catch {
+    return null;
+  }
+}
+
+function safeScale(value: number): number {
+  return value > 1e-8 ? value : 1;
+}
+
+/** Convert one world-space drag point into @react-three/rapier's native args
+ * and the live scaled Rapier shape used for immediate preview. */
+export function colliderEditFromWorld(
+  bindings: readonly ColliderSourceBinding[],
+  handle: string,
+  worldPosition: SpatialPoint3,
+): ColliderHandleEdit | null {
+  const parsed = parseHandleId(handle);
+  const binding = parsed ? bindings.find((candidate) => candidate.sourceOid === parsed.oid) : null;
+  if (!binding || !parsed || !binding.writable) return null;
+  const { center, rotation } = frame(binding.snapshot);
+  const local = new THREE.Vector3(...worldPosition)
+    .sub(center)
+    .applyQuaternion(rotation.clone().invert());
+  const shape = binding.snapshot.shape;
+  const scale = binding.snapshot.scale.map(safeScale) as [number, number, number];
+
+  if (shape.type === 'cuboid' && /^[012]:(?:-1|1)$/.test(parsed.part)) {
+    const axis = Number(parsed.part[0]) as 0 | 1 | 2;
+    const halfExtents: [number, number, number] = [...shape.halfExtents];
+    halfExtents[axis] = Math.max(MIN_DIMENSION, rounded(Math.abs(local.getComponent(axis))));
+    return {
+      sourceOid: binding.sourceOid,
+      colliderId: binding.snapshot.id,
+      shape: { type: 'cuboid', halfExtents },
+      args: halfExtents.map((value, index) => rounded(value / scale[index]!)),
+    };
+  }
+
+  if (shape.type === 'ball' && parsed.part === 'radius') {
+    const radius = Math.max(MIN_DIMENSION, rounded(local.length()));
+    return {
+      sourceOid: binding.sourceOid,
+      colliderId: binding.snapshot.id,
+      shape: { type: 'ball', radius },
+      args: [rounded(radius / scale[0])],
+    };
+  }
+
+  if (shape.type === 'capsule') {
+    if (parsed.part === 'radius') {
+      const radius = Math.max(MIN_DIMENSION, rounded(Math.hypot(local.x, local.z)));
+      return {
+        sourceOid: binding.sourceOid,
+        colliderId: binding.snapshot.id,
+        shape: { ...shape, radius },
+        args: [rounded(shape.halfHeight / scale[0]), rounded(radius / scale[1])],
+      };
+    }
+    if (parsed.part === 'half-height') {
+      const halfHeight = Math.max(MIN_DIMENSION, rounded(Math.abs(local.y) - shape.radius));
+      return {
+        sourceOid: binding.sourceOid,
+        colliderId: binding.snapshot.id,
+        shape: { ...shape, halfHeight },
+        args: [rounded(halfHeight / scale[0]), rounded(shape.radius / scale[1])],
+      };
+    }
+  }
+
+  return null;
+}

package/src/three/authoring/spatial-joint-handles.ts

@@ -0,0 +1,114 @@
+/** Native Rapier impulse-joint anchors projected onto generic viewport guides. */
+
+import type { R3fJointBinding, R3fJointLiteral } from '@volter/editor-core/ui-source/r3f-joint-binding';
+import type { PhysicsJointSnapshot, SpatialHandleLayer, SpatialPoint3 } from '@volter/editor-project/adapter';
+import * as THREE from 'three';
+
+const JOINT_COLOR = '#ffb020';
+const ROUND_TO = 1000;
+
+export interface JointSourceBinding {
+  readonly sourceOid: string;
+  readonly sourceFile: string;
+  readonly source: R3fJointBinding;
+  readonly snapshot: PhysicsJointSnapshot;
+  readonly writable: boolean;
+}
+
+export interface JointAnchorEdit {
+  readonly binding: JointSourceBinding;
+  readonly endpoint: 0 | 1;
+  readonly anchor: readonly [number, number, number];
+  readonly params: readonly R3fJointLiteral[];
+}
+
+function key(binding: JointSourceBinding): string {
+  return `${binding.source.line}:${binding.source.col}`;
+}
+
+function handleId(binding: JointSourceBinding, endpoint: 0 | 1): string {
+  return `joint:${key(binding)}:${endpoint}`;
+}
+
+export function jointHandleLayer(binding: JointSourceBinding): SpatialHandleLayer {
+  const snapshot = binding.snapshot;
+  const guides: SpatialHandleLayer['guides'][number][] = [
+    {
+      kind: 'line',
+      points: [snapshot.worldAnchor1, snapshot.worldAnchor2],
+      color: JOINT_COLOR,
+      opacity: 0.9,
+    },
+  ];
+  if (snapshot.worldAxis) {
+    const origin = new THREE.Vector3(...snapshot.worldAnchor1);
+    const axis = new THREE.Vector3(...snapshot.worldAxis).normalize();
+    guides.push({
+      kind: 'line',
+      points: [
+        [origin.x - axis.x, origin.y - axis.y, origin.z - axis.z],
+        [origin.x + axis.x, origin.y + axis.y, origin.z + axis.z],
+      ],
+      color: '#ffd166',
+      opacity: 0.82,
+      dashed: true,
+    });
+  }
+  return {
+    id: `joint:${key(binding)}`,
+    category: 'joints',
+    guides,
+    handles: [
+      {
+        id: handleId(binding, 0),
+        label: 'Joint anchor A',
+        position: snapshot.worldAnchor1,
+        color: JOINT_COLOR,
+        writable: binding.writable,
+      },
+      {
+        id: handleId(binding, 1),
+        label: 'Joint anchor B',
+        position: snapshot.worldAnchor2,
+        color: JOINT_COLOR,
+        writable: binding.writable,
+      },
+    ],
+  };
+}
+
+function rounded(value: number): number {
+  return Math.round(value * ROUND_TO) / ROUND_TO;
+}
+
+function parsedHandle(handle: string): { key: string; endpoint: 0 | 1 } | null {
+  const match = /^joint:(\d+:\d+):([01])$/.exec(handle);
+  return match ? { key: match[1]!, endpoint: Number(match[2]) as 0 | 1 } : null;
+}
+
+function anchorParamIndex(binding: JointSourceBinding, endpoint: 0 | 1): number {
+  return binding.source.hook === 'useFixedJoint' && endpoint === 1 ? 2 : endpoint;
+}
+
+/** Convert a world drag point back to the native hook's body-local anchor. */
+export function jointAnchorEditFromWorld(
+  bindings: readonly JointSourceBinding[],
+  handle: string,
+  worldPosition: SpatialPoint3,
+): JointAnchorEdit | null {
+  const parsed = parsedHandle(handle);
+  const binding = parsed ? bindings.find((candidate) => key(candidate) === parsed.key) : undefined;
+  if (!binding || !parsed || !binding.writable || !binding.source.params) return null;
+  const snapshot = binding.snapshot;
+  const position = parsed.endpoint === 0 ? snapshot.body1Position : snapshot.body2Position;
+  const rotation = parsed.endpoint === 0 ? snapshot.body1Rotation : snapshot.body2Rotation;
+  const local = new THREE.Vector3(...worldPosition)
+    .sub(new THREE.Vector3(...position))
+    .applyQuaternion(new THREE.Quaternion(...rotation).invert());
+  const anchor: [number, number, number] = [rounded(local.x), rounded(local.y), rounded(local.z)];
+  const params = binding.source.params.map((value) =>
+    Array.isArray(value) ? [...value] : value,
+  ) as R3fJointLiteral[];
+  params[anchorParamIndex(binding, parsed.endpoint)] = anchor;
+  return { binding, endpoint: parsed.endpoint, anchor, params };
+}