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

package/src/controls/touch-button.ts

@@ -0,0 +1,136 @@
+import { BehaviorSubject, Observable, skip, takeUntil } from 'rxjs';
+import { distinctUntilChanged, filter } from 'rxjs/operators';
+import { AnalogDirection, DirectionInput, KeyboardInput } from '@gg-web-engine/core';
+import { TouchControl, TouchControlOptions } from './touch-control';
+
+export type TouchButtonOptions = TouchControlOptions & {
+  /** What the button shows: markup (an inline SVG, plain text) or a DOM node. */
+  content?: string | Node;
+  /**
+   * `'hold'` (default): pressed while a finger is on it. `'toggle'`: every tap flips it, for an
+   * action that would otherwise need a finger parked on the button (sprint, crouch).
+   */
+  mode?: 'hold' | 'toggle';
+};
+
+/**
+ * An on-screen button. Read it through `pressed$`, or bind it to what a key already does with
+ * `bindKey`, so anything an app maps to its keyboard gets a touch button without further code.
+ */
+export class TouchButton extends TouchControl {
+  public readonly mode: 'hold' | 'toggle';
+
+  private readonly _pressed$: BehaviorSubject<boolean> = new BehaviorSubject<boolean>(false);
+  private _pressed: boolean = false;
+  private emitting: boolean = false;
+  private disposeRequested: boolean = false;
+
+  /** Emits the current state on subscription and then every change; completes on `dispose`. */
+  public get pressed$(): Observable<boolean> {
+    return this._pressed$.pipe(distinctUntilChanged(), takeUntil(this.disposed$));
+  }
+
+  public get pressed(): boolean {
+    return this._pressed;
+  }
+
+  /** Settable, e.g. to bring a toggle button in line with a state that changed by other means. */
+  public set pressed(value: boolean) {
+    if (this.disposed || value === this._pressed) {
+      return;
+    }
+    this._pressed = value;
+    this.element.classList.toggle('gg-mc-active', value);
+    this.element.setAttribute('aria-pressed', `${value}`);
+    if (this.emitting) {
+      // set from within a subscriber: the loop below delivers it once every subscriber has seen
+      // the change being emitted, so all of them get the changes in the same order
+      return;
+    }
+    this.emitting = true;
+    try {
+      while (this._pressed$.getValue() !== this._pressed) {
+        this._pressed$.next(this._pressed);
+      }
+    } finally {
+      this.emitting = false;
+    }
+    if (this.disposeRequested) {
+      super.dispose();
+    }
+  }
+
+  constructor(options: TouchButtonOptions = {}) {
+    super('button', options);
+    this.mode = options.mode || 'hold';
+    this.element.setAttribute('role', 'button');
+    this.setContent(options.content ?? '');
+  }
+
+  public setContent(content: string | Node): void {
+    if (typeof content === 'string') {
+      this.element.innerHTML = content;
+    } else {
+      this.element.replaceChildren(content);
+    }
+  }
+
+  /**
+   * Makes the button act as the key `code` of `keyboard`: pressing it is that key going down,
+   * releasing it the key going up.
+   */
+  public bindKey(keyboard: KeyboardInput, code: string): this {
+    this.changes$.subscribe(pressed => (pressed ? keyboard.emulateKeyDown(code) : keyboard.emulateKeyUp(code)));
+    return this;
+  }
+
+  /**
+   * Makes the button push `input` in a direction while pressed, e.g. `{ x: -1 }` for "left".
+   */
+  public bindDirection(input: DirectionInput, value: AnalogDirection): this {
+    this.changes$.subscribe(pressed => input.setAnalogDirection(this, pressed ? value : null));
+    return this;
+  }
+
+  /** Calls `callback` every time the button becomes pressed. */
+  public onPress(callback: () => void): this {
+    this.changes$.pipe(filter(pressed => pressed)).subscribe(() => callback());
+    return this;
+  }
+
+  /** Calls `callback` every time the button stops being pressed. */
+  public onRelease(callback: () => void): this {
+    this.changes$.pipe(filter(pressed => !pressed)).subscribe(() => callback());
+    return this;
+  }
+
+  public reset(): void {
+    super.reset();
+    this.pressed = false;
+  }
+
+  public dispose(): void {
+    if (this.emitting) {
+      // disposed from within a subscriber: the release has to reach every subscriber first
+      this.disposeRequested = true;
+      this.reset();
+      return;
+    }
+    super.dispose();
+  }
+
+  /** `pressed$` without the value it replays on subscription. */
+  private get changes$(): Observable<boolean> {
+    return this.pressed$.pipe(skip(1));
+  }
+
+  protected onPointerStart(): void {
+    this.pressed = this.mode === 'toggle' ? !this.pressed : true;
+  }
+
+  protected onPointerEnd(): void {
+    if (this.mode === 'hold') {
+      this.pressed = false;
+    }
+  }
+}

package/src/controls/touch-control.ts

@@ -0,0 +1,204 @@
+import { Subject } from 'rxjs';
+
+/**
+ * Where a control sits inside the overlay and how big it is. A number is a multiple of the overlay's
+ * `--gg-mc-unit` (an edge offset also keeps clear of the device's safe-area inset on that side); a
+ * string is used as a CSS value as is. Leave `width`/`height` out to keep the size the stylesheet
+ * gives that kind of control.
+ */
+export type ControlPlacement = {
+  left?: number | string;
+  right?: number | string;
+  top?: number | string;
+  bottom?: number | string;
+  width?: number | string;
+  height?: number | string;
+};
+
+export type TouchControlOptions = {
+  /**
+   * Identifies the control within its layout. Becomes the element's `gg-mc-id-<id>` class and
+   * `data-gg-mc` attribute, for styling one control from CSS.
+   */
+  id?: string;
+  placement?: ControlPlacement;
+  /** Extra CSS class names for the element, space-separated. */
+  className?: string;
+  /** Accessible name of the control. */
+  label?: string;
+};
+
+const EDGES = ['left', 'right', 'top', 'bottom'] as const;
+
+/**
+ * Sets a control element's inline position/size from a `ControlPlacement`.
+ */
+export function applyControlPlacement(element: HTMLElement, placement: ControlPlacement): void {
+  for (const edge of EDGES) {
+    const value = placement[edge];
+    if (value !== undefined) {
+      element.style.setProperty(
+        edge,
+        typeof value === 'number' ? `calc(var(--gg-mc-unit) * ${value} + env(safe-area-inset-${edge}, 0px))` : value,
+      );
+    }
+  }
+  for (const dimension of ['width', 'height'] as const) {
+    const value = placement[dimension];
+    if (value !== undefined) {
+      element.style.setProperty(dimension, typeof value === 'number' ? `calc(var(--gg-mc-unit) * ${value})` : value);
+    }
+  }
+}
+
+/**
+ * The base of every on-screen control: owns one DOM element and follows one pointer on it at a time.
+ * A control is plain DOM with no dependency on a world, so it works inside a `MobileControls` overlay
+ * and equally in an app's own markup - append `element` anywhere.
+ *
+ * A pointer that goes down on the control is captured by it and never reaches the elements below
+ * (the game canvas, a `MouseInput` listening on the window).
+ */
+export abstract class TouchControl {
+  public readonly element: HTMLElement;
+  public readonly id: string | undefined;
+
+  protected readonly disposed$: Subject<void> = new Subject<void>();
+  private activePointerId: number | null = null;
+  private _disposed: boolean = false;
+
+  public get disposed(): boolean {
+    return this._disposed;
+  }
+
+  /** Whether a pointer is currently down on the control. */
+  public get touched(): boolean {
+    return this.activePointerId !== null;
+  }
+
+  public get visible(): boolean {
+    return !this.element.hidden;
+  }
+
+  /**
+   * Takes the control off the screen (and back) without disposing it, for an action that is not
+   * available at the moment. Hiding releases whatever the control holds.
+   */
+  public set visible(value: boolean) {
+    if (!value) {
+      this.reset();
+    }
+    this.element.hidden = !value;
+  }
+
+  /** Moves/resizes the control; edges and sizes left out of `placement` stay as they are. */
+  public place(placement: ControlPlacement): void {
+    applyControlPlacement(this.element, placement);
+  }
+
+  protected constructor(kind: string, options: TouchControlOptions) {
+    this.id = options.id;
+    this.element = document.createElement('div');
+    this.element.className = `gg-mc-control gg-mc-${kind}`;
+    if (options.id) {
+      this.element.classList.add(`gg-mc-id-${options.id}`);
+      this.element.dataset.ggMc = options.id;
+    }
+    if (options.className) {
+      this.element.classList.add(...options.className.split(/\s+/).filter(x => !!x));
+    }
+    if (options.label) {
+      this.element.setAttribute('aria-label', options.label);
+    }
+    if (options.placement) {
+      applyControlPlacement(this.element, options.placement);
+    }
+    this.handlePointerDown = this.handlePointerDown.bind(this);
+    this.handlePointerMove = this.handlePointerMove.bind(this);
+    this.handlePointerEnd = this.handlePointerEnd.bind(this);
+    this.element.addEventListener('pointerdown', this.handlePointerDown);
+    this.element.addEventListener('pointermove', this.handlePointerMove);
+    this.element.addEventListener('pointerup', this.handlePointerEnd);
+    this.element.addEventListener('pointercancel', this.handlePointerEnd);
+    this.element.addEventListener('lostpointercapture', this.handlePointerEnd);
+    this.element.addEventListener('contextmenu', e => e.preventDefault());
+    // stops the long-press text selection/magnifier of iOS, which `touch-action` does not cover
+    this.element.addEventListener('touchstart', e => e.preventDefault(), { passive: false });
+  }
+
+  /**
+   * Returns the control to its untouched state, releasing whatever it holds (a pressed button, a
+   * deflected stick). A latched toggle button is released too.
+   */
+  public reset(): void {
+    if (this.activePointerId !== null) {
+      this.releaseCapture(this.activePointerId);
+      this.activePointerId = null;
+      this.onPointerEnd(null);
+    }
+  }
+
+  /**
+   * Resets the control, completes its observables (ending every binding made through it) and removes
+   * its element from the document.
+   */
+  public dispose(): void {
+    if (this._disposed) {
+      return;
+    }
+    this.reset();
+    this._disposed = true;
+    this.disposed$.next();
+    this.disposed$.complete();
+    this.element.remove();
+  }
+
+  protected abstract onPointerStart(event: PointerEvent): void;
+
+  protected onPointerMove(event: PointerEvent): void {}
+
+  /** `event` is `null` when the control was reset rather than released by the pointer. */
+  protected abstract onPointerEnd(event: PointerEvent | null): void;
+
+  private handlePointerDown(event: PointerEvent): void {
+    event.preventDefault();
+    event.stopPropagation();
+    if (this.activePointerId !== null || (event.pointerType === 'mouse' && event.button !== 0)) {
+      return;
+    }
+    this.activePointerId = event.pointerId;
+    try {
+      this.element.setPointerCapture(event.pointerId);
+    } catch (err) {
+      // not capturable (a synthetic event, a pointer already gone): the control still works while
+      // the pointer stays over it
+    }
+    this.onPointerStart(event);
+  }
+
+  private handlePointerMove(event: PointerEvent): void {
+    event.stopPropagation();
+    if (event.pointerId === this.activePointerId) {
+      event.preventDefault();
+      this.onPointerMove(event);
+    }
+  }
+
+  private handlePointerEnd(event: PointerEvent): void {
+    event.stopPropagation();
+    if (event.pointerId !== this.activePointerId) {
+      return;
+    }
+    this.activePointerId = null;
+    this.releaseCapture(event.pointerId);
+    this.onPointerEnd(event);
+  }
+
+  private releaseCapture(pointerId: number): void {
+    try {
+      this.element.releasePointerCapture(pointerId);
+    } catch (err) {
+      // was not captured
+    }
+  }
+}

package/src/controls/touch-dpad.ts

@@ -0,0 +1,78 @@
+import { Pnt2 } from '@gg-web-engine/core';
+import { TouchControlOptions } from './touch-control';
+import { TouchAxisControl } from './touch-axis-control';
+import { MobileControlsIcons } from '../icons';
+
+export type TouchDPadOptions = TouchControlOptions & {
+  /** Whether two neighboring directions can be held at once. `true` by default. */
+  diagonals?: boolean;
+  /** What each arm shows: markup or a DOM node. Arrows by default. */
+  content?: { up?: string | Node; down?: string | Node; left?: string | Node; right?: string | Node };
+};
+
+const ARMS = ['up', 'down', 'left', 'right'] as const;
+
+/**
+ * An on-screen directional pad: four arms read as one control, so a thumb slides from one direction
+ * to another without lifting. Each axis of its value is -1, 0 or 1.
+ */
+export class TouchDPad extends TouchAxisControl {
+  public readonly diagonals: boolean;
+
+  private readonly arms: { [arm in (typeof ARMS)[number]]: HTMLElement };
+
+  constructor(options: TouchDPadOptions = {}) {
+    super('dpad', options);
+    this.diagonals = options.diagonals ?? true;
+    this.arms = {} as any;
+    for (const arm of ARMS) {
+      const element = document.createElement('div');
+      element.className = `gg-mc-dpad-arm gg-mc-dpad-arm--${arm}`;
+      const content = options.content?.[arm] ?? MobileControlsIcons[arm];
+      if (typeof content === 'string') {
+        element.innerHTML = content;
+      } else {
+        element.appendChild(content);
+      }
+      this.arms[arm] = element;
+      this.element.appendChild(element);
+    }
+  }
+
+  protected onPointerStart(event: PointerEvent): void {
+    this.update(event);
+  }
+
+  protected onPointerMove(event: PointerEvent): void {
+    this.update(event);
+  }
+
+  protected onPointerEnd(): void {
+    this.apply(0, 0);
+  }
+
+  private update(event: PointerEvent): void {
+    const rect = this.element.getBoundingClientRect();
+    const radius = rect.width / 2 || 50;
+    const offset = {
+      x: (event.clientX - (rect.left + rect.width / 2)) / radius,
+      y: (event.clientY - (rect.top + rect.height / 2)) / radius,
+    };
+    if (Pnt2.len(offset) < 0.18) {
+      this.apply(0, 0);
+      return;
+    }
+    // split the circle into 8 sectors (4 without diagonals) and take the one the pointer is in
+    const sectors = this.diagonals ? 8 : 4;
+    const angle = (Math.round(Math.atan2(-offset.y, offset.x) / ((Math.PI * 2) / sectors)) * Math.PI * 2) / sectors;
+    this.apply(Math.round(Math.cos(angle)), Math.round(Math.sin(angle)));
+  }
+
+  private apply(x: number, y: number): void {
+    this.arms.up.classList.toggle('gg-mc-active', y > 0);
+    this.arms.down.classList.toggle('gg-mc-active', y < 0);
+    this.arms.left.classList.toggle('gg-mc-active', x < 0);
+    this.arms.right.classList.toggle('gg-mc-active', x > 0);
+    this.setValue({ x: x === 0 ? 0 : x, y: y === 0 ? 0 : y });
+  }
+}

package/src/controls/touch-look-area.ts

@@ -0,0 +1,78 @@
+import { Observable, Subject, takeUntil } from 'rxjs';
+import { MouseInput, Point2 } from '@gg-web-engine/core';
+import { TouchControl, TouchControlOptions } from './touch-control';
+
+export type TouchLookAreaOptions = TouchControlOptions & {
+  /** How far, in pixels, a touch may move and still count as a tap. 10 by default. */
+  tapDistance?: number;
+  /** How long, in milliseconds, a touch may last and still count as a tap. 250 by default. */
+  tapDuration?: number;
+};
+
+/**
+ * An invisible area that reports how a finger drags across it - the touch counterpart of moving the
+ * mouse to look around. Fills the whole overlay unless placed; put it before the other controls, so
+ * they stay on top of it.
+ */
+export class TouchLookArea extends TouchControl {
+  private readonly _delta$: Subject<Point2> = new Subject<Point2>();
+  private readonly _tap$: Subject<Point2> = new Subject<Point2>();
+  private readonly tapDistance: number;
+  private readonly tapDuration: number;
+  private last: Point2 = { x: 0, y: 0 };
+  private start: { x: number; y: number; time: number; moved: boolean } | null = null;
+
+  /** The movement of the dragging finger since its previous report, in pixels. */
+  public get delta$(): Observable<Point2> {
+    return this._delta$.pipe(takeUntil(this.disposed$));
+  }
+
+  /** A short touch that did not turn into a drag, with its client position. */
+  public get tap$(): Observable<Point2> {
+    return this._tap$.pipe(takeUntil(this.disposed$));
+  }
+
+  constructor(options: TouchLookAreaOptions = {}) {
+    super('look-area', options);
+    this.tapDistance = options.tapDistance ?? 10;
+    this.tapDuration = options.tapDuration ?? 250;
+    if (!options.placement) {
+      this.element.style.inset = '0';
+    }
+  }
+
+  /**
+   * Makes dragging over the area turn a view the way moving the mouse does: every drag is reported
+   * by `mouse` as a movement, multiplied by `sensitivity`.
+   */
+  public bindMouse(mouse: MouseInput, sensitivity: number = 1): this {
+    this.delta$.subscribe(delta => mouse.emulateMove({ x: delta.x * sensitivity, y: delta.y * sensitivity }));
+    return this;
+  }
+
+  protected onPointerStart(event: PointerEvent): void {
+    this.last = { x: event.clientX, y: event.clientY };
+    this.start = { x: event.clientX, y: event.clientY, time: event.timeStamp, moved: false };
+  }
+
+  protected onPointerMove(event: PointerEvent): void {
+    const delta = { x: event.clientX - this.last.x, y: event.clientY - this.last.y };
+    this.last = { x: event.clientX, y: event.clientY };
+    if (this.start && Math.hypot(event.clientX - this.start.x, event.clientY - this.start.y) > this.tapDistance) {
+      this.start.moved = true;
+    }
+    if (delta.x !== 0 || delta.y !== 0) {
+      this._delta$.next(delta);
+    }
+  }
+
+  protected onPointerEnd(event: PointerEvent | null): void {
+    const start = this.start;
+    this.start = null;
+    if (event && event.type === 'pointerup' && start && !start.moved) {
+      if (event.timeStamp - start.time <= this.tapDuration) {
+        this._tap$.next({ x: event.clientX, y: event.clientY });
+      }
+    }
+  }
+}

package/src/controls/touch-stick.ts

@@ -0,0 +1,100 @@
+import { Pnt2 } from '@gg-web-engine/core';
+import { TouchControlOptions } from './touch-control';
+import { TouchAxisControl } from './touch-axis-control';
+
+export type TouchStickOptions = TouchControlOptions & {
+  /**
+   * `'fixed'` (default): the stick stays where it is placed. `'floating'`: the control is a touch
+   * zone (give it a `placement` with a size), and the stick appears under the finger wherever the
+   * zone is touched, so the thumb never has to find it.
+   */
+  mode?: 'fixed' | 'floating';
+  /** Which axes the stick moves along. `'both'` by default. */
+  axes?: 'both' | 'x' | 'y';
+  /** The fraction of the travel around the center that reads as zero. 0.12 by default. */
+  deadzone?: number;
+  /**
+   * How far the knob travels from the center at full deflection, in pixels. By default 36% of the
+   * rendered width of the base.
+   */
+  travel?: number;
+};
+
+/**
+ * An on-screen analog stick.
+ */
+export class TouchStick extends TouchAxisControl {
+  public readonly mode: 'fixed' | 'floating';
+  public readonly axes: 'both' | 'x' | 'y';
+  public readonly deadzone: number;
+
+  private readonly base: HTMLElement;
+  private readonly knob: HTMLElement;
+  private readonly travelOption: number | undefined;
+  private center = Pnt2.O;
+  private travel: number = 1;
+
+  constructor(options: TouchStickOptions = {}) {
+    super('stick', options);
+    this.mode = options.mode || 'fixed';
+    this.axes = options.axes || 'both';
+    this.deadzone = options.deadzone ?? 0.12;
+    this.travelOption = options.travel;
+    this.element.classList.add(`gg-mc-stick--${this.mode}`);
+    this.base = document.createElement('div');
+    this.base.className = 'gg-mc-stick-base';
+    this.knob = document.createElement('div');
+    this.knob.className = 'gg-mc-stick-knob';
+    this.base.appendChild(this.knob);
+    this.element.appendChild(this.base);
+  }
+
+  protected onPointerStart(event: PointerEvent): void {
+    this.element.classList.add('gg-mc-active');
+    if (this.mode === 'floating') {
+      const zone = this.element.getBoundingClientRect();
+      this.base.style.left = `${event.clientX - zone.left}px`;
+      this.base.style.top = `${event.clientY - zone.top}px`;
+      this.center = { x: event.clientX, y: event.clientY };
+    }
+    const rect = this.base.getBoundingClientRect();
+    if (this.mode === 'fixed') {
+      this.center = { x: rect.left + rect.width / 2, y: rect.top + rect.height / 2 };
+    }
+    this.travel = this.travelOption ?? (rect.width * 0.36 || 50);
+    this.update(event);
+  }
+
+  protected onPointerMove(event: PointerEvent): void {
+    this.update(event);
+  }
+
+  protected onPointerEnd(): void {
+    this.element.classList.remove('gg-mc-active');
+    this.base.style.left = '';
+    this.base.style.top = '';
+    this.knob.style.transform = '';
+    this.setValue(Pnt2.O);
+  }
+
+  private update(event: PointerEvent): void {
+    let offset = { x: (event.clientX - this.center.x) / this.travel, y: (event.clientY - this.center.y) / this.travel };
+    if (this.axes === 'x') {
+      offset.y = 0;
+    } else if (this.axes === 'y') {
+      offset.x = 0;
+    }
+    const length = Pnt2.len(offset);
+    if (length > 1) {
+      offset = Pnt2.scalarMult(offset, 1 / length);
+    }
+    this.knob.style.transform = `translate(-50%, -50%) translate(${offset.x * this.travel}px, ${offset.y * this.travel}px)`;
+    if (length <= this.deadzone) {
+      this.setValue(Pnt2.O);
+      return;
+    }
+    // rescaled so the value starts from 0 right outside the deadzone instead of jumping to it
+    const scale = (Math.min(1, length) - this.deadzone) / (1 - this.deadzone) / Math.min(1, length);
+    this.setValue({ x: offset.x * scale, y: offset.y === 0 ? 0 : -offset.y * scale });
+  }
+}

package/src/icons.ts

@@ -0,0 +1,23 @@
+const svg = (body: string) => `<svg viewBox="0 0 24 24" aria-hidden="true">${body}</svg>`;
+
+/**
+ * The built-in icons, as inline SVG markup drawn with `currentColor`. Pass any of them (or any other
+ * markup, or a DOM node) as a `TouchButton`'s `content`.
+ */
+export const MobileControlsIcons = {
+  left: svg('<path d="M15 5l-7 7 7 7"/>'),
+  right: svg('<path d="M9 5l7 7-7 7"/>'),
+  up: svg('<path d="M5 15l7-7 7 7"/>'),
+  down: svg('<path d="M5 9l7 7 7-7"/>'),
+  accelerate: svg('<path d="M6 12l6-6 6 6M6 19l6-6 6 6"/>'),
+  brake: svg('<path d="M6 5l6 6 6-6M6 12l6 6 6-6"/>'),
+  handbrake: svg(
+    '<circle cx="12" cy="12" r="6"/><path d="M4.5 6a10 10 0 0 0 0 12M19.5 6a10 10 0 0 1 0 12M10.5 15V9h1.75a1.75 1.75 0 0 1 0 3.5H10.5"/>',
+  ),
+  plus: svg('<path d="M12 5v14M5 12h14"/>'),
+  minus: svg('<path d="M5 12h14"/>'),
+  jump: svg('<path d="M12 16V4M7 9l5-5 5 5M5 20h14"/>'),
+  crouch: svg('<path d="M12 4v12M7 11l5 5 5-5M5 20h14"/>'),
+  run: svg('<path d="M5 6l6 6-6 6M13 6l6 6-6 6"/>'),
+  view: svg('<path d="M2 12s3.5-7 10-7 10 7 10 7-3.5 7-10 7S2 12 2 12z"/><circle cx="12" cy="12" r="3"/>'),
+};

package/src/index.ts

@@ -0,0 +1,15 @@
+export * from './controls/touch-control';
+export * from './controls/touch-button';
+export * from './controls/touch-axis-control';
+export * from './controls/touch-stick';
+export * from './controls/touch-dpad';
+export * from './controls/touch-look-area';
+export * from './inputs/tilt.input';
+export * from './layouts/car.layout';
+export * from './layouts/character.layout';
+export * from './layouts/character-2d.layout';
+export * from './layouts/free-camera.layout';
+export * from './icons';
+export * from './styles';
+export * from './mobile-controls-layout';
+export * from './mobile-controls.entity';