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(draw): custom-draw goes reflected - editor grid renders on WebGPU (last GL-only path closed)
yhhcc1012d90e26
diff --git a/.github/workflows/build.yml b/.github/workflows/build.ymlindex 7b7316b17..3421d72ad 100644--- a/.github/workflows/build.yml+++ b/.github/workflows/build.yml@@ -194,6 +194,9 @@ jobs:env "$@" xvfb-run -a pnpm exec electron scripts/headless-verify.mjs}run_scene sprite-default+ # Editor grid on/off pixel diff — guards the custom-draw reflected+ # material path (drawMeshWithMaterial + MaterialConstants UBO).+ run_scene editor-grid ESTELLA_VERIFY_GRID=64 ESTELLA_VERIFY_STEPS=3run_scene mesh2d \ESTELLA_VERIFY_SCENE=/scenes/mesh2d.esscene \ESTELLA_VERIFY_MANIFEST=/scenes/mesh2d.textures.json \diff --git a/desktop/scripts/headless-verify.mjs b/desktop/scripts/headless-verify.mjsindex 947ca7781..1fbbae8f8 100644--- a/desktop/scripts/headless-verify.mjs+++ b/desktop/scripts/headless-verify.mjs@@ -17,6 +17,7 @@* ESTELLA_VERIFY_MANIFEST texture manifest url* ESTELLA_VERIFY_W / _H capture size (default 640×480)* ESTELLA_VERIFY_STEPS fixed-dt frames to advance before capture (default 30)+ * ESTELLA_VERIFY_GRID editor-grid on/off pixel-diff assertion (value = spacing)*/import { app, BrowserWindow } from 'electron';import http from 'node:http';@@ -75,7 +76,7 @@ function serveDist() {function finish(result, server) {const ok = result.ok && result.capture?.rendered && (result.expect?.ok ?? true) &&- (result.resize?.ok ?? true) && (result.preview?.ok ?? true);+ (result.resize?.ok ?? true) && (result.preview?.ok ?? true) && (result.grid?.ok ?? true);console.log(`\n[verify:render] ${ok ? 'PASS' : 'FAIL'} — ${SCENE} (${BACKEND})`);console.log('DRIVE_RESULT ' + JSON.stringify(result));process.exitCode = ok ? 0 : 1;@@ -267,7 +268,62 @@ app.whenReady().then(async () => {return { ok: got.every((g, k) => Math.abs(g - cfg.rgb[k]) <= tol), want: cfg.rgb, got, w, h };})()`);}- finish({ ok: true, entityCount, drawCalls, capture, expect, resize, preview }, server);+ // Optional editor-grid assertion (ESTELLA_VERIFY_GRID = minor spacing, world+ // units): flip the grid on (this activates the editor view it draws through),+ // capture, flip it off, and assert the frames differ — proving the custom-draw+ // drawMeshWithMaterial path rasterizes on this backend. Run standalone:+ // activating the editor view reframes the camera for any later capture.+ let grid = null;+ if (process.env.ESTELLA_VERIFY_GRID) {+ const spacing = Number(process.env.ESTELLA_VERIFY_GRID) || 64;+ await exec(`window.__estellaHeadless.api.setGrid(true, ${spacing})`);+ await exec('window.__estellaHeadless.api.step(2, 1 / 60)');+ // Optional PNG of the grid-on frame (ESTELLA_VERIFY_GRID_OUT) for eyeballing.+ // Same per-backend readback split as ESTELLA_VERIFY_OUT (GL page capture of a+ // hidden window never composites — read the framebuffer in-page instead).+ if (process.env.ESTELLA_VERIFY_GRID_OUT && BACKEND === 'webgpu') {+ const image = await win.webContents.capturePage({ x: 0, y: 0, width: W, height: H });+ await writeFile(process.env.ESTELLA_VERIFY_GRID_OUT, image.toPNG());+ } else if (process.env.ESTELLA_VERIFY_GRID_OUT) {+ const dataUrl = await exec(`(() => {+ const c = window.__estellaHeadless.api.captureViewport();+ const cv = document.createElement('canvas'); cv.width = c.width; cv.height = c.height;+ const ctx = cv.getContext('2d'); const img = ctx.createImageData(c.width, c.height);+ const w = c.width, h = c.height, src = c.rgba;+ for (let y = 0; y < h; y++) { const sy = (h - 1 - y) * w * 4; img.data.set(src.subarray(sy, sy + w * 4), y * w * 4); }+ ctx.putImageData(img, 0, 0);+ return cv.toDataURL('image/png');+ })()`);+ await writeFile(process.env.ESTELLA_VERIFY_GRID_OUT, Buffer.from(dataUrl.split(',')[1], 'base64'));+ }+ if (BACKEND === 'webgpu') {+ const on = (await grabWebGPU()).rgba;+ await exec('window.__estellaHeadless.api.setGrid(false)');+ await exec('window.__estellaHeadless.api.step(2, 1 / 60)');+ const off = (await grabWebGPU()).rgba;+ let differing = 0;+ for (let i = 0; i < on.length; i += 4) {+ const d = Math.abs(on[i] - off[i]) + Math.abs(on[i + 1] - off[i + 1]) + Math.abs(on[i + 2] - off[i + 2]);+ if (d > 12) differing++;+ }+ grid = { differingPixels: differing, ok: differing > 300 };+ } else {+ await exec('window.__estellaGridOn = window.__estellaHeadless.api.captureViewport().rgba.slice()');+ await exec('window.__estellaHeadless.api.setGrid(false)');+ await exec('window.__estellaHeadless.api.step(2, 1 / 60)');+ grid = await exec(`(() => {+ const off = window.__estellaHeadless.api.captureViewport().rgba;+ const on = window.__estellaGridOn;+ let differing = 0;+ for (let i = 0; i < on.length; i += 4) {+ const d = Math.abs(on[i] - off[i]) + Math.abs(on[i + 1] - off[i + 1]) + Math.abs(on[i + 2] - off[i + 2]);+ if (d > 12) differing++;+ }+ return { differingPixels: differing, ok: differing > 300 };+ })()`);+ }+ }+ finish({ ok: true, entityCount, drawCalls, capture, expect, resize, preview, grid }, server);} catch (e) {finish({ ok: false, error: String((e && e.stack) || e) }, server);}diff --git a/desktop/src/engine/EditorControlSurface.ts b/desktop/src/engine/EditorControlSurface.tsindex 7d60887b1..c968dbd1d 100644--- a/desktop/src/engine/EditorControlSurface.ts+++ b/desktop/src/engine/EditorControlSurface.ts@@ -295,6 +295,16 @@ export class EditorControlSurfaceImpl {canvas.style.height = `${height}px`;}+ /**+ * Enable/disable the editor reference grid (headless verification + MCP).+ * Enabling also seeds + activates the editor view — the edit-mode camera the+ * grid draws through — since the headless host boots with it inactive.+ */+ setGrid(enabled: boolean, spacing?: number): void {+ if (enabled) EngineHost.syncEditorViewToScene();+ EngineHost.setGrid(enabled, spacing);+ }+captureViewport(): ViewportCapture {const canvas = EngineHost.canvas;if (!canvas) {diff --git a/docs/REARCHITECTURE.md b/docs/REARCHITECTURE.mdindex e97f5b326..bde5b582b 100644--- a/docs/REARCHITECTURE.md+++ b/docs/REARCHITECTURE.md@@ -184,7 +184,12 @@ TS 驱动的主 pass clear 退出边界,`clear` 家族退出公共 RHI:- **方法论教训(已入记忆)**:排查期间多次实验跑在陈旧 wasm 上导致结论互相矛盾;现在的协议是每轮 bisect 在源里嵌标记字符串、grep 部署产物 + 比对双份 md5 后才采信结果。- 验证(全部本地、BelowNormal):13 个 headless 场景全 PASS(含 postprocess-effects/lut-grade 两个后处理场景、mesh2d、ui-mask、lit×2);6 套 MockGfxDevice harness、SDK 241 测试文件(renderer/renderPipeline 测试更新为 load-op 契约)、desktop 63 文件、双侧 tsc、24 examples 全绿。**WebGPU 前仅剩一片**:GLSL-only `createProgram` → WGSL 通路。-### WGSL/WebGPU 通路 — 🟡 进行中:Phase 2 切片 1-4 已落地——**首帧点亮、批多纹理、离屏与区域 clear 全部工作**(2026-07-07)+### WGSL/WebGPU 通路 — 🟡 Phase 0-3 全部完结 + SDK 启动 + custom-draw 现代化;剩 Phase 4 cook 期用户材质(2026-07-08)+**Phase 2 收官(切片 5a/5b)**:深度/模板全通(surface 伴随 DS 纹理、管线按 pass DS 形状惰性变体、clearStencil 中帧仿真、采样器参数缓存 + group-1 纹理/采样器 8+8 配对);引擎初始化流接入(`EstellaContext::init(Unique<GfxDevice>)`,后端选择留在平台边界零 #ifdef)+ `webgpu_engine_bringup` 真 ECS 场景两后端逐点 diff=0。+**Phase 3 完结(切片 1-6,2026-07-07 单日)**:显式绑定布局(掩码缓存 BGL + 哑资源回填,纹理槽 8→16);`.esshader` `#pragma vertex/fragment wgsl` 孪生段 + 注入头双语发射(块变量移植规则 tc/mc/lc、std140≡WGSL 布局、feature 迷你预处理器);batch/shape/particle 内嵌归位单路径;7 模板 + 3 滤镜 + 13 后处理效果全部双语(PP 参数迁反射 MaterialConstants per-pass UBO,`u_resolution` 退役);materialGraph 单 DAG 双语发射。+**SDK 启动 + resize(campaign coda)**:web 变体带 WebGPU 后端(wechat/playable 保持 GL 零胶水体积)、`WebAppOptions.backend`、`ESTELLA_VERIFY_BACKEND=webgpu` 场景断言像素精确相等、`GfxDevice::resizeBackbuffer` 每帧契约(WebGPU swapchain 重配)。+**Custom-draw/Draw API 现代化(2026-07-08,最后一个 GL-only 通路闭合)**:新绑定 `draw_meshWithMaterial`——反射材质(compileEsshader)经 `MaterialStore::bindForDraw` 走 MaterialConstants(binding 1)+ 材质记录供给全部管线态,两后端同路零散装 uniform;TS 侧 18 名字 loose 表退为 raw-GLSL `createShader` 兼容路径。编辑器网格迁双语 `.esshader`(`u_model`→`u_rect` 参数 + authored vertex 声明 FrameConstants)——**WebGPU 下编辑器网格首次渲染**,GL/WebGPU 帧一致;`ESTELLA_VERIFY_GRID` 双后端 on/off 像素 diff 断言入 harness。+**剩余**:Phase 4 用户手写 `.esshader` 的 cook 期 naga 转换(归 RC6 资产管线;实测边界——mat-lit 等场景资产 shader 无孪生,WebGPU 下按设计描述性跳过);WebGPU 异步 readback seam(`readPixels` stub,材质预览断言跳过);CI 无 WebGPU 适配器(webgpu verify 仅本地)。见 `REARCH_WGSL.md`(本地 gitignore,同 RC6/2D_PARITY 约定):着色器版图盘点(uniform 数据已全后端中立,剩程序文本)、岔路拍板(有限集人工孪生 / 图材质 AST 双发射 / 用户材质 cook 期转换——拒绝运行时翻译器的 MB 级体积代价)、四期计划(源语言接缝 → WebGPUDevice 原型 → 双语发射 → cook 期用户材质)。**Phase 0 已落地**:最后 3 个 GLSL ES 1.00 残留(SDK outline/drop-shadow/color-matrix 滤镜)重写为 fragment-only `.esshader` 反射路径——顺带修复其设计性破损(raw 形态无 `u_projection` 来源、无属性绑定、mat4 超 `setMaterialUniform` 的 vec4 上限**从未能传入**;色彩矩阵改为 4×vec4 行 + 偏移列,新增 `Filters.colorMatrixUniforms` 助手)。全仓每个程序自此都在现代缝上(300 es + UBO 反射)。**Phase 1(源语言接缝)已落地**:RHI 补上最后一块后端中立拼图——`createProgram` 收语言标签的 `GfxShaderSource`,新增 `supportsShaderLanguage` 能力查询(GL = 仅 GLSL ES 300;`Shader::compile` 在任何 GPU 调用前对不支持的语言快速失败);语言贯穿 Shader/ResourceManager(DrawParams 重写仅对 GLSL 生效);`ShaderParser::assembleStage` 获得 `ShaderTargetLanguage` 参数(WGSL 发射 = Phase 3)。MockGfxDevice 新增 `wgslSupported` 开关 + 语言门用例;行为零变化(8 harness + 场景抽样等价)。**Phase 2 切片 1(WebGPU 后端启动)已落地**:emdawnwebgpu 端口(Dawn)集成为测试目标独立依赖(主构建零影响);`renderer/webgpu/` 新增纯映射层(GfxEnums→WGPU 全翻译,blend/模板表镜像 GLDevice 语义,load-op 规则与 RenderPassDesc 契约一致)+ 空设备安全的 `WebGPUDevice` 骨架(缓冲/纹理/WGSL 模块真实现,布局/管线描述符保留待惰性构建,pass/draw 为切片 2 结构化桩);`test_webgpu_device` 用真 Dawn 头编译验证全部描述符拼写,入 CI。diff --git a/sdk/src/camera/editorGridRenderer.ts b/sdk/src/camera/editorGridRenderer.tsindex 2c5a1fead..acf01851d 100644--- a/sdk/src/camera/editorGridRenderer.ts+++ b/sdk/src/camera/editorGridRenderer.ts@@ -10,13 +10,18 @@* paints minor / major / axis lines in WORLD space. Because it runs in the* pre-scene pass, scene entities occlude the grid (UE5 / Unity behaviour).*- * The quad is a unit quad scaled+translated by `u_model` to cover the camera's- * visible world rect (centre = EditorView.x/y, half-extent = orthoSize * aspect- * by orthoSize), so the fragment's interpolated world position is exact and no+ * The quad is a unit quad placed by the `u_rect` param (centre = EditorView.x/y,+ * half-extents = orthoSize * aspect by orthoSize) to cover the camera's visible+ * world rect, so the fragment's interpolated world position is exact and no* inverse view-projection is needed. Line width and minor-line density fade are* driven by `worldPerPixel` (= 2·orthoSize / viewportHeight), so the grid stays* crisp and moiré-free at every zoom without relying on GLSL derivatives.*+ * The shader is a dual-language `.esshader` (GLSL + WGSL twins) on the reflected+ * `#pragma param` seam: parameters ride the MaterialConstants UBO and the draw+ * goes through `Draw.drawMeshWithMaterial`'s reflected path, so the grid renders+ * on every backend.+ ** Frontends just install this once and flip the `EditorGrid` resource — the web* editor and the headless render host (pixel verification) get the grid for free.*/@@ -29,93 +34,163 @@ import { registerPreSceneDrawCallback } from '../customDraw';import { EditorView } from './EditorView';import { EditorGrid, DEFAULT_EDITOR_GRID } from './EditorGrid';-// GLSL ES 3.0, so the engine lifts the loose uniforms into its std140-// DrawParams block — this draw's parameters ride the UBO seam, not per-program-// uniform uploads.-const GRID_VERT = `#version 300 es-in vec2 a_position;-uniform mat4 u_projection;-uniform mat4 u_model;+/** The grid's dual-language material shader (exported for the twins structure guard). */+export const GRID_ESSHADER = `#pragma shader "EditorGrid"+#pragma version 300 es++#pragma param u_rect vec4 default(0,0,1,1)+#pragma param u_gridParams vec4 default(32,10,1,0)+#pragma param u_minorColor color default(1,1,1,0.05)+#pragma param u_majorColor color default(1,1,1,0.1)+#pragma param u_axisXColor color default(0.812,0.357,0.325,0.55)+#pragma param u_axisYColor color default(0.502,0.725,0.29,0.55)++#pragma vertex+layout(location = 0) in vec2 a_position;++layout(std140) uniform FrameConstants {+ mat4 u_projection;+};+out vec2 v_world;+void main() {- vec4 wp = u_model * vec4(a_position, 0.0, 1.0);- v_world = wp.xy;- gl_Position = u_projection * wp;+ // u_rect: xy = view centre, zw = half extents — the unit quad covers the+ // camera's visible world rect, so v_world interpolates exact world coords.+ vec2 world = u_rect.xy + a_position * u_rect.zw;+ v_world = world;+ gl_Position = u_projection * vec4(world, 0.0, 1.0);}-`;+#pragma end-const GRID_FRAG = `#version 300 es+#pragma fragmentprecision highp float;+in vec2 v_world;-uniform float u_param0; // minor spacing (world units)-uniform float u_param1; // major every Nth line-uniform float u_param2; // worldPerPixel-uniform vec4 u_color; // minor line color-uniform vec4 u_vec0; // major line color-uniform vec4 u_vec1; // X axis (world y=0) color-uniform vec4 u_vec2; // Y axis (world x=0) colorout vec4 fragColor;float lineCov(float coord, float sp, float lw, float aa) {- float d = abs(mod(coord + sp * 0.5, sp) - sp * 0.5);- return 1.0 - smoothstep(lw, lw + aa, d);+ float d = abs(mod(coord + sp * 0.5, sp) - sp * 0.5);+ return 1.0 - smoothstep(lw, lw + aa, d);}vec4 over(vec4 top, vec4 bot) {- float a = top.a + bot.a * (1.0 - top.a);- if (a <= 0.0) return vec4(0.0);- vec3 rgb = (top.rgb * top.a + bot.rgb * bot.a * (1.0 - top.a)) / a;- return vec4(rgb, a);+ float a = top.a + bot.a * (1.0 - top.a);+ if (a <= 0.0) return vec4(0.0);+ vec3 rgb = (top.rgb * top.a + bot.rgb * bot.a * (1.0 - top.a)) / a;+ return vec4(rgb, a);}void main() {- float sp = u_param0;- float major = sp * u_param1;- float aa = u_param2; // ~1px in world units- float lw = aa * 0.5; // ~1px line-- // Fade minor lines out as they crowd below a few pixels apart (anti-moiré).- float minorFade = smoothstep(3.0, 9.0, sp / max(u_param2, 1e-6));- float minorC = max(lineCov(v_world.x, sp, lw, aa), lineCov(v_world.y, sp, lw, aa)) * minorFade;- float majorC = max(lineCov(v_world.x, major, lw, aa), lineCov(v_world.y, major, lw, aa));- float axisXC = 1.0 - smoothstep(lw, lw + aa, abs(v_world.y)); // world y=0- float axisYC = 1.0 - smoothstep(lw, lw + aa, abs(v_world.x)); // world x=0-- vec4 c = vec4(0.0);- c = over(vec4(u_color.rgb, u_color.a * minorC), c);- c = over(vec4(u_vec0.rgb, u_vec0.a * majorC), c);- c = over(vec4(u_vec1.rgb, u_vec1.a * axisXC), c);- c = over(vec4(u_vec2.rgb, u_vec2.a * axisYC), c);- if (c.a <= 0.0) discard;- fragColor = c;+ float sp = u_gridParams.x; // minor spacing (world units)+ float major = sp * u_gridParams.y;+ float aa = u_gridParams.z; // worldPerPixel, ~1px in world units+ float lw = aa * 0.5; // ~1px line++ // Fade minor lines out as they crowd below a few pixels apart (anti-moiré).+ float minorFade = smoothstep(3.0, 9.0, sp / max(aa, 1e-6));+ float minorC = max(lineCov(v_world.x, sp, lw, aa), lineCov(v_world.y, sp, lw, aa)) * minorFade;+ float majorC = max(lineCov(v_world.x, major, lw, aa), lineCov(v_world.y, major, lw, aa));+ float axisXC = 1.0 - smoothstep(lw, lw + aa, abs(v_world.y)); // world y=0+ float axisYC = 1.0 - smoothstep(lw, lw + aa, abs(v_world.x)); // world x=0++ vec4 c = vec4(0.0);+ c = over(vec4(u_minorColor.rgb, u_minorColor.a * minorC), c);+ c = over(vec4(u_majorColor.rgb, u_majorColor.a * majorC), c);+ c = over(vec4(u_axisXColor.rgb, u_axisXColor.a * axisXC), c);+ c = over(vec4(u_axisYColor.rgb, u_axisYColor.a * axisYC), c);+ if (c.a <= 0.0) discard;+ fragColor = c;}+#pragma end++#pragma vertex wgsl+struct FrameConstants { projection : mat4x4f };+@group(0) @binding(0) var<uniform> frame : FrameConstants;++struct VSIn { @location(0) a_position : vec2f };+struct VSOut {+ @builtin(position) pos : vec4f,+ @location(0) v_world : vec2f,+};++@vertex fn vs_main(v : VSIn) -> VSOut {+ var out : VSOut;+ let world = mc.u_rect.xy + v.a_position * mc.u_rect.zw;+ out.v_world = world;+ out.pos = frame.projection * vec4f(world, 0.0, 1.0);+ return out;+}+#pragma end++#pragma fragment wgsl+struct VSOut {+ @builtin(position) pos : vec4f,+ @location(0) v_world : vec2f,+};++// GLSL mod(): floor-based remainder (result follows the divisor's sign) — WGSL's+// % is trunc-based, which would misplace grid lines on the negative world half.+fn gmod(x : f32, y : f32) -> f32 { return x - y * floor(x / y); }++fn lineCov(coord : f32, sp : f32, lw : f32, aa : f32) -> f32 {+ let d = abs(gmod(coord + sp * 0.5, sp) - sp * 0.5);+ return 1.0 - smoothstep(lw, lw + aa, d);+}++fn over(top : vec4f, bot : vec4f) -> vec4f {+ let a = top.a + bot.a * (1.0 - top.a);+ if (a <= 0.0) { return vec4f(0.0, 0.0, 0.0, 0.0); }+ let rgb = (top.rgb * top.a + bot.rgb * bot.a * (1.0 - top.a)) / a;+ return vec4f(rgb, a);+}++@fragment fn fs_main(v : VSOut) -> @location(0) vec4f {+ let sp = mc.u_gridParams.x;+ let major = sp * mc.u_gridParams.y;+ let aa = mc.u_gridParams.z;+ let lw = aa * 0.5;++ let minorFade = smoothstep(3.0, 9.0, sp / max(aa, 1e-6));+ let minorC = max(lineCov(v.v_world.x, sp, lw, aa), lineCov(v.v_world.y, sp, lw, aa)) * minorFade;+ let majorC = max(lineCov(v.v_world.x, major, lw, aa), lineCov(v.v_world.y, major, lw, aa));+ let axisXC = 1.0 - smoothstep(lw, lw + aa, abs(v.v_world.y));+ let axisYC = 1.0 - smoothstep(lw, lw + aa, abs(v.v_world.x));++ var c = vec4f(0.0, 0.0, 0.0, 0.0);+ c = over(vec4f(mc.u_minorColor.rgb, mc.u_minorColor.a * minorC), c);+ c = over(vec4f(mc.u_majorColor.rgb, mc.u_majorColor.a * majorC), c);+ c = over(vec4f(mc.u_axisXColor.rgb, mc.u_axisXColor.a * axisXC), c);+ c = over(vec4f(mc.u_axisYColor.rgb, mc.u_axisYColor.a * axisYC), c);+ if (c.a <= 0.0) { discard; }+ return c;+}+#pragma end`;let quad_: GeometryHandle = 0;let material_: MaterialHandle = 0;-// Reused column-major translate·scale model matrix (no per-frame allocation).-const model_ = new Float32Array(16);++// Per-param last-set cache: Material.setUniform re-flushes the whole material on+// every call, so skipping unchanged values keeps an idle frame at zero pushes.+const lastSet_ = new Map<string, [number, number, number, number]>();++function setParam(name: string, x: number, y: number, z: number, w: number): void {+ const prev = lastSet_.get(name);+ if (prev && prev[0] === x && prev[1] === y && prev[2] === z && prev[3] === w) return;+ lastSet_.set(name, [x, y, z, w]);+ Material.setUniform(material_, name, { x, y, z, w });+}function ensureResources(): boolean {if (material_) return true;- const shader = Material.createShader(GRID_VERT, GRID_FRAG);+ const shader = Material.compileShader(GRID_ESSHADER);if (!shader) return false;quad_ = Geometry.createQuad(2, 2); // [-1, 1] unit quadmaterial_ = Material.create({ shader, blendMode: BlendMode.Normal, depthTest: false });return true;}-// translate(tx,ty) · scale(sx,sy) as a column-major 4x4.-function setModel(m: Float32Array, tx: number, ty: number, sx: number, sy: number): void {- m.fill(0);- m[0] = sx;- m[5] = sy;- m[10] = 1;- m[15] = 1;- m[12] = tx;- m[13] = ty;-}-/*** Register the editor grid renderer on this App. Idempotent per App: inserts the* default `EditorGrid` resource if absent and registers the pre-scene draw pass.@@ -135,16 +210,14 @@ export function installEditorGrid(app: App): void {const halfH = view.orthoSize;const halfW = halfH * (width / height);const worldPerPixel = (2 * halfH) / height;- setModel(model_, view.x, view.y, halfW, halfH);- Material.setUniform(material_, 'u_param0', grid.spacing);- Material.setUniform(material_, 'u_param1', grid.majorEvery);- Material.setUniform(material_, 'u_param2', worldPerPixel);- Material.setUniform(material_, 'u_color', grid.color);- Material.setUniform(material_, 'u_vec0', grid.majorColor);- Material.setUniform(material_, 'u_vec1', grid.axisX);- Material.setUniform(material_, 'u_vec2', grid.axisY);+ setParam('u_rect', view.x, view.y, halfW, halfH);+ setParam('u_gridParams', grid.spacing, grid.majorEvery, worldPerPixel, 0);+ setParam('u_minorColor', grid.color[0], grid.color[1], grid.color[2], grid.color[3]);+ setParam('u_majorColor', grid.majorColor[0], grid.majorColor[1], grid.majorColor[2], grid.majorColor[3]);+ setParam('u_axisXColor', grid.axisX[0], grid.axisX[1], grid.axisX[2], grid.axisX[3]);+ setParam('u_axisYColor', grid.axisY[0], grid.axisY[1], grid.axisY[2], grid.axisY[3]);- Draw.drawMeshWithMaterial(quad_, material_, model_);+ Draw.drawMeshWithMaterial(quad_, material_);});}diff --git a/sdk/src/draw.ts b/sdk/src/draw.tsindex 3fa3c0109..314c7525a 100644--- a/sdk/src/draw.ts+++ b/sdk/src/draw.ts@@ -32,6 +32,9 @@ let uniformsPtr: number = 0;const UNIFORMS_BUFFER_SIZE = 256;const uniformBuffer = new Float32Array(UNIFORMS_BUFFER_SIZE);+// Identity model matrix for legacy material draws that omit `transform`.+const IDENTITY_TRANSFORM = new Float32Array([1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1]);+// =============================================================================// Initialization// =============================================================================@@ -190,11 +193,19 @@ export interface DrawAPI {/*** Draws a custom mesh with a material.+ *+ * A material whose shader was compiled from a `.esshader` (Material.compileShader)+ * draws through the reflected MaterialConstants path: its `#pragma param` values and+ * render state come straight from the engine material store, the shader positions+ * itself via the injected FrameConstants (and params), and `transform` is unused —+ * this path runs on every backend. A raw-GLSL material (Material.createShader) uses+ * the legacy loose-uniform stream with `u_projection`/`u_model` and `transform`+ * (identity when omitted).* @param geometry Geometry handle* @param material Material handle- * @param transform Transform matrix (4x4, column-major)+ * @param transform Transform matrix (4x4, column-major) — legacy raw-GLSL path only*/- drawMeshWithMaterial(geometry: GeometryHandle, material: MaterialHandle, transform: Float32Array): void;+ drawMeshWithMaterial(geometry: GeometryHandle, material: MaterialHandle, transform?: Float32Array): void;}// =============================================================================@@ -359,22 +370,28 @@ export const Draw: DrawAPI = {}},- drawMeshWithMaterial(geometry: GeometryHandle, material: MaterialHandle, transform: Float32Array): void {+ drawMeshWithMaterial(geometry: GeometryHandle, material: MaterialHandle, transform?: Float32Array): void {try {const m = getModule();const matData = Material.get(material);if (!matData) return;+ // Reflected path first: a compileEsshader material draws entirely from the+ // engine material store (params + render state + pipeline), backend-neutral.+ // False means the shader has no #pragma-param layout — legacy stream below.+ if (m.draw_meshWithMaterial(geometry, material)) return;+Draw.setBlendMode(matData.blendMode);Draw.setDepthTest(matData.depthTest);+ if (transform) m.HEAPF32.set(transform, transformPtr / 4);+ else m.HEAPF32.set(IDENTITY_TRANSFORM, transformPtr / 4);+if (matData.uniforms.size === 0) {- Draw.drawMesh(geometry, matData.shader, transform);+ m.draw_mesh(geometry, matData.shader, transformPtr);return;}- m.HEAPF32.set(transform, transformPtr / 4);-let idx: number;if (!matData.dirty_ && matData.cachedBuffer_) {idx = matData.cachedIdx_;diff --git a/sdk/src/wasm.ts b/sdk/src/wasm.tsindex c791f8b6c..87c0150af 100644--- a/sdk/src/wasm.ts+++ b/sdk/src/wasm.ts@@ -235,6 +235,9 @@ export interface ESEngineModule {draw_mesh(geometryHandle: number, shaderHandle: number, transformPtr: number): void;draw_meshWithUniforms(geometryHandle: number, shaderHandle: number, transformPtr: number,uniformsPtr: number, uniformCount: number): void;+ /** Reflected-material mesh draw (MaterialConstants UBO); false = shader has no+ * #pragma-param layout, caller falls back to the loose uniform stream. */+ draw_meshWithMaterial(geometryHandle: number, materialId: number): boolean;// Geometry APIgeometry_create(): number;diff --git a/sdk/tests/draw.test.ts b/sdk/tests/draw.test.tsindex f7912ea68..28734c7ed 100644--- a/sdk/tests/draw.test.ts+++ b/sdk/tests/draw.test.ts@@ -65,6 +65,9 @@ function createDrawMockModule() {draw_getPrimitiveCount: vi.fn(() => 128),draw_mesh: vi.fn(),draw_meshWithUniforms: vi.fn(),+ // Reflected-material route: false = no #pragma-param layout, use the+ // legacy uniform stream (most cases below exercise the legacy encoding).+ draw_meshWithMaterial: vi.fn(() => false),};return mock;@@ -451,6 +454,68 @@ describe('Draw API', () => {expect(mock.draw_meshWithUniforms).not.toHaveBeenCalled();});+ it('routes through the reflected material path when the engine reports a layout', () => {+ const materials = (Material as any)._materials;+ materials.set(21, {+ shader: 10,+ uniforms: new Map([['u_rect', { x: 1, y: 2, z: 3, w: 4 }]]),+ blendMode: BlendMode.Additive,+ depthTest: true,+ dirty_: true,+ cachedBuffer_: null,+ cachedIdx_: 0,+ });+ mock.draw_meshWithMaterial.mockReturnValueOnce(true);++ Draw.drawMeshWithMaterial(geometry, 21 as any);++ expect(mock.draw_meshWithMaterial).toHaveBeenCalledWith(geometry, 21);+ // The engine material store owns render state + params on this path —+ // no legacy session-state writes, no uniform-stream encoding.+ expect(mock.draw_setBlendMode).not.toHaveBeenCalled();+ expect(mock.draw_setDepthTest).not.toHaveBeenCalled();+ expect(mock.draw_mesh).not.toHaveBeenCalled();+ expect(mock.draw_meshWithUniforms).not.toHaveBeenCalled();+ });++ it('falls back to the legacy stream when there is no reflected layout', () => {+ const materials = (Material as any)._materials;+ materials.set(22, {+ shader: 10,+ uniforms: new Map([['u_time', 1.5]]),+ blendMode: BlendMode.Normal,+ depthTest: false,+ dirty_: true,+ cachedBuffer_: null,+ cachedIdx_: 0,+ });++ Draw.drawMeshWithMaterial(geometry, 22 as any, transform);++ expect(mock.draw_meshWithMaterial).toHaveBeenCalledWith(geometry, 22);+ expect(mock.draw_meshWithUniforms).toHaveBeenCalled();+ });++ it('legacy draw uses the identity transform when omitted', () => {+ const materials = (Material as any)._materials;+ materials.set(23, {+ shader: 10,+ uniforms: new Map(),+ blendMode: BlendMode.Normal,+ depthTest: false,+ dirty_: true,+ cachedBuffer_: null,+ cachedIdx_: 0,+ });++ Draw.drawMeshWithMaterial(geometry, 23 as any);++ expect(mock.draw_mesh).toHaveBeenCalled();+ const transformP = mock.draw_mesh.mock.calls[0][2];+ const t = mock.HEAPF32.subarray(transformP / 4, transformP / 4 + 16);+ expect(Array.from(t)).toEqual([1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1]);+ });+it('should call drawMesh when material has no uniforms', () => {const materials = (Material as any)._materials;materials.set(1, {diff --git a/sdk/tests/shader-twins.test.ts b/sdk/tests/shader-twins.test.tsindex a146fa8ab..25290e68b 100644--- a/sdk/tests/shader-twins.test.ts+++ b/sdk/tests/shader-twins.test.ts@@ -45,13 +45,16 @@ const CASES: Array<{ name: string; source: string }> = [...embeddedEsshaders('spriteFilter.ts').map((source, i) => ({ name: `spriteFilter.ts[${i}]`, source })),...embeddedEsshaders('postprocess/postProcessEffects.ts').map((source, i) => ({ name: `postProcessEffects.ts[${i}]`, source })),+ ...embeddedEsshaders('camera/editorGridRenderer.ts').map(+ (source, i) => ({ name: `editorGridRenderer.ts[${i}]`, source })),];describe('embedded .esshader structure', () => {- it('found the filter and effect sources', () => {+ it('found the filter, effect and grid sources', () => {expect(CASES.filter((c) => c.name.startsWith('filters.ts')).length).toBe(1);expect(CASES.filter((c) => c.name.startsWith('spriteFilter.ts')).length).toBe(2);expect(CASES.filter((c) => c.name.startsWith('postProcessEffects.ts')).length).toBe(13);+ expect(CASES.filter((c) => c.name.startsWith('editorGridRenderer.ts')).length).toBe(1);});for (const { name, source } of CASES) {@@ -64,5 +67,15 @@ describe('embedded .esshader structure', () => {const wgsl = source.slice(source.indexOf('#pragma fragment wgsl'));expect(wgsl).toContain('fn fs_main(');});++ // A shader that authors its own vertex stage (no canonical injection)+ // must also carry the WGSL vertex twin, or it cannot link on WebGPU.+ if (/^#pragma vertex\s*$/m.test(source)) {+ it(`${name}: authored vertex carries a WGSL twin with the vs_main entry point`, () => {+ expect(source).toContain('#pragma vertex wgsl');+ const wgsl = source.slice(source.indexOf('#pragma vertex wgsl'));+ expect(wgsl).toContain('fn vs_main(');+ });+ }}});diff --git a/src/esengine/bindings/GeometryBindings.cpp b/src/esengine/bindings/GeometryBindings.cppindex fafd61823..98daa876d 100644--- a/src/esengine/bindings/GeometryBindings.cpp+++ b/src/esengine/bindings/GeometryBindings.cpp@@ -8,6 +8,7 @@#include "../renderer/GfxDevice.hpp"#include "../renderer/CustomGeometry.hpp"#include "../renderer/Buffer.hpp"+#include "../renderer/MaterialStore.hpp"#include "../renderer/RenderContext.hpp"#include "../renderer/RenderFrame.hpp"#include "../renderer/ImmediateDraw.hpp"@@ -30,6 +31,7 @@ static EstellaContext& ctx() { return activeCtx(); }#define g_immediateDraw (ctx().tryGet<ImmediateDraw>())#define g_immediateDrawActive (ctx().state().immediate_draw_active)#define g_currentViewProjection (ctx().state().current_view_projection)+#define g_renderContext (ctx().tryGet<RenderContext>())static void flushImmediateDrawIfActive() {if (g_immediateDrawActive && g_immediateDraw) {@@ -37,6 +39,20 @@ static void flushImmediateDrawIfActive() {}}+// Bind + submit a custom geometry through the device (indexed or arrays).+static void drawGeometry(GfxDevice& device, CustomGeometry& geom) {+ geom.bind(device);+ if (geom.hasIndices()) {+ auto* ib = geom.indexBuffer();+ if (ib) {+ auto type = ib->is16Bit() ? GfxDataType::UnsignedShort : GfxDataType::UnsignedInt;+ device.drawElements(geom.getIndexCount(), type, 0);+ }+ } else {+ device.drawArrays(0, geom.getVertexCount());+ }+}+// A mesh draw's pipeline: the requested shader + this geometry's vertex layout,// with blend/depth taken from the immediate-draw session state (Draw.setBlendMode /// setDepthTest apply to mesh draws too). The pipeline cache dedupes repeats.@@ -159,17 +175,46 @@ void draw_mesh(u32 geometryHandle, u32 shaderHandle, uintptr_t transformPtr) {shader->setUniform("u_model", transform);shader->commitParams();- geom->bind(ctx().require<GfxDevice>());+ drawGeometry(*g_device, *geom);+}++bool draw_meshWithMaterial(u32 geometryHandle, u32 materialId) {+ if (!g_initialized || !g_geometryManager) return false;+ auto* rc = g_renderContext;+ if (!rc) return false;- if (geom->hasIndices()) {- auto* ib = geom->indexBuffer();- if (ib) {- auto type = ib->is16Bit() ? GfxDataType::UnsignedShort : GfxDataType::UnsignedInt;- g_device->drawElements(geom->getIndexCount(), type, 0);- }- } else {- g_device->drawArrays(0, geom->getVertexCount());- }+ // Route through the reflected path only when the material's shader registered a+ // #pragma-param layout (compileEsshader). A raw-GLSL createShader program has no+ // layout — return false so the SDK falls back to the legacy uniform-stream path.+ const MaterialRecord* rec = rc->materials().find(materialId);+ if (!rec || !rc->materials().layoutFor(rec->shader)) return false;++ auto* geom = g_geometryManager->get(geometryHandle);+ if (!geom || !geom->isValid()) return true; // routed modern; nothing to draw++ flushImmediateDrawIfActive();++ // The material record supplies the full pipeline state (same resolve as+ // DrawList::execute); positioning comes from FrameConstants + params in the+ // shader — no per-draw loose uniforms, so the draw is backend-neutral.+ GfxDevice& device = *g_device;+ PipelineDesc desc{};+ desc.program = ShaderHandle{rec->shader};+ desc.vertexLayout = geom->layoutHandle();+ desc.blend = rec->blend;+ desc.blendEnabled = true;+ desc.depthTest = rec->depthTest;+ desc.depthWrite = rec->depthWrite;+ desc.cullEnabled = rec->cull != CullMode::None;+ desc.cullFront = rec->cull == CullMode::Front;+ device.invalidatePipelineCache();+ device.setPipeline(device.createPipeline(desc));++ // Per-material constants (binding 1): upload-if-dirty + bind, plus texture params.+ rc->materials().bindForDraw(materialId);++ drawGeometry(device, *geom);+ return true;}void draw_meshWithUniforms(u32 geometryHandle, u32 shaderHandle, uintptr_t transformPtr,@@ -256,17 +301,7 @@ void draw_meshWithUniforms(u32 geometryHandle, u32 shaderHandle, uintptr_t trans// shader's DrawParams block; flush + bind them for this draw.shader->commitParams();- geom->bind(ctx().require<GfxDevice>());-- if (geom->hasIndices()) {- auto* ib = geom->indexBuffer();- if (ib) {- auto type = ib->is16Bit() ? GfxDataType::UnsignedShort : GfxDataType::UnsignedInt;- g_device->drawElements(geom->getIndexCount(), type, 0);- }- } else {- g_device->drawArrays(0, geom->getVertexCount());- }+ drawGeometry(*g_device, *geom);}} // namespace esenginediff --git a/src/esengine/bindings/GeometryBindings.hpp b/src/esengine/bindings/GeometryBindings.hppindex 8b4c9d463..79235994c 100644--- a/src/esengine/bindings/GeometryBindings.hpp+++ b/src/esengine/bindings/GeometryBindings.hpp@@ -19,6 +19,7 @@ bool geometry_isValid(u32 handle);void draw_mesh(u32 geometryHandle, u32 shaderHandle, uintptr_t transformPtr);void draw_meshWithUniforms(u32 geometryHandle, u32 shaderHandle, uintptr_t transformPtr,uintptr_t uniformsPtr, u32 uniformCount);+bool draw_meshWithMaterial(u32 geometryHandle, u32 materialId);} // namespace esenginediff --git a/src/esengine/bindings/WebSDKEntry.cpp b/src/esengine/bindings/WebSDKEntry.cppindex fdefd10ef..0bbc1ae9a 100644--- a/src/esengine/bindings/WebSDKEntry.cpp+++ b/src/esengine/bindings/WebSDKEntry.cpp@@ -511,6 +511,7 @@ EMSCRIPTEN_BINDINGS(esengine_renderer) {emscripten::function("draw_setDepthTest", &esengine::draw_setDepthTest);emscripten::function("draw_mesh", &esengine::draw_mesh);emscripten::function("draw_meshWithUniforms", &esengine::draw_meshWithUniforms);+ emscripten::function("draw_meshWithMaterial", &esengine::draw_meshWithMaterial);emscripten::function("geometry_create", &esengine::geometry_create);emscripten::function("geometry_init", &esengine::geometry_init);