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

package/src/inputs/tilt.input.ts

@@ -0,0 +1,128 @@
+import { BehaviorSubject, Observable } from 'rxjs';
+import { distinctUntilChanged } from 'rxjs/operators';
+import { IInput } from '@gg-web-engine/core';
+
+export type TiltInputOptions = {
+  /** The tilt, in degrees, that reads as full deflection. 30 by default. */
+  maxAngle: number;
+  /** The tilt, in degrees, around level that reads as zero. 2 by default. */
+  deadzone: number;
+  /** Flips the sign of the output. `false` by default. */
+  invert: boolean;
+};
+
+const DEFAULT_OPTIONS: TiltInputOptions = { maxAngle: 30, deadzone: 2, invert: false };
+
+/**
+ * An input reading how the device is tilted sideways, like a steering wheel: `value$` goes from -1
+ * (the left edge of the screen is the lower one) to 1 (the right edge is), whichever way the screen
+ * is currently rotated and whether the device is held upright or lies flat.
+ *
+ * Orientation data is available to pages served over https (or from localhost) only; anywhere else
+ * `permission$` reports `'denied'`.
+ *
+ * Some browsers (iOS Safari) only hand out orientation data after the user allowed it in a prompt
+ * that has to be opened from a user gesture. `start()` takes care of that: when a permission is
+ * needed, it asks on the next tap anywhere on the page and starts reporting once granted.
+ * `permission$` tells how that went, for an app that wants to explain itself first or to fall back
+ * to another control when denied.
+ */
+export class TiltInput extends IInput {
+  /** Whether the browser reports device orientation at all. */
+  static isSupported(): boolean {
+    return typeof window !== 'undefined' && 'DeviceOrientationEvent' in window;
+  }
+
+  public readonly options: TiltInputOptions;
+
+  private readonly _value$: BehaviorSubject<number> = new BehaviorSubject<number>(0);
+  private readonly _permission$: BehaviorSubject<'unknown' | 'granted' | 'denied'> = new BehaviorSubject<
+    'unknown' | 'granted' | 'denied'
+  >('unknown');
+
+  /** Emits the current value on subscription and then every change. */
+  public get value$(): Observable<number> {
+    return this._value$.pipe(distinctUntilChanged());
+  }
+
+  public get value(): number {
+    return this._value$.getValue();
+  }
+
+  public get permission$(): Observable<'unknown' | 'granted' | 'denied'> {
+    return this._permission$.pipe(distinctUntilChanged());
+  }
+
+  constructor(options: Partial<TiltInputOptions> = {}) {
+    super();
+    this.options = { ...DEFAULT_OPTIONS, ...options };
+    this.handleOrientation = this.handleOrientation.bind(this);
+    this.requestPermission = this.requestPermission.bind(this);
+  }
+
+  protected startInternal(): void {
+    if (!TiltInput.isSupported()) {
+      this._permission$.next('denied');
+      return;
+    }
+    if (window.isSecureContext === false) {
+      // browsers hand out orientation data to pages served over https (or from localhost) only, and
+      // on other pages stay silent instead of failing
+      console.warn('[TiltInput] device orientation is not available: the page is not served over https');
+      this._permission$.next('denied');
+      return;
+    }
+    const needsPermission = typeof (DeviceOrientationEvent as any).requestPermission === 'function';
+    if (needsPermission && this._permission$.getValue() !== 'granted') {
+      // the prompt only opens from a handler of a finished gesture, not from a touch going down
+      window.addEventListener('touchend', this.requestPermission);
+      window.addEventListener('click', this.requestPermission);
+    } else {
+      this._permission$.next('granted');
+      window.addEventListener('deviceorientation', this.handleOrientation);
+    }
+  }
+
+  protected stopInternal(): void {
+    window.removeEventListener('touchend', this.requestPermission);
+    window.removeEventListener('click', this.requestPermission);
+    window.removeEventListener('deviceorientation', this.handleOrientation);
+    this._value$.next(0);
+  }
+
+  private requestPermission(): void {
+    window.removeEventListener('touchend', this.requestPermission);
+    window.removeEventListener('click', this.requestPermission);
+    (DeviceOrientationEvent as any)
+      .requestPermission()
+      .then((state: string) => {
+        this._permission$.next(state === 'granted' ? 'granted' : 'denied');
+        if (state === 'granted' && this.running) {
+          window.addEventListener('deviceorientation', this.handleOrientation);
+        }
+      })
+      .catch(() => this._permission$.next('denied'));
+  }
+
+  private handleOrientation(event: DeviceOrientationEvent): void {
+    if (event.beta === null || event.gamma === null) {
+      return;
+    }
+    const beta = (event.beta * Math.PI) / 180;
+    const gamma = (event.gamma * Math.PI) / 180;
+    // the direction of gravity within the plane of the screen, in the device's own (portrait) axes:
+    // x towards its right edge, y towards its top edge
+    const gravityX = Math.cos(beta) * Math.sin(gamma);
+    const gravityY = -Math.sin(beta);
+    // how much of it points towards the right edge of the screen as currently rotated
+    const screenAngle = ((screen.orientation?.angle ?? (window as any).orientation ?? 0) * Math.PI) / 180;
+    const right = gravityX * Math.cos(screenAngle) - gravityY * Math.sin(screenAngle);
+    const degrees = (Math.asin(Math.max(-1, Math.min(1, right))) * 180) / Math.PI;
+    const { maxAngle, deadzone, invert } = this.options;
+    let value = 0;
+    if (Math.abs(degrees) > deadzone) {
+      value = Math.sign(degrees) * Math.min(1, (Math.abs(degrees) - deadzone) / (maxAngle - deadzone));
+    }
+    this._value$.next(invert && value !== 0 ? -value : value);
+  }
+}

package/src/layouts/car.layout.ts

@@ -0,0 +1,139 @@
+import { CarHandlingController, GgCarHandlingController } from '@gg-web-engine/core';
+import { TouchButton } from '../controls/touch-button';
+import { TouchStick } from '../controls/touch-stick';
+import { MobileControlsIcons } from '../icons';
+import { TiltInput, TiltInputOptions } from '../inputs/tilt.input';
+import { LayoutBuilder, LayoutCustomization, MobileControlsLayoutFactory } from '../mobile-controls-layout';
+
+export type CarLayoutControlId =
+  'steer-left' | 'steer-right' | 'steer-stick' | 'accelerate' | 'brake' | 'handbrake' | 'gear-up' | 'gear-down';
+
+/** The controllers `carLayout` builds controls for. */
+export type CarLayoutController = GgCarHandlingController | CarHandlingController;
+
+export type CarLayoutOptions = LayoutCustomization<CarLayoutController, CarLayoutControlId> & {
+  /**
+   * How the car is steered: `'buttons'` (default) - a left and a right button, `'stick'` - an analog
+   * stick moving sideways, `'tilt'` - by tilting the device like a steering wheel (see `TiltInput`).
+   */
+  steering?: 'buttons' | 'stick' | 'tilt';
+  /** Options of the `TiltInput` behind `steering: 'tilt'`. */
+  tilt?: Partial<TiltInputOptions>;
+  /** Whether there is a handbrake button (`GgCarHandlingController` only). `true` by default. */
+  handbrake?: boolean;
+  /**
+   * Whether there are gear up/down buttons (`GgCarHandlingController` only). `'auto'`
+   * (default) shows them when the driver has to
+   * shift: gear switching is enabled on the controller, and the car has a manual gearbox or the
+   * controller does not pick reverse by itself (`autoReverse`).
+   */
+  gears?: boolean | 'auto';
+};
+
+/**
+ * The built-in layout for the car controllers: steering on the left, pedals on the right. For a
+ * `GgCarHandlingController` also the handbrake and the gears; a bare
+ * `CarHandlingController` (the steering/throttle half, usable with any vehicle) gets the
+ * steering and the pedals alone.
+ */
+export function carLayout(options: CarLayoutOptions = {}): MobileControlsLayoutFactory<CarLayoutController> {
+  return (controller, context) => {
+    if (controller.parent instanceof GgCarHandlingController) {
+      // the half of a `GgCarHandlingController`, whose own layout already covers it
+      return [];
+    }
+    const b = new LayoutBuilder(options);
+    const ggCar = controller instanceof GgCarHandlingController ? controller : null;
+    const direction = (ggCar ? ggCar.carHandlingInput : (controller as CarHandlingController)).directionsInput;
+    const steering = options.steering || 'buttons';
+    if (steering === 'buttons') {
+      b.add('steer-left', () =>
+        new TouchButton({
+          id: 'steer-left',
+          label: 'Steer left',
+          content: b.icon('steer-left', MobileControlsIcons.left),
+          placement: b.placement('steer-left', { left: 4, bottom: 4, width: 10, height: 10 }),
+        }).bindDirection(direction, { x: -1 }),
+      );
+      b.add('steer-right', () =>
+        new TouchButton({
+          id: 'steer-right',
+          label: 'Steer right',
+          content: b.icon('steer-right', MobileControlsIcons.right),
+          placement: b.placement('steer-right', { left: 16, bottom: 4, width: 10, height: 10 }),
+        }).bindDirection(direction, { x: 1 }),
+      );
+    } else if (steering === 'stick') {
+      b.add('steer-stick', () =>
+        new TouchStick({
+          id: 'steer-stick',
+          label: 'Steering',
+          axes: 'x',
+          placement: b.placement('steer-stick', { left: 4, bottom: 3 }),
+        }).bindDirection(direction),
+      );
+    }
+    b.add('accelerate', () =>
+      new TouchButton({
+        id: 'accelerate',
+        label: 'Accelerate',
+        content: b.icon('accelerate', MobileControlsIcons.accelerate),
+        placement: b.placement('accelerate', { right: 4, bottom: 4, width: 10, height: 10 }),
+      }).bindDirection(direction, { y: 1 }),
+    );
+    b.add('brake', () =>
+      new TouchButton({
+        id: 'brake',
+        label: 'Brake',
+        content: b.icon('brake', MobileControlsIcons.brake),
+        placement: b.placement('brake', { right: 16, bottom: 4, width: 10, height: 10 }),
+      }).bindDirection(direction, { y: -1 }),
+    );
+    if (ggCar && (options.handbrake ?? true)) {
+      b.add('handbrake', () =>
+        new TouchButton({
+          id: 'handbrake',
+          label: 'Handbrake',
+          content: b.icon('handbrake', MobileControlsIcons.handbrake),
+          placement: b.placement('handbrake', { right: 5.5, bottom: 16, width: 7, height: 7 }),
+        }).bindKey(ggCar.keyboard, ggCar.options.handbrakeKey),
+      );
+    }
+    let gears = options.gears ?? 'auto';
+    if (ggCar && gears === 'auto') {
+      const isAutoGearbox = !!ggCar.car?.carProperties.transmission.isAuto;
+      gears = ggCar.switchingGearsEnabled && !(isAutoGearbox && ggCar.options.autoReverse);
+    }
+    if (ggCar && gears) {
+      b.add('gear-down', () =>
+        new TouchButton({
+          id: 'gear-down',
+          label: 'Gear down',
+          content: b.icon('gear-down', MobileControlsIcons.minus),
+          placement: b.placement('gear-down', { left: 5.5, bottom: 16, width: 7, height: 7 }),
+        }).bindKey(ggCar.keyboard, ggCar.options.gearUpDownKeys[1]),
+      );
+      b.add('gear-up', () =>
+        new TouchButton({
+          id: 'gear-up',
+          label: 'Gear up',
+          content: b.icon('gear-up', MobileControlsIcons.plus),
+          placement: b.placement('gear-up', { left: 17.5, bottom: 16, width: 7, height: 7 }),
+        }).bindKey(ggCar.keyboard, ggCar.options.gearUpDownKeys[0]),
+      );
+    }
+    if (steering === 'tilt') {
+      const tilt = new TiltInput(options.tilt);
+      const subscription = tilt.value$.subscribe(x => direction.setAnalogDirection(tilt, x === 0 ? null : { x }));
+      tilt.start();
+      b.result.push({
+        dispose: () => {
+          subscription.unsubscribe();
+          direction.setAnalogDirection(tilt, null);
+          tilt.stop();
+        },
+      });
+    }
+    return b.finish(controller, context);
+  };
+}

package/src/layouts/character-2d.layout.ts

@@ -0,0 +1,85 @@
+import { PlayerCharacterController2d } from '@gg-web-engine/core';
+import { TouchButton } from '../controls/touch-button';
+import { TouchStick } from '../controls/touch-stick';
+import { MobileControlsIcons } from '../icons';
+import { LayoutBuilder, LayoutCustomization, MobileControlsLayoutFactory } from '../mobile-controls-layout';
+
+export type Character2dLayoutControlId = 'move-left' | 'move-right' | 'move' | 'jump' | 'run' | 'crouch';
+
+export type Character2dLayoutOptions = LayoutCustomization<
+  PlayerCharacterController2d<any>,
+  Character2dLayoutControlId
+> & {
+  /**
+   * How the character is moved: `'buttons'` (default) - a left and a right button, `'stick'` - an
+   * analog stick moving sideways.
+   */
+  movement?: 'buttons' | 'stick';
+};
+
+/**
+ * The built-in layout for `PlayerCharacterController2d`: left/right on the left, actions on the
+ * right.
+ */
+export function character2dLayout(
+  options: Character2dLayoutOptions = {},
+): MobileControlsLayoutFactory<PlayerCharacterController2d<any>> {
+  return (controller, context) => {
+    const b = new LayoutBuilder(options);
+    const direction = controller.directionsInput;
+    if ((options.movement || 'buttons') === 'buttons') {
+      b.add('move-left', () =>
+        new TouchButton({
+          id: 'move-left',
+          label: 'Move left',
+          content: b.icon('move-left', MobileControlsIcons.left),
+          placement: b.placement('move-left', { left: 4, bottom: 4, width: 10, height: 10 }),
+        }).bindDirection(direction, { x: -1 }),
+      );
+      b.add('move-right', () =>
+        new TouchButton({
+          id: 'move-right',
+          label: 'Move right',
+          content: b.icon('move-right', MobileControlsIcons.right),
+          placement: b.placement('move-right', { left: 16, bottom: 4, width: 10, height: 10 }),
+        }).bindDirection(direction, { x: 1 }),
+      );
+    } else {
+      b.add('move', () =>
+        new TouchStick({
+          id: 'move',
+          label: 'Move',
+          axes: 'x',
+          placement: b.placement('move', { left: 4, bottom: 3 }),
+        }).bindDirection(direction),
+      );
+    }
+    b.add('jump', () =>
+      new TouchButton({
+        id: 'jump',
+        label: 'Jump',
+        content: b.icon('jump', MobileControlsIcons.jump),
+        placement: b.placement('jump', { right: 4, bottom: 4, width: 10, height: 10 }),
+      }).bindKey(controller.keyboard, controller.options.jumpKey),
+    );
+    b.add('run', () =>
+      new TouchButton({
+        id: 'run',
+        label: 'Run',
+        mode: 'toggle',
+        content: b.icon('run', MobileControlsIcons.run),
+        placement: b.placement('run', { right: 16, bottom: 4, width: 8, height: 8 }),
+      }).bindKey(controller.keyboard, controller.options.runKey),
+    );
+    b.add('crouch', () =>
+      new TouchButton({
+        id: 'crouch',
+        label: 'Crouch',
+        mode: controller.character?.options.crouchMode === 'toggle' ? 'hold' : 'toggle',
+        content: b.icon('crouch', MobileControlsIcons.crouch),
+        placement: b.placement('crouch', { right: 5, bottom: 16, width: 8, height: 8 }),
+      }).bindKey(controller.keyboard, controller.options.crouchKey),
+    );
+    return b.finish(controller, context);
+  };
+}

package/src/layouts/character.layout.ts

@@ -0,0 +1,125 @@
+import { PlayerCharacterController } from '@gg-web-engine/core';
+import { TouchButton } from '../controls/touch-button';
+import { TouchDPad } from '../controls/touch-dpad';
+import { TouchLookArea } from '../controls/touch-look-area';
+import { TouchStick } from '../controls/touch-stick';
+import { MobileControlsIcons } from '../icons';
+import { LayoutBuilder, LayoutCustomization, MobileControlsLayoutFactory } from '../mobile-controls-layout';
+
+export type CharacterLayoutControlId = 'look' | 'look-stick' | 'move' | 'jump' | 'run' | 'crouch' | 'view';
+
+export type CharacterLayoutOptions = LayoutCustomization<PlayerCharacterController<any>, CharacterLayoutControlId> & {
+  /**
+   * How the character is moved: `'stick'` (default) - an analog stick that appears under the left
+   * thumb wherever it lands, `'dpad'` - a directional pad in the corner.
+   */
+  movement?: 'stick' | 'dpad';
+  /**
+   * How the view is turned: `'drag'` (default) - by dragging anywhere the other controls are not,
+   * `'stick'` - with a second stick on the right, `false` - not by this layout.
+   */
+  look?: 'drag' | 'stick' | false;
+  /**
+   * Multiplies the turning: of a drag, on top of the controller's `mouseSensitivity` (3 by default,
+   * a finger covers much less distance than a mouse), or of the look stick's speed.
+   */
+  lookSensitivity?: number;
+};
+
+/**
+ * The built-in layout for `PlayerCharacterController`: movement on the left, actions on the right,
+ * looking around by dragging over the rest of the screen.
+ */
+export function characterLayout(
+  options: CharacterLayoutOptions = {},
+): MobileControlsLayoutFactory<PlayerCharacterController<any>> {
+  return (controller, context) => {
+    const b = new LayoutBuilder(options);
+    const look = options.look ?? 'drag';
+    if (look === 'drag') {
+      b.add('look', () =>
+        new TouchLookArea({
+          id: 'look',
+          placement: b.placement('look', { left: '0', top: '0', width: '100%', height: '100%' }),
+        }).bindMouse(controller.mouseInput, options.lookSensitivity ?? 3),
+      );
+    }
+    if ((options.movement || 'stick') === 'stick') {
+      b.add('move', () =>
+        new TouchStick({
+          id: 'move',
+          label: 'Move',
+          mode: 'floating',
+          placement: b.placement('move', { left: '0', bottom: '0', width: '45%', height: '75%' }),
+        }).bindDirection(controller.directionsInput),
+      );
+    } else {
+      b.add('move', () =>
+        new TouchDPad({
+          id: 'move',
+          label: 'Move',
+          placement: b.placement('move', { left: 4, bottom: 4 }),
+        }).bindDirection(controller.directionsInput),
+      );
+    }
+    // with a look stick in the corner the action buttons move into a row above it
+    const stick = look === 'stick';
+    if (stick) {
+      b.add('look-stick', () =>
+        new TouchStick({
+          id: 'look-stick',
+          label: 'Look',
+          placement: b.placement('look-stick', { right: 4, bottom: 3 }),
+        }).bindLook(controller.mouseInput, 900 * (options.lookSensitivity ?? 1)),
+      );
+    }
+    b.add('jump', () =>
+      new TouchButton({
+        id: 'jump',
+        label: 'Jump',
+        content: b.icon('jump', MobileControlsIcons.jump),
+        placement: b.placement(
+          'jump',
+          stick ? { right: 4, bottom: 20, width: 8, height: 8 } : { right: 4, bottom: 5, width: 10, height: 10 },
+        ),
+      }).bindKey(controller.keyboard, controller.options.jumpKey),
+    );
+    b.add('run', () =>
+      new TouchButton({
+        id: 'run',
+        label: 'Run',
+        mode: 'toggle',
+        content: b.icon('run', MobileControlsIcons.run),
+        placement: b.placement(
+          'run',
+          stick ? { right: 14, bottom: 20, width: 8, height: 8 } : { right: 16, bottom: 4, width: 8, height: 8 },
+        ),
+      }).bindKey(controller.keyboard, controller.options.runKey),
+    );
+    b.add('crouch', () =>
+      new TouchButton({
+        id: 'crouch',
+        label: 'Crouch',
+        // a crouch that lasts while its key is held gets a latching button instead of a parked finger
+        mode: controller.character?.options.crouchMode === 'toggle' ? 'hold' : 'toggle',
+        content: b.icon('crouch', MobileControlsIcons.crouch),
+        placement: b.placement(
+          'crouch',
+          stick ? { right: 24, bottom: 20, width: 8, height: 8 } : { right: 5, bottom: 17, width: 8, height: 8 },
+        ),
+      }).bindKey(controller.keyboard, controller.options.crouchKey),
+    );
+    const toggleViewKey = controller.options.toggleViewKey;
+    if (toggleViewKey) {
+      b.add('view', () =>
+        new TouchButton({
+          id: 'view',
+          label: 'Switch view',
+          content: b.icon('view', MobileControlsIcons.view),
+          placement: b.placement('view', { right: 4, top: 4, width: 6.5, height: 6.5 }),
+        }).bindKey(controller.keyboard, toggleViewKey),
+      );
+    }
+    return b.finish(controller, context);
+  };
+}

package/src/layouts/free-camera.layout.ts

@@ -0,0 +1,103 @@
+import { FreeCameraController } from '@gg-web-engine/core';
+import { TouchButton } from '../controls/touch-button';
+import { TouchDPad } from '../controls/touch-dpad';
+import { TouchLookArea } from '../controls/touch-look-area';
+import { TouchStick } from '../controls/touch-stick';
+import { MobileControlsIcons } from '../icons';
+import { LayoutBuilder, LayoutCustomization, MobileControlsLayoutFactory } from '../mobile-controls-layout';
+
+export type FreeCameraLayoutControlId = 'look' | 'look-stick' | 'move' | 'ascend' | 'descend' | 'boost';
+
+export type FreeCameraLayoutOptions = LayoutCustomization<FreeCameraController, FreeCameraLayoutControlId> & {
+  /** How the camera is moved - see `CharacterLayoutOptions.movement`. `'stick'` by default. */
+  movement?: 'stick' | 'dpad';
+  /** How the camera is turned - see `CharacterLayoutOptions.look`. `'drag'` by default. */
+  look?: 'drag' | 'stick' | false;
+  /** Multiplies the turning - see `CharacterLayoutOptions.lookSensitivity`. */
+  lookSensitivity?: number;
+};
+
+/**
+ * The built-in layout for `FreeCameraController`: flying on the left, up/down/boost on the right,
+ * looking around by dragging over the rest of the screen.
+ */
+export function freeCameraLayout(
+  options: FreeCameraLayoutOptions = {},
+): MobileControlsLayoutFactory<FreeCameraController> {
+  return (controller, context) => {
+    const b = new LayoutBuilder(options);
+    const look = options.look ?? 'drag';
+    if (look === 'drag') {
+      b.add('look', () =>
+        new TouchLookArea({
+          id: 'look',
+          placement: b.placement('look', { left: '0', top: '0', width: '100%', height: '100%' }),
+        }).bindMouse(controller.mouseInput, options.lookSensitivity ?? 3),
+      );
+    }
+    if ((options.movement || 'stick') === 'stick') {
+      b.add('move', () =>
+        new TouchStick({
+          id: 'move',
+          label: 'Move',
+          mode: 'floating',
+          placement: b.placement('move', { left: '0', bottom: '0', width: '45%', height: '75%' }),
+        }).bindDirection(controller.directionsInput),
+      );
+    } else {
+      b.add('move', () =>
+        new TouchDPad({
+          id: 'move',
+          label: 'Move',
+          placement: b.placement('move', { left: 4, bottom: 4 }),
+        }).bindDirection(controller.directionsInput),
+      );
+    }
+    const stick = look === 'stick';
+    if (stick) {
+      b.add('look-stick', () =>
+        new TouchStick({
+          id: 'look-stick',
+          label: 'Look',
+          placement: b.placement('look-stick', { right: 4, bottom: 3 }),
+        }).bindLook(controller.mouseInput, 900 * (options.lookSensitivity ?? 1)),
+      );
+    }
+    // the keys `FreeCameraController` moves up/down and boosts with are fixed
+    b.add('ascend', () =>
+      new TouchButton({
+        id: 'ascend',
+        label: 'Up',
+        content: b.icon('ascend', MobileControlsIcons.up),
+        placement: b.placement(
+          'ascend',
+          stick ? { right: 4, bottom: 20, width: 8, height: 8 } : { right: 4, bottom: 15, width: 9, height: 9 },
+        ),
+      }).bindKey(controller.keyboard, 'KeyE'),
+    );
+    b.add('descend', () =>
+      new TouchButton({
+        id: 'descend',
+        label: 'Down',
+        content: b.icon('descend', MobileControlsIcons.down),
+        placement: b.placement(
+          'descend',
+          stick ? { right: 14, bottom: 20, width: 8, height: 8 } : { right: 4, bottom: 4, width: 9, height: 9 },
+        ),
+      }).bindKey(controller.keyboard, 'KeyQ'),
+    );
+    b.add('boost', () =>
+      new TouchButton({
+        id: 'boost',
+        label: 'Boost',
+        mode: 'toggle',
+        content: b.icon('boost', MobileControlsIcons.run),
+        placement: b.placement(
+          'boost',
+          stick ? { right: 24, bottom: 20, width: 8, height: 8 } : { right: 15, bottom: 4, width: 8, height: 8 },
+        ),
+      }).bindKey(controller.keyboard, 'ShiftLeft'),
+    );
+    return b.finish(controller, context);
+  };
+}

package/src/mobile-controls-layout.ts

@@ -0,0 +1,86 @@
+import { GgWorld, IEntity } from '@gg-web-engine/core';
+import { ControlPlacement, TouchControl } from './controls/touch-control';
+import type { MobileControls } from './mobile-controls.entity';
+
+export type MobileControlsLayoutContext = {
+  world: GgWorld<any, any>;
+  /** The overlay the layout is built for. */
+  controls: MobileControls;
+};
+
+/**
+ * One piece of a layout: a `TouchControl`, or anything else that lives as long as the layout does (a
+ * `TiltInput` wired to the controller, a subscription) and is ended through `dispose`.
+ */
+export type MobileControlsLayoutItem = TouchControl | { dispose(): void };
+
+/**
+ * Builds the on-screen controls for one controller entity, already bound to it. Called every time
+ * the controller becomes active; the returned items are disposed when it stops being active or
+ * leaves the world. The controls are stacked in the returned order, the last one on top.
+ */
+export type MobileControlsLayoutFactory<T extends IEntity = IEntity> = (
+  controller: T,
+  context: MobileControlsLayoutContext,
+) => MobileControlsLayoutItem[];
+
+/**
+ * What every built-in layout lets an app adjust without replacing the layout. `Id` are the ids of
+ * the controls that layout can contain.
+ */
+export type LayoutCustomization<T extends IEntity, Id extends string> = {
+  /** Moves/resizes a control. Merged over that control's default placement, edge by edge. */
+  placements?: { [id in Id]?: ControlPlacement };
+  /** Replaces what a button shows: markup (an inline SVG, plain text) or a DOM node. */
+  icons?: { [id in Id]?: string | Node };
+  /** Leaves controls out of the layout. */
+  hide?: Id[];
+  /** Adds controls of the app's own to the layout. */
+  extra?: MobileControlsLayoutFactory<T>;
+};
+
+/**
+ * Applies a `LayoutCustomization` while a built-in layout is put together.
+ */
+export class LayoutBuilder<T extends IEntity, Id extends string> {
+  public readonly result: MobileControlsLayoutItem[] = [];
+
+  constructor(private readonly customization: LayoutCustomization<T, Id>) {}
+
+  /** Whether the control with this id is to be built at all. */
+  has(id: Id): boolean {
+    return !(this.customization.hide || []).includes(id);
+  }
+
+  placement(id: Id, defaults: ControlPlacement): ControlPlacement {
+    const custom = this.customization.placements?.[id];
+    if (!custom) {
+      return defaults;
+    }
+    // an edge given by the app takes over from the opposite default one instead of stretching between
+    const merged = { ...defaults, ...custom };
+    if (custom.left !== undefined && custom.right === undefined) delete merged.right;
+    if (custom.right !== undefined && custom.left === undefined) delete merged.left;
+    if (custom.top !== undefined && custom.bottom === undefined) delete merged.bottom;
+    if (custom.bottom !== undefined && custom.top === undefined) delete merged.top;
+    return merged;
+  }
+
+  icon(id: Id, defaults: string): string | Node {
+    return this.customization.icons?.[id] ?? defaults;
+  }
+
+  /** Adds the control `create` makes, unless the app hid it. */
+  add(id: Id, create: () => TouchControl): void {
+    if (this.has(id)) {
+      this.result.push(create());
+    }
+  }
+
+  finish(controller: T, context: MobileControlsLayoutContext): MobileControlsLayoutItem[] {
+    if (this.customization.extra) {
+      this.result.push(...this.customization.extra(controller, context));
+    }
+    return this.result;
+  }
+}