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 bridge.ts
* @brief The contract a native host (embedded Dawn + JS engine on iOS/Android)
* injects so the existing TS SDK + wasm core runs unchanged — NOT a
* WebView. Every capability the engine needs from the OS is a method
* here; the {@link NativePlatformAdapter} adapts them to PlatformAdapter.
*
* Deliberately NOT on the bridge:
* - WASM instantiation — the host JS engine (JavaScriptCore / V8 / Hermes)
* provides the `WebAssembly` global; the adapter uses it directly, the
* same as the Node host.
* - The GPU render surface — it reaches the C++ renderer via a device
* handle (WebAppOptions), not through this adapter. Out of scope here.
*
* @beta Pre-1.0: the native host is unshipped; this contract will change as the
* shell (boot spike → full host) lands. Public via the `esengine/native` entry.
*/
import type {
GamepadSnapshot, ImageLoadResult, PlatformGlyph, PlatformGlyphRequest, PlatformRequestOptions,
} from '../types';
/**
* A single fetch result from the native http stack. The adapter wraps it into a
* {@link PlatformResponse}: provide `text` OR `arrayBuffer` (matching the request's
* responseType); the adapter derives the other on demand.
*/
export interface NativeFetchResult {
ok: boolean;
status: number;
statusText?: string;
headers?: Record<string, string>;
arrayBuffer?: ArrayBuffer;
text?: string;
}
/**
* The engine's input sink. The shell PUSHES events (native has no DOM event
* loop): touch coordinates are logical px, origin top-left. Keyboard is optional
* (most devices are touch-only). The adapter synthesizes the primary pointer from
* the first active touch, matching the web/mini-game adapters.
*/
export interface NativeInputListener {
onTouchStart(id: number, x: number, y: number): void;
onTouchMove(id: number, x: number, y: number): void;
onTouchEnd(id: number): void;
onTouchCancel(id: number): void;
/** A mouse or pen — separate from touch because it is separate on the web:
* a touch synthesizes the primary pointer, a mouse IS one and has a button
* (DOM order: 0 left, 1 middle, 2 right). */
onPointerDown(button: number, x: number, y: number): void;
onPointerMove(x: number, y: number): void;
onPointerUp(button: number): void;
/** Wheel delta in PIXELS, positive-down (the DOM `deltaMode: 0` contract). */
onWheel(deltaX: number, deltaY: number): void;
/** The DOM `KeyboardEvent.code` — the physical key, which is what the SDK's
* input maps are written against. NOT optional: it was, and the entry point
* that would have fed it was never written, so no native key ever arrived. */
onKeyDown(code: string): void;
onKeyUp(code: string): void;
}
/**
* The store's half of achievements, as the desktop host exposes it.
*
* `init` is separate from the rest because the app id lives in game.config.json,
* which the SDK reads — the host has no JSON parser and no reason to grow one.
*/
export interface NativeSteamBridge {
init(appId: number): boolean;
available(): boolean;
/** `{ id, name }`; the id is a STRING because 64 bits do not survive a double. */
identity(): { id: string; name: string };
unlock(id: string): boolean;
unlocked(id: string): boolean;
setStat(name: string, value: number): boolean;
getStat(name: string): number;
store(): boolean;
reset(): boolean;
/** Called when the store's overlay covers the game, and again when it stops.
* One subscriber: the host pushes to one entry point, and the services layer
* is what fans it out. */
onOverlay(listener: (covered: boolean) => void): void;
}
/** What the OS editing surface reports back. `state` carries the surface's whole
* value + selection (it is the owner while focused); `composing` is absent on a
* host that cannot tell whether an IME preedit is in flight. */
export type NativeTextEditorPush =
| {
kind: 'state';
value: string;
selectionStart: number;
selectionEnd: number;
composing?: boolean;
}
| { kind: 'submit' }
| { kind: 'cancel' };
/**
* The host's text-editing surface: the OS soft keyboard and its IME. Present only
* when the host bound it — a host without one omits `NativeBridge.textEditor`
* and editable fields render but do not type, the way a host without a sound
* device stays silent.
*
* `focus` opens the keyboard on the field's current value; `write` pushes an edit
* the app made (a programmatic setValue, a tap that moved the caret); everything
* the user does comes back through `subscribe`.
*/
export interface NativeTextEditorBridge {
focus(
value: string, selectionStart: number, selectionEnd: number,
multiline: boolean, maxLength: number, password: boolean,
): void;
blur(): void;
write(value: string, selectionStart: number, selectionEnd: number): void;
/** Returns an unsubscribe. */
subscribe(handler: (push: NativeTextEditorPush) => void): () => void;
}
/**
* The host's native audio engine, wrapped as a small object so {@link
* NativeAudioBackend} stays a thin adapter over it (mirroring the WeChat backend
* over InnerAudioContext). The engine owns decode + mixing + output natively —
* nothing per-sample runs in JS, which the no-JIT budget forbids. Present only
* when the host bound the audio primitives; a host without a sound device omits
* `NativeBridge.audio` and the audio system stays silent (the Null backend).
*
* A `bufferId` names a loaded clip; a `voiceId` names one playing instance of
* it. Both are non-negative host handles; a failed load or play returns null / -1.
*/
export interface NativeAudioBridge {
/** `bins` byte magnitudes of what is playing (0..Nyquist), or null when the
* host has no analyser / nothing has played. The device's AnalyserNode. */
spectrum?(bins: number): ArrayBuffer | null;
/**
* Register a clip from its (compressed) file bytes: decoded to PCM now, or —
* with `stream` — kept as the file and decoded by each voice as it plays.
* Returns the buffer handle, its length in seconds (0 when a streamed file does
* not say) and what stays resident in bytes, for the residency budget; null on
* decode failure. `streamed` is what the host did: one that cannot stream the
* file, or predates the argument, decodes it and leaves this unset.
*/
load(bytes: ArrayBuffer, stream?: boolean): { id: number; duration: number; bytes: number; streamed?: boolean } | null;
unload(bufferId: number): void;
/** Start a voice on a loaded buffer. Returns its voice id, or -1 if the buffer
* is unknown. */
/** @param loopStart seconds a looping voice comes back to; 0 is its start. A host older than this takes five arguments and loops from the start. */
/** @param start, end seconds in the decoded clip that it begins from and is over at (0 for end is its natural end): a clip the exporter re-encoded has silence before and after it. */
/** @param at a moment of the host's clock, as {@link time} gives it, that the voice begins on; 0 is now. Voices given the same one begin on the same sample. */
play(bufferId: number, volume: number, pan: number, loop: boolean, rate: number, loopStart?: number, start?: number, end?: number, at?: number): number;
/** The host's audio clock, in seconds. Absent on a host older than this, where voices begin as they are asked for. */
time?(): number;
stop(voiceId: number): void;
pause(voiceId: number): void;
resume(voiceId: number): void;
setVolume(voiceId: number, volume: number): void;
setPan(voiceId: number, pan: number): void;
setLoop(voiceId: number, loop: boolean): void;
setRate(voiceId: number, rate: number): void;
/** `{ playing, currentTime }` for a live voice, or null once it has ended (or
* was never known) — the SDK derives isPlaying / currentTime from it. */
voiceState(voiceId: number): { playing: boolean; currentTime: number } | null;
/** Pause / resume the whole device — the app going to background and back. */
suspendAll(): void;
resumeAll(): void;
/** Register the sink the host notifies when a voice ends on its own (pushed,
* like touch); returns an unsubscribe. */
onEnded(callback: (voiceId: number) => void): () => void;
}
/**
* The host's line to the app's own native code. Text both ways: the host carries
* a method name and JSON without knowing what either means (see channel.ts for
* the side that does).
*/
export interface NativeChannelBridge {
/** Whether anything answers to `method`. */
has(method: string): boolean;
/** Call `method` with JSON `args`. Resolves with the JSON it answered;
* rejects when nothing answers, or with the reason the native side gave. */
call(method: string, args: string): Promise<string>;
/** The sink for events native code raises on its own (pushed, like touch):
* the event's name and its JSON. Returns an unsubscribe. */
subscribe(handler: (name: string, payload: string) => void): () => void;
}
/**
* The host functions the native shell injects. Async where the call crosses to
* the OS (files, network, image decode); sync where the native API is sync
* (key-value storage). Textures take the pixel-decode path: the host decodes an
* image to RGBA via {@link NativeBridge.loadImagePixels} (there is no offscreen
* DOM canvas on native).
*/
export interface NativeBridge {
device?(): import('../../device/types').DeviceBackend;
/** Read a project-relative (packaged) file, or an absolute http(s) URL. */
readFile(path: string): Promise<ArrayBuffer>;
fileExists(path: string): Promise<boolean>;
fetch(url: string, options?: PlatformRequestOptions): Promise<NativeFetchResult>;
/** Decode an image to top-first RGBA (the Path-2 / createTextureFromPixels
* route the play realm and WeChat also use). */
loadImagePixels(path: string): Promise<ImageLoadResult>;
/** The app's own Java or Objective-C, by method name. Optional: a host built
* before the channel omits it, and the SDK then reports no native code. */
channel?: NativeChannelBridge;
/** Rasterize one glyph — the device's answer to the 2D canvas the browser
* path draws text on. Synchronous, because the dynamic glyph atlas fills
* cells during the frame that needs them. Optional: a host that has not
* bound its font stack omits it and `Text` draws nothing (the atlas treats
* a null the same as a canvas miss). See {@link PlatformAdapter.rasterizeGlyph}. */
rasterizeGlyph?(request: PlatformGlyphRequest): PlatformGlyph | null;
/** Persistent key-value store (NSUserDefaults / SharedPreferences). Sync,
* like localStorage / wx.*StorageSync. `storageKeys()` lets the adapter
* implement `clearStorage(prefix)` itself. */
getStorageItem(key: string): string | null;
setStorageItem(key: string, value: string): void;
removeStorageItem(key: string): void;
storageKeys(): string[];
/** Persistent content-addressed byte cache (hot-update offline store): the shell
* writes verified downloaded assets to disk and reads them back. Optional — a
* shell without on-disk caching omits both, and hot-updated assets simply refetch
* from the CDN. See {@link PlatformAdapter.readCacheFile}. */
readCacheFile?(key: string): Promise<ArrayBuffer | null>;
writeCacheFile?(key: string, bytes: ArrayBuffer): Promise<void>;
/** Register the engine's input sink; returns an unsubscribe. */
registerInput(listener: NativeInputListener): () => void;
/** The gamepads the shell can see, this frame. Polled rather than pushed,
* matching navigator.getGamepads(): a pad has a state, not events. Absent on
* a shell with no pads to report (a phone). */
pollGamepads?(): GamepadSnapshot[];
/** Size the host's own window, in design pixels. Absent where the app is given
* a screen instead of owning a window (a phone). */
setWindowSize?(width: number, height: number): void;
/** The Steam client, on a shell that can have one (desktop). Absent everywhere
* else, and present-but-unavailable when no client is running. */
steam?: NativeSteamBridge;
devicePixelRatio(): number;
/** Live content insets in surface pixels. Optional for older native hosts. */
safeAreaInsets?(): { top: number; bottom: number; left: number; right: number };
/** High-resolution clock. Optional — falls back to the host's `performance.now()`,
* then `Date.now()`, whose whole milliseconds read sub-millisecond spans as 0. */
now?(): number;
/** The device language as the OS spells it ('zh-Hans-CN', 'en-US', 'zh_CN');
* the adapter reduces it to language-region. Optional, and an empty answer
* counts as none — both fall back to 'en'. */
language?(): string;
/** The native audio engine, when the host has a sound device. Absent → silent
* Null backend. See {@link NativeAudioBridge}. */
audio?: NativeAudioBridge;
/** What the device is called in a list (system and model), when the host says. */
deviceName?(): string;
/** Whether the host is a phone or a tablet, when it says. */
isHandheld?(): boolean;
/** `ws://` sockets, on a host that carries the client. Absent → `createSocket`
* is unavailable, as it is on a host with no network. */
socket?: NativeSocketBridge;
/** The OS text-editing surface (soft keyboard + IME), when the host has wired
* one. Absent → fields render but cannot be typed into, exactly as a host
* with no audio device stays silent. See {@link NativeTextEditorBridge}. */
textEditor?: NativeTextEditorBridge;
/** App foreground/background signals (no DOM visibility on native): the shell
* pushes them, the adapter surfaces them as `onAppShow`/`onAppHide`, and the
* Lifecycle plugin auto-pauses on hide. Each returns an unsubscribe. Optional —
* a shell that never backgrounds (or has not wired it) omits them and the app
* stays always-visible. */
onShow?(callback: () => void): () => void;
onHide?(callback: () => void): () => void;
/** OS memory-pressure warning (iOS didReceiveMemoryWarning / Android
* onLowMemory), pushed by the shell. Residency caches (the audio buffer cache)
* subscribe via the adapter's `onMemoryWarning` to drop evictable entries.
* Returns an unsubscribe. Optional. */
onMemoryWarning?(callback: () => void): () => void;
/** An error that reached the host with nobody catching it. There is no DOM on
* native and QuickJS has no `window.onerror`, so the shell's JS-engine
* exception callback is the only thing that sees these — it pushes them in,
* and diagnostics records them as `unhandled`. Returns an unsubscribe.
* Optional. */
onUnhandledError?(callback: (error: unknown) => void): () => void;
/** The render device was lost — the WebGPU `device.lost` promise on the Dawn
* side, an Android surface torn down on rotation or task-switch. The engine
* cannot see this from JS: the surface belongs to the host binary, so this is
* the shell pushing it in, the same way it pushes the two above. Diagnostics
* records it; nothing recovers from it yet. Returns an unsubscribe. Optional —
* a shell that has not wired it simply never fires. */
onContextLost?(callback: () => void): () => void;
}
/** One event from the host's socket client; `close` is always the last. */
export interface NativeSocketEvent {
type: 'open' | 'message' | 'error' | 'close';
data?: string | ArrayBuffer;
code?: number;
reason?: string;
}
export interface NativeSocketBridge {
open(url: string, onEvent: (event: NativeSocketEvent) => void): {
send(data: string | ArrayBuffer): boolean;
close(code?: number, reason?: string): void;
};
}