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.
TypeScript 2d-game-engine3d3d-game-engineandroidcppecsgame-editorgame-enginegamedeviostypescriptwebassemblywebglwebgpuwechat-minigame
// 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(' · ');
}