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
refactor(shader): the assembler declares the bindings a twin reaches
esengine41b159025337
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex 766fceb4a..d7bb7e1b3 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -41,6 +41,21 @@ published separately; it ships inside the editor.### Fixed+- **A WGSL twin no longer declares the engine's own texture bindings.** A twin that+ writes its own vertex stage had to spell out every `tN`/`sN` it touched — a convention+ the engine owns, where forgetting one is an invalid pipeline that mentions no shader.+ The assembler now completes the set from what the stage reaches, leaving anything the+ twin declared itself alone, so a cooked (`wgsl full`) shader assembles unchanged.++ The rule had been copied into three places — the assembler's emitters, the WebGPU+ backend's bind-group reflection, and the twin generator. The unit→binding convention+ and the two source scans are one header now (`rhi/WgslBindings.hpp`), which the+ assembler emits from and the backend reads back with.++ `check-wgsl-twin` asked twins for those declarations; that question cannot fail any+ more, so it stopped asking and lost eighty lines. What it still holds is the varying+ struct, which is nobody else's to supply.+- **A shader that fails to compile says why.** `ResourceManager` asked the device tobuild a program, got a reason back, and logged "Failed to create shader from source"without it — so the one thing that could have named the problem was the one thingdiff --git a/src/esengine/data/shaders/lightshape2d.esshader b/src/esengine/data/shaders/lightshape2d.esshaderindex 6627d14ef..9be152ffe 100644--- a/src/esengine/data/shaders/lightshape2d.esshader+++ b/src/esengine/data/shaders/lightshape2d.esshader@@ -62,10 +62,6 @@ struct VSOut {#pragma end#pragma fragment wgsl-// The cookie, on the draw's own first slot — this pass binds one texture per light.-@group(1) @binding(0) var t0 : texture_2d<f32>;-@group(1) @binding(8) var s0 : sampler;-struct VSOut {@builtin(position) pos : vec4f,@location(0) v_texCoord : vec2f,diff --git a/src/esengine/data/shaders/mesh.esshader b/src/esengine/data/shaders/mesh.esshaderindex 666cbf7ba..00912955e 100644--- a/src/esengine/data/shaders/mesh.esshader+++ b/src/esengine/data/shaders/mesh.esshader@@ -280,9 +280,6 @@ struct VSOut {// lighting reads it for every Lit shader rather than behind a feature.@group(1) @binding(7) var t7 : texture_2d<f32>;@group(1) @binding(15) var s7 : sampler;-// The light-shape mask, one unit below it, on the same terms.-@group(1) @binding(6) var t6 : texture_2d<f32>;-@group(1) @binding(14) var s6 : sampler;struct VSOut {@builtin(position) pos : vec4f,diff --git a/src/esengine/data/shaders/sky.esshader b/src/esengine/data/shaders/sky.esshaderindex ef34b053d..d5412aca0 100644--- a/src/esengine/data/shaders/sky.esshader+++ b/src/esengine/data/shaders/sky.esshader@@ -63,9 +63,6 @@ struct VSOut {// The 2D shadow mask, which the injected lighting reads for every Lit shader.@group(1) @binding(7) var t7 : texture_2d<f32>;@group(1) @binding(15) var s7 : sampler;-// The light-shape mask, one unit below it, on the same terms.-@group(1) @binding(6) var t6 : texture_2d<f32>;-@group(1) @binding(14) var s6 : sampler;// Declared again: each WGSL block is compiled on its own, so a struct defined in// the vertex one is an undeclared name here — and that reaches anyone as andiff --git a/src/esengine/renderer/rhi/ShaderEmbeds.generated.hpp b/src/esengine/renderer/rhi/ShaderEmbeds.generated.hppindex b56280059..7058d428a 100644--- a/src/esengine/renderer/rhi/ShaderEmbeds.generated.hpp+++ b/src/esengine/renderer/rhi/ShaderEmbeds.generated.hpp@@ -337,10 +337,6 @@ struct VSOut {#pragma end#pragma fragment wgsl-// The cookie, on the draw's own first slot — this pass binds one texture per light.-@group(1) @binding(0) var t0 : texture_2d<f32>;-@group(1) @binding(8) var s0 : sampler;-struct VSOut {@builtin(position) pos : vec4f,@location(0) v_texCoord : vec2f,@@ -635,9 +631,6 @@ struct VSOut {// lighting reads it for every Lit shader rather than behind a feature.@group(1) @binding(7) var t7 : texture_2d<f32>;@group(1) @binding(15) var s7 : sampler;-// The light-shape mask, one unit below it, on the same terms.-@group(1) @binding(6) var t6 : texture_2d<f32>;-@group(1) @binding(14) var s6 : sampler;struct VSOut {@builtin(position) pos : vec4f,@@ -972,9 +965,6 @@ struct VSOut {// The 2D shadow mask, which the injected lighting reads for every Lit shader.@group(1) @binding(7) var t7 : texture_2d<f32>;@group(1) @binding(15) var s7 : sampler;-// The light-shape mask, one unit below it, on the same terms.-@group(1) @binding(6) var t6 : texture_2d<f32>;-@group(1) @binding(14) var s6 : sampler;// Declared again: each WGSL block is compiled on its own, so a struct defined in// the vertex one is an undeclared name here — and that reaches anyone as andiff --git a/src/esengine/renderer/rhi/WgslBindings.hpp b/src/esengine/renderer/rhi/WgslBindings.hppnew file mode 100644index 000000000..8f3b265b4--- /dev/null+++ b/src/esengine/renderer/rhi/WgslBindings.hpp@@ -0,0 +1,92 @@+// SPDX-License-Identifier: Apache-2.0+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team+/**+ * @file WgslBindings.hpp+ * @brief What a texture unit is called in WGSL, and what a WGSL source says about+ * the group-1 bindings it holds.+ * @details One author for a convention three places acted on: the shader assembler+ * emits these declarations, the WebGPU backend builds its bind-group layouts+ * from them, and the twin generator writes them into a cooked shader. Backend+ * neutral on purpose — the assembler runs in a build with no WebGPU in it.+ *+ * @copyright Copyright (c) 2026 ESEngine Team+ * Licensed under the Apache License, Version 2.0.+ */+#pragma once++#include "../../core/Types.hpp"++#include <cstdlib>+#include <cstring>++namespace esengine {++/**+ * @brief Group-1 binding of a texture unit. Units 0-7 are the batch stream and take+ * bindings 0-7; a material's own units start at 8 and take 16 upward, leaving+ * 8-15 for the samplers underneath the first eight.+ */+inline constexpr u32 textureBindingForUnit(u32 unit) { return unit < 8 ? unit : unit + 8; }++/** @brief Group-1 binding of a texture unit's sampler (see textureBindingForUnit). */+inline constexpr u32 samplerBindingForUnit(u32 unit) { return unit < 8 ? unit + 8 : unit + 16; }++/** @brief Units a `tN` / `sN` name can carry — the batch stream and a material's own. */+inline constexpr u32 WGSL_MAX_TEXTURE_UNITS = 16;++/**+ * @brief Bit mask of the `@group(N) @binding(i)` indices a WGSL source declares.+ * @details Declarations drive the backend's EXPLICIT bind-group layouts: every declared+ * binding gets a layout entry and a bound resource (or a dummy backfill), so a+ * declared-but-unused binding is as legal as it is in GLSL. Bindings >= 32 are+ * ignored — the group-1 convention tops out at 31.+ */+inline u32 scanWGSLBindingMask(const char* source, u32 group) {+ if (!source) return 0;+ u32 mask = 0;+ for (const char* p = source; (p = std::strstr(p, "@group(")) != nullptr;) {+ p += 7;+ char* end = nullptr;+ const unsigned long g = std::strtoul(p, &end, 10);+ if (end == p) continue;+ p = end;+ if (g != group) continue;+ const char* b = std::strstr(p, "@binding(");+ if (!b) break;+ b += 9;+ const unsigned long idx = std::strtoul(b, &end, 10);+ if (end == b) continue;+ p = end;+ if (idx < 32) mask |= (1u << idx);+ }+ return mask;+}++/**+ * @brief The `tN` / `sN` names a WGSL source REACHES, by unit.+ * @details The other half of the question {@link scanWGSLBindingMask} asks: what a+ * stage names, as against what it declares. A name reached and not declared is+ * an unresolved identifier, which WebGPU reports as an invalid PIPELINE with no+ * shader named anywhere in it — so the assembler completes the set instead.+ */+inline void scanWGSLReachedUnits(const char* source, u32& textures, u32& samplers) {+ textures = 0;+ samplers = 0;+ if (!source) return;+ const auto isIdent = [](char c) {+ return (c >= 'a' && c <= 'z') || (c >= 'A' && c <= 'Z') || (c >= '0' && c <= '9') || c == '_';+ };+ for (const char* p = source; *p; ++p) {+ if (*p != 't' && *p != 's') continue;+ if (p != source && isIdent(p[-1])) continue;+ char* end = nullptr;+ const unsigned long unit = std::strtoul(p + 1, &end, 10);+ if (end == p + 1 || isIdent(*end)) continue;+ if (unit < WGSL_MAX_TEXTURE_UNITS) {+ (*p == 't' ? textures : samplers) |= (1u << unit);+ }+ p = end - 1;+ }+}++} // namespace esenginediff --git a/src/esengine/renderer/webgpu/WebGPUMappings.hpp b/src/esengine/renderer/webgpu/WebGPUMappings.hppindex 8c72537a0..542ea5426 100644--- a/src/esengine/renderer/webgpu/WebGPUMappings.hpp+++ b/src/esengine/renderer/webgpu/WebGPUMappings.hpp@@ -23,6 +23,7 @@#include "../rhi/GfxEnums.hpp"#include "../draw/BlendMode.hpp"#include "../rhi/PipelineState.hpp"+#include "../rhi/WgslBindings.hpp"#include <webgpu/webgpu.h>@@ -353,86 +354,11 @@ inline WGPUCullMode toWGPUCullMode(bool enabled, bool front) {// Group-1 binding convention (texture units → bindings)// =============================================================================-/**- * @brief Texture units the group-1 convention spans: engine units 0..7 (the- * batch's u_textures[8]) plus material-param units 8..15 (the GL- * MATERIAL_TEXTURE_UNIT_BASE range).- */-inline constexpr u32 kGroup1TextureUnits = 16;--/**- * @brief Group-1 binding of a texture unit's texture_2d.- * @details Engine units 0..7 sit at bindings 0..7 with their samplers at 8..15- * (GL's combined texture+sampler state de-combined); material units- * 8..15 extend the group at bindings 16..23 with samplers at 24..31.- * The two maps are disjoint and together cover bits 0..31 exactly, so- * one u32 mask describes a whole group.- */-inline constexpr u32 textureBindingForUnit(u32 unit) { return unit < 8 ? unit : unit + 8; }+/** @brief Texture units the group-1 convention spans — see WGSL_MAX_TEXTURE_UNITS. */+inline constexpr u32 kGroup1TextureUnits = WGSL_MAX_TEXTURE_UNITS;-/** @brief Group-1 binding of a texture unit's sampler (see textureBindingForUnit). */-inline constexpr u32 samplerBindingForUnit(u32 unit) { return unit < 8 ? unit + 8 : unit + 16; }--// =============================================================================-// WGSL binding reflection (source scan)-// =============================================================================--/**- * @brief Bit mask of the `@group(N) @binding(i)` indices a WGSL source declares.- * @details Declarations drive the device's EXPLICIT bind-group layouts: every- * declared binding gets a layout entry and a bind-group entry (bound- * resource or dummy backfill), so declared-but-unused bindings are as- * legal as they are in GLSL. A source scan stands in for real- * reflection until the Phase 3 emitter carries binding metadata.- * Bindings ≥ 32 are ignored (the group-1 convention tops out at 31).- */-inline u32 scanWGSLBindingMask(const char* source, u32 group) {- if (!source) return 0;- u32 mask = 0;- for (const char* p = source; (p = std::strstr(p, "@group(")) != nullptr;) {- p += 7;- char* end = nullptr;- const unsigned long g = std::strtoul(p, &end, 10);- if (end == p) continue;- p = end;- if (g != group) continue;- const char* b = std::strstr(p, "@binding(");- if (!b) break;- b += 9;- const unsigned long idx = std::strtoul(b, &end, 10);- if (end == b) continue;- p = end;- if (idx < 32) mask |= (1u << idx);- }- return mask;-}--/**- * @brief The engine's `tN` / `sN` group-1 names a WGSL source REACHES, by unit.- * @details The other half of {@link scanWGSLBindingMask}: what a stage names, as- * against what it declares. A name reached and not declared is an- * unresolved identifier, and WebGPU reports that as an invalid PIPELINE- * with no shader named anywhere in it.- */-inline void scanWGSLReachedUnits(const char* source, u32& textures, u32& samplers) {- textures = 0;- samplers = 0;- if (!source) return;- const auto isIdent = [](char c) {- return (c >= 'a' && c <= 'z') || (c >= 'A' && c <= 'Z') || (c >= '0' && c <= '9') || c == '_';- };- for (const char* p = source; *p; ++p) {- if (*p != 't' && *p != 's') continue;- if (p != source && isIdent(p[-1])) continue;- char* end = nullptr;- const unsigned long unit = std::strtoul(p + 1, &end, 10);- if (end == p + 1 || isIdent(*end)) continue;- if (unit < 16) {- (*p == 't' ? textures : samplers) |= (1u << unit);- }- p = end - 1;- }-}+// The unit -> binding convention and the two source scans live in rhi/WgslBindings.hpp:+// the shader assembler EMITS what this backend reads back, so one of them owns the rule./*** @brief Bit mask of the group's bindings a WGSL source declares as DEPTH textures.diff --git a/src/esengine/resource/ShaderParser.cpp b/src/esengine/resource/ShaderParser.cppindex 1c64ef6c1..5e56fbaae 100644--- a/src/esengine/resource/ShaderParser.cpp+++ b/src/esengine/resource/ShaderParser.cpp@@ -14,6 +14,7 @@#include "ShaderParser.hpp"#include "../core/Log.hpp"#include "../renderer/store/MaterialConstants.hpp"+#include "../renderer/rhi/WgslBindings.hpp"#include <sstream>#include <algorithm>@@ -794,10 +795,40 @@ std::string wgslBatchTextureDecls(bool postProcess) {return src;}-// #pragma param texture uniforms: material units (>= 8) extend group 1 at-// texture bindings unit+8 (16..23) with samplers at unit+16 (24..31) — the-// WebGPUMappings unit→binding convention. The sampler rides the param's name-// with an _s suffix: textureSampleLevel(u_mask, u_mask_s, uv, 0.0).+/**+ * The `tN` / `sN` bindings a stage NAMES and has not declared for itself. The engine+ * owns what `tN` means, so it completes the set rather than asking a twin to repeat the+ * convention — an unresolved name is an invalid pipeline that mentions no shader. An+ * already-declared unit is left alone, so a cooked twin assembles unchanged.+ */+std::string wgslReachedTextureDecls(const std::string& source, bool postProcess) {+ u32 reachedTex = 0;+ u32 reachedSam = 0;+ scanWGSLReachedUnits(source.c_str(), reachedTex, reachedSam);+ const u32 declared = scanWGSLBindingMask(source.c_str(), 1);+ std::string src;+ for (u32 unit = 0; unit < WGSL_MAX_TEXTURE_UNITS; ++unit) {+ const std::string n = std::to_string(unit);+ if ((reachedTex & (1u << unit)) != 0+ && (declared & (1u << textureBindingForUnit(unit))) == 0) {+ // A fullscreen pass reads the scene's DEPTH at the top engine unit, and a+ // depth texture is its own WGSL type with no sampler under it.+ src += "@group(1) @binding(" + std::to_string(textureBindingForUnit(unit)) + ") var t" + n+ + (postProcess && unit == kSceneDepthUnit ? " : texture_depth_2d;\n"+ : " : texture_2d<f32>;\n");+ }+ if ((reachedSam & (1u << unit)) != 0+ && (declared & (1u << samplerBindingForUnit(unit))) == 0) {+ src += "@group(1) @binding(" + std::to_string(samplerBindingForUnit(unit)) + ") var s" + n+ + " : sampler;\n";+ }+ }+ return src;+}++// #pragma param texture uniforms: material units (>= 8) take the unit→binding+// convention in rhi/WgslBindings.hpp, and the sampler rides the param's own name with+// an _s suffix: textureSampleLevel(u_mask, u_mask_s, uv, 0.0).std::string wgslMaterialTextureDecls(const ParsedShader& parsed) {std::string src;for (const auto& p : parsed.properties) {@@ -1385,6 +1416,9 @@ ShaderParser::AssembledStage assembleWGSLStage(const ParsedShader& parsed,if (lit) inject(kLitHeaderWGSL);inject(kColorHelpersWGSL);}+ // Last, so it sees every declaration made above as well as the body's own.+ inject(wgslReachedTextureDecls(assembled.str() + bodyIt->second,+ parsed.domain == "PostProcess"));assembled << bodyIt->second;diff --git a/tools/check-wgsl-twin.mjs b/tools/check-wgsl-twin.mjsindex 40dd3cf22..ae550e6d6 100644--- a/tools/check-wgsl-twin.mjs+++ b/tools/check-wgsl-twin.mjs@@ -2,20 +2,21 @@// 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.+ * declares the structs 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.+ * A fragment-only twin is assembled with the domain's canonical vertex stage and+ * gets the matching `VSOut` with 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 itself.** 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.+ * log carrying no mention of a shader at all — which is how a sky twin naming the+ * `VSOut` of its own vertex block cost an afternoon.+ *+ * TEXTURES are not this file's question: a stage's `tN`/`sN` are completed by the+ * assembler from what it reaches, and the backend refuses by name what it cannot+ * complete. See ShaderParser's wgslReachedTextureDecls, WebGPUDevice::createProgram.** Not every dual-language shader is a file. The SDK writes some of its own into* template literals, and those reach the same parser and the same backend.@@ -26,77 +27,6 @@ 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);--/**- * The bindings a Lit twin must declare whether or not anything in it reads them: a- * stage is one WGSL module, so a name any injected helper mentions has to resolve even- * where nothing calls it. What sits behind an `#ifdef` is the exception — only a stage- * asking for the feature has that text, or binds it.- */-function unconditionalBindings(source) {- const out = new Set();- let depth = 0;- for (const line of source.split('\n')) {- if (/^\s*#\s*if/.test(line)) { depth++; continue; }- if (/^\s*#\s*endif/.test(line)) { depth = Math.max(0, depth - 1); continue; }- if (/^\s*#\s*(else|elif)/.test(line)) continue;- if (depth > 0) continue;- for (const m of line.matchAll(/\b([ts]\d+)\b/g)) out.add(m[1]);- }- return out;-}--const ALWAYS_INJECTED = unconditionalBindings(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;-}-/** Every template literal in `text` that carries shader source, labelled by line. */function embedded(file, text) {const out = [];@@ -130,8 +60,11 @@ for (const file of ROOTS.flatMap((r) => sourceFiles(r, /\.(esshader|ts)$/))) {/** `#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;+ // `full` included: a self-contained stage is the one the assembler does NOT+ // complete, so it is the one this file most has to read.+ const m = new RegExp(`^#pragma\\s+${stage}\\s+wgsl(\\s+full)?\\s*$([\\s\\S]*?)^#pragma\\s+end\\s*$`,+ 'm').exec(text);+ return m ? m[2] : null;}let checked = 0;@@ -153,21 +86,6 @@ for (const { label: file, text } of sources) {+ ' — its own vertex stage means nothing injects one');}- // Textures it samples itself, the ones the injected helpers it calls do, and the- // ones every injected helper mentions unconditionally — those are in the module- // whether or not this stage ever calls them.- 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);- }- if (/#pragma\s+domain\s+Lit\b/.test(text)) {- for (const n of ALWAYS_INJECTED) 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) {@@ -177,5 +95,5 @@ if (problems.length > 0) {}console.log(`check-wgsl-twin: ${checked} of ${sources.length} twin(s) write their own vertex`- + ` stage and declare every struct and texture they reach`- + ` (${HELPERS.size} injected helpers followed)`);+ + ' stage and declare every struct they name (their textures are the assembler\'s,'+ + ' and the backend names what it cannot complete)');