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 renderer init behind a neutral RenderSurfaceSource
yhhf7288d5bd2b1
diff --git a/desktop/src/engine/EngineHost.ts b/desktop/src/engine/EngineHost.tsindex 5d2cfb74f..310a4c25e 100644--- a/desktop/src/engine/EngineHost.ts+++ b/desktop/src/engine/EngineHost.ts@@ -15,7 +15,7 @@ import {setEditorMode,setPlayMode,} from 'esengine';-import type { App, ESEngineModule, ResourceDef, SubsystemStatus, SceneData } from 'esengine';+import type { App, ESEngineModule, ResourceDef, SubsystemStatus, SceneData, RenderSurfaceSource } from 'esengine';import { SpinePlugin } from 'esengine/spine';import type { SpineManager } from 'esengine/spine';import { SceneLoader } from './SceneLoader';@@ -609,11 +609,14 @@ class EngineHostImpl {});}+ // WebGPU hands the engine the whole canvas swapchain via the injected device+ // (canvas resolved by selector); WebGL2 binds the context we registered above.+ const renderSurface: RenderSurfaceSource = backend === 'webgpu'+ ? { kind: 'webgpu', canvasSelector: `#${canvas.id}` }+ : { kind: 'gl-context', handle: glHandle! };const app = await bootProfiler.phase('createWebApp', () => createWebApp(module, {- backend,+ renderSurface,colorSpace: opts.colorSpace,- canvasSelector: `#${canvas.id}`,- glContextHandle: glHandle,getViewportSize: () => ({ width: canvas.width, height: canvas.height }),// The per-version spine side modules are served next to esengine.wasm// (same /wasm/ dir as locateFile above), so the web spine provider candiff --git a/desktop/src/gameHost.ts b/desktop/src/gameHost.tsindex 9237243a5..8e85d009b 100644--- a/desktop/src/gameHost.ts+++ b/desktop/src/gameHost.ts@@ -118,7 +118,7 @@ async function boot(): Promise<void> {const glHandle = module.GL.registerContext(gl, { majorVersion: 2, minorVersion: 0, enableExtensionsByDefault: true });const app = createWebApp(module, {- glContextHandle: glHandle,+ renderSurface: { kind: 'gl-context', handle: glHandle },ySortLayers: cfg.ySortLayers,colorSpace: cfg.colorSpace,screenFit: cfg.screenFit,diff --git a/desktop/src/playHost.ts b/desktop/src/playHost.tsindex 8b958cf57..f8855c0ef 100644--- a/desktop/src/playHost.ts+++ b/desktop/src/playHost.ts@@ -188,7 +188,7 @@ function jsonMap(json: string | undefined): Record<string, number> {async function buildAppAndRun(msg: InitMessage): Promise<void> {const module = engineModule!;app = createWebApp(module, {- glContextHandle: glHandle,+ renderSurface: { kind: 'gl-context', handle: glHandle },ySortLayers: msg.ySortLayers,colorSpace: msg.colorSpace,screenFit: msg.screenFit,diff --git a/desktop/src/playableHost.ts b/desktop/src/playableHost.tsindex 4ea489dba..316554f6d 100644--- a/desktop/src/playableHost.ts+++ b/desktop/src/playableHost.ts@@ -76,7 +76,7 @@ async function boot(): Promise<void> {const glHandle = module.GL.registerContext(gl, { majorVersion: 2, minorVersion: 0, enableExtensionsByDefault: true });const app = createWebApp(module, {- glContextHandle: glHandle,+ renderSurface: { kind: 'gl-context', handle: glHandle },// Older exports predate the color-space global; treat it as optional.colorSpace: typeof __GAME_COLORSPACE__ !== 'undefined' ? __GAME_COLORSPACE__ : undefined,// Present only when the project opts into a camera fit; optional otherwise.diff --git a/sdk/etc/index.api.md b/sdk/etc/index.api.mdindex 3cb872247..cc9f05bc3 100644--- a/sdk/etc/index.api.md+++ b/sdk/etc/index.api.md@@ -1,7 +1,7 @@# API surface — esengine/index<!-- Generated by tools/api-surface.mjs — do not edit. Run --update to accept changes. -->-Symbols: 1320 stable · 17 beta · 0 deprecated+Symbols: 1321 stable · 17 beta · 0 deprecated## ABI_LAYOUT_HASH — const```@@ -1807,12 +1807,10 @@ world: World## CreateWebAppOptions — interface```-backend: "webgl2" | "webgpu" | undefined-canvasSelector: string | undefinedcolorSpace: "gamma" | "linear" | undefinedgetViewportSize: (() => { width: number; height: number; }) | undefined-glContextHandle: number | undefinedplugins: Plugin[] | undefined+renderSurface: RenderSurfaceSource | undefinedscreenFit: ScreenScalingData | undefinedsideModules: SideModuleHost | undefinedwasmBaseUrl: string | undefined@@ -5092,6 +5090,13 @@ text: numbertriangles: number```+## RenderSurfaceSource — type+```+| { readonly kind: 'gl-context'; readonly handle: number }+ | { readonly kind: 'webgpu'; readonly canvasSelector?: string }+ | { readonly kind: 'default' }+```+## RenderTargetHandle — type```number@@ -7737,12 +7742,10 @@ static prototype: WeChatSocket## WebAppOptions — interface```-backend: "webgl2" | "webgpu" | undefined-canvasSelector: string | undefinedcolorSpace: "gamma" | "linear" | undefinedgetViewportSize: (() => { width: number; height: number; }) | undefined-glContextHandle: number | undefinedplugins: Plugin[] | undefined+renderSurface: RenderSurfaceSource | undefinedscreenFit: ScreenScalingData | undefinedsideModules: SideModuleHost | undefinedySortLayers: number | undefineddiff --git a/sdk/etc/index.node.api.md b/sdk/etc/index.node.api.mdindex a406d136a..a275e661f 100644--- a/sdk/etc/index.node.api.md+++ b/sdk/etc/index.node.api.md@@ -1,7 +1,7 @@# API surface — esengine/index.node<!-- Generated by tools/api-surface.mjs — do not edit. Run --update to accept changes. -->-Symbols: 1319 stable · 19 beta · 0 deprecated+Symbols: 1320 stable · 19 beta · 0 deprecated## ANCHOR_AXES — const```@@ -1802,12 +1802,10 @@ world: World## CreateWebAppOptions — interface```-backend: "webgl2" | "webgpu" | undefined-canvasSelector: string | undefinedcolorSpace: "gamma" | "linear" | undefinedgetViewportSize: (() => { width: number; height: number; }) | undefined-glContextHandle: number | undefinedplugins: Plugin[] | undefined+renderSurface: RenderSurfaceSource | undefinedscreenFit: ScreenScalingData | undefinedsideModules: SideModuleHost | undefinedwasmBaseUrl: string | undefined@@ -5087,6 +5085,13 @@ text: numbertriangles: number```+## RenderSurfaceSource — type+```+| { readonly kind: 'gl-context'; readonly handle: number }+ | { readonly kind: 'webgpu'; readonly canvasSelector?: string }+ | { readonly kind: 'default' }+```+## RenderTargetHandle — type```number@@ -7732,12 +7737,10 @@ static prototype: WeChatSocket## WebAppOptions — interface```-backend: "webgl2" | "webgpu" | undefined-canvasSelector: string | undefinedcolorSpace: "gamma" | "linear" | undefinedgetViewportSize: (() => { width: number; height: number; }) | undefined-glContextHandle: number | undefinedplugins: Plugin[] | undefined+renderSurface: RenderSurfaceSource | undefinedscreenFit: ScreenScalingData | undefinedsideModules: SideModuleHost | undefinedySortLayers: number | undefineddiff --git a/sdk/etc/wechat.api.md b/sdk/etc/wechat.api.mdindex dfd65b228..31656084a 100644--- a/sdk/etc/wechat.api.md+++ b/sdk/etc/wechat.api.md@@ -1,7 +1,7 @@# API surface — esengine/wechat<!-- Generated by tools/api-surface.mjs — do not edit. Run --update to accept changes. -->-Symbols: 1330 stable · 17 beta · 0 deprecated+Symbols: 1331 stable · 17 beta · 0 deprecated## ANCHOR_AXES — const```@@ -1802,12 +1802,10 @@ world: World## CreateWebAppOptions — interface```-backend: "webgl2" | "webgpu" | undefined-canvasSelector: string | undefinedcolorSpace: "gamma" | "linear" | undefinedgetViewportSize: (() => { width: number; height: number; }) | undefined-glContextHandle: number | undefinedplugins: Plugin[] | undefined+renderSurface: RenderSurfaceSource | undefinedscreenFit: ScreenScalingData | undefinedsideModules: SideModuleHost | undefinedwasmBaseUrl: string | undefined@@ -5094,6 +5092,13 @@ text: numbertriangles: number```+## RenderSurfaceSource — type+```+| { readonly kind: 'gl-context'; readonly handle: number }+ | { readonly kind: 'webgpu'; readonly canvasSelector?: string }+ | { readonly kind: 'default' }+```+## RenderTargetHandle — type```number@@ -7756,12 +7761,10 @@ static prototype: WeChatSocket## WebAppOptions — interface```-backend: "webgl2" | "webgpu" | undefined-canvasSelector: string | undefinedcolorSpace: "gamma" | "linear" | undefinedgetViewportSize: (() => { width: number; height: number; }) | undefined-glContextHandle: number | undefinedplugins: Plugin[] | undefined+renderSurface: RenderSurfaceSource | undefinedscreenFit: ScreenScalingData | undefinedsideModules: SideModuleHost | undefinedySortLayers: number | undefineddiff --git a/sdk/src/app.ts b/sdk/src/app.tsindex fd8f43fc4..c10980d65 100644--- a/sdk/src/app.ts+++ b/sdk/src/app.ts@@ -1031,23 +1031,35 @@ export class App {// Web App Factory// =============================================================================+/**+ * How the host provides the render surface the C++ renderer binds to — the single+ * seam every platform's renderer init flows through:+ * - `gl-context`: an emscripten-registered WebGL2 context handle (web/desktop/WeChat).+ * - `webgpu`: the host acquired a GPUDevice (navigator.gpu) and passed it as the+ * module factory's `preinitializedWebGPUDevice` before instantiation; the engine+ * owns the swapchain, resolving the canvas via `canvasSelector` (default '#canvas',+ * via document.querySelector — so the canvas must be in the DOM).+ * - `default`: the module resolves its own surface (module.initRenderer()).+ *+ * NATIVE (embedded Dawn on iOS/Android) will provide its WebGPU device the same+ * `preinitializedWebGPUDevice` way, but bound to a native surface (CAMetalLayer /+ * ANativeWindow) rather than a DOM canvas — it uses `{ kind: 'webgpu' }` with+ * `canvasSelector` omitted, and the C++/glue native-surface resolution lands with+ * the native shell.+ */+export type RenderSurfaceSource =+ | { readonly kind: 'gl-context'; readonly handle: number }+ | { readonly kind: 'webgpu'; readonly canvasSelector?: string }+ | { readonly kind: 'default' };+export interface WebAppOptions {getViewportSize?: () => { width: number; height: number };- glContextHandle?: number;/**- * Render backend. 'webgpu' boots the injected-device path: the host must- * have acquired a GPUDevice (navigator.gpu) and passed it as the module- * factory's `preinitializedWebGPUDevice` before instantiation — the engine- * then owns the canvas swapchain, so no glContextHandle applies.- * Default: WebGL2.+ * How the host provides the render surface (WebGL2 context handle / WebGPU+ * device + swapchain / headless default). See {@link RenderSurfaceSource}.+ * Omitted ⇒ `{ kind: 'default' }` (module.initRenderer resolves its own).*/- backend?: 'webgl2' | 'webgpu';- /**- * CSS selector of the canvas for the WebGPU swapchain. The WebGPU glue- * resolves it with document.querySelector, so the canvas must be IN the- * DOM and reachable by this selector. Default '#canvas'.- */- canvasSelector?: string;+ renderSurface?: RenderSurfaceSource;plugins?: Plugin[];/** The realm's optional-native-module acquirer; set before plugins build so* SpinePlugin (and later physics) can pull from it. See {@link App.sideModules}. */@@ -1091,17 +1103,23 @@ export function createWebApp(module: ESEngineModule, options?: WebAppOptions): AsetLinearColorSpace(options?.colorSpace === 'linear');module.renderer_setColorSpace?.(options?.colorSpace === 'linear' ? 1 : 0);- if (options?.backend === 'webgpu') {- const size = options.getViewportSize?.() ?? { width: 800, height: 600 };- if (!module.initRendererWebGPU(options.canvasSelector ?? '#canvas', size.width, size.height)) {- throw new Error(- 'WebGPU renderer initialization failed — the module needs a ' +- 'preinitializedWebGPUDevice and a WebGPU-enabled engine build.');+ const surface: RenderSurfaceSource = options?.renderSurface ?? { kind: 'default' };+ switch (surface.kind) {+ case 'webgpu': {+ const size = options?.getViewportSize?.() ?? { width: 800, height: 600 };+ if (!module.initRendererWebGPU(surface.canvasSelector ?? '#canvas', size.width, size.height)) {+ throw new Error(+ 'WebGPU renderer initialization failed — the module needs a ' ++ 'preinitializedWebGPUDevice and a WebGPU-enabled engine build.');+ }+ break;}- } else if (options?.glContextHandle) {- module.initRendererWithContext(options.glContextHandle);- } else {- module.initRenderer();+ case 'gl-context':+ module.initRendererWithContext(surface.handle);+ break;+ case 'default':+ module.initRenderer();+ break;}// Always applied (not only when set): the renderer outlives the App on realm// reloads, so a fresh App must reset a prior session's y-sort state too.diff --git a/sdk/src/core-runtime.ts b/sdk/src/core-runtime.tsindex 2888174e1..cec1e6f72 100644--- a/sdk/src/core-runtime.ts+++ b/sdk/src/core-runtime.ts@@ -360,6 +360,7 @@ export {type Plugin,type PluginDependency,type WebAppOptions,+ type RenderSurfaceSource,} from './app';// =============================================================================diff --git a/sdk/src/wechatRuntime.ts b/sdk/src/wechatRuntime.tsindex 93cafec2c..61a31dd2e 100644--- a/sdk/src/wechatRuntime.ts+++ b/sdk/src/wechatRuntime.ts@@ -148,7 +148,7 @@ export async function initWeChatRuntime(config: WeChatRuntimeConfig): Promise<vo});const app = createWebApp(module, {- glContextHandle: glHandle,+ renderSurface: { kind: 'gl-context', handle: glHandle },ySortLayers: config.ySortLayers,colorSpace: config.colorSpace,screenFit: config.screenFit,