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

package/src/mobile-controls.entity.ts

@@ -0,0 +1,350 @@
+import { takeUntil } from 'rxjs';
+import {
+  CarHandlingController,
+  FreeCameraController,
+  GgCarHandlingController,
+  GgWorld,
+  IEntity,
+  PlayerCharacterController,
+  PlayerCharacterController2d,
+  TickOrder,
+} from '@gg-web-engine/core';
+import { TouchControl } from './controls/touch-control';
+import { carLayout, CarLayoutOptions } from './layouts/car.layout';
+import { character2dLayout, Character2dLayoutOptions } from './layouts/character-2d.layout';
+import { characterLayout, CharacterLayoutOptions } from './layouts/character.layout';
+import { freeCameraLayout, FreeCameraLayoutOptions } from './layouts/free-camera.layout';
+import { MobileControlsLayoutFactory, MobileControlsLayoutItem } from './mobile-controls-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(): boolean {
+  if (typeof window === 'undefined' || typeof navigator === 'undefined') {
+    return false;
+  }
+  if (typeof window.matchMedia === 'function') {
+    return window.matchMedia('(pointer: coarse)').matches;
+  }
+  return navigator.maxTouchPoints > 0;
+}
+
+export type MobileControlsOptions = {
+  /**
+   * `'auto'` (default): the overlay exists only on a touch-first device (`isTouchFirstDevice`).
+   * `true`: always, e.g. to try the controls with a mouse. `false`: never.
+   */
+  enabled: boolean | 'auto';
+  /**
+   * The element the overlay is added to. `null` (default) puts it on `document.body`, covering the
+   * viewport - right for a game filling the page. For a canvas that takes a part of the page, or one
+   * that enters fullscreen through the Fullscreen API, pass an element wrapping the canvas (it has to
+   * be positioned, e.g. `position: relative`): the overlay then covers exactly that element.
+   */
+  container: HTMLElement | null;
+  /** Extra CSS class names for the overlay element, e.g. one overriding its `--gg-mc-*` properties. */
+  className: string;
+  /** Whether to add the default stylesheet to the page. `true` by default. */
+  injectStyles: boolean;
+  /**
+   * Options of the built-in layout for `GgCarHandlingController` and a bare
+   * `CarHandlingController`, or `false` to have none.
+   */
+  car: CarLayoutOptions | false;
+  /** Options of the built-in layout for `PlayerCharacterController`, or `false` to have none. */
+  character: CharacterLayoutOptions | false;
+  /** Options of the built-in layout for `PlayerCharacterController2d`, or `false` to have none. */
+  character2d: Character2dLayoutOptions | false;
+  /** Options of the built-in layout for `FreeCameraController`, or `false` to have none. */
+  freeCamera: FreeCameraLayoutOptions | false;
+};
+
+const DEFAULT_OPTIONS: MobileControlsOptions = {
+  enabled: 'auto',
+  container: null,
+  className: '',
+  injectStyles: true,
+  car: {},
+  character: {},
+  character2d: {},
+  freeCamera: {},
+};
+
+type ControllerClass<T extends IEntity> = abstract new (...args: any[]) => T;
+
+/**
+ * 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 {
+  static readonly entityTypeName: string = 'MobileControls';
+  public readonly tickOrder = TickOrder.INPUT_CONTROLLERS;
+
+  public readonly options: MobileControlsOptions;
+
+  /** The overlay element. Created up front, attached to the page only while the overlay is shown. */
+  public readonly element: HTMLElement;
+
+  private readonly registrations: {
+    controllerClass: ControllerClass<any>;
+    factory: MobileControlsLayoutFactory<any>;
+  }[] = [];
+  private readonly tracked: Set<IEntity> = new Set<IEntity>();
+  private readonly layouts: Map<IEntity, MobileControlsLayoutItem[]> = new Map<IEntity, MobileControlsLayoutItem[]>();
+  private readonly ownControls: Set<TouchControl> = new Set<TouchControl>();
+  private _enabled: boolean | 'auto';
+  private _visible: boolean = true;
+
+  public get enabled(): boolean | 'auto' {
+    return this._enabled;
+  }
+
+  /** See `MobileControlsOptions.enabled`. */
+  public set enabled(value: boolean | 'auto') {
+    this._enabled = value;
+    this.sync();
+  }
+
+  public get visible(): boolean {
+    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.
+   */
+  public set visible(value: boolean) {
+    this._visible = value;
+    this.sync();
+  }
+
+  /** Whether the overlay is on the page right now. */
+  public get shown(): boolean {
+    return this.element.isConnected;
+  }
+
+  /** The controllers that currently have their controls on screen. */
+  public get activeControllers(): IEntity[] {
+    return [...this.layouts.keys()];
+  }
+
+  constructor(options: Partial<MobileControlsOptions> = {}) {
+    super();
+    this.options = { ...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.
+   */
+  public registerLayout<T extends IEntity>(
+    controllerClass: ControllerClass<T>,
+    factory: MobileControlsLayoutFactory<T> | null,
+  ): void {
+    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.
+   */
+  public addControls(...controls: TouchControl[]): void {
+    for (const control of controls) {
+      this.ownControls.add(control);
+      this.element.appendChild(control.element);
+    }
+  }
+
+  /** Removes controls added by `addControls` and disposes them. */
+  public removeControls(...controls: TouchControl[]): void {
+    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.
+   */
+  public refresh(controller?: IEntity): void {
+    for (const key of controller ? [controller] : [...this.layouts.keys()]) {
+      this.disposeLayout(key);
+    }
+    this.sync();
+  }
+
+  onSpawned(world: GgWorld<any, any>): void {
+    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(): void {
+    super.onRemoved();
+    window.removeEventListener('blur', this.releaseAll);
+    this.tracked.clear();
+    this.sync();
+  }
+
+  dispose(): void {
+    super.dispose();
+    for (const control of this.ownControls) {
+      control.dispose();
+    }
+    this.ownControls.clear();
+  }
+
+  /** Returns every control on screen to its untouched state. */
+  public releaseAll(): void {
+    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();
+    }
+  }
+
+  private findFactory(entity: IEntity): MobileControlsLayoutFactory<any> | null {
+    for (let i = this.registrations.length - 1; i >= 0; i--) {
+      if (entity instanceof this.registrations[i].controllerClass) {
+        return this.registrations[i].factory;
+      }
+    }
+    return null;
+  }
+
+  private rescan(): void {
+    this.tracked.clear();
+    const visit = (entity: IEntity) => {
+      if (this.findFactory(entity)) {
+        this.tracked.add(entity);
+      }
+      entity.children.forEach(visit);
+    };
+    (this.world?.children || []).forEach(visit);
+    for (const controller of [...this.layouts.keys()]) {
+      this.disposeLayout(controller);
+    }
+    this.sync();
+  }
+
+  private sync(): void {
+    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);
+          }
+        }
+      }
+    }
+  }
+
+  private disposeLayout(controller: IEntity): void {
+    const items = this.layouts.get(controller);
+    if (items) {
+      this.layouts.delete(controller);
+      for (const item of items) {
+        item.dispose();
+      }
+    }
+  }
+}

package/src/styles.ts

@@ -0,0 +1,160 @@
+/**
+ * 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(): void {
+  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/test/helpers.ts

@@ -0,0 +1,38 @@
+import { GgWorld } from '@gg-web-engine/core';
+
+export class TestWorld extends GgWorld<any, any> {
+  constructor() {
+    super({
+      visualScene: { init: async () => {}, dispose: () => {} } as any,
+      physicsWorld: { init: async () => {}, simulate: () => {}, dispose: () => {} } as any,
+    });
+  }
+
+  addPrimitiveRigidBody(): any {
+    return undefined;
+  }
+}
+
+export const tick = (world: GgWorld<any, any>, elapsed: number = 0, delta: number = 16) =>
+  (world.worldClock as any)._tick$.next([elapsed, delta]);
+
+/** Dispatches a touch pointer event; built on MouseEvent so it does not depend on jsdom's PointerEvent. */
+export const pointer = (
+  target: Element,
+  type: 'pointerdown' | 'pointermove' | 'pointerup' | 'pointercancel',
+  x: number = 0,
+  y: number = 0,
+  pointerId: number = 1,
+) => {
+  const event = new MouseEvent(type, { bubbles: true, cancelable: true, clientX: x, clientY: y });
+  Object.defineProperty(event, 'pointerId', { value: pointerId });
+  Object.defineProperty(event, 'pointerType', { value: 'touch' });
+  target.dispatchEvent(event);
+  return event;
+};
+
+/** Gives an element a layout box, which jsdom never computes. */
+export const setRect = (element: Element, left: number, top: number, width: number, height: number) => {
+  element.getBoundingClientRect = () =>
+    ({ left, top, width, height, right: left + width, bottom: top + height, x: left, y: top, toJSON: () => ({}) }) as DOMRect;
+};