@opsydyn/effect-three 0.2.0 → 0.3.0

package/src/kernel/build.ts

@@ -6,6 +6,8 @@
 import type {
   AmbientLightNode,
   Animation,
+  CameraShake,
+  Detail,
   BasicMaterial,
   Body,
   Behave,
@@ -40,6 +42,8 @@ import type {
   ColliderDescription,
   ColliderShapeDescription,
   CapsuleGeometry,
+  RoundedBoxGeometry,
+  BackdropGeometry,
   CircleGeometry,
   ConeGeometry,
   CylinderGeometry,
@@ -106,6 +110,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 +216,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: {
@@ -478,6 +538,7 @@ export const group = (
     readonly children?: ReadonlyArray<SceneNode>;
     readonly body?: Body | null;
     readonly follow?: XrSpace | null;
+    readonly detail?: Detail | null;
   },
 ): GroupNode => ({
   _tag: 'Group',
@@ -491,8 +552,20 @@ export const group = (
   children: options.children ?? [],
   body: options.body ?? null,
   follow: options.follow ?? null,
+  detail: options.detail ?? 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 });
+
 /** The head (the viewer), for content that stays in view. */
 export const headSpace = (): XrSpace => ({ _tag: 'Head' });
 
@@ -859,6 +932,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 +947,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 +1137,7 @@ export const perspectiveCamera = (
   lookAt: options.lookAt ?? origin,
   damping: options.damping ?? 0,
   autoRotate: options.autoRotate ?? 0,
+  shake: options.shake ?? null,
 });
 
 /**
@@ -1077,6 +1155,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> = [];

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,97 @@
+/**
+ * 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';
+
+/** A small seeded generator (mulberry32), so the noise is the same on every page load. */
+const seeded = (seed: number): { readonly random: () => number } => {
+  let state = seed >>> 0;
+  return {
+    random: () => {
+      state = (state + 0x6d2b79f5) >>> 0;
+      let t = state;
+      t = Math.imul(t ^ (t >>> 15), t | 1);
+      t ^= t + Math.imul(t ^ (t >>> 7), t | 61);
+      return ((t ^ (t >>> 14)) >>> 0) / 4294967296;
+    },
+  };
+};
+
+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),
+  };
+};

package/src/kernel/description.ts

@@ -30,6 +30,17 @@ export type Rotation =
       readonly axis: Axis;
       readonly radiansPerSecond: number;
       readonly phase: number;
+    }
+  /**
+   * Faces the scene's camera every frame, as Drei's `Billboard`: the node turns so its
+   * world rotation is the camera's. A locked axis stays at 0 in the node's own Euler
+   * angles (Drei keeps its previous value, which starts at 0).
+   */
+  | {
+      readonly _tag: 'Billboard';
+      readonly lockX: boolean;
+      readonly lockY: boolean;
+      readonly lockZ: boolean;
     };
 
 /** Box geometry parameters. */
@@ -90,6 +101,36 @@ export type CapsuleGeometry = {
   readonly radialSegments: number;
 };
 
+/**
+ * A box with rounded edges and corners, centred, as Drei's `RoundedBox`: a rounded
+ * rectangle extruded and bevelled, with normals creased at `creaseAngle`.
+ */
+export type RoundedBoxGeometry = {
+  readonly _tag: 'RoundedBox';
+  readonly width: number;
+  readonly height: number;
+  readonly depth: number;
+  readonly radius: number;
+  /** Segments in each rounded corner of the outline. */
+  readonly smoothness: number;
+  /** Segments across the bevel, which Drei doubles. */
+  readonly bevelSegments: number;
+  readonly steps: number;
+  /** Faces meeting at more than this angle (radians) keep a hard edge. */
+  readonly creaseAngle: number;
+};
+
+/**
+ * A photo backdrop, as Drei's `Backdrop`: a floor that sweeps up into a wall behind it,
+ * one unit each way (scale it to size). The floor lies along +Z towards the viewer, the
+ * wall rises at its back, and `floor` extends the flat front.
+ */
+export type BackdropGeometry = {
+  readonly _tag: 'Backdrop';
+  readonly floor: number;
+  readonly segments: number;
+};
+
 /** A flat ring (annulus) in the XY plane, facing +Z. */
 export type RingGeometry = {
   readonly _tag: 'Ring';
@@ -150,7 +191,9 @@ export type ShapeGeometry =
   | ConeGeometry
   | CapsuleGeometry
   | RingGeometry
-  | CircleGeometry;
+  | CircleGeometry
+  | RoundedBoxGeometry
+  | BackdropGeometry;
 
 /** Which faces a material draws. */
 export type MaterialSide = 'front' | 'back' | 'double';
@@ -342,6 +385,22 @@ export type GroupNode = {
    * not tracked (or no session presents). `null` for the group's own transform.
    */
   readonly follow: XrSpace | null;
+  /**
+   * Levels of detail: the group shows one child at a time, chosen by the camera's
+   * distance (Drei's `Detailed`, three's `LOD`), or `null` to show them all.
+   */
+  readonly detail: Detail | null;
+};
+
+/**
+ * Levels of detail for a group's children, in order: child `i` shows from
+ * `distances[i]` (scene units from the camera, divided by its zoom) until the next level's
+ * distance. `hysteresis` (a fraction) keeps a shown level until the camera is that much
+ * nearer than its distance, so the switch does not flicker at the boundary.
+ */
+export type Detail = {
+  readonly distances: ReadonlyArray<number>;
+  readonly hysteresis: number;
 };
 
 /** The joints of a tracked hand, as WebXR names them (`XRHandJoint`). */
@@ -656,6 +715,13 @@ export type BorrowedNode = {
   readonly animation: Animation | null;
   /** A rigid body whose colliders are the model's meshes, once it is lent; or `null`. */
   readonly body: Body | null;
+  /**
+   * Every mesh in what it shows casts (receives) shadows, as Drei's `Clone` shorthands;
+   * `false` leaves each mesh's own setting. Set on the lent object itself where it is
+   * shown as lent rather than cloned.
+   */
+  readonly castShadow: boolean;
+  readonly receiveShadow: boolean;
 };
 
 /** Where a label's origin is along its width: an edge, the middle, or a fraction of it. */
@@ -902,6 +968,8 @@ export type PerspectiveCamera = {
    * (`autoRotated(camera, detail)`). A new position or `lookAt` turns on from there.
    */
   readonly autoRotate: number;
+  /** Shakes the rendered camera (Drei's `CameraShake`), or `null` for none. */
+  readonly shake: CameraShake | null;
 };
 
 /**
@@ -919,6 +987,28 @@ export type OrthographicCamera = {
   readonly damping: number;
   /** As on `PerspectiveCamera`. */
   readonly autoRotate: number;
+  /** As on `PerspectiveCamera`. */
+  readonly shake: CameraShake | null;
+};
+
+/**
+ * Camera shake, as Drei's `CameraShake`: yaw, pitch and roll of up to `max*` radians,
+ * from noise at `*Frequency`, scaled by `intensity` squared (0 to 1). With `decay` the
+ * intensity falls by `decayRate` a second from when the shake began, so a decaying shake
+ * is a one-off: it begins when it first appears or changes, and `trigger` (a count the
+ * Model bumps) begins the same shake again. Reduced motion holds the camera still.
+ */
+export type CameraShake = {
+  readonly intensity: number;
+  readonly decay: boolean;
+  readonly decayRate: number;
+  readonly maxYaw: number;
+  readonly maxPitch: number;
+  readonly maxRoll: number;
+  readonly yawFrequency: number;
+  readonly pitchFrequency: number;
+  readonly rollFrequency: number;
+  readonly trigger: number;
 };
 
 /** The single active camera. */

package/src/kernel/diff.ts

@@ -31,6 +31,7 @@ import {
   labelMaterialEquals,
   labelTypeEquals,
   xrSpaceEquals,
+  detailEquals,
   shaderGridLookEquals,
   instancesEqual,
   materialRefEquals,
@@ -82,7 +83,9 @@ export type Field =
   /** A shader grid's look: anything but where it is. */
   | 'grid'
   /** The tracked space a group follows. */
-  | 'follow';
+  | 'follow'
+  /** A group's levels of detail. */
+  | 'detail';
 
 /** A single change to apply to the hosted scene graph. */
 export type Op =
@@ -131,6 +134,7 @@ export const changedFields = (
       if (prev.interactive !== next.interactive) fields.push('interactive');
       if (!bodyEquals(prev.body, next.body)) fields.push('body');
       if (!xrSpaceEquals(prev.follow, next.follow)) fields.push('follow');
+      if (!detailEquals(prev.detail, next.detail)) fields.push('detail');
       return fields;
     }
     case 'Mesh': {
@@ -175,6 +179,8 @@ export const changedFields = (
       if (!animationEquals(prev.animation, next.animation)) fields.push('animation');
       if (prev.interactive !== next.interactive) fields.push('interactive');
       if (!bodyEquals(prev.body, next.body)) fields.push('body');
+      if (prev.castShadow !== next.castShadow) fields.push('castShadow');
+      if (prev.receiveShadow !== next.receiveShadow) fields.push('receiveShadow');
       return fields;
     }
     case 'Label': {

package/src/kernel/equality.ts

@@ -7,6 +7,8 @@
 import type {
   Animation,
   Behave,
+  CameraShake,
+  Detail,
   Body,
   BodyRef,
   GeometryRef,
@@ -46,6 +48,17 @@ import type {
 export const vec3Equals = (a: Vec3, b: Vec3): boolean =>
   a === b || (Object.is(a[0], b[0]) && Object.is(a[1], b[1]) && Object.is(a[2], b[2]));
 
+/** Levels-of-detail equality: the same distances and hysteresis. */
+export const detailEquals = (a: Detail | null, b: Detail | null): boolean => {
+  if (a === b) return true;
+  if (a === null || b === null) return false;
+  return (
+    Object.is(a.hysteresis, b.hysteresis) &&
+    a.distances.length === b.distances.length &&
+    a.distances.every((distance, index) => Object.is(distance, b.distances[index]))
+  );
+};
+
 /** Rotation equality, including behaviour parameters. */
 export const rotationEquals = (a: Rotation, b: Rotation): boolean => {
   if (a === b) return true;
@@ -57,6 +70,9 @@ export const rotationEquals = (a: Rotation, b: Rotation): boolean => {
       Object.is(a.phase, b.phase)
     );
   }
+  if (a._tag === 'Billboard' && b._tag === 'Billboard') {
+    return a.lockX === b.lockX && a.lockY === b.lockY && a.lockZ === b.lockZ;
+  }
   return false;
 };
 
@@ -120,6 +136,20 @@ export const shapeEquals = (a: ShapeGeometry, b: ShapeGeometry): boolean => {
       );
     case 'Circle':
       return b._tag === 'Circle' && Object.is(a.radius, b.radius) && a.segments === b.segments;
+    case 'RoundedBox':
+      return (
+        b._tag === 'RoundedBox' &&
+        Object.is(a.width, b.width) &&
+        Object.is(a.height, b.height) &&
+        Object.is(a.depth, b.depth) &&
+        Object.is(a.radius, b.radius) &&
+        a.smoothness === b.smoothness &&
+        a.bevelSegments === b.bevelSegments &&
+        a.steps === b.steps &&
+        Object.is(a.creaseAngle, b.creaseAngle)
+      );
+    case 'Backdrop':
+      return b._tag === 'Backdrop' && Object.is(a.floor, b.floor) && a.segments === b.segments;
     case 'Text':
       return (
         b._tag === 'Text' &&
@@ -223,6 +253,22 @@ export const materialRefEquals = (a: MaterialRef, b: MaterialRef): boolean => {
 };
 
 /** Camera equality: same kind, same lens and same placement. */
+/** Camera shake equality: every setting, and the trigger count. */
+export const cameraShakeEquals = (a: CameraShake | null, b: CameraShake | null): boolean =>
+  a === b ||
+  (a !== null &&
+    b !== null &&
+    Object.is(a.intensity, b.intensity) &&
+    a.decay === b.decay &&
+    Object.is(a.decayRate, b.decayRate) &&
+    Object.is(a.maxYaw, b.maxYaw) &&
+    Object.is(a.maxPitch, b.maxPitch) &&
+    Object.is(a.maxRoll, b.maxRoll) &&
+    Object.is(a.yawFrequency, b.yawFrequency) &&
+    Object.is(a.pitchFrequency, b.pitchFrequency) &&
+    Object.is(a.rollFrequency, b.rollFrequency) &&
+    Object.is(a.trigger, b.trigger));
+
 export const cameraEquals = (a: Camera, b: Camera): boolean => {
   if (a === b) return true;
   const sameLens =
@@ -234,6 +280,7 @@ export const cameraEquals = (a: Camera, b: Camera): boolean => {
     Object.is(a.far, b.far) &&
     Object.is(a.damping, b.damping) &&
     Object.is(a.autoRotate, b.autoRotate) &&
+    cameraShakeEquals(a.shake, b.shake) &&
     vec3Equals(a.position, b.position) &&
     vec3Equals(a.lookAt, b.lookAt)
   );

package/src/kernel/index.ts

@@ -96,12 +96,17 @@ export {
   pointLight,
   renderSettings,
   ring,
+  roundedBox,
+  backdrop,
   scene,
   sharedGeometry,
   lentGeometry,
   sharedMaterial,
   sphere,
   spin,
+  cameraShake,
+  detailed,
+  billboard,
   spotLight,
   standard,
   overlay,

package/src/kernel/pointer.ts

@@ -359,6 +359,12 @@ const pathOf = (graph: SceneGraph, object: Object3D): ReadonlyArray<string> => {
   return path;
 };
 
+/** Whether an object and every ancestor are visible. */
+const shown = (object: Object3D): boolean => {
+  for (let at: Object3D | null = object; at !== null; at = at.parent) if (!at.visible) return false;
+  return true;
+};
+
 /** Creates a raycasting picker over a graph's interactive meshes and groups. */
 export const createPicker = (graph: SceneGraph): Picker => {
   const raycaster = new Raycaster();
@@ -403,6 +409,8 @@ export const createPicker = (graph: SceneGraph): Picker => {
   const nearestHit = (view: string | undefined): Hit | undefined => {
     // Recursive, so an interactive group makes every mesh inside it pickable.
     for (const intersection of raycaster.intersectObjects(graph.interactiveObjects(), true)) {
+      // Hidden things are not hit: a level of detail not showing, as three's `LOD.raycast`.
+      if (!shown(intersection.object)) continue;
       const owner = keyedOwner(graph, intersection.object);
       const key = owner === undefined ? undefined : graph.keyOf(owner);
       if (owner !== undefined && key !== undefined) {

package/src/kernel/resources.ts

@@ -22,17 +22,21 @@ import {
   CircleGeometry,
   ConeGeometry,
   CylinderGeometry,
+  Euler,
   ExtrudeGeometry,
   Material,
   type Object3D,
   type Texture,
   PlaneGeometry,
+  Quaternion,
   RingGeometry,
+  Shape,
   ShapeGeometry as ShapeGeometry3,
   SphereGeometry,
   TorusGeometry,
 } from 'three';
 import type { Font } from 'three/addons/loaders/FontLoader.js';
+import { toCreasedNormals } from 'three/addons/utils/BufferGeometryUtils.js';
 
 import type {
   GeometryRef,
@@ -191,6 +195,67 @@ const buildText = (shape: TextGeometry, font: Font | undefined): BufferGeometry
   return geometry;
 };
 
+/** Drei's `RoundedBox` nudge, keeping its corner arcs from being zero length. */
+const roundedEpsilon = 0.00001;
+
+/**
+ * Drei's `RoundedBox` (`bf6f4ad`): the corners' arcs drawn tiny and the bevel making the
+ * rounding, extruded through the depth less the bevels, centred, and its normals creased
+ * (three's `toCreasedNormals`, which Drei takes from three-stdlib).
+ */
+const buildRoundedBox = (shape: Extract<ShapeGeometry, { readonly _tag: 'RoundedBox' }>) => {
+  const { width, height, depth, radius } = shape;
+  const outline = new Shape();
+  const inset = radius - roundedEpsilon;
+  const e = roundedEpsilon;
+  outline.absarc(e, e, e, -Math.PI / 2, -Math.PI, true);
+  outline.absarc(e, height - inset * 2, e, Math.PI, Math.PI / 2, true);
+  outline.absarc(width - inset * 2, height - inset * 2, e, Math.PI / 2, 0, true);
+  outline.absarc(width - inset * 2, e, e, 0, -Math.PI / 2, true);
+  const geometry = new ExtrudeGeometry(outline, {
+    depth: depth - radius * 2,
+    bevelEnabled: true,
+    bevelSegments: shape.bevelSegments * 2,
+    steps: shape.steps,
+    bevelSize: radius - roundedEpsilon,
+    bevelThickness: radius,
+    curveSegments: shape.smoothness,
+  });
+  geometry.center();
+  return toCreasedNormals(geometry, shape.creaseAngle);
+};
+
+/** Drei's `Backdrop` mesh turn, built into the geometry: the floor flat, the wall behind. */
+const backdropTurn = new Quaternion().setFromEuler(new Euler(-Math.PI / 2, 0, Math.PI / 2));
+
+/** Drei's `Backdrop` easing: the floor stays flat, then sweeps up. */
+const easeInExpo = (x: number): number => (x === 0 ? 0 : 2 ** (10 * x - 10));
+
+/**
+ * Drei's `Backdrop` (`bf6f4ad`): a unit plane whose rows rise by an exponential ease, its
+ * first row pulled forward by `floor`, then turned as Drei turns its mesh.
+ */
+const buildBackdrop = (shape: Extract<ShapeGeometry, { readonly _tag: 'Backdrop' }>) => {
+  const { segments, floor } = shape;
+  const geometry = new PlaneGeometry(1, 1, segments, segments);
+  const position = geometry.getAttribute('position');
+  const offset = 0.5;
+  let vertex = 0;
+  for (let x = 0; x < segments + 1; x++) {
+    for (let y = 0; y < segments + 1; y++) {
+      position.setXYZ(
+        vertex++,
+        x / segments - offset + (x === 0 ? -floor : 0),
+        y / segments - offset,
+        easeInExpo(x / segments),
+      );
+    }
+  }
+  position.needsUpdate = true;
+  geometry.computeVertexNormals();
+  return geometry.applyQuaternion(backdropTurn);
+};
+
 /** Builds the three.js geometry for a shape description. */
 const buildShape = (
   shape: ShapeGeometry,
@@ -232,6 +297,10 @@ const buildShape = (
       return new RingGeometry(shape.innerRadius, shape.outerRadius, shape.thetaSegments);
     case 'Circle':
       return new CircleGeometry(shape.radius, shape.segments);
+    case 'RoundedBox':
+      return buildRoundedBox(shape);
+    case 'Backdrop':
+      return buildBackdrop(shape);
   }
 };