Skip to content

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.

refactor(platform): unify renderer init behind a neutral RenderSurfaceSource

yhhf7288d5bd2b1
diff --git a/desktop/src/engine/EngineHost.ts b/desktop/src/engine/EngineHost.ts
index 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 can
diff --git a/desktop/src/gameHost.ts b/desktop/src/gameHost.ts
index 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.ts
index 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.ts
index 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.md
index 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 | undefined
colorSpace: "gamma" | "linear" | undefined
getViewportSize: (() => { width: number; height: number; }) | undefined
-glContextHandle: number | undefined
plugins: Plugin[] | undefined
+renderSurface: RenderSurfaceSource | undefined
screenFit: ScreenScalingData | undefined
sideModules: SideModuleHost | undefined
wasmBaseUrl: string | undefined
@@ -5092,6 +5090,13 @@ text: number
triangles: 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 | undefined
colorSpace: "gamma" | "linear" | undefined
getViewportSize: (() => { width: number; height: number; }) | undefined
-glContextHandle: number | undefined
plugins: Plugin[] | undefined
+renderSurface: RenderSurfaceSource | undefined
screenFit: ScreenScalingData | undefined
sideModules: SideModuleHost | undefined
ySortLayers: number | undefined
diff --git a/sdk/etc/index.node.api.md b/sdk/etc/index.node.api.md
index 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 | undefined
colorSpace: "gamma" | "linear" | undefined
getViewportSize: (() => { width: number; height: number; }) | undefined
-glContextHandle: number | undefined
plugins: Plugin[] | undefined
+renderSurface: RenderSurfaceSource | undefined
screenFit: ScreenScalingData | undefined
sideModules: SideModuleHost | undefined
wasmBaseUrl: string | undefined
@@ -5087,6 +5085,13 @@ text: number
triangles: 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 | undefined
colorSpace: "gamma" | "linear" | undefined
getViewportSize: (() => { width: number; height: number; }) | undefined
-glContextHandle: number | undefined
plugins: Plugin[] | undefined
+renderSurface: RenderSurfaceSource | undefined
screenFit: ScreenScalingData | undefined
sideModules: SideModuleHost | undefined
ySortLayers: number | undefined
diff --git a/sdk/etc/wechat.api.md b/sdk/etc/wechat.api.md
index 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 | undefined
colorSpace: "gamma" | "linear" | undefined
getViewportSize: (() => { width: number; height: number; }) | undefined
-glContextHandle: number | undefined
plugins: Plugin[] | undefined
+renderSurface: RenderSurfaceSource | undefined
screenFit: ScreenScalingData | undefined
sideModules: SideModuleHost | undefined
wasmBaseUrl: string | undefined
@@ -5094,6 +5092,13 @@ text: number
triangles: 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 | undefined
colorSpace: "gamma" | "linear" | undefined
getViewportSize: (() => { width: number; height: number; }) | undefined
-glContextHandle: number | undefined
plugins: Plugin[] | undefined
+renderSurface: RenderSurfaceSource | undefined
screenFit: ScreenScalingData | undefined
sideModules: SideModuleHost | undefined
ySortLayers: number | undefined
diff --git a/sdk/src/app.ts b/sdk/src/app.ts
index 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): A
setLinearColorSpace(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.ts
index 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.ts
index 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,