@opsydyn/effect-three 0.2.0 → 0.3.0

package/src/kernel/sceneGraph.ts

@@ -21,10 +21,12 @@ import {
   OrthographicCamera,
   PerspectiveCamera,
   PointLight,
+  Quaternion,
   Scene,
   SpotLight,
   Vector3,
 } from 'three';
+import { clone as cloneSkinned } from 'three/addons/utils/SkeletonUtils.js';
 
 import { clipRunning, clipTime } from './animation.ts';
 import { writeRotation } from './behaviours.ts';
@@ -32,6 +34,7 @@ import { type BodyCollision, type BodyContactForce, createBodyHost } from './bod
 import { type BodySource, instanceSources, nodeSource, placeObject } from './bodySources.ts';
 import { renderSettings, scene as describeScene } from './build.ts';
 import { type CameraMotion, createCameraMotion } from './cameraMotion.ts';
+import { type CameraShaker, createCameraShaker } from './cameraShake.ts';
 import type {
   AmbientLightNode,
   BorrowedNode,
@@ -426,6 +429,14 @@ const noInstances: ReadonlyArray<Instance> = [];
 const emptyScene = describeScene({});
 
 /** Creates an empty scene graph. */
+/**
+ * A copy of a lent object for a second place to show it, sharing its geometry and
+ * materials, as Drei's `Clone` (`bf6f4ad`, `src/core/Clone.tsx`): a skinned model through
+ * three's `SkeletonUtils.clone`, so that the copy has bones of its own to animate.
+ */
+const cloneLoan = (lent: Object3D): Object3D =>
+  lent.getObjectByProperty('isSkinnedMesh', true) === undefined ? lent.clone() : cloneSkinned(lent);
+
 export const createSceneGraph = (options: SceneGraphOptions = {}): SceneGraph => {
   const store = options.store ?? createResourceStore();
   const ownsStore = options.store === undefined;
@@ -470,8 +481,22 @@ export const createSceneGraph = (options: SceneGraphOptions = {}): SceneGraph =>
     hostedSky = undefined;
   }
   const cameraMotion = createCameraMotion();
+  const cameraShaker = createCameraShaker();
   /** Each view's camera motion, by the view's key. */
   const viewMotions = new Map<string, CameraMotion>();
+  /** Each view's camera shake, by the view's key. */
+  const viewShakers = new Map<string, CameraShaker>();
+  const shaking = (): boolean => {
+    if (cameraShaker.shaking(elapsed)) return true;
+    for (const shaker of viewShakers.values()) if (shaker.shaking(elapsed)) return true;
+    return false;
+  };
+  /** Shakes a view's camera on top of where its motion aims it. */
+  const shakeView = (view: HostedView): void => {
+    const motion = viewMotions.get(view.key);
+    if (motion === undefined) return;
+    viewShakers.get(view.key)?.apply(view.camera, motion.target(), elapsed, animating);
+  };
   const viewsMoving = (): boolean => {
     for (const motion of viewMotions.values()) if (motion.moving()) return true;
     return false;
@@ -505,6 +530,9 @@ export const createSceneGraph = (options: SceneGraphOptions = {}): SceneGraph =>
     applyLens(hostedCamera, description.camera);
     const motion = viewMotions.get(description.key) ?? createCameraMotion();
     viewMotions.set(description.key, motion);
+    const shaker = viewShakers.get(description.key) ?? createCameraShaker();
+    viewShakers.set(description.key, shaker);
+    shaker.describe(description.camera.shake, elapsed);
     // As the scene's camera: a new kind of camera has nothing on screen to travel from.
     motion.aim(hostedCamera, description.camera, elapsed, hostedCamera !== previous || !animating);
     const area = areaOf(description.rect);
@@ -520,10 +548,21 @@ export const createSceneGraph = (options: SceneGraphOptions = {}): SceneGraph =>
     for (const key of viewMotions.keys()) {
       if (!described.some((description) => description.key === key)) viewMotions.delete(key);
     }
+    for (const key of viewShakers.keys()) {
+      if (!described.some((description) => description.key === key)) viewShakers.delete(key);
+    }
   };
   const entries = new Map<string, Entry>();
   const keys = new WeakMap<Object3D, string>();
   const spinning = new Set<Entry>();
+  // Billboards: turned towards the camera each frame, after everything else has moved.
+  const facing = new Set<Entry>();
+  const cameraTurn = new Quaternion();
+  const parentTurn = new Quaternion();
+  // Groups with levels of detail: one child shown at a time, by the camera's distance.
+  const detailing = new Set<Entry>();
+  const cameraPlace = new Vector3();
+  const groupPlace = new Vector3();
   const playing = new Set<Borrowing>();
   const registry: Readonly<Record<string, Behaviour>> = {
     ...builtinBehaviours,
@@ -580,6 +619,77 @@ export const createSceneGraph = (options: SceneGraphOptions = {}): SceneGraph =>
     writeRotation(entry.object.rotation, node.rotation, elapsed);
     if (node.rotation._tag === 'Spin') spinning.add(entry);
     else spinning.delete(entry);
+    if (node.rotation._tag === 'Billboard') facing.add(entry);
+    else facing.delete(entry);
+  };
+
+  /**
+   * Drei's `Billboard`: the node's rotation is its parent's world rotation undone, then the
+   * camera's, so its world rotation is the camera's; locked axes go back to 0.
+   */
+  const faceCamera = (entry: Entry): void => {
+    if (!isPlaced(entry) || entry.node.rotation._tag !== 'Billboard') return;
+    const { lockX, lockY, lockZ } = entry.node.rotation;
+    const object = entry.object;
+    parentTurn.identity();
+    object.parent?.getWorldQuaternion(parentTurn);
+    object.quaternion.copy(cameraTurn).premultiply(parentTurn.invert());
+    if (lockX) object.rotation.x = 0;
+    if (lockY) object.rotation.y = 0;
+    if (lockZ) object.rotation.z = 0;
+  };
+
+  /** The object of a group's `index`th child, as described. */
+  const childObject = (node: GroupNode, index: number): Object3D | undefined => {
+    const child = node.children[index];
+    return child === undefined ? undefined : entries.get(child.key)?.object;
+  };
+
+  /**
+   * three's `LOD.update`, as Drei's `Detailed` runs it each frame, over the group's children
+   * in order: the first level shows, each later one takes over once the camera is at least
+   * its distance away (less its hysteresis while it shows), and the rest hide.
+   */
+  const showLevel = (entry: Entry): void => {
+    if (entry._tag !== 'Group') return;
+    const { node } = entry;
+    const { detail } = node;
+    if (detail === null) return;
+    const { distances, hysteresis } = detail;
+    const count = node.children.length;
+    if (count < 2) return;
+    entry.object.getWorldPosition(groupPlace);
+    const distance = cameraPlace.distanceTo(groupPlace) / camera.zoom;
+    const first = childObject(node, 0);
+    if (first !== undefined) first.visible = true;
+    let level = 1;
+    for (; level < count; level++) {
+      const object = childObject(node, level);
+      const from = distances[level] ?? Number.NaN;
+      const reach = object?.visible === true ? from - from * hysteresis : from;
+      if (!(distance >= reach)) break;
+      const previous = childObject(node, level - 1);
+      if (previous !== undefined) previous.visible = false;
+      if (object !== undefined) object.visible = true;
+    }
+    for (; level < count; level++) {
+      const object = childObject(node, level);
+      if (object !== undefined) object.visible = false;
+    }
+  };
+
+  const trackDetail = (entry: Entry, node: GroupNode): void => {
+    if (node.detail !== null) {
+      detailing.add(entry);
+      return;
+    }
+    // No longer levels: every child shows again.
+    if (detailing.delete(entry)) {
+      for (let index = 0; index < node.children.length; index++) {
+        const object = childObject(node, index);
+        if (object !== undefined) object.visible = true;
+      }
+    }
   };
 
   const build = (node: SceneNode): Entry => {
@@ -593,6 +703,7 @@ export const createSceneGraph = (options: SceneGraphOptions = {}): SceneGraph =>
         trackInteractive(entry.object, node.interactive);
         // A group following a tracked space shows only once the space is found.
         if (node.follow !== null) entry.object.visible = false;
+        trackDetail(entry, node);
         return entry;
       }
       case 'Mesh': {
@@ -706,12 +817,22 @@ export const createSceneGraph = (options: SceneGraphOptions = {}): SceneGraph =>
     entry.shown = undefined;
     const lent = store.lent(entry.node.id);
     if (lent === undefined) return;
-    const shown = lent.parent === null ? lent : lent.clone();
+    const shown = lent.parent === null ? lent : cloneLoan(lent);
     entry.object.add(shown);
     entry.shown = shown;
+    castShadows(shown, entry.node);
     startPlayer(entry);
   };
 
+  /** Drei's `Clone` shadow shorthands: each mesh casts or receives where asked. */
+  const castShadows = (shown: Object3D, node: BorrowedNode): void => {
+    if (!node.castShadow && !node.receiveShadow) return;
+    shown.traverse((part) => {
+      if (part instanceof Mesh && node.castShadow) part.castShadow = true;
+      if (part instanceof Mesh && node.receiveShadow) part.receiveShadow = true;
+    });
+  };
+
   const stopPlayer = (entry: Borrowing): void => {
     if (entry.player === undefined) return;
     entry.player.mixer.stopAllAction();
@@ -850,6 +971,8 @@ export const createSceneGraph = (options: SceneGraphOptions = {}): SceneGraph =>
   const release = (entry: Entry): void => {
     if (isPlaced(entry)) behaving.delete(entry);
     spinning.delete(entry);
+    facing.delete(entry);
+    detailing.delete(entry);
     moving.delete(entry);
     reparented.delete(entry);
     trackInteractive(entry.object, false);
@@ -1005,6 +1128,9 @@ export const createSceneGraph = (options: SceneGraphOptions = {}): SceneGraph =>
       if (fields.includes('interactive')) trackInteractive(entry.object, next.interactive);
       if (fields.includes('id')) showLoan(entry);
       else if (fields.includes('animation')) startPlayer(entry);
+      if (fields.includes('castShadow') || fields.includes('receiveShadow')) {
+        if (entry.shown !== undefined) castShadows(entry.shown, next);
+      }
       return;
     }
     if (entry._tag === 'Label' && next._tag === 'Label') {
@@ -1023,6 +1149,7 @@ export const createSceneGraph = (options: SceneGraphOptions = {}): SceneGraph =>
       if (fields.includes('rotation')) trackRotation(entry, next);
       if (fields.includes('behaviour')) trackBehaviour(entry, next);
       if (fields.includes('interactive')) trackInteractive(entry.object, next.interactive);
+      if (fields.includes('detail')) trackDetail(entry, next);
       if (fields.includes('follow')) {
         // Back to its own transform, or hidden until the new space is found.
         entry.object.visible = next.follow === null;
@@ -1098,6 +1225,7 @@ export const createSceneGraph = (options: SceneGraphOptions = {}): SceneGraph =>
         applyLens(camera, op.camera);
         // A new kind of camera has nothing on screen to travel from.
         cameraMotion.aim(camera, op.camera, elapsed, camera !== previous || !animating);
+        cameraShaker.describe(op.camera.shake, elapsed);
         fitCamera(camera, viewport);
         return;
       }
@@ -1317,8 +1445,20 @@ export const createSceneGraph = (options: SceneGraphOptions = {}): SceneGraph =>
     behaving.forEach(applyBehaviour);
     cameraMotion.step(camera, elapsed);
     for (const view of views) viewMotions.get(view.key)?.step(view.camera, elapsed);
+    // Shake on top of wherever the cameras are aimed now.
+    cameraShaker.apply(camera, cameraMotion.target(), elapsed, animating);
+    views.forEach(shakeView);
     // Last: a dynamic body's pose is the simulation's, whatever else moved the mesh.
     bodyHost.tick(elapsed, animating);
+    // After the camera and everything a billboard may sit on have moved.
+    if (facing.size > 0) {
+      camera.getWorldQuaternion(cameraTurn);
+      facing.forEach(faceCamera);
+    }
+    if (detailing.size > 0) {
+      camera.getWorldPosition(cameraPlace);
+      detailing.forEach(showLevel);
+    }
   };
 
   const finishTween = (tween: Tween, entry: Entry): void => {
@@ -1408,6 +1548,7 @@ export const createSceneGraph = (options: SceneGraphOptions = {}): SceneGraph =>
           clipsRunning() ||
           cameraMotion.moving() ||
           viewsMoving() ||
+          shaking() ||
           bodyHost.needsFrame())),
     drawn: () => {
       dirty = false;

package/src/runtime/SceneSchema.ts

@@ -7,7 +7,7 @@
  *
  * @module
  */
-import { Schema } from 'effect';
+import { Effect, Schema } from 'effect';
 
 import { handJoints, type SceneNode as KernelSceneNode } from '../kernel/description.ts';
 
@@ -21,10 +21,18 @@ export const Vec3 = Schema.Tuple([Schema.Finite, Schema.Finite, Schema.Finite]);
 /** A rotation axis. */
 export const Axis = Schema.Literals(['x', 'y', 'z']);
 
+/**
+ * Fields added after 0.2.0 decode as their builder's default when absent, so descriptions
+ * stored before them (a camera kept in a Model, say) still decode.
+ */
+const absentAsNull = <S extends Schema.Top>(schema: S) =>
+  Schema.NullOr(schema).pipe(Schema.withDecodingDefaultKey(Effect.succeed(null)));
+const absentAsFalse = Schema.Boolean.pipe(Schema.withDecodingDefaultKey(Effect.succeed(false)));
+
 /** A 24-bit RGB colour, for example `0x3366ff`. */
 export const Rgb = Schema.Int.check(Schema.isBetween({ minimum: 0, maximum: 0xffffff }));
 
-/** Model-owned Euler angles, or a spin behaviour that owns the rotation. */
+/** Model-owned Euler angles, a spin behaviour, or facing the camera (a billboard). */
 export const Rotation = Schema.Union([
   Schema.TaggedStruct('Fixed', { euler: Vec3 }),
   Schema.TaggedStruct('Spin', {
@@ -32,6 +40,11 @@ export const Rotation = Schema.Union([
     radiansPerSecond: Schema.Finite,
     phase: Schema.Finite,
   }),
+  Schema.TaggedStruct('Billboard', {
+    lockX: Schema.Boolean,
+    lockY: Schema.Boolean,
+    lockZ: Schema.Boolean,
+  }),
 ]);
 
 /** Box geometry parameters. */
@@ -84,6 +97,24 @@ export const CapsuleGeometry = Schema.TaggedStruct('Capsule', {
   radialSegments: Segments,
 });
 
+/** Rounded box geometry parameters (Drei's `RoundedBox`). */
+export const RoundedBoxGeometry = Schema.TaggedStruct('RoundedBox', {
+  width: Positive,
+  height: Positive,
+  depth: Positive,
+  radius: NonNegative,
+  smoothness: Schema.Int.check(Schema.isGreaterThanOrEqualTo(1)),
+  bevelSegments: Schema.Int.check(Schema.isGreaterThanOrEqualTo(1)),
+  steps: Schema.Int.check(Schema.isGreaterThanOrEqualTo(1)),
+  creaseAngle: NonNegative,
+});
+
+/** Backdrop geometry parameters (Drei's `Backdrop`). */
+export const BackdropGeometry = Schema.TaggedStruct('Backdrop', {
+  floor: NonNegative,
+  segments: Schema.Int.check(Schema.isGreaterThanOrEqualTo(1)),
+});
+
 /** Ring geometry parameters. */
 export const RingGeometry = Schema.TaggedStruct('Ring', {
   innerRadius: NonNegative,
@@ -132,6 +163,8 @@ export const ShapeGeometry = Schema.Union([
   CapsuleGeometry,
   RingGeometry,
   CircleGeometry,
+  RoundedBoxGeometry,
+  BackdropGeometry,
 ]);
 
 /** A registered behaviour, by name, with numeric parameters. */
@@ -424,6 +457,8 @@ export const BorrowedNode = Schema.TaggedStruct('Borrowed', {
   behaviour: Schema.NullOr(Behave),
   interactive: Schema.Boolean,
   body: Schema.NullOr(Body),
+  castShadow: absentAsFalse,
+  receiveShadow: absentAsFalse,
 });
 
 /** Distance-field text. */
@@ -559,7 +594,7 @@ export const HemisphereLightNode = Schema.TaggedStruct('HemisphereLight', {
 });
 
 /** Any scene node. Groups nest recursively. */
-export const SceneNode: Schema.Codec<KernelSceneNode> = Schema.Union([
+export const SceneNode: Schema.Codec<KernelSceneNode, unknown> = Schema.Union([
   Schema.TaggedStruct('Group', {
     key: Schema.String,
     position: Vec3,
@@ -568,9 +603,12 @@ export const SceneNode: Schema.Codec<KernelSceneNode> = Schema.Union([
     transition: Transition,
     behaviour: Schema.NullOr(Behave),
     interactive: Schema.Boolean,
-    children: Schema.Array(Schema.suspend((): Schema.Codec<KernelSceneNode> => SceneNode)),
+    children: Schema.Array(Schema.suspend((): Schema.Codec<KernelSceneNode, unknown> => SceneNode)),
     body: Schema.NullOr(Body),
     follow: Schema.NullOr(XrSpace),
+    detail: absentAsNull(
+      Schema.Struct({ distances: Schema.Array(NonNegative), hysteresis: NonNegative }),
+    ),
   }),
   MeshNode,
   InstancesNode,
@@ -588,6 +626,20 @@ export const SceneNode: Schema.Codec<KernelSceneNode> = Schema.Union([
 /** The fraction of the way a camera closes every sixtieth of a second: 0 jumps. */
 const CameraDamping = Schema.Finite.check(Schema.isGreaterThanOrEqualTo(0), Schema.isLessThan(1));
 
+/** Camera shake (Drei's `CameraShake`). */
+export const CameraShake = Schema.Struct({
+  intensity: NonNegative,
+  decay: Schema.Boolean,
+  decayRate: NonNegative,
+  maxYaw: NonNegative,
+  maxPitch: NonNegative,
+  maxRoll: NonNegative,
+  yawFrequency: NonNegative,
+  pitchFrequency: NonNegative,
+  rollFrequency: NonNegative,
+  trigger: Schema.Finite,
+});
+
 /** A perspective camera. */
 export const PerspectiveCamera = Schema.TaggedStruct('Perspective', {
   fov: Schema.Finite.check(Schema.isBetween({ minimum: 0, maximum: 180, exclusiveMinimum: true })),
@@ -597,6 +649,7 @@ export const PerspectiveCamera = Schema.TaggedStruct('Perspective', {
   lookAt: Vec3,
   damping: CameraDamping,
   autoRotate: Schema.Finite,
+  shake: absentAsNull(CameraShake),
 });
 
 /** An orthographic camera; `zoom` is CSS pixels per world unit. */
@@ -608,6 +661,7 @@ export const OrthographicCamera = Schema.TaggedStruct('Orthographic', {
   lookAt: Vec3,
   damping: CameraDamping,
   autoRotate: Schema.Finite,
+  shake: absentAsNull(CameraShake),
 });
 
 /** The active camera. */