@opsydyn/effect-three 0.3.0 → 0.4.0

package/src/kernel/description.ts

@@ -208,6 +208,11 @@ export type BasicMaterial = {
   readonly transparent: boolean;
   readonly side: MaterialSide;
   readonly wireframe: boolean;
+  /**
+   * Whether it is hidden behind what is nearer, as usual; `false` draws it over
+   * everything (and writes no depth), as three's gizmos and helpers are drawn.
+   */
+  readonly depthTest: boolean;
 };
 
 /** A matte (Lambertian) material: cheap per-vertex lighting, no highlights. */
@@ -390,6 +395,8 @@ export type GroupNode = {
    * distance (Drei's `Detailed`, three's `LOD`), or `null` to show them all.
    */
   readonly detail: Detail | null;
+  /** A ribbon behind the group as it moves (Drei's `Trail`), or `null` for none. */
+  readonly trail: Trail | null;
 };
 
 /**
@@ -470,6 +477,47 @@ export type MeshNode = {
   readonly receiveShadow: boolean;
   /** A rigid body simulating the mesh, when the scene has `physics`; `null` for none. */
   readonly body: Body | null;
+  /** Lines along the mesh's hard edges (Drei's `Edges`), or `null` for none. */
+  readonly edges: Edges | null;
+  /** A ribbon behind the mesh as it moves (Drei's `Trail`), or `null` for none. */
+  readonly trail: Trail | null;
+};
+
+/**
+ * A trail behind a moving node, as Drei's `Trail`: `length × 10` points of where it has
+ * been, a new one every `interval` steps (60 a second of scene time) when it has moved at
+ * least `stride`, `decay` of them at a time; drawn as a ribbon facing the camera, a tenth
+ * of `width` wide in scene units, narrowing (`taper`) and fading (`fade`) to the tail.
+ * `local` follows the node's own position rather than its world position, as Drei's
+ * does; the ribbon is drawn in the scene's space either way.
+ */
+export type Trail = {
+  readonly width: number;
+  readonly length: number;
+  readonly decay: number;
+  readonly local: boolean;
+  readonly stride: number;
+  readonly interval: number;
+  readonly color: Rgb;
+  readonly taper: 'none' | 'linear' | 'quadratic';
+  readonly fade: boolean;
+};
+
+/**
+ * Lines along a mesh's edges where its faces meet at more than `threshold` degrees
+ * (three's `EdgesGeometry`, as Drei's `Edges`), drawn as a line (`width` pixels, or scene
+ * units with `worldUnits`) by the render kit. Never picked: hits go to the mesh.
+ */
+export type Edges = {
+  readonly threshold: number;
+  readonly color: Rgb;
+  readonly width: number;
+  readonly worldUnits: boolean;
+  readonly dashed: boolean;
+  readonly dashSize: number;
+  readonly gapSize: number;
+  readonly opacity: number;
+  readonly transparent: boolean;
 };
 
 /**
@@ -928,8 +976,106 @@ export type ShaderGridNode = {
   readonly side: MaterialSide;
 };
 
+/**
+ * A line through points, as Drei's `Line` (three's fat lines, `Line2`): `width` pixels
+ * wide on screen, or scene units with `worldUnits`; one colour, or one per point; solid
+ * or dashed. With `segments` each pair of points is its own segment (Drei's `Segments`).
+ * A render kit draws it; without one it is an empty group.
+ */
+export type LineNode = {
+  readonly _tag: 'Line';
+  readonly key: string;
+  readonly position: Vec3;
+  readonly rotation: Rotation;
+  readonly scale: Vec3;
+  readonly transition: Transition;
+  readonly behaviour: Behave | null;
+  /** Makes the line pickable, within its width. */
+  readonly interactive: boolean;
+  readonly points: ReadonlyArray<Vec3>;
+  readonly segments: boolean;
+  readonly color: Rgb;
+  /** A colour for each point, blended along the line, or `null` for `color` throughout. */
+  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;
+};
+
+/**
+ * Points, drawn by the render kit as round or square dots, Drei's sparkles or its
+ * stars. The look says which, and carries everything needed to draw them: given
+ * points, or a seed that scatters them the same way every time.
+ */
+export type PointsNode = {
+  readonly _tag: 'Points';
+  readonly key: string;
+  readonly position: Vec3;
+  readonly rotation: Rotation;
+  readonly scale: Vec3;
+  readonly transition: Transition;
+  readonly behaviour: Behave | null;
+  readonly look: PointLook;
+};
+
+/**
+ * What points look like:
+ *
+ * - `Dots`: Drei's `Points` with its `PointMaterial` (three's `PointsMaterial`, `round`
+ *   to circles): `size` pixels across, smaller with distance under `sizeAttenuation`;
+ *   one colour or one a point, one size or a factor a point.
+ * - `Sparkles`: Drei's `Sparkles`: `count` glowing motes scattered through a box of
+ *   `scale`, drifting by `noise` at `speed`.
+ * - `Stars`: Drei's `Stars`: `count` stars in a shell from `radius` to `radius + depth`,
+ *   `factor` sizing them, twinkling at `speed`, `fade` softening their edges.
+ */
+export type PointLook =
+  | {
+      readonly _tag: 'Dots';
+      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;
+    }
+  | {
+      readonly _tag: 'Sparkles';
+      readonly count: number;
+      readonly speed: number;
+      readonly opacity: number;
+      readonly scale: Vec3;
+      /** Each mote's size, or `null` for Drei's: random, up to 1. */
+      readonly size: number | null;
+      readonly color: Rgb;
+      readonly noise: Vec3;
+      readonly seed: number;
+    }
+  | {
+      readonly _tag: 'Stars';
+      readonly radius: number;
+      readonly depth: number;
+      readonly count: number;
+      readonly factor: number;
+      readonly saturation: number;
+      readonly fade: boolean;
+      readonly speed: number;
+      readonly seed: number;
+    };
+
 /** Any node in a scene. Keys are unique across the whole scene. */
 export type SceneNode =
+  | PointsNode
+  | LineNode
   | GridNode
   | ShaderGridNode
   | GroupNode
@@ -1080,6 +1226,33 @@ export type ViewRect = {
  */
 export type View = { readonly key: string; readonly camera: Camera; readonly rect: ViewRect };
 
+/** Where a HUD's origin sits on the canvas: a corner, an edge's middle, or the centre. */
+export type HudAlignment =
+  | 'top-left'
+  | 'top-center'
+  | 'top-right'
+  | 'center-left'
+  | 'center-center'
+  | 'center-right'
+  | 'bottom-left'
+  | 'bottom-center'
+  | 'bottom-right';
+
+/**
+ * Nodes drawn over the scene, Drei's `Hud`, as data: a scene of their own (keys apart
+ * from the scene's), drawn after it with only its depth cleared, through an orthographic
+ * camera measured in CSS pixels, y up, whose origin sits `margin` pixels in from the
+ * `alignment`'s edges (Drei's `GizmoHelper` places its gizmo so). Pointer events reach
+ * its interactive meshes before anything behind them; their points and rays are in the
+ * HUD's own space. Scene lighting and fog do not reach it.
+ */
+export type Hud = {
+  readonly alignment: HudAlignment;
+  /** CSS pixels in from the aligned edges, `[x, y]`: unused for a centred direction. */
+  readonly margin: readonly [number, number];
+  readonly children: ReadonlyArray<SceneNode>;
+};
+
 /**
  * A small scene rendered into a texture that materials use as `map: id`: Drei's
  * `RenderTexture`, as data. Its nodes have their own key namespace and may use the
@@ -1264,6 +1437,8 @@ export type SceneDescription = {
   readonly views: ReadonlyArray<View>;
   /** Scenes rendered into textures for materials to use. */
   readonly renderTextures: ReadonlyArray<RenderTexture>;
+  /** Nodes drawn over the scene, or `null` for none. */
+  readonly hud: Hud | null;
   /** Points to show HTML at, placed every frame the scene draws. */
   readonly overlays: ReadonlyArray<Overlay>;
   /** Image-based lighting and background, or `null` for none. */

package/src/kernel/diff.ts

@@ -31,6 +31,10 @@ import {
   labelMaterialEquals,
   labelTypeEquals,
   xrSpaceEquals,
+  lineLookEquals,
+  edgesEquals,
+  trailEquals,
+  pointLookEquals,
   detailEquals,
   shaderGridLookEquals,
   instancesEqual,
@@ -82,6 +86,14 @@ export type Field =
   | 'text'
   /** A shader grid's look: anything but where it is. */
   | 'grid'
+  /** A line's points or look: anything but where it is. */
+  | 'line'
+  /** A mesh's edge lines. */
+  | 'edges'
+  /** A group's or mesh's trail. */
+  | 'trail'
+  /** Points' look: what they are and where, within the node. */
+  | 'look'
   /** The tracked space a group follows. */
   | 'follow'
   /** A group's levels of detail. */
@@ -94,6 +106,9 @@ export type Op =
   /** A render texture was created, resized or its scene changed (its own operations). */
   | { readonly _tag: 'UpdateRenderTexture'; readonly id: string; readonly ops: ReadonlyArray<Op> }
   | { readonly _tag: 'RemoveRenderTexture'; readonly id: string }
+  /** The HUD was created or its scene changed (its own operations). */
+  | { readonly _tag: 'UpdateHud'; readonly ops: ReadonlyArray<Op> }
+  | { readonly _tag: 'RemoveHud' }
   | { readonly _tag: 'SetRenderSettings'; readonly settings: RenderSettings }
   | { readonly _tag: 'DefineResources'; readonly resources: ResourceDefinitions }
   | { readonly _tag: 'Create'; readonly node: SceneNode; readonly parent: ParentKey }
@@ -135,6 +150,7 @@ export const changedFields = (
       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');
+      if (!trailEquals(prev.trail, next.trail)) fields.push('trail');
       return fields;
     }
     case 'Mesh': {
@@ -150,6 +166,8 @@ export const changedFields = (
       if (prev.castShadow !== next.castShadow) fields.push('castShadow');
       if (prev.receiveShadow !== next.receiveShadow) fields.push('receiveShadow');
       if (!bodyEquals(prev.body, next.body)) fields.push('body');
+      if (!edgesEquals(prev.edges, next.edges)) fields.push('edges');
+      if (!trailEquals(prev.trail, next.trail)) fields.push('trail');
       return fields;
     }
     case 'Instances': {
@@ -239,6 +257,27 @@ export const changedFields = (
       if (!Object.is(prev.shadowBias, next.shadowBias)) fields.push('shadowBias');
       return fields;
     }
+    case 'Points': {
+      if (prev._tag !== 'Points') return undefined;
+      if (!behaviourEquals(prev.behaviour, next.behaviour)) fields.push('behaviour');
+      if (!vec3Equals(prev.position, next.position)) fields.push('position');
+      if (!rotationEquals(prev.rotation, next.rotation)) fields.push('rotation');
+      if (!vec3Equals(prev.scale, next.scale)) fields.push('scale');
+      if (!transitionEquals(prev.transition, next.transition)) fields.push('transition');
+      if (!pointLookEquals(prev.look, next.look)) fields.push('look');
+      return fields;
+    }
+    case 'Line': {
+      if (prev._tag !== 'Line') return undefined;
+      if (!behaviourEquals(prev.behaviour, next.behaviour)) fields.push('behaviour');
+      if (!vec3Equals(prev.position, next.position)) fields.push('position');
+      if (!rotationEquals(prev.rotation, next.rotation)) fields.push('rotation');
+      if (!vec3Equals(prev.scale, next.scale)) fields.push('scale');
+      if (!transitionEquals(prev.transition, next.transition)) fields.push('transition');
+      if (prev.interactive !== next.interactive) fields.push('interactive');
+      if (!lineLookEquals(prev, next)) fields.push('line');
+      return fields;
+    }
     case 'ShaderGrid': {
       if (prev._tag !== 'ShaderGrid') return undefined;
       if (!vec3Equals(prev.position, next.position)) fields.push('position');

package/src/kernel/equality.ts

@@ -9,6 +9,10 @@ import type {
   Behave,
   CameraShake,
   Detail,
+  LineNode,
+  Edges,
+  Trail,
+  PointLook,
   Body,
   BodyRef,
   GeometryRef,
@@ -573,6 +577,103 @@ export const labelMaterialEquals = (a: MaterialRef | null, b: MaterialRef | null
   a === b || (a !== null && b !== null && materialRefEquals(a, b));
 
 /** Shader grid equality, apart from its position and rotation. */
+/** Points' look equality: the same kind with the same settings and points. */
+export const pointLookEquals = (a: PointLook, b: PointLook): boolean => {
+  if (a === b) return true;
+  switch (a._tag) {
+    case 'Dots':
+      return (
+        b._tag === 'Dots' &&
+        a.positions.length === b.positions.length &&
+        a.positions.every((point, index) => vec3Equals(point, b.positions[index] ?? point)) &&
+        numbersEqual(a.colors, b.colors) &&
+        numbersEqual(a.sizes, b.sizes) &&
+        Object.is(a.color, b.color) &&
+        Object.is(a.size, b.size) &&
+        a.sizeAttenuation === b.sizeAttenuation &&
+        a.round === b.round &&
+        Object.is(a.opacity, b.opacity) &&
+        a.transparent === b.transparent
+      );
+    case 'Sparkles':
+      return (
+        b._tag === 'Sparkles' &&
+        a.count === b.count &&
+        Object.is(a.speed, b.speed) &&
+        Object.is(a.opacity, b.opacity) &&
+        vec3Equals(a.scale, b.scale) &&
+        Object.is(a.size, b.size) &&
+        Object.is(a.color, b.color) &&
+        vec3Equals(a.noise, b.noise) &&
+        Object.is(a.seed, b.seed)
+      );
+    case 'Stars':
+      return (
+        b._tag === 'Stars' &&
+        Object.is(a.radius, b.radius) &&
+        Object.is(a.depth, b.depth) &&
+        a.count === b.count &&
+        Object.is(a.factor, b.factor) &&
+        Object.is(a.saturation, b.saturation) &&
+        a.fade === b.fade &&
+        Object.is(a.speed, b.speed) &&
+        Object.is(a.seed, b.seed)
+      );
+  }
+};
+
+/** Trail equality: every setting. */
+export const trailEquals = (a: Trail | null, b: Trail | null): boolean =>
+  a === b ||
+  (a !== null &&
+    b !== null &&
+    Object.is(a.width, b.width) &&
+    Object.is(a.length, b.length) &&
+    Object.is(a.decay, b.decay) &&
+    a.local === b.local &&
+    Object.is(a.stride, b.stride) &&
+    Object.is(a.interval, b.interval) &&
+    Object.is(a.color, b.color) &&
+    a.taper === b.taper &&
+    a.fade === b.fade);
+
+/** Edge lines' equality: every setting. */
+export const edgesEquals = (a: Edges | null, b: Edges | null): boolean =>
+  a === b ||
+  (a !== null &&
+    b !== null &&
+    Object.is(a.threshold, b.threshold) &&
+    Object.is(a.color, b.color) &&
+    Object.is(a.width, b.width) &&
+    a.worldUnits === b.worldUnits &&
+    a.dashed === b.dashed &&
+    Object.is(a.dashSize, b.dashSize) &&
+    Object.is(a.gapSize, b.gapSize) &&
+    Object.is(a.opacity, b.opacity) &&
+    a.transparent === b.transparent);
+
+/** A line's points and look: everything but where it is. */
+export const lineLookEquals = (a: LineNode, b: LineNode): boolean =>
+  a.segments === b.segments &&
+  Object.is(a.color, b.color) &&
+  Object.is(a.width, b.width) &&
+  a.worldUnits === b.worldUnits &&
+  a.dashed === b.dashed &&
+  Object.is(a.dashSize, b.dashSize) &&
+  Object.is(a.gapSize, b.gapSize) &&
+  Object.is(a.dashScale, b.dashScale) &&
+  Object.is(a.dashOffset, b.dashOffset) &&
+  Object.is(a.opacity, b.opacity) &&
+  a.transparent === b.transparent &&
+  (a.points === b.points ||
+    (a.points.length === b.points.length &&
+      a.points.every((point, index) => vec3Equals(point, b.points[index] ?? point)))) &&
+  (a.vertexColors === b.vertexColors ||
+    (a.vertexColors !== null &&
+      b.vertexColors !== null &&
+      a.vertexColors.length === b.vertexColors.length &&
+      a.vertexColors.every((color, index) => Object.is(color, b.vertexColors?.[index]))));
+
 export const shaderGridLookEquals = (a: ShaderGridNode, b: ShaderGridNode): boolean =>
   Object.is(a.size[0], b.size[0]) &&
   Object.is(a.size[1], b.size[1]) &&