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(shaders): detect stale WGSL twins by hashing the authored GLSL

esenginecaab6fcc8819
diff --git a/desktop/electron/shaderTwins.ts b/desktop/electron/shaderTwins.ts
index 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.esshader
index 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: 9f608a54b0f5c530
struct 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: 9f608a54b0f5c530
struct Light2D {
posDir: vec4<f32>,
color: vec4<f32>,
diff --git a/desktop/public/scenes/mat-dissolve/dissolve.esshader b/desktop/public/scenes/mat-dissolve/dissolve.esshader
index 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: 99e3d67aae0be3c6
struct 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: 99e3d67aae0be3c6
struct 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.esshader
index 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: 17d9cf90b8470378
struct 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: 17d9cf90b8470378
struct 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.esshader
index 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: 2109a83ca59fdb20
struct 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: 2109a83ca59fdb20
struct 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.esshader
index 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: 60ae4382caf672f0
struct 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: 60ae4382caf672f0
struct Light2D {
posDir: vec4<f32>,
color: vec4<f32>,
diff --git a/desktop/public/scenes/mat-lit/lit.esshader b/desktop/public/scenes/mat-lit/lit.esshader
index 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: 95a1f35f723b831c
struct 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: 95a1f35f723b831c
struct Light2D {
posDir: vec4<f32>,
color: vec4<f32>,
diff --git a/desktop/public/scenes/mat-tex/masked.esshader b/desktop/public/scenes/mat-tex/masked.esshader
index 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: 70fc4540fdcdb04a
struct 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: 70fc4540fdcdb04a
struct 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.esshader
index 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: 1c3115bd7b73f674
struct 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: 1c3115bd7b73f674
struct 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.esshader
index 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: 0d65463ea0c29816
struct 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: 0d65463ea0c29816
struct 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.esshader
index 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: 2e7de16a41174f41
struct 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: 2e7de16a41174f41
struct MaterialConstants {
u_pixels: f32,
}
diff --git a/examples/effects-gallery/assets/materials/uv-scroll.esshader b/examples/effects-gallery/assets/materials/uv-scroll.esshader
index 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: 8ae602b222f8cbdc
struct 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: 8ae602b222f8cbdc
struct TimeConstants {
u_time: vec4<f32>,
u_viewport: vec4<f32>,
diff --git a/sdk/tests/shader-twins.test.ts b/sdk/tests/shader-twins.test.ts
index 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.mjs
index 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');