@opsydyn/effect-three 0.2.0 → 0.4.0

package/src/kernel/build.ts

@@ -3,9 +3,18 @@
  *
  * @module
  */
+import { CatmullRomCurve3, Color, CubicBezierCurve3, QuadraticBezierCurve3, Vector3 } from 'three';
+
 import type {
   AmbientLightNode,
+  LineNode,
+  PointLook,
+  PointsNode,
+  Edges,
+  Trail,
   Animation,
+  CameraShake,
+  Detail,
   BasicMaterial,
   Body,
   Behave,
@@ -16,6 +25,8 @@ import type {
   ContactShadows,
   Environment,
   Gestures,
+  Hud,
+  HudAlignment,
   GridNode,
   Sky,
   Xr,
@@ -40,6 +51,8 @@ import type {
   ColliderDescription,
   ColliderShapeDescription,
   CapsuleGeometry,
+  RoundedBoxGeometry,
+  BackdropGeometry,
   CircleGeometry,
   ConeGeometry,
   CylinderGeometry,
@@ -106,6 +119,21 @@ export const spin = (options: {
   phase: options.phase ?? 0,
 });
 
+/**
+ * Faces the camera every frame, as Drei's `Billboard` (`bf6f4ad`, `src/core/Billboard.tsx`):
+ * for labels, markers and sprites that should always read face on. Lock an axis to keep
+ * it still, `lockX` and `lockZ` together for something that stays upright and only turns
+ * round. To rotate it as well, put it in a rotated group.
+ */
+export const billboard = (
+  options: { readonly lockX?: boolean; readonly lockY?: boolean; readonly lockZ?: boolean } = {},
+): Rotation => ({
+  _tag: 'Billboard',
+  lockX: options.lockX ?? false,
+  lockY: options.lockY ?? false,
+  lockZ: options.lockZ ?? false,
+});
+
 /** Box geometry. Each dimension defaults to 1. */
 export const box = (
   size: { readonly width?: number; readonly height?: number; readonly depth?: number } = {},
@@ -197,6 +225,47 @@ export const capsule = (
   radialSegments: options.radialSegments ?? 8,
 });
 
+/**
+ * A box with rounded edges and corners, as Drei's `RoundedBox` (`bf6f4ad`,
+ * `src/core/RoundedBox.tsx`), with its defaults: 1 × 1 × 1, radius 0.05, smoothness 4,
+ * 4 bevel segments, 1 step, crease angle 0.4.
+ */
+export const roundedBox = (
+  options: {
+    readonly width?: number;
+    readonly height?: number;
+    readonly depth?: number;
+    readonly radius?: number;
+    readonly smoothness?: number;
+    readonly bevelSegments?: number;
+    readonly steps?: number;
+    readonly creaseAngle?: number;
+  } = {},
+): RoundedBoxGeometry => ({
+  _tag: 'RoundedBox',
+  width: options.width ?? 1,
+  height: options.height ?? 1,
+  depth: options.depth ?? 1,
+  radius: options.radius ?? 0.05,
+  smoothness: options.smoothness ?? 4,
+  bevelSegments: options.bevelSegments ?? 4,
+  steps: options.steps ?? 1,
+  creaseAngle: options.creaseAngle ?? 0.4,
+});
+
+/**
+ * A curved photo backdrop, as Drei's `Backdrop` (`bf6f4ad`, `src/core/Backdrop.tsx`), with
+ * its defaults: floor 0.25, 20 segments. One unit each way: scale the mesh to size, and
+ * give it `receiveShadow` to catch shadows as Drei's prop does.
+ */
+export const backdrop = (
+  options: { readonly floor?: number; readonly segments?: number } = {},
+): BackdropGeometry => ({
+  _tag: 'Backdrop',
+  floor: options.floor ?? 0.25,
+  segments: options.segments ?? 20,
+});
+
 /** Ring geometry facing +Z. Defaults (as three.js): radii 0.5 and 1, 32 segments. */
 export const ring = (
   options: {
@@ -284,6 +353,7 @@ export const basic = (options: Partial<Omit<BasicMaterial, '_tag'>> = {}): Basic
   transparent: options.transparent ?? false,
   side: options.side ?? 'front',
   wireframe: options.wireframe ?? false,
+  depthTest: options.depthTest ?? true,
 });
 
 /**
@@ -478,6 +548,8 @@ export const group = (
     readonly children?: ReadonlyArray<SceneNode>;
     readonly body?: Body | null;
     readonly follow?: XrSpace | null;
+    readonly detail?: Detail | null;
+    readonly trail?: Trail | null;
   },
 ): GroupNode => ({
   _tag: 'Group',
@@ -491,8 +563,287 @@ export const group = (
   children: options.children ?? [],
   body: options.body ?? null,
   follow: options.follow ?? null,
+  detail: options.detail ?? null,
+  trail: options.trail ?? null,
+});
+
+/**
+ * Levels of detail for a group, as Drei's `Detailed` (`bf6f4ad`, `src/core/Detailed.tsx`):
+ * `group({ detail: detailed({ distances: [0, 10, 20] }), children: [near, middle, far] })`
+ * shows `near` until the camera is 10 away, then `middle`, then `far` from 20. Hysteresis
+ * defaults to 0, as Drei's.
+ */
+export const detailed = (options: {
+  readonly distances: ReadonlyArray<number>;
+  readonly hysteresis?: number;
+}): Detail => ({ distances: options.distances, hysteresis: options.hysteresis ?? 0 });
+
+/**
+ * A line through `points`, as Drei's `Line` (`bf6f4ad`, `src/core/Line.tsx`), with its
+ * defaults: white, 1 pixel wide, solid, opaque. three's `LineMaterial` defaults the dashes:
+ * size 1, gap 1, scale 1, offset 0. `segments: true` is Drei's `Segments`: pairs of points.
+ */
+export const line = (
+  options: TransformOptions & {
+    readonly points: ReadonlyArray<Vec3>;
+    readonly segments?: boolean;
+    readonly color?: Rgb;
+    readonly vertexColors?: ReadonlyArray<Rgb> | null;
+    readonly width?: number;
+    readonly worldUnits?: boolean;
+    readonly dashed?: boolean;
+    readonly dashSize?: number;
+    readonly gapSize?: number;
+    readonly dashScale?: number;
+    readonly dashOffset?: number;
+    readonly opacity?: number;
+    readonly transparent?: boolean;
+    readonly interactive?: boolean;
+  },
+): LineNode => ({
+  _tag: 'Line',
+  key: options.key,
+  position: options.position ?? origin,
+  rotation: options.rotation ?? noRotation,
+  scale: options.scale ?? unitScale,
+  transition: options.transition ?? instantTransition,
+  behaviour: options.behaviour ?? null,
+  interactive: options.interactive ?? false,
+  points: options.points,
+  segments: options.segments ?? false,
+  color: options.color ?? 0xffffff,
+  vertexColors: options.vertexColors ?? null,
+  width: options.width ?? 1,
+  worldUnits: options.worldUnits ?? false,
+  dashed: options.dashed ?? false,
+  dashSize: options.dashSize ?? 1,
+  gapSize: options.gapSize ?? 1,
+  dashScale: options.dashScale ?? 1,
+  dashOffset: options.dashOffset ?? 0,
+  opacity: options.opacity ?? 1,
+  transparent: options.transparent ?? false,
 });
 
+const asVector = (point: Vec3): Vector3 => new Vector3(point[0], point[1], point[2]);
+const asVec3 = (point: Vector3): Vec3 => [point.x, point.y, point.z];
+
+/** Where a points node sits, as the other placed nodes. */
+type Placing = Pick<
+  TransformOptions,
+  'key' | 'position' | 'rotation' | 'scale' | 'transition' | 'behaviour'
+>;
+
+const placed = (options: Placing, look: PointLook): PointsNode => ({
+  _tag: 'Points',
+  key: options.key,
+  position: options.position ?? origin,
+  rotation: options.rotation ?? noRotation,
+  scale: options.scale ?? unitScale,
+  transition: options.transition ?? instantTransition,
+  behaviour: options.behaviour ?? null,
+  look,
+});
+
+/**
+ * Dots at `positions`, as Drei's `Points` (`bf6f4ad`, `src/core/Points.tsx`) with its
+ * `PointMaterial`: round, white, 1 pixel (three's `PointsMaterial` size), smaller with
+ * distance. `colors` gives each its own colour, `sizes` a factor on `size`.
+ */
+export const points = (
+  options: Placing & {
+    readonly positions: ReadonlyArray<Vec3>;
+    readonly colors?: ReadonlyArray<Rgb> | null;
+    readonly sizes?: ReadonlyArray<number> | null;
+    readonly color?: Rgb;
+    readonly size?: number;
+    readonly sizeAttenuation?: boolean;
+    readonly round?: boolean;
+    readonly opacity?: number;
+    readonly transparent?: boolean;
+  },
+): PointsNode =>
+  placed(options, {
+    _tag: 'Dots',
+    positions: options.positions,
+    colors: options.colors ?? null,
+    sizes: options.sizes ?? null,
+    color: options.color ?? 0xffffff,
+    size: options.size ?? 1,
+    sizeAttenuation: options.sizeAttenuation ?? true,
+    round: options.round ?? true,
+    opacity: options.opacity ?? 1,
+    transparent: options.transparent ?? false,
+  });
+
+/**
+ * Glowing motes drifting in a box, as Drei's `Sparkles` (`src/core/Sparkles.tsx`), with
+ * its defaults: 100 of them, speed 1, opaque, a unit box (`spread`, Drei's `scale`),
+ * random sizes up to 1, white, noise 1. Drei scatters them with `Math.random`; `seed`
+ * scatters them the same way every time.
+ */
+export const sparkles = (
+  options: Placing & {
+    readonly count?: number;
+    readonly speed?: number;
+    readonly opacity?: number;
+    readonly size?: number | null;
+    readonly color?: Rgb;
+    readonly spread?: number | Vec3;
+    readonly noise?: number | Vec3;
+    readonly seed?: number;
+  },
+): PointsNode => {
+  const spread = options.spread ?? 1;
+  const noise = options.noise ?? 1;
+  return placed(options, {
+    _tag: 'Sparkles',
+    count: options.count ?? 100,
+    speed: options.speed ?? 1,
+    opacity: options.opacity ?? 1,
+    scale: typeof spread === 'number' ? [spread, spread, spread] : spread,
+    size: options.size ?? null,
+    color: options.color ?? 0xffffff,
+    noise: typeof noise === 'number' ? [noise, noise, noise] : noise,
+    seed: options.seed ?? 1,
+  });
+};
+
+/**
+ * A starfield, as Drei's `Stars` (`src/core/Stars.tsx`), with its defaults: 5000 stars
+ * from radius 100 to 150, size factor 4, white (saturation 0), hard-edged, twinkling at
+ * speed 1. `seed` places them the same way every time.
+ */
+export const stars = (
+  options: Placing & {
+    readonly radius?: number;
+    readonly depth?: number;
+    readonly count?: number;
+    readonly factor?: number;
+    readonly saturation?: number;
+    readonly fade?: boolean;
+    readonly speed?: number;
+    readonly seed?: number;
+  },
+): PointsNode =>
+  placed(options, {
+    _tag: 'Stars',
+    radius: options.radius ?? 100,
+    depth: options.depth ?? 50,
+    count: options.count ?? 5000,
+    factor: options.factor ?? 4,
+    saturation: options.saturation ?? 0,
+    fade: options.fade ?? false,
+    speed: options.speed ?? 1,
+    seed: options.seed ?? 1,
+  });
+
+/**
+ * Points along a Catmull-Rom curve through `points`, as Drei's `CatmullRomLine`, with its
+ * defaults: open, centripetal, tension 0.5, 20 segments (so 21 points).
+ */
+export const catmullRomPoints = (
+  points: ReadonlyArray<Vec3>,
+  options: {
+    readonly closed?: boolean;
+    readonly curveType?: 'centripetal' | 'chordal' | 'catmullrom';
+    readonly tension?: number;
+    readonly segments?: number;
+  } = {},
+): ReadonlyArray<Vec3> =>
+  new CatmullRomCurve3(
+    points.map(asVector),
+    options.closed ?? false,
+    options.curveType ?? 'centripetal',
+    options.tension ?? 0.5,
+  )
+    .getPoints(options.segments ?? 20)
+    .map(asVec3);
+
+/**
+ * The point `t` of the way along a Catmull-Rom curve through `points` (0 its start, 1 its
+ * end; three's `getPoint`, by parameter rather than arc length), with
+ * `catmullRomPoints`'s defaults: for something that rides the curve, a behaviour say.
+ */
+export const catmullRomPointAt = (
+  points: ReadonlyArray<Vec3>,
+  t: number,
+  options: {
+    readonly closed?: boolean;
+    readonly curveType?: 'centripetal' | 'chordal' | 'catmullrom';
+    readonly tension?: number;
+  } = {},
+): Vec3 =>
+  asVec3(
+    new CatmullRomCurve3(
+      points.map(asVector),
+      options.closed ?? false,
+      options.curveType ?? 'centripetal',
+      options.tension ?? 0.5,
+    ).getPoint(Math.min(1, Math.max(0, t))),
+  );
+
+/**
+ * Colours for a Catmull-Rom line's points from a few along it, as Drei's
+ * `CatmullRomLine` spreads `vertexColors` over its segments (blended in linear colour).
+ */
+export const catmullRomColors = (
+  colors: ReadonlyArray<Rgb>,
+  options: { readonly segments?: number; readonly closed?: boolean } = {},
+): ReadonlyArray<Rgb> => {
+  const segments = options.segments ?? 20;
+  if (colors.length < 2 || colors.length === segments + 1) return colors;
+  const stops = colors.map((color) => new Color(color));
+  const first = stops[0];
+  if (options.closed === true && first !== undefined) stops.push(first.clone());
+  const divisions = segments / (stops.length - 1);
+  // The colour at point `index`: between the two stops either side of it.
+  const at = (index: number): Rgb =>
+    (stops[Math.floor(index / divisions)] ?? new Color())
+      .clone()
+      .lerp(
+        stops[Math.floor(index / divisions) + 1] ?? new Color(),
+        (index % divisions) / divisions,
+      )
+      .getHex();
+  const blended = Array.from({ length: segments - 1 }, (_, step) => at(step + 1));
+  return [colors[0] ?? 0, ...blended, stops.at(-1)?.getHex() ?? 0];
+};
+
+/** Points along a cubic Bézier curve, as Drei's `CubicBezierLine` (20 segments). */
+export const cubicBezierPoints = (options: {
+  readonly start: Vec3;
+  readonly midA: Vec3;
+  readonly midB: Vec3;
+  readonly end: Vec3;
+  readonly segments?: number;
+}): ReadonlyArray<Vec3> =>
+  new CubicBezierCurve3(
+    asVector(options.start),
+    asVector(options.midA),
+    asVector(options.midB),
+    asVector(options.end),
+  )
+    .getPoints(options.segments ?? 20)
+    .map(asVec3);
+
+/**
+ * Points along a quadratic Bézier curve, as Drei's `QuadraticBezierLine` (20 segments).
+ * Without `mid`, Drei's default: level with `start`, above or below `end`.
+ */
+export const quadraticBezierPoints = (options: {
+  readonly start: Vec3;
+  readonly end: Vec3;
+  readonly mid?: Vec3;
+  readonly segments?: number;
+}): ReadonlyArray<Vec3> => {
+  const [, startY] = options.start;
+  const [endX, , endZ] = options.end;
+  const mid = options.mid ?? [endX, startY, endZ];
+  return new QuadraticBezierCurve3(asVector(options.start), asVector(mid), asVector(options.end))
+    .getPoints(options.segments ?? 20)
+    .map(asVec3);
+};
+
 /** The head (the viewer), for content that stays in view. */
 export const headSpace = (): XrSpace => ({ _tag: 'Head' });
 
@@ -547,6 +898,8 @@ export const mesh = (
     readonly castShadow?: boolean;
     readonly receiveShadow?: boolean;
     readonly body?: Body | null;
+    readonly edges?: Edges | null;
+    readonly trail?: Trail | null;
   },
 ): MeshNode => ({
   _tag: 'Mesh',
@@ -562,6 +915,42 @@ export const mesh = (
   castShadow: options.castShadow ?? false,
   receiveShadow: options.receiveShadow ?? false,
   body: options.body ?? null,
+  edges: options.edges ?? null,
+  trail: options.trail ?? null,
+});
+
+/**
+ * A trail behind a moving node, as Drei's `Trail` (`bf6f4ad`, `src/core/Trail.tsx`), with
+ * its defaults: width 0.2, length 1, decay 1, world positions, no stride, every step, hot
+ * pink; no taper or fade (Drei's `attenuation` and `meshline` options).
+ */
+export const trail = (options: Partial<Trail> = {}): Trail => ({
+  width: options.width ?? 0.2,
+  length: options.length ?? 1,
+  decay: options.decay ?? 1,
+  local: options.local ?? false,
+  stride: options.stride ?? 0,
+  interval: options.interval ?? 1,
+  color: options.color ?? 0xff69b4,
+  taper: options.taper ?? 'none',
+  fade: options.fade ?? false,
+});
+
+/**
+ * Lines along a mesh's hard edges, as Drei's `Edges` (`bf6f4ad`, `src/core/Edges.tsx`),
+ * with its defaults: faces meeting at more than 15 degrees, a white line 1 pixel wide
+ * (Drei's `Line` defaults). `mesh({ edges: edges({ color: 0x000000 }) })`.
+ */
+export const edges = (options: Partial<Edges> = {}): Edges => ({
+  threshold: options.threshold ?? 15,
+  color: options.color ?? 0xffffff,
+  width: options.width ?? 1,
+  worldUnits: options.worldUnits ?? false,
+  dashed: options.dashed ?? false,
+  dashSize: options.dashSize ?? 1,
+  gapSize: options.gapSize ?? 1,
+  opacity: options.opacity ?? 1,
+  transparent: options.transparent ?? false,
 });
 
 /**
@@ -859,6 +1248,8 @@ export const borrowed = (
     readonly interactive?: boolean;
     readonly animation?: Animation | null;
     readonly body?: Body | null;
+    readonly castShadow?: boolean;
+    readonly receiveShadow?: boolean;
   },
 ): BorrowedNode => ({
   _tag: 'Borrowed',
@@ -872,6 +1263,8 @@ export const borrowed = (
   behaviour: options.behaviour ?? null,
   interactive: options.interactive ?? false,
   body: options.body ?? null,
+  castShadow: options.castShadow ?? false,
+  receiveShadow: options.receiveShadow ?? false,
 });
 
 /**
@@ -1060,6 +1453,7 @@ export const perspectiveCamera = (
   lookAt: options.lookAt ?? origin,
   damping: options.damping ?? 0,
   autoRotate: options.autoRotate ?? 0,
+  shake: options.shake ?? null,
 });
 
 /**
@@ -1077,6 +1471,26 @@ export const orthographicCamera = (
   lookAt: options.lookAt ?? origin,
   damping: options.damping ?? 0,
   autoRotate: options.autoRotate ?? 0,
+  shake: options.shake ?? null,
+});
+
+/**
+ * Camera shake, as Drei's `CameraShake` (`bf6f4ad`, `src/core/CameraShake.tsx`), with its
+ * defaults: intensity 1, no decay (rate 0.65 a second when on), and 0.1 radians at 0.1 for
+ * each of yaw, pitch and roll. `perspectiveCamera({ shake: cameraShake({ decay: true }) })`
+ * shakes once and settles; bump `trigger` to shake again.
+ */
+export const cameraShake = (options: Partial<CameraShake> = {}): CameraShake => ({
+  intensity: options.intensity ?? 1,
+  decay: options.decay ?? false,
+  decayRate: options.decayRate ?? 0.65,
+  maxYaw: options.maxYaw ?? 0.1,
+  maxPitch: options.maxPitch ?? 0.1,
+  maxRoll: options.maxRoll ?? 0.1,
+  yawFrequency: options.yawFrequency ?? 0.1,
+  pitchFrequency: options.pitchFrequency ?? 0.1,
+  rollFrequency: options.rollFrequency ?? 0.1,
+  trigger: options.trigger ?? 0,
 });
 
 const noEffects: ReadonlyArray<PostEffect> = [];
@@ -1288,11 +1702,26 @@ export const overlay = (options: {
   view: options.view ?? null,
 });
 
+/**
+ * Nodes drawn over the scene (Drei's `Hud`), with Drei's `GizmoHelper` defaults: the
+ * origin 80 CSS pixels in from the bottom right.
+ */
+export const hud = (options: {
+  readonly alignment?: HudAlignment;
+  readonly margin?: readonly [number, number];
+  readonly children?: ReadonlyArray<SceneNode>;
+}): Hud => ({
+  alignment: options.alignment ?? 'bottom-right',
+  margin: options.margin ?? [80, 80],
+  children: options.children ?? [],
+});
+
 export const scene = (options: {
   readonly camera?: Camera;
   readonly gestures?: Gestures;
   readonly views?: ReadonlyArray<View>;
   readonly renderTextures?: ReadonlyArray<RenderTexture>;
+  readonly hud?: Hud | null;
   readonly overlays?: ReadonlyArray<Overlay>;
   /** Optional staging: leave out or pass `null` for none, so a Model can switch it off. */
   readonly environment?: Environment | null;
@@ -1309,6 +1738,7 @@ export const scene = (options: {
   gestures: options.gestures ?? 'page',
   views: options.views ?? noViews,
   renderTextures: options.renderTextures ?? noRenderTextures,
+  hud: options.hud ?? null,
   overlays: options.overlays ?? noOverlays,
   environment: options.environment ?? null,
   sky: options.sky ?? null,

package/src/kernel/cameraMotion.ts

@@ -94,6 +94,8 @@ export type CameraMotion = {
   readonly hold: (held: boolean) => void;
   /** Where turning has taken the camera, when it has turned since its description. */
   readonly turned: () => Vec3 | undefined;
+  /** The point the camera looks at now, on its way to the aim. Not to be changed. */
+  readonly target: () => Vector3;
 };
 
 /** Radians a turning camera turns per second per unit of `autoRotate` (three's `2π / 60`). */
@@ -198,5 +200,6 @@ export const createCameraMotion = (): CameraMotion => {
       position.setFromSpherical(goal.spherical).add(goal.target);
       return [position.x, position.y, position.z];
     },
+    target: () => current.target,
   };
 };

package/src/kernel/cameraShake.ts

@@ -0,0 +1,87 @@
+/**
+ * Camera shake, as Drei's `CameraShake` (`bf6f4ad`, `src/core/CameraShake.tsx`): yaw, pitch
+ * and roll added to the camera's rotation from simplex noise, scaled by the square of the
+ * intensity. Here it is a pure function of scene time: the noise is seeded (Drei seeds
+ * from `Math.random`), and decay counts down from when the shake began, so the same scene
+ * time always shakes the same way, at any frame rate. Reduced motion holds it still.
+ *
+ * The camera always looks at its target here, so each frame it is aimed there again and
+ * the shake added on top: whatever moved the camera in between, nothing accumulates.
+ *
+ * @module
+ */
+import type { OrthographicCamera, PerspectiveCamera, Vector3 } from 'three';
+import { SimplexNoise } from 'three/addons/math/SimplexNoise.js';
+
+import type { CameraShake } from './description.ts';
+import { cameraShakeEquals } from './equality.ts';
+import { seededRandom } from './seeded.ts';
+
+/** Each axis's noise, seeded so the shake is the same on every page load. */
+const seeded = (seed: number) => ({ random: seededRandom(seed) });
+
+const yawNoise = new SimplexNoise(seeded(1));
+const pitchNoise = new SimplexNoise(seeded(2));
+const rollNoise = new SimplexNoise(seeded(3));
+
+/** The intensity at `seconds` after the shake began: Drei's, clamped to [0, 1], decaying. */
+export const shakeIntensity = (shake: CameraShake, seconds: number): number => {
+  const decayed = shake.decay ? shake.intensity - shake.decayRate * seconds : shake.intensity;
+  return Math.min(1, Math.max(0, decayed));
+};
+
+export type CameraShaker = {
+  /**
+   * The camera's shake as described at scene time `now`: one that first appears, changes
+   * or is triggered again begins then.
+   */
+  readonly describe: (shake: CameraShake | null, now: number) => void;
+  /**
+   * Aims the camera at `target` and adds the shake at scene time `now`, or only aims it
+   * when the shake has ended or motion is reduced. Does nothing when nothing was added.
+   */
+  readonly apply: (
+    camera: PerspectiveCamera | OrthographicCamera,
+    target: Vector3,
+    now: number,
+    animating: boolean,
+  ) => void;
+  /** Whether the camera is shaking at scene time `now`, and so needs frames. */
+  readonly shaking: (now: number) => boolean;
+};
+
+/** One camera's shake. Allocation-free once created. */
+export const createCameraShaker = (): CameraShaker => {
+  let current: CameraShake | null = null;
+  let since = 0;
+  // Whether the camera wears an offset that a still frame must take off again.
+  let offset = false;
+
+  return {
+    describe: (shake, now) => {
+      if (shake !== null && (current === null || !cameraShakeEquals(current, shake))) since = now;
+      current = shake;
+    },
+    apply: (camera, target, now, animating) => {
+      const shake = current;
+      const strength =
+        shake === null || !animating ? 0 : shakeIntensity(shake, Math.max(0, now - since)) ** 2;
+      if (shake === null || strength === 0) {
+        if (offset) camera.lookAt(target);
+        offset = false;
+        return;
+      }
+      camera.lookAt(target);
+      camera.rotation.set(
+        camera.rotation.x +
+          shake.maxPitch * strength * pitchNoise.noise(now * shake.pitchFrequency, 1),
+        camera.rotation.y + shake.maxYaw * strength * yawNoise.noise(now * shake.yawFrequency, 1),
+        camera.rotation.z +
+          shake.maxRoll * strength * rollNoise.noise(now * shake.rollFrequency, 1),
+      );
+      offset = true;
+    },
+    shaking: (now) =>
+      offset || (current !== null && shakeIntensity(current, Math.max(0, now - since)) > 0),
+  };
+};