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(shaders): detect stale WGSL twins by hashing the authored GLSL
esenginecaab6fcc8819
diff --git a/desktop/electron/shaderTwins.ts b/desktop/electron/shaderTwins.tsindex f6af698cd..a5e6a8aff 100644--- a/desktop/electron/shaderTwins.ts+++ b/desktop/electron/shaderTwins.ts@@ -42,6 +42,9 @@ async function findEsshaders(dir: string, out: string[] = []): Promise<string[]>}interface TwinGenerator {+ /** True when the shader has no twin, or a generated twin whose stored+ * source-hash no longer matches its GLSL (stale). Pure + cheap (no engine). */+ needsTwin(source: string): boolean;loadTwinModule(): Promise<{ esshader_cookInfo(source: string, features: string): unknown }>;processFile(module: unknown,@@ -67,15 +70,11 @@ export async function ensureProjectShaderTwins(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;+ if (files.length === 0) return result;+ // Import the generator up front — cheap (pure JS; the engine + converter wasm+ // load only in loadTwinModule below) — so its needsTwin decides which shaders+ // are missing OR stale (a twin whose source-hash no longer matches its GLSL).let gen: TwinGenerator;try {const url = pathToFileURL(path.join(repoRoot, 'tools', 'gen-shader-twins.mjs')).href;@@ -85,6 +84,13 @@ export async function ensureProjectShaderTwins(return result;}+ const needy: string[] = [];+ for (const f of files) {+ const src = await readFile(f, 'utf8').catch(() => '');+ if (gen.needsTwin(src)) needy.push(f);+ }+ if (needy.length === 0) return result;+const module = await gen.loadTwinModule();for (const f of needy) {try {diff --git a/desktop/public/scenes/mat-builtin-lit/lit.esshader b/desktop/public/scenes/mat-builtin-lit/lit.esshaderindex 8a8f92832..e7cc8723f 100644--- a/desktop/public/scenes/mat-builtin-lit/lit.esshader+++ b/desktop/public/scenes/mat-builtin-lit/lit.esshader@@ -26,6 +26,7 @@ void main() {#pragma vertex wgsl full// GENERATED by tools/gen-shader-twins.mjs (glslang + naga) - do not edit.// Regenerate after changing the GLSL stages above.+// source-hash: 9f608a54b0f5c530struct gl_PerVertex {@builtin(position) gl_Position: vec4<f32>,gl_PointSize: f32,@@ -101,6 +102,7 @@ fn vs_main(@location(0) a_position: vec2<f32>, @location(1) a_color: vec4<f32>,#pragma fragment wgsl full// GENERATED by tools/gen-shader-twins.mjs (glslang + naga) - do not edit.// Regenerate after changing the GLSL stages above.+// source-hash: 9f608a54b0f5c530struct Light2D {posDir: vec4<f32>,color: vec4<f32>,diff --git a/desktop/public/scenes/mat-dissolve/dissolve.esshader b/desktop/public/scenes/mat-dissolve/dissolve.esshaderindex dca1b762d..5810c4243 100644--- a/desktop/public/scenes/mat-dissolve/dissolve.esshader+++ b/desktop/public/scenes/mat-dissolve/dissolve.esshader@@ -39,6 +39,7 @@ void main() {#pragma vertex wgsl full// GENERATED by tools/gen-shader-twins.mjs (glslang + naga) - do not edit.// Regenerate after changing the GLSL stages above.+// source-hash: 99e3d67aae0be3c6struct gl_PerVertex {@builtin(position) gl_Position: vec4<f32>,gl_PointSize: f32,@@ -108,6 +109,7 @@ fn vs_main(@location(0) a_position: vec2<f32>, @location(1) a_color: vec4<f32>,#pragma fragment wgsl full// GENERATED by tools/gen-shader-twins.mjs (glslang + naga) - do not edit.// Regenerate after changing the GLSL stages above.+// source-hash: 99e3d67aae0be3c6struct MaterialConstants {u_progress: f32,u_edgeColor: vec4<f32>,diff --git a/desktop/public/scenes/mat-graph/graph-tint.esshader b/desktop/public/scenes/mat-graph/graph-tint.esshaderindex 5044570a7..1eea44c2b 100644--- a/desktop/public/scenes/mat-graph/graph-tint.esshader+++ b/desktop/public/scenes/mat-graph/graph-tint.esshader@@ -42,6 +42,7 @@ void main() {#pragma vertex wgsl full// GENERATED by tools/gen-shader-twins.mjs (glslang + naga) - do not edit.// Regenerate after changing the GLSL stages above.+// source-hash: 17d9cf90b8470378struct gl_PerVertex {@builtin(position) gl_Position: vec4<f32>,gl_PointSize: f32,@@ -114,6 +115,7 @@ fn vs_main(@location(0) a_position: vec2<f32>, @location(1) a_color: vec4<f32>,#pragma fragment wgsl full// GENERATED by tools/gen-shader-twins.mjs (glslang + naga) - do not edit.// Regenerate after changing the GLSL stages above.+// source-hash: 17d9cf90b8470378struct MaterialConstants {u_tint: vec4<f32>,}diff --git a/desktop/public/scenes/mat-lit-flatnormal/lit-fn.esshader b/desktop/public/scenes/mat-lit-flatnormal/lit-fn.esshaderindex 9e04a3fe6..69fc3db76 100644--- a/desktop/public/scenes/mat-lit-flatnormal/lit-fn.esshader+++ b/desktop/public/scenes/mat-lit-flatnormal/lit-fn.esshader@@ -50,6 +50,7 @@ void main() {#pragma vertex wgsl full// GENERATED by tools/gen-shader-twins.mjs (glslang + naga) - do not edit.// Regenerate after changing the GLSL stages above.+// source-hash: 2109a83ca59fdb20struct gl_PerVertex {@builtin(position) gl_Position: vec4<f32>,gl_PointSize: f32,@@ -121,6 +122,7 @@ fn vs_main(@location(0) a_position: vec2<f32>, @location(1) a_color: vec4<f32>,#pragma fragment wgsl full// GENERATED by tools/gen-shader-twins.mjs (glslang + naga) - do not edit.// Regenerate after changing the GLSL stages above.+// source-hash: 2109a83ca59fdb20struct Light2D {posDir: vec4<f32>,color: vec4<f32>,diff --git a/desktop/public/scenes/mat-lit-normal/lit-normal.esshader b/desktop/public/scenes/mat-lit-normal/lit-normal.esshaderindex d853b13c0..261c7f5af 100644--- a/desktop/public/scenes/mat-lit-normal/lit-normal.esshader+++ b/desktop/public/scenes/mat-lit-normal/lit-normal.esshader@@ -50,6 +50,7 @@ void main() {#pragma vertex wgsl full// GENERATED by tools/gen-shader-twins.mjs (glslang + naga) - do not edit.// Regenerate after changing the GLSL stages above.+// source-hash: 60ae4382caf672f0struct gl_PerVertex {@builtin(position) gl_Position: vec4<f32>,gl_PointSize: f32,@@ -121,6 +122,7 @@ fn vs_main(@location(0) a_position: vec2<f32>, @location(1) a_color: vec4<f32>,#pragma fragment wgsl full// GENERATED by tools/gen-shader-twins.mjs (glslang + naga) - do not edit.// Regenerate after changing the GLSL stages above.+// source-hash: 60ae4382caf672f0struct Light2D {posDir: vec4<f32>,color: vec4<f32>,diff --git a/desktop/public/scenes/mat-lit/lit.esshader b/desktop/public/scenes/mat-lit/lit.esshaderindex a4644ce0f..33cb4aacb 100644--- a/desktop/public/scenes/mat-lit/lit.esshader+++ b/desktop/public/scenes/mat-lit/lit.esshader@@ -49,6 +49,7 @@ void main() {#pragma vertex wgsl full// GENERATED by tools/gen-shader-twins.mjs (glslang + naga) - do not edit.// Regenerate after changing the GLSL stages above.+// source-hash: 95a1f35f723b831cstruct gl_PerVertex {@builtin(position) gl_Position: vec4<f32>,gl_PointSize: f32,@@ -116,6 +117,7 @@ fn vs_main(@location(0) a_position: vec2<f32>, @location(1) a_color: vec4<f32>,#pragma fragment wgsl full// GENERATED by tools/gen-shader-twins.mjs (glslang + naga) - do not edit.// Regenerate after changing the GLSL stages above.+// source-hash: 95a1f35f723b831cstruct Light2D {posDir: vec4<f32>,color: vec4<f32>,diff --git a/desktop/public/scenes/mat-tex/masked.esshader b/desktop/public/scenes/mat-tex/masked.esshaderindex 4ec42a511..ee3c12822 100644--- a/desktop/public/scenes/mat-tex/masked.esshader+++ b/desktop/public/scenes/mat-tex/masked.esshader@@ -41,6 +41,7 @@ void main() {#pragma vertex wgsl full// GENERATED by tools/gen-shader-twins.mjs (glslang + naga) - do not edit.// Regenerate after changing the GLSL stages above.+// source-hash: 70fc4540fdcdb04astruct gl_PerVertex {@builtin(position) gl_Position: vec4<f32>,gl_PointSize: f32,@@ -107,6 +108,7 @@ fn vs_main(@location(0) a_position: vec2<f32>, @location(1) a_color: vec4<f32>,#pragma fragment wgsl full// GENERATED by tools/gen-shader-twins.mjs (glslang + naga) - do not edit.// Regenerate after changing the GLSL stages above.+// source-hash: 70fc4540fdcdb04astruct TimeConstants {u_time: vec4<f32>,u_viewport: vec4<f32>,diff --git a/examples/effects-gallery/assets/materials/hit-flash.esshader b/examples/effects-gallery/assets/materials/hit-flash.esshaderindex c5e68d3e9..ffb62b204 100644--- a/examples/effects-gallery/assets/materials/hit-flash.esshader+++ b/examples/effects-gallery/assets/materials/hit-flash.esshader@@ -24,6 +24,7 @@ void main() {#pragma vertex wgsl full// GENERATED by tools/gen-shader-twins.mjs (glslang + naga) - do not edit.// Regenerate after changing the GLSL stages above.+// source-hash: 1c3115bd7b73f674struct gl_PerVertex {@builtin(position) gl_Position: vec4<f32>,gl_PointSize: f32,@@ -91,6 +92,7 @@ fn vs_main(@location(0) a_position: vec2<f32>, @location(1) a_color: vec4<f32>,#pragma fragment wgsl full// GENERATED by tools/gen-shader-twins.mjs (glslang + naga) - do not edit.// Regenerate after changing the GLSL stages above.+// source-hash: 1c3115bd7b73f674struct MaterialConstants {u_flash: f32,u_flashColor: vec4<f32>,diff --git a/examples/effects-gallery/assets/materials/outline.esshader b/examples/effects-gallery/assets/materials/outline.esshaderindex 026cec7b9..8abf34dff 100644--- a/examples/effects-gallery/assets/materials/outline.esshader+++ b/examples/effects-gallery/assets/materials/outline.esshader@@ -33,6 +33,7 @@ void main() {#pragma vertex wgsl full// GENERATED by tools/gen-shader-twins.mjs (glslang + naga) - do not edit.// Regenerate after changing the GLSL stages above.+// source-hash: 0d65463ea0c29816struct gl_PerVertex {@builtin(position) gl_Position: vec4<f32>,gl_PointSize: f32,@@ -100,6 +101,7 @@ fn vs_main(@location(0) a_position: vec2<f32>, @location(1) a_color: vec4<f32>,#pragma fragment wgsl full// GENERATED by tools/gen-shader-twins.mjs (glslang + naga) - do not edit.// Regenerate after changing the GLSL stages above.+// source-hash: 0d65463ea0c29816struct MaterialConstants {u_outlineColor: vec4<f32>,u_outlineWidth: f32,diff --git a/examples/effects-gallery/assets/materials/pixelate.esshader b/examples/effects-gallery/assets/materials/pixelate.esshaderindex b9505d72a..3abd64bec 100644--- a/examples/effects-gallery/assets/materials/pixelate.esshader+++ b/examples/effects-gallery/assets/materials/pixelate.esshader@@ -22,6 +22,7 @@ void main() {#pragma vertex wgsl full// GENERATED by tools/gen-shader-twins.mjs (glslang + naga) - do not edit.// Regenerate after changing the GLSL stages above.+// source-hash: 2e7de16a41174f41struct gl_PerVertex {@builtin(position) gl_Position: vec4<f32>,gl_PointSize: f32,@@ -88,6 +89,7 @@ fn vs_main(@location(0) a_position: vec2<f32>, @location(1) a_color: vec4<f32>,#pragma fragment wgsl full// GENERATED by tools/gen-shader-twins.mjs (glslang + naga) - do not edit.// Regenerate after changing the GLSL stages above.+// source-hash: 2e7de16a41174f41struct MaterialConstants {u_pixels: f32,}diff --git a/examples/effects-gallery/assets/materials/uv-scroll.esshader b/examples/effects-gallery/assets/materials/uv-scroll.esshaderindex 89382357f..b8202a32b 100644--- a/examples/effects-gallery/assets/materials/uv-scroll.esshader+++ b/examples/effects-gallery/assets/materials/uv-scroll.esshader@@ -23,6 +23,7 @@ void main() {#pragma vertex wgsl full// GENERATED by tools/gen-shader-twins.mjs (glslang + naga) - do not edit.// Regenerate after changing the GLSL stages above.+// source-hash: 8ae602b222f8cbdcstruct gl_PerVertex {@builtin(position) gl_Position: vec4<f32>,gl_PointSize: f32,@@ -89,6 +90,7 @@ fn vs_main(@location(0) a_position: vec2<f32>, @location(1) a_color: vec4<f32>,#pragma fragment wgsl full// GENERATED by tools/gen-shader-twins.mjs (glslang + naga) - do not edit.// Regenerate after changing the GLSL stages above.+// source-hash: 8ae602b222f8cbdcstruct TimeConstants {u_time: vec4<f32>,u_viewport: vec4<f32>,diff --git a/sdk/tests/shader-twins.test.ts b/sdk/tests/shader-twins.test.tsindex b77ee4c0c..8460f271c 100644--- a/sdk/tests/shader-twins.test.ts+++ b/sdk/tests/shader-twins.test.ts@@ -79,3 +79,37 @@ describe('embedded .esshader structure', () => {}}});++// The staleness contract behind cook-time + editor twin (re)generation: a+// generated twin stores a hash of the authored GLSL, so `needsTwin` is true when+// the twin is missing OR the GLSL changed under it (stale) — but not when only+// the generated twin body changed. This is what makes "GLSL is the single source,+// WGSL is a derivative" hold — the derivative provably tracks the source.+const gen = (await import('../../tools/gen-shader-twins.mjs')) as unknown as {+ needsTwin(s: string): boolean;+ sourceHash(s: string): string;+};+describe('gen-shader-twins needsTwin / sourceHash (staleness)', () => {+ const glsl = '#pragma shader "T"\n#pragma fragment\nvoid main() { }\n#pragma end\n';+ const twin = (hash: string | null) =>+ `${glsl}\n#pragma fragment wgsl full\n` ++ (hash ? `// source-hash: ${hash}\n` : '') ++ '@fragment fn fs_main() { }\n#pragma end\n';++ it('no twin → needs one', () => expect(gen.needsTwin(glsl)).toBe(true));+ it('fresh generated twin (matching hash) → up to date', () =>+ expect(gen.needsTwin(twin(gen.sourceHash(glsl)))).toBe(false));+ it('stale generated twin (wrong hash) → needs regen', () =>+ expect(gen.needsTwin(twin('deadbeefdeadbeef'))).toBe(true));+ it('generated twin with no stored hash → needs regen (legacy)', () =>+ expect(gen.needsTwin(twin(null))).toBe(true));+ it('hand-authored (non-full) twin → left alone', () =>+ expect(gen.needsTwin(`${glsl}\n#pragma fragment wgsl\n@fragment fn fs_main() { }\n#pragma end\n`)).toBe(false));+ it('#pragma switch shader → never auto-generated', () =>+ expect(gen.needsTwin(`${glsl}#pragma switch FOO default(off)\n`)).toBe(false));+ it('editing only the twin body does not stale it; editing the GLSL does', () => {+ const fresh = twin(gen.sourceHash(glsl));+ expect(gen.needsTwin(fresh.replace('fs_main', 'fs_main_x'))).toBe(false);+ expect(gen.needsTwin(fresh.replace('void main() { }', 'void main() { discard; }'))).toBe(true);+ });+});diff --git a/tools/gen-shader-twins.mjs b/tools/gen-shader-twins.mjsindex 4bb5ceafb..36bf39c19 100644--- a/tools/gen-shader-twins.mjs+++ b/tools/gen-shader-twins.mjs@@ -38,6 +38,7 @@* says so per file.*/import { mkdtemp, readFile, rm, writeFile } from 'node:fs/promises';+import { createHash } from 'node:crypto';import { tmpdir } from 'node:os';import path from 'node:path';import { fileURLToPath, pathToFileURL } from 'node:url';@@ -59,9 +60,12 @@ const BLOCK_BINDINGS = {const textureBindingForUnit = (u) => (u < 8 ? u : u + 8);const samplerBindingForUnit = (u) => (u < 8 ? u + 8 : u + 16);-const GENERATED_BANNER =+const bannerFor = (hash) =>'// GENERATED by tools/gen-shader-twins.mjs (glslang + naga) - do not edit.\n' +- '// Regenerate after changing the GLSL stages above.';+ '// Regenerate after changing the GLSL stages above.\n' ++ `// source-hash: ${hash}`;++const STORED_HASH_RE = /\/\/ source-hash:\s*([0-9a-f]+)/;/*** Adapt an assembled GLSL ES 300 stage to the dialect glslang -V + naga accept,@@ -266,11 +270,39 @@ async function glslToWgsl(glsl, stage, entryName, workDir) {return text.replace(/\bfn main\(/, `fn ${entryName}(`);}-/** Strip previously generated `wgsl full` sections (for --force regeneration). */+/** Strip previously generated `wgsl full` sections (for --force / stale regen). */function stripGeneratedTwins(source) {return source.replace(/\n?#pragma (?:vertex|fragment) wgsl full\n[\s\S]*?#pragma end\n?/g, '\n');}+/** Hash of a shader's AUTHORED content — everything but the generated twins, i.e.+ * what changes when someone edits the GLSL. Stored in the generated banner so a+ * stale twin (GLSL changed, twin not regenerated) is detectable without running+ * the converter toolchain. */+export function sourceHash(source) {+ // trim(): stripping the twin leaves trailing newlines, and the writer trimEnds+ // before appending — normalize both so generate-then-check round-trips exactly.+ return createHash('sha256').update(stripGeneratedTwins(source).trim()).digest('hex').slice(0, 16);+}++/** Whether `source` needs a (re)generated WGSL twin: it has no twin, or its+ * GENERATED twin's stored source-hash no longer matches the authored GLSL+ * (stale). A hand-authored `wgsl` twin (builtins) and a `#pragma switch` shader+ * are left alone — the former is authored not derived, the latter needs+ * per-permutation twins the generator can't emit. Pure + cheap (no engine), so+ * the editor's on-open scan and CI --check share one definition of "stale". */+export function needsTwin(source) {+ if (/#pragma switch\b/.test(source)) return false;+ const hasGenerated = /#pragma (?:vertex|fragment) wgsl[ \t]+full\b/.test(source);+ const hasHandwritten = /#pragma (?:vertex|fragment) wgsl(?![ \t]+full)/.test(source);+ if (hasHandwritten && !hasGenerated) return false;+ if (hasGenerated) {+ const m = source.match(STORED_HASH_RE);+ return !m || m[1] !== sourceHash(source);+ }+ return true;+}+/** 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() {@@ -280,12 +312,12 @@ export async function loadTwinModule() {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);-- if (/#pragma fragment wgsl/.test(source)) {- return { file, status: 'has-twin' };+ if (!opts.force && !needsTwin(source)) {+ return { file, status: /#pragma switch\b/.test(source) ? 'skipped-switches' : 'has-twin' };}+ // Regenerating (missing, stale, or --force): drop any old generated twin so the+ // new one — and its source-hash — replaces it cleanly.+ if (/#pragma (?:vertex|fragment) wgsl full/.test(source)) source = stripGeneratedTwins(source);const info = module.esshader_cookInfo(source, '');if (!info.valid) throw new Error(`parse failed: ${info.error}`);@@ -304,9 +336,10 @@ export async function processFile(module, file, opts) {const vertWgsl = await glslToWgsl(adapted.vert, 'vert', 'vs_main', workDir);const fragWgsl = await glslToWgsl(adapted.frag, 'frag', 'fs_main', workDir);+ const banner = bannerFor(sourceHash(source));const twin =- `\n#pragma vertex wgsl full\n${GENERATED_BANNER}\n${vertWgsl.trimEnd()}\n#pragma end\n` +- `\n#pragma fragment wgsl full\n${GENERATED_BANNER}\n${fragWgsl.trimEnd()}\n#pragma end\n`;+ `\n#pragma vertex wgsl full\n${banner}\n${vertWgsl.trimEnd()}\n#pragma end\n` ++ `\n#pragma fragment wgsl full\n${banner}\n${fragWgsl.trimEnd()}\n#pragma end\n`;if (opts.check) return { file, status: 'would-generate' };await writeFile(file, source.trimEnd() + '\n' + twin, 'utf8');