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.

feat(editor): switch the viewport between WebGL2 and WebGPU (Settings → Renderer)

yhh012bfc624af0
diff --git a/desktop/src/engine/EngineHost.ts b/desktop/src/engine/EngineHost.ts
index 62ba3b15b..391b2117a 100644
--- a/desktop/src/engine/EngineHost.ts
+++ b/desktop/src/engine/EngineHost.ts
@@ -18,6 +18,7 @@ import {
import type { App, ESEngineModule, ResourceDef, SubsystemStatus, SceneData } from 'esengine';
import { SpinePlugin } from 'esengine/spine';
import { SceneLoader } from './SceneLoader';
+import { useSettings } from '@/store/settingsStore';
import { loadEditorSpine } from './spineLoad';
import { checkEngineBuild } from './EngineGuard';
import type { ReadonlyWorldT, WorldT } from './schema';
@@ -49,6 +50,8 @@ class EngineHostImpl {
private module_: ESEngineModule | null = null;
private targetFps_ = 0;
private booted = false;
+ /** The GPU backend the viewport actually booted with (after availability fallback). */
+ activeBackend: 'webgl2' | 'webgpu' = 'webgl2';
private resizeObserver: ResizeObserver | null = null;
private readonly statusStore = createStore<EngineSnapshot>(() => ({ status: 'idle', error: null }));
@@ -360,12 +363,36 @@ class EngineHostImpl {
this.setStatus('booting');
try {
const canvas = this.ensureCanvas();
- await this.bootCore(canvas, { runLoop: true, loadInitialScene: true });
+ const backend = await this.resolveBackend();
+ await this.bootCore(canvas, { runLoop: true, loadInitialScene: true, backend });
} catch (err) {
this.swallowUnwind(err);
}
}
+ /**
+ * The viewport's GPU backend: the persisted `renderer.backend` setting, with a
+ * safe fall back to WebGL2 when WebGPU is requested but unavailable (no
+ * `navigator.gpu`, or no adapter). Probed BEFORE the canvas is touched — a
+ * canvas cannot switch context types once one is acquired.
+ */
+ private async resolveBackend(): Promise<'webgl2' | 'webgpu'> {
+ const requested = useSettings.getState().getValue<string>('renderer.backend');
+ if (requested !== 'webgpu') return 'webgl2';
+ const gpu = (navigator as unknown as { gpu?: { requestAdapter(): Promise<unknown> } }).gpu;
+ if (!gpu) {
+ console.warn('[engine] WebGPU requested, but navigator.gpu is unavailable — using WebGL2.');
+ return 'webgl2';
+ }
+ try {
+ if (await gpu.requestAdapter()) return 'webgpu';
+ console.warn('[engine] WebGPU requested, but no adapter is available — using WebGL2.');
+ } catch (e) {
+ console.warn('[engine] WebGPU adapter probe failed — using WebGL2.', e);
+ }
+ return 'webgl2';
+ }
+
/**
* Boot the engine without a DOM viewport or a self-driving loop, for the
* headless render host: a fixed-size
@@ -404,6 +431,8 @@ class EngineHostImpl {
opts: { runLoop: boolean; loadInitialScene: boolean; backend?: 'webgl2' | 'webgpu' },
) {
const backend = opts.backend ?? 'webgl2';
+ this.activeBackend = backend;
+ console.info(`[engine] backend: ${backend}`);
// Early build-consistency check: compare the wasm's stamped manifest
// (variant / ABI / provenance) against this SDK before the heavy
// instantiate. Advisory only — the runtime bridge handshake is the
diff --git a/desktop/src/settings/editorSettings.ts b/desktop/src/settings/editorSettings.ts
index 514cb36cd..a199e73da 100644
--- a/desktop/src/settings/editorSettings.ts
+++ b/desktop/src/settings/editorSettings.ts
@@ -24,6 +24,7 @@ settingsRegistry.registerSection({ id: 'viewport', label: 'Viewport', category:
settingsRegistry.registerSection({ id: 'performance', label: 'Performance', category: 'editor', order: 3 });
settingsRegistry.registerSection({ id: 'shortcuts', label: 'Keyboard Shortcuts', category: 'editor', order: 4 });
settingsRegistry.registerSection({ id: 'console', label: 'Console', category: 'editor', order: 5 });
+settingsRegistry.registerSection({ id: 'renderer', label: 'Renderer', category: 'editor', order: 6 });
// ── Appearance (store-owned, applied via CSS) ───────────────────────────────
settingsRegistry.register({
@@ -61,6 +62,25 @@ settingsRegistry.register({
},
});
+// ── Renderer (read at engine boot; the GfxDevice backend seam) ──────────────
+settingsRegistry.register({
+ id: 'renderer.backend',
+ type: 'enum',
+ scope: 'editor',
+ section: 'renderer',
+ group: 'Renderer',
+ label: 'Graphics backend',
+ description:
+ 'Which GPU API the viewport renders through. Applies on engine reload (Ctrl+R). ' +
+ 'WebGPU falls back to WebGL2 automatically if no adapter is available.',
+ default: 'webgl2',
+ segmented: true,
+ options: [
+ { value: 'webgl2', label: 'WebGL2' },
+ { value: 'webgpu', label: 'WebGPU' },
+ ],
+});
+
// ── Viewport (bound to editorStore — one source with the viewport toolbar) ───
const ed = () => useEditorStore.getState();