@thunderclap-engine/engine 0.0.0-stage → 1.1.0

package/dist/input/pointer-sources.js

@@ -0,0 +1,306 @@
+import { createPointerDispatcher, POINTER_PRIORITY, } from './pointer-dispatch.js';
+import { createRay, screenRay } from './rays.js';
+export function createSample(key, device) {
+    return {
+        key,
+        device,
+        hand: null,
+        ray: createRay(),
+        x: Number.NaN,
+        y: Number.NaN,
+        select: false,
+        secondary: false,
+        xr: null,
+        synthetic: false,
+    };
+}
+/**
+ * Mouse, pen and touch as router pointers. Mouse and pen hover (a pointer while over the
+ * target); touch is a pointer only while the finger is down, plus one more tick after it lifts so
+ * a tap's tick still sees what it was on. Positions go through the pointer transform into the
+ * camera's screen units. With linked `Gestures` that have `magnify`, a single touch points at the
+ * gesture's aim (the snapped target's centre, else the lifted aim point) instead of the finger.
+ *
+ * Feed methods (`pointerDown`, `pointerMove`, `pointerUp`, `pointerLeave`, `pointerCancel`,
+ * `cancelAll`) take client coordinates and are public for tests and replays. `synthetic` on
+ * `pointerDown`/`pointerMove` marks a replayed pointer (see `PointerSample.synthetic`).
+ */
+export class ScreenPointers {
+    transform = null;
+    gestures = null;
+    contacts = [];
+    out = [];
+    detachFn = null;
+    /**
+     * Hides a pointer from `poll` while it reads true: installed by `attach` with a dispatcher as
+     * "claimed and not `hoverWhileClaimed`", so an orbit drag or a touch-zone thumb produces no
+     * hits until it is released. Public so tests can stand one in.
+     */
+    claim = null;
+    setPointerTransform(fn) {
+        this.transform = fn;
+        this.ownDispatcher?.setTransform(fn);
+    }
+    setGestures(g) {
+        this.gestures = g;
+    }
+    // ---------------------------------------------------------------- feed
+    pointerDown(id, x, y, device = 'mouse', button = 0, synthetic = false) {
+        const c = this.contact(id, device, true, synthetic);
+        if (!c)
+            return;
+        c.cx = x;
+        c.cy = y;
+        if (button === 2)
+            c.secondary = true;
+        else if (button === 0) {
+            c.select = true;
+            c.tapped = true;
+        }
+    }
+    pointerMove(id, x, y, device = 'mouse', synthetic = false) {
+        // Touch is a pointer only while down; mouse and pen hover.
+        const c = this.contact(id, device, device !== 'touch', synthetic);
+        if (!c)
+            return;
+        c.cx = x;
+        c.cy = y;
+    }
+    pointerUp(id, x, y, button = 0) {
+        const c = this.find(id);
+        if (!c)
+            return;
+        c.cx = x;
+        c.cy = y;
+        if (button === 2)
+            c.secondary = false;
+        else if (button === 0)
+            c.select = false;
+        if (c.device === 'touch')
+            c.gone = true;
+    }
+    /** A hovering mouse or pen left the target. */
+    pointerLeave(id) {
+        const c = this.find(id);
+        if (c && c.device !== 'touch' && !c.select && !c.secondary)
+            c.cancelled = true;
+    }
+    pointerCancel(id) {
+        const c = this.find(id);
+        if (c)
+            c.cancelled = true;
+    }
+    cancelAll() {
+        for (const c of this.contacts)
+            c.cancelled = true;
+    }
+    // ---------------------------------------------------------------- poll
+    poll(camera) {
+        const out = this.out;
+        out.length = 0;
+        const aim = this.gestures?.aim ?? null;
+        let touches = 0;
+        for (const c of this.contacts)
+            if (c.device === 'touch' && !c.cancelled)
+                touches++;
+        for (let i = 0; i < this.contacts.length; i++) {
+            const c = this.contacts[i];
+            if (c.cancelled) {
+                this.contacts.splice(i--, 1);
+                continue;
+            }
+            const s = c.sample;
+            let sx;
+            let sy;
+            if (aim && c.device === 'touch' && touches === 1) {
+                // The magnify aim: where the finger is pointing, not where it covers.
+                sx = aim.target ? aim.target.x : aim.x;
+                sy = aim.target ? aim.target.y : aim.y;
+                if (!aim.inside && !aim.target)
+                    sx = Number.NaN;
+            }
+            else if (this.transform) {
+                const p = this.transform(c.cx, c.cy);
+                sx = p ? p.x : Number.NaN;
+                sy = p ? p.y : Number.NaN;
+            }
+            else {
+                sx = c.cx;
+                sy = c.cy;
+            }
+            s.select = c.select || c.tapped;
+            s.secondary = c.secondary;
+            s.synthetic = c.synthetic;
+            c.tapped = false;
+            if (c.gone)
+                this.contacts.splice(i--, 1);
+            if (this.claim?.(c.id))
+                continue;
+            if (!camera || Number.isNaN(sx) || !screenRay(camera, sx, sy, s.ray))
+                continue;
+            s.x = sx;
+            s.y = sy;
+            out.push(s);
+        }
+        return out;
+    }
+    // ---------------------------------------------------------------- DOM
+    /**
+     * Listen to pointer events on `target` (the router calls this from its `attach`). Positions are
+     * client px with a transform, target-relative px without one.
+     */
+    attach(target, dispatcher) {
+        this.detach();
+        const shared = dispatcher ?? null;
+        const d = shared ?? createPointerDispatcher(target, { transform: this.transform });
+        if (!shared)
+            this.ownDispatcher = d;
+        // Sees claimed pointers too (their contacts must end cleanly); `poll` hides them.
+        const remove = d.add(this.consumer, POINTER_PRIORITY.screen, true);
+        this.claim = (id) => !d.hoverWhileClaimed && d.claimed(id);
+        this.detachFn = () => {
+            remove();
+            if (!shared)
+                d.destroy();
+            this.ownDispatcher = null;
+            this.claim = null;
+        };
+    }
+    ownDispatcher = null;
+    consumer = {
+        pointerDown: (p) => this.pointerDown(p.id, p.x, p.y, p.device, p.button, p.synthetic),
+        pointerMove: (p) => this.pointerMove(p.id, p.x, p.y, p.device, p.synthetic),
+        pointerUp: (p) => this.pointerUp(p.id, p.x, p.y, p.button),
+        pointerLeave: (p) => this.pointerLeave(p.id),
+        pointerCancel: (p) => this.pointerCancel(p.id),
+        cancelAll: () => this.cancelAll(),
+    };
+    detach() {
+        this.detachFn?.();
+        this.detachFn = null;
+        this.cancelAll();
+    }
+    find(id) {
+        for (const c of this.contacts)
+            if (c.id === id && !c.cancelled && !c.gone)
+                return c;
+        return null;
+    }
+    contact(id, device, create, synthetic) {
+        const found = this.find(id);
+        if (found)
+            found.synthetic = synthetic;
+        if (found || !create)
+            return found;
+        const c = {
+            id,
+            device,
+            cx: 0,
+            cy: 0,
+            select: false,
+            secondary: false,
+            tapped: false,
+            gone: false,
+            cancelled: false,
+            synthetic,
+            sample: createSample(id, device),
+        };
+        this.contacts.push(c);
+        return c;
+    }
+}
+function defaultGamepads() {
+    try {
+        return typeof navigator !== 'undefined' && navigator.getGamepads ? navigator.getGamepads() : [];
+    }
+    catch {
+        return [];
+    }
+}
+/**
+ * A virtual pointer a gamepad stick moves over the camera's screen, so a pad aims like a mouse.
+ * It appears (at the screen centre) the first time its stick passes the deadzone or its select
+ * button is pressed, then stays until `hide()`. `x`, `y` are camera screen units.
+ */
+export class PadCursor {
+    x = Number.NaN;
+    y = Number.NaN;
+    /** True while the cursor is shown (it reports a pointer). */
+    active = false;
+    getGamepads;
+    opts;
+    sample = createSample(0, 'gamepad');
+    out = [];
+    constructor(opts = {}) {
+        this.getGamepads = opts.getGamepads ?? defaultGamepads;
+        this.opts = {
+            pad: opts.pad,
+            axes: opts.axes ?? [0, 1],
+            deadzone: opts.deadzone ?? 0.2,
+            speed: opts.speed ?? 0.012,
+            selectButton: opts.selectButton ?? 0,
+            secondaryButton: opts.secondaryButton ?? 2,
+        };
+    }
+    /** Put the cursor at a screen point and show it. */
+    moveTo(x, y) {
+        this.x = x;
+        this.y = y;
+        this.active = true;
+    }
+    /** Hide the cursor (for example when the mouse moves); the stick shows it again. */
+    hide() {
+        this.active = false;
+    }
+    poll(camera) {
+        const out = this.out;
+        out.length = 0;
+        const o = this.opts;
+        let ax = 0;
+        let ay = 0;
+        let sel = false;
+        let sec = false;
+        const pads = this.getGamepads();
+        for (let i = 0; i < pads.length; i++) {
+            if (o.pad !== undefined && i !== o.pad)
+                continue;
+            const p = pads[i];
+            if (!p || p.connected === false)
+                continue;
+            const x = p.axes[o.axes[0]] ?? 0;
+            const y = p.axes[o.axes[1]] ?? 0;
+            if (ax === 0 && ay === 0 && Math.hypot(x, y) > o.deadzone) {
+                ax = x;
+                ay = y;
+            }
+            if (p.buttons[o.selectButton]?.pressed)
+                sel = true;
+            if (p.buttons[o.secondaryButton]?.pressed)
+                sec = true;
+        }
+        if (!camera)
+            return out;
+        const sc = camera.screen;
+        if ((ax !== 0 || ay !== 0 || sel) && !this.active) {
+            this.active = true;
+            if (Number.isNaN(this.x)) {
+                this.x = sc.x + sc.width / 2;
+                this.y = sc.y + sc.height / 2;
+            }
+        }
+        if (!this.active)
+            return out;
+        const step = o.speed * Math.min(sc.width, sc.height);
+        this.x = Math.min(sc.x + sc.width, Math.max(sc.x, this.x + ax * step));
+        this.y = Math.min(sc.y + sc.height, Math.max(sc.y, this.y + ay * step));
+        const s = this.sample;
+        s.select = sel;
+        s.secondary = sec;
+        if (!screenRay(camera, this.x, this.y, s.ray))
+            return out;
+        s.x = this.x;
+        s.y = this.y;
+        out.push(s);
+        return out;
+    }
+}

package/dist/input/rays.d.ts

@@ -0,0 +1,138 @@
+/**
+ * Rays and hit testing for the pointer router (`pointer-router.ts`). Plain math, no DOM, no
+ * game nouns: a `HitTester` turns a world-space `Ray` into the nearest `PickHit` it knows, and the
+ * game decides what `target` means.
+ */
+import type { Camera } from '../render/camera.js';
+import type { MeshBounds } from '../render/mesh.js';
+import type { Transform } from '../render/transform.js';
+/** A 3-vector, mutable and reused (`[x, y, z]`). */
+export type Vec3 = [number, number, number];
+/** A world-space ray. `dir` is unit length. Reuse one per pointer; nothing here allocates. */
+export interface Ray {
+    readonly origin: Vec3;
+    readonly dir: Vec3;
+}
+/**
+ * The nearest thing a ray met. `distance` is along `ray.dir` from `ray.origin` (world units).
+ * `normal` faces the ray (unit), or `null` when the tester has none (the ray started inside).
+ * Hits the router hands out are reused: read them in the listener or copy them.
+ */
+export interface PickHit<T = unknown> {
+    readonly point: Vec3;
+    normal: Vec3 | null;
+    distance: number;
+    /** What was hit, as the game named it (a box's `target`, a plane's `target`). */
+    target: T;
+}
+/**
+ * Returns the nearest hit of `ray` against what this tester knows, or `null`. It may return the
+ * same object on every call (the router copies it before calling again).
+ */
+export type HitTester<T = unknown> = (ray: Ray) => PickHit<T> | null;
+/** The camera slice the router needs: `screen` and the inverse projection (`render`'s `Camera`). */
+export type RayCamera = Pick<Camera, 'screen' | 'screenToWorld'>;
+export declare function createRay(): Ray;
+export declare function createHit<T = unknown>(target: T): PickHit<T>;
+/** `out = ray.origin + t * ray.dir`. */
+export declare function rayAt(ray: Ray, t: number, out: Vec3): Vec3;
+/**
+ * The ray through screen point (`sx`, `sy`) (the camera's screen units): from the near plane
+ * (`screenToWorld(…, 0)`) towards the far one (`…, 1`; depth 0.5 when the far plane is at
+ * infinity). For `Camera.ortho2d` the origin is the world point on the near plane
+ * (z = -ORTHO2D_HALF_DEPTH) and `dir` is +z, into the screen.
+ * Returns false (and leaves `out` alone) when the camera gives no usable ray.
+ */
+export declare function screenRay(camera: RayCamera, sx: number, sy: number, out: Ray): boolean;
+/**
+ * Any plane for `planeTester` (ws/api-core): the points `p` with `dot(normal, p) = offset`.
+ * `normal` need not be unit length; it must not be zero. Read on every call, so the game may
+ * move the plane in place. `{ normal: [0, 0, 1], offset: z }` is the plane z = `z`.
+ */
+export interface RayPlane {
+    normal: readonly [number, number, number];
+    /** Default 0 (the plane through the origin). */
+    offset?: number;
+}
+/**
+ * Hits a plane: the plane z = `plane` when it is a number (a 2D game's world, default 0), or
+ * any `RayPlane` (a floor at y = 0 is `{ normal: [0, 1, 0] }`). The hit point is where the ray
+ * crosses it, so through `Camera.ortho2d` the z-plane hit is the world point under the pointer.
+ * Rays parallel to the plane or pointing away from it miss. The hit's normal is the plane's,
+ * unit length, turned to face the ray. `target` is what every hit carries (default `null`).
+ */
+export declare function planeTester<T = null>(plane?: number | RayPlane, target?: T): HitTester<T>;
+/** An axis-aligned box for `aabbTester`. `min` ≤ `max` per axis; a flat box (2D quad) is fine. */
+export interface RayBox<T = unknown> {
+    min: readonly [number, number, number];
+    max: readonly [number, number, number];
+    target: T;
+}
+/**
+ * Hits the nearest of `boxes` (read on every call, so the game may edit the array and its
+ * boxes). A ray that starts inside a box hits it at distance 0 with no normal. Equal distances
+ * go to the earlier box. Flat boxes (`min[i] === max[i]`) work, so 2D quads at z = 0 can be
+ * picked through `Camera.ortho2d`.
+ */
+export declare function aabbTester<T = unknown>(boxes: readonly RayBox<T>[]): HitTester<T>;
+/**
+ * The slice of `render`'s `Transform` a transformed tester reads: the 3×4 row-major world
+ * matrix (12 floats, `[r0 | tx, r1 | ty, r2 | tz]`). Read on every call, so a moving object
+ * picks correctly without re-registering its tester.
+ */
+export type RayTransform = Pick<Transform, 'world'>;
+/** A bounding sphere in object space (`render`'s `MeshBounds`): `center` and `radius`. */
+export type RayBounds = MeshBounds;
+/**
+ * `outRay` = `ray` in the object space of `worldMatrix3x4` (12 floats, row-major, as
+ * `Transform.world`): the 3×3 is inverted (non-uniform scale is fine), the translation
+ * removed, and `outRay.dir` normalised. Returns the world units per object-space unit along
+ * the ray, so a distance found in object space times the result is the world distance. Returns
+ * 0 (and leaves `outRay` alone) when the matrix is singular. No allocation.
+ */
+export declare function transformRayInto(ray: Ray, worldMatrix3x4: ArrayLike<number>, outRay: Ray): number;
+/**
+ * Möller–Trumbore: the distance along `ray` to triangle `a, b, c` (counter-clockwise seen from
+ * the front), or -1 for a miss. With `cullBack` a triangle whose back faces the ray misses.
+ * `out`, when given, receives the unit triangle normal turned to face the ray. No allocation.
+ */
+export declare function rayTriangle(ray: Ray, a: ArrayLike<number>, b: ArrayLike<number>, c: ArrayLike<number>, cullBack: boolean, out: Vec3 | null): number;
+/**
+ * Hits `bounds` (an object-space sphere, read each call) placed by `transform` (read each call).
+ * The hit carries `point` and `normal` in world space and `distance` in world units, under any
+ * rotation and non-uniform scale (an ellipsoid). A ray that starts inside hits at distance 0
+ * with `normal: null`. Zero allocations per call.
+ */
+export declare function sphereTester<T = null>(transform: RayTransform, bounds: RayBounds, target?: T): HitTester<T>;
+/**
+ * Hits an oriented box: the object-space box `[-halfExtents, +halfExtents]` placed by
+ * `transform` (both read each call). The hit's `normal` is the entering face's, in world space;
+ * `distance` is in world units. A ray that starts inside hits at distance 0 with `normal: null`.
+ * Zero allocations per call.
+ */
+export declare function obbTester<T = null>(transform: RayTransform, halfExtents: readonly [number, number, number], target?: T): HitTester<T>;
+export interface MeshTesterOptions {
+    /**
+     * Object-space bounding sphere the ray must enter before any triangle is tested (read each
+     * call, so a mesh rebuilt in place can update it). Default: computed once from `positions`.
+     * `radius` Infinity skips the test.
+     */
+    bounds?: RayBounds;
+    /** Skip triangles whose back faces the ray (counter-clockwise front). Default false. */
+    cullBack?: boolean;
+    /** Floats per vertex in `positions` (`VertexLayout.floats`). Default 12 (`VERTEX_LAYOUT_3D`). */
+    stride?: number;
+    /** Float offset of x, y, z within a vertex. Default 0 (every shipped layout). */
+    offset?: number;
+}
+/**
+ * Hits the triangles of a mesh whose positions the game keeps on the CPU: `positions` is the
+ * interleaved vertex buffer it uploaded (`MeshDesc.vertices`; `stride`/`offset` in floats say
+ * where x, y, z sit, default `VERTEX_LAYOUT_3D`), `indices` its index buffer or `null` for a
+ * plain triangle list. Both are read each call, so a mesh rebuilt in place is picked as drawn,
+ * and `transform` is read each call too. The ray is moved into object space, rejected on the
+ * bounds sphere first, then tested against every triangle (Möller–Trumbore); the nearest wins.
+ * The hit carries the world-space `point`, the triangle's unit `normal` facing the ray and
+ * `distance` in world units. Zero allocations per call; O(triangles) after the sphere.
+ */
+export declare function meshTester<T = null>(transform: RayTransform, positions: Float32Array, indices: Uint16Array | Uint32Array | null, target?: T, opts?: MeshTesterOptions): HitTester<T>;