@opsydyn/effect-three 0.3.0 → 0.6.4

package/src/kernel/build.ts

@@ -3,8 +3,16 @@
  *
  * @module
  */
+import { CatmullRomCurve3, Color, CubicBezierCurve3, QuadraticBezierCurve3, Vector3 } from 'three';
+
 import type {
+  Asset,
   AmbientLightNode,
+  LineNode,
+  PointLook,
+  PointsNode,
+  Edges,
+  Trail,
   Animation,
   CameraShake,
   Detail,
@@ -18,6 +26,8 @@ import type {
   ContactShadows,
   Environment,
   Gestures,
+  Hud,
+  HudAlignment,
   GridNode,
   Sky,
   Xr,
@@ -344,6 +354,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,
 });
 
 /**
@@ -539,6 +550,7 @@ export const group = (
     readonly body?: Body | null;
     readonly follow?: XrSpace | null;
     readonly detail?: Detail | null;
+    readonly trail?: Trail | null;
   },
 ): GroupNode => ({
   _tag: 'Group',
@@ -553,6 +565,7 @@ export const group = (
   body: options.body ?? null,
   follow: options.follow ?? null,
   detail: options.detail ?? null,
+  trail: options.trail ?? null,
 });
 
 /**
@@ -566,6 +579,272 @@ export const detailed = (options: {
   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' });
 
@@ -620,6 +899,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',
@@ -635,6 +916,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,
 });
 
 /**
@@ -751,13 +1068,19 @@ const noJoints: ReadonlyArray<Joint> = [];
 
 /**
  * A physics world. Defaults as react-three-rapier's `Physics`: Earth gravity
- * `[0, -9.81, 0]`, running, fixed steps of 1/60 s, interpolated; no joints.
+ * `[0, -9.81, 0]`, running, fixed steps of 1/60 s, interpolated; no joints; on scene
+ * time rather than `until` a step the Model sets.
  */
 export const physics = (options: Partial<Physics> = {}): Physics => ({
   gravity: options.gravity ?? [0, -9.81, 0],
   paused: options.paused ?? false,
   timeStep: options.timeStep ?? 1 / 60,
   interpolate: options.interpolate ?? true,
+  until: options.until ?? null,
+  run: options.run ?? 0,
+  snapshotAt: options.snapshotAt ?? null,
+  from: options.from ?? null,
+  keep: options.keep ?? 0,
   debug: options.debug ?? false,
   joints: options.joints ?? noJoints,
 });
@@ -1358,6 +1681,38 @@ export const contactShadows = (
 
 const noOverlays: ReadonlyArray<Overlay> = [];
 const noMeasures: ReadonlyArray<string> = [];
+const noAssets: ReadonlyArray<Asset> = [];
+
+/** What an asset builder takes: an id, the finest URL, and coarser ones to show first. */
+type AssetOptions = {
+  readonly id: string;
+  readonly url: string;
+  readonly levels?: ReadonlyArray<string>;
+};
+
+const noLevels: ReadonlyArray<string> = [];
+
+const assetOf =
+  (kind: Asset['kind']) =>
+  ({ id, url, levels }: AssetOptions): Asset => ({ kind, id, url, levels: levels ?? noLevels });
+
+/** A glTF or GLB model for `scene({ assets })`, lent under `id` for `borrowed({ id })`. */
+export const modelAsset = assetOf('model');
+
+/** A colour texture (sRGB) for `scene({ assets })`, lent under `id` for a material's `map`. */
+export const textureAsset = assetOf('texture');
+
+/**
+ * An equirectangular HDR panorama (`.hdr`) for `scene({ assets })`, lent under `id` for
+ * `environment({ map: id })`.
+ */
+export const environmentAsset = assetOf('environment');
+
+/**
+ * A typeface JSON font (three.js's `FontLoader` format) for `scene({ assets })`, lent under
+ * `id` for `text({ font: id })`.
+ */
+export const fontAsset = assetOf('font');
 
 /** Drei's `zIndexRange` default: near points on top, far ones at 0. */
 const defaultZIndexRange: readonly [number, number] = [16777271, 0];
@@ -1386,11 +1741,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;
@@ -1399,6 +1769,7 @@ export const scene = (options: {
   readonly physics?: Physics | null;
   readonly xr?: Xr | null;
   readonly measure?: ReadonlyArray<string>;
+  readonly assets?: ReadonlyArray<Asset>;
   readonly render?: RenderSettings;
   readonly resources?: Partial<ResourceDefinitions>;
   readonly children?: ReadonlyArray<SceneNode>;
@@ -1407,6 +1778,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,
@@ -1414,6 +1786,7 @@ export const scene = (options: {
   physics: options.physics ?? null,
   xr: options.xr ?? null,
   measure: options.measure ?? noMeasures,
+  assets: options.assets ?? noAssets,
   render: options.render ?? defaultRenderSettings,
   resources: {
     geometries: options.resources?.geometries ?? noResources.geometries,

package/src/kernel/cameraShake.ts

@@ -15,20 +15,10 @@ import { SimplexNoise } from 'three/addons/math/SimplexNoise.js';
 
 import type { CameraShake } from './description.ts';
 import { cameraShakeEquals } from './equality.ts';
+import { seededRandom } from './seeded.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;
-    },
-  };
-};
+/** 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));