Skip to content

A fast 2D and 3D game engine — TypeScript SDK, C++/WebAssembly core, visual editor. Ship one project to web, desktop, WeChat MiniGames, playable ads, and native Android / iOS.

18.7 KB
Raw Blame
// SPDX-License-Identifier: Apache-2.0
// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
/**
 * @file    web.ts
 * @brief   Web platform adapter implementation
 */

import type {
    PlatformAdapter,
    PlatformRequestOptions,
    PlatformResponse,
    WasmInstantiateResult,
    InputEventCallbacks,
    GamepadSnapshot,
    ImageLoadResult,
    PlatformCanvas,
    PlatformImage,
    PlatformSocket,
    PlatformSocketOptions,
    PlatformTextEditor,
    PlatformScreenRecorder,
} from './types';
import { createWebTextEditor } from './webTextEditor';
import { WebAudioBackend } from '../audio/WebAudioBackend';
import type { PlatformAudioBackend } from '../audio/PlatformAudioBackend';
import { WebVideoBackend } from '../video/WebVideoBackend';
import type { PlatformVideoBackend } from '../video/PlatformVideoBackend';
import { GameSocket } from '../net/GameSocket';
import { createPrimaryPointer } from './primaryPointer';
import { createWebRecorder } from './webRecorder';
import { WebDevice } from '../device/web';
import { cacheEntryName } from './cacheEntryName';
import { webCacheAvailable, webCacheList, webCacheRead, webCacheRemove, webCacheWrite } from './webCacheStore';

const WHEEL_LINE_HEIGHT = 16;

// =============================================================================
// Web Platform Adapter
// =============================================================================

class WebPlatformAdapter implements PlatformAdapter {
    private device_: WebDevice | null = null;
    device(): WebDevice { return this.device_ ??= new WebDevice(); }
    readonly name = 'web' as const;
    private inputCleanup_: (() => void) | null = null;
    private recorder_: PlatformScreenRecorder | null | undefined;

    /** Resolved on first ask: the canvas exists by the time a game records. */
    screenRecorder(): PlatformScreenRecorder | null {
        if (this.recorder_ === undefined) this.recorder_ = createWebRecorder();
        return this.recorder_;
    }

    hasTouch(): boolean {
        return typeof navigator !== 'undefined'
            && ((navigator.maxTouchPoints ?? 0) > 0 || 'ontouchstart' in globalThis);
    }

    async fetch(url: string, options?: PlatformRequestOptions): Promise<PlatformResponse> {
        const response = await globalThis.fetch(url, {
            method: options?.method ?? 'GET',
            headers: options?.headers,
            body: options?.body,
        });

        const headers: Record<string, string> = {};
        response.headers.forEach((value, key) => {
            headers[key] = value;
        });

        return {
            ok: response.ok,
            status: response.status,
            statusText: response.statusText,
            headers,
            json: <T>() => response.json() as Promise<T>,
            text: () => response.text(),
            arrayBuffer: () => response.arrayBuffer(),
        };
    }

    async readFile(path: string): Promise<ArrayBuffer> {
        const response = await this.fetch(path);
        if (!response.ok) {
            throw new Error(`Failed to read file: ${path} (${response.status})`);
        }
        return response.arrayBuffer();
    }

    async readTextFile(path: string): Promise<string> {
        const response = await this.fetch(path);
        if (!response.ok) {
            throw new Error(`Failed to read file: ${path} (${response.status})`);
        }
        return response.text();
    }

    async fileExists(path: string): Promise<boolean> {
        try {
            const response = await globalThis.fetch(path);
            const ok = response.ok;
            response.body?.cancel();
            return ok;
        } catch {
            return false;
        }
    }

    async loadImagePixels(path: string): Promise<ImageLoadResult> {
        const img = this.createImage();
        await new Promise<void>((resolve, reject) => {
            img.crossOrigin = 'anonymous';
            img.onload = () => resolve();
            img.onerror = () => reject(new Error(`Failed to load image: ${path}`));
            img.src = path;
        });
        const cv = this.createCanvas(img.width, img.height);
        const ctx = cv.getContext('2d')!;
        ctx.drawImage(img, 0, 0);
        const id = ctx.getImageData(0, 0, img.width, img.height);
        return { width: img.width, height: img.height, pixels: new Uint8Array(id.data.buffer) };
    }

    async instantiateWasm(
        pathOrBuffer: string | ArrayBuffer,
        imports: WebAssembly.Imports
    ): Promise<WasmInstantiateResult> {
        let buffer: ArrayBuffer;

        if (typeof pathOrBuffer === 'string') {
            buffer = await this.readFile(pathOrBuffer);
        } else {
            buffer = pathOrBuffer;
        }

        const result = await WebAssembly.instantiate(buffer, imports);

        return {
            instance: result.instance,
            module: result.module,
        };
    }
    createImage(): PlatformImage {
        return new Image();
    }

    /** A hidden textarea: the browser's own field, borrowed for its keyboard
     *  layouts, IME and selection gestures (see platform/webTextEditor.ts). */
    createTextEditor(): PlatformTextEditor | null {
        return createWebTextEditor();
    }

    /** Hand a shipped font to the browser's font stack, which is what Canvas2D
     *  resolves `ctx.font` families against. `document.fonts` is the only route:
     *  a file on disk (or behind `estella://`) is invisible to Canvas2D until a
     *  FontFace for it is added to the document. */
    async registerFont(family: string, bytes: ArrayBuffer): Promise<void> {
        if (typeof FontFace === 'undefined' || typeof document === 'undefined') return;
        const face = new FontFace(family, bytes);
        await face.load();
        // `FontFaceSet.add` predates the lib.dom typing we compile against.
        (document.fonts as unknown as { add(f: FontFace): void }).add(face);
    }

    createCanvas(width: number, height: number): PlatformCanvas {
        let canvas: HTMLCanvasElement | OffscreenCanvas;
        if (typeof OffscreenCanvas !== 'undefined') {
            canvas = new OffscreenCanvas(width, height);
        } else {
            canvas = document.createElement('canvas');
        }
        canvas.width = width;
        canvas.height = height;
        return canvas;
    }

    now(): number {
        return performance.now();
    }

    bindInputEvents(callbacks: InputEventCallbacks, target?: unknown): void {
        if (this.inputCleanup_) {
            this.inputCleanup_();
            this.inputCleanup_ = null;
        }

        const el = (target as HTMLElement) ?? document.querySelector('canvas') ?? document.body;

        const heldKeys = new Set<string>();
        const heldButtons = new Set<number>();
        const heldTouches = new Set<number>();
        const onKeyDown = (e: Event) => {
            const key = e as KeyboardEvent;
            const target = key.target instanceof HTMLElement ? key.target : null;
            // Host forms keep typing/Tab; the engine's own hidden editor still routes Tab.
            if (target?.closest('input, textarea, select, button, a[href], [contenteditable]')
                && target.dataset.estellaTextEditor !== 'true') return;
            if (key.isComposing || key.keyCode === 229) return;
            if ((key.ctrlKey || key.metaKey || key.altKey) && ['Tab', 'Enter', 'Space'].includes(key.code)) return;
            heldKeys.add(key.code);
            if (callbacks.onKeyDown(key.code) === true) key.preventDefault();
        };
        const onKeyUp = (e: Event) => {
            const code = (e as KeyboardEvent).code;
            if (heldKeys.delete(code)) callbacks.onKeyUp(code);
        };
        const onBlur = () => {
            for (const code of heldKeys) callbacks.onKeyUp(code);
            heldKeys.clear();
            for (const button of heldButtons) callbacks.onPointerUp(button);
            heldButtons.clear();
            for (const id of heldTouches) pointer.cancel(id);
            heldTouches.clear();
            callbacks.onInputCancel?.();
        };
        const onVisibilityChange = () => { if (document.hidden) onBlur(); };
        const onMouseMove = (e: Event) => {
            const me = e as MouseEvent;
            callbacks.onPointerMove(me.offsetX, me.offsetY, me.movementX, me.movementY);
        };
        const onMouseDown = (e: Event) => {
            const me = e as MouseEvent;
            heldButtons.add(me.button);
            callbacks.onPointerDown(me.button, me.offsetX, me.offsetY);
        };
        const onMouseUp = (e: Event) => {
            const button = (e as MouseEvent).button;
            if (heldButtons.delete(button)) callbacks.onPointerUp(button);
        };
        const pointer = createPrimaryPointer(callbacks);

        const onTouchStart = (e: Event) => {
            e.preventDefault();
            const te = e as TouchEvent;
            const rect = (el as HTMLElement).getBoundingClientRect();
            for (let i = 0; i < te.changedTouches.length; i++) {
                const touch = te.changedTouches[i];
                heldTouches.add(touch.identifier);
                pointer.start(touch.identifier, touch.clientX - rect.left, touch.clientY - rect.top);
            }
        };
        const onTouchMove = (e: Event) => {
            e.preventDefault();
            const te = e as TouchEvent;
            const rect = (el as HTMLElement).getBoundingClientRect();
            for (let i = 0; i < te.changedTouches.length; i++) {
                const touch = te.changedTouches[i];
                pointer.move(touch.identifier, touch.clientX - rect.left, touch.clientY - rect.top);
            }
        };
        const onTouchEnd = (e: Event) => {
            e.preventDefault();
            const te = e as TouchEvent;
            for (let i = 0; i < te.changedTouches.length; i++) {
                const id = te.changedTouches[i].identifier;
                if (heldTouches.delete(id)) pointer.end(id);
            }
        };
        const onTouchCancel = (e: Event) => {
            const te = e as TouchEvent;
            for (let i = 0; i < te.changedTouches.length; i++) {
                const id = te.changedTouches[i].identifier;
                if (heldTouches.delete(id)) pointer.cancel(id);
            }
        };
        const onWheel = (e: Event) => {
            const we = e as WheelEvent;
            let dx = we.deltaX;
            let dy = we.deltaY;
            if (we.deltaMode === 1) {
                dx *= WHEEL_LINE_HEIGHT;
                dy *= WHEEL_LINE_HEIGHT;
            } else if (we.deltaMode === 2) {
                dx *= window.innerWidth;
                dy *= window.innerHeight;
            }
            callbacks.onWheel(dx, dy);
        };

        window.addEventListener('blur', onBlur);
        document.addEventListener('visibilitychange', onVisibilityChange);
        document.addEventListener('keydown', onKeyDown);
        document.addEventListener('keyup', onKeyUp);
        el.addEventListener('mousemove', onMouseMove);
        el.addEventListener('mousedown', onMouseDown);
        document.addEventListener('mouseup', onMouseUp);
        el.addEventListener('touchstart', onTouchStart, { passive: false });
        el.addEventListener('touchmove', onTouchMove, { passive: false });
        el.addEventListener('touchend', onTouchEnd, { passive: false });
        el.addEventListener('touchcancel', onTouchCancel);
        el.addEventListener('wheel', onWheel);

        this.inputCleanup_ = () => {
            window.removeEventListener('blur', onBlur);
            document.removeEventListener('visibilitychange', onVisibilityChange);
            onBlur();
            document.removeEventListener('keydown', onKeyDown);
            document.removeEventListener('keyup', onKeyUp);
            el.removeEventListener('mousemove', onMouseMove);
            el.removeEventListener('mousedown', onMouseDown);
            document.removeEventListener('mouseup', onMouseUp);
            el.removeEventListener('touchstart', onTouchStart);
            el.removeEventListener('touchmove', onTouchMove);
            el.removeEventListener('touchend', onTouchEnd);
            el.removeEventListener('touchcancel', onTouchCancel);
            el.removeEventListener('wheel', onWheel);
        };
    }

    unbindInputEvents(): void {
        if (this.inputCleanup_) {
            this.inputCleanup_();
            this.inputCleanup_ = null;
        }
    }

    pollGamepads(): GamepadSnapshot[] {
        const nav = typeof navigator !== 'undefined' ? navigator : undefined;
        if (!nav || typeof nav.getGamepads !== 'function') return [];
        const out: GamepadSnapshot[] = [];
        for (const gp of nav.getGamepads()) {
            if (!gp) continue; // navigator.getGamepads() is a sparse array (null slots)
            out.push({
                index: gp.index,
                connected: gp.connected,
                buttons: gp.buttons.map((b) => b.value),
                axes: gp.axes.slice(),
                mapping: gp.mapping,
            });
        }
        return out;
    }

    createAudioBackend(): PlatformAudioBackend {
        return new WebAudioBackend();
    }

    createVideoBackend(): PlatformVideoBackend {
        return new WebVideoBackend();
    }

    createSocket(options: PlatformSocketOptions): PlatformSocket {
        return new GameSocket(options);
    }

    // The content cache, in IndexedDB (webCacheStore.ts): what a page makes and would make again each visit, and what a hot
    // update downloads, kept under the cache's own names.
    hasCacheStorage(): boolean { return webCacheAvailable(); }
    canManageCache(): boolean { return webCacheAvailable(); }
    readCacheFile(key: string): Promise<ArrayBuffer | null> { return webCacheRead(cacheEntryName(key)); }
    writeCacheFile(key: string, bytes: ArrayBuffer): Promise<void> { return webCacheWrite(cacheEntryName(key), bytes); }
    listCacheFiles(): Promise<{ name: string; size: number; lastAccess: number }[]> { return webCacheList(); }
    removeCacheFile(name: string): Promise<void> {
        if (!/^[0-9a-f]{16}$/.test(name)) throw Error('invalid cache entry');
        return webCacheRemove(name);
    }

    getStorageItem(key: string): string | null {
        return localStorage.getItem(key);
    }

    setStorageItem(key: string, value: string): void {
        localStorage.setItem(key, value);
    }

    removeStorageItem(key: string): void {
        localStorage.removeItem(key);
    }

    devicePixelRatio(): number {
        return typeof window !== 'undefined' ? (window.devicePixelRatio || 1) : 1;
    }

    deviceName(): string {
        return typeof navigator !== 'undefined' ? browserDeviceName(navigator.userAgent) : '';
    }

    isHandheld(): boolean {
        return typeof navigator !== 'undefined' && browserIsHandheld(navigator.userAgent, navigator.maxTouchPoints ?? 0);
    }

    deviceQualityInfo(): { memoryGB?: number; cores?: number } {
        if (typeof navigator === 'undefined') return {};
        return { memoryGB: (navigator as Navigator & { deviceMemory?: number }).deviceMemory,
            cores: navigator.hardwareConcurrency };
    }

    /**
     * Both ways an error reaches the browser with nobody holding it.
     *
     * `error` carries the thrown value on the event; `unhandledrejection`
     * carries the rejection reason, which is the more common one in practice —
     * a promise chain in game code with no `.catch` fails completely silently
     * otherwise. Neither is prevented: this observes, and the browser still
     * logs to the console the way the developer expects.
     */
    onUnhandledError(callback: (error: unknown) => void): () => void {
        if (typeof window === 'undefined') return () => {};
        const onError = (e: ErrorEvent): void => { callback(e.error ?? e.message); };
        const onRejection = (e: PromiseRejectionEvent): void => { callback(e.reason); };
        window.addEventListener('error', onError);
        window.addEventListener('unhandledrejection', onRejection);
        return () => {
            window.removeEventListener('error', onError);
            window.removeEventListener('unhandledrejection', onRejection);
        };
    }

    /**
     * Context loss, without needing to be told which canvas.
     *
     * `webglcontextlost` does not bubble, so a listener on `window` looks like
     * it could not work — but a non-bubbling event still travels the CAPTURE
     * phase down to its target, and `window` is the first stop. One listener
     * therefore sees every canvas on the page, including one the engine did not
     * create, and the plugin needs no canvas handed to it.
     */
    onContextLost(callback: () => void): () => void {
        if (typeof window === 'undefined') return () => {};
        const onLost = (e: Event): void => {
            // Without this the browser's default action is to abandon the context
            // permanently: `webglcontextrestored` never fires, and no amount of
            // recovery code downstream gets a chance to matter.
            e.preventDefault();
            callback();
        };
        window.addEventListener('webglcontextlost', onLost, true);
        return () => window.removeEventListener('webglcontextlost', onLost, true);
    }

    clearStorage(prefix: string): void {
        const toRemove: string[] = [];
        for (let i = 0; i < localStorage.length; i++) {
            const k = localStorage.key(i);
            if (k !== null && k.startsWith(prefix)) {
                toRemove.push(k);
            }
        }
        for (const k of toRemove) {
            localStorage.removeItem(k);
        }
    }
}

// =============================================================================
// Export Singleton
// =============================================================================

export const webAdapter = new WebPlatformAdapter();

/** A browser and the system it runs on, from its user agent. Chrome on Android
 *  no longer names the phone's model there, so this is as close as a page gets. */
/** A phone or a tablet, by its browser. An iPad's Safari says it is a Mac by default; only its touch screen tells them apart. */
export function browserIsHandheld(ua: string, touchPoints: number): boolean {
    return /Android|iPhone|iPad|iPod/.test(ua) || (/Macintosh/.test(ua) && touchPoints > 1);
}

export function browserDeviceName(ua: string): string {
    const system = /Android/.test(ua) ? 'Android'
        : /iPhone/.test(ua) ? 'iPhone'
        : /iPad/.test(ua) ? 'iPad'
        : /Mac OS X/.test(ua) ? 'Mac'
        : /Windows/.test(ua) ? 'Windows'
        : /Linux/.test(ua) ? 'Linux' : '';
    const browser = /Electron\//.test(ua) ? 'Electron'
        : /Edg\//.test(ua) ? 'Edge'
        : /Firefox\//.test(ua) ? 'Firefox'
        : /Chrome\//.test(ua) ? 'Chrome'
        : /Safari\//.test(ua) ? 'Safari' : '';
    return [browser, system].filter(Boolean).join(' · ');
}