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 base.ts
* @brief Base platform adapter - no platform-specific code
*/
import type { PlatformAdapter } from './types';
import type { PlatformAudioBackend } from '../audio/PlatformAudioBackend';
import { NullAudioBackend } from '../audio/NullAudioBackend';
import { log } from '../util/logger';
import { contentCacheFor } from './contentCache';
let cacheWriteFailureReported = false;
// =============================================================================
// Platform Instance (set by entry point)
// =============================================================================
let currentPlatform: PlatformAdapter | null = null;
/**
* Set the platform adapter (called by entry point)
*/
export function setPlatform(adapter: PlatformAdapter): void {
currentPlatform = adapter;
}
/**
* Add capabilities to the platform this app is already on — a host answering
* what its adapter cannot (the editor's play realm stands in for an open data
* context this way). Its own door because `setPlatform({ ...getPlatform() })`
* drops every method an adapter holds on its PROTOTYPE.
*
* @throws Error if no platform is set — there is nothing to extend yet.
*/
export function extendPlatform(extra: Partial<PlatformAdapter>): void {
Object.assign(getPlatform(), extra);
}
/**
* Get the current platform adapter
* @throws Error if platform not initialized
*/
export function getPlatform(): PlatformAdapter {
if (!currentPlatform) {
throw new Error(
'[ESEngine] Platform not initialized. ' +
'Import from "esengine" (web) or "esengine/wechat" (WeChat) instead of direct imports.'
);
}
return currentPlatform;
}
/**
* Check if platform is initialized
*/
export function isPlatformInitialized(): boolean {
return currentPlatform !== null;
}
/**
* Get platform type
*/
export function getPlatformType(): PlatformAdapter['name'] | null {
return currentPlatform?.name ?? null;
}
/**
* Check if running on WeChat specifically (true vendor identity).
* Prefer isMiniGame() for "no DOM / packaged fs / subpackages" checks that hold
* for every mini-game vendor, not just WeChat.
*/
export function isWeChat(): boolean {
return currentPlatform?.name === 'wechat';
}
/**
* Check if running on any mini-game host (WeChat, Douyin, a vendor the game
* brought itself) — the capability family that shares the packaged-filesystem /
* subpackage / no-DOM model.
*
* Reads the adapter's declared family, not a list of vendor names: every
* platform built on {@link MiniGamePlatformAdapter} answers true here, so
* shipping a new vendor never means editing this function.
*/
export function isMiniGame(): boolean {
return currentPlatform?.family === 'minigame';
}
/**
* Check if running on Web
*/
export function isWeb(): boolean {
return currentPlatform?.name === 'web';
}
/**
* Check if running on a native host (embedded Dawn + JS engine on iOS/Android).
* Native has no DOM: offscreen canvas/image throw, textures come from the
* pixel-decode path (loadImagePixels), and lifecycle/safe-area treat it like a
* headless-but-visible host rather than the web DOM branch.
*/
export function isNative(): boolean {
return currentPlatform?.name === 'native';
}
// =============================================================================
// Convenience Functions
// =============================================================================
export async function platformFetch(
url: string,
options?: import('./types').PlatformRequestOptions
): Promise<import('./types').PlatformResponse> {
return getPlatform().fetch(url, options);
}
export async function platformReadFile(path: string): Promise<ArrayBuffer> {
return getPlatform().readFile(path);
}
export async function platformReadTextFile(path: string): Promise<string> {
return getPlatform().readTextFile(path);
}
export async function platformFileExists(path: string): Promise<boolean> {
return getPlatform().fileExists(path);
}
export async function platformLoadImagePixels(path: string): Promise<import('./types').ImageLoadResult> {
return getPlatform().loadImagePixels(path);
}
export async function platformInstantiateWasm(
pathOrBuffer: string | ArrayBuffer,
imports: WebAssembly.Imports
): Promise<import('./types').WasmInstantiateResult> {
return getPlatform().instantiateWasm(pathOrBuffer, imports);
}
export function platformCreateCanvas(
width: number,
height: number,
): import('./types').PlatformCanvas {
return getPlatform().createCanvas(width, height);
}
export function platformCreateImage(): import('./types').PlatformImage {
return getPlatform().createImage();
}
/** Whether this platform rasterizes glyphs itself (no 2D canvas to draw them on).
* The glyph atlas picks its rasterizer from this — false everywhere a canvas
* exists, so web/WeChat text is untouched. Safe before a platform is set. */
export function platformHasGlyphRasterizer(): boolean {
return isPlatformInitialized() && typeof getPlatform().rasterizeGlyph === 'function';
}
/** Rasterize one glyph through the platform's own text stack; null when the
* platform has no rasterizer, or the font/glyph was unavailable. */
export function platformRasterizeGlyph(
request: import('./types').PlatformGlyphRequest,
): import('./types').PlatformGlyph | null {
if (!isPlatformInitialized()) return null;
return getPlatform().rasterizeGlyph?.(request) ?? null;
}
/** The platform's text-editing surface, or null where there is none (a headless
* realm, the editor in edit mode) — fields then render but cannot be typed
* into. Safe before a platform is set. */
export function platformCreateTextEditor(): import('./types').PlatformTextEditor | null {
if (!isPlatformInitialized()) return null;
return getPlatform().createTextEditor?.() ?? null;
}
export function platformNow(): number {
return getPlatform().now();
}
/** Tear down input listeners the adapter bound. No-op on a host that never bound
* input (headless node) or before a platform is set (tests). */
export function platformUnbindInputEvents(): void {
if (!isPlatformInitialized()) return;
getPlatform().unbindInputEvents?.();
}
/** The platform audio backend, or the silent Null backend when the host has no
* audio device (headless node, the native shell before audio lands) — the single
* place the "no real backend" default is decided, mirroring the video backend. */
export function platformCreateAudioBackend(): PlatformAudioBackend {
return getPlatform().createAudioBackend?.() ?? new NullAudioBackend();
}
/** Download an on-demand subpackage by name (resolves immediately on platforms
* with no subpackage concept, e.g. web). The single channel lazy asset groups
* use before loading their assets. */
export function platformLoadSubpackage(name: string): Promise<void> {
const p = getPlatform();
return p.loadSubpackage ? p.loadSubpackage(name) : Promise.resolve();
}
/** Read a content-addressed asset from the persistent cache (hot-update's offline
* store). Returns null on a miss, when the platform has no cache (web), when the
* platform is uninitialized (tests), OR on any read error — every case means "not
* cached, fetch normally", so cache failures never break loading. */
export async function platformReadCacheFile(key: string): Promise<ArrayBuffer | null> {
if (!isPlatformInitialized()) return null;
const p = getPlatform();
if (!p.readCacheFile) return null;
try {
return await contentCacheFor(p).read(key);
} catch {
return null;
}
}
/** Persist a content-addressed asset to the cache: `stored`, `failed` (said once in
* the log as well), or `unsupported` where the platform keeps no cache (web) or is
* uninitialized (tests). A caller decides what a failed write means for it. */
export async function platformWriteCacheFile(key: string, bytes: ArrayBuffer): Promise<'stored' | 'failed' | 'unsupported'> {
if (!isPlatformInitialized()) return 'unsupported';
const p = getPlatform();
if (!p.writeCacheFile || p.hasCacheStorage?.() === false) return 'unsupported';
try {
await contentCacheFor(p).write(key, bytes);
return 'stored';
} catch (err) {
if (!cacheWriteFailureReported) {
cacheWriteFailureReported = true;
log.warn('asset', `cache write failed, so updated assets will need the network next launch: ${String(err)}`);
}
return 'failed';
}
}
/** Subscribe to OS memory-pressure warnings (wx.onMemoryWarning on WeChat).
* Returns an unsubscribe. On platforms without a pressure signal the callback
* simply never fires. Tolerates an uninitialized platform (tests). */
export function platformOnMemoryWarning(callback: () => void): () => void {
if (!isPlatformInitialized()) return () => {};
const p = getPlatform();
return p.onMemoryWarning ? p.onMemoryWarning(callback) : () => {};
}
/** Subscribe to errors that reached the host uncaught (window.onerror /
* wx.onError and the promise equivalents). Returns an unsubscribe. A platform
* without the signal never fires; tolerates an uninitialized platform (tests). */
export function platformOnUnhandledError(callback: (error: unknown) => void): () => void {
if (!isPlatformInitialized()) return () => {};
const p = getPlatform();
return p.onUnhandledError ? p.onUnhandledError(callback) : () => {};
}
/** Subscribe to the render context being lost. Returns an unsubscribe. A
* platform whose surface cannot be lost never fires; tolerates an
* uninitialized platform (tests). */
export function platformOnContextLost(callback: () => void): () => void {
if (!isPlatformInitialized()) return () => {};
const p = getPlatform();
return p.onContextLost ? p.onContextLost(callback) : () => {};
}
/** Subscribe to the app returning to foreground / going to background — the
* native shell's push signals (no DOM visibility on native). Return an
* unsubscribe; a platform without the signal never fires. Tolerates an
* uninitialized platform (tests). */
export function platformOnAppShow(callback: () => void): () => void {
if (!isPlatformInitialized()) return () => {};
const p = getPlatform();
return p.onAppShow ? p.onAppShow(callback) : () => {};
}
export function platformOnAppHide(callback: () => void): () => void {
if (!isPlatformInitialized()) return () => {};
const p = getPlatform();
return p.onAppHide ? p.onAppHide(callback) : () => {};
}
/** Read a persisted string by key (adapter storage: localStorage on web,
* `wx.getStorageSync` on WeChat). Returns null when the key is absent OR the
* platform is uninitialized (tests) — callers treat both as "nothing stored". */
export function platformGetStorageItem(key: string): string | null {
if (!isPlatformInitialized()) return null;
return getPlatform().getStorageItem(key);
}
/** Persist a string by key through the adapter's storage. No-op when the platform
* is uninitialized (tests), so persistence is a safe best-effort everywhere. */
export function platformSetStorageItem(key: string, value: string): void {
if (!isPlatformInitialized()) return;
getPlatform().setStorageItem(key, value);
}
export function platformRemoveStorageItem(key: string): void {
if (!isPlatformInitialized()) return;
getPlatform().removeStorageItem(key);
}
/** The app's own native code, or null where there is none to reach (the web, a
* mini-game, a native host built before the channel, an uninitialized platform). */
export function platformNativeChannel(): import('./types').PlatformNativeChannel | null {
if (!isPlatformInitialized()) return null;
return getPlatform().nativeChannel?.() ?? null;
}
/** Whether this platform can mint ad units at all, without minting one (a
* mini-game host materializes a real host object per created unit). */
export function platformCanCreateAds(): boolean {
return isPlatformInitialized() && getPlatform().createRewardedAd !== undefined;
}
/** One rewarded ad unit from the platform, or null where the platform has no ad
* system (web, a native app whose own code answers for none, playable, an uninitialized platform in tests). Null is
* an answer, not an error: the services layer substitutes its mock provider or
* fails loud with the reason, which is a decision this layer cannot make. */
export function platformCreateRewardedAd(adUnitId: string): import('./types').PlatformRewardedAd | null {
if (!isPlatformInitialized()) return null;
return getPlatform().createRewardedAd?.(adUnitId) ?? null;
}
/** One interstitial ad unit, or null — same availability story as rewarded. */
export function platformCreateInterstitialAd(adUnitId: string): import('./types').PlatformInterstitialAd | null {
if (!isPlatformInitialized()) return null;
return getPlatform().createInterstitialAd?.(adUnitId) ?? null;
}
/** Whether this platform can open a share sheet at all, without opening one. */
export function platformCanShare(): boolean {
return isPlatformInitialized() && getPlatform().share !== undefined;
}
/** Actively open the host's share sheet; false when this platform cannot share
* (web, native, tests) so the caller can hide its share button honestly. */
export function platformShare(options: import('./types').PlatformShareOptions): boolean {
if (!isPlatformInitialized()) return false;
const p = getPlatform();
if (!p.share) return false;
p.share(options);
return true;
}
/** Register the passive-share card provider; false when the platform has no
* passive share surface. The host asks the provider at share time. */
export function platformOnShareRequest(provide: () => import('./types').PlatformShareOptions): boolean {
if (!isPlatformInitialized()) return false;
const p = getPlatform();
if (!p.onShareRequest) return false;
p.onShareRequest(provide);
return true;
}
/** The host's screen recorder, or null where there is none — which a game reads
* to hide its record button rather than to show one that fails. */
export function platformScreenRecorder(): import('./types').PlatformScreenRecorder | null {
if (!isPlatformInitialized()) return null;
return getPlatform().screenRecorder?.() ?? null;
}
/** Whether this platform can sign a player in at all — what a menu reads to
* hide its sign-in button honestly (web, native and the editor cannot). */
export function platformCanSignIn(): boolean {
if (!isPlatformInitialized()) return false;
const p = getPlatform();
// Declared, and — where the adapter can be more precise than its own method
// list — actually backed by a host that signs people in.
return p.login !== undefined && (p.canSignIn?.() ?? true);
}
/** Begin a sign-in; rejects where the platform has none, so a caller that
* skipped {@link platformCanSignIn} still hears about it rather than awaiting
* a promise that never settles. */
export function platformLogin(): Promise<string> {
if (!platformCanSignIn()) return Promise.reject(new Error('this platform has no sign-in'));
return getPlatform().login!();
}
/** Whether the host still regards the last sign-in as current. False where
* there is no sign-in at all — there is nothing current about nothing. */
export function platformCheckSession(): Promise<boolean> {
if (!isPlatformInitialized()) return Promise.resolve(false);
return getPlatform().checkSession?.() ?? Promise.resolve(false);
}
/** Whether a purchase may happen here at all — declared by the platform, and
* permitted on THIS device. See `PlatformAdapter.canPay`. */
export function platformCanPay(): boolean {
if (!isPlatformInitialized()) return false;
const p = getPlatform();
return p.requestPayment !== undefined && (p.canPay?.() ?? true);
}
/** Buy in-game currency; rejects where purchase is not available, so a caller
* that skipped {@link platformCanPay} hears why rather than hanging. */
export function platformRequestPayment(request: import('./types').PlatformPaymentRequest): Promise<void> {
if (!platformCanPay()) {
return Promise.reject(new Error('in-game purchase is not available on this platform'));
}
return getPlatform().requestPayment!(request);
}
/**
* Whether this platform has a USABLE open data context — what a leaderboard
* reads to hide itself honestly (web, native and the editor have none).
*
* Method presence is not the answer here, the way it is for share: the
* mini-game family is ONE adapter, so every vendor defines these, and a game
* whose package declares no context directory has none even on a host that
* supports them. So the honest probe is the same one the ad path uses — ask
* for the thing and treat null as "not here".
*/
export function platformCanOpenData(): boolean {
if (!isPlatformInitialized()) return false;
const p = getPlatform();
return p.openDataPostMessage !== undefined && p.openDataCanvas?.() != null;
}
/**
* Send one message into the open data context; false where there is none.
* One way: the hosts offer no path back, so there is nothing to await.
*
* Gated on the same probe rather than on method presence — otherwise this
* reports a delivery it did not make, on every mini-game host without a
* context, which is the answer a caller is least able to check.
*/
export function platformOpenDataPostMessage(message: Record<string, unknown>): boolean {
if (!platformCanOpenData()) return false;
getPlatform().openDataPostMessage!(message);
return true;
}
/** The canvas the open data context draws on, for sampling as a texture. */
export function platformOpenDataCanvas(): import('./types').PlatformCanvas | null {
if (!isPlatformInitialized()) return null;
return getPlatform().openDataCanvas?.() ?? null;
}
/** Write this player's own cloud rows; false where the host has no such store.
* Unlike a share, "there was nowhere to write this" is knowable at call time,
* so it is reported rather than swallowed. */
export function platformSetCloudKeyValues(entries: Readonly<Record<string, string>>): boolean {
if (!isPlatformInitialized()) return false;
return getPlatform().setCloudKeyValues?.(entries) ?? false;
}
export function platformDevicePixelRatio(): number {
if (currentPlatform) {
return currentPlatform.devicePixelRatio();
}
return typeof window !== 'undefined' ? (window.devicePixelRatio || 1) : 1;
}
/** The host's UI language as a BCP-47-ish tag ('zh-CN', 'en-US', …): the
* adapter's report (WeChat), else navigator.language (web), else 'en'.
* Underscore tags ('zh_CN') normalize to hyphens. Tolerates an
* uninitialized platform (tests). */
export function platformLanguage(): string {
const raw = currentPlatform?.language?.()
?? (typeof navigator !== 'undefined' ? navigator.language : undefined);
return (raw ?? 'en').replace(/_/g, '-');
}