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(gates): the two shader languages have to say the same thing

esengine598af3719434
diff --git a/CHANGELOG.md b/CHANGELOG.md
index c5ad017be..53d6c8ce4 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -14,6 +14,27 @@ published separately; it ships inside the editor.
## [Unreleased]
+### Added
+
+- **A gate holds the two shader languages together.** The engine's uniform
+ blocks are written three times — the C++ struct that fills one, the GLSL
+ declaration injected into a shader, and the WGSL twin injected into the other
+ backend's — and the lighting helpers around them twice. Blocks are read by
+ OFFSET, so a field added to two of the three is an error nowhere: every later
+ field is simply read from the wrong bytes, on one backend, and the picture is
+ merely wrong. That is how an RGBM decode lost a multiply and a mesh twin never
+ declared its third texture; both were found by asking why a pixel was 255.
+
+ `check-shader-blocks` compares what a name can carry across all three: field
+ order, array lengths, the set of helpers, and how many arguments each
+ definition takes — including the ones defined once per feature branch, where
+ keeping only the last would hide a branch that drifted. It cannot prove two
+ expressions compute the same thing; it does catch the drift that is a missing
+ or misplaced name, which is what every one found so far has been. Two
+ differences are declared with their reasons: `u_projection` names the block's
+ `viewProjection` (`.esshader` is a format users write), and `sampleNormal`
+ takes a texture and its sampler apart on WGSL, which GLSL has no way to spell.
+
### Changed
- **The same mesh drawn again is one more instance, not one more draw call.**
diff --git a/tools/check-shader-blocks.mjs b/tools/check-shader-blocks.mjs
new file mode 100644
index 000000000..aec102074
--- /dev/null
+++ b/tools/check-shader-blocks.mjs
@@ -0,0 +1,222 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+/**
+ * @file check-shader-blocks.mjs — the engine's uniform blocks and lighting
+ * helpers say the same thing in all three languages they are written in.
+ *
+ * A block like LightConstants exists three times: the C++ struct that fills it,
+ * the GLSL declaration injected into a shader, and the WGSL twin injected into
+ * the other backend's. They are laid out by OFFSET, so a field added to two of
+ * them and forgotten in the third is not an error anywhere — every later field
+ * is simply read from the wrong bytes, on one backend, and the picture is
+ * merely wrong. The lighting helpers around them are written twice for the same
+ * reason, and have already drifted in ways only a pixel told anyone about (an
+ * RGBM decode missing one multiply; a texture one twin never declared).
+ *
+ * This holds the shapes together — field order, array lengths, the set of
+ * helpers and how many arguments each takes. It cannot prove two expressions
+ * compute the same thing; it does catch every drift that is a missing or
+ * misplaced NAME, which is what the ones found so far have been.
+ */
+import { readFileSync } from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const PARSER = path.join('src', 'esengine', 'resource', 'ShaderParser.cpp');
+
+/** Blocks that exist in all three languages, and the C++ header that owns each. */
+const BLOCKS = {
+ FrameConstants: 'src/esengine/renderer/frame/FrameConstants.hpp',
+ TimeConstants: 'src/esengine/renderer/frame/FrameConstants.hpp',
+ LightConstants: 'src/esengine/renderer/store/LightConstants.hpp',
+};
+
+const parser = readFileSync(path.join(ROOT, PARSER), 'utf8');
+
+/**
+ * The headers this compares. Everything else in the parser is a fragment for one
+ * shader rather than a face both backends present, and pulling those in would
+ * ask a vertex entry point to have a GLSL twin.
+ */
+const HEADERS = ['kColorHelpers', 'kFrameHeader', 'kTimeHeader', 'kLit2DHeader'];
+
+/**
+ * One header's text as the shader receives it: raw strings taken whole,
+ * concatenated literals unescaped, so both spellings read the same way.
+ */
+function headerText(symbol) {
+ const at = parser.indexOf(`${symbol} =`);
+ if (at < 0) return '';
+ const raw = /^\s*R"\(([\s\S]*?)\)";/.exec(parser.slice(at + symbol.length + 2));
+ if (raw) return raw[1];
+
+ // Where the DEFINITION ends, not where the first `;` is: these headers are
+ // shader source, and half their lines end in one inside a string literal.
+ let i = at;
+ const out = [];
+ while (i < parser.length) {
+ const c = parser[i];
+ if (c === ';') break;
+ if (c === '/' && parser[i + 1] === '/') { i = parser.indexOf('\n', i) + 1 || parser.length; continue; }
+ if (c === '"') {
+ let j = i + 1;
+ let literal = '';
+ while (j < parser.length && parser[j] !== '"') {
+ if (parser[j] === '\\') { literal += parser[j] + parser[j + 1]; j += 2; continue; }
+ literal += parser[j]; j++;
+ }
+ out.push(literal.replace(/\\n/g, '\n').replace(/\\"/g, '"').replace(/\\\\/g, '\\'));
+ i = j + 1;
+ continue;
+ }
+ i++;
+ }
+ return out.join('');
+}
+
+const glslText = HEADERS.map(headerText).join('\n');
+const wgslText = HEADERS.map((h) => headerText(`${h}WGSL`)).join('\n');
+const text = `${glslText}\n${wgslText}`;
+/**
+ * Names that differ on purpose, and why. Each entry is one field the languages
+ * spell differently; the POSITION is still compared, so a field added to one
+ * side and not the other is still caught. Keep this list short — an entry is a
+ * disagreement someone decided to keep, not permission to add more.
+ */
+const ALIASES = {
+ // The block holds view * projection; the shaders have called it u_projection
+ // since before there was a view, and `.esshader` is a format users write.
+ 'FrameConstants.viewProjection': 'projection',
+};
+
+/**
+ * Helpers whose signatures cannot match, and why. A WGSL texture and its sampler
+ * are separate arguments; GLSL has one combined sampler. Nothing can close this.
+ */
+const SIGNATURE_GAPS = {
+ sampleNormal: 'WGSL takes the texture and its sampler apart; GLSL has one combined type',
+};
+
+/** A field name as the comparison sees it: the `u_` a shader adds is not part of it. */
+const bare = (name) => name.replace(/^u_/, '');
+
+/** GLSL: `layout(std140) uniform Name { highp vec4 u_a; Light2D u_b[16]; };` */
+function glslBlock(name) {
+ const m = new RegExp(`layout\\(std140\\)\\s+uniform\\s+${name}\\s*\\{([^}]*)\\}`, 'm').exec(text);
+ if (!m) return null;
+ return [...m[1].matchAll(/(\w+)\s*(?:\[(\d+)\])?\s*;/g)]
+ .map((f) => `${bare(f[1])}${f[2] ? `[${f[2]}]` : ''}`);
+}
+
+/** WGSL: `struct Name { a : vec4f, b : array<T, 16> };` */
+function wgslBlock(name) {
+ const m = new RegExp(`struct\\s+${name}\\s*\\{([^}]*)\\}`, 'm').exec(text);
+ if (!m) return null;
+ // Split on the commas BETWEEN fields, which the ones inside `array<T, N>`
+ // are not — reading a field as "up to the next comma" loses every length.
+ return m[1].split(/,(?![^<]*>)/).map((f) => f.trim()).filter(Boolean).map((f) => {
+ const [, name, type] = /^(\w+)\s*:\s*([\s\S]+)$/.exec(f) ?? [];
+ if (!name) return '';
+ const count = /array\s*<[^,>]+,\s*(\d+)\s*>/.exec(type);
+ return `${bare(name)}${count ? `[${count[1]}]` : ''}`;
+ }).filter(Boolean);
+}
+
+/** C++: `struct Name { glm::vec4 a{...}; GpuLight2D b[16]; };` — comments and all. */
+function cppBlock(name, file) {
+ const source = readFileSync(path.join(ROOT, file), 'utf8');
+ const m = new RegExp(`struct\\s+${name}\\s*\\{([\\s\\S]*?)\\n\\};`, 'm').exec(source);
+ if (!m) return null;
+ const body = m[1].replace(/\/\/[^\n]*/g, '').replace(/\/\*[\s\S]*?\*\//g, '');
+ return [...body.matchAll(/^\s*(?:glm::)?\w+\s+(\w+)\s*(?:\[([^\]]+)\])?\s*(?:\{[^}]*\})?\s*;/gm)]
+ .map((f) => `${bare(f[1])}${f[2] ? `[${f[2]}]` : ''}`);
+}
+
+/** `MAX_LIGHTS_2D` and friends, so a C++ array length compares as a number. */
+function constants() {
+ const out = new Map();
+ for (const file of new Set(Object.values(BLOCKS))) {
+ const source = readFileSync(path.join(ROOT, file), 'utf8');
+ for (const [, k, v] of source.matchAll(/constexpr\s+\w+\s+(\w+)\s*=\s*(\d+)/g)) {
+ out.set(k, v);
+ }
+ }
+ return out;
+}
+
+const CONSTS = constants();
+const resolve = (field) => field.replace(/\[([A-Z_][A-Z_0-9]*)\]/, (m, k) =>
+ CONSTS.has(k) ? `[${CONSTS.get(k)}]` : m);
+
+const problems = [];
+let checked = 0;
+
+for (const [name, file] of Object.entries(BLOCKS)) {
+ const sides = {
+ [`${PARSER} (GLSL)`]: glslBlock(name),
+ [`${PARSER} (WGSL)`]: wgslBlock(name),
+ [file]: cppBlock(name, file)?.map(resolve)
+ .map((f) => ALIASES[`${name}.${f.replace(/\[.*/, '')}`]
+ ? f.replace(/^[^[]+/, ALIASES[`${name}.${f.replace(/\[.*/, '')}`]) : f),
+ };
+ const missing = Object.entries(sides).filter(([, v]) => !v || v.length === 0);
+ if (missing.length > 0) {
+ for (const [where] of missing) problems.push(`${name}: not found in ${where}`);
+ continue;
+ }
+ const [reference, ...rest] = Object.entries(sides);
+ for (const [where, fields] of rest) {
+ if (fields.join(' ') !== reference[1].join(' ')) {
+ problems.push(`${name} differs between ${reference[0]} and ${where}:`
+ + `\n ${reference[1].join(', ')}`
+ + `\n ${fields.join(', ')}`);
+ }
+ }
+ checked += reference[1].length;
+}
+
+/**
+ * GLSL `highp vec3 name(args)` / WGSL `fn name(args) -> t` → name → the argument
+ * count of EVERY definition, since several helpers are defined once per feature
+ * branch. Keeping only the last would hide a branch that drifted, and a branch
+ * present on one backend and not the other.
+ */
+function helpers(pattern) {
+ const out = new Map();
+ for (const m of text.matchAll(pattern)) {
+ const args = m[2].trim();
+ const counts = out.get(m[1]) ?? [];
+ counts.push(args === '' ? 0 : args.split(',').length);
+ out.set(m[1], counts.sort());
+ }
+ return out;
+}
+
+const glslFns = helpers(/^\s*(?:highp\s+)?(?:vec[234]|float|mat[234])\s+(\w+)\s*\(([^)]*)\)\s*\{/gm);
+const wgslFns = helpers(/\bfn\s+(\w+)\s*\(([^)]*)\)\s*->/g);
+
+const shape = (counts) => counts.length === 1 ? `${counts[0]} argument(s)`
+ : `${counts.length} definitions taking ${counts.join('/')} argument(s)`;
+
+for (const [name, args] of glslFns) {
+ if (!wgslFns.has(name)) problems.push(`the helper ${name}() is GLSL-only — the WGSL twin has none`);
+ else if (wgslFns.get(name).join() !== args.join() && !SIGNATURE_GAPS[name]) {
+ problems.push(`${name}(): ${shape(args)} in GLSL, ${shape(wgslFns.get(name))} in WGSL`);
+ }
+ checked++;
+}
+for (const name of wgslFns.keys()) {
+ if (!glslFns.has(name)) problems.push(`the helper ${name}() is WGSL-only — the GLSL twin has none`);
+}
+
+if (problems.length > 0) {
+ console.error('check-shader-blocks: the injected shader headers disagree:');
+ for (const p of problems) console.error(` ${p}`);
+ process.exit(1);
+}
+
+const declared = Object.keys(ALIASES).length + Object.keys(SIGNATURE_GAPS).length;
+console.log(`check-shader-blocks: ${Object.keys(BLOCKS).length} uniform block(s) and`
+ + ` ${glslFns.size} lighting helper(s) agree across C++, GLSL and WGSL`
+ + ` (${checked} name(s), ${declared} declared difference(s))`);
diff --git a/tools/gates.mjs b/tools/gates.mjs
index 706bddf31..d1207e651 100644
--- a/tools/gates.mjs
+++ b/tools/gates.mjs
@@ -77,6 +77,7 @@ export const GATES = [
{ id: 'component-fields', run: 'node tools/check-component-fields.mjs' },
{ id: 'shader-conditionals', run: 'node tools/check-shader-conditionals.mjs' },
{ id: 'mesh-vocabulary', run: 'node tools/check-mesh-vocabulary.mjs' },
+ { id: 'shader-blocks', run: 'node tools/check-shader-blocks.mjs' },
{ id: 'import-settings', run: 'node tools/check-import-settings.mjs' },
{ id: 'dirty-source', run: 'node tools/check-dirty-source.mjs' },
{ id: 'path-sandbox', run: 'node tools/check-path-sandbox.mjs' },