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

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

@@ -0,0 +1,15 @@
+import { PlayerCharacterController2d } from '@gg-web-engine/core';
+import { 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 declare function character2dLayout(options?: Character2dLayoutOptions): MobileControlsLayoutFactory<PlayerCharacterController2d<any>>;

package/dist/layouts/character-2d.layout.js

@@ -0,0 +1,60 @@
+import { TouchButton } from '../controls/touch-button';
+import { TouchStick } from '../controls/touch-stick';
+import { MobileControlsIcons } from '../icons';
+import { LayoutBuilder } from '../mobile-controls-layout';
+/**
+ * The built-in layout for `PlayerCharacterController2d`: left/right on the left, actions on the
+ * right.
+ */
+export function character2dLayout(options = {}) {
+    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', () => {
+            var _a;
+            return new TouchButton({
+                id: 'crouch',
+                label: 'Crouch',
+                mode: ((_a = controller.character) === null || _a === void 0 ? void 0 : _a.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/dist/layouts/character.layout.d.ts

@@ -0,0 +1,25 @@
+import { PlayerCharacterController } from '@gg-web-engine/core';
+import { 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 declare function characterLayout(options?: CharacterLayoutOptions): MobileControlsLayoutFactory<PlayerCharacterController<any>>;

package/dist/layouts/character.layout.js

@@ -0,0 +1,87 @@
+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 } from '../mobile-controls-layout';
+/**
+ * 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 = {}) {
+    return (controller, context) => {
+        var _a;
+        const b = new LayoutBuilder(options);
+        const look = (_a = options.look) !== null && _a !== void 0 ? _a : 'drag';
+        if (look === 'drag') {
+            b.add('look', () => {
+                var _a;
+                return new TouchLookArea({
+                    id: 'look',
+                    placement: b.placement('look', { left: '0', top: '0', width: '100%', height: '100%' }),
+                }).bindMouse(controller.mouseInput, (_a = options.lookSensitivity) !== null && _a !== void 0 ? _a : 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', () => {
+                var _a;
+                return new TouchStick({
+                    id: 'look-stick',
+                    label: 'Look',
+                    placement: b.placement('look-stick', { right: 4, bottom: 3 }),
+                }).bindLook(controller.mouseInput, 900 * ((_a = options.lookSensitivity) !== null && _a !== void 0 ? _a : 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', () => {
+            var _a;
+            return 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: ((_a = controller.character) === null || _a === void 0 ? void 0 : _a.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/dist/layouts/free-camera.layout.d.ts

@@ -0,0 +1,16 @@
+import { FreeCameraController } from '@gg-web-engine/core';
+import { 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 declare function freeCameraLayout(options?: FreeCameraLayoutOptions): MobileControlsLayoutFactory<FreeCameraController>;

package/dist/layouts/free-camera.layout.js

@@ -0,0 +1,73 @@
+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 } from '../mobile-controls-layout';
+/**
+ * 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 = {}) {
+    return (controller, context) => {
+        var _a;
+        const b = new LayoutBuilder(options);
+        const look = (_a = options.look) !== null && _a !== void 0 ? _a : 'drag';
+        if (look === 'drag') {
+            b.add('look', () => {
+                var _a;
+                return new TouchLookArea({
+                    id: 'look',
+                    placement: b.placement('look', { left: '0', top: '0', width: '100%', height: '100%' }),
+                }).bindMouse(controller.mouseInput, (_a = options.lookSensitivity) !== null && _a !== void 0 ? _a : 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', () => {
+                var _a;
+                return new TouchStick({
+                    id: 'look-stick',
+                    label: 'Look',
+                    placement: b.placement('look-stick', { right: 4, bottom: 3 }),
+                }).bindLook(controller.mouseInput, 900 * ((_a = options.lookSensitivity) !== null && _a !== void 0 ? _a : 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/dist/mobile-controls-layout.d.ts

@@ -0,0 +1,54 @@
+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 declare class LayoutBuilder<T extends IEntity, Id extends string> {
+    private readonly customization;
+    readonly result: MobileControlsLayoutItem[];
+    constructor(customization: LayoutCustomization<T, Id>);
+    /** Whether the control with this id is to be built at all. */
+    has(id: Id): boolean;
+    placement(id: Id, defaults: ControlPlacement): ControlPlacement;
+    icon(id: Id, defaults: string): string | Node;
+    /** Adds the control `create` makes, unless the app hid it. */
+    add(id: Id, create: () => TouchControl): void;
+    finish(controller: T, context: MobileControlsLayoutContext): MobileControlsLayoutItem[];
+}

package/dist/mobile-controls-layout.js

@@ -0,0 +1,47 @@
+/**
+ * Applies a `LayoutCustomization` while a built-in layout is put together.
+ */
+export class LayoutBuilder {
+    constructor(customization) {
+        this.customization = customization;
+        this.result = [];
+    }
+    /** Whether the control with this id is to be built at all. */
+    has(id) {
+        return !(this.customization.hide || []).includes(id);
+    }
+    placement(id, defaults) {
+        var _a;
+        const custom = (_a = this.customization.placements) === null || _a === void 0 ? void 0 : _a[id];
+        if (!custom) {
+            return defaults;
+        }
+        // an edge given by the app takes over from the opposite default one instead of stretching between
+        const merged = Object.assign(Object.assign({}, 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, defaults) {
+        var _a, _b;
+        return (_b = (_a = this.customization.icons) === null || _a === void 0 ? void 0 : _a[id]) !== null && _b !== void 0 ? _b : defaults;
+    }
+    /** Adds the control `create` makes, unless the app hid it. */
+    add(id, create) {
+        if (this.has(id)) {
+            this.result.push(create());
+        }
+    }
+    finish(controller, context) {
+        if (this.customization.extra) {
+            this.result.push(...this.customization.extra(controller, context));
+        }
+        return this.result;
+    }
+}

package/dist/mobile-controls.entity.d.ts

@@ -0,0 +1,112 @@
+import { GgWorld, IEntity, TickOrder } from '@gg-web-engine/core';
+import { TouchControl } from './controls/touch-control';
+import { CarLayoutOptions } from './layouts/car.layout';
+import { Character2dLayoutOptions } from './layouts/character-2d.layout';
+import { CharacterLayoutOptions } from './layouts/character.layout';
+import { FreeCameraLayoutOptions } from './layouts/free-camera.layout';
+import { MobileControlsLayoutFactory } from './mobile-controls-layout';
+/**
+ * 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 declare function isTouchFirstDevice(): boolean;
+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;
+};
+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 declare class MobileControls extends IEntity {
+    static readonly entityTypeName: string;
+    readonly tickOrder = TickOrder.INPUT_CONTROLLERS;
+    readonly options: MobileControlsOptions;
+    /** The overlay element. Created up front, attached to the page only while the overlay is shown. */
+    readonly element: HTMLElement;
+    private readonly registrations;
+    private readonly tracked;
+    private readonly layouts;
+    private readonly ownControls;
+    private _enabled;
+    private _visible;
+    get enabled(): boolean | 'auto';
+    /** See `MobileControlsOptions.enabled`. */
+    set enabled(value: boolean | 'auto');
+    get visible(): boolean;
+    /**
+     * 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: boolean);
+    /** Whether the overlay is on the page right now. */
+    get shown(): boolean;
+    /** The controllers that currently have their controls on screen. */
+    get activeControllers(): IEntity[];
+    constructor(options?: Partial<MobileControlsOptions>);
+    /**
+     * 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<T extends IEntity>(controllerClass: ControllerClass<T>, factory: MobileControlsLayoutFactory<T> | null): void;
+    /**
+     * Adds controls that stay on screen whichever controller is active, on top of the layouts.
+     */
+    addControls(...controls: TouchControl[]): void;
+    /** Removes controls added by `addControls` and disposes them. */
+    removeControls(...controls: TouchControl[]): void;
+    /**
+     * 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?: IEntity): void;
+    onSpawned(world: GgWorld<any, any>): void;
+    onRemoved(): void;
+    dispose(): void;
+    /** Returns every control on screen to its untouched state. */
+    releaseAll(): void;
+    private findFactory;
+    private rescan;
+    private sync;
+    private disposeLayout;
+}
+export {};