@vibedgames/gamepad 0.1.0

package/dist/dom.d.ts

@@ -0,0 +1,77 @@
+import { VirtualGamepad } from "./core";
+import type { StickState, VirtualGamepadOptions, VisibilityPolicy } from "./types";
+export type DomGamepadRenderOptions = {
+    /** z-index of the overlay container (default 40 — above the canvas, below
+     *  modal HUD). */
+    zIndex?: number;
+    /** Knob + button accent as a CSS color (default "#fff"). Change at runtime
+     *  with `setTint`. */
+    tint?: string;
+};
+export type DomGamepadOptions = VirtualGamepadOptions & {
+    /** Element the overlay is appended to (default `document.body`). */
+    root?: HTMLElement;
+    /** When the overlay renders: "touch" after the first touch (default),
+     *  "coarse" pre-shown on touch-capable devices so fixed buttons are
+     *  discoverable, or "always". */
+    visible?: VisibilityPolicy;
+    /** Built-in DOM renderer config, or `false` to render it yourself from the
+     *  exposed `pad`. */
+    render?: false | DomGamepadRenderOptions;
+    /** Fired the first time a touch is seen — e.g. swap a control hint. */
+    onFirstTouch?: () => void;
+    /**
+     * Touches whose event target matches are left to the page (they never reach
+     * the pad). Defaults to interactive elements — `button`, `a`, `input`,
+     * `select`, `textarea`, `[data-gamepad-ignore]` — so a rest button doesn't
+     * swallow taps on HUD controls.
+     */
+    ignore?: (target: EventTarget | null) => boolean;
+};
+export type DomGamepad = {
+    /** The underlying framework-agnostic controller. */
+    readonly pad: VirtualGamepad;
+    /** True once any touch has been seen this session (stays true). */
+    readonly isTouch: boolean;
+    getStick(): StickState;
+    isButtonDown(id: string): boolean;
+    /** Edge-triggered press since last `update()` (tap = one action). */
+    justPressed(id: string): boolean;
+    justReleased(id: string): boolean;
+    /** Recolor the knob + buttons (CSS color). */
+    setTint(color: string): void;
+    /** Call once per frame from your game loop: publishes press edges and
+     *  redraws the overlay. */
+    update(): void;
+    destroy(): void;
+};
+/**
+ * Wire a {@link VirtualGamepad} to a plain DOM page — the adapter for
+ * non-Phaser games (Three.js, canvas, anything). Listens for touch pointer
+ * events on `window` (mouse is ignored so desktop keeps its own controls) and
+ * renders the floating stick + fixed buttons as positioned DOM elements in a
+ * `pointer-events:none` overlay, so it never steals taps from the page.
+ *
+ * The page is responsible for `touch-action: none` on its game surface —
+ * without it the browser may scroll/zoom instead of delivering moves.
+ *
+ * ```ts
+ * const gamepad = attachDomGamepad({
+ *   visible: "coarse",
+ *   buttons: [{ id: "jump", label: "JUMP", position: (v) => ({
+ *     x: v.width - 72 - v.inset.right, y: v.height - 72 - v.inset.bottom,
+ *   }) }],
+ * });
+ * // in your game loop:
+ * gamepad.update();
+ * const stick = gamepad.getStick();
+ * if (gamepad.justPressed("jump")) jump();
+ * ```
+ */
+export declare function attachDomGamepad(options?: DomGamepadOptions): DomGamepad;
+export { VirtualGamepad, stickDirection4, stickDirection8 } from "./core";
+export { PhysicalGamepad, isPadConnected } from "./physical";
+export { safeAreaInset } from "./safe-area";
+export type { PadButton, PhysicalGamepadOptions } from "./physical";
+export type { ButtonLayout, ButtonOptions, Dir4, Dir8, Inset, StickGeometry, StickOptions, StickState, Vec2, VirtualGamepadOptions, Viewport, VisibilityPolicy, } from "./types";
+//# sourceMappingURL=dom.d.ts.map

package/dist/dom.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dom.d.ts","sourceRoot":"","sources":["../src/dom.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,MAAM,QAAQ,CAAC;AAExC,OAAO,KAAK,EAAE,UAAU,EAAE,qBAAqB,EAAE,gBAAgB,EAAE,MAAM,SAAS,CAAC;AAEnF,MAAM,MAAM,uBAAuB,GAAG;IACpC;sBACkB;IAClB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;0BACsB;IACtB,IAAI,CAAC,EAAE,MAAM,CAAC;CACf,CAAC;AAEF,MAAM,MAAM,iBAAiB,GAAG,qBAAqB,GAAG;IACtD,oEAAoE;IACpE,IAAI,CAAC,EAAE,WAAW,CAAC;IACnB;;qCAEiC;IACjC,OAAO,CAAC,EAAE,gBAAgB,CAAC;IAC3B;yBACqB;IACrB,MAAM,CAAC,EAAE,KAAK,GAAG,uBAAuB,CAAC;IACzC,uEAAuE;IACvE,YAAY,CAAC,EAAE,MAAM,IAAI,CAAC;IAC1B;;;;;OAKG;IACH,MAAM,CAAC,EAAE,CAAC,MAAM,EAAE,WAAW,GAAG,IAAI,KAAK,OAAO,CAAC;CAClD,CAAC;AAEF,MAAM,MAAM,UAAU,GAAG;IACvB,oDAAoD;IACpD,QAAQ,CAAC,GAAG,EAAE,cAAc,CAAC;IAC7B,mEAAmE;IACnE,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,QAAQ,IAAI,UAAU,CAAC;IACvB,YAAY,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC;IAClC,qEAAqE;IACrE,WAAW,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC;IACjC,YAAY,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC;IAClC,8CAA8C;IAC9C,OAAO,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B;+BAC2B;IAC3B,MAAM,IAAI,IAAI,CAAC;IACf,OAAO,IAAI,IAAI,CAAC;CACjB,CAAC;AAYF;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,GAAE,iBAAsB,GAAG,UAAU,CA2E5E;AA4GD,OAAO,EAAE,cAAc,EAAE,eAAe,EAAE,eAAe,EAAE,MAAM,QAAQ,CAAC;AAC1E,OAAO,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAC7D,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAC5C,YAAY,EAAE,SAAS,EAAE,sBAAsB,EAAE,MAAM,YAAY,CAAC;AACpE,YAAY,EACV,YAAY,EACZ,aAAa,EACb,IAAI,EACJ,IAAI,EACJ,KAAK,EACL,aAAa,EACb,YAAY,EACZ,UAAU,EACV,IAAI,EACJ,qBAAqB,EACrB,QAAQ,EACR,gBAAgB,GACjB,MAAM,SAAS,CAAC"}

package/dist/dom.js

@@ -0,0 +1,202 @@
+import { VirtualGamepad } from "./core";
+import { preShow, safeAreaInset } from "./safe-area";
+const defaultIgnore = (target) => target instanceof Element &&
+    target.closest("button, a, input, select, textarea, [data-gamepad-ignore]") !== null;
+const placement = (x, y, r) => ({
+    transform: `translate(${x - r}px, ${y - r}px)`,
+    width: `${r * 2}px`,
+    height: `${r * 2}px`,
+});
+/**
+ * Wire a {@link VirtualGamepad} to a plain DOM page — the adapter for
+ * non-Phaser games (Three.js, canvas, anything). Listens for touch pointer
+ * events on `window` (mouse is ignored so desktop keeps its own controls) and
+ * renders the floating stick + fixed buttons as positioned DOM elements in a
+ * `pointer-events:none` overlay, so it never steals taps from the page.
+ *
+ * The page is responsible for `touch-action: none` on its game surface —
+ * without it the browser may scroll/zoom instead of delivering moves.
+ *
+ * ```ts
+ * const gamepad = attachDomGamepad({
+ *   visible: "coarse",
+ *   buttons: [{ id: "jump", label: "JUMP", position: (v) => ({
+ *     x: v.width - 72 - v.inset.right, y: v.height - 72 - v.inset.bottom,
+ *   }) }],
+ * });
+ * // in your game loop:
+ * gamepad.update();
+ * const stick = gamepad.getStick();
+ * if (gamepad.justPressed("jump")) jump();
+ * ```
+ */
+export function attachDomGamepad(options = {}) {
+    const pad = new VirtualGamepad(options);
+    const ignore = options.ignore ?? defaultIgnore;
+    const policy = options.visible ?? "touch";
+    const renderOpts = options.render === false ? null : (options.render ?? {});
+    let isTouch = false;
+    let tint = renderOpts?.tint ?? "#fff";
+    let destroyed = false;
+    const live = new Set();
+    const syncViewport = () => pad.setViewport(window.innerWidth, window.innerHeight, safeAreaInset());
+    syncViewport();
+    const onDown = (e) => {
+        if (e.pointerType !== "touch")
+            return; // mouse stays on the game's own controls
+        if (!isTouch) {
+            isTouch = true;
+            options.onFirstTouch?.();
+        }
+        if (ignore(e.target))
+            return;
+        live.add(e.pointerId);
+        pad.pointerDown(e.pointerId, e.clientX, e.clientY);
+    };
+    const onMove = (e) => {
+        if (e.pointerType === "touch")
+            pad.pointerMove(e.pointerId, e.clientX, e.clientY);
+    };
+    const onUp = (e) => {
+        live.delete(e.pointerId);
+        pad.pointerUp(e.pointerId);
+    };
+    const onGone = () => {
+        live.clear();
+        pad.reset();
+    };
+    window.addEventListener("pointerdown", onDown);
+    window.addEventListener("pointermove", onMove);
+    window.addEventListener("pointerup", onUp);
+    window.addEventListener("pointercancel", onUp);
+    window.addEventListener("blur", onGone);
+    window.addEventListener("resize", syncViewport);
+    const view = renderOpts ? createOverlay(options.root ?? document.body, renderOpts) : null;
+    return {
+        pad,
+        get isTouch() {
+            return isTouch;
+        },
+        getStick: () => pad.getStick(),
+        isButtonDown: (id) => pad.isButtonDown(id),
+        justPressed: (id) => pad.justPressed(id),
+        justReleased: (id) => pad.justReleased(id),
+        setTint(color) {
+            tint = color;
+        },
+        update() {
+            pad.reconcile(live);
+            pad.nextFrame();
+            view?.draw(pad, tint, isTouch || preShow(policy));
+        },
+        destroy() {
+            if (destroyed)
+                return;
+            destroyed = true;
+            window.removeEventListener("pointerdown", onDown);
+            window.removeEventListener("pointermove", onMove);
+            window.removeEventListener("pointerup", onUp);
+            window.removeEventListener("pointercancel", onUp);
+            window.removeEventListener("blur", onGone);
+            window.removeEventListener("resize", syncViewport);
+            view?.root.remove();
+        },
+    };
+}
+// All chrome is drawn with white at fixed alphas; only the accent (knob fill,
+// button border) takes the tint — mirrors the Phaser renderer's look.
+function createOverlay(parent, opts) {
+    const root = document.createElement("div");
+    root.className = "vg-gamepad";
+    root.style.cssText =
+        `position:fixed;inset:0;pointer-events:none;z-index:${opts.zIndex ?? 40};` +
+            "font-family:system-ui,sans-serif;user-select:none;-webkit-user-select:none;";
+    parent.appendChild(root);
+    // Nodes are positioned with transform (top-left stays 0,0) and every style
+    // write is diffed through this cache, so an idle overlay costs zero style
+    // recalcs and a moving knob is compositor-only.
+    const applied = new Map();
+    const set = (node, styles) => {
+        let prev = applied.get(node);
+        if (!prev) {
+            prev = {};
+            applied.set(node, prev);
+        }
+        for (const [key, value] of Object.entries(styles)) {
+            if (prev[key] === value)
+                continue;
+            prev[key] = value;
+            if (key === "text")
+                node.textContent = value;
+            else
+                node.style.setProperty(key, value);
+        }
+    };
+    const el = (cls, css) => {
+        const d = document.createElement("div");
+        d.className = cls;
+        d.style.cssText = css;
+        root.appendChild(d);
+        return d;
+    };
+    const circle = "position:absolute;left:0;top:0;border-radius:50%;box-sizing:border-box;display:none;will-change:transform;";
+    const base = el("vg-stick-base", `${circle}background:rgba(255,255,255,.05);border:2px solid rgba(255,255,255,.2);`);
+    const knob = el("vg-stick-knob", `${circle}border:2px solid;`);
+    const buttons = new Map();
+    return {
+        root,
+        draw(pad, tint, show) {
+            const stick = pad.getStick();
+            const geom = pad.getStickGeometry();
+            const stickOn = show && stick.active && geom !== null;
+            set(base, { display: stickOn ? "block" : "none" });
+            set(knob, { display: stickOn ? "block" : "none" });
+            if (stickOn && geom) {
+                // Puck clamps to the ring edge so it never escapes the base.
+                const clamped = Math.min(stick.distance, geom.radius);
+                const kx = stick.distance > 0.001
+                    ? stick.anchorX + (stick.dx / stick.distance) * clamped
+                    : stick.anchorX;
+                const ky = stick.distance > 0.001
+                    ? stick.anchorY + (stick.dy / stick.distance) * clamped
+                    : stick.anchorY;
+                set(base, placement(stick.anchorX, stick.anchorY, geom.radius));
+                set(knob, {
+                    ...placement(kx, ky, geom.knobRadius),
+                    "border-color": tint,
+                    background: `color-mix(in srgb, ${tint} 25%, transparent)`,
+                });
+            }
+            for (const b of pad.getButtonLayout()) {
+                if (b.rest)
+                    continue; // rest buttons have no on-screen position
+                let node = buttons.get(b.id);
+                if (!node) {
+                    node = el("vg-btn", `${circle}border:2px solid;align-items:center;justify-content:center;` +
+                        "font-weight:600;letter-spacing:.04em;color:rgba(255,255,255,.92);");
+                    node.dataset["id"] = b.id;
+                    buttons.set(b.id, node);
+                }
+                if (!show) {
+                    set(node, { display: "none" });
+                    continue;
+                }
+                set(node, {
+                    ...placement(b.x, b.y, b.radius),
+                    display: "flex",
+                    text: b.label ?? "",
+                    "font-size": `${Math.round(b.radius * 0.42)}px`,
+                    "border-color": tint,
+                    opacity: b.pressed ? "1" : "0.55",
+                    background: b.pressed
+                        ? `color-mix(in srgb, ${tint} 34%, transparent)`
+                        : "rgba(255,255,255,.08)",
+                });
+            }
+        },
+    };
+}
+export { VirtualGamepad, stickDirection4, stickDirection8 } from "./core";
+export { PhysicalGamepad, isPadConnected } from "./physical";
+export { safeAreaInset } from "./safe-area";
+//# sourceMappingURL=dom.js.map

package/dist/dom.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"dom.js","sourceRoot":"","sources":["../src/dom.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -0,0 +1,6 @@
+export { VirtualGamepad, stickDirection4, stickDirection8 } from "./core";
+export { PhysicalGamepad, isPadConnected } from "./physical";
+export { safeAreaInset } from "./safe-area";
+export type { PadButton, PhysicalGamepadOptions } from "./physical";
+export type { ButtonLayout, ButtonOptions, Dir4, Dir8, Inset, StickGeometry, StickOptions, StickState, Vec2, VirtualGamepadOptions, Viewport, VisibilityPolicy, } from "./types";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,eAAe,EAAE,eAAe,EAAE,MAAM,QAAQ,CAAC;AAC1E,OAAO,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAC7D,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAC5C,YAAY,EAAE,SAAS,EAAE,sBAAsB,EAAE,MAAM,YAAY,CAAC;AACpE,YAAY,EACV,YAAY,EACZ,aAAa,EACb,IAAI,EACJ,IAAI,EACJ,KAAK,EACL,aAAa,EACb,YAAY,EACZ,UAAU,EACV,IAAI,EACJ,qBAAqB,EACrB,QAAQ,EACR,gBAAgB,GACjB,MAAM,SAAS,CAAC"}

package/dist/index.js

@@ -0,0 +1,4 @@
+export { VirtualGamepad, stickDirection4, stickDirection8 } from "./core";
+export { PhysicalGamepad, isPadConnected } from "./physical";
+export { safeAreaInset } from "./safe-area";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,eAAe,EAAE,eAAe,EAAE,MAAM,QAAQ,CAAC;AAC1E,OAAO,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAC7D,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC"}

package/dist/phaser.d.ts

@@ -0,0 +1,70 @@
+import Phaser from "phaser";
+import { VirtualGamepad } from "./core";
+import type { StickState, VirtualGamepadOptions, VisibilityPolicy } from "./types";
+export type PhaserGamepadRenderOptions = {
+    /** Render depth of the overlay Graphics (default 95 — above the world,
+     *  below a DOM HUD). */
+    depth?: number;
+    /** Knob + button color (default white). Change at runtime with `setTint`. */
+    tint?: number;
+    /** Blend mode for the Graphics (default `Phaser.BlendModes.ADD` so it glows
+     *  over a dark scene). Button labels always render NORMAL for legibility. */
+    blendMode?: Phaser.BlendModes;
+};
+export type PhaserGamepadOptions = VirtualGamepadOptions & {
+    /** Extra simultaneous pointers to register. Defaults to one per button plus
+     *  two for the stick + a spare, so simultaneous holds are never dropped. */
+    extraPointers?: number;
+    /** When the overlay renders: "touch" after the first touch (default),
+     *  "coarse" pre-shown on touch-capable devices so fixed buttons are
+     *  discoverable, or "always". */
+    visible?: VisibilityPolicy;
+    /** Built-in Graphics renderer config, or `false` to render it yourself from
+     *  the exposed `pad`. */
+    render?: false | PhaserGamepadRenderOptions;
+    /** Fired the first time a touch is seen — e.g. swap an on-screen control
+     *  hint, or hide a desktop cursor prompt. */
+    onFirstTouch?: () => void;
+};
+export type PhaserGamepad = {
+    /** The underlying framework-agnostic controller. */
+    readonly pad: VirtualGamepad;
+    /** True once any touch has been seen this session (stays true). */
+    readonly isTouch: boolean;
+    /** Current stick reading. */
+    getStick(): StickState;
+    isButtonDown(id: string): boolean;
+    /** Edge-triggered press since last `update()` (tap = one action). */
+    justPressed(id: string): boolean;
+    justReleased(id: string): boolean;
+    /** Recolor the knob + buttons (e.g. to the local player's color). */
+    setTint(color: number): void;
+    /** Call once per frame from your scene's `update()`: reconciles stale
+     *  pointers, publishes press edges, and redraws the overlay. */
+    update(): void;
+    destroy(): void;
+};
+/**
+ * Wire a {@link VirtualGamepad} to a Phaser scene: registers extra pointers,
+ * forwards touch events (mouse is ignored so a desktop game keeps its own
+ * cursor controls), and draws a screen-fixed joystick + buttons overlay.
+ *
+ * ```ts
+ * const gamepad = attachVirtualGamepad(this, {
+ *   buttons: [{ id: "fire" }], // a "rest" button: any 2nd finger fires
+ *   onFirstTouch: () => hideHint(),
+ * });
+ * // in update():
+ * gamepad.update();
+ * const stick = gamepad.getStick();
+ * if (stick.active && !stick.inDeadZone) steer(stick.angle, stick.magnitude);
+ * if (gamepad.isButtonDown("fire")) shoot();
+ * ```
+ */
+export declare function attachVirtualGamepad(scene: Phaser.Scene, options?: PhaserGamepadOptions): PhaserGamepad;
+export { VirtualGamepad, stickDirection4, stickDirection8 } from "./core";
+export { PhysicalGamepad, isPadConnected } from "./physical";
+export { safeAreaInset } from "./safe-area";
+export type { PadButton, PhysicalGamepadOptions } from "./physical";
+export type { ButtonLayout, ButtonOptions, Dir4, Dir8, Inset, StickGeometry, StickOptions, StickState, Vec2, VirtualGamepadOptions, Viewport, VisibilityPolicy, } from "./types";
+//# sourceMappingURL=phaser.d.ts.map

package/dist/phaser.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"phaser.d.ts","sourceRoot":"","sources":["../src/phaser.ts"],"names":[],"mappings":"AAAA,OAAO,MAAM,MAAM,QAAQ,CAAC;AAE5B,OAAO,EAAE,cAAc,EAAE,MAAM,QAAQ,CAAC;AAExC,OAAO,KAAK,EAAE,UAAU,EAAE,qBAAqB,EAAE,gBAAgB,EAAE,MAAM,SAAS,CAAC;AAEnF,MAAM,MAAM,0BAA0B,GAAG;IACvC;4BACwB;IACxB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,6EAA6E;IAC7E,IAAI,CAAC,EAAE,MAAM,CAAC;IACd;iFAC6E;IAC7E,SAAS,CAAC,EAAE,MAAM,CAAC,UAAU,CAAC;CAC/B,CAAC;AAEF,MAAM,MAAM,oBAAoB,GAAG,qBAAqB,GAAG;IACzD;gFAC4E;IAC5E,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB;;qCAEiC;IACjC,OAAO,CAAC,EAAE,gBAAgB,CAAC;IAC3B;6BACyB;IACzB,MAAM,CAAC,EAAE,KAAK,GAAG,0BAA0B,CAAC;IAC5C;iDAC6C;IAC7C,YAAY,CAAC,EAAE,MAAM,IAAI,CAAC;CAC3B,CAAC;AAEF,MAAM,MAAM,aAAa,GAAG;IAC1B,oDAAoD;IACpD,QAAQ,CAAC,GAAG,EAAE,cAAc,CAAC;IAC7B,mEAAmE;IACnE,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,6BAA6B;IAC7B,QAAQ,IAAI,UAAU,CAAC;IACvB,YAAY,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC;IAClC,qEAAqE;IACrE,WAAW,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC;IACjC,YAAY,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC;IAClC,qEAAqE;IACrE,OAAO,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B;oEACgE;IAChE,MAAM,IAAI,IAAI,CAAC;IACf,OAAO,IAAI,IAAI,CAAC;CACjB,CAAC;AAEF;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,oBAAoB,CAClC,KAAK,EAAE,MAAM,CAAC,KAAK,EACnB,OAAO,GAAE,oBAAyB,GACjC,aAAa,CA2Ff;AA4DD,OAAO,EAAE,cAAc,EAAE,eAAe,EAAE,eAAe,EAAE,MAAM,QAAQ,CAAC;AAC1E,OAAO,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAC7D,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAC5C,YAAY,EAAE,SAAS,EAAE,sBAAsB,EAAE,MAAM,YAAY,CAAC;AACpE,YAAY,EACV,YAAY,EACZ,aAAa,EACb,IAAI,EACJ,IAAI,EACJ,KAAK,EACL,aAAa,EACb,YAAY,EACZ,UAAU,EACV,IAAI,EACJ,qBAAqB,EACrB,QAAQ,EACR,gBAAgB,GACjB,MAAM,SAAS,CAAC"}

package/dist/phaser.js

@@ -0,0 +1,169 @@
+import Phaser from "phaser";
+import { VirtualGamepad } from "./core";
+import { preShow, safeAreaInset } from "./safe-area";
+/**
+ * Wire a {@link VirtualGamepad} to a Phaser scene: registers extra pointers,
+ * forwards touch events (mouse is ignored so a desktop game keeps its own
+ * cursor controls), and draws a screen-fixed joystick + buttons overlay.
+ *
+ * ```ts
+ * const gamepad = attachVirtualGamepad(this, {
+ *   buttons: [{ id: "fire" }], // a "rest" button: any 2nd finger fires
+ *   onFirstTouch: () => hideHint(),
+ * });
+ * // in update():
+ * gamepad.update();
+ * const stick = gamepad.getStick();
+ * if (stick.active && !stick.inDeadZone) steer(stick.angle, stick.magnitude);
+ * if (gamepad.isButtonDown("fire")) shoot();
+ * ```
+ */
+export function attachVirtualGamepad(scene, options = {}) {
+    const pad = new VirtualGamepad(options);
+    let isTouch = false;
+    const policy = options.visible ?? "touch";
+    const renderOpts = options.render === false ? null : (options.render ?? {});
+    let tint = renderOpts?.tint ?? 0xffffff;
+    scene.input.addPointer(options.extraPointers ?? Math.max(2, (options.buttons?.length ?? 0) + 2));
+    const syncViewport = () => {
+        const { width, height } = scene.scale;
+        // Phaser's logical size can differ from CSS pixels (FIT/zoom modes) —
+        // scale the CSS-px insets into scene units so anchored buttons don't
+        // overshoot on notched phones.
+        const raw = safeAreaInset();
+        const sx = window.innerWidth > 0 ? width / window.innerWidth : 1;
+        const sy = window.innerHeight > 0 ? height / window.innerHeight : 1;
+        pad.setViewport(width, height, {
+            top: raw.top * sy,
+            right: raw.right * sx,
+            bottom: raw.bottom * sy,
+            left: raw.left * sx,
+        });
+    };
+    syncViewport();
+    const onDown = (p) => {
+        if (!p.wasTouch)
+            return; // mouse stays on the game's own control model
+        if (!isTouch) {
+            isTouch = true;
+            options.onFirstTouch?.();
+        }
+        syncViewport();
+        pad.pointerDown(p.id, p.x, p.y);
+    };
+    const onMove = (p) => {
+        if (p.wasTouch)
+            pad.pointerMove(p.id, p.x, p.y);
+    };
+    const onUp = (p) => pad.pointerUp(p.id);
+    scene.input.on(Phaser.Input.Events.POINTER_DOWN, onDown);
+    scene.input.on(Phaser.Input.Events.POINTER_MOVE, onMove);
+    scene.input.on(Phaser.Input.Events.POINTER_UP, onUp);
+    let gfx = null;
+    const labels = new Map();
+    if (renderOpts) {
+        gfx = scene.add
+            .graphics()
+            .setScrollFactor(0)
+            .setDepth(renderOpts.depth ?? 95)
+            .setBlendMode(renderOpts.blendMode ?? Phaser.BlendModes.ADD);
+    }
+    const draw = () => {
+        if (!gfx)
+            return;
+        gfx.clear();
+        const show = isTouch || preShow(policy);
+        if (show)
+            drawGamepad(gfx, pad, tint);
+        syncLabels(scene, gfx, pad, labels, show);
+    };
+    return {
+        pad,
+        get isTouch() {
+            return isTouch;
+        },
+        getStick: () => pad.getStick(),
+        isButtonDown: (id) => pad.isButtonDown(id),
+        justPressed: (id) => pad.justPressed(id),
+        justReleased: (id) => pad.justReleased(id),
+        setTint: (color) => {
+            tint = color;
+        },
+        update() {
+            const live = [];
+            for (const ptr of scene.input.manager.pointers)
+                if (ptr.isDown)
+                    live.push(ptr.id);
+            pad.reconcile(live);
+            pad.nextFrame();
+            syncViewport();
+            draw();
+        },
+        destroy() {
+            scene.input.off(Phaser.Input.Events.POINTER_DOWN, onDown);
+            scene.input.off(Phaser.Input.Events.POINTER_MOVE, onMove);
+            scene.input.off(Phaser.Input.Events.POINTER_UP, onUp);
+            gfx?.destroy();
+            for (const t of labels.values())
+                t.destroy();
+            labels.clear();
+        },
+    };
+}
+/** Keep a Text object per labeled fixed button (Graphics can't draw text). */
+function syncLabels(scene, gfx, pad, labels, show) {
+    for (const b of pad.getButtonLayout()) {
+        if (b.rest || !b.label)
+            continue;
+        let text = labels.get(b.id);
+        if (!text) {
+            text = scene.add
+                .text(0, 0, b.label, {
+                fontFamily: "system-ui, sans-serif",
+                fontStyle: "600",
+                color: "#ffffff",
+            })
+                .setOrigin(0.5)
+                .setScrollFactor(0)
+                .setDepth(gfx.depth + 1);
+            labels.set(b.id, text);
+        }
+        text.setVisible(show);
+        if (!show)
+            continue;
+        text.setPosition(b.x, b.y);
+        text.setFontSize(Math.round(b.radius * 0.42));
+        text.setAlpha(b.pressed ? 1 : 0.75);
+    }
+}
+/** Draw the joystick + fixed buttons into a Graphics object (screen-space). */
+function drawGamepad(g, pad, tint) {
+    const geom = pad.getStickGeometry();
+    const stick = pad.getStick();
+    if (geom && stick.active) {
+        const { radius, deadZone, knobRadius } = geom;
+        const ax = stick.anchorX;
+        const ay = stick.anchorY;
+        // Puck clamps to the ring edge so it never escapes the base.
+        const clamped = Math.min(stick.distance, radius);
+        const kx = stick.distance > 0.001 ? ax + (stick.dx / stick.distance) * clamped : ax;
+        const ky = stick.distance > 0.001 ? ay + (stick.dy / stick.distance) * clamped : ay;
+        g.fillStyle(0xffffff, 0.05).fillCircle(ax, ay, radius);
+        g.lineStyle(2, 0xffffff, 0.2).strokeCircle(ax, ay, radius);
+        g.fillStyle(0xffffff, 0.12).fillCircle(ax, ay, deadZone);
+        g.fillStyle(tint, 0.22).fillCircle(kx, ky, knobRadius);
+        g.lineStyle(2, tint, 0.85).strokeCircle(kx, ky, knobRadius);
+    }
+    for (const b of pad.getButtonLayout()) {
+        if (b.rest)
+            continue; // rest buttons have no on-screen position
+        g.fillStyle(tint, b.pressed ? 0.34 : 0.12);
+        g.fillCircle(b.x, b.y, b.radius);
+        g.lineStyle(2, tint, b.pressed ? 0.95 : 0.45);
+        g.strokeCircle(b.x, b.y, b.radius);
+    }
+}
+export { VirtualGamepad, stickDirection4, stickDirection8 } from "./core";
+export { PhysicalGamepad, isPadConnected } from "./physical";
+export { safeAreaInset } from "./safe-area";
+//# sourceMappingURL=phaser.js.map

package/dist/phaser.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"phaser.js","sourceRoot":"","sources":["../src/phaser.ts"],"names":[],"mappings":"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"}

package/dist/physical.d.ts

@@ -0,0 +1,77 @@
+import type { StickState } from "./types";
+/** Standard-mapping button names (https://w3c.github.io/gamepad/#remapping).
+ *  Non-standard pads are read with the same indices — best effort. */
+export type PadButton = "a" | "b" | "x" | "y" | "lb" | "rb" | "lt" | "rt" | "select" | "start" | "ls" | "rs" | "up" | "down" | "left" | "right";
+export type PhysicalGamepadOptions = {
+    /**
+     * Game action id → physical buttons, so a game reads the SAME ids from this
+     * pad as from its {@link VirtualGamepad} buttons (e.g. `"jump"`, `"fire"`).
+     * Raw {@link PadButton} names always work without a binding.
+     */
+    bindings?: Readonly<Record<string, readonly PadButton[]>>;
+    /** Stick deflection (0–1) treated as noise. Default 0.15. */
+    stickDeadZone?: number;
+    /** Analog trigger value above which lt/rt count as pressed. Default 0.05. */
+    triggerThreshold?: number;
+    /** Fired when the first pad appears (polled — fires on the next update()). */
+    onConnect?: () => void;
+    /** Fired when the last pad disappears. */
+    onDisconnect?: () => void;
+    /** Pad source, injectable for tests. Default `navigator.getGamepads()`. */
+    poll?: () => ReadonlyArray<Gamepad | null>;
+};
+/** True if any physical pad is currently connected — e.g. to decide whether
+ *  controller rows belong on an instructions screen. */
+export declare function isPadConnected(): boolean;
+/**
+ * Physical controller input, API-mirroring {@link VirtualGamepad} so a game's
+ * read path works for both: `isButtonDown(id)` / `justPressed(id)` /
+ * `getStick()`. Poll-based — call `update()` once per frame; edges are
+ * published per update, matching the virtual pad's `nextFrame()` semantics.
+ * The first connected pad wins. No DOM, no engine, no listeners.
+ *
+ * ```ts
+ * const pad = new PhysicalGamepad({ bindings: { jump: ["a"], dash: ["b", "rb"] } });
+ * // in your game loop:
+ * pad.update();
+ * const dir = stickDirection4(pad.getStick());
+ * if (pad.justPressed("jump")) jump();
+ * ```
+ */
+export declare class PhysicalGamepad {
+    private readonly bindings;
+    private readonly stickDeadZone;
+    private readonly triggerThreshold;
+    private readonly onConnect?;
+    private readonly onDisconnect?;
+    private readonly poll;
+    private wasConnected;
+    private axes;
+    private down;
+    private prevDown;
+    /** Raw analog values (triggers), by button name. */
+    private values;
+    constructor(options?: PhysicalGamepadOptions);
+    /** Poll the first connected pad and publish press edges for this frame. */
+    update(): void;
+    /** A pad was connected as of the last `update()`. */
+    get connected(): boolean;
+    /** `id` is a binding action id or a raw {@link PadButton} name. */
+    isButtonDown(id: string): boolean;
+    /** Action went up→down since the previous `update()` (any bound button). */
+    justPressed(id: string): boolean;
+    /** Action went down→up since the previous `update()` (all bound buttons up). */
+    justReleased(id: string): boolean;
+    /** Raw analog value 0–1 (triggers are the interesting case). 0 when absent. */
+    buttonValue(button: PadButton): number;
+    /**
+     * A stick reading in {@link StickState} form (axes 0/1 left, 2/3 right;
+     * y-down matches screen space), so `stickDirection4/8` work unchanged.
+     * `active` while a pad is connected; dead-zoned like the virtual stick.
+     */
+    getStick(side?: "left" | "right"): StickState;
+    /** Release all state (the class holds no listeners — this just clears). */
+    destroy(): void;
+    private resolve;
+}
+//# sourceMappingURL=physical.d.ts.map