@gg-web-engine/mobile-controls 0.0.0-stage → 0.0.78

package/dist/mobile-controls.entity.js

@@ -0,0 +1,274 @@
+import { takeUntil } from 'rxjs';
+import { CarHandlingController, FreeCameraController, GgCarHandlingController, IEntity, PlayerCharacterController, PlayerCharacterController2d, TickOrder, } from '@gg-web-engine/core';
+import { TouchControl } from './controls/touch-control';
+import { carLayout } from './layouts/car.layout';
+import { character2dLayout } from './layouts/character-2d.layout';
+import { characterLayout } from './layouts/character.layout';
+import { freeCameraLayout } from './layouts/free-camera.layout';
+import { injectMobileControlsStyles } from './styles';
+/**
+ * Whether the device is operated by touch first (a phone, a tablet) - what `enabled: 'auto'` goes by.
+ * A laptop that merely has a touch screen next to its mouse does not count.
+ */
+export function isTouchFirstDevice() {
+    if (typeof window === 'undefined' || typeof navigator === 'undefined') {
+        return false;
+    }
+    if (typeof window.matchMedia === 'function') {
+        return window.matchMedia('(pointer: coarse)').matches;
+    }
+    return navigator.maxTouchPoints > 0;
+}
+const DEFAULT_OPTIONS = {
+    enabled: 'auto',
+    container: null,
+    className: '',
+    injectStyles: true,
+    car: {},
+    character: {},
+    character2d: {},
+    freeCamera: {},
+};
+/**
+ * An overlay of on-screen touch controls over the game canvas. Add it to a world once, and it shows
+ * the controls matching whichever input controller is active in that world at the moment, swapping
+ * them as controllers are activated, deactivated, spawned and removed:
+ *
+ * ```ts
+ * world.addEntity(new MobileControls());
+ * ```
+ *
+ * Out of the box it knows the car controllers (`GgCarHandlingController`,
+ * `CarHandlingController`), `PlayerCharacterController`, `PlayerCharacterController2d` and
+ * `FreeCameraController`. Each of those layouts is adjusted through
+ * its options (see `MobileControlsOptions`), replaced by `registerLayout`, and any other controller
+ * class - including an app's own - gets a layout the same way. Controls that belong to no controller
+ * (pause, a menu button) are added with `addControls`.
+ */
+export class MobileControls extends IEntity {
+    get enabled() {
+        return this._enabled;
+    }
+    /** See `MobileControlsOptions.enabled`. */
+    set enabled(value) {
+        this._enabled = value;
+        this.sync();
+    }
+    get visible() {
+        return this._visible;
+    }
+    /**
+     * Hides the overlay without disabling it, for the moments touch controls are in the way (a menu,
+     * a cutscene). Everything held is released.
+     */
+    set visible(value) {
+        this._visible = value;
+        this.sync();
+    }
+    /** Whether the overlay is on the page right now. */
+    get shown() {
+        return this.element.isConnected;
+    }
+    /** The controllers that currently have their controls on screen. */
+    get activeControllers() {
+        return [...this.layouts.keys()];
+    }
+    constructor(options = {}) {
+        super();
+        this.tickOrder = TickOrder.INPUT_CONTROLLERS;
+        this.registrations = [];
+        this.tracked = new Set();
+        this.layouts = new Map();
+        this.ownControls = new Set();
+        this._visible = true;
+        this.options = Object.assign(Object.assign({}, DEFAULT_OPTIONS), options);
+        this._enabled = this.options.enabled;
+        this.element = document.createElement('div');
+        this.element.className = 'gg-mc';
+        if (this.options.container) {
+            this.element.classList.add('gg-mc--contained');
+        }
+        if (this.options.className) {
+            this.element.classList.add(...this.options.className.split(/\s+/).filter(x => !!x));
+        }
+        this.releaseAll = this.releaseAll.bind(this);
+        if (this.options.car) {
+            const layout = carLayout(this.options.car);
+            this.registerLayout(CarHandlingController, layout);
+            this.registerLayout(GgCarHandlingController, layout);
+        }
+        if (this.options.character) {
+            this.registerLayout(PlayerCharacterController, characterLayout(this.options.character));
+        }
+        if (this.options.character2d) {
+            this.registerLayout(PlayerCharacterController2d, character2dLayout(this.options.character2d));
+        }
+        if (this.options.freeCamera) {
+            this.registerLayout(FreeCameraController, freeCameraLayout(this.options.freeCamera));
+        }
+    }
+    /**
+     * Sets the layout shown while a controller of `controllerClass` (or of a subclass) is active,
+     * replacing a layout registered for the same class before; `null` leaves that class without one.
+     * Of several registered classes a controller is an instance of, the one registered last wins.
+     */
+    registerLayout(controllerClass, factory) {
+        const index = this.registrations.findIndex(r => r.controllerClass === controllerClass);
+        if (index >= 0) {
+            this.registrations.splice(index, 1);
+        }
+        if (factory) {
+            this.registrations.push({ controllerClass, factory });
+        }
+        if (this.world) {
+            this.rescan();
+        }
+    }
+    /**
+     * Adds controls that stay on screen whichever controller is active, on top of the layouts.
+     */
+    addControls(...controls) {
+        for (const control of controls) {
+            this.ownControls.add(control);
+            this.element.appendChild(control.element);
+        }
+    }
+    /** Removes controls added by `addControls` and disposes them. */
+    removeControls(...controls) {
+        for (const control of controls) {
+            if (this.ownControls.delete(control)) {
+                control.dispose();
+            }
+        }
+    }
+    /**
+     * Builds the layout of `controller` anew - after something its layout was built from has changed
+     * (the car it drives, an option), since a layout is otherwise built once per activation.
+     */
+    refresh(controller) {
+        for (const key of controller ? [controller] : [...this.layouts.keys()]) {
+            this.disposeLayout(key);
+        }
+        this.sync();
+    }
+    onSpawned(world) {
+        super.onSpawned(world);
+        world.entityAdded$.pipe(takeUntil(this._onRemoved$)).subscribe(entity => {
+            if (this.findFactory(entity)) {
+                this.tracked.add(entity);
+                this.sync();
+            }
+        });
+        world.entityRemoved$.pipe(takeUntil(this._onRemoved$)).subscribe(entity => {
+            if (this.tracked.delete(entity)) {
+                this.sync();
+            }
+        });
+        // a world whose input is switched off (a screen covering the game) takes its controls off the
+        // screen; it may be paused at that moment, so this can't wait for the next tick
+        world.inputEnabled$.pipe(takeUntil(this._onRemoved$)).subscribe(() => this.sync());
+        // `active` has no change notification, so it is polled
+        this.tick$.pipe(takeUntil(this._onRemoved$)).subscribe(() => this.sync());
+        window.addEventListener('blur', this.releaseAll);
+        this.rescan();
+    }
+    onRemoved() {
+        super.onRemoved();
+        window.removeEventListener('blur', this.releaseAll);
+        this.tracked.clear();
+        this.sync();
+    }
+    dispose() {
+        super.dispose();
+        for (const control of this.ownControls) {
+            control.dispose();
+        }
+        this.ownControls.clear();
+    }
+    /** Returns every control on screen to its untouched state. */
+    releaseAll() {
+        for (const items of this.layouts.values()) {
+            for (const item of items) {
+                if (item instanceof TouchControl) {
+                    item.reset();
+                }
+            }
+        }
+        for (const control of this.ownControls) {
+            control.reset();
+        }
+    }
+    findFactory(entity) {
+        for (let i = this.registrations.length - 1; i >= 0; i--) {
+            if (entity instanceof this.registrations[i].controllerClass) {
+                return this.registrations[i].factory;
+            }
+        }
+        return null;
+    }
+    rescan() {
+        var _a;
+        this.tracked.clear();
+        const visit = (entity) => {
+            if (this.findFactory(entity)) {
+                this.tracked.add(entity);
+            }
+            entity.children.forEach(visit);
+        };
+        (((_a = this.world) === null || _a === void 0 ? void 0 : _a.children) || []).forEach(visit);
+        for (const controller of [...this.layouts.keys()]) {
+            this.disposeLayout(controller);
+        }
+        this.sync();
+    }
+    sync() {
+        const world = this.world;
+        const show = !!world &&
+            this._visible &&
+            world.inputEnabled !== false &&
+            (this._enabled === 'auto' ? isTouchFirstDevice() : this._enabled);
+        if (show !== this.shown) {
+            if (show) {
+                if (this.options.injectStyles) {
+                    injectMobileControlsStyles();
+                }
+                (this.options.container || document.body).appendChild(this.element);
+            }
+            else {
+                this.releaseAll();
+                this.element.remove();
+            }
+        }
+        for (const controller of [...this.layouts.keys()]) {
+            if (!show || !this.tracked.has(controller) || !controller.active) {
+                this.disposeLayout(controller);
+            }
+        }
+        if (!show) {
+            return;
+        }
+        for (const controller of this.tracked) {
+            if (controller.active && !this.layouts.has(controller)) {
+                const items = this.findFactory(controller)(controller, { world: world, controls: this });
+                this.layouts.set(controller, items);
+                // below the controls added by `addControls`, which stay on top
+                const before = this.ownControls.size > 0 ? [...this.ownControls][0].element : null;
+                for (const item of items) {
+                    if (item instanceof TouchControl) {
+                        this.element.insertBefore(item.element, before);
+                    }
+                }
+            }
+        }
+    }
+    disposeLayout(controller) {
+        const items = this.layouts.get(controller);
+        if (items) {
+            this.layouts.delete(controller);
+            for (const item of items) {
+                item.dispose();
+            }
+        }
+    }
+}
+MobileControls.entityTypeName = 'MobileControls';

package/dist/styles.d.ts

@@ -0,0 +1,16 @@
+/**
+ * The id of the `<style>` element `injectMobileControlsStyles` adds to the document head.
+ */
+export declare const MOBILE_CONTROLS_STYLE_ID = "gg-mobile-controls-styles";
+/**
+ * The default stylesheet of the overlay. `--gg-mc-unit` follows the viewport so that the built-in
+ * layouts, which are up to 55 units wide, fit a phone held upright as well as on its side (at least
+ * 58 units across). Everything is sized in `--gg-mc-unit` and colored through
+ * the other `--gg-mc-*` custom properties declared on `.gg-mc`, so an app restyles the overlay by
+ * overriding those on its own class, and a single control through its `.gg-mc-id-*` class.
+ */
+export declare const MOBILE_CONTROLS_CSS = "\n.gg-mc {\n  --gg-mc-unit: clamp(5px, min(2vmin, 1.7vw), 10px);\n  --gg-mc-color: #fff;\n  --gg-mc-background: rgba(18, 22, 30, 0.3);\n  --gg-mc-border: rgba(255, 255, 255, 0.6);\n  --gg-mc-active-background: rgba(255, 255, 255, 0.4);\n  --gg-mc-opacity: 0.85;\n  position: fixed;\n  inset: 0;\n  z-index: 1000;\n  overflow: hidden;\n  pointer-events: none;\n  touch-action: none;\n  user-select: none;\n  -webkit-user-select: none;\n  -webkit-touch-callout: none;\n  -webkit-tap-highlight-color: transparent;\n  color: var(--gg-mc-color);\n  opacity: var(--gg-mc-opacity);\n  font: 600 calc(var(--gg-mc-unit) * 2.4) / 1 system-ui, -apple-system, 'Segoe UI', sans-serif;\n}\n.gg-mc.gg-mc--contained {\n  position: absolute;\n}\n.gg-mc-control {\n  position: absolute;\n  box-sizing: border-box;\n  pointer-events: auto;\n  touch-action: none;\n}\n.gg-mc-control[hidden] {\n  display: none;\n}\n.gg-mc-control svg {\n  width: 52%;\n  height: 52%;\n  fill: none;\n  stroke: currentColor;\n  stroke-width: 2;\n  stroke-linecap: round;\n  stroke-linejoin: round;\n  pointer-events: none;\n}\n.gg-mc-button {\n  width: calc(var(--gg-mc-unit) * 8);\n  height: calc(var(--gg-mc-unit) * 8);\n  display: flex;\n  align-items: center;\n  justify-content: center;\n  border: calc(var(--gg-mc-unit) * 0.22) solid var(--gg-mc-border);\n  border-radius: 50%;\n  background: var(--gg-mc-background);\n  transition: transform 60ms ease-out, background-color 60ms ease-out;\n}\n.gg-mc-button.gg-mc-active {\n  background: var(--gg-mc-active-background);\n  transform: scale(0.93);\n}\n.gg-mc-stick {\n  width: calc(var(--gg-mc-unit) * 15);\n  height: calc(var(--gg-mc-unit) * 15);\n}\n.gg-mc-stick-base {\n  position: absolute;\n  left: 50%;\n  top: 50%;\n  width: calc(var(--gg-mc-unit) * 15);\n  height: calc(var(--gg-mc-unit) * 15);\n  box-sizing: border-box;\n  border: calc(var(--gg-mc-unit) * 0.22) solid var(--gg-mc-border);\n  border-radius: 50%;\n  background: var(--gg-mc-background);\n  transform: translate(-50%, -50%);\n  pointer-events: none;\n}\n.gg-mc-stick--floating .gg-mc-stick-base {\n  left: calc(var(--gg-mc-unit) * 13 + env(safe-area-inset-left, 0px));\n  top: calc(100% - var(--gg-mc-unit) * 12 - env(safe-area-inset-bottom, 0px));\n  opacity: 0.55;\n  transition: opacity 120ms ease-out;\n}\n.gg-mc-stick--floating.gg-mc-active .gg-mc-stick-base {\n  opacity: 1;\n}\n.gg-mc-stick-knob {\n  position: absolute;\n  left: 50%;\n  top: 50%;\n  width: 44%;\n  height: 44%;\n  box-sizing: border-box;\n  border: calc(var(--gg-mc-unit) * 0.22) solid var(--gg-mc-border);\n  border-radius: 50%;\n  background: var(--gg-mc-active-background);\n  transform: translate(-50%, -50%);\n}\n.gg-mc-dpad {\n  width: calc(var(--gg-mc-unit) * 19);\n  height: calc(var(--gg-mc-unit) * 19);\n}\n.gg-mc-dpad-arm {\n  position: absolute;\n  width: 34%;\n  height: 34%;\n  display: flex;\n  align-items: center;\n  justify-content: center;\n  box-sizing: border-box;\n  border: calc(var(--gg-mc-unit) * 0.22) solid var(--gg-mc-border);\n  border-radius: 22%;\n  background: var(--gg-mc-background);\n  transition: background-color 60ms ease-out;\n  pointer-events: none;\n}\n.gg-mc-dpad-arm.gg-mc-active {\n  background: var(--gg-mc-active-background);\n}\n.gg-mc-dpad-arm--up {\n  left: 33%;\n  top: 0;\n}\n.gg-mc-dpad-arm--down {\n  left: 33%;\n  bottom: 0;\n}\n.gg-mc-dpad-arm--left {\n  left: 0;\n  top: 33%;\n}\n.gg-mc-dpad-arm--right {\n  right: 0;\n  top: 33%;\n}\n";
+/**
+ * Adds the default stylesheet to the document head, once per document.
+ */
+export declare function injectMobileControlsStyles(): void;

package/dist/styles.js

@@ -0,0 +1,158 @@
+/**
+ * The id of the `<style>` element `injectMobileControlsStyles` adds to the document head.
+ */
+export const MOBILE_CONTROLS_STYLE_ID = 'gg-mobile-controls-styles';
+/**
+ * The default stylesheet of the overlay. `--gg-mc-unit` follows the viewport so that the built-in
+ * layouts, which are up to 55 units wide, fit a phone held upright as well as on its side (at least
+ * 58 units across). Everything is sized in `--gg-mc-unit` and colored through
+ * the other `--gg-mc-*` custom properties declared on `.gg-mc`, so an app restyles the overlay by
+ * overriding those on its own class, and a single control through its `.gg-mc-id-*` class.
+ */
+export const MOBILE_CONTROLS_CSS = `
+.gg-mc {
+  --gg-mc-unit: clamp(5px, min(2vmin, 1.7vw), 10px);
+  --gg-mc-color: #fff;
+  --gg-mc-background: rgba(18, 22, 30, 0.3);
+  --gg-mc-border: rgba(255, 255, 255, 0.6);
+  --gg-mc-active-background: rgba(255, 255, 255, 0.4);
+  --gg-mc-opacity: 0.85;
+  position: fixed;
+  inset: 0;
+  z-index: 1000;
+  overflow: hidden;
+  pointer-events: none;
+  touch-action: none;
+  user-select: none;
+  -webkit-user-select: none;
+  -webkit-touch-callout: none;
+  -webkit-tap-highlight-color: transparent;
+  color: var(--gg-mc-color);
+  opacity: var(--gg-mc-opacity);
+  font: 600 calc(var(--gg-mc-unit) * 2.4) / 1 system-ui, -apple-system, 'Segoe UI', sans-serif;
+}
+.gg-mc.gg-mc--contained {
+  position: absolute;
+}
+.gg-mc-control {
+  position: absolute;
+  box-sizing: border-box;
+  pointer-events: auto;
+  touch-action: none;
+}
+.gg-mc-control[hidden] {
+  display: none;
+}
+.gg-mc-control svg {
+  width: 52%;
+  height: 52%;
+  fill: none;
+  stroke: currentColor;
+  stroke-width: 2;
+  stroke-linecap: round;
+  stroke-linejoin: round;
+  pointer-events: none;
+}
+.gg-mc-button {
+  width: calc(var(--gg-mc-unit) * 8);
+  height: calc(var(--gg-mc-unit) * 8);
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  border: calc(var(--gg-mc-unit) * 0.22) solid var(--gg-mc-border);
+  border-radius: 50%;
+  background: var(--gg-mc-background);
+  transition: transform 60ms ease-out, background-color 60ms ease-out;
+}
+.gg-mc-button.gg-mc-active {
+  background: var(--gg-mc-active-background);
+  transform: scale(0.93);
+}
+.gg-mc-stick {
+  width: calc(var(--gg-mc-unit) * 15);
+  height: calc(var(--gg-mc-unit) * 15);
+}
+.gg-mc-stick-base {
+  position: absolute;
+  left: 50%;
+  top: 50%;
+  width: calc(var(--gg-mc-unit) * 15);
+  height: calc(var(--gg-mc-unit) * 15);
+  box-sizing: border-box;
+  border: calc(var(--gg-mc-unit) * 0.22) solid var(--gg-mc-border);
+  border-radius: 50%;
+  background: var(--gg-mc-background);
+  transform: translate(-50%, -50%);
+  pointer-events: none;
+}
+.gg-mc-stick--floating .gg-mc-stick-base {
+  left: calc(var(--gg-mc-unit) * 13 + env(safe-area-inset-left, 0px));
+  top: calc(100% - var(--gg-mc-unit) * 12 - env(safe-area-inset-bottom, 0px));
+  opacity: 0.55;
+  transition: opacity 120ms ease-out;
+}
+.gg-mc-stick--floating.gg-mc-active .gg-mc-stick-base {
+  opacity: 1;
+}
+.gg-mc-stick-knob {
+  position: absolute;
+  left: 50%;
+  top: 50%;
+  width: 44%;
+  height: 44%;
+  box-sizing: border-box;
+  border: calc(var(--gg-mc-unit) * 0.22) solid var(--gg-mc-border);
+  border-radius: 50%;
+  background: var(--gg-mc-active-background);
+  transform: translate(-50%, -50%);
+}
+.gg-mc-dpad {
+  width: calc(var(--gg-mc-unit) * 19);
+  height: calc(var(--gg-mc-unit) * 19);
+}
+.gg-mc-dpad-arm {
+  position: absolute;
+  width: 34%;
+  height: 34%;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  box-sizing: border-box;
+  border: calc(var(--gg-mc-unit) * 0.22) solid var(--gg-mc-border);
+  border-radius: 22%;
+  background: var(--gg-mc-background);
+  transition: background-color 60ms ease-out;
+  pointer-events: none;
+}
+.gg-mc-dpad-arm.gg-mc-active {
+  background: var(--gg-mc-active-background);
+}
+.gg-mc-dpad-arm--up {
+  left: 33%;
+  top: 0;
+}
+.gg-mc-dpad-arm--down {
+  left: 33%;
+  bottom: 0;
+}
+.gg-mc-dpad-arm--left {
+  left: 0;
+  top: 33%;
+}
+.gg-mc-dpad-arm--right {
+  right: 0;
+  top: 33%;
+}
+`;
+/**
+ * Adds the default stylesheet to the document head, once per document.
+ */
+export function injectMobileControlsStyles() {
+    if (typeof document === 'undefined' || document.getElementById(MOBILE_CONTROLS_STYLE_ID)) {
+        return;
+    }
+    const style = document.createElement('style');
+    style.id = MOBILE_CONTROLS_STYLE_ID;
+    style.textContent = MOBILE_CONTROLS_CSS;
+    document.head.appendChild(style);
+}

package/package.json

@@ -1,6 +1,70 @@
 {
   "name": "@gg-web-engine/mobile-controls",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.0.78",
+  "description": "On-screen touch controls for gg-web-engine: buttons, sticks, d-pads, look areas and tilt steering over the game canvas",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "scripts": {
+    "test": "jest",
+    "prettier-format": "prettier --config ../../.prettierrc 'src/**/*.ts' --write",
+    "prepublish": "rm -rf ./dist/ && tsc",
+    "build": "tsc"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/AndyGura/gg-web-engine.git"
+  },
+  "keywords": [
+    "game-development",
+    "game-engine",
+    "game-engine-framework",
+    "gamedev",
+    "touch-controls",
+    "virtual-joystick",
+    "mobile"
+  ],
+  "author": "AndyGura",
+  "license": "Apache-2.0",
+  "bugs": {
+    "url": "https://github.com/AndyGura/gg-web-engine/issues"
+  },
+  "homepage": "https://github.com/AndyGura/gg-web-engine#readme",
+  "dependencies": {},
+  "devDependencies": {
+    "@gg-web-engine/core": "0.0.78",
+    "@types/jest": "^30.0.0",
+    "@types/node": "^26.4.0",
+    "jest": "^30.5.0",
+    "jest-environment-jsdom": "^30.5.0",
+    "prettier": "^3.9.6",
+    "rxjs": "7.8.2",
+    "ts-jest": "^29.4.12",
+    "typescript": "~6.0.3"
+  },
+  "peerDependencies": {
+    "@gg-web-engine/core": "0.0.78",
+    "rxjs": "7.8.2"
+  },
+  "jest": {
+    "rootDir": ".",
+    "testRegex": "\\.spec\\.ts$",
+    "transform": {
+      "^.+\\.(t|j)s$": "ts-jest"
+    },
+    "moduleNameMapper": {
+      "@gg-web-engine/core": "<rootDir>/../core/src/index.ts"
+    },
+    "preset": "ts-jest/presets/default",
+    "collectCoverageFrom": [
+      "**/*.ts",
+      "!**/*.module.ts"
+    ],
+    "coveragePathIgnorePatterns": [
+      "<rootDir>/node_modules/",
+      "<rootDir>/dist/",
+      "<rootDir>/test/"
+    ],
+    "coverageDirectory": "./coverage",
+    "testEnvironment": "jsdom"
+  }
+}

package/src/controls/touch-axis-control.ts

@@ -0,0 +1,105 @@
+import { BehaviorSubject, Observable, takeUntil } from 'rxjs';
+import { distinctUntilChanged } from 'rxjs/operators';
+import { DirectionInput, KeyboardInput, MouseInput, Pnt2, Point2 } from '@gg-web-engine/core';
+import { TouchControl, TouchControlOptions } from './touch-control';
+
+/** The key codes a `TouchAxisControl` presses for each direction - see `bindKeys`. */
+export type AxisKeys = { up?: string; down?: string; left?: string; right?: string };
+
+/**
+ * The base of the controls that point in a direction (`TouchStick`, `TouchDPad`). `value$` is a
+ * vector with `x` from -1 (left) to 1 (right) and `y` from -1 (down) to 1 (up), never longer than 1 -
+ * the same convention as `DirectionInput.direction$`.
+ */
+export abstract class TouchAxisControl extends TouchControl {
+  private readonly _value$: BehaviorSubject<Point2> = new BehaviorSubject<Point2>(Pnt2.O);
+
+  /** Emits the current value on subscription and then every change; completes on `dispose`. */
+  public get value$(): Observable<Point2> {
+    return this._value$.pipe(
+      distinctUntilChanged((a, b) => a.x === b.x && a.y === b.y),
+      takeUntil(this.disposed$),
+    );
+  }
+
+  public get value(): Point2 {
+    return this._value$.getValue();
+  }
+
+  protected constructor(kind: string, options: TouchControlOptions) {
+    super(kind, options);
+  }
+
+  protected setValue(value: Point2): void {
+    if (!this.disposed) {
+      this._value$.next(value);
+    }
+  }
+
+  /**
+   * Feeds the control into `input` as an analog direction, which every built-in controller moving by
+   * direction keys (car, character, free camera) follows proportionally.
+   */
+  public bindDirection(input: DirectionInput): this {
+    this.value$.subscribe(v => input.setAnalogDirection(this, v.x === 0 && v.y === 0 ? null : v));
+    return this;
+  }
+
+  /**
+   * Makes the control hold a key of `keyboard` down per direction while it points that way further
+   * than `threshold` - for anything that only understands keys.
+   */
+  public bindKeys(keyboard: KeyboardInput, keys: AxisKeys, threshold: number = 0.5): this {
+    const held: { [code: string]: boolean } = {};
+    const set = (code: string | undefined, down: boolean) => {
+      if (!code || !!held[code] === down) {
+        return;
+      }
+      held[code] = down;
+      down ? keyboard.emulateKeyDown(code) : keyboard.emulateKeyUp(code);
+    };
+    this.value$.subscribe(v => {
+      set(keys.up, v.y > threshold);
+      set(keys.down, v.y < -threshold);
+      set(keys.left, v.x < -threshold);
+      set(keys.right, v.x > threshold);
+    });
+    return this;
+  }
+
+  /**
+   * Makes the control turn a view the way a mouse does: while it is deflected, `mouse` reports a
+   * continuous movement of up to `speed` pixels per second in that direction.
+   */
+  public bindLook(mouse: MouseInput, speed: number = 900): this {
+    let frame: number | null = null;
+    let last = 0;
+    const step = (time: number) => {
+      frame = null;
+      const { x, y } = this.value;
+      if (this.disposed || (x === 0 && y === 0)) {
+        return;
+      }
+      // the first frame's timestamp is its start time, which may precede the moment `last` was taken
+      const dt = Math.max(0, Math.min(100, time - last)) / 1000;
+      last = time;
+      // the pointer's y grows downwards, the control's upwards
+      mouse.emulateMove({ x: x * speed * dt, y: -y * speed * dt });
+      frame = requestAnimationFrame(step);
+    };
+    this.value$.subscribe({
+      next: v => {
+        if (frame === null && (v.x !== 0 || v.y !== 0)) {
+          last = performance.now();
+          frame = requestAnimationFrame(step);
+        }
+      },
+      complete: () => {
+        if (frame !== null) {
+          cancelAnimationFrame(frame);
+        }
+      },
+    });
+    return this;
+  }
+}