@opsydyn/effect-three-foldkit 0.0.0-stage → 0.1.0

package/src/dom/xr.ts

@@ -0,0 +1,211 @@
+/**
+ * Presenting a scene in a WebXR session through three.js's `WebXRManager`.
+ *
+ * Behavioural references: React Three Fiber `core/configuration.ts` at `d74622e` (on
+ * `sessionstart` enable XR and hand frames to `xr.setAnimationLoop`; on `sessionend` take
+ * them back and draw again), and pmndrs/xr at `0e1acd8` (`store.ts` `setupXRManager`:
+ * reference space type and framebuffer scale before `setSession`; `init.ts`
+ * `buildXRSessionInit`: the reference space required, other features optional). The
+ * player's origin is an offset reference space, as three.js's teleport example moves
+ * the viewer. Controller selects become rays, as `@react-three/xr`'s pointers hit-test
+ * along each controller's target ray.
+ *
+ * @module
+ */
+import type { Xr, XrInput } from '@opsydyn/effect-three';
+import { Group, type Object3D } from 'three';
+
+import type { PresentableRenderer } from './renderSettings.ts';
+import { floorFacing, type GlidePose, glideFrame, startGlider } from './xrGlide.ts';
+import { rayOf, trackInputs, type XrInputs } from './xrInputs.ts';
+import { type Follow, type LendGeometry, trackSpaces } from './xrSpaces.ts';
+
+/** Where an immersive session can come from: `navigator.xr`, or an emulator's. */
+export type XrSystem = Pick<XRSystem, 'requestSession' | 'isSessionSupported'>;
+
+/** The immersive session modes. */
+export type XrMode = 'immersive-vr' | 'immersive-ar';
+
+/**
+ * The session request for a scene's settings: its reference space required, other
+ * floors, hand tracking and anchors optional, and plane detection, a DOM overlay (on
+ * `overlay`, the scene's element) and in AR hit testing when the scene asks for them
+ * (pmndrs/xr's `buildXRSessionInit` asks for every feature it may use, optionally, and
+ * roots the overlay on the element it is given). Anchors are asked for whether or not
+ * the scene has any yet: it may place them mid-session.
+ */
+export const sessionInit = (
+  settings: Xr,
+  mode: XrMode = 'immersive-vr',
+  overlay?: Element,
+): XRSessionInit => ({
+  requiredFeatures: [settings.referenceSpace],
+  optionalFeatures: [
+    ...['local-floor', 'bounded-floor', 'hand-tracking', 'anchors'].filter(
+      (feature) => feature !== settings.referenceSpace,
+    ),
+    ...(settings.planes ? ['plane-detection'] : []),
+    ...(settings.meshes ? ['mesh-detection'] : []),
+    ...(settings.domOverlay && overlay !== undefined ? ['dom-overlay'] : []),
+    ...(mode === 'immersive-ar' && settings.hitTest ? ['hit-test'] : []),
+  ],
+  ...(settings.domOverlay && overlay !== undefined ? { domOverlay: { root: overlay } } : {}),
+});
+
+/**
+ * The offset that puts the player at `origin` facing `heading`: a reference space whose
+ * poses are the device's, rotated by the heading and moved to the origin.
+ */
+const originOffset = (settings: GlidePose): XRRigidTransform => {
+  const [x, y, z] = settings.origin;
+  const half = -settings.heading / 2;
+  const cos = Math.cos(-settings.heading);
+  const sin = Math.sin(-settings.heading);
+  // The inverse of "rotate by heading, then move to origin": rotate by −heading the point −origin.
+  return new XRRigidTransform(
+    { x: -x * cos - z * sin, y: -y, z: x * sin - z * cos },
+    { x: 0, y: Math.sin(half), z: 0, w: Math.cos(half) },
+  );
+};
+
+/**
+ * Forwards each source's select as a ray in the presented space (the scene's, since the
+ * reference space is offset to the player's origin); a select ending in AR also reports
+ * the surface its ray met. Returns a function that stops.
+ */
+const listenForSelects = (
+  session: XRSession,
+  space: () => XRReferenceSpace | null,
+  inputs: XrInputs,
+  input: (input: XrInput) => void,
+): (() => void) => {
+  const forward = (tag: 'SelectStart' | 'SelectEnd') => (event: XRInputSourceEvent) => {
+    const reference = space();
+    const pose =
+      reference === null
+        ? undefined
+        : event.frame.getPose(event.inputSource.targetRaySpace, reference);
+    if (pose !== undefined && pose !== null) {
+      input({ _tag: tag, source: inputs.idOf(event.inputSource), ray: rayOf(pose) });
+    }
+    if (tag === 'SelectEnd') inputs.selected(event.inputSource);
+  };
+  const started = forward('SelectStart');
+  const ended = forward('SelectEnd');
+  session.addEventListener('selectstart', started);
+  session.addEventListener('selectend', ended);
+  return () => {
+    session.removeEventListener('selectstart', started);
+    session.removeEventListener('selectend', ended);
+  };
+};
+
+export type Presentation = {
+  /** Applies new settings mid-session: a new origin or heading moves the player. */
+  readonly update: (settings: Xr) => void;
+  readonly session: XRSession;
+};
+
+/** What a session presents: the scene, and how it is drawn, followed and told of input. */
+export type Presented = {
+  readonly scene: Object3D;
+  readonly draw: () => void;
+  /** Places the groups that follow tracked spaces (`group({ follow })`). */
+  readonly follow: Follow;
+  /** Lends detected meshes' geometry to the scene (`xrMesh(id)`). */
+  readonly lend: LendGeometry;
+  readonly input: (input: XrInput) => void;
+};
+
+/**
+ * Presents into `session`: frames come from the session (each read for input and the
+ * spaces groups follow, then drawn) until it ends, when `ended` is called and the page's
+ * own frames take over again. Input sources are drawn into the scene while it presents.
+ */
+export const present = async (
+  renderer: PresentableRenderer,
+  session: XRSession,
+  settings: Xr,
+  presented: Presented,
+  ended: () => void,
+): Promise<Presentation> => {
+  const { scene, draw, input } = presented;
+  const { xr } = renderer;
+  xr.enabled = true;
+  xr.setReferenceSpaceType(settings.referenceSpace);
+  xr.setFramebufferScaleFactor(settings.framebufferScale);
+  let inputs: XrInputs | undefined;
+  const spaces = trackSpaces(session, () => current, presented.follow, input, presented.lend);
+  let current = settings;
+  // Gliding (`xr({ glide })`) moves the player from the description's place; the
+  // description wins again whenever it changes.
+  let glider = startGlider({ origin: settings.origin, heading: settings.heading });
+  let lastTime: number | undefined;
+  let base: XRReferenceSpace | null = null;
+  const place = (pose: GlidePose): void => {
+    if (base !== null) xr.setReferenceSpace(base.getOffsetReferenceSpace(originOffset(pose)));
+  };
+
+  /** One frame of gliding, when the description asks for it. */
+  const glideStep = (time: number, frame: XRFrame, space: XRReferenceSpace): void => {
+    const seconds = Math.min(0.1, Math.max(0, (time - (lastTime ?? time)) / 1000));
+    lastTime = time;
+    if (current.glide === null || inputs === undefined) return;
+    const head = frame.getViewerPose(space);
+    const facing = floorFacing(head?.transform.orientation ?? { x: 0, y: 0, z: 0, w: 1 });
+    const { left, right } = inputs.sticks();
+    const next = glideFrame(glider, current.glide, { move: left, turn: right }, facing, seconds);
+    if (next.glider.pose !== glider.pose) place(next.glider.pose);
+    glider = next.glider;
+    if (next.stopped !== undefined) input({ _tag: 'Moved', ...next.stopped });
+  };
+
+  /** One session frame: its input read, then drawn. Frames outside the session are skipped. */
+  function sessionFrame(time: number, frame?: XRFrame): void {
+    if (!xr.isPresenting) return;
+    const space = xr.getReferenceSpace();
+    if (frame !== undefined && space !== null) {
+      inputs?.frame(frame, space);
+      glideStep(time, frame, space);
+      // After gliding, so the spaces are where the player now stands.
+      spaces.frame(frame, xr.getReferenceSpace() ?? space);
+    }
+    draw();
+  }
+  // Set before the session starts (WebGPU's XR manager takes the loop then).
+  renderer.setXrLoop(sessionFrame);
+  await xr.setSession(session);
+  base = xr.getReferenceSpace();
+  place(glider.pose);
+  const shown = new Group();
+  shown.name = 'xr-inputs';
+  scene.add(shown);
+  const tracked = trackInputs(session, shown, () => current, input);
+  inputs = tracked;
+  const stopSelects = listenForSelects(session, () => xr.getReferenceSpace(), tracked, input);
+  session.addEventListener(
+    'end',
+    () => {
+      stopSelects();
+      tracked.stop();
+      spaces.stop();
+      shown.removeFromParent();
+      renderer.setXrLoop(null);
+      xr.enabled = false;
+      ended();
+    },
+    { once: true },
+  );
+  return {
+    session,
+    update: (next) => {
+      const moved =
+        next.origin.some((value, i) => value !== current.origin[i]) ||
+        next.heading !== current.heading;
+      current = next;
+      if (!moved) return;
+      glider = startGlider({ origin: next.origin, heading: next.heading });
+      place(glider.pose);
+    },
+  };
+};

package/src/dom/xrGlide.ts

@@ -0,0 +1,114 @@
+/**
+ * Gliding with the thumbsticks while presenting (`xr({ glide })`), one frame at a time.
+ *
+ * Behavioural reference: pmndrs/xr at `0e1acd8`, `packages/xr/src/controller-locomotion.ts`:
+ * the left stick moves the player along the head's facing, flattened onto the floor, at
+ * `speed` metres per second at full stick (forward is the stick pushed away, negative y);
+ * the right stick turns, smoothly at `turnSpeed`, or by `snapDegrees` once per push past
+ * halfway, ready again once back under it. Unlike there, a still stick is a still player
+ * (a small dead zone keeps resting thumbsticks from drifting), and the frame that stops
+ * says where the player ended, for the Model.
+ *
+ * @module
+ */
+import type { Vec3, XrGlide } from '@opsydyn/effect-three';
+
+/** Where the player stands: the reference space's origin in the scene, and its heading. */
+export type GlidePose = { readonly origin: Vec3; readonly heading: number };
+
+/** A thumbstick, `[x, y]`, each −1 to 1 (`y` negative pushed away). */
+export type Stick = readonly [x: number, y: number];
+
+/** Gliding's state between frames. */
+export type Glider = {
+  readonly pose: GlidePose;
+  /** Whether a snap turn is ready (the turning stick has been back under halfway). */
+  readonly snapReady: boolean;
+  /** Whether the pose moved since the last report. */
+  readonly moved: boolean;
+};
+
+/** Thumbsticks rest a little off centre; under this they are still. */
+const deadZone = 0.15;
+/** Past this the turning stick turns (pmndrs/xr's default dead zone, 0.5). */
+const turnZone = 0.5;
+
+export const startGlider = (pose: GlidePose): Glider => ({ pose, snapReady: true, moved: false });
+
+/** The head's facing on the floor, from its orientation quaternion: −z turned, flattened. */
+export const floorFacing = (q: {
+  readonly x: number;
+  readonly y: number;
+  readonly z: number;
+  readonly w: number;
+}): readonly [x: number, z: number] => {
+  const x = -2 * (q.x * q.z + q.w * q.y);
+  const z = -(1 - 2 * (q.x * q.x + q.y * q.y));
+  const length = Math.hypot(x, z);
+  return length < 1e-6 ? [0, -1] : [x / length, z / length];
+};
+
+const still = (stick: Stick, zone: number): boolean =>
+  Math.abs(stick[0]) < zone && Math.abs(stick[1]) < zone;
+
+/** One step of moving: along the head's facing and its right, by the stick. */
+const moveBy = (
+  origin: Vec3,
+  stick: Stick,
+  facing: readonly [number, number],
+  distance: number,
+): Vec3 => {
+  const [fx, fz] = facing;
+  // The right of the facing (fx, fz) on the floor, y up: (−fz, fx).
+  const forward = -stick[1] * distance;
+  const right = stick[0] * distance;
+  return [origin[0] + fx * forward - fz * right, origin[1], origin[2] + fz * forward + fx * right];
+};
+
+/** The heading after the turning stick, and whether a snap is ready next frame. */
+const turnBy = (
+  glider: Glider,
+  glide: XrGlide,
+  stick: Stick,
+  seconds: number,
+): { readonly heading: number; readonly snapReady: boolean } => {
+  const { heading } = glider.pose;
+  const pushed = Math.abs(stick[0]) >= turnZone;
+  if (glide.turn === 'smooth') {
+    return {
+      heading: pushed ? heading - stick[0] * glide.turnSpeed * seconds : heading,
+      snapReady: true,
+    };
+  }
+  if (!pushed) return { heading, snapReady: true };
+  if (!glider.snapReady) return { heading, snapReady: false };
+  // Pushed right turns right: the heading (about +y) goes down.
+  return {
+    heading: heading - (Math.sign(stick[0]) * (glide.snapDegrees * Math.PI)) / 180,
+    snapReady: false,
+  };
+};
+
+/**
+ * One frame of gliding. Returns the next state, and the pose to report when the sticks
+ * have just come to rest after moving it.
+ */
+export const glideFrame = (
+  glider: Glider,
+  glide: XrGlide,
+  sticks: { readonly move: Stick; readonly turn: Stick },
+  facing: readonly [number, number],
+  seconds: number,
+): { readonly glider: Glider; readonly stopped: GlidePose | undefined } => {
+  const moving = !still(sticks.move, deadZone);
+  const origin = moving
+    ? moveBy(glider.pose.origin, sticks.move, facing, glide.speed * seconds)
+    : glider.pose.origin;
+  const { heading, snapReady } = turnBy(glider, glide, sticks.turn, seconds);
+  const changed = moving || heading !== glider.pose.heading;
+  const resting = !moving && still(sticks.turn, turnZone);
+  const moved = glider.moved || changed;
+  const pose = { origin, heading };
+  if (resting && moved) return { glider: { pose, snapReady, moved: false }, stopped: pose };
+  return { glider: { pose, snapReady, moved }, stopped: undefined };
+};

package/src/dom/xrHub.ts

@@ -0,0 +1,118 @@
+/**
+ * The page's immersive sessions: which mounted scenes can be presented, and the one
+ * session (WebXR allows one at a time) presenting a scene.
+ *
+ * @module
+ */
+import type { Xr, XrInput } from '@opsydyn/effect-three';
+import type { Object3D } from 'three';
+
+import { presentableRendererOf } from './renderSettings.ts';
+import { type Presentation, present, sessionInit, type XrMode, type XrSystem } from './xr.ts';
+import type { Follow, LendGeometry } from './xrSpaces.ts';
+
+export type { XrMode } from './xr.ts';
+
+/** A mounted scene that can be presented. */
+export type XrTarget = {
+  readonly canvas: HTMLCanvasElement;
+  /** The scene's current `xr` description; `null` while it does not ask to be presented. */
+  readonly settings: () => Xr | null;
+  /** Draws one frame now (the session calls it for each of its frames). */
+  readonly draw: () => void;
+  /** The scene's three.js root, where input sources are drawn while it presents. */
+  readonly scene: Object3D;
+  /** The scene's element: the DOM overlay's root, when the scene asks for one. */
+  readonly element: Element;
+  /** Places the groups that follow tracked spaces. */
+  readonly follow: Follow;
+  /** Lends a geometry to the scene's store, for detected meshes. */
+  readonly lend: LendGeometry;
+  /** Input from the session: aims, selects, sticks, buttons and surfaces. */
+  readonly input: (input: XrInput) => void;
+  /** The session began presenting this scene in `mode`, or (with `null`) ended. */
+  readonly presenting: (mode: XrMode | null) => void;
+};
+
+export type XrHub = {
+  /** Makes a scene presentable; returns a function that withdraws it (ending its session). */
+  readonly register: (target: XrTarget) => () => void;
+  readonly supported: (mode: XrMode) => Promise<boolean>;
+  /**
+   * Requests a session and presents the first registered scene that describes `xr`.
+   * Call from a user gesture's handling: browsers require one to start a session.
+   */
+  readonly enter: (mode: XrMode) => Promise<void>;
+  readonly exit: () => Promise<void>;
+};
+
+type Current = { readonly target: XrTarget; readonly presentation: Presentation };
+
+/** Creates the hub for a page; `system` is `navigator.xr` when the browser has WebXR. */
+export const createXrHub = (system: () => XrSystem | undefined): XrHub => {
+  const targets = new Set<XrTarget>();
+  let current: Current | undefined;
+
+  const presentable = (): { readonly target: XrTarget; readonly settings: Xr } | undefined => {
+    for (const target of targets) {
+      const settings = target.settings();
+      if (settings !== null) return { target, settings };
+    }
+    return undefined;
+  };
+
+  const enter = async (mode: XrMode): Promise<void> => {
+    if (current !== undefined) return;
+    const xr = system();
+    if (xr === undefined) throw new Error('WebXR is not available in this browser');
+    const chosen = presentable();
+    if (chosen === undefined) throw new Error('no mounted scene describes xr');
+    const renderer = presentableRendererOf(chosen.target.canvas);
+    if (renderer === undefined) throw new Error('the scene is not drawn by a three.js renderer');
+    const session = await xr.requestSession(
+      mode,
+      sessionInit(chosen.settings, mode, chosen.target.element),
+    );
+    const { target } = chosen;
+    // Each frame: follow the description (a new origin moves the player), then draw.
+    const draw = (): void => {
+      const settings = target.settings();
+      if (settings !== null) current?.presentation.update(settings);
+      target.draw();
+    };
+    const ended = (): void => {
+      current = undefined;
+      target.presenting(null);
+    };
+    const presentation = await present(
+      renderer,
+      session,
+      chosen.settings,
+      {
+        scene: target.scene,
+        draw,
+        follow: target.follow,
+        lend: target.lend,
+        input: target.input,
+      },
+      ended,
+    );
+    current = { target, presentation };
+    target.presenting(mode);
+  };
+
+  return {
+    register: (target) => {
+      targets.add(target);
+      return () => {
+        targets.delete(target);
+        if (current?.target === target) void current.presentation.session.end();
+      };
+    },
+    supported: async (mode) => (await system()?.isSessionSupported(mode)) ?? false,
+    enter,
+    exit: async () => {
+      await current?.presentation.session.end();
+    },
+  };
+};