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
feat(editor): auto-generate WGSL twins for GLSL shaders on project open
esengine9631e2024f25
diff --git a/desktop/electron/main.ts b/desktop/electron/main.tsindex 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.tsnew file mode 100644index 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.mjsindex 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();+}