@aura3d/input 1.0.6

package/src/controls/OrbitControls.ts

@@ -0,0 +1,168 @@
+import type { InputSnapshot } from "../InputSnapshot";
+import { clamp, type CameraTransformLike, type Vec3Like } from "./ControlTypes";
+
+export const DEFAULT_ORBIT_MAX_POLAR = Math.PI * 0.37;
+
+export interface OrbitControlsOptions {
+  readonly enabled?: boolean;
+  readonly enablePan?: boolean;
+  readonly enableZoom?: boolean;
+  readonly enableRotate?: boolean;
+  readonly target?: Vec3Like;
+  readonly distance?: number;
+  readonly minDistance?: number;
+  readonly maxDistance?: number;
+  readonly minPolar?: number;
+  readonly maxPolar?: number;
+  readonly rotateSpeed?: number;
+  readonly zoomSpeed?: number;
+  readonly panSpeed?: number;
+}
+
+export class OrbitControls {
+  enabled: boolean;
+  enablePan: boolean;
+  enableZoom: boolean;
+  enableRotate: boolean;
+  readonly target: Vec3Like;
+
+  private azimuth = 0;
+  private polar = Math.PI / 2;
+  private distance: number;
+  private readonly initial: { target: Vec3Like; azimuth: number; polar: number; distance: number };
+  private readonly minDistance: number;
+  private readonly maxDistance: number;
+  private readonly minPolar: number;
+  private readonly maxPolar: number;
+  private readonly rotateSpeed: number;
+  private readonly zoomSpeed: number;
+  private readonly panSpeed: number;
+
+  constructor(
+    private readonly camera: CameraTransformLike,
+    options: OrbitControlsOptions = {}
+  ) {
+    this.enabled = options.enabled ?? true;
+    this.enablePan = options.enablePan ?? true;
+    this.enableZoom = options.enableZoom ?? true;
+    this.enableRotate = options.enableRotate ?? true;
+    this.target = { ...(options.target ?? { x: 0, y: 0, z: 0 }) };
+    this.minDistance = options.minDistance ?? 0.1;
+    this.maxDistance = options.maxDistance ?? 1_000;
+    this.minPolar = options.minPolar ?? 0.001;
+    this.maxPolar = options.maxPolar ?? DEFAULT_ORBIT_MAX_POLAR;
+    this.rotateSpeed = options.rotateSpeed ?? 0.005;
+    this.zoomSpeed = options.zoomSpeed ?? 1;
+    this.panSpeed = options.panSpeed ?? 0.002;
+    const current = orbitStateFromCamera(camera, this.target);
+    this.distance = clamp(options.distance ?? current.distance, this.minDistance, this.maxDistance);
+    this.azimuth = current.azimuth;
+    this.polar = clamp(current.polar, this.minPolar, this.maxPolar);
+    this.initial = {
+      target: { ...this.target },
+      azimuth: this.azimuth,
+      polar: this.polar,
+      distance: this.distance
+    };
+    this.apply();
+  }
+
+  update(snapshot: InputSnapshot): void {
+    if (!this.enabled) {
+      return;
+    }
+
+    const leftButton = snapshot.button(0);
+    const middleButton = snapshot.button(1);
+    const rightButton = snapshot.button(2);
+    const panModifier = snapshot.keys.has("ShiftLeft") || snapshot.keys.has("ShiftRight") || snapshot.keys.has("ControlLeft") || snapshot.keys.has("ControlRight") || snapshot.keys.has("MetaLeft") || snapshot.keys.has("MetaRight");
+
+    if (this.enableRotate && leftButton.down && !panModifier) {
+      this.azimuth -= snapshot.pointer.deltaX * this.rotateSpeed;
+      this.polar = clamp(this.polar - snapshot.pointer.deltaY * this.rotateSpeed, this.minPolar, this.maxPolar);
+    }
+
+    if (this.enablePan && (rightButton.down || middleButton.down || (leftButton.down && panModifier))) {
+      this.pan(snapshot.pointer.deltaX, snapshot.pointer.deltaY);
+    }
+
+    if (this.enableZoom && snapshot.pointer.wheelY !== 0) {
+      this.dollyFromWheel(snapshot.pointer.wheelY);
+    }
+
+    this.apply();
+  }
+
+  getPolarAngle(): number {
+    return this.polar;
+  }
+
+  getAzimuthalAngle(): number {
+    return this.azimuth;
+  }
+
+  getDistance(): number {
+    return this.distance;
+  }
+
+  saveState(): void {
+    this.initial.target.x = this.target.x;
+    this.initial.target.y = this.target.y;
+    this.initial.target.z = this.target.z;
+    this.initial.azimuth = this.azimuth;
+    this.initial.polar = this.polar;
+    this.initial.distance = this.distance;
+  }
+
+  reset(): void {
+    this.target.x = this.initial.target.x;
+    this.target.y = this.initial.target.y;
+    this.target.z = this.initial.target.z;
+    this.azimuth = this.initial.azimuth;
+    this.polar = this.initial.polar;
+    this.distance = this.initial.distance;
+    this.apply();
+  }
+
+  dispose(): void {
+    this.enabled = false;
+  }
+
+  private pan(deltaX: number, deltaY: number): void {
+    const scale = this.distance * this.panSpeed;
+    this.target.x -= deltaX * scale;
+    this.target.y += deltaY * scale;
+  }
+
+  private dollyFromWheel(deltaY: number): void {
+    const normalizedDelta = Math.abs(deltaY * 0.01);
+    const zoomScale = Math.pow(0.95, this.zoomSpeed * normalizedDelta);
+    const nextDistance = deltaY < 0
+      ? this.distance * zoomScale
+      : this.distance / zoomScale;
+    this.distance = clamp(nextDistance, this.minDistance, this.maxDistance);
+  }
+
+  private apply(): void {
+    const sinPolar = Math.sin(this.polar);
+    this.camera.position.x = this.target.x + this.distance * sinPolar * Math.sin(this.azimuth);
+    this.camera.position.y = this.target.y + this.distance * Math.cos(this.polar);
+    this.camera.position.z = this.target.z + this.distance * sinPolar * Math.cos(this.azimuth);
+    this.camera.lookAt?.(this.target);
+  }
+}
+
+function orbitStateFromCamera(camera: CameraTransformLike, target: Vec3Like): { readonly azimuth: number; readonly polar: number; readonly distance: number } {
+  const dx = camera.position.x - target.x;
+  const dy = camera.position.y - target.y;
+  const dz = camera.position.z - target.z;
+  const distance = Math.hypot(dx, dy, dz);
+  if (!Number.isFinite(distance) || distance <= 1e-6) {
+    return { azimuth: 0, polar: Math.PI / 2, distance: 5 };
+  }
+  return {
+    azimuth: Math.atan2(dx, dz),
+    polar: Math.acos(clamp(dy / distance, -1, 1)),
+    distance
+  };
+}

package/src/controls/PointerLockControls.ts

@@ -0,0 +1,24 @@
+import type { InputSnapshot } from "../InputSnapshot";
+import { FirstPersonControls, type FirstPersonControlsOptions } from "./FirstPersonControls";
+import type { CameraTransformLike } from "./ControlTypes";
+
+export class PointerLockControls extends FirstPersonControls {
+  locked = false;
+
+  constructor(camera: CameraTransformLike, options: FirstPersonControlsOptions = {}) {
+    super(camera, options);
+  }
+
+  lock(): void {
+    this.locked = true;
+  }
+
+  unlock(): void {
+    this.locked = false;
+  }
+
+  override update(snapshot: InputSnapshot, deltaSeconds: number): void {
+    if (!this.locked) return;
+    super.update(snapshot, deltaSeconds);
+  }
+}

package/src/controls/SceneCameraAdapter.ts

@@ -0,0 +1,100 @@
+import { Quaternion, Vector3 } from "@aura3d/math";
+import { type Camera } from "@aura3d/scene";
+import { type CameraTransformLike, type EulerLike, type Vec3Like } from "./ControlTypes";
+
+export interface SceneCameraControlAdapter extends CameraTransformLike {
+  readonly camera: Camera;
+  readonly position: Vec3Like;
+  readonly rotation: EulerLike;
+  lookAt(target: Vec3Like): void;
+}
+
+export function createSceneCameraControlAdapter(camera: Camera): SceneCameraControlAdapter {
+  const euler = quaternionToEuler(camera.transform.rotation);
+  const position = {
+    get x(): number {
+      return camera.transform.position[0];
+    },
+    set x(value: number) {
+      camera.transform.setPosition(value, camera.transform.position[1], camera.transform.position[2]);
+      syncCamera(camera);
+    },
+    get y(): number {
+      return camera.transform.position[1];
+    },
+    set y(value: number) {
+      camera.transform.setPosition(camera.transform.position[0], value, camera.transform.position[2]);
+      syncCamera(camera);
+    },
+    get z(): number {
+      return camera.transform.position[2];
+    },
+    set z(value: number) {
+      camera.transform.setPosition(camera.transform.position[0], camera.transform.position[1], value);
+      syncCamera(camera);
+    }
+  };
+  const rotation = {
+    get x(): number {
+      return euler.x;
+    },
+    set x(value: number) {
+      euler.x = value;
+      applyEuler(camera, euler);
+    },
+    get y(): number {
+      return euler.y;
+    },
+    set y(value: number) {
+      euler.y = value;
+      applyEuler(camera, euler);
+    },
+    get z(): number {
+      return euler.z;
+    },
+    set z(value: number) {
+      euler.z = value;
+      applyEuler(camera, euler);
+    }
+  };
+
+  return {
+    camera,
+    position,
+    rotation,
+    lookAt(target: Vec3Like): void {
+      const origin = new Vector3(camera.transform.position[0], camera.transform.position[1], camera.transform.position[2]);
+      const direction = new Vector3(target.x, target.y, target.z).subtract(origin).normalize();
+      if (direction.lengthSquared() === 0) return;
+      const q = Quaternion.fromUnitVectors(Vector3.forward, direction);
+      camera.transform.setRotation(q.x, q.y, q.z, q.w);
+      const nextEuler = quaternionToEuler([q.x, q.y, q.z, q.w]);
+      euler.x = nextEuler.x;
+      euler.y = nextEuler.y;
+      euler.z = nextEuler.z;
+      syncCamera(camera);
+    }
+  };
+}
+
+function applyEuler(camera: Camera, euler: EulerLike): void {
+  const yaw = Quaternion.fromAxisAngle(Vector3.up, euler.y);
+  const pitch = Quaternion.fromAxisAngle(Vector3.right, euler.x);
+  const roll = Quaternion.fromAxisAngle(new Vector3(0, 0, 1), euler.z);
+  const q = yaw.multiply(pitch).multiply(roll).normalize();
+  camera.transform.setRotation(q.x, q.y, q.z, q.w);
+  syncCamera(camera);
+}
+
+function syncCamera(camera: Camera): void {
+  camera.updateCameraMatrices();
+}
+
+function quaternionToEuler(rotation: readonly [number, number, number, number]): EulerLike {
+  const [x, y, z, w] = rotation;
+  const sinPitch = 2 * (w * x - z * y);
+  const pitch = Math.abs(sinPitch) >= 1 ? Math.sign(sinPitch) * Math.PI / 2 : Math.asin(sinPitch);
+  const yaw = Math.atan2(2 * (w * y + x * z), 1 - 2 * (x * x + y * y));
+  const roll = Math.atan2(2 * (w * z + x * y), 1 - 2 * (x * x + z * z));
+  return { x: pitch, y: yaw, z: roll };
+}

package/src/controls/ThirdPersonFollowControls.ts

@@ -0,0 +1,42 @@
+import { type CameraTransformLike, type Vec3Like } from "./ControlTypes";
+
+export interface ThirdPersonFollowControlsOptions {
+  readonly offset?: Vec3Like;
+  readonly damping?: number;
+}
+
+export class ThirdPersonFollowControls {
+  enabled = true;
+  target?: { readonly position: Vec3Like };
+  readonly offset: Vec3Like;
+  damping: number;
+
+  constructor(
+    private readonly camera: CameraTransformLike,
+    target?: { readonly position: Vec3Like },
+    options: ThirdPersonFollowControlsOptions = {}
+  ) {
+    this.target = target;
+    this.offset = { ...(options.offset ?? { x: 0, y: 2, z: 6 }) };
+    this.damping = options.damping ?? 12;
+  }
+
+  update(deltaSeconds: number): void {
+    if (!this.enabled || !this.target) return;
+    const desired = {
+      x: this.target.position.x + this.offset.x,
+      y: this.target.position.y + this.offset.y,
+      z: this.target.position.z + this.offset.z
+    };
+    const alpha = 1 - Math.exp(-this.damping * Math.max(0, deltaSeconds));
+    this.camera.position.x += (desired.x - this.camera.position.x) * alpha;
+    this.camera.position.y += (desired.y - this.camera.position.y) * alpha;
+    this.camera.position.z += (desired.z - this.camera.position.z) * alpha;
+    this.camera.lookAt?.(this.target.position);
+  }
+
+  dispose(): void {
+    this.enabled = false;
+    this.target = undefined;
+  }
+}

package/src/index.ts

@@ -0,0 +1,72 @@
+export { ActionMap } from "./ActionMap";
+export type { ActionBinding, AxisBinding } from "./ActionMap";
+export { GamepadDevice } from "./GamepadDevice";
+export type { GamepadButtonLike, GamepadLike } from "./GamepadDevice";
+export { sampleGestureHapticsFixture } from "./GestureHapticsFixtures";
+export type { GestureHapticsFixture, GestureHapticsFixtureOptions, GestureHapticsGestureType, GestureHapticsPatternName } from "./GestureHapticsFixtures";
+export { GestureRecognizer } from "./GestureRecognizer";
+export type { Gesture } from "./GestureRecognizer";
+export { processInputValue, sampleInputActionBindingFixture } from "./InputActionBindingFixtures";
+export type { InputActionBindingFixture, InputValueProcessor } from "./InputActionBindingFixtures";
+export { InputSnapshot } from "./InputSnapshot";
+export type { ButtonState, GamepadSnapshot, InputSnapshotOptions, PointerSnapshot, PointerTouch } from "./InputSnapshot";
+export { InputPlayback, InputRecorder, parseInputRecording } from "./InputReplay";
+export type { InputPlaybackOptions, InputPlaybackSnapshot, InputRecording, InputRecordingMetadata, InputReplayEvent, InputReplayEventType } from "./InputReplay";
+export { InputSystem } from "./InputSystem";
+export type { InputEventTargetLike } from "./InputSystem";
+export { InteractionSystem } from "./InteractionSystem";
+export type {
+  InteractionBounds,
+  InteractionEvent,
+  InteractionEventType,
+  InteractionHit,
+  InteractionListener,
+  InteractionRayProvider,
+  InteractionTarget,
+  InteractionTargetProvider
+} from "./InteractionSystem";
+export { KeyboardDevice } from "./KeyboardDevice";
+export type { KeyboardEventLike } from "./KeyboardDevice";
+export { pickingRayFromCamera } from "./PickingRay";
+export type { PickingRayViewport } from "./PickingRay";
+export { PointerDevice } from "./PointerDevice";
+export type { PointerEventLike, WheelEventLike } from "./PointerDevice";
+export { VirtualTouchJoystick, sampleVirtualTouchJoystickFixture } from "./VirtualTouchControls";
+export type { VirtualJoystickConfig, VirtualTouchJoystickSnapshot, VirtualTouchPoint } from "./VirtualTouchControls";
+export { sampleXRRuntimeFixture } from "./XRFixtures";
+export type { XRFixtureLodLevel, XRFixtureOptions, XRFixtureSessionMode, XRRuntimeFixture } from "./XRFixtures";
+export { WebXRSessionController } from "./WebXRSessionController";
+export type {
+  A3DXRFrameLike,
+  A3DXRHandedness,
+  A3DXRHitTestResultLike,
+  A3DXRInputSourceLike,
+  A3DXRPoseLike,
+  A3DXRReferenceSpaceLike,
+  A3DXRReferenceSpaceType,
+  A3DXRSessionInit,
+  A3DXRSessionLike,
+  A3DXRSessionMode,
+  A3DXRSystemLike,
+  WebXRControllerSample,
+  WebXRFrameSample,
+  WebXRHitTestSample,
+  WebXRSessionControllerOptions,
+  WebXRSessionStartResult
+} from "./WebXRSessionController";
+export * from "./GamepadInput.js";
+export * from "./GestureControls.js";
+export * from "./controls/PointerLockControls.js";
+export { CameraRig } from "./controls/CameraRig";
+export type { CameraRigState } from "./controls/CameraRig";
+export type { CameraTransformLike, EulerLike, Vec3Like } from "./controls/ControlTypes";
+export { createSceneCameraControlAdapter } from "./controls/SceneCameraAdapter";
+export type { SceneCameraControlAdapter } from "./controls/SceneCameraAdapter";
+export { EditorFlyControls } from "./controls/EditorFlyControls";
+export type { EditorFlyControlsOptions } from "./controls/EditorFlyControls";
+export { FirstPersonControls } from "./controls/FirstPersonControls";
+export type { FirstPersonControlsOptions } from "./controls/FirstPersonControls";
+export { DEFAULT_ORBIT_MAX_POLAR, OrbitControls } from "./controls/OrbitControls";
+export type { OrbitControlsOptions } from "./controls/OrbitControls";
+export { ThirdPersonFollowControls } from "./controls/ThirdPersonFollowControls";
+export type { ThirdPersonFollowControlsOptions } from "./controls/ThirdPersonFollowControls";

package/tests/input.test.ts

@@ -0,0 +1,69 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import { Ray, Vector3 } from "@aura3d/math";
+import { Scene } from "@aura3d/scene";
+import { ActionMap, InputSnapshot, InputSystem, InteractionSystem, pickingRayFromCamera } from "../src/index";
+
+test("InputSystem produces stable key transitions across frames", () => {
+  const input = new InputSystem();
+  input.keyboard.keyDown({ code: "Space" });
+  let snapshot = input.update();
+  assert.equal(snapshot.key("Space").pressed, true);
+  assert.equal(snapshot.key("Space").down, true);
+
+  input.endFrame();
+  snapshot = input.update();
+  assert.equal(snapshot.key("Space").pressed, false);
+  assert.equal(snapshot.key("Space").down, true);
+
+  input.keyboard.keyUp({ code: "Space" });
+  snapshot = input.update();
+  assert.equal(snapshot.key("Space").released, true);
+});
+
+test("ActionMap supports alternatives and axes", () => {
+  const input = new InputSystem();
+  const actions = new ActionMap();
+  actions.bind("jump", [
+    { type: "keyboard", code: "Space" },
+    { type: "pointer", button: 0 }
+  ]);
+  actions.bindAxis("moveX", [{ type: "keyboard-axis", negative: "KeyA", positive: "KeyD", scale: 2 }]);
+
+  input.keyboard.keyDown({ code: "KeyD" });
+  input.pointer.down({ clientX: 5, clientY: 7, button: 0 });
+  const snapshot = input.update();
+
+  assert.equal(actions.pressed("jump", snapshot), true);
+  assert.equal(actions.axis("moveX", snapshot), 2);
+});
+
+test("pickingRayFromCamera creates a center ray through the camera forward axis", () => {
+  const scene = new Scene();
+  const camera = scene.createPerspectiveCamera({ aspect: 1 });
+  scene.root.addChild(camera);
+  camera.setViewport({ x: 0, y: 0, width: 100, height: 100 });
+
+  const ray = pickingRayFromCamera(camera, 50, 50);
+  assert.ok(ray.direction.equals(new Vector3(0, 0, -1), 1e-6));
+});
+
+test("InteractionSystem picks nearest target and emits click lifecycle", () => {
+  const events: string[] = [];
+  const interaction = new InteractionSystem(
+    () => new Ray(new Vector3(0, 0, 5), new Vector3(0, 0, -1)),
+    () => [
+      { id: "far", bounds: { min: [-1, -1, -5], max: [1, 1, -4] } },
+      { id: "near", bounds: { min: [-1, -1, 0], max: [1, 1, 1] } }
+    ]
+  );
+  interaction.subscribe((event) => events.push(event.type));
+
+  const down = new InputSnapshot({ pointer: { buttons: new Map([[0, { down: true, pressed: false, released: false }]]) } });
+  const hit = interaction.update(down);
+  const up = new InputSnapshot({ pointer: { buttons: new Map() }, previousPointerButtons: new Set([0]) });
+  interaction.update(up);
+
+  assert.equal(hit?.target.id, "near");
+  assert.deepEqual(events, ["hover-enter", "pointer-down", "click"]);
+});

package/tsconfig.json

@@ -0,0 +1,7 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "noEmit": true
+  },
+  "include": ["src/**/*.ts"]
+}