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(render): a WebGPU run says which adapter drew it

yhhae33ff01abba
diff --git a/desktop/scripts/headless-verify.mjs b/desktop/scripts/headless-verify.mjs
index 3a6905994..48aa21e8a 100644
--- a/desktop/scripts/headless-verify.mjs
+++ b/desktop/scripts/headless-verify.mjs
@@ -171,7 +171,9 @@ app.whenReady().then(async () => {
webPreferences: { offscreen: false },
});
onRendererConsole(win.webContents, (msg) => {
- if (/error|fail|unwind|exception|webgl|recovery|placeholder/i.test(msg)) console.log('[renderer]', msg.slice(0, 240));
+ // `webgpu` spelled out: "webgl" does not match it, so the second backend's
+ // boot — including which adapter served it — was the one thing never shown.
+ if (/error|fail|unwind|exception|webgl|webgpu|adapter|recovery|placeholder/i.test(msg)) console.log('[renderer]', msg.slice(0, 240));
});
await win.loadURL(url);
diff --git a/desktop/src/engine/EngineHost.ts b/desktop/src/engine/EngineHost.ts
index a3adec669..9f8b648ab 100644
--- a/desktop/src/engine/EngineHost.ts
+++ b/desktop/src/engine/EngineHost.ts
@@ -608,6 +608,7 @@ class EngineHostImpl {
// it in silence, which reads as a black pass with nothing wrong.
const gpu = await acquireWebGPUDevice('webgpu', (m) => console.error(m));
if (!gpu.device) throw new Error(`WebGPU is not available: ${gpu.reason}`);
+ console.info(`[engine] webgpu adapter: ${gpu.adapter ?? 'unreported'}`);
moduleArg.preinitializedWebGPUDevice = gpu.device;
// The swapchain glue resolves the canvas by document.querySelector, so
// it must be connected (the headless host never attaches it to a view).
diff --git a/sdk/etc/index.api.md b/sdk/etc/index.api.md
index 40eb97b11..f560dc56a 100644
--- a/sdk/etc/index.api.md
+++ b/sdk/etc/index.api.md
@@ -8942,6 +8942,7 @@ features: { has(name: string): boolean; } | undefined
## WebGPUBootResult — interface @experimental
```
+adapter: string | undefined
device: unknown
reason: string | undefined
```
diff --git a/sdk/etc/index.native.api.md b/sdk/etc/index.native.api.md
index b77c95f3f..f99cfcfe8 100644
--- a/sdk/etc/index.native.api.md
+++ b/sdk/etc/index.native.api.md
@@ -9135,6 +9135,7 @@ features: { has(name: string): boolean; } | undefined
## WebGPUBootResult — interface @experimental
```
+adapter: string | undefined
device: unknown
reason: string | undefined
```
diff --git a/sdk/etc/index.node.api.md b/sdk/etc/index.node.api.md
index 407ccc332..f5cd79de8 100644
--- a/sdk/etc/index.node.api.md
+++ b/sdk/etc/index.node.api.md
@@ -8937,6 +8937,7 @@ features: { has(name: string): boolean; } | undefined
## WebGPUBootResult — interface @experimental
```
+adapter: string | undefined
device: unknown
reason: string | undefined
```
diff --git a/sdk/etc/minigame.api.md b/sdk/etc/minigame.api.md
index fc9b26f3f..fde0a951e 100644
--- a/sdk/etc/minigame.api.md
+++ b/sdk/etc/minigame.api.md
@@ -9182,6 +9182,7 @@ features: { has(name: string): boolean; } | undefined
## WebGPUBootResult — interface @experimental
```
+adapter: string | undefined
device: unknown
reason: string | undefined
```
diff --git a/sdk/etc/wechat.api.md b/sdk/etc/wechat.api.md
index a215db285..0804947c4 100644
--- a/sdk/etc/wechat.api.md
+++ b/sdk/etc/wechat.api.md
@@ -8964,6 +8964,7 @@ features: { has(name: string): boolean; } | undefined
## WebGPUBootResult — interface @experimental
```
+adapter: string | undefined
device: unknown
reason: string | undefined
```
diff --git a/sdk/src/render/webgpuBoot.ts b/sdk/src/render/webgpuBoot.ts
index b8281b7f1..de8ff74e8 100644
--- a/sdk/src/render/webgpuBoot.ts
+++ b/sdk/src/render/webgpuBoot.ts
@@ -21,15 +21,39 @@ export interface WebGPUBootResult {
device: unknown | null;
/** Why WebGPU was not used, for a host that wants to say so. */
reason?: string;
+ /**
+ * Which adapter served the device. An unrecognized `--use-webgpu-adapter` is
+ * ignored in silence, so this is the only thing that says whether hardware or
+ * a software rasterizer drew the frame.
+ */
+ adapter?: string;
+}
+
+interface AdapterInfo {
+ vendor?: string;
+ architecture?: string;
+ device?: string;
+ description?: string;
}
interface GpuLike {
requestAdapter(): Promise<{
features?: { has(name: string): boolean };
+ info?: AdapterInfo;
+ isFallbackAdapter?: boolean;
requestDevice(descriptor?: { requiredFeatures?: string[] }): Promise<unknown>;
} | null>;
}
+function describeAdapter(adapter: {
+ info?: AdapterInfo; isFallbackAdapter?: boolean;
+}): string {
+ const info = adapter.info ?? {};
+ const named = [info.vendor, info.architecture, info.device].filter(Boolean).join(' ');
+ const kind = adapter.isFallbackAdapter ? 'fallback' : 'default';
+ return `${named || info.description || 'unnamed adapter'} (${kind})`;
+}
+
const gpuOf = (): GpuLike | undefined =>
(globalThis.navigator as unknown as { gpu?: GpuLike } | undefined)?.gpu;
@@ -63,7 +87,7 @@ export async function acquireWebGPUDevice(
onError(`[webgpu] uncaptured error: ${msg ?? String(e)}`);
});
}
- return { device };
+ return { device, adapter: describeAdapter(adapter) };
} catch (e) {
return { device: null, reason: `WebGPU device request failed: ${String(e)}` };
}
diff --git a/tools/renderScenes.mjs b/tools/renderScenes.mjs
index 72ef739cd..e871031e8 100644
--- a/tools/renderScenes.mjs
+++ b/tools/renderScenes.mjs
@@ -22,14 +22,10 @@
/** Cheapest tier a scene runs at; tiers are cumulative. */
export const TIERS = ['pr', 'nightly'];
-/**
- * What still separates the second backend from the first: a CI runner has no
- * Dawn adapter, so nothing here runs it there. On a machine that has one all 85
- * pass — measured, not assumed (2026-08-17, `--tier nightly --backend webgpu`).
- * A boot with no device throws rather than falling back, so a pass is a pass on
- * the backend it names.
- */
-export const WEBGPU_GAP = 'no adapter on a CI runner; where one exists all 85 passed on 2026-08-17'
+/** All 85 pass on Electron's bundled SwiftShader, the software adapter a GPU-less
+ * runner would use — so CI's failure is that runner's Vulkan stack, not Dawn's
+ * ability to drive a software rasterizer. Only the boot log names the adapter. */
+export const WEBGPU_GAP = 'no step runs these on CI; all 85 passed on SwiftShader on 2026-08-17'
+ ' (`--tier nightly --backend webgpu`)';
/**