@opsydyn/effect-three 0.0.0-stage → 0.1.0

package/src/kernel/frames.ts

@@ -0,0 +1,124 @@
+/**
+ * Frame scheduling contracts. A scheduler calls registered callbacks once per frame:
+ * `requestAnimationFrame` in a browser, three's `setAnimationLoop` for WebGPU and XR, or
+ * a manual scheduler in tests.
+ *
+ * @module
+ */
+
+/** Registers a per-frame callback and returns a function that unregisters it. */
+export type FrameScheduler = {
+  readonly subscribe: (onFrame: () => void) => () => void;
+};
+
+/** A scheduler driven by hand. `step` runs one frame for every subscriber. */
+export type ManualFrames = FrameScheduler & {
+  readonly step: () => void;
+  readonly subscribers: () => number;
+};
+
+/** Creates a manual frame scheduler for deterministic tests. */
+export const createManualFrames = (): ManualFrames => {
+  const callbacks = new Set<() => void>();
+  return {
+    subscribe: (onFrame) => {
+      callbacks.add(onFrame);
+      return () => {
+        callbacks.delete(onFrame);
+      };
+    },
+    step: () => {
+      // Snapshot: callbacks subscribed during this frame first run on the next one.
+      for (const onFrame of Array.from(callbacks)) onFrame();
+    },
+    subscribers: () => callbacks.size,
+  };
+};
+
+/** A scheduler that forwards frames only while open. */
+export type GatedFrames = FrameScheduler & {
+  readonly setOpen: (open: boolean) => void;
+};
+
+/**
+ * Wraps `base` so frames pass only while open: for example, only while the canvas is on
+ * screen, or only while a scene has something to draw. A closed gate unsubscribes from
+ * `base`, so a scheduler that stops when nobody listens (such as the browser's animation
+ * frames) really stops.
+ */
+export const createGatedFrames = (base: FrameScheduler): GatedFrames => {
+  let open = true;
+  const callbacks = new Set<() => void>();
+  let unsubscribe: (() => void) | undefined;
+  const forward = (): void => {
+    // Snapshot: a callback may close the gate or unsubscribe while running.
+    for (const onFrame of Array.from(callbacks)) onFrame();
+  };
+  const sync = (): void => {
+    const wanted = open && callbacks.size > 0;
+    if (wanted && unsubscribe === undefined) unsubscribe = base.subscribe(forward);
+    else if (!wanted && unsubscribe !== undefined) {
+      unsubscribe();
+      unsubscribe = undefined;
+    }
+  };
+  return {
+    subscribe: (onFrame) => {
+      callbacks.add(onFrame);
+      sync();
+      return () => {
+        callbacks.delete(onFrame);
+        sync();
+      };
+    },
+    setOpen: (next) => {
+      open = next;
+      sync();
+    },
+  };
+};
+
+/** Turns a scene's frames on and off. Off unsubscribes, so an idle scheduler can stop. */
+export type FrameControl = {
+  readonly wake: () => void;
+  readonly sleep: () => void;
+};
+
+/** The part of a scene loop that pacing needs. */
+export type Paced = {
+  readonly frame: () => void;
+  readonly wantsFrames: () => boolean;
+};
+
+export type FramePacer = {
+  /** The per-frame callback: draws, then sleeps when no further frame is wanted. */
+  readonly frame: () => void;
+  /** Connects the subscription's control, putting it to sleep if nothing is wanted yet. */
+  readonly attach: (control: FrameControl) => void;
+  /** Wakes the subscription if a frame is now wanted. Call on every invalidation. */
+  readonly wake: () => void;
+  /** Draws one frame now, whatever the mode: React Three Fiber's `advance`. */
+  readonly advance: () => void;
+};
+
+/**
+ * Paces a scene's frames: subscribed while frames are wanted, asleep otherwise, so an
+ * idle scene costs no frames at all.
+ */
+export const createFramePacer = (loop: Paced): FramePacer => {
+  let control: FrameControl | undefined;
+  return {
+    frame: () => {
+      loop.frame();
+      if (!loop.wantsFrames()) control?.sleep();
+    },
+    attach: (next) => {
+      control = next;
+      if (!loop.wantsFrames()) next.sleep();
+    },
+    wake: () => {
+      if (loop.wantsFrames()) control?.wake();
+    },
+    advance: loop.frame,
+  };
+};

package/src/kernel/index.ts

@@ -0,0 +1,274 @@
+/**
+ * The non-Effect kernel (ADR-003): descriptions, keyed diff, applier, behaviours and
+ * resource ownership. Synchronous, allocation-conscious and DOM-free.
+ *
+ * @module
+ */
+export type * from './description.ts';
+export { handJoints } from './description.ts';
+export { clipRunning, clipTime } from './animation.ts';
+export {
+  type Behaviour,
+  type BehaviourPose,
+  builtinBehaviours,
+  createPose,
+  float,
+  resetPose,
+} from './motion.ts';
+export { spinAngle, writeRotation } from './behaviours.ts';
+export { buildMaterial, type HostMaterial, type Textures, updateMaterial } from './materials.ts';
+export { capacityFor, type HostInstances } from './instances.ts';
+export {
+  createPerformanceMonitor,
+  type PerformanceChange,
+  type PerformanceMonitor,
+  type PerformanceOptions,
+} from './performance.ts';
+export { applyTween, easeProgress, startTween, type Tween } from './tween.ts';
+export {
+  ambientLight,
+  basic,
+  behave,
+  bloom,
+  borrowed,
+  box,
+  capsule,
+  body,
+  circle,
+  colorRange,
+  xr,
+  glide,
+  xrAnchor,
+  headSpace,
+  jointSpace,
+  controllerSpace,
+  anchorSpace,
+  planeSpace,
+  meshSpace,
+  xrMesh,
+  xrMeshGeometryId,
+  physics,
+  cuboidCollider,
+  ballCollider,
+  capsuleCollider,
+  cylinderCollider,
+  coneCollider,
+  velocityMotor,
+  interactionGroups,
+  positionMotor,
+  shaderGrid,
+  label,
+  bodyRef,
+  joint,
+  fixedJoint,
+  sphericalJoint,
+  revoluteJoint,
+  prismaticJoint,
+  ropeJoint,
+  springJoint,
+  contactShadows,
+  grid,
+  sky,
+  sunPositionFromAngles,
+  environment,
+  text,
+  cone,
+  cylinder,
+  directionalLight,
+  ease,
+  film,
+  fixed,
+  group,
+  hemisphereLight,
+  instance,
+  instances,
+  instant,
+  lambert,
+  mesh,
+  normalMaterial,
+  shadowMaterial,
+  orthographicCamera,
+  perspectiveCamera,
+  phong,
+  play,
+  physical,
+  plane,
+  pointLight,
+  renderSettings,
+  ring,
+  scene,
+  sharedGeometry,
+  lentGeometry,
+  sharedMaterial,
+  sphere,
+  spin,
+  spotLight,
+  standard,
+  overlay,
+  renderTexture,
+  torus,
+  type TransformOptions,
+  view,
+  vignette,
+} from './build.ts';
+export { changedFields, diff, type DiffResult, type Field, type Op } from './diff.ts';
+export {
+  cameraEquals,
+  animationEquals,
+  behaviourEquals,
+  effectsEqual,
+  geometryRefEquals,
+  instanceEquals,
+  instancesEqual,
+  materialRefEquals,
+  resourcesEqual,
+  renderSettingsEquals,
+  rotationEquals,
+  shapeEquals,
+  transitionEquals,
+  environmentEquals,
+  contactShadowsEquals,
+  bodyEquals,
+  overlaysEqual,
+  xrEquals,
+  physicsEquals,
+  skyEquals,
+  viewsEqual,
+  vec3Equals,
+} from './equality.ts';
+export {
+  createResourceStore,
+  type GeometryReplaced,
+  type Loan,
+  type MaterialReplaced,
+  type ResourceCounts,
+  type ResourceStats,
+  type ResourceStore,
+} from './resources.ts';
+export { createSceneClock, type SceneClock } from './clock.ts';
+export {
+  createFramePacer,
+  createGatedFrames,
+  type FrameControl,
+  type FramePacer,
+  createManualFrames,
+  type FrameScheduler,
+  type GatedFrames,
+  type ManualFrames,
+} from './frames.ts';
+export {
+  autoRotated,
+  type Box,
+  clipCamera,
+  type Cursor,
+  defaultOrbit,
+  dollyCamera,
+  dollyCameraToward,
+  fitCamera,
+  orbit,
+  type OrbitKey,
+  orbitKey,
+  type OrbitOptions,
+  orbitOptions,
+  panCamera,
+  rotateCamera,
+} from './orbit.ts';
+export { type OverlayPlacement, placeOverlays } from './overlays.ts';
+export {
+  type BodyPose,
+  type Collider,
+  type ColliderShape,
+  colliderFor,
+  collidersFor,
+  colliderSignature,
+  type Collision,
+  type ContactForce,
+  type DebugLines,
+  describedColliders,
+  interactionBits,
+  type PhysicsEngine,
+  type PhysicsJoint,
+  type PhysicsWorld,
+  type Quat,
+} from './physics.ts';
+export type { BodyCollision, BodyContactForce } from './bodies.ts';
+export type {
+  ContactShadowPasses,
+  HostedShaderGrid,
+  HostedSky,
+  RenderKit,
+  ShadowedScene,
+} from './renderKit.ts';
+export { glided, type LocomotionOptions, locomote, teleport } from './xrLocomotion.ts';
+export {
+  createXrTracker,
+  type XrButtonName,
+  type XrHand,
+  type XrInput,
+  type XrMesh,
+  type XrPlane,
+  type XrStickDirection,
+} from './xrInput.ts';
+export type { HostedLabel, LabelEngine, LabelLayout } from './labels.ts';
+export {
+  type EnvironmentPreset,
+  environmentPresets,
+  environmentPresetUrl,
+} from './environmentPresets.ts';
+export {
+  type CenterAlign,
+  centerOffset,
+  type Stage,
+  stage,
+  stageBounds,
+  type StageLighting,
+  type StagePreset,
+  stagePresets,
+} from './stage.ts';
+export { createSceneLoop, type SceneLoop, type SceneLoopOptions } from './loop.ts';
+export {
+  createPicker,
+  createPointerTracker,
+  type Gesture,
+  type Hit,
+  type Modifiers,
+  noModifiers,
+  type Picker,
+  type PlaneEquation,
+  pointOnPlane,
+  type PointerInput,
+  type PointerTracker,
+  type Ray,
+  type Region,
+  type SceneEvent,
+} from './pointer.ts';
+export {
+  recordingRendererFactory,
+  type RecordingRenderer,
+  type RenderArea,
+  type RenderTarget,
+  type RecordingRendererFactory,
+  type RendererFactory,
+  type RendererMemory,
+  type SceneRenderer,
+  type Viewport,
+} from './renderer.ts';
+export {
+  createSceneGraph,
+  type HostCamera,
+  type HostedTexture,
+  type HostedView,
+  type HostMesh,
+  type ReconcileResult,
+  type SceneGraph,
+  type SceneGraphOptions,
+} from './sceneGraph.ts';
+export {
+  type DescriptionError,
+  emptyIndex,
+  type IndexedNode,
+  indexScene,
+  type IndexResult,
+  type ParentKey,
+  type SceneIndex,
+} from './sceneIndex.ts';

package/src/kernel/instances.ts

@@ -0,0 +1,97 @@
+/**
+ * Writing instance descriptions into three.js's `InstancedMesh` buffers.
+ *
+ * Slots are positional: instance `i` of the description lives in slot `i`. An update
+ * writes only the slots whose instance changed, so moving one of 10,000 instances writes
+ * one matrix. Capacity grows by doubling, so adding instances rarely reallocates.
+ *
+ * @module
+ */
+import {
+  type BufferGeometry,
+  Color,
+  DynamicDrawUsage,
+  Euler,
+  InstancedMesh,
+  Matrix4,
+  Quaternion,
+  Vector3,
+} from 'three';
+
+import type { Instance } from './description.ts';
+import { instanceEquals } from './equality.ts';
+import type { HostMaterial } from './materials.ts';
+
+/** The three.js object an `instances` node is hosted as. */
+export type HostInstances = InstancedMesh<BufferGeometry, HostMaterial>;
+
+const minimumCapacity = 16;
+
+/** Slots to allocate for `count` instances: the next power of two, at least 16. */
+export const capacityFor = (count: number): number =>
+  Math.max(minimumCapacity, 2 ** Math.ceil(Math.log2(Math.max(1, count))));
+
+// Scratch values, so writing instances allocates nothing.
+const matrix = new Matrix4();
+const position = new Vector3();
+const euler = new Euler();
+const quaternion = new Quaternion();
+const scale = new Vector3();
+const color = new Color();
+
+const writeSlot = (mesh: HostInstances, slot: number, instance: Instance): void => {
+  position.set(instance.position[0], instance.position[1], instance.position[2]);
+  euler.set(instance.rotation[0], instance.rotation[1], instance.rotation[2]);
+  quaternion.setFromEuler(euler);
+  scale.set(instance.scale[0], instance.scale[1], instance.scale[2]);
+  mesh.setMatrixAt(slot, matrix.compose(position, quaternion, scale));
+  mesh.setColorAt(slot, color.setHex(instance.color));
+};
+
+/** Creates an instanced mesh with room for at least `count` instances. */
+export const createInstances = (
+  geometry: BufferGeometry,
+  material: HostMaterial,
+  count: number,
+): HostInstances => {
+  const mesh: HostInstances = new InstancedMesh(geometry, material, capacityFor(count));
+  mesh.instanceMatrix.setUsage(DynamicDrawUsage);
+  // Allocate per-instance colours up front so the shader never changes as colours come and go.
+  mesh.setColorAt(0, color.setHex(0xffffff));
+  mesh.instanceColor?.setUsage(DynamicDrawUsage);
+  mesh.count = 0;
+  return mesh;
+};
+
+/** Whether `count` instances fit without reallocating. */
+export const fits = (mesh: HostInstances, count: number): boolean =>
+  count <= mesh.instanceMatrix.count;
+
+/**
+ * Writes `next` into `mesh`, skipping slots whose instance is unchanged from `previous`
+ * (pass an empty list to write every slot). `next` must fit. Returns the slots written.
+ */
+export const writeInstances = (
+  mesh: HostInstances,
+  previous: ReadonlyArray<Instance>,
+  next: ReadonlyArray<Instance>,
+): number => {
+  let written = 0;
+  for (let slot = 0; slot < next.length; slot++) {
+    const instance = next[slot];
+    if (instance === undefined) continue;
+    const before = previous[slot];
+    if (before !== undefined && instanceEquals(before, instance)) continue;
+    writeSlot(mesh, slot, instance);
+    written++;
+  }
+  if (written > 0 || mesh.count !== next.length) {
+    mesh.count = next.length;
+    mesh.instanceMatrix.needsUpdate = true;
+    if (mesh.instanceColor !== null) mesh.instanceColor.needsUpdate = true;
+    // Picking and frustum culling recompute these lazily from the new instances.
+    mesh.boundingSphere = null;
+    mesh.boundingBox = null;
+  }
+  return written;
+};

package/src/kernel/labels.ts

@@ -0,0 +1,48 @@
+/**
+ * The kernel's side of labels (distance-field text): an engine-neutral contract. An
+ * engine package (troika, in `@opsydyn/effect-three-troika`) implements `LabelEngine`; the
+ * scene graph hosts what it makes inside each label's wrapper.
+ *
+ * Behavioural reference: Drei's `Text` at `bf6f4ad` (`src/core/Text.tsx`): a troika mesh
+ * per label, its properties set from props, `sync` run after each change and the frame
+ * invalidated when it finishes, and the mesh disposed on unmount.
+ *
+ * @module
+ */
+import type { Material, Object3D } from 'three';
+
+import type { LabelNode } from './description.ts';
+
+/**
+ * A label's laid-out size in its own units (before its scale), each as
+ * `[minX, minY, maxX, maxY]`: `block` the whole text block, line height included, and
+ * `visible` tight round the glyphs (troika's `blockBounds` and `visibleBounds`).
+ */
+export type LabelLayout = {
+  readonly block: readonly [number, number, number, number];
+  readonly visible: readonly [number, number, number, number];
+};
+
+/** One label as an engine draws it. */
+export type HostedLabel = {
+  /** What to show inside the label's wrapper. */
+  readonly object: Object3D;
+  /** Applies new text or type settings; `ready` is called again when they are drawn. */
+  readonly update: (label: LabelNode) => void;
+  /**
+   * Draws the glyphs with a material the scene lends (`label({ material })`), or the
+   * engine's own with `undefined`. The scene owns it: the engine never disposes it.
+   */
+  readonly setMaterial: (material: Material | undefined) => void;
+  /** The text's laid-out size, once it has been laid out. */
+  readonly layout: () => LabelLayout | undefined;
+  readonly dispose: () => void;
+};
+
+/**
+ * Draws labels. `ready` is called whenever a label's glyphs have been built (fonts load
+ * and glyphs build in the background), so the scene can draw again.
+ */
+export type LabelEngine = {
+  readonly create: (label: LabelNode, ready: () => void) => HostedLabel;
+};