@opsydyn/effect-three 0.0.0-stage → 0.1.0

package/src/kernel/sceneIndex.ts

@@ -0,0 +1,219 @@
+/**
+ * Flattened, validated view of a scene description, used by the diff.
+ *
+ * @module
+ */
+import type { Joint, SceneDescription, SceneNode } from './description.ts';
+
+/** Parent of a node: another node's key, or `null` for the scene root. */
+export type ParentKey = string | null;
+
+/** A node with its position in the tree. */
+export type IndexedNode = {
+  readonly node: SceneNode;
+  readonly parent: ParentKey;
+};
+
+/** A description is rejected as a whole; nothing is applied (no partial updates). */
+export type DescriptionError =
+  | { readonly _tag: 'DuplicateKey'; readonly key: string }
+  | {
+      readonly _tag: 'DuplicateResourceId';
+      readonly resource: 'geometry' | 'material';
+      readonly id: string;
+    }
+  | { readonly _tag: 'UnknownSharedGeometry'; readonly nodeKey: string; readonly id: string }
+  | { readonly _tag: 'UnknownSharedMaterial'; readonly nodeKey: string; readonly id: string }
+  | { readonly _tag: 'DuplicateInstanceKey'; readonly nodeKey: string; readonly key: string }
+  | { readonly _tag: 'UnknownBehaviour'; readonly nodeKey: string; readonly name: string }
+  | { readonly _tag: 'DuplicateViewKey'; readonly key: string }
+  | { readonly _tag: 'DuplicateRenderTextureId'; readonly id: string }
+  | { readonly _tag: 'DuplicateOverlayKey'; readonly key: string }
+  | { readonly _tag: 'UnknownOverlayNode'; readonly key: string; readonly node: string }
+  | { readonly _tag: 'UnknownOverlayView'; readonly key: string; readonly view: string }
+  | { readonly _tag: 'UnknownMeasuredNode'; readonly key: string }
+  /** Two joints share a key. */
+  | { readonly _tag: 'DuplicateJointKey'; readonly key: string }
+  /** A joint names a node that is not in the scene. */
+  | { readonly _tag: 'UnknownJointBody'; readonly joint: string; readonly body: string };
+
+/** A validated scene. Keys are unique across the whole scene. */
+export type SceneIndex = {
+  readonly description: SceneDescription | null;
+  readonly nodes: ReadonlyMap<string, IndexedNode>;
+  /** Child keys per parent, in description order. Includes the root (`null`). */
+  readonly children: ReadonlyMap<ParentKey, ReadonlyArray<string>>;
+  /** Keys in depth-first pre-order: parents always precede their children. */
+  readonly preOrder: ReadonlyArray<string>;
+};
+
+/** The index of the empty scene that every graph starts from. */
+export const emptyIndex: SceneIndex = {
+  description: null,
+  nodes: new Map(),
+  children: new Map([[null, []]]),
+  preOrder: [],
+};
+
+export type IndexResult =
+  | { readonly _tag: 'Indexed'; readonly index: SceneIndex }
+  | { readonly _tag: 'Invalid'; readonly error: DescriptionError };
+
+/** A node waiting to be indexed: its index entry, and the list its key joins. */
+type Stacked = IndexedNode & { readonly siblings: Array<string> };
+
+/** The first instance key used twice, if any. */
+const firstDuplicateInstance = (
+  instances: ReadonlyArray<{ readonly key: string }>,
+): string | undefined => {
+  const seen = new Set<string>();
+  for (const { key } of instances) {
+    if (seen.has(key)) return key;
+    seen.add(key);
+  }
+  return undefined;
+};
+
+/** The first joint error: a key used twice, or a body naming no node. */
+const jointsError = (
+  joints: ReadonlyArray<Joint>,
+  nodes: ReadonlyMap<string, IndexedNode>,
+): DescriptionError | undefined => {
+  const duplicate = firstDuplicateInstance(joints);
+  if (duplicate !== undefined) return { _tag: 'DuplicateJointKey', key: duplicate };
+  for (const joint of joints) {
+    for (const { key } of [joint.a, joint.b]) {
+      if (!nodes.has(key)) return { _tag: 'UnknownJointBody', joint: joint.key, body: key };
+    }
+  }
+  return undefined;
+};
+
+/** Validates and flattens a description. */
+export const indexScene = (
+  description: SceneDescription,
+  behaviours: ReadonlySet<string> = new Set(),
+): IndexResult => {
+  const duplicateTexture = firstDuplicateInstance(
+    description.renderTextures.map((texture) => ({ key: texture.id })),
+  );
+  if (duplicateTexture !== undefined) {
+    return { _tag: 'Invalid', error: { _tag: 'DuplicateRenderTextureId', id: duplicateTexture } };
+  }
+  const duplicateView = firstDuplicateInstance(description.views);
+  if (duplicateView !== undefined) {
+    return { _tag: 'Invalid', error: { _tag: 'DuplicateViewKey', key: duplicateView } };
+  }
+  const duplicateOverlay = firstDuplicateInstance(description.overlays);
+  if (duplicateOverlay !== undefined) {
+    return { _tag: 'Invalid', error: { _tag: 'DuplicateOverlayKey', key: duplicateOverlay } };
+  }
+  const viewKeys = new Set(description.views.map((view) => view.key));
+  const strayView = description.overlays.find(
+    (overlay) => overlay.view !== null && !viewKeys.has(overlay.view),
+  );
+  if (strayView?.view != null) {
+    return {
+      _tag: 'Invalid',
+      error: { _tag: 'UnknownOverlayView', key: strayView.key, view: strayView.view },
+    };
+  }
+  const geometryIds = new Set<string>();
+  for (const { id } of description.resources.geometries) {
+    if (geometryIds.has(id)) {
+      return { _tag: 'Invalid', error: { _tag: 'DuplicateResourceId', resource: 'geometry', id } };
+    }
+    geometryIds.add(id);
+  }
+  const materialIds = new Set<string>();
+  for (const { id } of description.resources.materials) {
+    if (materialIds.has(id)) {
+      return { _tag: 'Invalid', error: { _tag: 'DuplicateResourceId', resource: 'material', id } };
+    }
+    materialIds.add(id);
+  }
+
+  const nodes = new Map<string, IndexedNode>();
+  const rootChildren: Array<string> = [];
+  const children = new Map<ParentKey, Array<string>>([[null, rootChildren]]);
+  const preOrder: Array<string> = [];
+  // Explicit stack instead of recursion: deep scenes cannot overflow the call stack. Each
+  // item becomes the node's index entry, and carries its parent's child list, so indexing
+  // a node allocates nothing else.
+  const stack: Array<Stacked> = [];
+  for (let i = description.children.length - 1; i >= 0; i--) {
+    const node = description.children[i];
+    if (node !== undefined) stack.push({ node, parent: null, siblings: rootChildren });
+  }
+  for (let item = stack.pop(); item !== undefined; item = stack.pop()) {
+    const { node } = item;
+    if (nodes.has(node.key))
+      return { _tag: 'Invalid', error: { _tag: 'DuplicateKey', key: node.key } };
+    if (
+      node._tag === 'Label' &&
+      node.material?._tag === 'SharedMaterial' &&
+      !materialIds.has(node.material.id)
+    ) {
+      return {
+        _tag: 'Invalid',
+        error: { _tag: 'UnknownSharedMaterial', nodeKey: node.key, id: node.material.id },
+      };
+    }
+    if (node._tag === 'Mesh' || node._tag === 'Instances') {
+      if (node.geometry._tag === 'SharedGeometry' && !geometryIds.has(node.geometry.id)) {
+        return {
+          _tag: 'Invalid',
+          error: { _tag: 'UnknownSharedGeometry', nodeKey: node.key, id: node.geometry.id },
+        };
+      }
+      if (node.material._tag === 'SharedMaterial' && !materialIds.has(node.material.id)) {
+        return {
+          _tag: 'Invalid',
+          error: { _tag: 'UnknownSharedMaterial', nodeKey: node.key, id: node.material.id },
+        };
+      }
+    }
+    if ('behaviour' in node && node.behaviour !== null && !behaviours.has(node.behaviour.name)) {
+      return {
+        _tag: 'Invalid',
+        error: { _tag: 'UnknownBehaviour', nodeKey: node.key, name: node.behaviour.name },
+      };
+    }
+    if (node._tag === 'Instances') {
+      const duplicate = firstDuplicateInstance(node.instances);
+      if (duplicate !== undefined) {
+        return {
+          _tag: 'Invalid',
+          error: { _tag: 'DuplicateInstanceKey', nodeKey: node.key, key: duplicate },
+        };
+      }
+    }
+    nodes.set(node.key, item);
+    preOrder.push(node.key);
+    item.siblings.push(node.key);
+    if (node._tag === 'Group') {
+      const siblings: Array<string> = [];
+      children.set(node.key, siblings);
+      for (let i = node.children.length - 1; i >= 0; i--) {
+        const child = node.children[i];
+        if (child !== undefined) stack.push({ node: child, parent: node.key, siblings });
+      }
+    }
+  }
+  const strayNode = description.overlays.find(
+    (overlay) => overlay.node !== null && !nodes.has(overlay.node),
+  );
+  if (strayNode?.node != null) {
+    return {
+      _tag: 'Invalid',
+      error: { _tag: 'UnknownOverlayNode', key: strayNode.key, node: strayNode.node },
+    };
+  }
+  const unmeasurable = description.measure.find((key) => !nodes.has(key));
+  if (unmeasurable !== undefined) {
+    return { _tag: 'Invalid', error: { _tag: 'UnknownMeasuredNode', key: unmeasurable } };
+  }
+  const jointError = jointsError(description.physics?.joints ?? [], nodes);
+  if (jointError !== undefined) return { _tag: 'Invalid', error: jointError };
+  return { _tag: 'Indexed', index: { description, nodes, children, preOrder } };
+};

package/src/kernel/stage.ts

@@ -0,0 +1,157 @@
+/**
+ * A ready-lit stage for a model, as Drei's `Stage` (`src/core/Stage.tsx` at `bf6f4ad`):
+ * an ambient light, a main spot light and a fill point light placed by a lighting preset
+ * and scaled by the content's size, contact shadows at its base, and an environment.
+ *
+ * Drei's `Stage` measures and centres its children and can fit the camera to them. Here
+ * that is a loop through the Model, as controls are (ADR-006): measure the content
+ * (`scene({ measure })` reports its box), place it at `centerOffset(box)` as Drei's
+ * `Center` would, light it with `stage(stageBounds(box))`, and frame it with `fitCamera`
+ * as Drei's `Bounds` would.
+ *
+ * @module
+ */
+import {
+  ambientLight,
+  contactShadows as contactShadowsOf,
+  environment as environmentOf,
+  pointLight,
+  spotLight,
+} from './build.ts';
+import type { ContactShadows, Environment, SceneNode, Vec3 } from './description.ts';
+import type { Box } from './orbit.ts';
+
+/** Where the main and fill lights sit, in multiples of the content's radius. */
+export type StageLighting = { readonly main: Vec3; readonly fill: Vec3 };
+
+/** Drei's lighting presets. */
+export const stagePresets = {
+  rembrandt: { main: [1, 2, 1], fill: [-2, -0.5, -2] },
+  portrait: { main: [-1, 2, 0.5], fill: [-1, 0.5, -1.5] },
+  upfront: { main: [0, 2, 1], fill: [-1, 0.5, -1.5] },
+  soft: { main: [-2, 4, 4], fill: [-1, 0.5, -1.5] },
+} satisfies Record<string, StageLighting>;
+
+export type StagePreset = keyof typeof stagePresets;
+
+/** The scene parts a stage contributes: spread them into `scene`. */
+export type Stage = {
+  /** The stage's lights; add them to the scene's children. */
+  readonly lights: ReadonlyArray<SceneNode>;
+  readonly contactShadows: ContactShadows | null;
+  readonly environment: Environment | null;
+};
+
+const scaled = (point: Vec3, by: number): Vec3 => [point[0] * by, point[1] * by, point[2] * by];
+
+/**
+ * Lights, ground shadows and an environment for content centred on the origin with
+ * bounding radius `radius` and height `height`. Defaults as Drei's `Stage`: the
+ * Rembrandt preset, intensity 0.5, contact shadows (`radius × 4` across, reaching
+ * `radius` up, blur 2) and a spot light that casts shadow maps when the scene enables
+ * them (bias −0.0001, 1024 texels). Drei's default environment is the "city" HDR from a
+ * CDN; here it is three.js's `RoomEnvironment`, built in code. `keyPrefix` names the
+ * lights (`stage-ambient`, `stage-main`, `stage-fill` by default).
+ */
+export const stage = (options: {
+  readonly radius: number;
+  readonly height: number;
+  readonly preset?: StagePreset | StageLighting;
+  readonly intensity?: number;
+  readonly shadows?: 'contact' | 'none';
+  readonly environment?: Environment | null;
+  readonly keyPrefix?: string;
+}): Stage => {
+  const { radius, height } = options;
+  const lighting =
+    typeof options.preset === 'object'
+      ? options.preset
+      : stagePresets[options.preset ?? 'rembrandt'];
+  const intensity = options.intensity ?? 0.5;
+  const prefix = options.keyPrefix ?? 'stage';
+  const shadowed = (options.shadows ?? 'contact') === 'contact';
+  return {
+    lights: [
+      ambientLight({ key: `${prefix}-ambient`, intensity: intensity / 3 }),
+      spotLight({
+        key: `${prefix}-main`,
+        position: scaled(lighting.main, radius),
+        penumbra: 1,
+        intensity: intensity * 2,
+        castShadow: shadowed,
+        shadowBias: -0.0001,
+        shadowMapSize: 1024,
+      }),
+      pointLight({ key: `${prefix}-fill`, position: scaled(lighting.fill, radius), intensity }),
+    ],
+    contactShadows: shadowed
+      ? contactShadowsOf({ position: [0, -height / 2, 0], size: radius * 4, far: radius, blur: 2 })
+      : null,
+    environment: options.environment === undefined ? environmentOf() : options.environment,
+  };
+};
+
+/**
+ * Which way to align content instead of centring it, per axis, as Drei's `Center` props:
+ * `top` stands it on y = 0 (on top of the origin), `bottom` hangs it below; `left` puts
+ * it left of x = 0, `right` right of it; `front` before z = 0, `back` behind. `disableY`
+ * leaves that axis as it is.
+ */
+export type CenterAlign = {
+  readonly top?: boolean;
+  readonly bottom?: boolean;
+  readonly left?: boolean;
+  readonly right?: boolean;
+  readonly front?: boolean;
+  readonly back?: boolean;
+  readonly disableX?: boolean;
+  readonly disableY?: boolean;
+  readonly disableZ?: boolean;
+};
+
+/**
+ * One axis of Drei's `Center`: the shift that puts the box's middle at 0, moved half its
+ * size up the axis (`above`, so its low side is at 0) or down it (`below`).
+ */
+const alignAxis = (
+  min: number,
+  max: number,
+  above: boolean | undefined,
+  below: boolean | undefined,
+  disabled: boolean | undefined,
+): number => {
+  if (disabled === true) return 0;
+  const half = (max - min) / 2;
+  const shift = above === true ? half : below === true ? -half : 0;
+  return -(min + max) / 2 + shift;
+};
+
+/**
+ * Where to put content whose box (as measured where it is drawn now, at no offset) is
+ * `box` so that it is centred on the origin, or aligned by `align`: Drei's `Center`
+ * (`src/core/Center.tsx` at `bf6f4ad`), which sets its inner group to this position.
+ */
+export const centerOffset = (box: Box, align: CenterAlign = {}): Vec3 => [
+  alignAxis(box.min[0], box.max[0], align.right, align.left, align.disableX),
+  alignAxis(box.min[1], box.max[1], align.top, align.bottom, align.disableY),
+  alignAxis(box.min[2], box.max[2], align.front, align.back, align.disableZ),
+];
+
+/**
+ * The sizes Drei's `Stage` takes from `Center`'s report: the box's bounding sphere radius
+ * (half its diagonal) and its width, height and depth. Pass to `stage` for lights and
+ * shadows scaled to the content.
+ */
+export const stageBounds = (
+  box: Box,
+): {
+  readonly radius: number;
+  readonly width: number;
+  readonly height: number;
+  readonly depth: number;
+} => {
+  const width = box.max[0] - box.min[0];
+  const height = box.max[1] - box.min[1];
+  const depth = box.max[2] - box.min[2];
+  return { radius: Math.hypot(width, height, depth) / 2, width, height, depth };
+};

package/src/kernel/textLayout.ts

@@ -0,0 +1,102 @@
+/**
+ * Lays out text from a typeface font as shapes, with letter spacing, line height and
+ * alignment.
+ *
+ * Behavioural reference: three.js `FontLoader.js` `createPaths` at 0.186.1 (each glyph
+ * advanced by its `ha`, a new line down by the font's bounding box height plus its
+ * underline thickness, a missing glyph drawn as `?`). Drei's `Text3D` (`bf6f4ad`) takes
+ * `letterSpacing` and `lineHeight` and hands them to `TextGeometry`, which ignores them;
+ * here they are applied, in the units troika's `Text` uses: letter spacing in ems, line
+ * height as a multiple of the font's own. At the defaults the shapes are three's.
+ *
+ * @module
+ */
+import { Vector2, type Path, type Shape } from 'three';
+import type { Font } from 'three/addons/loaders/FontLoader.js';
+
+import type { TextAlign } from './description.ts';
+
+/** How to lay the text out. */
+export type TextLayout = {
+  readonly size: number;
+  /** Extra space after each glyph, in ems (multiples of `size`). */
+  readonly letterSpacing: number;
+  /** Line spacing as a multiple of the font's. */
+  readonly lineHeight: number;
+  /** Where each line sits within the widest. */
+  readonly align: TextAlign;
+};
+
+type Glyph = { readonly ha: number };
+
+const corners = ['v0', 'v1', 'v2', 'v3'] as const;
+
+/** Moves every point of a path's curves by `(dx, dy)`. */
+const shiftPath = (path: Path, dx: number, dy: number): void => {
+  for (const curve of path.curves) {
+    for (const corner of corners) {
+      const point: unknown = Reflect.get(curve, corner);
+      if (point instanceof Vector2) point.set(point.x + dx, point.y + dy);
+    }
+  }
+};
+
+/** Moves a shape and its holes. */
+const shiftShape = (shape: Shape, dx: number, dy: number): Shape => {
+  shiftPath(shape, dx, dy);
+  for (const hole of shape.holes) shiftPath(hole, dx, dy);
+  return shape;
+};
+
+/** A glyph, or `?` for one the font lacks; neither, and the character is skipped. */
+const glyphOf = (font: Font, char: string): Glyph | undefined => {
+  const glyphs: Readonly<Record<string, Glyph | undefined>> = font.data.glyphs;
+  return glyphs[char] ?? glyphs['?'];
+};
+
+type Line = {
+  readonly chars: ReadonlyArray<string>;
+  readonly starts: ReadonlyArray<number>;
+  readonly width: number;
+};
+
+/** A line's drawable glyphs, where each starts, and its width (without trailing spacing). */
+const lineOf = (font: Font, line: string, scale: number, spacing: number): Line => {
+  const chars: Array<string> = [];
+  const starts: Array<number> = [];
+  let x = 0;
+  for (const char of Array.from(line)) {
+    const glyph = glyphOf(font, char);
+    if (glyph === undefined) continue;
+    chars.push(char);
+    starts.push(x);
+    x += glyph.ha * scale + spacing;
+  }
+  return { chars, starts, width: chars.length === 0 ? 0 : x - spacing };
+};
+
+const alignShift = { left: () => 0, center: (gap: number) => gap / 2, right: (gap: number) => gap };
+
+/** The shapes of `text` laid out by `layout`, the first line's baseline at y = 0. */
+export const layoutText = (font: Font, text: string, layout: TextLayout): ReadonlyArray<Shape> => {
+  const { data } = font;
+  const scale = layout.size / data.resolution;
+  const lineStep =
+    (data.boundingBox.yMax - data.boundingBox.yMin + data.underlineThickness) *
+    scale *
+    layout.lineHeight;
+  const spacing = layout.letterSpacing * layout.size;
+  const lines = text.split('\n').map((line) => lineOf(font, line, scale, spacing));
+  const widest = Math.max(0, ...lines.map((line) => line.width));
+  const shapes: Array<Shape> = [];
+  lines.forEach((line, row) => {
+    const indent = alignShift[layout.align](widest - line.width);
+    line.chars.forEach((char, i) => {
+      const x = indent + (line.starts[i] ?? 0);
+      for (const shape of font.generateShapes(char, layout.size)) {
+        shapes.push(shiftShape(shape, x, -row * lineStep));
+      }
+    });
+  });
+  return shapes;
+};

package/src/kernel/tween.ts

@@ -0,0 +1,80 @@
+/**
+ * Eased transitions of position and scale. A tween's pose is a pure function of scene
+ * time: `from + (to - from) * easing(progress)`, so frames are deterministic.
+ *
+ * @module
+ */
+import type { Object3D, Vector3Tuple } from 'three';
+
+import type { Easing, Vec3 } from './description.ts';
+
+const backOvershoot = 1.70158;
+
+/** Maps linear progress in [0, 1] through an easing curve. */
+export const easeProgress = (easing: Easing, progress: number): number => {
+  switch (easing) {
+    case 'linear':
+      return progress;
+    case 'easeInOutCubic':
+      return progress < 0.5 ? 4 * progress ** 3 : 1 - (-2 * progress + 2) ** 3 / 2;
+    case 'easeOutCubic':
+      return 1 - (1 - progress) ** 3;
+    case 'easeOutBack':
+      return 1 + (backOvershoot + 1) * (progress - 1) ** 3 + backOvershoot * (progress - 1) ** 2;
+  }
+};
+
+/** A position and scale transition in flight. */
+export type Tween = {
+  readonly fromPosition: Vector3Tuple;
+  readonly fromScale: Vector3Tuple;
+  readonly toPosition: Vec3;
+  readonly toScale: Vec3;
+  /** Scene time the tween started, in seconds. */
+  readonly start: number;
+  readonly seconds: number;
+  readonly easing: Easing;
+};
+
+/** Starts a tween from the object's current pose towards the targets. */
+export const startTween = (
+  object: Object3D,
+  target: { readonly position: Vec3; readonly scale: Vec3 },
+  start: number,
+  transition: { readonly seconds: number; readonly easing: Easing },
+): Tween => ({
+  fromPosition: object.position.toArray(),
+  fromScale: object.scale.toArray(),
+  toPosition: target.position,
+  toScale: target.scale,
+  start,
+  seconds: transition.seconds,
+  easing: transition.easing,
+});
+
+const lerp = (from: number, to: number, amount: number): number => from + (to - from) * amount;
+
+/**
+ * Writes the tween's pose at `elapsedSeconds` into the object without allocating.
+ * Returns true once the tween has finished, after writing the exact targets.
+ */
+export const applyTween = (object: Object3D, tween: Tween, elapsedSeconds: number): boolean => {
+  const progress = Math.min(1, Math.max(0, (elapsedSeconds - tween.start) / tween.seconds));
+  if (progress >= 1) {
+    object.position.set(tween.toPosition[0], tween.toPosition[1], tween.toPosition[2]);
+    object.scale.set(tween.toScale[0], tween.toScale[1], tween.toScale[2]);
+    return true;
+  }
+  const amount = easeProgress(tween.easing, progress);
+  object.position.set(
+    lerp(tween.fromPosition[0], tween.toPosition[0], amount),
+    lerp(tween.fromPosition[1], tween.toPosition[1], amount),
+    lerp(tween.fromPosition[2], tween.toPosition[2], amount),
+  );
+  object.scale.set(
+    lerp(tween.fromScale[0], tween.toScale[0], amount),
+    lerp(tween.fromScale[1], tween.toScale[1], amount),
+    lerp(tween.fromScale[2], tween.toScale[2], amount),
+  );
+  return false;
+};