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(gates): a WGSL twin declares what nothing declares for it
esenginec1539359a617
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex 2dc00af70..d9da2a7ec 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -16,6 +16,21 @@ published separately; it ships inside the editor.### Added+- **A gate on what a WGSL twin has to declare for itself.** A fragment-only twin+ is assembled with its domain's canonical vertex stage, and the engine injects+ the matching `VSOut` and the eight batch texture bindings with it. A twin that+ writes its own vertex stage gets neither — nothing can know what interface that+ stage produces — so it has to declare the varying struct and every texture it+ reaches, including the ones the injected lighting helpers sample through it.++ Miss one and nothing says so: the stage is not an error to the parser, and what+ reaches whoever runs the second backend is `Invalid RenderPipeline` with no+ mention of a shader anywhere in the log. That has now happened four times — a+ mesh twin without `t3`, a shadow map the same, an environment atlas nobody+ declared, and a sky twin naming the `VSOut` from its own vertex block.+ `check-wgsl-twin` follows the injected helpers a stage calls, transitively, to+ the textures they sample, and each of those four is red under it.+- **An environment can be seen, not only reflected.** A baked `.esenv` gave ascene its irradiance and a prefiltered reflection, so a metal ball had a sky init — and behind the ball was a flat clear colour. The same panorama was halfdiff --git a/tools/check-wgsl-twin.mjs b/tools/check-wgsl-twin.mjsnew file mode 100644index 000000000..7087b3367--- /dev/null+++ b/tools/check-wgsl-twin.mjs@@ -0,0 +1,125 @@+// SPDX-License-Identifier: Apache-2.0+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team+/**+ * @file check-wgsl-twin.mjs — a WGSL twin that writes its own vertex stage+ * declares everything its fragment stage names.+ *+ * A fragment-only twin is assembled with the domain's canonical vertex stage,+ * and the engine injects the matching `VSOut` and the eight batch texture+ * bindings alongside it. **A twin that writes its own vertex stage gets neither**+ * — the engine cannot know what interface that stage produces — so its fragment+ * stage has to declare the varying struct and every texture it reaches, its own+ * and the ones the injected lighting helpers sample through it.+ *+ * Miss one and nothing says so. The stage is not an error to the parser, and it+ * reaches whoever runs the second backend as "Invalid RenderPipeline", with the+ * log carrying no mention of a shader at all. That has now happened four times:+ * a mesh twin without `t3`, an environment atlas nobody declared, a shadow map+ * the same, and a sky twin that named the `VSOut` from its own vertex block.+ */+import { readFileSync } from 'node:fs';+import { execFileSync } from 'node:child_process';+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');++const parser = readFileSync(path.join(ROOT, PARSER), 'utf8');++/** The injected WGSL, as the shader receives it: raw strings plus literal runs. */+function injectedWgsl() {+ const raws = [...parser.matchAll(/const char\* k\w*WGSL\s*=\s*R"\(([\s\S]*?)\)";/g)].map((m) => m[1]);+ const runs = [...parser.matchAll(/const char\* k\w*WGSL\s*=\s*((?:\s*"(?:[^"\\]|\\.)*"\s*)+);/g)]+ .map((m) => [...m[1].matchAll(/"((?:[^"\\]|\\.)*)"/g)]+ .map((l) => l[1].replace(/\\n/g, '\n').replace(/\\"/g, '"')).join(''));+ return [...raws, ...runs].join('\n');+}++const injected = injectedWgsl();++/** Injected helper → the texture/sampler names its body reaches, directly. */+function helperBindings(source) {+ const out = new Map();+ for (const m of source.matchAll(/\bfn\s+(\w+)\s*\([^)]*\)\s*->[^{]*\{([\s\S]*?)\n\}/g)) {+ const body = m[2];+ const names = new Set([...body.matchAll(/\b([ts]\d+)\b/g)].map((b) => b[1]));+ const calls = new Set([...body.matchAll(/\b(\w+)\s*\(/g)].map((c) => c[1]));+ const prev = out.get(m[1]);+ // Several helpers are defined once per feature branch; a caller may reach+ // either, so what it needs is the union of them.+ if (prev) {+ for (const n of names) prev.names.add(n);+ for (const c of calls) prev.calls.add(c);+ } else {+ out.set(m[1], { names, calls });+ }+ }+ return out;+}++const HELPERS = helperBindings(injected);++/** Everything calling `name` can end up sampling, following calls transitively. */+function bindingsReachedBy(name, seen = new Set()) {+ if (seen.has(name)) return new Set();+ seen.add(name);+ const helper = HELPERS.get(name);+ if (!helper) return new Set();+ const out = new Set(helper.names);+ for (const call of helper.calls) {+ for (const n of bindingsReachedBy(call, seen)) out.add(n);+ }+ return out;+}++const files = execFileSync('git', ['ls-files', '*.esshader'], { cwd: ROOT, encoding: 'utf8' })+ .split('\n').filter(Boolean);++/** `#pragma <stage> wgsl` … `#pragma end` for one stage, or null. */+function wgslStage(text, stage) {+ const m = new RegExp(`^#pragma\\s+${stage}\\s+wgsl\\s*$([\\s\\S]*?)^#pragma\\s+end\\s*$`, 'm').exec(text);+ return m ? m[1] : null;+}++const problems = [];+let checked = 0;++for (const file of files) {+ const text = readFileSync(path.join(ROOT, file), 'utf8');+ const frag = wgslStage(text, 'fragment');+ // No twin at all, or a fragment-only one: the engine supplies the interface.+ if (!frag || wgslStage(text, 'vertex') === null) continue;+ checked++;++ const declaredStructs = new Set([...frag.matchAll(/\bstruct\s+(\w+)\s*\{/g)].map((m) => m[1]));+ const declaredBindings = new Set([...frag.matchAll(/@binding\(\d+\)\s*var\s+(\w+)\s*:/g)].map((m) => m[1]));++ // A struct named in a signature or a constructor, that this stage does not declare.+ for (const [, name] of frag.matchAll(/:\s*([A-Z]\w*)\s*[),]/g)) {+ if (declaredStructs.has(name) || /^(f32|i32|u32|bool)$/.test(name)) continue;+ if (/^vec[234][fiu]?$|^mat[234]x[234]f$|^array$|^texture_|^sampler$/.test(name)) continue;+ problems.push(`${file}: the fragment twin names \`${name}\` and does not declare it`+ + ' — its own vertex stage means nothing injects one');+ }++ // Textures it samples itself, plus the ones the injected helpers it calls do.+ const needed = new Set([...frag.matchAll(/\b([ts]\d+)\b/g)].map((m) => m[1]));+ for (const [, call] of frag.matchAll(/\b(\w+)\s*\(/g)) {+ for (const n of bindingsReachedBy(call)) needed.add(n);+ }+ for (const name of [...needed].sort()) {+ if (declaredBindings.has(name)) continue;+ problems.push(`${file}: the fragment twin reaches \`${name}\` and does not declare it`+ + ' — an injected helper samples it, and only this stage can bind it');+ }+}++if (problems.length > 0) {+ console.error('check-wgsl-twin: a WGSL twin names what nothing declares for it:');+ for (const p of [...new Set(problems)]) console.error(` ${p}`);+ process.exit(1);+}++console.log(`check-wgsl-twin: ${checked} twin(s) with their own vertex stage declare every`+ + ` struct and texture they reach (${HELPERS.size} injected helpers followed)`);diff --git a/tools/gates.mjs b/tools/gates.mjsindex d1207e651..c3e45c370 100644--- a/tools/gates.mjs+++ b/tools/gates.mjs@@ -78,6 +78,7 @@ export const GATES = [{ 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: 'wgsl-twin', run: 'node tools/check-wgsl-twin.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' },