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
refactor(platform): unify the adapter capability surface
esengine7c963b2c3855
diff --git a/sdk/etc/index.api.md b/sdk/etc/index.api.mdindex 2a596bdce..1f21c015a 100644--- a/sdk/etc/index.api.md+++ b/sdk/etc/index.api.md@@ -4424,7 +4424,7 @@ _physics_updateBodyProperties: (entityId: number, bodyType: number, gravityScale```bindInputEvents: (callbacks: InputEventCallbacks, target?: unknown) => voidclearStorage: (prefix: string) => void-createAudioBackend: () => PlatformAudioBackend+createAudioBackend: (() => PlatformAudioBackend) | undefinedcreateCanvas: (width: number, height: number) => PlatformCanvascreateImage: () => PlatformImagecreateSocket: ((options: PlatformSocketOptions) => PlatformSocket) | undefined@@ -4446,6 +4446,7 @@ readFile: (path: string) => Promise<ArrayBuffer>readTextFile: (path: string) => Promise<string>removeStorageItem: (key: string) => voidsetStorageItem: (key: string, value: string) => void+unbindInputEvents: (() => void) | undefinedwriteCacheFile: ((key: string, bytes: ArrayBuffer) => Promise<void>) | undefined```diff --git a/sdk/etc/index.native.api.md b/sdk/etc/index.native.api.mdindex 68a5cf4a7..9fcfe05af 100644--- a/sdk/etc/index.native.api.md+++ b/sdk/etc/index.native.api.md@@ -3947,7 +3947,6 @@ onTouchStart: (id: number, x: number, y: number) => void```bindInputEvents: (callbacks: InputEventCallbacks) => voidclearStorage: (prefix: string) => void-createAudioBackend: () => PlatformAudioBackendcreateCanvas: (_width: number, _height: number) => PlatformCanvascreateImage: () => PlatformImagedevicePixelRatio: () => number@@ -4491,7 +4490,7 @@ _physics_updateBodyProperties: (entityId: number, bodyType: number, gravityScale```bindInputEvents: (callbacks: InputEventCallbacks, target?: unknown) => voidclearStorage: (prefix: string) => void-createAudioBackend: () => PlatformAudioBackend+createAudioBackend: (() => PlatformAudioBackend) | undefinedcreateCanvas: (width: number, height: number) => PlatformCanvascreateImage: () => PlatformImagecreateSocket: ((options: PlatformSocketOptions) => PlatformSocket) | undefined@@ -4513,6 +4512,7 @@ readFile: (path: string) => Promise<ArrayBuffer>readTextFile: (path: string) => Promise<string>removeStorageItem: (key: string) => voidsetStorageItem: (key: string, value: string) => void+unbindInputEvents: (() => void) | undefinedwriteCacheFile: ((key: string, bytes: ArrayBuffer) => Promise<void>) | undefined```diff --git a/sdk/etc/index.node.api.md b/sdk/etc/index.node.api.mdindex 375c916a2..3888d205e 100644--- a/sdk/etc/index.node.api.md+++ b/sdk/etc/index.node.api.md@@ -4419,7 +4419,7 @@ _physics_updateBodyProperties: (entityId: number, bodyType: number, gravityScale```bindInputEvents: (callbacks: InputEventCallbacks, target?: unknown) => voidclearStorage: (prefix: string) => void-createAudioBackend: () => PlatformAudioBackend+createAudioBackend: (() => PlatformAudioBackend) | undefinedcreateCanvas: (width: number, height: number) => PlatformCanvascreateImage: () => PlatformImagecreateSocket: ((options: PlatformSocketOptions) => PlatformSocket) | undefined@@ -4441,6 +4441,7 @@ readFile: (path: string) => Promise<ArrayBuffer>readTextFile: (path: string) => Promise<string>removeStorageItem: (key: string) => voidsetStorageItem: (key: string, value: string) => void+unbindInputEvents: (() => void) | undefinedwriteCacheFile: ((key: string, bytes: ArrayBuffer) => Promise<void>) | undefined```diff --git a/sdk/etc/wechat.api.md b/sdk/etc/wechat.api.mdindex f61b51fab..74008ed03 100644--- a/sdk/etc/wechat.api.md+++ b/sdk/etc/wechat.api.md@@ -4426,7 +4426,7 @@ _physics_updateBodyProperties: (entityId: number, bodyType: number, gravityScale```bindInputEvents: (callbacks: InputEventCallbacks, target?: unknown) => voidclearStorage: (prefix: string) => void-createAudioBackend: () => PlatformAudioBackend+createAudioBackend: (() => PlatformAudioBackend) | undefinedcreateCanvas: (width: number, height: number) => PlatformCanvascreateImage: () => PlatformImagecreateSocket: ((options: PlatformSocketOptions) => PlatformSocket) | undefined@@ -4448,6 +4448,7 @@ readFile: (path: string) => Promise<ArrayBuffer>readTextFile: (path: string) => Promise<string>removeStorageItem: (key: string) => voidsetStorageItem: (key: string, value: string) => void+unbindInputEvents: (() => void) | undefinedwriteCacheFile: ((key: string, bytes: ArrayBuffer) => Promise<void>) | undefined```diff --git a/sdk/src/audio/AudioPlugin.ts b/sdk/src/audio/AudioPlugin.tsindex 9ed2d624e..817900bdf 100644--- a/sdk/src/audio/AudioPlugin.ts+++ b/sdk/src/audio/AudioPlugin.ts@@ -7,7 +7,7 @@ import { Res, Time, type TimeData } from '../resource';import { Audio, AudioAPI } from './Audio';import { AudioSource, AudioListener, type AudioSourceData, type AudioListenerData } from './AudioComponents';import { WorldTransform, type WorldTransformData } from '../component';-import { getPlatform, platformOnMemoryWarning } from '../platform/base';+import { platformCreateAudioBackend, platformOnMemoryWarning } from '../platform/base';import { calculateAttenuation, calculatePanning, type SpatialAudioConfig, AttenuationModel } from './SpatialAudio';import type { AudioHandle } from './PlatformAudioBackend';import { isEditor, isPlayMode } from '../env';@@ -34,7 +34,7 @@ export class AudioPlugin implements Plugin {}build(app: App): void {- const backend = getPlatform().createAudioBackend();+ const backend = platformCreateAudioBackend();const config = this.config_;backend.initialize({ initialPoolSize: config.initialPoolSize }).catch(err => {diff --git a/sdk/src/camera/CameraPlugin.ts b/sdk/src/camera/CameraPlugin.tsindex 717708913..526f23edb 100644--- a/sdk/src/camera/CameraPlugin.ts+++ b/sdk/src/camera/CameraPlugin.ts@@ -22,7 +22,7 @@ import { ScreenScaling, DEFAULT_SCREEN_SCALING, SCREEN_FIT_OFF } from './ScreenSimport { CameraDirector, createDirectorState, resolveMainPOV } from './CameraDirector';import { RenderPipeline } from '../renderPipeline';import { Renderer } from '../renderer';-import { platformNow } from '../platform';+import { platformNow, platformDevicePixelRatio } from '../platform';import { SceneManager } from '../sceneManager';import { ortho, perspective, invertViewZ, multiply, IDENTITY } from '../math/mat4';@@ -446,7 +446,7 @@ export function cameraPlugin(app.insertResource(CameraDirector, createDirectorState());const viewport = getViewportSize ?? (() => {- const dpr = typeof window !== 'undefined' ? (window.devicePixelRatio || 1) : 1;+ const dpr = platformDevicePixelRatio();return {width: window.innerWidth * dpr,height: window.innerHeight * dpr,diff --git a/sdk/src/input.ts b/sdk/src/input.tsindex 6bd6324df..95af4b26f 100644--- a/sdk/src/input.ts+++ b/sdk/src/input.ts@@ -3,7 +3,7 @@import { defineResource } from './resource';import { defineSystem, Schedule } from './system';import type { App, Plugin } from './app';-import { getPlatform } from './platform';+import { getPlatform, platformUnbindInputEvents } from './platform';import type { GamepadSnapshot } from './platform/types';import { inputRouter } from './inputRouter';@@ -371,10 +371,7 @@ export class InputPlugin implements Plugin {}cleanup(): void {- const platform = getPlatform() as any;- if (typeof platform.unbindInputEvents === 'function') {- platform.unbindInputEvents();- }+ platformUnbindInputEvents();}}diff --git a/sdk/src/platform/base.ts b/sdk/src/platform/base.tsindex 8fa1fd4bf..5fbe25ff3 100644--- a/sdk/src/platform/base.ts+++ b/sdk/src/platform/base.ts@@ -6,6 +6,8 @@*/import type { PlatformAdapter } from './types';+import type { PlatformAudioBackend } from '../audio/PlatformAudioBackend';+import { NullAudioBackend } from '../audio/NullAudioBackend';// =============================================================================// Platform Instance (set by entry point)@@ -132,8 +134,18 @@ export function platformNow(): number {return getPlatform().now();}-export function platformCreateAudioBackend(): import('../audio/PlatformAudioBackend').PlatformAudioBackend {- return getPlatform().createAudioBackend();+/** 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 platformsdiff --git a/sdk/src/platform/index.ts b/sdk/src/platform/index.tsindex be1021878..26a2b474e 100644--- a/sdk/src/platform/index.ts+++ b/sdk/src/platform/index.ts@@ -37,6 +37,7 @@ export {platformCreateCanvas,platformCreateImage,platformNow,+ platformUnbindInputEvents,platformCreateAudioBackend,platformLoadSubpackage,platformReadCacheFile,diff --git a/sdk/src/platform/minigame/adapter.ts b/sdk/src/platform/minigame/adapter.tsindex 1b91252df..c89611b44 100644--- a/sdk/src/platform/minigame/adapter.ts+++ b/sdk/src/platform/minigame/adapter.ts@@ -28,7 +28,8 @@ import type { PlatformAudioBackend } from '../../audio/PlatformAudioBackend';import type { PlatformVideoBackend, VideoBackendContext } from '../../video/PlatformVideoBackend';import { toBuildPath } from '../../assetTypes';import { log } from '../../logger';-import type { MiniGameGlobal, MiniGameProfile, MiniGameFileSystemManager } from './api';+import type { MiniGameGlobal, MiniGameProfile, MiniGameFileSystemManager, MiniGameTouchEvent } from './api';+import { createPrimaryPointer } from '../primaryPointer';import { mgReadFileSync, mgReadTextFileSync, mgFileExistsSync } from './fs';import { mgLoadImagePixels } from './image';import { mgFetch } from './fetch';@@ -142,38 +143,25 @@ export class MiniGamePlatformAdapter implements PlatformAdapter {g.onKeyUp?.(onKeyUp);}- let primaryTouchId: number | null = null;+ const pointer = createPrimaryPointer(callbacks);- const onTouchStart = (res: { changedTouches: { identifier: number; clientX: number; clientY: number }[] }) => {- for (const touch of res.changedTouches) {- callbacks.onTouchStart?.(touch.identifier, touch.clientX, touch.clientY);- if (primaryTouchId === null) {- primaryTouchId = touch.identifier;- callbacks.onPointerDown(0, touch.clientX, touch.clientY);- }- }+ const onTouchStart = (res: MiniGameTouchEvent) => {+ for (const touch of res.changedTouches) pointer.start(touch.identifier, touch.clientX, touch.clientY);};- const onTouchMove = (res: { changedTouches: { identifier: number; clientX: number; clientY: number }[] }) => {- for (const touch of res.changedTouches) {- callbacks.onTouchMove?.(touch.identifier, touch.clientX, touch.clientY);- if (touch.identifier === primaryTouchId) {- callbacks.onPointerMove(touch.clientX, touch.clientY);- }- }+ const onTouchMove = (res: MiniGameTouchEvent) => {+ for (const touch of res.changedTouches) pointer.move(touch.identifier, touch.clientX, touch.clientY);};- const onTouchEnd = (res: { changedTouches: { identifier: number; clientX: number; clientY: number }[] }) => {- for (const touch of res.changedTouches) {- callbacks.onTouchEnd?.(touch.identifier);- if (touch.identifier === primaryTouchId) {- primaryTouchId = null;- callbacks.onPointerUp(0);- }- }+ const onTouchEnd = (res: MiniGameTouchEvent) => {+ for (const touch of res.changedTouches) pointer.end(touch.identifier);+ };+ const onTouchCancel = (res: MiniGameTouchEvent) => {+ for (const touch of res.changedTouches) pointer.cancel(touch.identifier);};g.onTouchStart(onTouchStart);g.onTouchMove(onTouchMove);g.onTouchEnd(onTouchEnd);+ g.onTouchCancel?.(onTouchCancel);this.inputCleanup_ = () => {if (hasKeyboard) {@@ -183,6 +171,7 @@ export class MiniGamePlatformAdapter implements PlatformAdapter {g.offTouchStart(onTouchStart);g.offTouchMove(onTouchMove);g.offTouchEnd(onTouchEnd);+ g.offTouchCancel?.(onTouchCancel);};}diff --git a/sdk/src/platform/minigame/api.ts b/sdk/src/platform/minigame/api.tsindex 4c75e6acd..d97ea7d48 100644--- a/sdk/src/platform/minigame/api.ts+++ b/sdk/src/platform/minigame/api.ts@@ -115,6 +115,10 @@ export interface MiniGameGlobal {offTouchStart(cb: (res: MiniGameTouchEvent) => void): void;offTouchMove(cb: (res: MiniGameTouchEvent) => void): void;offTouchEnd(cb: (res: MiniGameTouchEvent) => void): void;+ // Optional: a cancelled gesture (system interruption). Present on WeChat/Douyin;+ // guarded so a host without it still binds start/move/end.+ onTouchCancel?(cb: (res: MiniGameTouchEvent) => void): void;+ offTouchCancel?(cb: (res: MiniGameTouchEvent) => void): void;onKeyDown?(cb: (res: MiniGameKeyEvent) => void): void;onKeyUp?(cb: (res: MiniGameKeyEvent) => void): void;diff --git a/sdk/src/platform/native/adapter.ts b/sdk/src/platform/native/adapter.tsindex 7808bfaf7..58db1d0ff 100644--- a/sdk/src/platform/native/adapter.ts+++ b/sdk/src/platform/native/adapter.ts@@ -24,9 +24,8 @@ import type {PlatformCanvas,PlatformImage,} from '../types';-import type { PlatformAudioBackend } from '../../audio/PlatformAudioBackend';-import { NullAudioBackend } from '../../audio/NullAudioBackend';import { setPlatform } from '../base';+import { createPrimaryPointer } from '../primaryPointer';import type { NativeBridge, NativeInputListener } from './bridge';export class NativePlatformAdapter implements PlatformAdapter {@@ -106,33 +105,12 @@ export class NativePlatformAdapter implements PlatformAdapter {bindInputEvents(callbacks: InputEventCallbacks): void {this.inputCleanup_?.();- let primaryTouchId: number | null = null;+ const pointer = createPrimaryPointer(callbacks);const listener: NativeInputListener = {- onTouchStart: (id, x, y) => {- callbacks.onTouchStart?.(id, x, y);- if (primaryTouchId === null) {- primaryTouchId = id;- callbacks.onPointerDown(0, x, y);- }- },- onTouchMove: (id, x, y) => {- callbacks.onTouchMove?.(id, x, y);- if (id === primaryTouchId) callbacks.onPointerMove(x, y);- },- onTouchEnd: (id) => {- callbacks.onTouchEnd?.(id);- if (id === primaryTouchId) {- primaryTouchId = null;- callbacks.onPointerUp(0);- }- },- onTouchCancel: (id) => {- callbacks.onTouchCancel?.(id);- if (id === primaryTouchId) {- primaryTouchId = null;- callbacks.onPointerUp(0);- }- },+ onTouchStart: (id, x, y) => pointer.start(id, x, y),+ onTouchMove: (id, x, y) => pointer.move(id, x, y),+ onTouchEnd: (id) => pointer.end(id),+ onTouchCancel: (id) => pointer.cancel(id),onKeyDown: (code) => callbacks.onKeyDown(code),onKeyUp: (code) => callbacks.onKeyUp(code),};@@ -144,11 +122,9 @@ export class NativePlatformAdapter implements PlatformAdapter {this.inputCleanup_ = null;}- // Audio ships with the shell; a silent backend keeps sound-playing gameplay- // code running unchanged until then (same choice as the Node host).- createAudioBackend(): PlatformAudioBackend {- return new NullAudioBackend();- }+ // No createAudioBackend: audio ships with the shell, so the adapter omits it+ // and the audio system falls back to the silent Null backend (like the Node+ // host and the optional video backend) until the shell provides one.getStorageItem(key: string): string | null {return this.bridge_.getStorageItem(key);diff --git a/sdk/src/platform/node.ts b/sdk/src/platform/node.tsindex 93d6d3da6..1ba9bd4e9 100644--- a/sdk/src/platform/node.ts+++ b/sdk/src/platform/node.ts@@ -27,8 +27,6 @@ import type {PlatformSocket,PlatformSocketOptions,} from './types';-import type { PlatformAudioBackend } from '../audio/PlatformAudioBackend';-import { NullAudioBackend } from '../audio/NullAudioBackend';import { GameSocket } from '../net/GameSocket';function isUrl(path: string): boolean {@@ -135,10 +133,6 @@ class NodePlatformAdapter implements PlatformAdapter {// No local input device — player input arrives over the network.}- createAudioBackend(): PlatformAudioBackend {- return new NullAudioBackend();- }-createSocket(options: PlatformSocketOptions): PlatformSocket {// Node ≥ 22 ships a spec-compliant global WebSocket client.return new GameSocket(options);diff --git a/sdk/src/platform/primaryPointer.ts b/sdk/src/platform/primaryPointer.tsnew file mode 100644index 000000000..88a46ee4c--- /dev/null+++ b/sdk/src/platform/primaryPointer.ts@@ -0,0 +1,51 @@+// SPDX-License-Identifier: Apache-2.0+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team+/**+ * @file primaryPointer.ts+ * @brief The primary-pointer synthesis every touch host shares. The first+ * active touch drives pointer 0 (down / move / up); a concurrent second+ * touch is still forwarded as a raw touch but does not move the pointer.+ * The primary touch's END or CANCEL both release the pointer, so a+ * cancelled gesture never leaves it stuck down. Adapters (web / native /+ * mini-game) feed it already-extracted `(id, x, y)`; the state machine+ * lives here once instead of being copied per adapter.+ */+import type { InputEventCallbacks } from './types';++export interface PrimaryPointer {+ start(id: number, x: number, y: number): void;+ move(id: number, x: number, y: number): void;+ end(id: number): void;+ cancel(id: number): void;+}++export function createPrimaryPointer(callbacks: InputEventCallbacks): PrimaryPointer {+ let primary: number | null = null;+ return {+ start(id, x, y) {+ callbacks.onTouchStart?.(id, x, y);+ if (primary === null) {+ primary = id;+ callbacks.onPointerDown(0, x, y);+ }+ },+ move(id, x, y) {+ callbacks.onTouchMove?.(id, x, y);+ if (id === primary) callbacks.onPointerMove(x, y);+ },+ end(id) {+ callbacks.onTouchEnd?.(id);+ if (id === primary) {+ primary = null;+ callbacks.onPointerUp(0);+ }+ },+ cancel(id) {+ callbacks.onTouchCancel?.(id);+ if (id === primary) {+ primary = null;+ callbacks.onPointerUp(0);+ }+ },+ };+}diff --git a/sdk/src/platform/types.ts b/sdk/src/platform/types.tsindex 973469e72..1ebe61295 100644--- a/sdk/src/platform/types.ts+++ b/sdk/src/platform/types.ts@@ -261,12 +261,20 @@ export interface PlatformAdapter {bindInputEvents(callbacks: InputEventCallbacks, target?: unknown): void;+ /** Tear down the listeners {@link bindInputEvents} registered. Optional — a+ * headless host that never binds input (node) omits it. */+ unbindInputEvents?(): void;+/** Poll connected gamepads for this frame. Optional — platforms without* gamepad support (WeChat, headless) omit it and the input plugin skips* gamepad polling entirely. */pollGamepads?(): GamepadSnapshot[];- createAudioBackend(): import('../audio/PlatformAudioBackend').PlatformAudioBackend;+ /** Create the platform audio backend (WebAudio on web, the mini-game audio API+ * on WeChat). Optional — a host with no audio device (headless node, the+ * unshipped native shell) omits it and the audio system falls back to the+ * silent Null backend, exactly like {@link createVideoBackend}. */+ createAudioBackend?(): import('../audio/PlatformAudioBackend').PlatformAudioBackend;/** Create the platform video backend: HTMLVideoElement on web, the wasm* software decoder (videodec side module) on WeChat. The choice is a staticdiff --git a/sdk/src/platform/web.ts b/sdk/src/platform/web.tsindex 1ce11065b..5dcd70b3e 100644--- a/sdk/src/platform/web.ts+++ b/sdk/src/platform/web.ts@@ -23,6 +23,7 @@ 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';const WHEEL_LINE_HEIGHT = 16;@@ -159,7 +160,7 @@ class WebPlatformAdapter implements PlatformAdapter {const onMouseUp = (e: Event) => {callbacks.onPointerUp((e as MouseEvent).button);};- let primaryTouchId: number | null = null;+ const pointer = createPrimaryPointer(callbacks);const onTouchStart = (e: Event) => {e.preventDefault();@@ -167,13 +168,7 @@ class WebPlatformAdapter implements PlatformAdapter {const rect = (el as HTMLElement).getBoundingClientRect();for (let i = 0; i < te.changedTouches.length; i++) {const touch = te.changedTouches[i];- const x = touch.clientX - rect.left;- const y = touch.clientY - rect.top;- callbacks.onTouchStart?.(touch.identifier, x, y);- if (primaryTouchId === null) {- primaryTouchId = touch.identifier;- callbacks.onPointerDown(0, x, y);- }+ pointer.start(touch.identifier, touch.clientX - rect.left, touch.clientY - rect.top);}};const onTouchMove = (e: Event) => {@@ -182,35 +177,20 @@ class WebPlatformAdapter implements PlatformAdapter {const rect = (el as HTMLElement).getBoundingClientRect();for (let i = 0; i < te.changedTouches.length; i++) {const touch = te.changedTouches[i];- const x = touch.clientX - rect.left;- const y = touch.clientY - rect.top;- callbacks.onTouchMove?.(touch.identifier, x, y);- if (touch.identifier === primaryTouchId) {- callbacks.onPointerMove(x, y);- }+ 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 touch = te.changedTouches[i];- callbacks.onTouchEnd?.(touch.identifier);- if (touch.identifier === primaryTouchId) {- primaryTouchId = null;- callbacks.onPointerUp(0);- }+ pointer.end(te.changedTouches[i].identifier);}};const onTouchCancel = (e: Event) => {const te = e as TouchEvent;for (let i = 0; i < te.changedTouches.length; i++) {- const touch = te.changedTouches[i];- callbacks.onTouchCancel?.(touch.identifier);- if (touch.identifier === primaryTouchId) {- primaryTouchId = null;- callbacks.onPointerUp(0);- }+ pointer.cancel(te.changedTouches[i].identifier);}};const onWheel = (e: Event) => {