Input

@urth/metatell-sdk/input exposes pointer, hover, and gaze events, plus a request/response raycast into the scene.

Pointer and hover events

Each subscription returns an Unsubscribe function; call it on teardown.

import {
  onPointerDown,
  onPointerUp,
  onPointerMove,
  onHover,
} from "@urth/metatell-sdk/input";

const off = onPointerDown((e) => {
  console.log(e.kind, e.objectId, e.point);
});
Copy

A PointerEvent has the following shape:

interface PointerEvent {
  kind: "pointerdown" | "pointerup" | "pointermove" | "hover";
  objectId?: string;  // the object under the pointer, if any
  point?: Vec3;       // world-space hit point
  normal?: Vec3;      // surface normal at the hit point
  button?: number;
}
Copy

onPointerMove and onHover can fire frequently; keep the handlers cheap.

Gaze

import { onGaze } from "@urth/metatell-sdk/input";

const off = onGaze((info) => {
  console.log(info.objectId, info.point);
});
Copy

interface GazeInfo {
  objectId?: string;
  point?: Vec3;
}
Copy

Raycast

raycast() casts a ray into the scene and resolves with the first hit (or null when nothing is hit).

import { raycast } from "@urth/metatell-sdk/input";

const hit = await raycast(
  { x: 0, y: 1.6, z: 0 }, // origin
  { x: 0, y: 0, z: -1 },  // direction
  { maxDistance: 10 },
);

if (hit) {
  console.log(hit.objectId, hit.distance, hit.point);
}
Copy

Options:

interface RaycastOptions {
  maxDistance?: number;
  layerMask?: number;
  timeoutMs?: number; // default 5000
}
Copy

raycast() rejects if no host handler is wired, if the host returns an error, or if it times out. A RaycastHit is:

interface RaycastHit {
  objectId: string;
  distance: number;
  point: Vec3;
  normal?: Vec3;
}
Copy

Vec3 is { x: number; y: number; z: number }.