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): auto-generate WGSL twins for GLSL shaders on project open

esengine9631e2024f25
diff --git a/desktop/electron/main.ts b/desktop/electron/main.ts
index 2dd3f7d91..bdbb2deb2 100644
--- a/desktop/electron/main.ts
+++ b/desktop/electron/main.ts
@@ -35,6 +35,7 @@ import { loopbackServer, closeAllLoopbackServers } from './loopbackServer';
import { httpContentType } from './mimeTypes';
import { buildPlayRealm } from './buildPlayRealm';
import { ensureSdkTypes } from './syncSdkTypes';
+import { ensureProjectShaderTwins } from './shaderTwins';
import { installCrashCapture, logsDir } from './resilience';
import { mcpMode, startMcpEndpoint } from './mcpEndpoint';
import { checkForUpdate } from './updateCheck';
@@ -575,6 +576,22 @@ async function adoptRoot(root: string): Promise<string | undefined> {
}
}
+// A GLSL-only project shader can't render on WebGPU; generate its WGSL twin on
+// open (idempotent — a project whose shaders already carry twins costs only a
+// directory walk). Never throws: a converter miss must not block opening. Dev
+// only — the vendored converters aren't staged into a packaged app yet, where
+// shipped shaders are expected to carry the CI-enforced committed twins.
+const REPO_ROOT = path.join(__dirname, '..', '..');
+async function ensureTwinsForOpen(root: string): Promise<void> {
+ if (app.isPackaged) return;
+ try {
+ const r = await ensureProjectShaderTwins(root, REPO_ROOT);
+ if (r.generated.length) console.log(`[shader-twins] generated ${r.generated.length} WGSL twin(s) on open`);
+ } catch (err) {
+ console.warn('[shader-twins] ensure failed', err);
+ }
+}
+
ipcMain.handle('project:openDialog', async () => {
if (!win) return null;
const res = await dialog.showOpenDialog(win, {
@@ -583,11 +600,13 @@ ipcMain.handle('project:openDialog', async () => {
});
if (res.canceled || res.filePaths.length === 0) return null;
const opened = await openProject(res.filePaths[0]);
+ await ensureTwinsForOpen(opened.root);
return { ...opened, stagingError: await adoptRoot(opened.root) };
});
ipcMain.handle('project:open', async (_e, root: string) => {
const opened = await openProject(root);
+ await ensureTwinsForOpen(opened.root);
return { ...opened, stagingError: await adoptRoot(opened.root) };
});
diff --git a/desktop/electron/shaderTwins.ts b/desktop/electron/shaderTwins.ts
new file mode 100644
index 000000000..f6af698cd
--- /dev/null
+++ b/desktop/electron/shaderTwins.ts
@@ -0,0 +1,101 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+/**
+ * @file shaderTwins.ts — editor-side GLSL→WGSL twin generation on project open.
+ *
+ * A `.esshader` authored in GLSL only fails to compile on the WebGPU backend
+ * (no WGSL twin). Rather than make authors run `tools/gen-shader-twins.mjs` by
+ * hand, the editor generates the twin for any twin-less project shader when the
+ * project opens — GLSL stays the single authored source, the WGSL twin is a
+ * generated derivative written back beside it, and both the editor viewport and
+ * the exported game render on WebGPU with no author action.
+ *
+ * The converter pipeline (vendored glslang + naga wasm, driven through the engine
+ * wasm's `esshader_cookInfo`) is Node-only — naga runs under `node:wasi` — so it
+ * lives here in the main process. The generator module is imported at runtime by
+ * absolute path so the vite-electron bundler leaves it (and its wasm) external.
+ *
+ * Dev-only for now: the vendored converters are not yet staged into a packaged
+ * app, so a packaged editor skips generation (a shipped project's shaders are
+ * expected to carry committed twins, enforced by the CI twin-coverage guard).
+ */
+import { readFile, readdir } from 'node:fs/promises';
+import path from 'node:path';
+import { pathToFileURL } from 'node:url';
+
+/** Recursively collect `.esshader` files under `dir` (skips dot-dirs like
+ * `.esengine` staging and `node_modules`). */
+async function findEsshaders(dir: string, out: string[] = []): Promise<string[]> {
+ let entries;
+ try {
+ entries = await readdir(dir, { withFileTypes: true });
+ } catch {
+ return out;
+ }
+ for (const e of entries) {
+ if (e.name.startsWith('.') || e.name === 'node_modules') continue;
+ const full = path.join(dir, e.name);
+ if (e.isDirectory()) await findEsshaders(full, out);
+ else if (e.name.endsWith('.esshader')) out.push(full);
+ }
+ return out;
+}
+
+interface TwinGenerator {
+ loadTwinModule(): Promise<{ esshader_cookInfo(source: string, features: string): unknown }>;
+ processFile(
+ module: unknown,
+ file: string,
+ opts: { check?: boolean; force?: boolean },
+ ): Promise<{ file: string; status: string }>;
+}
+
+/**
+ * Ensure every twin-less project `.esshader` gets a generated WGSL twin. The
+ * cheap string scan runs first, so a project whose shaders already carry twins
+ * (or have none) costs one directory walk and never loads the heavy engine +
+ * converter wasm. A shader using `#pragma switch` is left alone — its
+ * per-permutation twins can't be auto-generated (it must hand-author them).
+ *
+ * Never throws: a converter failure on one shader is logged and skipped so it
+ * can't block project open. Returns what happened for logging/telemetry.
+ */
+export async function ensureProjectShaderTwins(
+ root: string,
+ repoRoot: string,
+): Promise<{ generated: string[]; failed: string[]; skipped: string[] }> {
+ const result = { generated: [] as string[], failed: [] as string[], skipped: [] as string[] };
+
+ const files = await findEsshaders(root);
+ const needy: string[] = [];
+ for (const f of files) {
+ const src = await readFile(f, 'utf8').catch(() => '');
+ if (src.includes('#pragma fragment wgsl')) continue; // already has a twin
+ if (src.includes('#pragma switch')) { result.skipped.push(f); continue; }
+ needy.push(f);
+ }
+ if (needy.length === 0) return result;
+
+ let gen: TwinGenerator;
+ try {
+ const url = pathToFileURL(path.join(repoRoot, 'tools', 'gen-shader-twins.mjs')).href;
+ gen = (await import(url)) as unknown as TwinGenerator;
+ } catch (err) {
+ console.warn('[shader-twins] generator unavailable — skipping', err);
+ return result;
+ }
+
+ const module = await gen.loadTwinModule();
+ for (const f of needy) {
+ try {
+ const r = await gen.processFile(module, f, {});
+ if (r.status === 'generated') result.generated.push(f);
+ else if (r.status === 'skipped-switches') result.skipped.push(f);
+ } catch (err) {
+ result.failed.push(f);
+ console.warn(`[shader-twins] generation failed for ${path.relative(root, f)} —`,
+ err instanceof Error ? err.message : String(err));
+ }
+ }
+ return result;
+}
diff --git a/tools/gen-shader-twins.mjs b/tools/gen-shader-twins.mjs
index 699101d0a..4bb5ceafb 100644
--- a/tools/gen-shader-twins.mjs
+++ b/tools/gen-shader-twins.mjs
@@ -271,7 +271,14 @@ function stripGeneratedTwins(source) {
return source.replace(/\n?#pragma (?:vertex|fragment) wgsl full\n[\s\S]*?#pragma end\n?/g, '\n');
}
-async function processFile(module, file, opts) {
+/** Load the engine wasm module (esshader_cookInfo) the twin pipeline assembles
+ * through — shared by the CLI and the editor's on-open generation. */
+export async function loadTwinModule() {
+ const { default: createModule } = await import(pathToFileURL(WASM_GLUE).href);
+ return createModule();
+}
+
+export async function processFile(module, file, opts) {
let source = await readFile(file, 'utf8');
const hadGenerated = /#pragma (?:vertex|fragment) wgsl full/.test(source);
if (opts.force && hadGenerated) source = stripGeneratedTwins(source);
@@ -318,8 +325,7 @@ async function main() {
process.exit(2);
}
- const { default: createModule } = await import(pathToFileURL(WASM_GLUE).href);
- const module = await createModule();
+ const module = await loadTwinModule();
let pending = 0;
let failed = 0;
@@ -338,4 +344,8 @@ async function main() {
process.exitCode = failed > 0 || pending > 0 ? 1 : 0;
}
-await main();
+// Run as a CLI only when invoked directly (`node tools/gen-shader-twins.mjs …`);
+// stays importable as a module (the editor's on-open twin generation).
+if (process.argv[1] && pathToFileURL(process.argv[1]).href === import.meta.url) {
+ await main();
+}