@opsydyn/effect-three 0.0.0-stage → 0.1.0

package/src/kernel/loop.ts

@@ -0,0 +1,248 @@
+import { Box3, EquirectangularReflectionMapping, type Texture, UVMapping } from 'three';
+
+import type { RenderSettings } from './description.ts';
+import { type OverlayPlacement, placeOverlays } from './overlays.ts';
+import { createPerformanceMonitor, type PerformanceOptions } from './performance.ts';
+/**
+ * The per-frame step and pointer routing for one scene. Plain synchronous code: the
+ * Effect runtime owns its lifetime (ADR-003: Effect owns lifetimes, not frames).
+ *
+ * @module
+ */
+import {
+  createPicker,
+  createPointerTracker,
+  type PointerInput,
+  type SceneEvent,
+} from './pointer.ts';
+import type { RenderTarget, SceneRenderer } from './renderer.ts';
+import type { ContactShadowPasses } from './renderKit.ts';
+import type { SceneGraph } from './sceneGraph.ts';
+import { createXrTracker, type XrInput } from './xrInput.ts';
+
+export type SceneLoopOptions = {
+  readonly graph: SceneGraph;
+  readonly renderer: SceneRenderer;
+  /** Scene time in seconds. Behaviours are a pure function of it. */
+  readonly elapsedSeconds: () => number;
+  /** Receives every scene event. Must not throw. */
+  readonly emit: (event: SceneEvent) => void;
+  /** Wall-clock milliseconds, for the frame-rate monitor. Defaults to `Date.now`. */
+  readonly now?: () => number;
+  /** Tuning for the frame-rate monitor. */
+  readonly performance?: PerformanceOptions;
+  /**
+   * Receives where the scene's overlays are after each drawn frame, for the host to move
+   * their HTML there; once with none after the last overlay goes. Must not throw.
+   */
+  readonly placeOverlays?: (placements: ReadonlyArray<OverlayPlacement>) => void;
+};
+
+export type SceneLoop = {
+  /** Advances behaviours, re-tests hover and renders one frame. */
+  readonly frame: () => void;
+  /**
+   * Whether frames should keep coming: always in `always` mode, while the graph needs one
+   * in `demand` mode, never in `never` mode (frames then come only from `advance`).
+   */
+  readonly wantsFrames: () => boolean;
+  /** Releases the render textures' targets and withdraws their textures. */
+  readonly dispose: () => void;
+  /**
+   * Routes pointer input to hit testing, emits the resulting events and returns them, so
+   * a DOM listener can decide synchronously whether the scene handled its event.
+   */
+  readonly pointer: (input: PointerInput) => ReadonlyArray<SceneEvent>;
+  /** Routes XR input (aims, selects, sticks, buttons, surfaces), emitting the events. */
+  readonly xrInput: (input: XrInput) => ReadonlyArray<SceneEvent>;
+};
+
+/** Creates the frame step and pointer router for one scene. */
+const noContactShadows: ContactShadowPasses = { draw: () => undefined, dispose: () => undefined };
+
+export const createSceneLoop = (options: SceneLoopOptions): SceneLoop => {
+  const { graph, renderer, elapsedSeconds, emit } = options;
+  const picker = createPicker(graph);
+  const tracker = createPointerTracker(picker);
+  const xrTracker = createXrTracker(picker);
+  const monitor = createPerformanceMonitor(options.performance);
+  const now = options.now ?? Date.now;
+  let configured: RenderSettings | undefined;
+  // Whether overlays were placed last frame, so their going is reported once.
+  let placedAny = false;
+  // One offscreen target per render texture, its texture lent to the store under its id.
+  const targets = new Map<
+    string,
+    {
+      readonly target: RenderTarget;
+      readonly width: number;
+      readonly height: number;
+      readonly withdraw: () => void;
+      fresh: boolean;
+    }
+  >();
+
+  const release = (id: string): void => {
+    const held = targets.get(id);
+    if (held === undefined) return;
+    held.withdraw();
+    held.target.dispose();
+    targets.delete(id);
+  };
+
+  /** Draws each render texture whose scene changed or animates, into its own target. */
+  const drawTextures = (): void => {
+    const textures = graph.renderTextures();
+    for (const texture of textures) {
+      const held = targets.get(texture.id);
+      if (held === undefined || held.width !== texture.width || held.height !== texture.height) {
+        release(texture.id);
+        const target = renderer.createTarget(texture.width, texture.height);
+        const withdraw = graph.store.lendTexture(texture.id, target.texture);
+        targets.set(texture.id, {
+          target,
+          width: texture.width,
+          height: texture.height,
+          withdraw,
+          fresh: true,
+        });
+      }
+      const current = targets.get(texture.id);
+      if (current !== undefined && (current.fresh || texture.graph.needsFrame())) {
+        renderer.render(texture.graph.scene, texture.graph.camera, undefined, current.target);
+        texture.graph.drawn();
+        current.fresh = false;
+      }
+    }
+    if (targets.size > textures.length) {
+      const live = new Set(textures.map((texture) => texture.id));
+      for (const id of targets.keys()) if (!live.has(id)) release(id);
+    }
+  };
+  // Contact shadows are shaded: the render kit draws them, or nothing does.
+  const contact = graph.kit?.contactShadows(graph, renderer) ?? noContactShadows;
+  // The room environment, made by the renderer while a scene asks for it.
+  let room: RenderTarget | undefined;
+
+  const releaseRoom = (): void => {
+    room?.dispose();
+    room = undefined;
+  };
+
+  /** The environment's texture: the room, or the lent map (set to reflect as a panorama). */
+  const environmentTexture = (map: string | null): Texture | null => {
+    if (map === null) {
+      room ??= renderer.createEnvironment();
+      return room.texture;
+    }
+    releaseRoom();
+    const texture = graph.store.texture(map) ?? null;
+    // As Drei's useEnvironment: an equirectangular image maps as a reflection panorama.
+    if (texture !== null && texture.mapping === UVMapping) {
+      texture.mapping = EquirectangularReflectionMapping;
+      texture.needsUpdate = true;
+    }
+    return texture;
+  };
+
+  /** Applies the scene's environment as Drei's `setEnvProps` does. */
+  const applyEnvironment = (): void => {
+    const environment = graph.environment();
+    const { scene } = graph;
+    if (environment === null) {
+      releaseRoom();
+      scene.environment = null;
+      scene.background = null;
+      return;
+    }
+    const texture = environmentTexture(environment.map);
+    scene.environment = environment.background === 'only' ? null : texture;
+    scene.background = environment.background === false ? null : texture;
+    scene.backgroundBlurriness = environment.backgroundBlurriness;
+    scene.backgroundIntensity = environment.backgroundIntensity;
+    scene.environmentIntensity = environment.environmentIntensity;
+  };
+
+  // The last box reported for each measured key, so only changes are reported.
+  const reported = new Map<string, Box3>();
+  const box = new Box3();
+
+  // The last layout reported for each measured label.
+  const laidOut = new Map<string, string>();
+
+  const measureLabel = (key: string): void => {
+    const layout = graph.labelLayout(key);
+    if (layout === undefined) return;
+    const signature = [...layout.block, ...layout.visible].join(',');
+    if (laidOut.get(key) === signature) return;
+    laidOut.set(key, signature);
+    emit({ _tag: 'LabelMeasured', key, block: layout.block, visible: layout.visible });
+  };
+
+  const measure = (): void => {
+    const keys = graph.measured();
+    if (keys.length === 0 && reported.size === 0 && laidOut.size === 0) return;
+    for (const key of keys) {
+      measureLabel(key);
+      const object = graph.object(key);
+      if (object === undefined) continue;
+      box.setFromObject(object);
+      if (box.isEmpty()) continue;
+      const last = reported.get(key);
+      if (last !== undefined && last.equals(box)) continue;
+      reported.set(key, box.clone());
+      emit({ _tag: 'Measured', key, min: box.min.toArray(), max: box.max.toArray() });
+    }
+    for (const key of reported.keys()) if (!keys.includes(key)) reported.delete(key);
+    for (const key of laidOut.keys()) if (!keys.includes(key)) laidOut.delete(key);
+  };
+
+  return {
+    frame: () => {
+      graph.tick(elapsedSeconds());
+      for (const event of tracker.frame()) emit(event);
+      for (const collision of graph.collisions()) emit({ _tag: 'Collision', ...collision });
+      for (const force of graph.contactForces()) emit({ _tag: 'ContactForce', ...force });
+      // Settings change only through reconcile, which replaces the value: compare by reference.
+      const settings = graph.renderSettings();
+      if (settings !== configured) {
+        renderer.configure(settings);
+        configured = settings;
+      }
+      drawTextures();
+      applyEnvironment();
+      contact.draw();
+      const views = graph.views();
+      if (views.length === 0) renderer.render(graph.scene, graph.camera);
+      for (const view of views) renderer.render(graph.scene, view.camera, view.area);
+      graph.drawn();
+      measure();
+      const overlays = graph.overlays();
+      if (options.placeOverlays !== undefined && (overlays.length > 0 || placedAny)) {
+        options.placeOverlays(placeOverlays(graph));
+        placedAny = overlays.length > 0;
+      }
+      const change = monitor.sample(now());
+      if (change !== undefined) emit({ _tag: 'PerformanceChanged', ...change });
+    },
+    dispose: () => {
+      for (const id of targets.keys()) release(id);
+      releaseRoom();
+      contact.dispose();
+    },
+    wantsFrames: () => {
+      const mode = graph.renderSettings().frames;
+      return mode === 'always' || (mode === 'demand' && graph.needsFrame());
+    },
+    pointer: (input) => {
+      const events = tracker.input(input);
+      for (const event of events) emit(event);
+      return events;
+    },
+    xrInput: (input) => {
+      const events = xrTracker(input);
+      for (const event of events) emit(event);
+      return events;
+    },
+  };
+};

package/src/kernel/materials.ts

@@ -0,0 +1,258 @@
+/**
+ * Building and updating three.js materials from descriptions.
+ *
+ * Kinds and defaults follow three.js's mesh materials (`three/src/materials`). A change
+ * within one kind is applied in place; when it touches something compiled into the shader
+ * (transparency, side, flat shading) the material is flagged for recompilation, as three
+ * requires. A change of kind needs a new material, which the resource store handles.
+ *
+ * @module
+ */
+import {
+  BackSide,
+  DoubleSide,
+  FrontSide,
+  MeshBasicMaterial,
+  MeshLambertMaterial,
+  MeshNormalMaterial,
+  MeshPhongMaterial,
+  MeshPhysicalMaterial,
+  MeshStandardMaterial,
+  ShadowMaterial as ThreeShadowMaterial,
+  type Side,
+  type Texture,
+} from 'three';
+
+import type {
+  BasicMaterial,
+  LambertMaterial,
+  MaterialSide,
+  NormalMaterial,
+  PhongMaterial,
+  PhysicalMaterial,
+  ShadowMaterial,
+  StandardMaterial,
+  SurfaceMaterial,
+} from './description.ts';
+
+/** Looks up a texture lent to the store. */
+export type Textures = (id: string) => Texture | undefined;
+
+const noTextures: Textures = () => undefined;
+
+/** Sets the colour map. Returns whether the shader must recompile (a map came or went). */
+const applyMap = (
+  material: Exclude<HostMaterial, MeshNormalMaterial | ThreeShadowMaterial>,
+  id: string | null,
+  textures: Textures,
+): boolean => {
+  const map = id === null ? null : (textures(id) ?? null);
+  const recompile = (material.map === null) !== (map === null);
+  material.map = map;
+  return recompile;
+};
+
+/** The three.js material kinds the kernel hosts. */
+export type HostMaterial =
+  | MeshBasicMaterial
+  | MeshLambertMaterial
+  | MeshPhongMaterial
+  | MeshStandardMaterial
+  | MeshPhysicalMaterial
+  | MeshNormalMaterial
+  | ThreeShadowMaterial;
+
+const sides = { front: FrontSide, back: BackSide, double: DoubleSide } satisfies Record<
+  MaterialSide,
+  Side
+>;
+
+type SurfaceFields = {
+  readonly opacity: number;
+  readonly transparent: boolean;
+  readonly side: MaterialSide;
+  readonly wireframe: boolean;
+};
+
+type Shaded = SurfaceFields & { readonly flatShading: boolean };
+
+/** Applies the fields every kind shares. Returns whether the shader must recompile. */
+const applySurface = (
+  material: Exclude<HostMaterial, ThreeShadowMaterial>,
+  description: SurfaceFields,
+): boolean => {
+  const side = sides[description.side];
+  const recompile = material.transparent !== description.transparent || material.side !== side;
+  material.opacity = description.opacity;
+  material.transparent = description.transparent;
+  material.side = side;
+  material.wireframe = description.wireframe;
+  return recompile;
+};
+
+const applyShaded = (
+  material: Exclude<HostMaterial, MeshBasicMaterial | ThreeShadowMaterial>,
+  description: Shaded,
+  mapChanged = false,
+): void => {
+  const flatChanged = material.flatShading !== description.flatShading;
+  material.flatShading = description.flatShading;
+  if (applySurface(material, description) || flatChanged || mapChanged) {
+    material.needsUpdate = true;
+  }
+};
+
+const applyBasic = (
+  material: MeshBasicMaterial,
+  description: BasicMaterial,
+  textures: Textures,
+): void => {
+  material.color.setHex(description.color);
+  const mapChanged = applyMap(material, description.map, textures);
+  if (applySurface(material, description) || mapChanged) material.needsUpdate = true;
+};
+
+const applyLambert = (
+  material: MeshLambertMaterial,
+  description: LambertMaterial,
+  textures: Textures,
+): void => {
+  material.color.setHex(description.color);
+  material.emissive.setHex(description.emissive);
+  applyShaded(material, description, applyMap(material, description.map, textures));
+};
+
+const applyPhong = (
+  material: MeshPhongMaterial,
+  description: PhongMaterial,
+  textures: Textures,
+): void => {
+  material.color.setHex(description.color);
+  material.emissive.setHex(description.emissive);
+  material.specular.setHex(description.specular);
+  material.shininess = description.shininess;
+  applyShaded(material, description, applyMap(material, description.map, textures));
+};
+
+const applyStandard = (
+  material: MeshStandardMaterial,
+  description: StandardMaterial | PhysicalMaterial,
+  textures: Textures,
+): void => {
+  material.color.setHex(description.color);
+  material.roughness = description.roughness;
+  material.metalness = description.metalness;
+  material.emissive.setHex(description.emissive);
+  material.emissiveIntensity = description.emissiveIntensity;
+  applyShaded(material, description, applyMap(material, description.map, textures));
+};
+
+const applyPhysical = (
+  material: MeshPhysicalMaterial,
+  description: PhysicalMaterial,
+  textures: Textures,
+): void => {
+  applyStandard(material, description, textures);
+  // three's clearcoat and transmission setters recompile when crossing zero.
+  material.clearcoat = description.clearcoat;
+  material.clearcoatRoughness = description.clearcoatRoughness;
+  material.transmission = description.transmission;
+  material.ior = description.ior;
+};
+
+const applyNormal = (material: MeshNormalMaterial, description: NormalMaterial): void => {
+  applyShaded(material, description);
+};
+
+const applyShadow = (material: ThreeShadowMaterial, description: ShadowMaterial): void => {
+  material.color.setHex(description.color);
+  material.opacity = description.opacity;
+};
+
+/** Builds a new material for a description. */
+export const buildMaterial = (
+  description: SurfaceMaterial,
+  textures: Textures = noTextures,
+): HostMaterial => {
+  switch (description._tag) {
+    case 'Shadow': {
+      const material = new ThreeShadowMaterial();
+      applyShadow(material, description);
+      return material;
+    }
+    case 'Basic': {
+      const material = new MeshBasicMaterial();
+      applyBasic(material, description, textures);
+      return material;
+    }
+    case 'Lambert': {
+      const material = new MeshLambertMaterial();
+      applyLambert(material, description, textures);
+      return material;
+    }
+    case 'Phong': {
+      const material = new MeshPhongMaterial();
+      applyPhong(material, description, textures);
+      return material;
+    }
+    case 'Standard': {
+      const material = new MeshStandardMaterial();
+      applyStandard(material, description, textures);
+      return material;
+    }
+    case 'Physical': {
+      const material = new MeshPhysicalMaterial();
+      applyPhysical(material, description, textures);
+      return material;
+    }
+    case 'Normal': {
+      const material = new MeshNormalMaterial();
+      applyNormal(material, description);
+      return material;
+    }
+  }
+};
+
+/**
+ * Applies a description to an existing material in place. Returns `false`, changing
+ * nothing, when the material is a different kind: the caller must build a new one.
+ */
+export const updateMaterial = (
+  material: HostMaterial,
+  description: SurfaceMaterial,
+  textures: Textures = noTextures,
+): boolean => {
+  // MeshPhysicalMaterial extends MeshStandardMaterial, so test the exact kind by type.
+  switch (description._tag) {
+    case 'Shadow':
+      if (!(material instanceof ThreeShadowMaterial)) return false;
+      applyShadow(material, description);
+      return true;
+    case 'Basic':
+      if (!(material instanceof MeshBasicMaterial)) return false;
+      applyBasic(material, description, textures);
+      return true;
+    case 'Lambert':
+      if (!(material instanceof MeshLambertMaterial)) return false;
+      applyLambert(material, description, textures);
+      return true;
+    case 'Phong':
+      if (!(material instanceof MeshPhongMaterial)) return false;
+      applyPhong(material, description, textures);
+      return true;
+    case 'Standard':
+      if (material.type !== 'MeshStandardMaterial' || !(material instanceof MeshStandardMaterial)) {
+        return false;
+      }
+      applyStandard(material, description, textures);
+      return true;
+    case 'Physical':
+      if (!(material instanceof MeshPhysicalMaterial)) return false;
+      applyPhysical(material, description, textures);
+      return true;
+    case 'Normal':
+      if (!(material instanceof MeshNormalMaterial)) return false;
+      applyNormal(material, description);
+      return true;
+  }
+};

package/src/kernel/motion.ts

@@ -0,0 +1,75 @@
+/**
+ * Registered behaviours: application motion as pure functions of scene time.
+ *
+ * A behaviour writes a pose (a position offset, a rotation and a scale factor) into a
+ * reused scratch value, so ticking allocates nothing. The scene graph composes that pose
+ * on top of the node's own transform each frame: position added, rotation added, scale
+ * multiplied. Because the pose depends only on time and parameters, behaviours pause,
+ * rewind and replay with the scene, unlike `useFrame` callbacks that mutate state.
+ *
+ * @module
+ */
+import { Vector3 } from 'three';
+
+/** Where a behaviour writes its pose. Reset to no change before every call. */
+export type BehaviourPose = {
+  /** Added to the node's position, in its parent's space. */
+  readonly offset: Vector3;
+  /** Euler angles (radians) added to the node's rotation. */
+  readonly rotation: Vector3;
+  /** Multiplies the node's scale. */
+  readonly scale: Vector3;
+};
+
+/** A behaviour: writes the pose for `seconds` of scene time and the node's parameters. */
+export type Behaviour = (
+  pose: BehaviourPose,
+  seconds: number,
+  params: Readonly<Record<string, number>>,
+) => void;
+
+/** A pose that changes nothing. */
+export const createPose = (): BehaviourPose => ({
+  offset: new Vector3(),
+  rotation: new Vector3(),
+  scale: new Vector3(1, 1, 1),
+});
+
+export const resetPose = (pose: BehaviourPose): void => {
+  pose.offset.set(0, 0, 0);
+  pose.rotation.set(0, 0, 0);
+  pose.scale.set(1, 1, 1);
+};
+
+/** Maps `value` from one range to another, as three's `MathUtils.mapLinear`. */
+const mapLinear = (value: number, a1: number, a2: number, b1: number, b2: number): number =>
+  b1 + ((value - a1) * (b2 - b1)) / (a2 - a1);
+
+/**
+ * Drei's `Float` (`drei-main/src/core/Float.tsx` at `bf6f4ad`): a gentle bob and sway.
+ * Parameters (Drei's defaults): `speed` 1, `rotationIntensity` 1, `floatIntensity` 1,
+ * `low` -0.1 and `high` 0.1 (Drei's `floatingRange`), and `phase` 0 in place of Drei's
+ * random start, so the motion is the same on every run.
+ */
+export const float: Behaviour = (pose, seconds, params) => {
+  const speed = params['speed'] ?? 1;
+  const turn = params['rotationIntensity'] ?? 1;
+  const lift = params['floatIntensity'] ?? 1;
+  const angle = (((params['phase'] ?? 0) + seconds) / 4) * speed;
+  pose.rotation.set(
+    (Math.cos(angle) / 8) * turn,
+    (Math.sin(angle) / 8) * turn,
+    (Math.sin(angle) / 20) * turn,
+  );
+  const y = mapLinear(
+    Math.sin(angle) / 10,
+    -0.1,
+    0.1,
+    params['low'] ?? -0.1,
+    params['high'] ?? 0.1,
+  );
+  pose.offset.set(0, y * lift, 0);
+};
+
+/** Behaviours every scene knows without registering them. */
+export const builtinBehaviours: Readonly<Record<string, Behaviour>> = { float };