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(material): first-class material system — params, instances, Lit-2D, graph, preview
esenginec85f84ac6edc
diff --git a/CMakeLists.txt b/CMakeLists.txtindex 81ee1e02e..f45b752cd 100644--- a/CMakeLists.txt+++ b/CMakeLists.txt@@ -54,6 +54,8 @@ set(ESENGINE_SOURCESsrc/esengine/renderer/TransientBufferPool.cppsrc/esengine/renderer/DrawList.cppsrc/esengine/renderer/BatchBuilder.cpp+ src/esengine/renderer/MaterialStore.cpp+ src/esengine/renderer/LightStore.cppsrc/esengine/renderer/plugins/BatchPlugin.cppsrc/esengine/renderer/plugins/SpritePlugin.cppsrc/esengine/renderer/plugins/UIElementPlugin.cppdiff --git a/desktop/package.json b/desktop/package.jsonindex 85bc0f0d7..7e3289c66 100644--- a/desktop/package.json+++ b/desktop/package.json@@ -22,6 +22,17 @@"verify:render:text:rect": "vite build && ESTELLA_VERIFY_SCENE=/scenes/ui-text-rect.esscene ESTELLA_VERIFY_MANIFEST=/scenes/ui-text-sdf.textures.json electron scripts/headless-verify.mjs","verify:render:uinode": "vite build && ESTELLA_VERIFY_SCENE=/scenes/ui-node-flex.esscene ESTELLA_VERIFY_MANIFEST=/scenes/ui-node-flex.textures.json ESTELLA_VERIFY_W=800 ESTELLA_VERIFY_H=600 electron scripts/headless-verify.mjs","verify:render:tilemap": "vite build && ESTELLA_VERIFY_SCENE=/scenes/tilemap-flip.esscene ESTELLA_VERIFY_MANIFEST=/scenes/tilemap-flip.textures.json ESTELLA_VERIFY_W=256 ESTELLA_VERIFY_H=256 ESTELLA_VERIFY_STEPS=2 ESTELLA_VERIFY_EXPECT=\"[{\\\"x\\\":0.46,\\\"y\\\":0.5,\\\"rgb\\\":[255,0,0]},{\\\"x\\\":0.84,\\\"y\\\":0.5,\\\"rgb\\\":[0,255,0]},{\\\"x\\\":0.46,\\\"y\\\":0.84,\\\"rgb\\\":[0,0,255]},{\\\"x\\\":0.84,\\\"y\\\":0.84,\\\"rgb\\\":[255,255,0]}]\" electron scripts/headless-verify.mjs",+ "verify:render:material": "vite build && ESTELLA_VERIFY_SCENE=/scenes/mat-tint.esscene ESTELLA_VERIFY_MANIFEST=/scenes/mat-tint.textures.json ESTELLA_VERIFY_W=256 ESTELLA_VERIFY_H=256 ESTELLA_VERIFY_STEPS=2 ESTELLA_VERIFY_EXPECT=\"[{\\\"x\\\":0.5,\\\"y\\\":0.5,\\\"rgb\\\":[255,0,0],\\\"tol\\\":40}]\" electron scripts/headless-verify.mjs",+ "verify:render:material:instance": "vite build && ESTELLA_VERIFY_SCENE=/scenes/mat-instance.esscene ESTELLA_VERIFY_MANIFEST=/scenes/mat-instance.textures.json ESTELLA_VERIFY_W=256 ESTELLA_VERIFY_H=256 ESTELLA_VERIFY_STEPS=2 ESTELLA_VERIFY_EXPECT=\"[{\\\"x\\\":0.5,\\\"y\\\":0.5,\\\"rgb\\\":[0,255,0],\\\"tol\\\":40}]\" electron scripts/headless-verify.mjs",+ "verify:render:material:texture": "vite build && ESTELLA_VERIFY_SCENE=/scenes/mat-tex.esscene ESTELLA_VERIFY_MANIFEST=/scenes/mat-tex.textures.json ESTELLA_VERIFY_W=256 ESTELLA_VERIFY_H=256 ESTELLA_VERIFY_STEPS=2 ESTELLA_VERIFY_EXPECT=\"[{\\\"x\\\":0.5,\\\"y\\\":0.5,\\\"rgb\\\":[0,255,0],\\\"tol\\\":50}]\" electron scripts/headless-verify.mjs",+ "verify:render:material:switch": "vite build && ESTELLA_VERIFY_SCENE=/scenes/mat-sw.esscene ESTELLA_VERIFY_MANIFEST=/scenes/mat-sw.textures.json ESTELLA_VERIFY_W=256 ESTELLA_VERIFY_H=256 ESTELLA_VERIFY_STEPS=2 ESTELLA_VERIFY_EXPECT=\"[{\\\"x\\\":0.25,\\\"y\\\":0.5,\\\"rgb\\\":[255,0,0],\\\"tol\\\":50},{\\\"x\\\":0.75,\\\"y\\\":0.5,\\\"rgb\\\":[0,255,0],\\\"tol\\\":50}]\" electron scripts/headless-verify.mjs",+ "verify:render:material:lit": "vite build && ESTELLA_VERIFY_SCENE=/scenes/mat-lit.esscene ESTELLA_VERIFY_MANIFEST=/scenes/mat-lit.textures.json ESTELLA_VERIFY_W=256 ESTELLA_VERIFY_H=256 ESTELLA_VERIFY_STEPS=2 ESTELLA_VERIFY_EXPECT=\"[{\\\"x\\\":0.5,\\\"y\\\":0.5,\\\"rgb\\\":[0,255,0],\\\"tol\\\":50}]\" electron scripts/headless-verify.mjs",+ "verify:render:material:lit:point": "vite build && ESTELLA_VERIFY_SCENE=/scenes/mat-lit-point.esscene ESTELLA_VERIFY_MANIFEST=/scenes/mat-lit-point.textures.json ESTELLA_VERIFY_W=256 ESTELLA_VERIFY_H=256 ESTELLA_VERIFY_STEPS=2 ESTELLA_VERIFY_EXPECT=\"[{\\\"x\\\":0.5,\\\"y\\\":0.5,\\\"rgb\\\":[0,255,0],\\\"tol\\\":50},{\\\"x\\\":0.75,\\\"y\\\":0.5,\\\"rgb\\\":[0,64,0],\\\"tol\\\":60}]\" electron scripts/headless-verify.mjs",+ "verify:render:material:lit:normal": "vite build && ESTELLA_VERIFY_SCENE=/scenes/mat-lit-normal.esscene ESTELLA_VERIFY_MANIFEST=/scenes/mat-lit-normal.textures.json ESTELLA_VERIFY_W=256 ESTELLA_VERIFY_H=256 ESTELLA_VERIFY_STEPS=2 ESTELLA_VERIFY_EXPECT=\"[{\\\"x\\\":0.333,\\\"y\\\":0.5,\\\"rgb\\\":[0,252,0],\\\"tol\\\":45},{\\\"x\\\":0.667,\\\"y\\\":0.5,\\\"rgb\\\":[0,36,0],\\\"tol\\\":50}]\" electron scripts/headless-verify.mjs",+ "verify:render:material:lit:spot": "vite build && ESTELLA_VERIFY_SCENE=/scenes/mat-lit-spot.esscene ESTELLA_VERIFY_MANIFEST=/scenes/mat-lit-spot.textures.json ESTELLA_VERIFY_W=256 ESTELLA_VERIFY_H=256 ESTELLA_VERIFY_STEPS=2 ESTELLA_VERIFY_EXPECT=\"[{\\\"x\\\":0.5,\\\"y\\\":0.5,\\\"rgb\\\":[0,228,0],\\\"tol\\\":55},{\\\"x\\\":0.75,\\\"y\\\":0.5,\\\"rgb\\\":[0,0,0],\\\"tol\\\":35}]\" electron scripts/headless-verify.mjs",+ "verify:render:material:lit:flatnormal": "vite build && ESTELLA_VERIFY_SCENE=/scenes/mat-lit-flatnormal.esscene ESTELLA_VERIFY_MANIFEST=/scenes/mat-lit-flatnormal.textures.json ESTELLA_VERIFY_W=256 ESTELLA_VERIFY_H=256 ESTELLA_VERIFY_STEPS=2 ESTELLA_VERIFY_EXPECT=\"[{\\\"x\\\":0.5,\\\"y\\\":0.5,\\\"rgb\\\":[0,255,0],\\\"tol\\\":30}]\" electron scripts/headless-verify.mjs",+ "verify:render:material:graph": "vite build && ESTELLA_VERIFY_SCENE=/scenes/mat-graph.esscene ESTELLA_VERIFY_MANIFEST=/scenes/mat-graph.textures.json ESTELLA_VERIFY_W=256 ESTELLA_VERIFY_H=256 ESTELLA_VERIFY_STEPS=2 ESTELLA_VERIFY_EXPECT=\"[{\\\"x\\\":0.5,\\\"y\\\":0.5,\\\"rgb\\\":[255,0,0],\\\"tol\\\":40}]\" electron scripts/headless-verify.mjs",+ "verify:render:material:preview": "vite build && ESTELLA_VERIFY_SCENE=/scenes/mat-tint.esscene ESTELLA_VERIFY_MANIFEST=/scenes/mat-tint.textures.json ESTELLA_VERIFY_W=256 ESTELLA_VERIFY_H=256 ESTELLA_VERIFY_STEPS=2 ESTELLA_VERIFY_PREVIEW=\"{\\\"w\\\":64,\\\"h\\\":64,\\\"rgb\\\":[255,0,0],\\\"tol\\\":45}\" electron scripts/headless-verify.mjs","verify:smoke": "vite build && electron scripts/headless-smoke.mjs","mcp": "electron electron/mcp/server.mjs","mcp:smoke": "vite build && node electron/mcp/smoke.mjs"diff --git a/desktop/public/scenes/mat-graph.esscene b/desktop/public/scenes/mat-graph.esscenenew file mode 100644index 000000000..894e66fce--- /dev/null+++ b/desktop/public/scenes/mat-graph.esscene@@ -0,0 +1,35 @@+{+ "version": "1.0",+ "name": "Main",+ "entities": [+ {+ "id": 0,+ "name": "Camera",+ "parent": null,+ "children": [],+ "components": [+ { "type": "Transform", "data": { "position": { "x": 0, "y": 0, "z": 10 } } },+ { "type": "Camera", "data": { "projectionType": 1, "orthoSize": 300, "isActive": true, "priority": 0 } }+ ],+ "visible": true+ },+ {+ "id": 1,+ "name": "Graphed",+ "parent": null,+ "children": [],+ "components": [+ { "type": "Transform", "data": { "position": { "x": 0, "y": 0, "z": 0 } } },+ {+ "type": "Sprite",+ "data": {+ "size": { "x": 400, "y": 400 },+ "color": { "r": 1, "g": 1, "b": 1, "a": 1 },+ "material": "/scenes/mat-graph/graph-tint.esmaterial"+ }+ }+ ],+ "visible": true+ }+ ]+}diff --git a/desktop/public/scenes/mat-graph.textures.json b/desktop/public/scenes/mat-graph.textures.jsonnew file mode 100644index 000000000..0967ef424--- /dev/null+++ b/desktop/public/scenes/mat-graph.textures.json@@ -0,0 +1 @@+{}diff --git a/desktop/public/scenes/mat-graph/graph-tint.esmaterial b/desktop/public/scenes/mat-graph/graph-tint.esmaterialnew file mode 100644index 000000000..4eab73e2f--- /dev/null+++ b/desktop/public/scenes/mat-graph/graph-tint.esmaterial@@ -0,0 +1,12 @@+{+ "version": "1.0",+ "type": "material",+ "shader": "graph-tint.esshader",+ "blendMode": 0,+ "depthTest": false,+ "depthWrite": true,+ "cull": 0,+ "properties": {+ "u_tint": { "r": 1, "g": 0, "b": 0, "a": 1 }+ }+}diff --git a/desktop/public/scenes/mat-graph/graph-tint.esmatgraph b/desktop/public/scenes/mat-graph/graph-tint.esmatgraphnew file mode 100644index 000000000..0a29594bf--- /dev/null+++ b/desktop/public/scenes/mat-graph/graph-tint.esmatgraph@@ -0,0 +1,42 @@+{+ "name": "GraphTint",+ "output": "out",+ "nodes": [+ {+ "id": "tex",+ "type": "textureSample",+ "params": {+ "name": "u_albedo",+ "default": "white"+ }+ },+ {+ "id": "tint",+ "type": "constColor",+ "params": {+ "name": "u_tint",+ "value": [+ 1,+ 1,+ 1,+ 1+ ]+ }+ },+ {+ "id": "mul",+ "type": "multiply",+ "inputs": {+ "a": "tex",+ "b": "tint"+ }+ },+ {+ "id": "out",+ "type": "output",+ "inputs": {+ "color": "mul"+ }+ }+ ]+}diff --git a/desktop/public/scenes/mat-graph/graph-tint.esshader b/desktop/public/scenes/mat-graph/graph-tint.esshadernew file mode 100644index 000000000..2dd0e9467--- /dev/null+++ b/desktop/public/scenes/mat-graph/graph-tint.esshader@@ -0,0 +1,40 @@+#pragma shader "GraphTint"+#pragma version 300 es+#pragma domain Unlit2D+#pragma param u_albedo texture default(white)+#pragma param u_tint color default(1,1,1,1)++#pragma vertex+layout(location = 0) in vec2 a_position;+layout(location = 1) in vec4 a_color;+layout(location = 2) in vec2 a_texCoord;+layout(location = 3) in float a_texIndex;++layout(std140) uniform FrameConstants {+ mat4 u_projection;+};++out vec4 v_color;+out vec2 v_texCoord;++void main() {+ gl_Position = u_projection * vec4(a_position, 0.0, 1.0);+ v_color = a_color;+ v_texCoord = a_texCoord;+}+#pragma end++#pragma fragment+precision mediump float;++in vec4 v_color;+in vec2 v_texCoord;++out vec4 fragColor;++void main() {+ vec4 n0 = texture(u_albedo, v_texCoord);+ vec4 n1 = n0 * u_tint;+ fragColor = n1;+}+#pragma enddiff --git a/desktop/public/scenes/mat-instance.esscene b/desktop/public/scenes/mat-instance.esscenenew file mode 100644index 000000000..9325c0486--- /dev/null+++ b/desktop/public/scenes/mat-instance.esscene@@ -0,0 +1,35 @@+{+ "version": "1.0",+ "name": "Main",+ "entities": [+ {+ "id": 0,+ "name": "Camera",+ "parent": null,+ "children": [],+ "components": [+ { "type": "Transform", "data": { "position": { "x": 0, "y": 0, "z": 10 } } },+ { "type": "Camera", "data": { "projectionType": 1, "orthoSize": 300, "isActive": true, "priority": 0 } }+ ],+ "visible": true+ },+ {+ "id": 1,+ "name": "InstanceTinted",+ "parent": null,+ "children": [],+ "components": [+ { "type": "Transform", "data": { "position": { "x": 0, "y": 0, "z": 0 } } },+ {+ "type": "Sprite",+ "data": {+ "size": { "x": 400, "y": 400 },+ "color": { "r": 1, "g": 1, "b": 1, "a": 1 },+ "material": "/scenes/mat-tint/tint-green.esmaterial"+ }+ }+ ],+ "visible": true+ }+ ]+}diff --git a/desktop/public/scenes/mat-instance.textures.json b/desktop/public/scenes/mat-instance.textures.jsonnew file mode 100644index 000000000..0967ef424--- /dev/null+++ b/desktop/public/scenes/mat-instance.textures.json@@ -0,0 +1 @@+{}diff --git a/desktop/public/scenes/mat-lit-flatnormal.esscene b/desktop/public/scenes/mat-lit-flatnormal.esscenenew file mode 100644index 000000000..275d519db--- /dev/null+++ b/desktop/public/scenes/mat-lit-flatnormal.esscene@@ -0,0 +1,54 @@+{+ "version": "1.0",+ "name": "Main",+ "entities": [+ {+ "id": 0,+ "name": "Camera",+ "parent": null,+ "children": [],+ "components": [+ { "type": "Transform", "data": { "position": { "x": 0, "y": 0, "z": 10 } } },+ { "type": "Camera", "data": { "projectionType": 1, "orthoSize": 300, "isActive": true, "priority": 0 } }+ ],+ "visible": true+ },+ {+ "id": 1,+ "name": "Lit",+ "parent": null,+ "children": [],+ "components": [+ { "type": "Transform", "data": { "position": { "x": 0, "y": 0, "z": 0 } } },+ {+ "type": "Sprite",+ "data": {+ "size": { "x": 400, "y": 400 },+ "color": { "r": 1, "g": 1, "b": 1, "a": 1 },+ "material": "/scenes/mat-lit-flatnormal/lit-fn.esmaterial"+ }+ }+ ],+ "visible": true+ },+ {+ "id": 2,+ "name": "GreenLight",+ "parent": null,+ "children": [],+ "components": [+ { "type": "Transform", "data": { "position": { "x": 0, "y": 0, "z": 0 } } },+ {+ "type": "Light2D",+ "data": {+ "type": 1,+ "color": { "r": 0, "g": 1, "b": 0, "a": 1 },+ "intensity": 1,+ "direction": { "x": 0, "y": 0 }+ }+ }+ ],+ "visible": true+ }+ ]+}diff --git a/desktop/public/scenes/mat-lit-flatnormal.textures.json b/desktop/public/scenes/mat-lit-flatnormal.textures.jsonnew file mode 100644index 000000000..0967ef424--- /dev/null+++ b/desktop/public/scenes/mat-lit-flatnormal.textures.json@@ -0,0 +1 @@+{}diff --git a/desktop/public/scenes/mat-lit-flatnormal/lit-fn.esmaterial b/desktop/public/scenes/mat-lit-flatnormal/lit-fn.esmaterialnew file mode 100644index 000000000..3f9d77829--- /dev/null+++ b/desktop/public/scenes/mat-lit-flatnormal/lit-fn.esmaterial@@ -0,0 +1,10 @@+{+ "version": "1.0",+ "type": "material",+ "shader": "lit-fn.esshader",+ "blendMode": 0,+ "depthTest": false,+ "depthWrite": true,+ "cull": 0,+ "properties": {}+}diff --git a/desktop/public/scenes/mat-lit-flatnormal/lit-fn.esshader b/desktop/public/scenes/mat-lit-flatnormal/lit-fn.esshadernew file mode 100644index 000000000..f6dca5a77--- /dev/null+++ b/desktop/public/scenes/mat-lit-flatnormal/lit-fn.esshader@@ -0,0 +1,48 @@+#pragma shader "Lit2DFlatNormal"+#pragma version 300 es+#pragma domain Lit2D+#pragma param u_normal texture default(flatnormal)++#pragma vertex+layout(location = 0) in vec2 a_position;+layout(location = 1) in vec4 a_color;+layout(location = 2) in vec2 a_texCoord;+layout(location = 3) in float a_texIndex;++layout(std140) uniform FrameConstants {+ mat4 u_projection;+};++out vec4 v_color;+out vec2 v_texCoord;+out highp vec2 v_worldPos;++void main() {+ gl_Position = u_projection * vec4(a_position, 0.0, 1.0);+ v_color = a_color;+ v_texCoord = a_texCoord;+ v_worldPos = a_position;+}+#pragma end++#pragma fragment+precision mediump float;++in vec4 v_color;+in vec2 v_texCoord;+in highp vec2 v_worldPos;++uniform sampler2D u_textures[8];++out vec4 fragColor;++// The material leaves u_normal unset, so it binds the shader's declared `default(flatnormal)`+// (a flat tangent normal (0,0,1)) — proving texture-param defaults actually bind. With a+// straight-on light, a flat normal gives N·L = 1 (full bright); a wrong default would not.+void main() {+ vec4 base = texture(u_textures[0], v_texCoord) * v_color;+ vec3 N = es_sampleNormal(u_normal, v_texCoord);+ vec3 lit = es_applyLighting2D(base.rgb, N, v_worldPos);+ fragColor = vec4(lit, base.a);+}+#pragma enddiff --git a/desktop/public/scenes/mat-lit-normal.esscene b/desktop/public/scenes/mat-lit-normal.esscenenew file mode 100644index 000000000..fa2e6cc43--- /dev/null+++ b/desktop/public/scenes/mat-lit-normal.esscene@@ -0,0 +1,54 @@+{+ "version": "1.0",+ "name": "Main",+ "entities": [+ {+ "id": 0,+ "name": "Camera",+ "parent": null,+ "children": [],+ "components": [+ { "type": "Transform", "data": { "position": { "x": 0, "y": 0, "z": 10 } } },+ { "type": "Camera", "data": { "projectionType": 1, "orthoSize": 300, "isActive": true, "priority": 0 } }+ ],+ "visible": true+ },+ {+ "id": 1,+ "name": "Lit",+ "parent": null,+ "children": [],+ "components": [+ { "type": "Transform", "data": { "position": { "x": 0, "y": 0, "z": 0 } } },+ {+ "type": "Sprite",+ "data": {+ "size": { "x": 400, "y": 400 },+ "color": { "r": 1, "g": 1, "b": 1, "a": 1 },+ "material": "/scenes/mat-lit-normal/lit-normal.esmaterial"+ }+ }+ ],+ "visible": true+ },+ {+ "id": 2,+ "name": "GreenLight",+ "parent": null,+ "children": [],+ "components": [+ { "type": "Transform", "data": { "position": { "x": 0, "y": 0, "z": 0 } } },+ {+ "type": "Light2D",+ "data": {+ "type": 1,+ "color": { "r": 0, "g": 1, "b": 0, "a": 1 },+ "intensity": 1,+ "direction": { "x": -1, "y": 0 }+ }+ }+ ],+ "visible": true+ }+ ]+}diff --git a/desktop/public/scenes/mat-lit-normal.textures.json b/desktop/public/scenes/mat-lit-normal.textures.jsonnew file mode 100644index 000000000..0967ef424--- /dev/null+++ b/desktop/public/scenes/mat-lit-normal.textures.json@@ -0,0 +1 @@+{}diff --git a/desktop/public/scenes/mat-lit-normal/lit-normal.esmaterial b/desktop/public/scenes/mat-lit-normal/lit-normal.esmaterialnew file mode 100644index 000000000..dccfb8697--- /dev/null+++ b/desktop/public/scenes/mat-lit-normal/lit-normal.esmaterial@@ -0,0 +1,12 @@+{+ "version": "1.0",+ "type": "material",+ "shader": "lit-normal.esshader",+ "blendMode": 0,+ "depthTest": false,+ "depthWrite": true,+ "cull": 0,+ "properties": {+ "u_normal": "normal.png"+ }+}diff --git a/desktop/public/scenes/mat-lit-normal/lit-normal.esshader b/desktop/public/scenes/mat-lit-normal/lit-normal.esshadernew file mode 100644index 000000000..c39d1cc4c--- /dev/null+++ b/desktop/public/scenes/mat-lit-normal/lit-normal.esshader@@ -0,0 +1,48 @@+#pragma shader "Lit2DNormal"+#pragma version 300 es+#pragma domain Lit2D+#pragma param u_normal texture default(white)++#pragma vertex+layout(location = 0) in vec2 a_position;+layout(location = 1) in vec4 a_color;+layout(location = 2) in vec2 a_texCoord;+layout(location = 3) in float a_texIndex;++layout(std140) uniform FrameConstants {+ mat4 u_projection;+};++out vec4 v_color;+out vec2 v_texCoord;+out highp vec2 v_worldPos;++void main() {+ gl_Position = u_projection * vec4(a_position, 0.0, 1.0);+ v_color = a_color;+ v_texCoord = a_texCoord;+ v_worldPos = a_position;+}+#pragma end++#pragma fragment+precision mediump float;++in vec4 v_color;+in vec2 v_texCoord;+in highp vec2 v_worldPos;++uniform sampler2D u_textures[8];++out vec4 fragColor;++// es_sampleNormal + es_applyLighting2D + the LightConstants block are injected by ShaderParser+// for `#pragma domain Lit2D`. The surface normal comes from the material's u_normal map, so+// lighting varies per texel.+void main() {+ vec4 base = texture(u_textures[0], v_texCoord) * v_color;+ vec3 N = es_sampleNormal(u_normal, v_texCoord);+ vec3 lit = es_applyLighting2D(base.rgb, N, v_worldPos);+ fragColor = vec4(lit, base.a);+}+#pragma enddiff --git a/desktop/public/scenes/mat-lit-normal/normal.png b/desktop/public/scenes/mat-lit-normal/normal.pngnew file mode 100644index 000000000..32638325bBinary files /dev/null and b/desktop/public/scenes/mat-lit-normal/normal.png differdiff --git a/desktop/public/scenes/mat-lit-point.esscene b/desktop/public/scenes/mat-lit-point.esscenenew file mode 100644index 000000000..0a7f9fbf2--- /dev/null+++ b/desktop/public/scenes/mat-lit-point.esscene@@ -0,0 +1,54 @@+{+ "version": "1.0",+ "name": "Main",+ "entities": [+ {+ "id": 0,+ "name": "Camera",+ "parent": null,+ "children": [],+ "components": [+ { "type": "Transform", "data": { "position": { "x": 0, "y": 0, "z": 10 } } },+ { "type": "Camera", "data": { "projectionType": 1, "orthoSize": 300, "isActive": true, "priority": 0 } }+ ],+ "visible": true+ },+ {+ "id": 1,+ "name": "Lit",+ "parent": null,+ "children": [],+ "components": [+ { "type": "Transform", "data": { "position": { "x": 0, "y": 0, "z": 0 } } },+ {+ "type": "Sprite",+ "data": {+ "size": { "x": 400, "y": 400 },+ "color": { "r": 1, "g": 1, "b": 1, "a": 1 },+ "material": "/scenes/mat-lit/lit.esmaterial"+ }+ }+ ],+ "visible": true+ },+ {+ "id": 2,+ "name": "GreenPointLight",+ "parent": null,+ "children": [],+ "components": [+ { "type": "Transform", "data": { "position": { "x": 0, "y": 0, "z": 0 } } },+ {+ "type": "Light2D",+ "data": {+ "type": 0,+ "color": { "r": 0, "g": 1, "b": 0, "a": 1 },+ "intensity": 1,+ "radius": 200+ }+ }+ ],+ "visible": true+ }+ ]+}diff --git a/desktop/public/scenes/mat-lit-point.textures.json b/desktop/public/scenes/mat-lit-point.textures.jsonnew file mode 100644index 000000000..0967ef424--- /dev/null+++ b/desktop/public/scenes/mat-lit-point.textures.json@@ -0,0 +1 @@+{}diff --git a/desktop/public/scenes/mat-lit-spot.esscene b/desktop/public/scenes/mat-lit-spot.esscenenew file mode 100644index 000000000..ff8af2415--- /dev/null+++ b/desktop/public/scenes/mat-lit-spot.esscene@@ -0,0 +1,57 @@+{+ "version": "1.0",+ "name": "Main",+ "entities": [+ {+ "id": 0,+ "name": "Camera",+ "parent": null,+ "children": [],+ "components": [+ { "type": "Transform", "data": { "position": { "x": 0, "y": 0, "z": 10 } } },+ { "type": "Camera", "data": { "projectionType": 1, "orthoSize": 300, "isActive": true, "priority": 0 } }+ ],+ "visible": true+ },+ {+ "id": 1,+ "name": "Lit",+ "parent": null,+ "children": [],+ "components": [+ { "type": "Transform", "data": { "position": { "x": 0, "y": 0, "z": 0 } } },+ {+ "type": "Sprite",+ "data": {+ "size": { "x": 400, "y": 400 },+ "color": { "r": 1, "g": 1, "b": 1, "a": 1 },+ "material": "/scenes/mat-lit/lit.esmaterial"+ }+ }+ ],+ "visible": true+ },+ {+ "id": 2,+ "name": "GreenSpot",+ "parent": null,+ "children": [],+ "components": [+ { "type": "Transform", "data": { "position": { "x": 0, "y": 200, "z": 0 } } },+ {+ "type": "Light2D",+ "data": {+ "type": 3,+ "color": { "r": 0, "g": 1, "b": 0, "a": 1 },+ "intensity": 1,+ "radius": 2000,+ "direction": { "x": 0, "y": -1 },+ "innerAngle": 30,+ "outerAngle": 45+ }+ }+ ],+ "visible": true+ }+ ]+}diff --git a/desktop/public/scenes/mat-lit-spot.textures.json b/desktop/public/scenes/mat-lit-spot.textures.jsonnew file mode 100644index 000000000..0967ef424--- /dev/null+++ b/desktop/public/scenes/mat-lit-spot.textures.json@@ -0,0 +1 @@+{}diff --git a/desktop/public/scenes/mat-lit.esscene b/desktop/public/scenes/mat-lit.esscenenew file mode 100644index 000000000..5425cb9b5--- /dev/null+++ b/desktop/public/scenes/mat-lit.esscene@@ -0,0 +1,53 @@+{+ "version": "1.0",+ "name": "Main",+ "entities": [+ {+ "id": 0,+ "name": "Camera",+ "parent": null,+ "children": [],+ "components": [+ { "type": "Transform", "data": { "position": { "x": 0, "y": 0, "z": 10 } } },+ { "type": "Camera", "data": { "projectionType": 1, "orthoSize": 300, "isActive": true, "priority": 0 } }+ ],+ "visible": true+ },+ {+ "id": 1,+ "name": "Lit",+ "parent": null,+ "children": [],+ "components": [+ { "type": "Transform", "data": { "position": { "x": 0, "y": 0, "z": 0 } } },+ {+ "type": "Sprite",+ "data": {+ "size": { "x": 400, "y": 400 },+ "color": { "r": 1, "g": 1, "b": 1, "a": 1 },+ "material": "/scenes/mat-lit/lit.esmaterial"+ }+ }+ ],+ "visible": true+ },+ {+ "id": 2,+ "name": "GreenLight",+ "parent": null,+ "children": [],+ "components": [+ { "type": "Transform", "data": { "position": { "x": 0, "y": 0, "z": 0 } } },+ {+ "type": "Light2D",+ "data": {+ "type": 1,+ "color": { "r": 0, "g": 1, "b": 0, "a": 1 },+ "intensity": 1+ }+ }+ ],+ "visible": true+ }+ ]+}diff --git a/desktop/public/scenes/mat-lit.textures.json b/desktop/public/scenes/mat-lit.textures.jsonnew file mode 100644index 000000000..0967ef424--- /dev/null+++ b/desktop/public/scenes/mat-lit.textures.json@@ -0,0 +1 @@+{}diff --git a/desktop/public/scenes/mat-lit/lit.esmaterial b/desktop/public/scenes/mat-lit/lit.esmaterialnew file mode 100644index 000000000..ac92f1385--- /dev/null+++ b/desktop/public/scenes/mat-lit/lit.esmaterial@@ -0,0 +1,8 @@+{+ "version": "1.0",+ "type": "material",+ "shader": "lit.esshader",+ "blendMode": 0,+ "depthTest": false,+ "properties": {}+}diff --git a/desktop/public/scenes/mat-lit/lit.esshader b/desktop/public/scenes/mat-lit/lit.esshadernew file mode 100644index 000000000..0376a220e--- /dev/null+++ b/desktop/public/scenes/mat-lit/lit.esshader@@ -0,0 +1,47 @@+#pragma shader "Lit2DTest"+#pragma version 300 es+#pragma domain Lit2D++#pragma vertex+layout(location = 0) in vec2 a_position;+layout(location = 1) in vec4 a_color;+layout(location = 2) in vec2 a_texCoord;+layout(location = 3) in float a_texIndex;++layout(std140) uniform FrameConstants {+ mat4 u_projection;+};++out vec4 v_color;+out vec2 v_texCoord;+out highp vec2 v_worldPos;++void main() {+ gl_Position = u_projection * vec4(a_position, 0.0, 1.0);+ v_color = a_color;+ v_texCoord = a_texCoord;+ // The batch path bakes the transform into the vertices, so a_position is already world-space.+ v_worldPos = a_position;+}+#pragma end++#pragma fragment+precision mediump float;++in vec4 v_color;+in vec2 v_texCoord;+in highp vec2 v_worldPos;++uniform sampler2D u_textures[8];++out vec4 fragColor;++// The LightConstants block + es_applyLighting2D() are injected by ShaderParser for+// `#pragma domain Lit2D`. A flat normal (no normal map in this fixture) faces the camera.+void main() {+ vec4 base = texture(u_textures[0], v_texCoord) * v_color;+ vec3 N = vec3(0.0, 0.0, 1.0);+ vec3 lit = es_applyLighting2D(base.rgb, N, v_worldPos);+ fragColor = vec4(lit, base.a);+}+#pragma enddiff --git a/desktop/public/scenes/mat-sw.esscene b/desktop/public/scenes/mat-sw.esscenenew file mode 100644index 000000000..5afc700f2--- /dev/null+++ b/desktop/public/scenes/mat-sw.esscene@@ -0,0 +1,45 @@+{+ "version": "1.0",+ "name": "Main",+ "entities": [+ {+ "id": 0,+ "name": "Camera",+ "parent": null,+ "children": [],+ "components": [+ { "type": "Transform", "data": { "position": { "x": 0, "y": 0, "z": 10 } } },+ { "type": "Camera", "data": { "projectionType": 1, "orthoSize": 300, "isActive": true, "priority": 0 } }+ ],+ "visible": true+ },+ {+ "id": 1,+ "name": "RedSwitch",+ "parent": null,+ "children": [],+ "components": [+ { "type": "Transform", "data": { "position": { "x": -160, "y": 0, "z": 0 } } },+ {+ "type": "Sprite",+ "data": { "size": { "x": 220, "y": 400 }, "color": { "r": 1, "g": 1, "b": 1, "a": 1 }, "material": "/scenes/mat-sw/red.esmaterial" }+ }+ ],+ "visible": true+ },+ {+ "id": 2,+ "name": "GreenSwitch",+ "parent": null,+ "children": [],+ "components": [+ { "type": "Transform", "data": { "position": { "x": 160, "y": 0, "z": 0 } } },+ {+ "type": "Sprite",+ "data": { "size": { "x": 220, "y": 400 }, "color": { "r": 1, "g": 1, "b": 1, "a": 1 }, "material": "/scenes/mat-sw/green.esmaterial" }+ }+ ],+ "visible": true+ }+ ]+}diff --git a/desktop/public/scenes/mat-sw.textures.json b/desktop/public/scenes/mat-sw.textures.jsonnew file mode 100644index 000000000..0967ef424--- /dev/null+++ b/desktop/public/scenes/mat-sw.textures.json@@ -0,0 +1 @@+{}diff --git a/desktop/public/scenes/mat-sw/green.esmaterial b/desktop/public/scenes/mat-sw/green.esmaterialnew file mode 100644index 000000000..3b8ce4817--- /dev/null+++ b/desktop/public/scenes/mat-sw/green.esmaterial@@ -0,0 +1,11 @@+{+ "version": "1.0",+ "type": "material",+ "shader": "switched.esshader",+ "blendMode": 0,+ "depthTest": false,+ "depthWrite": true,+ "cull": 0,+ "switches": { "USE_GREEN": true },+ "properties": {}+}diff --git a/desktop/public/scenes/mat-sw/red.esmaterial b/desktop/public/scenes/mat-sw/red.esmaterialnew file mode 100644index 000000000..ac68c782f--- /dev/null+++ b/desktop/public/scenes/mat-sw/red.esmaterial@@ -0,0 +1,10 @@+{+ "version": "1.0",+ "type": "material",+ "shader": "switched.esshader",+ "blendMode": 0,+ "depthTest": false,+ "depthWrite": true,+ "cull": 0,+ "properties": {}+}diff --git a/desktop/public/scenes/mat-sw/switched.esshader b/desktop/public/scenes/mat-sw/switched.esshadernew file mode 100644index 000000000..ac02454e8--- /dev/null+++ b/desktop/public/scenes/mat-sw/switched.esshader@@ -0,0 +1,39 @@+#pragma shader "Switched"+#pragma version 300 es+#pragma domain Unlit2D+#pragma switch USE_GREEN default(off)++#pragma vertex+layout(location = 0) in vec2 a_position;+layout(location = 1) in vec4 a_color;+layout(location = 2) in vec2 a_texCoord;+layout(location = 3) in float a_texIndex;++layout(std140) uniform FrameConstants {+ mat4 u_projection;+};++out vec4 v_color;++void main() {+ gl_Position = u_projection * vec4(a_position, 0.0, 1.0);+ v_color = a_color;+}+#pragma end++#pragma fragment+precision mediump float;++in vec4 v_color;++out vec4 fragColor;++// USE_GREEN is a #pragma switch — a material's static switch selects this permutation.+void main() {+#ifdef USE_GREEN+ fragColor = vec4(0.0, 1.0, 0.0, 1.0) * v_color;+#else+ fragColor = vec4(1.0, 0.0, 0.0, 1.0) * v_color;+#endif+}+#pragma enddiff --git a/desktop/public/scenes/mat-tex.esscene b/desktop/public/scenes/mat-tex.esscenenew file mode 100644index 000000000..cc901cd10--- /dev/null+++ b/desktop/public/scenes/mat-tex.esscene@@ -0,0 +1,35 @@+{+ "version": "1.0",+ "name": "Main",+ "entities": [+ {+ "id": 0,+ "name": "Camera",+ "parent": null,+ "children": [],+ "components": [+ { "type": "Transform", "data": { "position": { "x": 0, "y": 0, "z": 10 } } },+ { "type": "Camera", "data": { "projectionType": 1, "orthoSize": 300, "isActive": true, "priority": 0 } }+ ],+ "visible": true+ },+ {+ "id": 1,+ "name": "Masked",+ "parent": null,+ "children": [],+ "components": [+ { "type": "Transform", "data": { "position": { "x": 0, "y": 0, "z": 0 } } },+ {+ "type": "Sprite",+ "data": {+ "size": { "x": 400, "y": 400 },+ "color": { "r": 1, "g": 1, "b": 1, "a": 1 },+ "material": "/scenes/mat-tex/masked.esmaterial"+ }+ }+ ],+ "visible": true+ }+ ]+}diff --git a/desktop/public/scenes/mat-tex.textures.json b/desktop/public/scenes/mat-tex.textures.jsonnew file mode 100644index 000000000..0967ef424--- /dev/null+++ b/desktop/public/scenes/mat-tex.textures.json@@ -0,0 +1 @@+{}diff --git a/desktop/public/scenes/mat-tex/green.png b/desktop/public/scenes/mat-tex/green.pngnew file mode 100644index 000000000..0e9295be7Binary files /dev/null and b/desktop/public/scenes/mat-tex/green.png differdiff --git a/desktop/public/scenes/mat-tex/masked.esmaterial b/desktop/public/scenes/mat-tex/masked.esmaterialnew file mode 100644index 000000000..540675deb--- /dev/null+++ b/desktop/public/scenes/mat-tex/masked.esmaterial@@ -0,0 +1,12 @@+{+ "version": "1.0",+ "type": "material",+ "shader": "masked.esshader",+ "blendMode": 0,+ "depthTest": false,+ "depthWrite": true,+ "cull": 0,+ "properties": {+ "u_mask": "green.png"+ }+}diff --git a/desktop/public/scenes/mat-tex/masked.esshader b/desktop/public/scenes/mat-tex/masked.esshadernew file mode 100644index 000000000..330024d04--- /dev/null+++ b/desktop/public/scenes/mat-tex/masked.esshader@@ -0,0 +1,39 @@+#pragma shader "Masked"+#pragma version 300 es+#pragma domain Unlit2D+#pragma param u_mask texture default(white)++#pragma vertex+layout(location = 0) in vec2 a_position;+layout(location = 1) in vec4 a_color;+layout(location = 2) in vec2 a_texCoord;+layout(location = 3) in float a_texIndex;++layout(std140) uniform FrameConstants {+ mat4 u_projection;+};++out vec4 v_color;+out vec2 v_texCoord;++void main() {+ gl_Position = u_projection * vec4(a_position, 0.0, 1.0);+ v_color = a_color;+ v_texCoord = a_texCoord;+}+#pragma end++#pragma fragment+precision mediump float;++in vec4 v_color;+in vec2 v_texCoord;++out vec4 fragColor;++// u_mask is the material texture param — ShaderParser auto-declares `uniform sampler2D u_mask;`+// and the engine binds it to sampler unit 8 (above the batch path's 0..7).+void main() {+ fragColor = texture(u_mask, v_texCoord) * v_color;+}+#pragma enddiff --git a/desktop/public/scenes/mat-tint.esscene b/desktop/public/scenes/mat-tint.esscenenew file mode 100644index 000000000..6644f693d--- /dev/null+++ b/desktop/public/scenes/mat-tint.esscene@@ -0,0 +1,35 @@+{+ "version": "1.0",+ "name": "Main",+ "entities": [+ {+ "id": 0,+ "name": "Camera",+ "parent": null,+ "children": [],+ "components": [+ { "type": "Transform", "data": { "position": { "x": 0, "y": 0, "z": 10 } } },+ { "type": "Camera", "data": { "projectionType": 1, "orthoSize": 300, "isActive": true, "priority": 0 } }+ ],+ "visible": true+ },+ {+ "id": 1,+ "name": "Tinted",+ "parent": null,+ "children": [],+ "components": [+ { "type": "Transform", "data": { "position": { "x": 0, "y": 0, "z": 0 } } },+ {+ "type": "Sprite",+ "data": {+ "size": { "x": 400, "y": 400 },+ "color": { "r": 1, "g": 1, "b": 1, "a": 1 },+ "material": "/scenes/mat-tint/tint.esmaterial"+ }+ }+ ],+ "visible": true+ }+ ]+}diff --git a/desktop/public/scenes/mat-tint.textures.json b/desktop/public/scenes/mat-tint.textures.jsonnew file mode 100644index 000000000..0967ef424--- /dev/null+++ b/desktop/public/scenes/mat-tint.textures.json@@ -0,0 +1 @@+{}diff --git a/desktop/public/scenes/mat-tint/tint-green.esmaterial b/desktop/public/scenes/mat-tint/tint-green.esmaterialnew file mode 100644index 000000000..c990608f3--- /dev/null+++ b/desktop/public/scenes/mat-tint/tint-green.esmaterial@@ -0,0 +1,9 @@+{+ "version": "1.0",+ "type": "material",+ "shader": "",+ "instanceOf": "tint.esmaterial",+ "properties": {+ "u_tint": { "r": 0, "g": 1, "b": 0, "a": 1 }+ }+}diff --git a/desktop/public/scenes/mat-tint/tint.esmaterial b/desktop/public/scenes/mat-tint/tint.esmaterialnew file mode 100644index 000000000..bd01059ad--- /dev/null+++ b/desktop/public/scenes/mat-tint/tint.esmaterial@@ -0,0 +1,10 @@+{+ "version": "1.0",+ "type": "material",+ "shader": "tint.esshader",+ "blendMode": 0,+ "depthTest": false,+ "properties": {+ "u_tint": { "r": 1, "g": 0, "b": 0, "a": 1 }+ }+}diff --git a/desktop/public/scenes/mat-tint/tint.esshader b/desktop/public/scenes/mat-tint/tint.esshadernew file mode 100644index 000000000..570c78f57--- /dev/null+++ b/desktop/public/scenes/mat-tint/tint.esshader@@ -0,0 +1,41 @@+#pragma shader "TintTest"+#pragma version 300 es+#pragma domain Unlit2D+#pragma param u_tint color default(1,1,1,1)++#pragma vertex+layout(location = 0) in vec2 a_position;+layout(location = 1) in vec4 a_color;+layout(location = 2) in vec2 a_texCoord;+layout(location = 3) in float a_texIndex;++layout(std140) uniform FrameConstants {+ mat4 u_projection;+};++out vec4 v_color;+out vec2 v_texCoord;++void main() {+ gl_Position = u_projection * vec4(a_position, 0.0, 1.0);+ v_color = a_color;+ v_texCoord = a_texCoord;+}+#pragma end++#pragma fragment+precision mediump float;++in vec4 v_color;+in vec2 v_texCoord;++uniform sampler2D u_textures[8];++out vec4 fragColor;++// u_tint comes from the auto-generated MaterialConstants block (#pragma param).+void main() {+ vec4 texColor = texture(u_textures[0], v_texCoord);+ fragColor = texColor * v_color * u_tint;+}+#pragma enddiff --git a/desktop/scripts/headless-verify.mjs b/desktop/scripts/headless-verify.mjsindex ce5b338fe..b97fc493b 100644--- a/desktop/scripts/headless-verify.mjs+++ b/desktop/scripts/headless-verify.mjs@@ -63,7 +63,7 @@ function serveDist() {}function finish(result, server) {- const ok = result.ok && result.capture?.rendered && (result.expect?.ok ?? true);+ const ok = result.ok && result.capture?.rendered && (result.expect?.ok ?? true) && (result.preview?.ok ?? true);console.log(`\n[verify:render] ${ok ? 'PASS' : 'FAIL'} — ${SCENE}`);console.log('DRIVE_RESULT ' + JSON.stringify(result));process.exitCode = ok ? 0 : 1;@@ -147,7 +147,24 @@ app.whenReady().then(async () => {})()`);await writeFile(process.env.ESTELLA_VERIFY_OUT, Buffer.from(dataUrl.split(',')[1], 'base64'));}- finish({ ok: true, entityCount, drawCalls, capture, expect }, server);+ // Optional offscreen material-preview assertion (ESTELLA_VERIFY_PREVIEW =+ // {w,h,rgb:[r,g,b],tol?}): renders a scene material to an offscreen target and checks the+ // center pixel — proves the render-to-texture preview primitive, not just the viewport.+ let preview = null;+ if (process.env.ESTELLA_VERIFY_PREVIEW) {+ const cfg = JSON.parse(process.env.ESTELLA_VERIFY_PREVIEW);+ preview = await exec(`(() => {+ const cfg = ${JSON.stringify(cfg)};+ const cap = window.__estellaHeadless.api.renderSceneMaterialPreview(cfg.w, cfg.h);+ if (!cap) return { ok: false, reason: 'no scene material' };+ const { width: w, height: h, rgba } = cap;+ const i = (Math.floor(h / 2) * w + Math.floor(w / 2)) * 4;+ const got = [rgba[i], rgba[i + 1], rgba[i + 2]];+ const tol = cfg.tol ?? 40;+ 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, preview }, server);} catch (e) {finish({ ok: false, error: String((e && e.stack) || e) }, server);}diff --git a/desktop/src/components/Tooltip.tsx b/desktop/src/components/Tooltip.tsxnew file mode 100644index 000000000..d18599e2e--- /dev/null+++ b/desktop/src/components/Tooltip.tsx@@ -0,0 +1,125 @@+// SPDX-License-Identifier: LicenseRef-PolyForm-Noncommercial-1.0.0+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team+/**+ * @file Tooltip.tsx+ * @brief A hover-anchored, non-interactive info card — the one primitive behind+ * the editor's hover tooltips (e.g. the Content Browser's asset card).+ * Portaled to the body, anchored beside the trigger, clamped on-screen,+ * and — unlike a bare portal — it self-dismisses the instant its anchor+ * stops being visible: a scroll, a resize, a window blur, or the anchor's+ * host being detached/hidden. A dock tab switch detaches the host panel+ * without unmounting its component, so a body-level portal whose only+ * exits are mouseleave/unmount would otherwise be stranded on screen.+ */+import { useCallback, useEffect, useLayoutEffect, useRef, useState, type ReactNode } from 'react';+import { createPortal } from 'react-dom';++// UE-style hover delay: long enough not to flicker while sweeping over a grid.+const OPEN_DELAY = 450;++function Tooltip({+ anchor,+ onDismiss,+ children,+}: {+ anchor: HTMLElement;+ onDismiss: () => void;+ children: ReactNode;+}) {+ const ref = useRef<HTMLDivElement>(null);+ const [pos, setPos] = useState(() => {+ const r = anchor.getBoundingClientRect();+ return { left: r.right + 10, top: r.top };+ });++ // Place beside the anchor (flip left / lift up near an edge) before paint, and+ // re-place when the card resizes — its content (stat, image dims) loads async.+ useLayoutEffect(() => {+ const el = ref.current;+ if (!el) return;+ const place = () => {+ const a = anchor.getBoundingClientRect();+ const r = el.getBoundingClientRect();+ const pad = 8;+ let left = a.right + 10;+ if (left + r.width > window.innerWidth - pad) left = Math.max(pad, a.left - r.width - 10);+ let top = a.top;+ if (top + r.height > window.innerHeight - pad) top = Math.max(pad, window.innerHeight - r.height - pad);+ setPos((p) => (p.left === left && p.top === top ? p : { left, top }));+ };+ place();+ const ro = new ResizeObserver(place);+ ro.observe(el);+ return () => ro.disconnect();+ }, [anchor]);++ // Dismiss the moment the anchor leaves the screen. The IntersectionObserver is+ // the load-bearing part: it reports the anchor non-intersecting when its panel+ // is detached on a dock tab switch or collapsed — cases a mouseleave never sees.+ useEffect(() => {+ const io = new IntersectionObserver((entries) => {+ if (entries.some((e) => !e.isIntersecting)) onDismiss();+ });+ io.observe(anchor);+ window.addEventListener('scroll', onDismiss, true);+ window.addEventListener('wheel', onDismiss, { passive: true });+ window.addEventListener('resize', onDismiss);+ window.addEventListener('blur', onDismiss);+ return () => {+ io.disconnect();+ window.removeEventListener('scroll', onDismiss, true);+ window.removeEventListener('wheel', onDismiss);+ window.removeEventListener('resize', onDismiss);+ window.removeEventListener('blur', onDismiss);+ };+ }, [anchor, onDismiss]);++ return createPortal(+ <div ref={ref} className="tooltip" style={{ left: pos.left, top: pos.top }}>+ {children}+ </div>,+ document.body,+ );+}++/**+ * Hover-tooltip controller for a set of triggers that share one card. `bind(payload)`+ * returns the enter/leave handlers for a trigger (the card opens after a short+ * delay); render `card` once to host the floating card; `render` maps the hovered+ * payload to the card body. `close()` dismisses it imperatively (e.g. on drag start).+ */+export function useTooltip<T>(render: (payload: T) => ReactNode, delay = OPEN_DELAY) {+ const [target, setTarget] = useState<{ anchor: HTMLElement; payload: T } | null>(null);+ const timer = useRef<number | null>(null);++ const close = useCallback(() => {+ if (timer.current != null) {+ clearTimeout(timer.current);+ timer.current = null;+ }+ setTarget(null);+ }, []);++ // A body-level portal must never outlive the component that owns it.+ useEffect(() => () => close(), [close]);++ const bind = useCallback(+ (payload: T) => ({+ onMouseEnter: (ev: React.MouseEvent) => {+ const anchor = ev.currentTarget as HTMLElement;+ if (timer.current != null) clearTimeout(timer.current);+ timer.current = window.setTimeout(() => setTarget({ anchor, payload }), delay);+ },+ onMouseLeave: close,+ }),+ [close, delay],+ );++ const card = target ? (+ <Tooltip anchor={target.anchor} onDismiss={close}>+ {render(target.payload)}+ </Tooltip>+ ) : null;++ return { bind, card, close };+}diff --git a/desktop/src/engine/EditorControlSurface.ts b/desktop/src/engine/EditorControlSurface.tsindex 3b6d1467d..6e56f0b93 100644--- a/desktop/src/engine/EditorControlSurface.ts+++ b/desktop/src/engine/EditorControlSurface.ts@@ -24,6 +24,7 @@ import type {SceneNode,} from '@/types';import type { SceneData, SubsystemStatus } from 'esengine';+import { Material, Sprite } from 'esengine';import { EngineHost } from './EngineHost';import type { SceneCommandsImpl, EditorTransaction } from './SceneCommands';import type { SceneQueryImpl } from './SceneQuery';@@ -255,6 +256,24 @@ export class EditorControlSurfaceImpl {return { rgba, width, height };}+ /**+ * Render a material to an offscreen @p w×@p h target (a "material ball" preview), found by the+ * handle a scene sprite carries — so a loaded scene's material can be previewed without+ * re-loading it. Reuses the real render path. Null if no sprite material is in the scene.+ */+ renderSceneMaterialPreview(w: number, h: number): ViewportCapture | null {+ const world = EngineHost.world;+ if (!world) return null;+ for (const e of world.getAllEntities()) {+ if (!world.has(e, Sprite)) continue;+ const mat = (world.get(e, Sprite) as { material: number }).material;+ if (!mat) continue;+ const img = Material.renderPreview(mat, w, h);+ if (img) return { rgba: new Uint8Array(img.data), width: img.width, height: img.height };+ }+ return null;+ }+/** Live counts for quick assertions (entity count + last frame's merged draw calls). */getStats(): { entities: number; drawCalls: number } {return {diff --git a/desktop/src/engine/ViewportController.ts b/desktop/src/engine/ViewportController.tsindex 846b51abd..cea227c3a 100644--- a/desktop/src/engine/ViewportController.ts+++ b/desktop/src/engine/ViewportController.ts@@ -1,6 +1,6 @@// SPDX-License-Identifier: LicenseRef-PolyForm-Noncommercial-1.0.0// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team-import { Camera, CameraView, EditorView, Sprite, Transform } from 'esengine';+import { Camera, CameraView, EditorView, Light2D, Sprite, Transform } from 'esengine';import type { EntityId } from '@/types';import { EngineHost } from './EngineHost';import { SceneModel } from './SceneModel';@@ -209,4 +209,58 @@ export const ViewportController = {const minY = Math.min(...ys);return { cx: center.x, cy: center.y, rect: { x: minX, y: minY, w: Math.max(...xs) - minX, h: Math.max(...ys) - minY } };},++ /** Ids of the scene's Light2D entities — the light-gizmo set (structural). */+ light2DIds(): EntityId[] {+ const world = EngineHost.world;+ if (!world) return [];+ const out: EntityId[] = [];+ for (const e of world.getAllEntities()) {+ if (world.has(e, Light2D) && world.has(e, Transform)) out.push(e);+ }+ return out;+ },++ /**+ * Screen-space gizmo geometry for a Light2D: its icon position, reach radius (Point/Spot,+ * CSS px), and screen-space direction unit vector (Directional/Spot). `kind` mirrors+ * Light2DType (0 Point / 1 Directional / 2 Ambient / 3 Spot); `color` is the light tint.+ */+ getLightGizmo(+ id: EntityId,+ ): { cx: number; cy: number; kind: number; color: string; radiusPx: number; sdx: number; sdy: number; coneHalf: number } | null {+ const world = EngineHost.world;+ if (!world || !world.valid(id) || !world.has(id, Light2D) || !world.has(id, Transform)) return null;+ const t = world.get(id, Transform);+ const l = world.get(id, Light2D) as {+ type: number; color: { r: number; g: number; b: number }; radius: number;+ direction: { x: number; y: number }; outerAngle: number;+ };+ const center = this.worldToClient(t.position.x, t.position.y);+ if (!center) return null;++ // Point (0) / Spot (3) have a falloff radius; project a world-radius offset to CSS px.+ let radiusPx = 0;+ if (l.type === 0 || l.type === 3) {+ const edge = this.worldToClient(t.position.x + l.radius, t.position.y);+ if (edge) radiusPx = Math.hypot(edge.x - center.x, edge.y - center.y);+ }+ // Directional (1) / Spot (3) point along `direction`; flip world-Y to screen space. A Spot+ // with no direction defaults to aiming down (matching the engine's collectLights fallback).+ let sdx = 0;+ let sdy = 0;+ if (l.type === 1 || l.type === 3) {+ const len = Math.hypot(l.direction.x, l.direction.y);+ if (len > 1e-4) {+ sdx = l.direction.x / len;+ sdy = -l.direction.y / len;+ } else if (l.type === 3) {+ sdy = 1; // world (0,-1) → screen down+ }+ }+ const coneHalf = l.type === 3 ? ((l.outerAngle ?? 45) * 0.5 * Math.PI) / 180 : 0;+ const hex = (v: number) => Math.max(0, Math.min(255, Math.round(v * 255))).toString(16).padStart(2, '0');+ const color = `#${hex(l.color.r)}${hex(l.color.g)}${hex(l.color.b)}`;+ return { cx: center.x, cy: center.y, kind: l.type, color, radiusPx, sdx, sdy, coneHalf };+ },};diff --git a/desktop/src/layout/DockLayout.tsx b/desktop/src/layout/DockLayout.tsxindex 68098574b..fbb63addf 100644--- a/desktop/src/layout/DockLayout.tsx+++ b/desktop/src/layout/DockLayout.tsx@@ -17,6 +17,7 @@ import { GamePanel } from '@/panels/GamePanel';import { Sequencer } from '@/panels/Sequencer';import { TilesetEditor } from '@/panels/TilesetEditor';import { TilemapPainter } from '@/panels/TilemapPainter';+import { MaterialGraphEditor } from '@/panels/MaterialGraphEditor';import { dockApi } from '@/layout/dockApi';// Each dock panel is a thin wrapper so dockview owns mount/unmount.@@ -29,6 +30,7 @@ const components: Record<string, FC<IDockviewPanelProps>> = {sequencer: () => <Sequencer />,tileset: () => <TilesetEditor />,tilemap: () => <TilemapPainter />,+ materialgraph: () => <MaterialGraphEditor />,// The "Game" view (isolated play realm) — added on Play, removed on Stop.game: () => <GamePanel />,};@@ -83,6 +85,7 @@ const BOTTOM_TABS: { id: string; component: string; title: string; refs: string[{ id: 'sequencer', component: 'sequencer', title: 'Sequencer', refs: ['content', 'log'] },{ id: 'tileset', component: 'tileset', title: 'Tileset', refs: ['content', 'sequencer'] },{ id: 'tilemap', component: 'tilemap', title: 'Tilemap', refs: ['content', 'tileset'] },+ { id: 'materialgraph', component: 'materialgraph', title: 'Material Graph', refs: ['content', 'tilemap'] },];function ensureBottomTabs(api: DockviewReadyEvent['api']) {diff --git a/desktop/src/main.tsx b/desktop/src/main.tsxindex 749ca9c9c..c0c78c327 100644--- a/desktop/src/main.tsx+++ b/desktop/src/main.tsx@@ -24,6 +24,7 @@ import './theme/content.css';import './theme/sequencer.css';import './theme/tileset.css';import './theme/tilemap.css';+import './theme/material.css';import './theme/chrome.css';import './theme/menus.css';import './theme/settings.css';diff --git a/desktop/src/material/MaterialDocument.ts b/desktop/src/material/MaterialDocument.tsnew file mode 100644index 000000000..87cfb7944--- /dev/null+++ b/desktop/src/material/MaterialDocument.ts@@ -0,0 +1,56 @@+// SPDX-License-Identifier: LicenseRef-PolyForm-Noncommercial-1.0.0+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team+/**+ * @file MaterialDocument.ts+ * @brief Reactive, undoable document for a single `.esmaterial` — the Material Editor's+ * model. Subclasses AssetDocument with the same contract as TilesetDocument: panels+ * subscribe via useSyncExternalStore(subscribe, getRevision); edits go through+ * {@link AssetDocument.edit} (one undo step each).+ */+import type { MaterialAssetData } from 'esengine';+import { AssetDocument } from '@/document/AssetDocument';++export interface MaterialDocMeta {+ filePath: string | null;+ dirty: boolean;+ isInstance: boolean;+}++class MaterialDocumentImpl extends AssetDocument<MaterialAssetData> {+ /**+ * The running material handle this document edits (the one the scene's sprites use), or 0+ * when the material isn't in the current scene. The editor pushes live parameter edits onto+ * it so the viewport reflects them immediately — the document stays the source of truth.+ */+ private _liveHandle = 0;+ get liveHandle(): number {+ return this._liveHandle;+ }+ setLiveHandle(handle: number): void {+ this._liveHandle = handle;+ }++ get meta(): MaterialDocMeta {+ return {+ filePath: this.filePath,+ dirty: this.dirty,+ isInstance: this.asset?.instanceOf != null,+ };+ }++ open(asset: MaterialAssetData, filePath: string | null): void {+ this._liveHandle = 0; // resolved by the opener once the asset is bound+ this.openAsset(asset, filePath);+ }++ openJson(raw: unknown, filePath: string | null): void {+ this.open(raw as MaterialAssetData, filePath);+ }++ close(): void {+ this._liveHandle = 0;+ this.closeAsset();+ }+}++export const MaterialDocument = new MaterialDocumentImpl();diff --git a/desktop/src/material/MaterialGraphDocument.ts b/desktop/src/material/MaterialGraphDocument.tsnew file mode 100644index 000000000..6cc61bdf7--- /dev/null+++ b/desktop/src/material/MaterialGraphDocument.ts@@ -0,0 +1,25 @@+// SPDX-License-Identifier: LicenseRef-PolyForm-Noncommercial-1.0.0+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team+/**+ * @file MaterialGraphDocument.ts+ * @brief Reactive, undoable document for a `.esmatgraph` — the Material Graph editor's model.+ * Same AssetDocument contract as MaterialDocument/TilesetDocument: panels subscribe via+ * useSyncExternalStore(subscribe, getRevision); node edits go through {@link edit}+ * (one undo step each). The graph compiles to a sibling `.esshader` on save.+ */+import type { MaterialGraph } from 'esengine';+import { AssetDocument } from '@/document/AssetDocument';++class MaterialGraphDocumentImpl extends AssetDocument<MaterialGraph> {+ open(graph: MaterialGraph, filePath: string | null): void {+ this.openAsset(graph, filePath);+ }+ openJson(raw: unknown, filePath: string | null): void {+ this.open(raw as MaterialGraph, filePath);+ }+ close(): void {+ this.closeAsset();+ }+}++export const MaterialGraphDocument = new MaterialGraphDocumentImpl();diff --git a/desktop/src/material/materialInspectorModel.ts b/desktop/src/material/materialInspectorModel.tsnew file mode 100644index 000000000..b7dbf5f35--- /dev/null+++ b/desktop/src/material/materialInspectorModel.ts@@ -0,0 +1,279 @@+// SPDX-License-Identifier: LicenseRef-PolyForm-Noncommercial-1.0.0+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team+/**+ * @file materialInspectorModel.ts+ * @brief View-model that drives material editing through the *unified* inspector.+ * @details A `.esmaterial` is edited in the Details panel by the same reflection-driven+ * `ComponentSection`/`FieldRow` machinery as an entity's components — not a bespoke+ * panel. This module is the pure bridge: it turns a material asset + its shader+ * reflection into `InspectorComponent[]` (Parameters + Render State), converts a+ * field edit back into the asset's stored shape (writing the live `MaterialDocument`+ * with diff/override semantics), and projects the document onto the running material+ * handle for the live viewport preview. The engine stays the single source of the+ * std140 layout; this is the editor view of the declarations.+ */+import { BlendMode, CullMode, Material, type MaterialAssetData, type UniformValue } from 'esengine';+import type { InspectorComponent, InspectorField, InspectorFieldType, EnumOption, GradientValue, CurveValue } from '@/types';+import { MaterialDocument } from './MaterialDocument';+import { reflectEsshader, type ShaderParam, type ShaderReflection } from './shaderReflect';++const BLEND_OPTIONS: EnumOption[] = [+ { label: 'Normal', value: BlendMode.Normal },+ { label: 'Additive', value: BlendMode.Additive },+ { label: 'Multiply', value: BlendMode.Multiply },+ { label: 'Screen', value: BlendMode.Screen },+ { label: 'Premultiplied', value: BlendMode.PremultipliedAlpha },+];+const CULL_OPTIONS: EnumOption[] = [+ { label: 'None', value: CullMode.None },+ { label: 'Back', value: CullMode.Back },+ { label: 'Front', value: CullMode.Front },+];++const ARITY: Record<string, number> = { float: 1, int: 1, vec2: 2, vec3: 3, vec4: 4, color: 4 };+const VEC_KEYS = ['x', 'y', 'z', 'w'] as const;+const RENDER_STATE_KEYS = new Set(['blendMode', 'depthTest', 'depthWrite', 'cull']);++const hch = (n: number) => Math.max(0, Math.min(255, Math.round(n * 255))).toString(16).padStart(2, '0');++function colorToHex(c: Record<string, number> | undefined): string {+ const o = c ?? {};+ return `#${hch(o.r ?? 0)}${hch(o.g ?? 0)}${hch(o.b ?? 0)}${hch(o.a ?? 1)}`;+}+function hexToColor(hex: string): { r: number; g: number; b: number; a: number } {+ const s = hex.replace('#', '');+ const n = (i: number) => parseInt(s.slice(i, i + 2), 16) / 255;+ return { r: n(0), g: n(2), b: n(4), a: s.length >= 8 ? n(6) : 1 };+}+function vecToArray(v: unknown, arity: number): number[] {+ const o = (v ?? {}) as Record<string, number>;+ return VEC_KEYS.slice(0, arity).map((k) => o[k] ?? 0);+}+function arrayToVec(arr: number[], arity: number): Record<string, number> {+ const o: Record<string, number> = {};+ for (let i = 0; i < arity; i++) o[VEC_KEYS[i]] = arr[i] ?? 0;+ return o;+}++/** A param's declared shader default, in the asset's stored shape (color/vec object, or scalar). */+function shaderDefaultAsset(param: ShaderParam): unknown {+ if (param.type === 'texture') return param.defaultTexture ?? 0;+ if (param.type === 'color') {+ const d = param.default;+ return { r: d[0] ?? 0, g: d[1] ?? 0, b: d[2] ?? 0, a: d[3] ?? 1 };+ }+ if (param.type === 'float' || param.type === 'int') return param.default[0] ?? 0;+ return arrayToVec(param.default, ARITY[param.type] ?? 1);+}++/** Deep value equality for the asset's stored shapes (scalar / color obj / vec obj / ref). */+function assetEquals(a: unknown, b: unknown): boolean {+ if (typeof a === 'number' && typeof b === 'number') return Math.abs(a - b) < 1e-6;+ if (a && b && typeof a === 'object' && typeof b === 'object') {+ const ka = Object.keys(a as object);+ const kb = Object.keys(b as object);+ if (ka.length !== kb.length) return false;+ return ka.every((k) => assetEquals((a as Record<string, unknown>)[k], (b as Record<string, unknown>)[k]));+ }+ return a === b;+}++/** Whether a path names a material asset (the unified inspector edits it inline). */+export function isMaterialAsset(path: string): boolean {+ return /\.(esmaterial|esmat)$/i.test(path);+}++export interface MaterialContext {+ reflection: ShaderReflection;+ /** Resolved parameter values inherited from the parent chain (empty for a base material). */+ inherited: Record<string, unknown>;+}++function dirOf(p: string): string {+ return p.includes('/') ? p.slice(0, p.lastIndexOf('/') + 1) : '';+}+function resolveRef(ref: string, dir: string): string {+ return ref.startsWith('/') ? ref : dir + ref;+}++/**+ * Walk a material's `instanceOf` chain to its root, returning the root shader's source (for+ * reflection) and the parameters inherited from the parent chain (a base contributes none).+ * The inherited map is the reset/override baseline: an instance param reverts to it.+ */+export async function resolveMaterialContext(+ asset: MaterialAssetData,+ filePath: string,+): Promise<MaterialContext> {+ const chain: { asset: MaterialAssetData; path: string }[] = [];+ const visited = new Set<string>();+ let cur: MaterialAssetData | null = asset;+ let curPath = filePath;+ try {+ while (cur && !visited.has(curPath)) {+ visited.add(curPath);+ chain.push({ asset: cur, path: curPath });+ if (!cur.instanceOf) break;+ const parentPath = resolveRef(cur.instanceOf, dirOf(curPath));+ cur = JSON.parse(await window.estella.fs.read(parentPath)) as MaterialAssetData;+ curPath = parentPath;+ }+ } catch {+ /* a broken parent ref just truncates the chain */+ }++ const root = chain[chain.length - 1];+ let shaderSource: string | null = null;+ if (root?.asset.shader) {+ try {+ shaderSource = await window.estella.fs.read(resolveRef(root.asset.shader, dirOf(root.path)));+ } catch {+ shaderSource = null;+ }+ }++ // Inherited = parent chain merged parent-first (closer ancestors override farther ones),+ // excluding this asset itself (chain[0]).+ const inherited: Record<string, unknown> = {};+ for (let i = chain.length - 1; i >= 1; i--) Object.assign(inherited, chain[i].asset.properties ?? {});++ return { reflection: shaderSource ? reflectEsshader(shaderSource) : { domain: 'Unlit2D', params: [] }, inherited };+}++/** Build one reflected parameter field; null for unsupported types (vec4 has no inspector control). */+function paramField(param: ShaderParam, asset: MaterialAssetData, inherited: Record<string, unknown>): InspectorField | null {+ const def = inherited[param.name] !== undefined ? inherited[param.name] : shaderDefaultAsset(param);+ const stored = asset.properties[param.name];+ const cur = stored !== undefined ? stored : def;+ const base = { key: param.name, label: param.displayName };++ switch (param.type) {+ case 'color':+ return { ...base, type: 'color', value: colorToHex(cur as Record<string, number>), defaultValue: colorToHex(def as Record<string, number>) };+ case 'texture':+ return { ...base, type: 'asset', assetType: 'texture', value: (cur as string | number) ?? 0, defaultValue: (def as string | number) ?? 0 };+ case 'float':+ case 'int': {+ const f: InspectorField = { ...base, type: 'number', value: typeof cur === 'number' ? cur : 0, defaultValue: typeof def === 'number' ? def : 0 };+ if (param.range) {+ f.min = param.range.min;+ f.max = param.range.max;+ f.slider = true;+ }+ return f;+ }+ case 'vec2':+ return { ...base, type: 'vec2', value: vecToArray(cur, 2) as [number, number], defaultValue: vecToArray(def, 2) as [number, number] };+ case 'vec3':+ return { ...base, type: 'vec3', value: vecToArray(cur, 3) as [number, number, number], defaultValue: vecToArray(def, 3) as [number, number, number] };+ default:+ return null; // vec4: no FieldRow control yet (no material shader uses it) — Material Graph (P5) era.+ }+}++/**+ * The material as inspector components: a Parameters section (reflected `#pragma param`s) and a+ * Render State section (blend / depth / cull). Rendered by the same ComponentSection as entity+ * components — that is the whole point: one inspector, no bespoke panel.+ */+export function buildMaterialComponents(asset: MaterialAssetData, ctx: MaterialContext): InspectorComponent[] {+ const out: InspectorComponent[] = [];++ const paramFields = ctx.reflection.params.map((p) => paramField(p, asset, ctx.inherited)).filter((f): f is InspectorField => f != null);+ if (paramFields.length) out.push({ name: 'Parameters', label: 'Parameters', fields: paramFields });++ out.push({+ name: 'Render State',+ label: 'Render State',+ fields: [+ { key: 'blendMode', label: 'Blend Mode', type: 'enum', options: BLEND_OPTIONS, value: asset.blendMode ?? BlendMode.Normal, defaultValue: BlendMode.Normal },+ { key: 'depthTest', label: 'Depth Test', type: 'bool', value: asset.depthTest ?? false, defaultValue: false },+ { key: 'depthWrite', label: 'Depth Write', type: 'bool', value: asset.depthWrite ?? true, defaultValue: true },+ { key: 'cull', label: 'Cull', type: 'enum', options: CULL_OPTIONS, value: asset.cull ?? CullMode.None, defaultValue: CullMode.None },+ ],+ });++ return out;+}++/** Convert a FieldRow value (hex / number[] / scalar / ref) back into the param's stored shape. */+function fieldValueToAsset(param: ShaderParam, value: number | boolean | string | number[]): unknown {+ if (param.type === 'color') return hexToColor(value as string);+ if (param.type === 'texture') return value as string | number;+ if (param.type === 'float' || param.type === 'int') return value as number;+ return arrayToVec(value as number[], ARITY[param.type] ?? 1);+}++/**+ * A FieldWrite that routes an inspector edit to the live MaterialDocument. Render state is set+ * directly; a parameter is stored as an override unless it equals the inherited/default value,+ * in which case the override is dropped (diff serialization — the standard Reset reverts an+ * instance param to its inherited value with no extra UI).+ */+export function makeMaterialWrite(ctx: MaterialContext) {+ // The value union matches FieldRow's edit callback; materials only ever emit+ // number / boolean / string / number[] (no gradient/curve), so the cast below is safe.+ return (key: string, _type: InspectorFieldType, value: number | boolean | string | number[] | GradientValue | CurveValue): void => {+ if (RENDER_STATE_KEYS.has(key)) {+ MaterialDocument.edit(`Set ${key}`, (d) => {+ (d as unknown as Record<string, unknown>)[key] = value;+ });+ return;+ }+ const param = ctx.reflection.params.find((p) => p.name === key);+ if (!param) return;+ const def = ctx.inherited[key] !== undefined ? ctx.inherited[key] : shaderDefaultAsset(param);+ const assetVal = fieldValueToAsset(param, value as number | boolean | string | number[]);+ MaterialDocument.edit(`Set ${key}`, (d) => {+ if (assetEquals(assetVal, def)) delete d.properties[key];+ else d.properties[key] = assetVal as never;+ });+ };+}++// Convert a param's stored value (or its declared default) into the runtime UniformValue the SDK+// expects: color {r,g,b,a} -> Vec4, vec {x,y,..} -> array, scalar -> number, texture -> skip.+function toRuntimeValue(param: ShaderParam, stored: unknown): UniformValue | undefined {+ if (param.type === 'texture') return undefined;+ if (param.type === 'color') {+ const c = (stored ?? {}) as Record<string, number>;+ const d = param.default;+ return stored+ ? { x: c.r ?? 0, y: c.g ?? 0, z: c.b ?? 0, w: c.a ?? 1 }+ : { x: d[0] ?? 0, y: d[1] ?? 0, z: d[2] ?? 0, w: d[3] ?? 1 };+ }+ if (param.type === 'float' || param.type === 'int') return typeof stored === 'number' ? stored : param.default[0] ?? 0;+ const arity = ARITY[param.type] ?? 1;+ return stored ? vecToArray(stored, arity) : param.default.slice(0, arity);+}++/**+ * Project the document onto the running material handle so the viewport reflects edits next frame.+ * A base pushes every param (declared defaults included); an instance pushes only its overrides,+ * leaving inherited params alone. The document stays the source of truth — this is its runtime view.+ */+export function projectMaterialToHandle(asset: MaterialAssetData, ctx: MaterialContext, handle: number): void {+ if (!handle) return;+ const isInstance = asset.instanceOf != null;+ for (const param of ctx.reflection.params) {+ const overridden = Object.prototype.hasOwnProperty.call(asset.properties, param.name);+ if (isInstance && !overridden) continue;+ const rv = toRuntimeValue(param, overridden ? asset.properties[param.name] : undefined);+ if (rv !== undefined) Material.setUniform(handle, param.name, rv);+ }+ if (!isInstance || asset.blendMode !== undefined) Material.setBlendMode(handle, (asset.blendMode ?? BlendMode.Normal) as BlendMode);+ if (!isInstance || asset.depthTest !== undefined) Material.setDepthTest(handle, asset.depthTest ?? false);+ if (!isInstance || asset.depthWrite !== undefined) Material.setDepthWrite(handle, asset.depthWrite ?? true);+ if (!isInstance || asset.cull !== undefined) Material.setCull(handle, (asset.cull ?? CullMode.None) as CullMode);+}++/**+ * Draw a live "material ball" thumbnail of the material at @p handle into @p canvas (a square),+ * via the engine's offscreen render-to-texture preview. No-op without a handle/canvas; call it+ * after pushing edits to the handle so the thumbnail reflects them.+ */+export function renderMaterialThumbnail(handle: number, canvas: HTMLCanvasElement | null): void {+ if (!handle || !canvas) return;+ const img = Material.renderPreview(handle, canvas.width, canvas.height);+ if (img) canvas.getContext('2d')?.putImageData(img, 0, 0);+}diff --git a/desktop/src/material/openMaterial.ts b/desktop/src/material/openMaterial.tsnew file mode 100644index 000000000..4b2952686--- /dev/null+++ b/desktop/src/material/openMaterial.ts@@ -0,0 +1,140 @@+// SPDX-License-Identifier: LicenseRef-PolyForm-Noncommercial-1.0.0+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team+/**+ * @file openMaterial.ts+ * @brief Open / create a `.esmaterial` from the Content Browser. Mirrors openTileset.ts+ * (open + create + .meta + registry re-scan). A new material is born with its own+ * default unlit `.esshader` (a `u_tint` color param) so it renders and is editable+ * immediately; a material instance writes only its parent ref (UE MIC).+ */+import type { MaterialAssetData } from 'esengine';+import { ProjectStore } from '@/project/ProjectStore';+import { dockApi } from '@/layout/dockApi';+import { useSelection } from '@/store/selectionStore';+import { baseName } from '@/project/assetMeta';+import { Toasts } from '@/store/Toasts';++// Default material shader: the batch vertex layout + an unlit fragment that tints the sampled+// texture by the per-instance color and a `u_tint` material param (the auto-generated+// MaterialConstants block supplies u_tint). Gives a new material a visible, editable param.+const DEFAULT_MATERIAL_SHADER = `#pragma shader "Material"+#pragma version 300 es+#pragma domain Unlit2D+#pragma param u_tint color default(1,1,1,1)++#pragma vertex+layout(location = 0) in vec2 a_position;+layout(location = 1) in vec4 a_color;+layout(location = 2) in vec2 a_texCoord;+layout(location = 3) in float a_texIndex;++layout(std140) uniform FrameConstants {+ mat4 u_projection;+};++out vec4 v_color;+out vec2 v_texCoord;++void main() {+ gl_Position = u_projection * vec4(a_position, 0.0, 1.0);+ v_color = a_color;+ v_texCoord = a_texCoord;+}+#pragma end++#pragma fragment+precision mediump float;++in vec4 v_color;+in vec2 v_texCoord;++uniform sampler2D u_textures[8];++out vec4 fragColor;++void main() {+ fragColor = texture(u_textures[0], v_texCoord) * v_color * u_tint;+}+#pragma end+`;++/**+ * Open a `.esmaterial` for editing: select it so the unified Details inspector edits it inline+ * (reflection-driven Parameters + Render State), and reveal the Details panel. There is no+ * separate material panel — the asset inspector loads + previews the selected material.+ */+export function openMaterial(path: string): void {+ useSelection.getState().selectAsset(path);+ dockApi.reveal('details');+}++// Pick a `<base>.esmaterial` name in @p dir that no tracked asset already uses.+function uniqueMaterialPath(dir: string, base: string): string {+ let rel = `${dir}${base}.esmaterial`;+ for (let n = 1; ProjectStore.assetRef(rel); n++) rel = `${dir}${base}-${n}.esmaterial`;+ return rel;+}++async function writeMeta(rel: string): Promise<void> {+ await window.estella.fs.write(+ rel + '.meta',+ JSON.stringify({ uuid: crypto.randomUUID(), version: '1.0', type: 'material', importer: { autoMigrate: true } }, null, 2) + '\n',+ );+}++/** Create a new base material (+ its own default shader) in @p dir, then open it. */+export async function createMaterial(dir: string): Promise<void> {+ const folder = dir ? (dir.endsWith('/') ? dir : `${dir}/`) : '';+ const matRel = uniqueMaterialPath(folder, 'NewMaterial');+ const base = baseName(matRel).replace(/\.esmaterial$/, '');+ const shaderRel = `${folder}${base}.esshader`;++ const asset: MaterialAssetData = {+ version: '1.0',+ type: 'material',+ shader: `${base}.esshader`,+ blendMode: 0,+ depthTest: false,+ depthWrite: true,+ cull: 0,+ properties: { u_tint: { r: 1, g: 1, b: 1, a: 1 } },+ };++ try {+ await window.estella.fs.write(shaderRel, DEFAULT_MATERIAL_SHADER);+ await window.estella.fs.write(matRel, JSON.stringify(asset, null, 2) + '\n');+ await writeMeta(matRel);+ } catch (e) {+ Toasts.push(`创建材质失败:${String(e)}`, 'error');+ return;+ }+ await ProjectStore.refreshAssets();+ Toasts.push(`已创建材质:${baseName(matRel)}`, 'info');+ openMaterial(matRel);+}++/** Create a material instance of @p parentPath (UE MIC): only the parent ref, no overrides yet. */+export async function createMaterialInstance(parentPath: string): Promise<void> {+ const dir = parentPath.includes('/') ? parentPath.slice(0, parentPath.lastIndexOf('/') + 1) : '';+ const parentBase = baseName(parentPath).replace(/\.esmaterial$/, '');+ const matRel = uniqueMaterialPath(dir, `${parentBase} Instance`);++ const asset: MaterialAssetData = {+ version: '1.0',+ type: 'material',+ shader: '',+ instanceOf: baseName(parentPath), // relative to the same folder+ properties: {},+ };++ try {+ await window.estella.fs.write(matRel, JSON.stringify(asset, null, 2) + '\n');+ await writeMeta(matRel);+ } catch (e) {+ Toasts.push(`创建材质实例失败:${String(e)}`, 'error');+ return;+ }+ await ProjectStore.refreshAssets();+ Toasts.push(`已创建材质实例:${baseName(matRel)}`, 'info');+ openMaterial(matRel);+}diff --git a/desktop/src/material/openMaterialGraph.ts b/desktop/src/material/openMaterialGraph.tsnew file mode 100644index 000000000..838adc9db--- /dev/null+++ b/desktop/src/material/openMaterialGraph.ts@@ -0,0 +1,67 @@+// SPDX-License-Identifier: LicenseRef-PolyForm-Noncommercial-1.0.0+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team+/**+ * @file openMaterialGraph.ts+ * @brief Open / create / save a `.esmatgraph` (the visual Material Graph, P5b).+ * @details A graph is a visual frontend that compiles to a sibling `.esshader` (P5a's+ * `compileMaterialGraph`); any `.esmaterial` then references that shader like a+ * hand-written one. Create writes the graph + its compiled shader + .meta; Save+ * rewrites both so an edit flows to every material on the shader.+ */+import { compileMaterialGraph, newMaterialGraph, type MaterialGraph } from 'esengine';+import { MaterialGraphDocument } from './MaterialGraphDocument';+import { ProjectStore } from '@/project/ProjectStore';+import { dockApi } from '@/layout/dockApi';+import { baseName } from '@/project/assetMeta';+import { Toasts } from '@/store/Toasts';++const shaderPathOf = (graphPath: string) => graphPath.replace(/\.esmatgraph$/, '.esshader');++/** Open an existing `.esmatgraph` into the Material Graph editor and reveal the panel. */+export async function openMaterialGraph(path: string): Promise<void> {+ try {+ const text = await window.estella.fs.read(path);+ MaterialGraphDocument.openJson(JSON.parse(text), path);+ dockApi.revealAndExpand('materialgraph');+ } catch (e) {+ Toasts.push(`无法打开材质图:${String(e)}`, 'error');+ }+}++/** Write the graph + recompile its sibling `.esshader`. Throws on a graph that can't compile. */+export async function saveMaterialGraph(path: string, graph: MaterialGraph): Promise<void> {+ try {+ const shader = compileMaterialGraph(graph); // throws on a broken graph — surfaced below+ await window.estella.fs.write(path, JSON.stringify(graph, null, 2) + '\n');+ await window.estella.fs.write(shaderPathOf(path), shader);+ MaterialGraphDocument.markSaved();+ Toasts.push('Material graph saved', 'info', 1400);+ } catch (e) {+ Toasts.push(`保存材质图失败:${String(e)}`, 'error');+ }+}++/** Create a new `.esmatgraph` (+ its compiled `.esshader` + .meta) in @p dir, then open it. */+export async function createMaterialGraph(dir: string): Promise<void> {+ const folder = dir ? (dir.endsWith('/') ? dir : `${dir}/`) : '';+ let rel = `${folder}NewGraph.esmatgraph`;+ for (let n = 1; ProjectStore.assetRef(rel); n++) rel = `${folder}NewGraph-${n}.esmatgraph`;++ const graph = newMaterialGraph();+ graph.name = baseName(rel).replace(/\.esmatgraph$/, '');++ try {+ await window.estella.fs.write(rel, JSON.stringify(graph, null, 2) + '\n');+ await window.estella.fs.write(shaderPathOf(rel), compileMaterialGraph(graph));+ await window.estella.fs.write(+ rel + '.meta',+ JSON.stringify({ uuid: crypto.randomUUID(), version: '1.0', type: 'materialgraph', importer: { autoMigrate: true } }, null, 2) + '\n',+ );+ } catch (e) {+ Toasts.push(`创建材质图失败:${String(e)}`, 'error');+ return;+ }+ await ProjectStore.refreshAssets();+ Toasts.push(`已创建材质图:${baseName(rel)}`, 'info');+ await openMaterialGraph(rel);+}diff --git a/desktop/src/material/shaderReflect.ts b/desktop/src/material/shaderReflect.tsnew file mode 100644index 000000000..934bd2be3--- /dev/null+++ b/desktop/src/material/shaderReflect.ts@@ -0,0 +1,118 @@+// SPDX-License-Identifier: LicenseRef-PolyForm-Noncommercial-1.0.0+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team+/**+ * @file shaderReflect.ts+ * @brief Editor-side reflection of a `.esshader`'s `#pragma param` declarations.+ * @details Parses the same param grammar the engine's C++ ShaderParser does, but only the+ * UI-facing metadata (name / type / default / range / ui hint / display name) — the+ * editor builds a parameter panel from it. The engine remains the single source of+ * the std140 layout + GLSL codegen; this is the static, editor-only view of the+ * declarations, so the Material Editor needn't round-trip through a compiled shader.+ *+ * Grammar (matches ShaderParser):+ * #pragma param <name> <type> [default(csv)] [range(min,max)] [ui(hint)]+ * #pragma domain <Unlit2D|Lit2D|PostProcess|UI>+ */++export type ShaderParamType = 'float' | 'vec2' | 'vec3' | 'vec4' | 'color' | 'int' | 'texture';++export interface ShaderParam {+ name: string;+ type: ShaderParamType;+ /** Human label for the inspector row (leading `u_` stripped, capitalized). */+ displayName: string;+ /** Default components for a scalar/vector param (length 1–4); empty for a texture. */+ default: number[];+ /** Default texture hint for a texture param (e.g. "white"); undefined otherwise. */+ defaultTexture?: string;+ /** Optional slider bounds from `range(min,max)`. */+ range?: { min: number; max: number };+ /** Optional UI hint from `ui(...)`, e.g. "slider". */+ ui?: string;+}++export interface ShaderReflection {+ domain: string;+ params: ShaderParam[];+}++const TYPES = new Set<ShaderParamType>(['float', 'vec2', 'vec3', 'vec4', 'color', 'int', 'texture']);+const ARITY: Record<string, number> = { float: 1, int: 1, vec2: 2, vec3: 3, vec4: 4, color: 4 };++// Extract the contents of a `key(...)` clause from a directive argument.+function clause(arg: string, key: string): string | undefined {+ const token = `${key}(`;+ const open = arg.indexOf(token);+ if (open < 0) return undefined;+ const start = open + token.length;+ const close = arg.indexOf(')', start);+ if (close < 0) return undefined;+ return arg.slice(start, close).trim();+}++function defaultForType(type: ShaderParamType): number[] {+ if (type === 'texture') return [];+ if (type === 'color') return [0, 0, 0, 1];+ return new Array(ARITY[type] ?? 1).fill(0);+}++function displayNameFor(name: string): string {+ let s = name.startsWith('u_') ? name.slice(2) : name;+ if (s.length > 0) s = s[0].toUpperCase() + s.slice(1);+ return s;+}++function parseParam(arg: string): ShaderParam | null {+ const tokens = arg.trim().split(/\s+/);+ const name = tokens[0];+ const typeStr = tokens[1];+ if (!name || !typeStr || !TYPES.has(typeStr as ShaderParamType)) return null;+ const type = typeStr as ShaderParamType;++ const param: ShaderParam = { name, type, displayName: displayNameFor(name), default: defaultForType(type) };++ const def = clause(arg, 'default');+ if (def !== undefined) {+ if (type === 'texture') {+ param.defaultTexture = def;+ } else {+ const nums = def.split(',').map((s) => parseFloat(s.trim())).filter((n) => !Number.isNaN(n));+ if (nums.length > 0) param.default = nums;+ }+ }++ const range = clause(arg, 'range');+ if (range !== undefined) {+ const [min, max] = range.split(',').map((s) => parseFloat(s.trim()));+ if (!Number.isNaN(min) && !Number.isNaN(max)) param.range = { min, max };+ }++ const ui = clause(arg, 'ui');+ if (ui !== undefined) param.ui = ui;++ return param;+}++/** Parse a `.esshader` source into its editor-facing parameter reflection. */+export function reflectEsshader(source: string): ShaderReflection {+ const params: ShaderParam[] = [];+ let domain = 'Unlit2D';++ for (const raw of source.split('\n')) {+ const line = raw.trim();+ if (!line.startsWith('#pragma')) continue;+ const rest = line.slice('#pragma'.length).trim();+ const sp = rest.search(/\s/);+ const directive = sp < 0 ? rest : rest.slice(0, sp);+ const arg = sp < 0 ? '' : rest.slice(sp + 1).trim();++ if (directive === 'param') {+ const p = parseParam(arg);+ if (p) params.push(p);+ } else if (directive === 'domain' && arg) {+ domain = arg;+ }+ }++ return { domain, params };+}diff --git a/desktop/src/panels/ContentBrowser.tsx b/desktop/src/panels/ContentBrowser.tsxindex 98e440596..2c92cb375 100644--- a/desktop/src/panels/ContentBrowser.tsx+++ b/desktop/src/panels/ContentBrowser.tsx@@ -1,10 +1,10 @@// SPDX-License-Identifier: LicenseRef-PolyForm-Noncommercial-1.0.0// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team-import { Fragment, useCallback, useEffect, useLayoutEffect, useMemo, useRef, useState, useSyncExternalStore } from 'react';-import { createPortal } from 'react-dom';+import { Fragment, useCallback, useEffect, useMemo, useRef, useState, useSyncExternalStore } from 'react';import { ChevronRight, Search, LayoutGrid, List, Import, FolderOpen, FolderPlus, ArrowLeft, ArrowRight, ArrowUp } from 'lucide-react';import { AssetIcon, assetTint } from '@/components/icons';import { ContextMenu, type MenuItem } from '@/components/Menu';+import { useTooltip } from '@/components/Tooltip';import { ProjectStore } from '@/project/ProjectStore';import { Toasts } from '@/store/Toasts';import { useSelection } from '@/store/selectionStore';@@ -12,6 +12,8 @@ import { IMAGE_RE, assetTypeOf as assetType, TYPE_CODE } from '@/project/assetMeimport { ASSET_OPEN } from '@/project/assetOpen';import { createTilesetFromTexture } from '@/tileset/openTileset';import { createTilemapFromTileset } from '@/tilemap/createTilemap';+import { createMaterial, createMaterialInstance } from '@/material/openMaterial';+import { createMaterialGraph } from '@/material/openMaterialGraph';import { fsRefresh } from '@/project/fsWatch';import type { DirEntry } from '@/project/format';import type { AssetType } from '@/types';@@ -105,12 +107,11 @@ function TipRow({ k, v, mono }: { k: string; v: string; mono?: boolean }) {);}-// UE5-style hover card: the metadata you can't see at a glance (type / path /-// reference / image dimensions / disk size / modified). Anchored beside the tile,-// clamped on-screen, non-interactive. Fetches stat + dimensions lazily on show.-function AssetTooltip({ path, entry, rect }: { path: string; entry: DirEntry; rect: DOMRect }) {- const ref = useRef<HTMLDivElement>(null);- const [pos, setPos] = useState({ left: rect.right + 10, top: rect.top });+// UE5-style hover-card body: the metadata you can't see at a glance (type / path /+// reference / image dimensions / disk size / modified). Positioning, portaling and+// dismissal are the shared <Tooltip> primitive's job; this is just the contents,+// fetched lazily on show.+function AssetTipCard({ path, entry }: { path: string; entry: DirEntry }) {const [stat, setStat] = useState<{ size: number; mtimeMs: number } | null>(null);const [dims, setDims] = useState<string | null>(null);@@ -139,21 +140,8 @@ function AssetTooltip({ path, entry, rect }: { path: string; entry: DirEntry; re};}, [isImg, path]);- // Clamp beside the tile (flip to the left / lift up near an edge).- useLayoutEffect(() => {- const el = ref.current;- if (!el) return;- const r = el.getBoundingClientRect();- const pad = 8;- let left = rect.right + 10;- if (left + r.width > window.innerWidth - pad) left = Math.max(pad, rect.left - r.width - 10);- let top = rect.top;- if (top + r.height > window.innerHeight - pad) top = Math.max(pad, window.innerHeight - r.height - pad);- setPos({ left, top });- }, [rect, stat, dims]);-- return createPortal(- <div ref={ref} className="cb-tip" style={{ left: pos.left, top: pos.top }}>+ return (+ <><div className="cb-tip-name">{entry.name}</div><TipRow k="Type" v={entry.isDir ? 'Folder' : TYPE_CODE[type] || type} />{dims && <TipRow k="Dimensions" v={dims} />}@@ -161,8 +149,7 @@ function AssetTooltip({ path, entry, rect }: { path: string; entry: DirEntry; re{stat && <TipRow k="Modified" v={new Date(stat.mtimeMs).toLocaleString()} />}<TipRow k="Path" v={path} mono />{assetReference && <TipRow k="Reference" v={assetReference} mono />}- </div>,- document.body,+ </>);}@@ -249,18 +236,9 @@ export function ContentBrowser() {// A right-click menu: on an item (target set) or on empty space (target null).const [ctx, setCtx] = useState<{ x: number; y: number; target: { path: string; entry: DirEntry } | null } | null>(null);const [renaming, setRenaming] = useState<string | null>(null);- const [hover, setHover] = useState<{ path: string; entry: DirEntry; rect: DOMRect } | null>(null);- const hoverTimer = useRef<number | null>(null);const [filters, setFilters] = useState<Set<AssetType>>(new Set());+ const tip = useTooltip<{ path: string; entry: DirEntry }>((p) => <AssetTipCard path={p.path} entry={p.entry} />);- const clearHover = useCallback(() => {- if (hoverTimer.current) {- clearTimeout(hoverTimer.current);- hoverTimer.current = null;- }- setHover(null);- }, []);- useEffect(() => () => clearHover(), [clearHover]);// Asset selection lives in the shared store (unified inspector): selecting an// asset drives the Details panel + clears any entity selection.const selected = useSelection((s) => s.selectedAsset);@@ -411,24 +389,19 @@ export function ContentBrowser() {const bindItem = (path: string, e: DirEntry) => ({draggable: !e.isDir && renaming !== path,onDragStart: (ev: React.DragEvent) => {- clearHover();+ tip.close();ev.dataTransfer.effectAllowed = 'copy';ev.dataTransfer.setData('application/x-estella-asset', path);ev.dataTransfer.setData('text/plain', path);},onClick: () => selectAsset(path),onDoubleClick: () => onOpen(path, e.isDir, e.name),- onMouseEnter: (ev: React.MouseEvent) => {- if (renaming) return;- const rect = ev.currentTarget.getBoundingClientRect();- if (hoverTimer.current) clearTimeout(hoverTimer.current);- hoverTimer.current = window.setTimeout(() => setHover({ path, entry: e, rect }), 450);- },- onMouseLeave: clearHover,+ // Suppress the hover card while any inline rename is active.+ ...(renaming ? null : tip.bind({ path, entry: e })),onContextMenu: (ev: React.MouseEvent) => {ev.preventDefault();ev.stopPropagation(); // don't fall through to the empty-space menu- clearHover();+ tip.close();selectAsset(path);setCtx({ x: ev.clientX, y: ev.clientY, target: { path, entry: e } });},@@ -441,6 +414,8 @@ export function ContentBrowser() {return [{ label: 'Import…', icon: <Import size={14} />, onClick: () => void importAssets() },{ label: 'New Folder', icon: <FolderPlus size={14} />, onClick: () => void newFolder() },+ { label: 'New Material', onClick: () => void createMaterial(cwd) },+ { label: 'New Material Graph', onClick: () => void createMaterialGraph(cwd) },{ sep: true },{ label: 'Show in Explorer', onClick: () => void showInExplorer(cwd) },];@@ -449,9 +424,10 @@ export function ContentBrowser() {const isScene = !entry.isDir && assetType(entry.name) === 'scene';const isTexture = !entry.isDir && (assetType(entry.name) === 'texture' || assetType(entry.name) === 'sprite');const isTileset = !entry.isDir && assetType(entry.name) === 'tileset';+ const isMaterial = !entry.isDir && assetType(entry.name) === 'material';const ref = entry.isDir ? null : ProjectStore.assetRef(path);return [- ...(entry.isDir || isScene+ ...(entry.isDir || isScene || isMaterial? [{ label: 'Open', onClick: () => onOpen(path, entry.isDir, entry.name) }]: []),...(isTexture@@ -460,6 +436,9 @@ export function ContentBrowser() {...(isTileset? [{ label: 'Create Tilemap', onClick: () => void createTilemapFromTileset(path) }]: []),+ ...(isMaterial+ ? [{ label: 'Create Material Instance', onClick: () => void createMaterialInstance(path) }]+ : []),{ label: 'Rename', onClick: () => setRenaming(path) },{ label: 'Duplicate', onClick: () => void duplicate(path) },{ sep: true },@@ -581,14 +560,13 @@ export function ContentBrowser() {<divclassName={`cb-scroll${view === 'list' ? ' list' : ''}`}- onScroll={clearHover}onClick={(e) => {if (e.target === e.currentTarget) selectAsset(null);}}onContextMenu={(e) => {// Items stopPropagation, so reaching here = a right-click on empty space.e.preventDefault();- clearHover();+ tip.close();setCtx({ x: e.clientX, y: e.clientY, target: null });}}>@@ -688,7 +666,7 @@ export function ContentBrowser() {</div></div>- {hover && !ctx && <AssetTooltip path={hover.path} entry={hover.entry} rect={hover.rect} />}+ {!ctx && tip.card}{ctx && <ContextMenu x={ctx.x} y={ctx.y} items={ctxItems} onClose={() => setCtx(null)} />}</div>);diff --git a/desktop/src/panels/Details.tsx b/desktop/src/panels/Details.tsxindex 8b5e4bbed..0a2c2eb8d 100644--- a/desktop/src/panels/Details.tsx+++ b/desktop/src/panels/Details.tsx@@ -1,6 +1,6 @@// SPDX-License-Identifier: LicenseRef-PolyForm-Noncommercial-1.0.0// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team-import { useMemo, useRef, useState, useSyncExternalStore } from 'react';+import { useEffect, useMemo, useRef, useState, useSyncExternalStore } from 'react';import {Box,Camera,@@ -18,6 +18,7 @@ import {Package,Plus,RotateCcw,+ Save,Search,Square,Trash2,@@ -41,6 +42,16 @@ import { PlayInspect } from '@/engine/PlayInspect';import type { SceneData } from 'esengine';import { modelAddableComponentEntries, subscribeSchemas, getSchemaRevision, prettyLabel, hexToRgba } from '@/engine/schema';import { ProjectStore } from '@/project/ProjectStore';+import { MaterialDocument } from '@/material/MaterialDocument';+import {+ isMaterialAsset,+ resolveMaterialContext,+ buildMaterialComponents,+ makeMaterialWrite,+ projectMaterialToHandle,+ renderMaterialThumbnail,+ type MaterialContext,+} from '@/material/materialInspectorModel';import { ContextMenu } from '@/components/Menu';import { Popover, usePopover } from '@/components/Popover';import { AddComponentMenu } from '@/components/AddComponentMenu';@@ -91,7 +102,7 @@ const KIND_LABEL: Record<NodeKind, string> = {// Each control reports gesture boundaries (onBegin/onEnd) so one focus→blur, one// click, or one drag-scrub becomes a single undo step; onCommit applies live.-interface ControlGesture {+export interface ControlGesture {onBegin?: () => void;onEnd?: () => void;}@@ -144,7 +155,7 @@ function useScrub(value: number, onCommit: (n: number) => void, opts: ScrubOpts// Plain click-to-type numeric input. `suffix` (e.g. °) shows in the resting value;// `mixed` (multi-select disagreement) shows a "—" placeholder until typed over.-function NumField({+export function NumField({value,suffix,mixed,@@ -219,7 +230,7 @@ function VecField({);}-function VecControl({+export function VecControl({value,mixed,onBegin,@@ -250,7 +261,7 @@ function VecControl({// A named-int dropdown (e.g. Camera projection, body type) — a themed popover, not// a native <select>, so the list matches the editor and searches when long. The// stored value is the option's int; an unknown value shows a "(n)" placeholder.-function EnumControl({+export function EnumControl({value,options,mixed,@@ -382,7 +393,7 @@ function FlagsControl({// A bounded number: a draggable track (the .slider widget) paired with a compact// exact-entry box. Both snap to `step` and clamp to [min,max].-function SliderControl({+export function SliderControl({value,min,max,@@ -445,7 +456,7 @@ function SliderControl({);}-function BoolControl({+export function BoolControl({value,mixed,onBegin,@@ -562,7 +573,7 @@ function useDragTrack(onMove: (x: number, y: number) => void) {// editable (the native <input type=color> can't). Local HSV state preserves hue// while dragging at zero saturation/value; the whole picker session is one undo// step (begin on open, end on close). The hex box accepts 6- or 8-digit input.-function ColorControl({+export function ColorControl({value,onBegin,onEnd,@@ -884,7 +895,7 @@ const isImageAsset = (t: AssetType): boolean => t === 'texture' || t === 'sprite// An asset-ref field: a drop target showing the bound asset, PLUS a pick popover// (search + thumbnail grid of the project's matching assets) on the lens button —// so a ref can be set without dragging from the Content Browser. Clear with ×.-function AssetControl({+export function AssetControl({value,assetType,onBegin,@@ -1322,13 +1333,150 @@ function GameDetails() {);}+// Material view of the unified inspector — a `.esmaterial` selected in the content browser is+// edited right here, by the same ComponentSection/FieldRow machinery as an entity's components+// (Parameters + Render State), driven by the shader's reflection. There is no bespoke material+// panel: edits flow through the live MaterialDocument (one undo step each, viewport preview) and+// Save writes the JSON back. An instance edits only its overrides; Reset reverts to inherited.+function MaterialAssetInspector({ path }: { path: string }) {+ const revision = useSyncExternalStore(MaterialDocument.subscribe, MaterialDocument.getRevision);+ const [ctx, setCtx] = useState<MaterialContext | null>(null);+ const [collapsed, setCollapsed] = useState<Set<string>>(new Set());+ const toggle = (name: string) =>+ setCollapsed((s) => {+ const n = new Set(s);+ n.has(name) ? n.delete(name) : n.add(name);+ return n;+ });++ // Load the selected material into the singleton document when the selection changes, and bind+ // the running handle the scene's sprites use (0 when it's not in the current scene).+ useEffect(() => {+ let alive = true;+ void window.estella.fs+ .read(path)+ .then((text) => {+ if (!alive) return;+ MaterialDocument.openJson(JSON.parse(text), path);+ MaterialDocument.setLiveHandle(ProjectStore.materialHandle(path));+ })+ .catch(() => {});+ return () => {+ alive = false;+ MaterialDocument.close();+ };+ }, [path]);++ const asset = MaterialDocument.asset;+ const filePath = MaterialDocument.filePath;+ const loaded = !!asset && filePath === path;++ // Reflect the (root) shader + collect inherited params only when the shader binding changes.+ useEffect(() => {+ if (!loaded || !asset || !filePath) {+ setCtx(null);+ return;+ }+ let alive = true;+ void resolveMaterialContext(asset, filePath).then((c) => {+ if (alive) setCtx(c);+ });+ return () => {+ alive = false;+ };+ }, [loaded, asset?.shader, asset?.instanceOf, filePath]);++ const thumbRef = useRef<HTMLCanvasElement>(null);+ // Live preview: re-project the document onto the running handle on every edit/undo/redo, then+ // refresh the offscreen "material ball" thumbnail from that same handle (WYSIWYG).+ useEffect(() => {+ if (loaded && asset && ctx) {+ projectMaterialToHandle(asset, ctx, MaterialDocument.liveHandle);+ renderMaterialThumbnail(MaterialDocument.liveHandle, thumbRef.current);+ }+ }, [revision, ctx, loaded]);++ if (!loaded || !asset) {+ return (+ <div className="insp">+ <div className="insp-empty" style={{ flex: 1 }}>+ <div className="et">Loading material…</div>+ </div>+ </div>+ );+ }++ const isInstance = asset.instanceOf != null;+ const dirty = MaterialDocument.dirty;+ const components = ctx ? buildMaterialComponents(asset, ctx) : [];+ const write = ctx ? makeMaterialWrite(ctx) : undefined;++ const save = async () => {+ try {+ await window.estella.fs.write(path, JSON.stringify(asset, null, 2) + '\n');+ MaterialDocument.markSaved();+ Toasts.push('Material saved', 'info', 1400);+ } catch (e) {+ Toasts.push(`保存材质失败:${String(e)}`, 'error');+ }+ };++ return (+ <div className="insp">+ <div className="ent-head">+ <div className="ent-row1">+ <div className="ent-name">{baseName(path)}</div>+ <button type="button" className="primary" disabled={!dirty} onClick={() => void save()} title="Save material">+ <Save size={13} strokeWidth={1.9} /> Save+ </button>+ </div>+ <div className="ent-meta">+ <span className="pill">+ <span className="pk">Material</span>+ {isInstance ? 'Instance' : ctx?.reflection.domain ?? 'Unlit2D'}+ </span>+ {dirty && <span className="pill">Unsaved</span>}+ </div>+ </div>+ {MaterialDocument.liveHandle > 0 && (+ <div className="mat-preview">+ <canvas ref={thumbRef} className="mat-thumb" width={96} height={96} />+ </div>+ )}+ <div className="mat-sync">+ {MaterialDocument.liveHandle+ ? 'Edits preview live in the viewport.'+ : 'Not in the current scene — edits apply on Save.'}+ </div>+ <div className="insp-body">+ {components.map((comp) => (+ <ComponentSection+ key={comp.name}+ entities={[]}+ comp={comp}+ collapsed={collapsed.has(comp.name)}+ onToggle={() => toggle(comp.name)}+ write={write}+ />+ ))}+ {ctx && components.length === 1 && (+ <div className="mat-hint">This material's shader declares no parameters.</div>+ )}+ </div>+ </div>+ );+}+// Asset view of the unified inspector — shown when an asset (not an entity) is-// selected (in the content browser). Only fields the fs layer provides; the-// preview is the image itself or the type glyph.+// selected (in the content browser). A material is edited inline (reflection-driven+// rows); other assets show their fs metadata + the image/type glyph preview.function AssetInspector({ path }: { path: string }) {const name = baseName(path);const type = assetTypeOf(name);const isImage = IMAGE_RE.test(name);+ if (isMaterialAsset(path)) {+ return <MaterialAssetInspector path={path} />;+ }return (<div className="insp"><div className="cb-detail-body" style={{ flex: 1, minHeight: 0, overflowY: 'auto' }}>diff --git a/desktop/src/panels/MaterialGraphEditor.tsx b/desktop/src/panels/MaterialGraphEditor.tsxnew file mode 100644index 000000000..13b477457--- /dev/null+++ b/desktop/src/panels/MaterialGraphEditor.tsx@@ -0,0 +1,289 @@+// SPDX-License-Identifier: LicenseRef-PolyForm-Noncommercial-1.0.0+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team+/**+ * @file MaterialGraphEditor.tsx+ * @brief The `.esmatgraph` node editor (Material Graph, P5b) — a canvas of node boxes wired by+ * bezier connections. All graph mutation goes through the pure, tested SDK ops+ * (addNode/connect/disconnect/removeNode/moveNode) on the reactive MaterialGraphDocument;+ * NODE_SPECS drives the palette, ports, and node-param fields so the editor and the+ * compiler never drift. Save compiles the graph to its sibling `.esshader` (P5a).+ */+import { useEffect, useRef, useState, useSyncExternalStore } from 'react';+import { Save, Plus, Trash2 } from 'lucide-react';+import {+ NODE_SPECS,+ addNode,+ moveNode,+ connect,+ disconnect,+ removeNode,+ type MaterialGraph,+ type GraphNodeType,+ type GraphType,+} from 'esengine';+import { MaterialGraphDocument } from '@/material/MaterialGraphDocument';+import { saveMaterialGraph } from '@/material/openMaterialGraph';+import { EditorHistory } from '@/engine/EditorHistory';+import { NumField, ColorControl } from '@/panels/Details';++const NODE_W = 168;+const HEADER_H = 28;+const ROW_H = 24;++// A node's input/output port positions in canvas coordinates (node.x/.y are canvas px).+const nodeX = (n: { x?: number }) => n.x ?? 0;+const nodeY = (n: { y?: number }) => n.y ?? 0;+const outPort = (n: { x?: number; y?: number }) => ({ x: nodeX(n) + NODE_W, y: nodeY(n) + HEADER_H / 2 });+const inPort = (n: { x?: number; y?: number }, i: number) => ({ x: nodeX(n), y: nodeY(n) + HEADER_H + ROW_H * i + ROW_H / 2 });++// Port hue by GLSL type — the same legend the compiler's types imply.+const TYPE_COLOR: Record<GraphType, string> = {+ float: '#9aa7b5',+ vec2: '#6fae8f',+ vec3: '#c2a274',+ vec4: '#c0917a',+};++function bezier(x1: number, y1: number, x2: number, y2: number): string {+ const dx = Math.max(40, Math.abs(x2 - x1) * 0.5);+ return `M ${x1} ${y1} C ${x1 + dx} ${y1}, ${x2 - dx} ${y2}, ${x2} ${y2}`;+}++const rgbaToHex = (c: number[]) => {+ const h = (v: number) => Math.max(0, Math.min(255, Math.round((v ?? 0) * 255))).toString(16).padStart(2, '0');+ return `#${h(c[0])}${h(c[1])}${h(c[2])}${h(c[3] ?? 1)}`;+};+const hexToRgba = (hex: string): number[] => {+ const s = hex.replace('#', '');+ const n = (i: number) => parseInt(s.slice(i, i + 2), 16) / 255;+ return [n(0), n(2), n(4), s.length >= 8 ? n(6) : 1];+};++export function MaterialGraphEditor() {+ useSyncExternalStore(MaterialGraphDocument.subscribe, MaterialGraphDocument.getRevision);+ const graph = MaterialGraphDocument.asset;+ const filePath = MaterialGraphDocument.filePath;+ const dirty = MaterialGraphDocument.dirty;++ const canvasRef = useRef<HTMLDivElement>(null);+ const [selected, setSelected] = useState<string | null>(null);+ const [palette, setPalette] = useState(false);+ // Live cursor (canvas coords) while connecting, to draw the in-progress wire.+ const [cursor, setCursor] = useState<{ x: number; y: number } | null>(null);+ const drag = useRef<{ id: string; offX: number; offY: number; before: MaterialGraph } | null>(null);+ const wire = useRef<{ fromId: string } | null>(null);++ const toCanvas = (clientX: number, clientY: number) => {+ const el = canvasRef.current;+ if (!el) return { x: clientX, y: clientY };+ const r = el.getBoundingClientRect();+ return { x: clientX - r.left + el.scrollLeft, y: clientY - r.top + el.scrollTop };+ };++ // Window-level move/up so a drag or wire keeps tracking outside the node it started on.+ useEffect(() => {+ const onMove = (e: PointerEvent) => {+ const p = toCanvas(e.clientX, e.clientY);+ if (drag.current && graph) {+ MaterialGraphDocument.replaceAsset(moveNode(graph, drag.current.id, p.x - drag.current.offX, p.y - drag.current.offY), { dirty: true });+ } else if (wire.current) {+ setCursor(p);+ }+ };+ const onUp = (e: PointerEvent) => {+ if (drag.current && graph) {+ const after = graph;+ const before = drag.current.before;+ EditorHistory.record('Move node', () => MaterialGraphDocument.replaceAsset(after), () => MaterialGraphDocument.replaceAsset(before));+ drag.current = null;+ }+ if (wire.current && graph) {+ const p = toCanvas(e.clientX, e.clientY);+ const hit = nearestInputPort(graph, p.x, p.y);+ if (hit) MaterialGraphDocument.edit('Connect', (d) => Object.assign(d, connect(d, wire.current!.fromId, hit.nodeId, hit.slot)));+ wire.current = null;+ setCursor(null);+ }+ };+ window.addEventListener('pointermove', onMove);+ window.addEventListener('pointerup', onUp);+ return () => {+ window.removeEventListener('pointermove', onMove);+ window.removeEventListener('pointerup', onUp);+ };+ }, [graph]);++ useEffect(() => {+ const onKey = (e: KeyboardEvent) => {+ if ((e.key === 'Delete' || e.key === 'Backspace') && selected && graph) {+ MaterialGraphDocument.edit('Delete node', (d) => Object.assign(d, removeNode(d, selected)));+ setSelected(null);+ }+ };+ window.addEventListener('keydown', onKey);+ return () => window.removeEventListener('keydown', onKey);+ }, [selected, graph]);++ if (!graph || !filePath) {+ return (+ <div className="panel mg">+ <div className="empty">+ <p>Open a `.esmatgraph` from the Content Browser to edit it.</p>+ </div>+ </div>+ );+ }++ const addAt = (type: GraphNodeType) => {+ const el = canvasRef.current;+ const x = (el?.scrollLeft ?? 0) + 60;+ const y = (el?.scrollTop ?? 0) + 60;+ MaterialGraphDocument.edit(`Add ${type}`, (d) => Object.assign(d, addNode(d, type, x, y).graph));+ setPalette(false);+ };++ const setNodeParam = (id: string, key: string, value: unknown) =>+ MaterialGraphDocument.edit(`Set ${key}`, (d) => {+ const n = d.nodes.find((m) => m.id === id);+ if (n) (n.params ??= {})[key] = value as never;+ });++ // Connections: each node's wired input slots → a bezier from the source output port.+ const wires: { key: string; d: string }[] = [];+ for (const n of graph.nodes) {+ const spec = NODE_SPECS[n.type];+ spec.inputs.forEach((port, i) => {+ const src = n.inputs?.[port.name];+ if (!src) return;+ const from = graph.nodes.find((m) => m.id === src);+ if (!from) return;+ const a = outPort(from);+ const b = inPort(n, i);+ wires.push({ key: `${n.id}.${port.name}`, d: bezier(a.x, a.y, b.x, b.y) });+ });+ }++ return (+ <div className="panel mg">+ <div className="mg-bar">+ <button type="button" className="mg-add" onClick={() => setPalette((v) => !v)} title="Add node">+ <Plus size={13} strokeWidth={2} /> Add+ </button>+ {selected && (+ <button type="button" className="mg-del" onClick={() => { MaterialGraphDocument.edit('Delete node', (d) => Object.assign(d, removeNode(d, selected))); setSelected(null); }} title="Delete selected">+ <Trash2 size={13} strokeWidth={1.9} />+ </button>+ )}+ <span className="mg-title">{filePath.split('/').pop()}{dirty && <span className="mg-dot" title="Unsaved">●</span>}</span>+ <span style={{ flex: 1 }} />+ <button type="button" className="primary" disabled={!dirty} onClick={() => void saveMaterialGraph(filePath, graph)}>+ <Save size={13} strokeWidth={1.9} /> Save+ </button>+ {palette && (+ <div className="mg-palette" onPointerLeave={() => setPalette(false)}>+ {(Object.keys(NODE_SPECS) as GraphNodeType[]).filter((t) => NODE_SPECS[t].addable).map((t) => (+ <button key={t} type="button" onClick={() => addAt(t)}>{NODE_SPECS[t].label}</button>+ ))}+ </div>+ )}+ </div>++ <div className="mg-canvas" ref={canvasRef} onPointerDown={() => setSelected(null)}>+ <svg className="mg-wires" aria-hidden="true">+ {wires.map((w) => <path key={w.key} d={w.d} />)}+ {wire.current && cursor && (() => {+ const from = graph.nodes.find((m) => m.id === wire.current!.fromId);+ if (!from) return null;+ const a = outPort(from);+ return <path className="mg-wire-live" d={bezier(a.x, a.y, cursor.x, cursor.y)} />;+ })()}+ </svg>++ {graph.nodes.map((n) => {+ const spec = NODE_SPECS[n.type];+ const h = HEADER_H + Math.max(spec.inputs.length, 1) * ROW_H + spec.params.length * ROW_H;+ return (+ <div+ key={n.id}+ className={`mg-node${selected === n.id ? ' sel' : ''}`}+ style={{ left: nodeX(n), top: nodeY(n), width: NODE_W, minHeight: h }}+ onPointerDown={(e) => { e.stopPropagation(); setSelected(n.id); }}+ >+ <div+ className="mg-node-head"+ onPointerDown={(e) => {+ e.stopPropagation();+ setSelected(n.id);+ const p = toCanvas(e.clientX, e.clientY);+ drag.current = { id: n.id, offX: p.x - nodeX(n), offY: p.y - nodeY(n), before: graph };+ }}+ >+ {spec.label}+ </div>++ {/* Output port (right edge, at the header row). */}+ {spec.output && (+ <span+ className="mg-port out"+ style={{ top: HEADER_H / 2, background: TYPE_COLOR[spec.output] }}+ title={spec.output}+ onPointerDown={(e) => { e.stopPropagation(); wire.current = { fromId: n.id }; setCursor(toCanvas(e.clientX, e.clientY)); }}+ />+ )}++ {/* Input ports + rows. Click a wired input to disconnect it. */}+ {spec.inputs.map((port) => (+ <div className="mg-row" key={port.name} style={{ height: ROW_H }}>+ <span+ className="mg-port in"+ style={{ top: '50%', background: TYPE_COLOR[port.type] }}+ title={port.type}+ onPointerDown={(e) => {+ e.stopPropagation();+ if (n.inputs?.[port.name]) MaterialGraphDocument.edit('Disconnect', (d) => Object.assign(d, disconnect(d, n.id, port.name)));+ }}+ />+ <span className="mg-row-label">{port.name}</span>+ </div>+ ))}++ {/* Node literal params (constColor / constFloat / textureSample). */}+ {spec.params.map((pf) => (+ <div className="mg-param" key={pf.key} style={{ height: ROW_H }}>+ <span className="mg-row-label">{pf.label}</span>+ {pf.kind === 'color' && (+ <ColorControl value={rgbaToHex((n.params?.value as number[]) ?? [1, 1, 1, 1])} onChange={(hex) => setNodeParam(n.id, 'value', hexToRgba(hex))} />+ )}+ {pf.kind === 'float' && (+ <NumField value={typeof n.params?.value === 'number' ? n.params.value : 0} onCommit={(v) => setNodeParam(n.id, 'value', v)} />+ )}+ {pf.kind === 'texture' && (+ <span className="mg-texname">{String(n.params?.name ?? '')}</span>+ )}+ </div>+ ))}+ </div>+ );+ })}+ </div>+ </div>+ );+}++// The input port nearest (@p x,@p y) within a small radius — the connect-drop hit test.+function nearestInputPort(graph: MaterialGraph, x: number, y: number): { nodeId: string; slot: string } | null {+ let best: { nodeId: string; slot: string } | null = null;+ let bestD2 = 18 * 18;+ for (const n of graph.nodes) {+ const inputs = NODE_SPECS[n.type].inputs;+ for (let i = 0; i < inputs.length; i++) {+ const p = inPort(n, i);+ const d2 = (p.x - x) ** 2 + (p.y - y) ** 2;+ if (d2 < bestD2) {+ bestD2 = d2;+ best = { nodeId: n.id, slot: inputs[i].name };+ }+ }+ }+ return best;+}diff --git a/desktop/src/panels/Viewport.tsx b/desktop/src/panels/Viewport.tsxindex be61cc45a..719b1ff42 100644--- a/desktop/src/panels/Viewport.tsx+++ b/desktop/src/panels/Viewport.tsx@@ -4,7 +4,7 @@ import { useEffect, useMemo, useRef, useState, useSyncExternalStore } from 'reacimport type { PointerEvent as ReactPointerEvent, DragEvent as ReactDragEvent, ReactNode } from 'react';import {MousePointer2, Move, RotateCw, Scale3d, Grid3x3, Eye, Frame,- Camera, Check, ChevronDown, Loader2, TriangleAlert, type LucideIcon,+ Camera, Check, ChevronDown, Loader2, TriangleAlert, Lightbulb, type LucideIcon,} from 'lucide-react';import { useEditorStore } from '@/store/editorStore';import { useSelection } from '@/store/selectionStore';@@ -220,6 +220,13 @@ export function Viewport() {() => (engine.status === 'ready' ? ViewportController.cameraIds() : []),[structRev, engine.status],);+ // Light2D entities don't render in edit mode — draw each as a gizmo (icon + reach+ // circle + direction), positioned by the same per-frame rAF as the camera gizmos.+ const lightRefs = useRef(new Map<number, HTMLDivElement | null>());+ const lightIds = useMemo(+ () => (engine.status === 'ready' ? ViewportController.light2DIds() : []),+ [structRev, engine.status],+ );// Mount the live engine canvas into the stage; it survives panel re-docking.useEffect(() => {@@ -316,6 +323,51 @@ export function Viewport() {wrap.style.opacity = '0';}}++ // Light2D gizmos — icon at the light, dashed reach circle (Point/Spot), direction+ // line (Directional/Spot), all tinted by the light color. Edit mode + gizmos on.+ for (const [lid, wrap] of lightRefs.current) {+ if (!wrap) continue;+ const lg = camsOn ? ViewportController.getLightGizmo(lid) : null;+ if (lg) {+ wrap.style.opacity = '1';+ wrap.style.color = lg.color;+ wrap.style.transform = `translate(${lg.cx}px, ${lg.cy}px)`;+ const circle = wrap.querySelector('.lg-radius') as SVGCircleElement | null;+ if (circle) {+ circle.setAttribute('r', String(lg.radiusPx));+ circle.style.opacity = lg.radiusPx > 0 ? '0.6' : '0';+ }+ const dir = wrap.querySelector('.lg-dir') as SVGLineElement | null;+ if (dir) {+ const hasDir = lg.sdx !== 0 || lg.sdy !== 0;+ const len = lg.kind === 3 ? Math.max(lg.radiusPx, 28) : 38;+ dir.setAttribute('x2', String(lg.sdx * len));+ dir.setAttribute('y2', String(lg.sdy * len));+ dir.style.opacity = hasDir ? '0.9' : '0';+ }+ // Spot (kind 3): two cone-edge lines at ±half-angle around the aim, out to the reach.+ const cone1 = wrap.querySelector('.lg-cone1') as SVGLineElement | null;+ const cone2 = wrap.querySelector('.lg-cone2') as SVGLineElement | null;+ for (const [line, sign] of [[cone1, 1], [cone2, -1]] as const) {+ if (!line) continue;+ if (lg.kind === 3 && (lg.sdx !== 0 || lg.sdy !== 0)) {+ const a = sign * lg.coneHalf;+ const ca = Math.cos(a);+ const sa = Math.sin(a);+ const ex = (lg.sdx * ca - lg.sdy * sa) * lg.radiusPx;+ const ey = (lg.sdx * sa + lg.sdy * ca) * lg.radiusPx;+ line.setAttribute('x2', String(ex));+ line.setAttribute('y2', String(ey));+ line.style.opacity = '0.55';+ } else {+ line.style.opacity = '0';+ }+ }+ } else {+ wrap.style.opacity = '0';+ }+ }};raf = requestAnimationFrame(tick);return () => cancelAnimationFrame(raf);@@ -490,6 +542,27 @@ export function Viewport() {</div>))}+ {/* Scene-light gizmos (icon + reach circle + direction); positioned by the rAF. */}+ {lightIds.map((id) => (+ <div+ key={id}+ ref={(el) => {+ if (el) lightRefs.current.set(id, el);+ else lightRefs.current.delete(id);+ }}+ className="viewport__light-gizmo"+ aria-hidden="true"+ >+ <Lightbulb className="viewport__light-icon" size={14} strokeWidth={1.9} />+ <svg className="viewport__light-svg" width="0" height="0" overflow="visible" aria-hidden="true">+ <circle className="lg-radius" cx="0" cy="0" r="0" />+ <line className="lg-dir" x1="0" y1="0" x2="0" y2="0" />+ <line className="lg-cone1" x1="0" y1="0" x2="0" y2="0" />+ <line className="lg-cone2" x1="0" y1="0" x2="0" y2="0" />+ </svg>+ </div>+ ))}+{/* Play In Viewport: the realm iframe fills the stage; a thin badge marks PIE. */}{playInViewport && (<div className="viewport__play">diff --git a/desktop/src/project/ProjectStore.ts b/desktop/src/project/ProjectStore.tsindex 8620c5f01..3c6482b65 100644--- a/desktop/src/project/ProjectStore.ts+++ b/desktop/src/project/ProjectStore.ts@@ -389,6 +389,13 @@ class ProjectStoreImpl {return r.materialHandles.get(path) ?? r.fontHandles.get(path) ?? 0;}+ /** The live material handle a scene's sprites use for @p path (from the last scene+ * preload), or 0 if the material isn't loaded in the current scene. The Material Editor+ * uses it to push live edits onto the running material so the viewport reflects them. */+ materialHandle(path: string): number {+ return this.lastAssetResult?.materialHandles.get(path) ?? 0;+ }+/** Load a `.esprefab` asset (PrefabData) by ref, cached. The scene load-expand* / save-collapse path resolves prefab instances through this. */private async loadPrefabAsset(ref: string): Promise<PrefabData | null> {diff --git a/desktop/src/project/assetOpen.ts b/desktop/src/project/assetOpen.tsindex de14d862c..c316fe67c 100644--- a/desktop/src/project/assetOpen.ts+++ b/desktop/src/project/assetOpen.ts@@ -12,6 +12,8 @@ import { ProjectStore } from './ProjectStore';import { EditorHistory } from '@/engine/EditorHistory';import { openAnimationClip } from '@/timeline/openClip';import { openTileset } from '@/tileset/openTileset';+import { openMaterial } from '@/material/openMaterial';+import { openMaterialGraph } from '@/material/openMaterialGraph';/** Open action per asset type; types absent here aren't double-click-openable. */export const ASSET_OPEN: Partial<Record<AssetType, (path: string, name: string) => void>> = {@@ -22,4 +24,6 @@ export const ASSET_OPEN: Partial<Record<AssetType, (path: string, name: string)},animation: (path) => void openAnimationClip(path),tileset: (path) => void openTileset(path),+ material: (path) => void openMaterial(path),+ materialgraph: (path) => void openMaterialGraph(path),};diff --git a/desktop/src/project/assetTypes.ts b/desktop/src/project/assetTypes.tsindex c6be13642..bf46dc2de 100644--- a/desktop/src/project/assetTypes.ts+++ b/desktop/src/project/assetTypes.ts@@ -13,7 +13,7 @@*/import {Folder, Film, Image, FileImage, PersonStanding, Music,- Component, Blend, FileCode2, Clapperboard, Grid3x3, File,+ Component, Blend, FileCode2, Clapperboard, Grid3x3, File, Workflow,type LucideIcon,} from 'lucide-react';import type { AssetType } from '@/types';@@ -41,6 +41,7 @@ export const ASSET_TYPES: Record<AssetType, AssetTypeDef> = {// .esmaterial is the real extension (the SDK MaterialAssetLoader only loads it);// .esmat is tolerated as a legacy alias (cf. electron/importAssets.ts).material: { extensions: ['esmaterial', 'esmat'], badge: 'MAT', icon: Blend, tint: '#c0917a' },+ materialgraph: { extensions: ['esmatgraph'], badge: 'MGR', icon: Workflow, tint: '#c0917a' },script: { extensions: ['ts', 'js'], badge: 'TS', icon: FileCode2, tint: '#93a3bf' },// Unified animation clip (.esanim) + legacy multi-track timeline (.estimeline).animation: { extensions: ['esanim', 'estimeline'], badge: 'ANM', icon: Clapperboard, tint: '#9bb39a' },diff --git a/desktop/src/theme/app.css b/desktop/src/theme/app.cssindex 4a670382f..fcd49c3f7 100644--- a/desktop/src/theme/app.css+++ b/desktop/src/theme/app.css@@ -645,6 +645,49 @@background: rgba(76, 143, 214, 0.04);}+/* Light2D gizmo: the wrap is translated to the light (rAF); icon + SVG draw at its origin,+ tinted by the wrap's `color` (set to the light color) via currentColor. */+.viewport__light-gizmo {+ position: absolute;+ left: 0;+ top: 0;+ z-index: 2;+ pointer-events: none;+ will-change: transform;+ transition: opacity 0.1s;+}+.viewport__light-icon {+ position: absolute;+ left: 0;+ top: 0;+ margin: -7px 0 0 -7px;+ filter: drop-shadow(0 0 2px rgba(0, 0, 0, 0.8));+}+.viewport__light-svg {+ position: absolute;+ left: 0;+ top: 0;+ overflow: visible;+}+.viewport__light-svg .lg-radius {+ fill: none;+ stroke: currentColor;+ stroke-width: 1.5;+ stroke-dasharray: 5 4;+}+.viewport__light-svg .lg-dir {+ stroke: currentColor;+ stroke-width: 2;+ stroke-linecap: round;+}+.viewport__light-svg .lg-cone1,+.viewport__light-svg .lg-cone2 {+ stroke: currentColor;+ stroke-width: 1.25;+ stroke-dasharray: 4 3;+ stroke-linecap: round;+}+.viewport__overlay {position: absolute;display: flex;diff --git a/desktop/src/theme/content.css b/desktop/src/theme/content.cssindex d4717974c..d9aad05bd 100644--- a/desktop/src/theme/content.css+++ b/desktop/src/theme/content.css@@ -57,8 +57,7 @@.cb-rename { width: 100%; min-width: 0; font: inherit; color: var(--text); background: var(--inset); border: 1px solid var(--acc); border-radius: var(--r-xs); padding: 1px 4px; outline: none; text-align: center; }.lr .cb-rename { text-align: left; }-/* Hover metadata card (UE5-style quick-glance; non-interactive). */-.cb-tip { position: fixed; z-index: 135; min-width: 180px; max-width: 340px; padding: 8px 10px; background: var(--srf-3); border: 1px solid var(--border-line); border-radius: var(--r-md); box-shadow: var(--shadow-3); pointer-events: none; font-size: var(--fs-xs); }+/* Asset hover-card body — rendered inside the shared `.tooltip` container. */.cb-tip-name { font-weight: 600; color: var(--text); margin-bottom: 6px; word-break: break-word; }.cb-tip-row { display: flex; gap: 10px; line-height: 1.7; }.cb-tip-row .k { width: 70px; flex-shrink: 0; color: var(--text-mute); }diff --git a/desktop/src/theme/material.css b/desktop/src/theme/material.cssnew file mode 100644index 000000000..4b60eb493--- /dev/null+++ b/desktop/src/theme/material.css@@ -0,0 +1,56 @@+/* =============================================================================+ @file material.css+ @brief Material editing in the unified Details inspector. A `.esmaterial` is+ edited inline by the shared .insp/.comp/.prop machinery (inspector.css) — there+ is no bespoke panel; only these two material-specific notes have their own style.+ ========================================================================== */++.mat-preview { display: flex; justify-content: center; padding: 10px; }+/* The "material ball" thumbnail (engine offscreen render-to-texture). A checker backdrop+ reveals alpha; the canvas is drawn into via putImageData each edit. */+.mat-thumb {+ width: 96px;+ height: 96px;+ border-radius: 6px;+ border: 1px solid var(--border-line);+ background-image:+ linear-gradient(45deg, var(--srf-3) 25%, transparent 25%),+ linear-gradient(-45deg, var(--srf-3) 25%, transparent 25%),+ linear-gradient(45deg, transparent 75%, var(--srf-3) 75%),+ linear-gradient(-45deg, transparent 75%, var(--srf-3) 75%);+ background-size: 12px 12px;+ background-position: 0 0, 0 6px, 6px -6px, -6px 0;+ background-color: var(--srf-2);+}+.mat-sync { padding: 4px 10px; font-size: var(--fs-2xs); color: var(--text-mute); border-bottom: 1px solid var(--border); flex-shrink: 0; }+.mat-hint { padding: 8px 10px; font-size: var(--fs-xs); color: var(--text-mute); }++/* ── Material Graph node editor (P5b) ─────────────────────────────────────── */+.panel.mg { display: flex; flex-direction: column; min-height: 0; height: 100%; }+.mg-bar { position: relative; display: flex; align-items: center; gap: 8px; height: 34px; flex-shrink: 0; padding: 0 10px; border-bottom: 1px solid var(--border); background: var(--srf-2); }+.mg-bar .mg-add, .mg-bar .mg-del { display: inline-flex; align-items: center; gap: 4px; height: 22px; padding: 0 8px; background: var(--srf-3); border: 1px solid var(--border-line); border-radius: var(--r-sm); color: var(--text); cursor: pointer; }+.mg-bar .mg-add:hover, .mg-bar .mg-del:hover { background: var(--srf-4); }+.mg-title { display: inline-flex; align-items: center; gap: 6px; font-size: var(--fs-sm); color: var(--text); }+.mg-dot { color: var(--acc-hi); font-size: 10px; }+.mg-palette { position: absolute; top: 32px; left: 10px; z-index: 10; display: flex; flex-direction: column; min-width: 130px; padding: 4px; background: var(--srf-2); border: 1px solid var(--border-line); border-radius: var(--r-sm); box-shadow: 0 6px 18px rgba(0, 0, 0, 0.4); }+.mg-palette button { text-align: left; padding: 5px 8px; background: none; border: none; border-radius: var(--r-sm); color: var(--text); cursor: pointer; font-size: var(--fs-xs); }+.mg-palette button:hover { background: var(--srf-4); }++.mg-canvas { position: relative; flex: 1; min-height: 0; overflow: auto; background-color: var(--srf-1); background-image: radial-gradient(circle, var(--border) 1px, transparent 1px); background-size: 20px 20px; }+.mg-wires { position: absolute; top: 0; left: 0; width: 3000px; height: 3000px; pointer-events: none; overflow: visible; }+.mg-wires path { fill: none; stroke: var(--text-mute); stroke-width: 2; }+.mg-wires path.mg-wire-live { stroke: var(--acc); stroke-dasharray: 5 4; opacity: 0.8; }++.mg-node { position: absolute; background: var(--srf-2); border: 1px solid var(--border-line); border-radius: 6px; box-shadow: 0 2px 8px rgba(0, 0, 0, 0.35); user-select: none; }+.mg-node.sel { border-color: var(--acc); box-shadow: 0 0 0 1px var(--acc), 0 2px 8px rgba(0, 0, 0, 0.4); }+.mg-node-head { height: 28px; display: flex; align-items: center; padding: 0 10px; font-size: var(--fs-xs); font-weight: 600; color: var(--text); border-bottom: 1px solid var(--border); border-radius: 6px 6px 0 0; cursor: grab; background: var(--srf-3); }+.mg-node .mg-row, .mg-node .mg-param { position: relative; display: flex; align-items: center; gap: 6px; padding: 0 10px; }+.mg-row-label { font-size: var(--fs-2xs); color: var(--text-dim); }+.mg-param { gap: 6px; }+.mg-param .mg-row-label { min-width: 38px; }+.mg-texname { font-size: var(--fs-2xs); color: var(--text-mute); font-family: var(--font-mono, monospace); }++.mg-port { position: absolute; width: 11px; height: 11px; border-radius: 50%; border: 2px solid var(--srf-1); cursor: crosshair; }+.mg-port.out { right: -6px; transform: translateY(-50%); }+.mg-port.in { left: -6px; transform: translateY(-50%); }+.mg-port:hover { box-shadow: 0 0 0 3px rgba(255, 255, 255, 0.15); }diff --git a/desktop/src/theme/menus.css b/desktop/src/theme/menus.cssindex 951de3a72..526a27042 100644--- a/desktop/src/theme/menus.css+++ b/desktop/src/theme/menus.css@@ -41,6 +41,23 @@.ctx-item.danger:hover .ci { color: var(--error); }.ctx-sep { height: 1px; background: var(--border-line); margin: 4px 6px; }+/* ════════════════════════ Hover tooltip ════════════════════════ */+/* The floating container for the shared <Tooltip> primitive (asset hover card,+ etc.). Non-interactive and below the context menu so a menu always wins. */+.tooltip {+ position: fixed;+ z-index: 135;+ min-width: 180px;+ max-width: 340px;+ padding: 8px 10px;+ background: var(--srf-3);+ border: 1px solid var(--border-line);+ border-radius: var(--r-md);+ box-shadow: var(--shadow-3);+ pointer-events: none;+ font-size: var(--fs-xs);+}+/* ════════════════════════ Add Component picker ════════════════════════ */.ac-scrim {position: fixed;diff --git a/desktop/src/types.ts b/desktop/src/types.tsindex fe1ffc860..339b11c34 100644--- a/desktop/src/types.ts+++ b/desktop/src/types.ts@@ -136,6 +136,7 @@ export type AssetType =| 'audio'| 'prefab'| 'material'+ | 'materialgraph'| 'script'| 'animation'| 'tileset'diff --git a/desktop/tests/shader-reflect.test.ts b/desktop/tests/shader-reflect.test.tsnew file mode 100644index 000000000..a22df8a90--- /dev/null+++ b/desktop/tests/shader-reflect.test.ts@@ -0,0 +1,72 @@+// SPDX-License-Identifier: LicenseRef-PolyForm-Noncommercial-1.0.0+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team+import { describe, it, expect } from 'vitest';+import { reflectEsshader } from '../src/material/shaderReflect';++const SRC = `+#pragma shader "ParamTest"+#pragma version 300 es+#pragma domain Unlit2D+#pragma param u_strength float default(1) range(0,4) ui(slider)+#pragma param u_tint color default(1,0.5,0.25,1)+#pragma param u_offset vec2 default(3,4)+#pragma param u_noise texture default(white)++#pragma vertex+void main() {}+#pragma end+#pragma fragment+void main() {}+#pragma end+`;++describe('reflectEsshader', () => {+ it('parses domain and all params', () => {+ const r = reflectEsshader(SRC);+ expect(r.domain).toBe('Unlit2D');+ expect(r.params.map((p) => p.name)).toEqual(['u_strength', 'u_tint', 'u_offset', 'u_noise']);+ });++ it('parses type, default, range and ui for a scalar', () => {+ const p = reflectEsshader(SRC).params.find((x) => x.name === 'u_strength')!;+ expect(p.type).toBe('float');+ expect(p.default).toEqual([1]);+ expect(p.range).toEqual({ min: 0, max: 4 });+ expect(p.ui).toBe('slider');+ expect(p.displayName).toBe('Strength'); // u_ stripped + capitalized+ });++ it('parses a color default as 4 components', () => {+ const p = reflectEsshader(SRC).params.find((x) => x.name === 'u_tint')!;+ expect(p.type).toBe('color');+ expect(p.default).toEqual([1, 0.5, 0.25, 1]);+ });++ it('parses a vec2 default', () => {+ const p = reflectEsshader(SRC).params.find((x) => x.name === 'u_offset')!;+ expect(p.type).toBe('vec2');+ expect(p.default).toEqual([3, 4]);+ });++ it('parses a texture param with a default texture hint (not in components)', () => {+ const p = reflectEsshader(SRC).params.find((x) => x.name === 'u_noise')!;+ expect(p.type).toBe('texture');+ expect(p.default).toEqual([]);+ expect(p.defaultTexture).toBe('white');+ });++ it('applies type defaults when no default() clause is given', () => {+ const r = reflectEsshader('#pragma param u_a float\n#pragma param u_c color\n#pragma vertex\n#pragma end\n#pragma fragment\n#pragma end');+ expect(r.params.find((p) => p.name === 'u_a')!.default).toEqual([0]);+ expect(r.params.find((p) => p.name === 'u_c')!.default).toEqual([0, 0, 0, 1]); // color alpha defaults to 1+ });++ it('ignores malformed/unknown-type params and non-pragma lines', () => {+ const r = reflectEsshader('#pragma param u_x notatype\n#pragma param onlyname\nuniform float x;\n#pragma param u_ok float');+ expect(r.params.map((p) => p.name)).toEqual(['u_ok']);+ });++ it('returns the default domain when none is declared', () => {+ expect(reflectEsshader('#pragma param u_a float').domain).toBe('Unlit2D');+ });+});diff --git a/sdk/src/asset/MaterialLoader.ts b/sdk/src/asset/MaterialLoader.tsdeleted file mode 100644index 4371f0fc9..000000000--- a/sdk/src/asset/MaterialLoader.ts+++ /dev/null@@ -1,111 +0,0 @@-// SPDX-License-Identifier: LicenseRef-PolyForm-Noncommercial-1.0.0-// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team-/**- * @file MaterialLoader.ts- * @brief Material asset loading and caching- */--import type { MaterialAssetData, MaterialHandle, ShaderHandle } from '../material';-import { Material } from '../material';-import { platformReadTextFile, platformFileExists } from '../platform';-import { AsyncCache } from './AsyncCache';--// =============================================================================-// Types-// =============================================================================--export interface LoadedMaterial {- handle: MaterialHandle;- shaderHandle: ShaderHandle;- path: string;-}--export interface ShaderLoader {- load(path: string): Promise<ShaderHandle>;- get(path: string): ShaderHandle | undefined;-}--// =============================================================================-// MaterialLoader-// =============================================================================--export class MaterialLoader {- private cache_ = new AsyncCache<LoadedMaterial>();- private shaderLoader_: ShaderLoader;- private basePath_: string;-- constructor(shaderLoader: ShaderLoader, basePath: string = '') {- this.shaderLoader_ = shaderLoader;- this.basePath_ = basePath;- }-- async load(path: string): Promise<LoadedMaterial> {- return this.cache_.getOrLoad(path, () => this.loadInternal(path), 0);- }-- get(path: string): LoadedMaterial | undefined {- return this.cache_.get(path);- }-- has(path: string): boolean {- return this.cache_.has(path);- }-- release(path: string): void {- const loaded = this.cache_.get(path);- if (loaded) {- Material.release(loaded.handle);- this.cache_.delete(path);- }- }-- releaseAll(): void {- for (const loaded of this.cache_.values()) {- Material.release(loaded.handle);- }- this.cache_.clear();- }-- private async loadInternal(path: string): Promise<LoadedMaterial> {- const fullPath = this.resolvePath(path);- const exists = await platformFileExists(fullPath);- if (!exists) {- throw new Error(`Material file not found: ${fullPath}`);- }-- const content = await platformReadTextFile(fullPath);- if (!content) {- throw new Error(`Failed to read material file: ${fullPath}`);- }-- const data = JSON.parse(content) as MaterialAssetData;- if (data.type !== 'material') {- throw new Error(`Invalid material file type: ${data.type}`);- }-- const shaderPath = this.resolveShaderPath(path, data.shader);- const shaderHandle = await this.shaderLoader_.load(shaderPath);- const materialHandle = Material.createFromAsset(data, shaderHandle);-- return {- handle: materialHandle,- shaderHandle,- path,- };- }-- private resolvePath(path: string): string {- if (path.startsWith('/') || path.startsWith('http')) {- return path;- }- return this.basePath_ ? `${this.basePath_}/${path}` : path;- }-- private resolveShaderPath(materialPath: string, shaderPath: string): string {- if (shaderPath.startsWith('/') || shaderPath.startsWith('http') || shaderPath.startsWith('assets/')) {- return shaderPath;- }- const dir = materialPath.substring(0, materialPath.lastIndexOf('/'));- return dir ? `${dir}/${shaderPath}` : shaderPath;- }-}diff --git a/sdk/src/asset/index.ts b/sdk/src/asset/index.tsindex 9e101fbf9..98a1bb740 100644--- a/sdk/src/asset/index.ts+++ b/sdk/src/asset/index.ts@@ -9,7 +9,6 @@ export {export { AsyncCache } from './AsyncCache';export { Assets, AssetPlugin, assetPlugin, type AssetsData } from './AssetPlugin';export { decodeImageBitmap, decodeImagePixels, imageBitmapOptions, type DecodedPixels } from './imageDecode';-export { MaterialLoader, type LoadedMaterial, type ShaderLoader } from './MaterialLoader';export { AssetRefCounter, type AssetRefInfo } from './AssetRefCounter';export { Assets as AssetsImpl, type AssetsOptions, type AssetBundle, type SceneAssetResult, type MissingAsset } from './Assets';diff --git a/sdk/src/asset/loaders/MaterialAssetLoader.ts b/sdk/src/asset/loaders/MaterialAssetLoader.tsindex d2680c118..e340ce708 100644--- a/sdk/src/asset/loaders/MaterialAssetLoader.ts+++ b/sdk/src/asset/loaders/MaterialAssetLoader.ts@@ -5,9 +5,6 @@ import type { MaterialAssetData, ShaderHandle } from '../../material';import { Material } from '../../material';import { AsyncCache } from '../AsyncCache';-const ES_SHADER_VERTEX_RE = /#pragma\s+vertex\s*([\s\S]*?)#pragma\s+end/;-const ES_SHADER_FRAGMENT_RE = /#pragma\s+fragment\s*([\s\S]*?)#pragma\s+end/;-export class MaterialAssetLoader implements AssetLoader<MaterialResult> {readonly type = 'material';readonly extensions = ['.esmaterial'];@@ -23,13 +20,47 @@ export class MaterialAssetLoader implements AssetLoader<MaterialResult> {throw new Error(`Invalid material file type: ${data.type} at ${path}`);}- const shaderPath = resolveShaderPath(path, data.shader);- const shaderHandle = await this.loadShader(shaderPath, ctx);+ // A material instance (`instanceOf`) inherits its parent's shader + state; load the+ // parent first, then build the instance from the asset's diffs. Parent shader resolution+ // and uniforms come from the parent material, so no shader is loaded here.+ if (data.instanceOf) {+ const parentPath = resolveRelativePath(path, data.instanceOf);+ const parent = await this.load(parentPath, ctx);+ const handle = Material.createFromAsset(data, 0, parent.handle);+ await this.applyTextureProps(handle, data, path, ctx);+ return { handle, shaderHandle: parent.shaderHandle };+ }++ // Enabled static switches select the shader permutation (compiled once per switch-set).+ const features = enabledSwitches(data.switches);+ const shaderPath = resolveRelativePath(path, data.shader);+ const shaderHandle = await this.loadShader(shaderPath, features, ctx);const handle = Material.createFromAsset(data, shaderHandle);+ await this.applyTextureProps(handle, data, path, ctx);return { handle, shaderHandle };}+ // A texture param is a string property (an asset ref); scalar/vector params are+ // numbers/objects (handled by createFromAsset). Load each texture and bind it to its param.+ private async applyTextureProps(+ handle: number,+ data: MaterialAssetData,+ matPath: string,+ ctx: LoadContext,+ ): Promise<void> {+ for (const [name, value] of Object.entries(data.properties)) {+ if (typeof value !== 'string') continue;+ const texPath = resolveRelativePath(matPath, value);+ try {+ const tex = await ctx.loadTexture(texPath);+ Material.setUniform(handle, name, Material.tex(tex.handle));+ } catch {+ // Missing texture: leave the param unbound (it samples whatever is at the unit).+ }+ }+ }+unload(asset: MaterialResult): void {Material.release(asset.handle);}@@ -38,29 +69,40 @@ export class MaterialAssetLoader implements AssetLoader<MaterialResult> {this.shaderCache_.clearAll();}- private async loadShader(path: string, ctx: LoadContext): Promise<ShaderHandle> {- const cached = this.shaderCache_.get(path);+ // One compiled program per (shader path, enabled-switch set) — distinct switch sets are+ // distinct permutations, so the cache key folds the sorted features in.+ private async loadShader(path: string, features: string[], ctx: LoadContext): Promise<ShaderHandle> {+ const cacheKey = features.length ? `${path}#${features.join('|')}` : path;+ const cached = this.shaderCache_.get(cacheKey);if (cached !== undefined) return cached;- return this.shaderCache_.getOrLoad(path, async () => {+ return this.shaderCache_.getOrLoad(cacheKey, async () => {const buildPath = ctx.catalog.getBuildPath(path);const content = await ctx.loadText(buildPath);- const vertexMatch = content.match(ES_SHADER_VERTEX_RE);- const fragmentMatch = content.match(ES_SHADER_FRAGMENT_RE);-- if (!vertexMatch?.[1] || !fragmentMatch?.[1]) {- throw new Error(`Invalid shader format: ${path}`);+ // Compile through ShaderParser (engine-side): assembles the stages + the enabled+ // switch permutation, generates the std140 MaterialConstants block from #pragma param,+ // and registers the layout so the material's parameters reach the GPU.+ const handle = Material.compileShader(content, features);+ if (!handle) {+ throw new Error(`Failed to compile material shader: ${path}`);}-- return Material.createShader(vertexMatch[1].trim(), fragmentMatch[1].trim());+ return handle;});}}-function resolveShaderPath(materialPath: string, shaderPath: string): string {- if (shaderPath.startsWith('/') || shaderPath.startsWith('http') || shaderPath.startsWith('assets/')) {- return shaderPath;+// The enabled static switches, sorted for a stable permutation cache key.+function enabledSwitches(switches: Record<string, boolean> | undefined): string[] {+ if (!switches) return [];+ return Object.entries(switches).filter(([, on]) => on).map(([name]) => name).sort();+}++// Resolve a ref (shader or parent material) relative to the referencing material's directory;+// absolute / http / assets-rooted refs pass through unchanged.+function resolveRelativePath(fromPath: string, ref: string): string {+ if (ref.startsWith('/') || ref.startsWith('http') || ref.startsWith('assets/')) {+ return ref;}- const dir = materialPath.substring(0, materialPath.lastIndexOf('/'));- return dir ? `${dir}/${shaderPath}` : shaderPath;+ const dir = fromPath.substring(0, fromPath.lastIndexOf('/'));+ return dir ? `${dir}/${ref}` : ref;}diff --git a/sdk/src/component.generated.ts b/sdk/src/component.generated.tsindex e7fd675ba..b5819b81b 100644--- a/sdk/src/component.generated.ts+++ b/sdk/src/component.generated.ts@@ -12,7 +12,7 @@ import type { AssetFieldType } from './scene';* getAbiLayoutHash(); BuiltinBridge.connect() compares them and refuses to* run on mismatch, because mismatched offsets read the wrong heap bytes.*/-export const ABI_LAYOUT_HASH = 'ffbf3c8be66d1354';+export const ABI_LAYOUT_HASH = '2896a68ab5ef40b7';export interface AssetFieldMeta {field: string;@@ -168,6 +168,22 @@ export const COMPONENT_META: Record<string, ComponentMetaEntry> = {colorFields: [],animatableFields: [],},+ Light2D: {+ defaults: {+ type: 0,+ color: { r: 1, g: 1, b: 1, a: 1 },+ intensity: 1,+ radius: 200,+ direction: { x: 0, y: 0 },+ innerAngle: 30,+ outerAngle: 45,+ enabled: true,+ },+ assetFields: [],+ entityFields: [],+ colorFields: ['color'],+ animatableFields: ['color.r', 'color.g', 'color.b', 'color.a', 'intensity', 'radius', 'innerAngle', 'outerAngle'],+ },Parent: {defaults: {entity: 0,diff --git a/sdk/src/component.ts b/sdk/src/component.tsindex c6b50b1c2..e63966012 100644--- a/sdk/src/component.ts+++ b/sdk/src/component.ts@@ -455,6 +455,26 @@ export const ShapeType = {export type ShapeType = (typeof ShapeType)[keyof typeof ShapeType];+export const Light2DType = {+ Point: 0,+ Directional: 1,+ Ambient: 2,+ Spot: 3,+} as const;++export type Light2DType = (typeof Light2DType)[keyof typeof Light2DType];++export interface Light2DData {+ type: number;+ color: Color;+ intensity: number;+ radius: number;+ direction: Vec2;+ innerAngle: number;+ outerAngle: number;+ enabled: boolean;+}+export interface ShapeRendererData {shapeType: number;color: Color;@@ -596,6 +616,20 @@ export const ShapeRenderer = defineBuiltin<ShapeRendererData>('ShapeRenderer',});+export const Light2D = defineBuiltin<Light2DData>('Light2D',+ metaDefaults<Light2DData>('Light2D'),+ {+ fields: {+ type: { enum: enumOptions(Light2DType) },+ intensity: { min: 0 },+ radius: { min: 0 },+ direction: { advanced: true },+ innerAngle: { min: 0, max: 180, unit: '°', advanced: true },+ outerAngle: { min: 0, max: 180, unit: '°', advanced: true },+ },+ }+);+export const Camera = defineBuiltin<CameraData>('Camera',metaDefaults<CameraData>('Camera', {projectionType: ProjectionType.Orthographic,diff --git a/sdk/src/core-content.ts b/sdk/src/core-content.tsindex 1bcf2e284..4c990c126 100644--- a/sdk/src/core-content.ts+++ b/sdk/src/core-content.ts@@ -48,7 +48,6 @@ export {Assets,AssetPlugin,assetPlugin,- MaterialLoader,AssetRefCounter,decodeImageBitmap,decodeImagePixels,@@ -60,8 +59,6 @@ export {type AssetsData,type TextureInfo,type SpineLoadResult,- type LoadedMaterial,- type ShaderLoader,type AssetRefInfo,} from './asset';diff --git a/sdk/src/core-render.ts b/sdk/src/core-render.tsindex 4c0785d47..d95d2e0dd 100644--- a/sdk/src/core-render.ts+++ b/sdk/src/core-render.ts@@ -72,8 +72,8 @@ export {ShaderSources,initMaterialAPI,shutdownMaterialAPI,- registerMaterialCallback,isTextureRef,+ CullMode,type ShaderHandle,type MaterialHandle,type MaterialOptions,@@ -82,6 +82,24 @@ export {type TextureRef,} from './material';+export {+ compileMaterialGraph,+ newMaterialGraph,+ addNode,+ moveNode,+ connect,+ disconnect,+ removeNode,+ NODE_SPECS,+ type MaterialGraph,+ type MaterialGraphNode,+ type GraphNodeType,+ type GraphType,+ type NodeSpec,+ type NodePort,+ type NodeParamSpec,+} from './materialGraph';+// =============================================================================// Geometry API// =============================================================================diff --git a/sdk/src/core-runtime.ts b/sdk/src/core-runtime.tsindex b2cbfc6f9..83065ba12 100644--- a/sdk/src/core-runtime.ts+++ b/sdk/src/core-runtime.ts@@ -85,6 +85,8 @@ export {Sprite,ShapeRenderer,ShapeType,+ Light2D,+ Light2DType,Camera,Canvas,Velocity,@@ -103,6 +105,7 @@ export {type WorldTransformData,type SpriteData,type ShapeRendererData,+ type Light2DData,type CameraData,type CanvasData,type VelocityData,diff --git a/sdk/src/ecs/ptrAccessors.generated.ts b/sdk/src/ecs/ptrAccessors.generated.tsindex 71c9fc2bd..b1f661c63 100644--- a/sdk/src/ecs/ptrAccessors.generated.ts+++ b/sdk/src/ecs/ptrAccessors.generated.ts@@ -405,6 +405,58 @@ export function createInteractableData(): InteractablePtrData {};}+export interface Light2DPtrData {+ type: number;+ color: Color;+ intensity: number;+ radius: number;+ direction: Vec2;+ innerAngle: number;+ outerAngle: number;+ enabled: boolean;+}++export function fillLight2D(+ f32: Float32Array, u32: Uint32Array, u8: Uint8Array,+ ptr: number, out: Light2DPtrData,+): void {+ out.type = u32[ptr >> 2] | 0;+ const color_ = out.color; color_.r = f32[(ptr + 4) >> 2]; color_.g = f32[((ptr + 4) >> 2) + 1]; color_.b = f32[((ptr + 4) >> 2) + 2]; color_.a = f32[((ptr + 4) >> 2) + 3];+ out.intensity = f32[(ptr + 20) >> 2];+ out.radius = f32[(ptr + 24) >> 2];+ const direction_ = out.direction; direction_.x = f32[(ptr + 28) >> 2]; direction_.y = f32[((ptr + 28) >> 2) + 1];+ out.innerAngle = f32[(ptr + 36) >> 2];+ out.outerAngle = f32[(ptr + 40) >> 2];+ out.enabled = u8[ptr + 44] !== 0;+}++export function writeLight2D(+ f32: Float32Array, u32: Uint32Array, u8: Uint8Array,+ ptr: number, data: Light2DPtrData,+): void {+ u32[ptr >> 2] = data.type | 0;+ f32[(ptr + 4) >> 2] = data.color.r; f32[((ptr + 4) >> 2) + 1] = data.color.g; f32[((ptr + 4) >> 2) + 2] = data.color.b; f32[((ptr + 4) >> 2) + 3] = data.color.a;+ f32[(ptr + 20) >> 2] = data.intensity;+ f32[(ptr + 24) >> 2] = data.radius;+ f32[(ptr + 28) >> 2] = data.direction.x; f32[((ptr + 28) >> 2) + 1] = data.direction.y;+ f32[(ptr + 36) >> 2] = data.innerAngle;+ f32[(ptr + 40) >> 2] = data.outerAngle;+ u8[ptr + 44] = data.enabled ? 1 : 0;+}++export function createLight2DData(): Light2DPtrData {+ return {+ type: 0,+ color: { r: 0, g: 0, b: 0, a: 0 },+ intensity: 0,+ radius: 0,+ direction: { x: 0, y: 0 },+ innerAngle: 0,+ outerAngle: 0,+ enabled: false,+ };+}+export interface ParticleEmitterPtrData {rate: number;burstCount: number;@@ -1184,6 +1236,7 @@ export const PTR_ACCESSORS: Record<string, PtrAccessor<any>> = {CircleCollider: { fill: fillCircleCollider, write: writeCircleCollider, create: createCircleColliderData },FlexContainer: { fill: fillFlexContainer, write: writeFlexContainer, create: createFlexContainerData },Interactable: { fill: fillInteractable, write: writeInteractable, create: createInteractableData },+ Light2D: { fill: fillLight2D, write: writeLight2D, create: createLight2DData },ParticleEmitter: { fill: fillParticleEmitter, write: writeParticleEmitter, create: createParticleEmitterData },RigidBody: { fill: fillRigidBody, write: writeRigidBody, create: createRigidBodyData },SegmentCollider: { fill: fillSegmentCollider, write: writeSegmentCollider, create: createSegmentColliderData },diff --git a/sdk/src/material.ts b/sdk/src/material.tsindex 82b1f4bed..db452d0c3 100644--- a/sdk/src/material.ts+++ b/sdk/src/material.ts@@ -11,7 +11,6 @@ import { CoreApiBridge } from './CoreApiBridge';import { requireResourceManager } from './resourceManager';import type { Vec2, Vec3, Vec4 } from './types';import { BlendMode } from './blend';-import { log } from './logger';export type { Vec2, Vec3, Vec4 } from './types';@@ -68,19 +67,43 @@ export function classifyUniformArity(value: Exclude<UniformValue, TextureRef>):return { arity: 2, values: [value.x, value.y, 0, 0] };}+/** Triangle culling mode; mirrors the engine's CullMode. */+export enum CullMode {+ None = 0,+ Back = 1,+ Front = 2,+}+export interface MaterialOptions {shader: ShaderHandle;uniforms?: Record<string, UniformValue>;blendMode?: BlendMode;depthTest?: boolean;+ depthWrite?: boolean;+ cull?: CullMode;+ /** Enabled static switches (#pragma switch) for the record; the shader permutation is+ * chosen at compile time (see Material.compileShader). Stored for inspection/serialization. */+ switches?: Record<string, boolean>;}export interface MaterialAssetData {version: string;type: 'material';shader: string;- blendMode: number;- depthTest: boolean;+ // Render state is optional so an instance can serialize only its overrides; a base+ // material writes all of them. Absent fields fall back to the engine defaults on load.+ blendMode?: number;+ depthTest?: boolean;+ depthWrite?: boolean;+ cull?: number;+ /**+ * Parent material asset ref — present on a material instance (UE MaterialInstanceConstant).+ * The shader and any non-overridden render state are inherited from the parent; `shader`+ * is then ignored and `properties` carries only the overridden parameters (the diff).+ */+ instanceOf?: string;+ /** Enabled static switches (#pragma switch) — selects the shader permutation at load. */+ switches?: Record<string, boolean>;properties: Record<string, unknown>;}@@ -89,6 +112,20 @@ export interface MaterialData {uniforms: Map<string, UniformValue>;blendMode: BlendMode;depthTest: boolean;+ depthWrite: boolean;+ cull: CullMode;+ /** Enabled static switches (the shader permutation was chosen for these at compile time). */+ switches: Record<string, boolean>;+ /**+ * Instance parenting (UE MaterialInstanceConstant): when set, this material inherits the+ * parent's shader + render state + params, and only its own diffs are stored — `uniforms`+ * holds just the overridden params, and `overrides` names the overridden render-state+ * fields ('blendMode' | 'depthTest' | 'depthWrite' | 'cull'). Undefined on a base material.+ */+ parent?: MaterialHandle;+ overrides: Set<string>;+ // Immediate-mode mesh uniform cache (draw.ts): the encoded uniform buffer is rebuilt+ // only when dirty_ (a uniform changed). Distinct from the batch render path's material UBO.dirty_: boolean;cachedBuffer_: Float32Array | null;cachedIdx_: number;@@ -102,6 +139,8 @@ const bridge = new CoreApiBridge('material');let module: ESEngineModule | null = null;let nextMaterialId = 1;const materials = new Map<MaterialHandle, MaterialData>();+// Reverse index parent -> instances, so editing a base material re-flushes its instances.+const childrenOf = new Map<MaterialHandle, Set<MaterialHandle>>();// =============================================================================// Initialization@@ -110,23 +149,110 @@ const materials = new Map<MaterialHandle, MaterialData>();export function initMaterialAPI(wasmModule: ESEngineModule): void {bridge.connect(wasmModule);module = bridge.module;- registerMaterialCallback();}export function shutdownMaterialAPI(): void {- if (uniformBuffer !== 0 && module) {- module._free(uniformBuffer);- uniformBuffer = 0;- }materials.clear();+ childrenOf.clear();nextMaterialId = 1;- materialCallbackRegistered = false;- encodedNameCache.clear();- encoder = null;bridge.disconnect();module = null;}+// Pack the render-state flags the engine store expects: depthTest (bit 0), depthWrite+// (bit 1), CullMode (bits 2-3).+function materialFlags(depthTest: boolean, depthWrite: boolean, cull: CullMode): number {+ return (depthTest ? 0x1 : 0) | (depthWrite ? 0x2 : 0) | ((cull & 0x3) << 2);+}++function registerChild(parent: MaterialHandle, child: MaterialHandle): void {+ let set = childrenOf.get(parent);+ if (!set) { set = new Set(); childrenOf.set(parent, set); }+ set.add(child);+}++function unregisterChild(parent: MaterialHandle, child: MaterialHandle): void {+ childrenOf.get(parent)?.delete(child);+}++// Push one param value into the engine material store: texture refs bind to a sampler unit,+// scalar/vector values pack into the std140 MaterialConstants UBO (both by the offset/unit the+// shader's #pragma param reflection assigns). A no-op engine-side for unknown params.+function pushUniform(handle: MaterialHandle, name: string, value: UniformValue): void {+ if (!module) return;+ if (isTextureRef(value)) {+ module.setMaterialTexture(handle, name, value.textureId);+ return;+ }+ const { arity, values } = classifyUniformArity(value);+ module.setMaterialUniform(handle, name, arity, values[0], values[1], values[2], values[3]);+}++interface ResolvedMaterial {+ shader: ShaderHandle;+ blendMode: BlendMode;+ depthTest: boolean;+ depthWrite: boolean;+ cull: CullMode;+ uniforms: Map<string, UniformValue>;+}++// Flatten an instance chain to its effective material: the parent's values with this+// material's overrides applied (uniforms by key, render state by `overrides`). Defensive+// against a missing parent (e.g. a released base) — falls back to the material's own values.+function resolveMaterial(handle: MaterialHandle): ResolvedMaterial | null {+ const data = materials.get(handle);+ if (!data) return null;+ const parent = data.parent !== undefined ? resolveMaterial(data.parent) : null;+ if (!parent) {+ return {+ shader: data.shader, blendMode: data.blendMode, depthTest: data.depthTest,+ depthWrite: data.depthWrite, cull: data.cull, uniforms: new Map(data.uniforms),+ };+ }+ const uniforms = parent.uniforms; // fresh map from the recursive call+ for (const [k, v] of data.uniforms) uniforms.set(k, v); // instance overrides win+ return {+ shader: parent.shader, // instances inherit the shader+ blendMode: data.overrides.has('blendMode') ? data.blendMode : parent.blendMode,+ depthTest: data.overrides.has('depthTest') ? data.depthTest : parent.depthTest,+ depthWrite: data.overrides.has('depthWrite') ? data.depthWrite : parent.depthWrite,+ cull: data.overrides.has('cull') ? data.cull : parent.cull,+ uniforms,+ };+}++// Push a material's flattened state to the engine, then re-flush every instance of it — so a+// base edit propagates to non-overriding children. The single push point for create + edits.+function flushMaterial(handle: MaterialHandle): void {+ const resolved = resolveMaterial(handle);+ if (resolved && module) {+ module.defineMaterial(handle, resolved.shader, resolved.blendMode,+ materialFlags(resolved.depthTest, resolved.depthWrite, resolved.cull));+ for (const [name, value] of resolved.uniforms) pushUniform(handle, name, value);+ }+ const kids = childrenOf.get(handle);+ if (kids) for (const child of kids) flushMaterial(child);+}++// Convert a .esmaterial `properties` map (JSON numbers / colors / vectors) into typed+// UniformValues. Keyed by the value's shape: {r,g,b,a} -> color vec4, {x,y,z,w}/{x,y,z}/{x,y}.+function parseAssetProperties(properties: Record<string, unknown>): Record<string, UniformValue> {+ const uniforms: Record<string, UniformValue> = {};+ for (const [key, value] of Object.entries(properties)) {+ if (typeof value === 'number') {+ uniforms[key] = value;+ } else if (typeof value === 'object' && value !== null) {+ const obj = value as Record<string, number>;+ if ('a' in obj) uniforms[key] = { x: obj.r ?? 0, y: obj.g ?? 0, z: obj.b ?? 0, w: obj.a ?? 0 };+ else if ('w' in obj) uniforms[key] = { x: obj.x ?? 0, y: obj.y ?? 0, z: obj.z ?? 0, w: obj.w ?? 0 };+ else if ('z' in obj) uniforms[key] = { x: obj.x ?? 0, y: obj.y ?? 0, z: obj.z ?? 0 };+ else if ('y' in obj) uniforms[key] = { x: obj.x ?? 0, y: obj.y ?? 0 };+ }+ }+ return uniforms;+}+// =============================================================================// Shader API// =============================================================================@@ -164,6 +290,10 @@ export const Material = {uniforms: new Map(),blendMode: options.blendMode ?? BlendMode.Normal,depthTest: options.depthTest ?? false,+ depthWrite: options.depthWrite ?? true,+ cull: options.cull ?? CullMode.None,+ switches: options.switches ? { ...options.switches } : {},+ overrides: new Set(),dirty_: true,cachedBuffer_: null,cachedIdx_: 0,@@ -176,9 +306,33 @@ export const Material = {}materials.set(handle, data);+ flushMaterial(handle);return handle;},+ /**+ * Compiles a `.esshader` material shader through the engine's ShaderParser, which+ * generates the std140 MaterialConstants block from its `#pragma param` declarations and+ * registers the param layout. Use this (not createShader) for materials whose parameters+ * should reach the GPU. Returns a shader handle, or 0 on failure.+ */+ compileShader(esshaderSource: string, features: string[] = []): ShaderHandle {+ return module?.compileEsshader(esshaderSource, features.join(',')) ?? 0;+ },++ /** Gets an enabled static switch (false when unset). */+ getSwitch(material: MaterialHandle, name: string): boolean {+ return materials.get(material)?.switches[name] ?? false;+ },++ /** Sets a static switch on the record. The shader permutation is chosen at compile time,+ * so a change takes effect when the material's shader is next (re)compiled — callers that+ * need it live recompile the shader with the new switch set. */+ setSwitch(material: MaterialHandle, name: string, on: boolean): void {+ const data = materials.get(material);+ if (data) data.switches[name] = on;+ },+/*** Gets material data by handle.* @param material Material handle@@ -197,9 +351,10 @@ export const Material = {setUniform(material: MaterialHandle, name: string, value: UniformValue): void {const data = materials.get(material);if (data) {+ // On an instance, the local uniforms map *is* the override set (presence = override).data.uniforms.set(name, value);- data.dirty_ = true;- module?.invalidateMaterialCache(material);+ data.dirty_ = true; // immediate-mode mesh path re-encodes its uniform cache.+ flushMaterial(material); // batch path: re-flatten + push (+ propagate to instances).}},@@ -210,8 +365,7 @@ export const Material = {* @returns Uniform value or undefined*/getUniform(material: MaterialHandle, name: string): UniformValue | undefined {- const data = materials.get(material);- return data?.uniforms.get(name);+ return resolveMaterial(material)?.uniforms.get(name);},/**@@ -223,7 +377,8 @@ export const Material = {const data = materials.get(material);if (data) {data.blendMode = mode;- module?.invalidateMaterialCache(material);+ if (data.parent !== undefined) data.overrides.add('blendMode');+ flushMaterial(material);}},@@ -233,8 +388,7 @@ export const Material = {* @returns Blend mode*/getBlendMode(material: MaterialHandle): BlendMode {- const data = materials.get(material);- return data?.blendMode ?? BlendMode.Normal;+ return resolveMaterial(material)?.blendMode ?? BlendMode.Normal;},/**@@ -246,7 +400,28 @@ export const Material = {const data = materials.get(material);if (data) {data.depthTest = enabled;- module?.invalidateMaterialCache(material);+ if (data.parent !== undefined) data.overrides.add('depthTest');+ flushMaterial(material);+ }+ },++ /** Enables/disables depth writes (default on, matching the engine's 2D state). */+ setDepthWrite(material: MaterialHandle, enabled: boolean): void {+ const data = materials.get(material);+ if (data) {+ data.depthWrite = enabled;+ if (data.parent !== undefined) data.overrides.add('depthWrite');+ flushMaterial(material);+ }+ },++ /** Sets the triangle culling mode. */+ setCull(material: MaterialHandle, cull: CullMode): void {+ const data = materials.get(material);+ if (data) {+ data.cull = cull;+ if (data.parent !== undefined) data.overrides.add('cull');+ flushMaterial(material);}},@@ -256,8 +431,7 @@ export const Material = {* @returns Shader handle*/getShader(material: MaterialHandle): ShaderHandle {- const data = materials.get(material);- return data?.shader ?? 0;+ return resolveMaterial(material)?.shader ?? 0;},/**@@ -265,8 +439,11 @@ export const Material = {* @param material Material handle*/release(material: MaterialHandle): void {+ const data = materials.get(material);+ if (data?.parent !== undefined) unregisterChild(data.parent, material);+ childrenOf.delete(material); // orphaned instances fall back to their own values (resolve is defensive)materials.delete(material);- module?.invalidateMaterialCache(material);+ module?.undefineMaterial(material);},/**@@ -278,49 +455,74 @@ export const Material = {return materials.has(material);},+ /**+ * Render a material to an offscreen @p w×@p h target and return its pixels (a "material ball"+ * thumbnail). Reuses the real viewport render path — a unit quad lit by one directional light+ * — so the preview matches how the material looks in-scene. Null if the engine isn't ready.+ */+ renderPreview(material: MaterialHandle, w: number, h: number): ImageData | null {+ if (!module) return null;+ module.renderer_renderMaterialPreview(material, w, h);+ const size = module.renderer_getPreviewSize();+ const pw = module.renderer_getPreviewWidth();+ const ph = module.renderer_getPreviewHeight();+ if (size === 0 || pw === 0 || ph === 0) return null;+ const pixels = new Uint8ClampedArray(module.HEAPU8.buffer, module.renderer_getPreviewPtr(), size);+ // GL reads bottom-up; flip rows so the thumbnail is upright.+ const flipped = new Uint8ClampedArray(size);+ const rowBytes = pw * 4;+ for (let y = 0; y < ph; y++) {+ flipped.set(pixels.subarray(y * rowBytes, (y + 1) * rowBytes), (ph - 1 - y) * rowBytes);+ }+ return new ImageData(flipped, pw, ph);+ },+releaseAll(): void {+ if (module) {+ for (const handle of materials.keys()) module.undefineMaterial(handle);+ }materials.clear();- module?.clearMaterialCache();+ childrenOf.clear();},/**- * Creates a material from asset data.- * @param data Material asset data (properties object)- * @param shaderHandle Pre-loaded shader handle- * @returns Material handle+ * Creates a material from asset data. When @p parentHandle is given (the asset's+ * `instanceOf` resolved to a loaded parent), builds a Material Instance carrying only the+ * asset's overrides — `properties` and any present render-state fields. Otherwise builds a+ * base material on @p shaderHandle.*/- createFromAsset(data: MaterialAssetData, shaderHandle: ShaderHandle): MaterialHandle {- const uniforms: Record<string, UniformValue> = {};-- for (const [key, value] of Object.entries(data.properties)) {- if (typeof value === 'number') {- uniforms[key] = value;- } else if (typeof value === 'object' && value !== null) {- const obj = value as Record<string, number>;- if ('a' in obj) {- uniforms[key] = { x: obj.r ?? 0, y: obj.g ?? 0, z: obj.b ?? 0, w: obj.a ?? 0 };- } else if ('w' in obj) {- uniforms[key] = { x: obj.x ?? 0, y: obj.y ?? 0, z: obj.z ?? 0, w: obj.w ?? 0 };- } else if ('z' in obj) {- uniforms[key] = { x: obj.x ?? 0, y: obj.y ?? 0, z: obj.z ?? 0 };- } else if ('y' in obj) {- uniforms[key] = { x: obj.x ?? 0, y: obj.y ?? 0 };- }- }+ createFromAsset(data: MaterialAssetData, shaderHandle: ShaderHandle, parentHandle?: MaterialHandle): MaterialHandle {+ const uniforms = parseAssetProperties(data.properties);++ if (parentHandle !== undefined && parentHandle !== 0) {+ const handle = this.createInstance(parentHandle);+ for (const [key, value] of Object.entries(uniforms)) this.setUniform(handle, key, value);+ // Present render-state fields are the instance's overrides (absent = inherited).+ if (data.blendMode !== undefined) this.setBlendMode(handle, data.blendMode as BlendMode);+ if (data.depthTest !== undefined) this.setDepthTest(handle, data.depthTest);+ if (data.depthWrite !== undefined) this.setDepthWrite(handle, data.depthWrite);+ if (data.cull !== undefined) this.setCull(handle, data.cull as CullMode);+ return handle;}return this.create({shader: shaderHandle,uniforms,- blendMode: data.blendMode as BlendMode ?? BlendMode.Normal,+ blendMode: (data.blendMode as BlendMode) ?? BlendMode.Normal,depthTest: data.depthTest ?? false,+ depthWrite: data.depthWrite ?? true,+ cull: (data.cull as CullMode) ?? CullMode.None,+ switches: data.switches,});},/**- * Creates a material instance that shares the shader with source.- * @param source Source material handle- * @returns New material handle with copied settings+ * Creates a material instance (UE MaterialInstanceConstant): it inherits @p source's+ * shader, render state and parameters, and stores only the diffs you later set on it.+ * Editing the parent propagates to every non-overriding instance. Use this for cheap+ * variants ("the same material, but red") instead of duplicating the whole material.+ * @param source Parent material (a base material or another instance)+ * @returns New instance handle*/createInstance(source: MaterialHandle): MaterialHandle {const sourceData = materials.get(source);@@ -330,16 +532,25 @@ export const Material = {const handle = nextMaterialId++;const data: MaterialData = {+ // Render-state fields are placeholders (resolve inherits from the parent unless an+ // override is set); `uniforms` holds only this instance's overrides, empty at first.shader: sourceData.shader,- uniforms: new Map(sourceData.uniforms),+ uniforms: new Map(),blendMode: sourceData.blendMode,depthTest: sourceData.depthTest,+ depthWrite: sourceData.depthWrite,+ cull: sourceData.cull,+ switches: {}, // instance inherits the parent's shader permutation (switch override = follow-up)+ parent: source,+ overrides: new Set(),dirty_: true,cachedBuffer_: null,cachedIdx_: 0,};materials.set(handle, data);+ registerChild(source, handle);+ flushMaterial(handle);return handle;},@@ -349,23 +560,41 @@ export const Material = {* @param shaderPath Shader file path for asset reference* @returns Material asset data*/- toAssetData(material: MaterialHandle, shaderPath: string): MaterialAssetData | null {+ toAssetData(material: MaterialHandle, shaderPath: string, parentPath?: string): MaterialAssetData | null {const data = materials.get(material);if (!data) return null;+ // An instance serializes as a diff: instanceOf + only its overridden params (the local+ // uniforms map) and overridden render-state. A base writes its full state.+ const isInstance = data.parent !== undefined && parentPath !== undefined;+const properties: Record<string, unknown> = {};- for (const [key, value] of data.uniforms) {- properties[key] = value;+ const localUniforms = isInstance ? data.uniforms : resolveMaterial(material)?.uniforms ?? data.uniforms;+ for (const [key, value] of localUniforms) properties[key] = value;++ if (isInstance) {+ const asset: MaterialAssetData = {+ version: '1.0', type: 'material', shader: shaderPath, instanceOf: parentPath, properties,+ };+ if (data.overrides.has('blendMode')) asset.blendMode = data.blendMode;+ if (data.overrides.has('depthTest')) asset.depthTest = data.depthTest;+ if (data.overrides.has('depthWrite')) asset.depthWrite = data.depthWrite;+ if (data.overrides.has('cull')) asset.cull = data.cull;+ return asset;}- return {+ const asset: MaterialAssetData = {version: '1.0',type: 'material',shader: shaderPath,blendMode: data.blendMode,depthTest: data.depthTest,+ depthWrite: data.depthWrite,+ cull: data.cull,properties,};+ if (Object.keys(data.switches).length > 0) asset.switches = { ...data.switches };+ return asset;},/**@@ -374,8 +603,8 @@ export const Material = {* @returns Map of uniform names to values*/getUniforms(material: MaterialHandle): Map<string, UniformValue> {- const data = materials.get(material);- return data ? new Map(data.uniforms) : new Map();+ // Resolved (flattened) uniforms — an instance reports inherited + overridden params.+ return resolveMaterial(material)?.uniforms ?? new Map();},tex(textureId: number, slot?: number): TextureRef {@@ -383,114 +612,6 @@ export const Material = {},};-// =============================================================================-// Material Callback Registration-// =============================================================================--let materialCallbackRegistered = false;-let uniformBuffer: number = 0;-const UNIFORM_BUFFER_SIZE = 16384;-// Cap the cache so apps that generate many unique uniform names (e.g. per--// instance shader variants) don't leak Uint8Arrays for the whole session.-const ENCODED_NAME_CACHE_LIMIT = 256;-const encodedNameCache = new Map<string, Uint8Array>();-let encoder: TextEncoder | null = null;--function ensureUniformBuffer(): number {- if (uniformBuffer === 0 && module) {- uniformBuffer = module._malloc(UNIFORM_BUFFER_SIZE);- }- return uniformBuffer;-}--function serializeUniforms(uniforms: Map<string, UniformValue>): { ptr: number; count: number } {- const bufferPtr = ensureUniformBuffer();- if (bufferPtr === 0 || !module) return { ptr: 0, count: 0 };-- let offset = 0;- let count = 0;- const heap8 = module.HEAPU8;- const heap32 = module.HEAPU32;- const heapF32 = module.HEAPF32;-- for (const [name, value] of uniforms) {- if (isTextureRef(value)) continue;-- let nameBytes = encodedNameCache.get(name);- if (!nameBytes) {- if (!encoder) encoder = new TextEncoder();- nameBytes = encoder.encode(name);- if (encodedNameCache.size >= ENCODED_NAME_CACHE_LIMIT) {- // Evict the oldest entry (Map preserves insertion order).- const oldest = encodedNameCache.keys().next().value;- if (oldest !== undefined) encodedNameCache.delete(oldest);- }- encodedNameCache.set(name, nameBytes);- }- const nameLen = nameBytes.length;- const namePadded = Math.ceil(nameLen / 4) * 4;- const requiredBytes = 4 + namePadded + 4 + 16;-- if (offset + requiredBytes > UNIFORM_BUFFER_SIZE) {- log.warn('material', `uniform buffer full (${offset}/${UNIFORM_BUFFER_SIZE} bytes), skipping remaining uniforms`);- break;- }-- heap32[(bufferPtr + offset) >> 2] = nameLen;- offset += 4;-- heap8.set(nameBytes, bufferPtr + offset);- offset += namePadded;-- // Type codes in this layout are zero-indexed (0=float, 1=vec2,- // 2=vec3, 3=vec4); classifyUniformArity returns arity 1..4 so we- // subtract one to match.- const { arity, values } = classifyUniformArity(value as Exclude<UniformValue, TextureRef>);- heap32[(bufferPtr + offset) >> 2] = arity - 1;- offset += 4;-- for (let i = 0; i < 4; i++) {- heapF32[(bufferPtr + offset) >> 2] = values[i];- offset += 4;- }-- count++;- }-- return { ptr: bufferPtr, count };-}--export function registerMaterialCallback(): void {- if (!module || materialCallbackRegistered) return;-- const callback = (- materialId: number,- outShaderIdPtr: number,- outBlendModePtr: number,- outUniformBufferPtr: number,- outUniformCountPtr: number- ) => {- const data = materials.get(materialId);- if (!data) {- module!.HEAPU32[outShaderIdPtr >> 2] = 0;- module!.HEAPU32[outBlendModePtr >> 2] = 0;- module!.HEAPU32[outUniformBufferPtr >> 2] = 0;- module!.HEAPU32[outUniformCountPtr >> 2] = 0;- return;- }-- module!.HEAPU32[outShaderIdPtr >> 2] = data.shader;- module!.HEAPU32[outBlendModePtr >> 2] = data.blendMode;-- const { ptr, count } = serializeUniforms(data.uniforms);- module!.HEAPU32[outUniformBufferPtr >> 2] = ptr;- module!.HEAPU32[outUniformCountPtr >> 2] = count;- };-- module.materialDataProvider = callback;- materialCallbackRegistered = true;-}-// =============================================================================// Built-in Shader Sources// =============================================================================diff --git a/sdk/src/materialGraph.ts b/sdk/src/materialGraph.tsnew file mode 100644index 000000000..7ac9281b1--- /dev/null+++ b/sdk/src/materialGraph.ts@@ -0,0 +1,374 @@+// SPDX-License-Identifier: LicenseRef-PolyForm-Noncommercial-1.0.0+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team+/**+ * @file materialGraph.ts+ * @brief Material Graph → `.esshader` compiler (REARCH_MATERIAL §4.4, P5).+ * @details A material graph is a **visual frontend that generates a `.esshader`**, not a parallel+ * pipeline: `compileMaterialGraph` emits GLSL whose backend is the same ShaderParser+ * path (`compileEsshader` → MaterialConstants block + sampler units + variants). Const /+ * texture nodes become `#pragma param`s, so a graph's inputs are ordinary, reflected,+ * editable material parameters — one reflection model for hand-written and graph shaders+ * alike. The vertex stage is fixed (2D bakes the transform into the batch vertices); the+ * programmable surface is the fragment, which this compiler builds by topologically+ * walking the node DAG from the output.+ */++/** A node's GLSL output type. Determines how it combines and how it promotes to fragColor. */+export type GraphType = 'float' | 'vec2' | 'vec3' | 'vec4';++export type GraphNodeType =+ | 'output' // the root: its `color` input becomes fragColor+ | 'uv' // v_texCoord+ | 'vertexColor' // v_color (the sprite's per-instance tint)+ | 'constFloat' // a scalar material param (#pragma param ... float)+ | 'constColor' // an RGBA material param (#pragma param ... color)+ | 'textureSample' // sample a texture material param at a UV (#pragma param ... texture)+ | 'multiply'+ | 'add'+ | 'lerp'+ | 'oneMinus' // 1 - x (invert a mask)+ | 'saturate'; // clamp(x, 0, 1)++export interface MaterialGraphNode {+ id: string;+ type: GraphNodeType;+ /** Node literals: param `name`, scalar/color `value`, texture `default`. */+ params?: Record<string, unknown>;+ /** Input slot → source node id (e.g. multiply: `{ a, b }`; textureSample: `{ uv? }`). */+ inputs?: Record<string, string>;+ /** Editor canvas position (px). Ignored by the compiler — layout only. */+ x?: number;+ y?: number;+}++export interface MaterialGraph {+ name?: string;+ /** Material domain (Unlit2D default; Lit2D etc. flow through unchanged). */+ domain?: string;+ /** Id of the `output` node — the compile root. */+ output: string;+ nodes: MaterialGraphNode[];+}++const TYPE_RANK: Record<GraphType, number> = { float: 1, vec2: 2, vec3: 3, vec4: 4 };++/** The wider of two types (vecN op float broadcasts in GLSL; mixing vec2 with vec4 is invalid). */+function widen(a: GraphType, b: GraphType): GraphType {+ return TYPE_RANK[a] >= TYPE_RANK[b] ? a : b;+}++/** Promote an expression of @p type to a vec4 (for fragColor / mix endpoints). */+function toVec4(expr: string, type: GraphType): string {+ switch (type) {+ case 'vec4': return expr;+ case 'vec3': return `vec4(${expr}, 1.0)`;+ case 'vec2': return `vec4(${expr}, 0.0, 1.0)`;+ case 'float': return `vec4(vec3(${expr}), 1.0)`;+ }+}++/**+ * Compile a material graph into a `.esshader` source string (assembled by the engine's+ * ShaderParser like any hand-written shader). Throws on a missing node/input, a cycle, an+ * unknown node type, or an output root that isn't an `output` node.+ */+export function compileMaterialGraph(graph: MaterialGraph): string {+ const nodes = new Map(graph.nodes.map((n) => [n.id, n] as const));+ const memo = new Map<string, { expr: string; type: GraphType }>();+ const visiting = new Set<string>();+ const params: string[] = [];+ const body: string[] = [];+ let tmp = 0;++ const paramName = (n: MaterialGraphNode) =>+ typeof n.params?.name === 'string' ? (n.params.name as string) : `u_${n.id}`;++ function emit(id: string): { expr: string; type: GraphType } {+ const cached = memo.get(id);+ if (cached) return cached;+ if (visiting.has(id)) throw new Error(`material graph: cycle through node "${id}"`);+ const n = nodes.get(id);+ if (!n) throw new Error(`material graph: missing node "${id}"`);+ visiting.add(id);++ const input = (slot: string): { expr: string; type: GraphType } => {+ const src = n.inputs?.[slot];+ if (!src) throw new Error(`material graph: node "${id}" (${n.type}) missing input "${slot}"`);+ return emit(src);+ };++ let out: { expr: string; type: GraphType };+ switch (n.type) {+ case 'uv':+ out = { expr: 'v_texCoord', type: 'vec2' };+ break;+ case 'vertexColor':+ out = { expr: 'v_color', type: 'vec4' };+ break;+ case 'constFloat': {+ const name = paramName(n);+ const v = typeof n.params?.value === 'number' ? n.params.value : 0;+ params.push(`#pragma param ${name} float default(${v})`);+ out = { expr: name, type: 'float' };+ break;+ }+ case 'constColor': {+ const name = paramName(n);+ const c = Array.isArray(n.params?.value) ? (n.params!.value as number[]) : [1, 1, 1, 1];+ params.push(`#pragma param ${name} color default(${c.slice(0, 4).join(',')})`);+ out = { expr: name, type: 'vec4' };+ break;+ }+ case 'textureSample': {+ const name = paramName(n);+ const def = typeof n.params?.default === 'string' ? n.params.default : 'white';+ params.push(`#pragma param ${name} texture default(${def})`);+ const uv = n.inputs?.uv ? input('uv').expr : 'v_texCoord';+ const t = `n${tmp++}`;+ body.push(`vec4 ${t} = texture(${name}, ${uv});`);+ out = { expr: t, type: 'vec4' };+ break;+ }+ case 'multiply':+ case 'add': {+ const a = input('a');+ const b = input('b');+ const op = n.type === 'multiply' ? '*' : '+';+ const ty = widen(a.type, b.type);+ const t = `n${tmp++}`;+ body.push(`${ty} ${t} = ${a.expr} ${op} ${b.expr};`);+ out = { expr: t, type: ty };+ break;+ }+ case 'lerp': {+ const a = input('a');+ const b = input('b');+ const f = input('t');+ const t = `n${tmp++}`;+ body.push(`vec4 ${t} = mix(${toVec4(a.expr, a.type)}, ${toVec4(b.expr, b.type)}, ${f.expr});`);+ out = { expr: t, type: 'vec4' };+ break;+ }+ case 'oneMinus':+ case 'saturate': {+ // Both are single-input and preserve type — GLSL broadcasts the scalar over any genType.+ const a = input('x');+ const t = `n${tmp++}`;+ const expr = n.type === 'oneMinus' ? `1.0 - ${a.expr}` : `clamp(${a.expr}, 0.0, 1.0)`;+ body.push(`${a.type} ${t} = ${expr};`);+ out = { expr: t, type: a.type };+ break;+ }+ case 'output': {+ const c = input('color');+ out = { expr: toVec4(c.expr, c.type), type: 'vec4' };+ break;+ }+ default:+ throw new Error(`material graph: unknown node type "${(n as MaterialGraphNode).type}"`);+ }++ visiting.delete(id);+ memo.set(id, out);+ return out;+ }++ const root = nodes.get(graph.output);+ if (!root || root.type !== 'output') {+ throw new Error('material graph: `output` must reference an "output" node');+ }+ const result = emit(graph.output);++ const name = graph.name ?? 'Graph';+ const domain = graph.domain ?? 'Unlit2D';+ const paramBlock = params.length ? params.join('\n') + '\n' : '';+ const bodyBlock = body.map((l) => ' ' + l).join('\n');++ return `#pragma shader "${name}"+#pragma version 300 es+#pragma domain ${domain}+${paramBlock}+#pragma vertex+layout(location = 0) in vec2 a_position;+layout(location = 1) in vec4 a_color;+layout(location = 2) in vec2 a_texCoord;+layout(location = 3) in float a_texIndex;++layout(std140) uniform FrameConstants {+ mat4 u_projection;+};++out vec4 v_color;+out vec2 v_texCoord;++void main() {+ gl_Position = u_projection * vec4(a_position, 0.0, 1.0);+ v_color = a_color;+ v_texCoord = a_texCoord;+}+#pragma end++#pragma fragment+precision mediump float;++in vec4 v_color;+in vec2 v_texCoord;++out vec4 fragColor;++void main() {+${bodyBlock}+ fragColor = ${result.expr};+}+#pragma end+`;+}++// =============================================================================+// Editor schema + graph operations (the visual node editor, P5b)+// =============================================================================++/** A node input/output port. `type` drives the port's color hint; connections coerce freely. */+export interface NodePort {+ name: string;+ type: GraphType;+}++/** An editable node literal, surfaced as a node-inspector field. */+export interface NodeParamSpec {+ key: string;+ label: string;+ kind: 'color' | 'float' | 'texture';+}++/** Static schema for a node type — the single source the palette, ports, and node inspector+ * all read, kept beside the compiler so the editor and codegen never drift. */+export interface NodeSpec {+ label: string;+ inputs: NodePort[];+ /** Output port type, or null for the `output` sink (no output port). */+ output: GraphType | null;+ params: NodeParamSpec[];+ /** Whether the palette offers it (the singleton `output` node is not addable). */+ addable: boolean;+}++export const NODE_SPECS: Record<GraphNodeType, NodeSpec> = {+ output: { label: 'Output', inputs: [{ name: 'color', type: 'vec4' }], output: null, params: [], addable: false },+ uv: { label: 'UV', inputs: [], output: 'vec2', params: [], addable: true },+ vertexColor: { label: 'Vertex Color', inputs: [], output: 'vec4', params: [], addable: true },+ constFloat: { label: 'Float', inputs: [], output: 'float', params: [{ key: 'value', label: 'Value', kind: 'float' }], addable: true },+ constColor: { label: 'Color', inputs: [], output: 'vec4', params: [{ key: 'value', label: 'Color', kind: 'color' }], addable: true },+ textureSample: { label: 'Texture', inputs: [{ name: 'uv', type: 'vec2' }], output: 'vec4', params: [{ key: 'name', label: 'Param', kind: 'texture' }], addable: true },+ multiply: { label: 'Multiply', inputs: [{ name: 'a', type: 'vec4' }, { name: 'b', type: 'vec4' }], output: 'vec4', params: [], addable: true },+ add: { label: 'Add', inputs: [{ name: 'a', type: 'vec4' }, { name: 'b', type: 'vec4' }], output: 'vec4', params: [], addable: true },+ lerp: { label: 'Lerp', inputs: [{ name: 'a', type: 'vec4' }, { name: 'b', type: 'vec4' }, { name: 't', type: 'float' }], output: 'vec4', params: [], addable: true },+ oneMinus: { label: 'One Minus', inputs: [{ name: 'x', type: 'vec4' }], output: 'vec4', params: [], addable: true },+ saturate: { label: 'Saturate', inputs: [{ name: 'x', type: 'vec4' }], output: 'vec4', params: [], addable: true },+};++/** A default starter graph: a white texture sample straight into the output. */+export function newMaterialGraph(): MaterialGraph {+ return {+ name: 'Graph',+ output: 'out',+ nodes: [+ { id: 'tex', type: 'textureSample', x: 60, y: 120, params: { name: 'u_albedo', default: 'white' } },+ { id: 'out', type: 'output', x: 360, y: 140, inputs: { color: 'tex' } },+ ],+ };+}++const clone = (g: MaterialGraph): MaterialGraph => JSON.parse(JSON.stringify(g)) as MaterialGraph;++/** A node id unused in @p g, of the form `<type><n>`. */+function freshId(g: MaterialGraph, type: GraphNodeType): string {+ const used = new Set(g.nodes.map((n) => n.id));+ for (let i = 1; ; i++) {+ const id = `${type}${i}`;+ if (!used.has(id)) return id;+ }+}++/** Default literal params for a freshly-added node (so its #pragma param compiles). */+function defaultParams(type: GraphNodeType, id: string): Record<string, unknown> | undefined {+ switch (type) {+ case 'constFloat': return { name: `u_${id}`, value: 1 };+ case 'constColor': return { name: `u_${id}`, value: [1, 1, 1, 1] };+ case 'textureSample': return { name: `u_${id}`, default: 'white' };+ default: return undefined;+ }+}++/** Add a node of @p type at canvas (@p x,@p y); returns the new graph + the new node id. */+export function addNode(g: MaterialGraph, type: GraphNodeType, x: number, y: number): { graph: MaterialGraph; id: string } {+ const next = clone(g);+ const id = freshId(g, type);+ next.nodes.push({ id, type, x, y, params: defaultParams(type, id) });+ return { graph: next, id };+}++/** Move a node to (@p x,@p y) on the canvas (layout only). */+export function moveNode(g: MaterialGraph, id: string, x: number, y: number): MaterialGraph {+ const next = clone(g);+ const n = next.nodes.find((m) => m.id === id);+ if (n) {+ n.x = x;+ n.y = y;+ }+ return next;+}++/** Whether a path from @p fromId back to @p toId exists (so connecting them would loop). */+function reaches(g: MaterialGraph, fromId: string, toId: string): boolean {+ const byId = new Map(g.nodes.map((n) => [n.id, n] as const));+ const stack = [fromId];+ const seen = new Set<string>();+ while (stack.length) {+ const id = stack.pop()!;+ if (id === toId) return true;+ if (seen.has(id)) continue;+ seen.add(id);+ const n = byId.get(id);+ if (n?.inputs) stack.push(...Object.values(n.inputs));+ }+ return false;+}++/**+ * Connect @p fromId's output into @p toId's @p toSlot input. Rejected (returns the graph+ * unchanged) if it would create a cycle or the slot is unknown — so the canvas can't author an+ * uncompilable graph.+ */+export function connect(g: MaterialGraph, fromId: string, toId: string, toSlot: string): MaterialGraph {+ if (fromId === toId) return g;+ const to = g.nodes.find((n) => n.id === toId);+ if (!to || !NODE_SPECS[to.type].inputs.some((p) => p.name === toSlot)) return g;+ if (reaches(g, fromId, toId)) return g; // the source already depends on the target → cycle+ const next = clone(g);+ const n = next.nodes.find((m) => m.id === toId)!;+ (n.inputs ??= {})[toSlot] = fromId;+ return next;+}++/** Clear @p toId's @p toSlot input connection. */+export function disconnect(g: MaterialGraph, toId: string, toSlot: string): MaterialGraph {+ const next = clone(g);+ const n = next.nodes.find((m) => m.id === toId);+ if (n?.inputs) delete n.inputs[toSlot];+ return next;+}++/** Remove a node (and every edge into/out of it). The `output` node can't be removed. */+export function removeNode(g: MaterialGraph, id: string): MaterialGraph {+ if (g.output === id) return g;+ const next = clone(g);+ next.nodes = next.nodes.filter((n) => n.id !== id);+ for (const n of next.nodes) {+ if (!n.inputs) continue;+ for (const [slot, src] of Object.entries(n.inputs)) {+ if (src === id) delete n.inputs[slot];+ }+ }+ return next;+}diff --git a/sdk/src/ptrLayouts.generated.ts b/sdk/src/ptrLayouts.generated.tsindex e71ce4dc3..f2cd5b5bf 100644--- a/sdk/src/ptrLayouts.generated.ts+++ b/sdk/src/ptrLayouts.generated.ts@@ -117,6 +117,19 @@ export const PTR_LAYOUTS: Record<string, PtrLayout> = {{ name: 'raycastTarget', type: 'bool', offset: 2 },],},+ Light2D: {+ ptrFn: 'getLight2DPtr',+ fields: [+ { name: 'type', type: 'i32', offset: 0 },+ { name: 'color', type: 'color', offset: 4 },+ { name: 'intensity', type: 'f32', offset: 20 },+ { name: 'radius', type: 'f32', offset: 24 },+ { name: 'direction', type: 'vec2', offset: 28 },+ { name: 'innerAngle', type: 'f32', offset: 36 },+ { name: 'outerAngle', type: 'f32', offset: 40 },+ { name: 'enabled', type: 'bool', offset: 44 },+ ],+ },ParticleEmitter: {ptrFn: 'getParticleEmitterPtr',fields: [diff --git a/sdk/src/wasm.generated.ts b/sdk/src/wasm.generated.tsindex 2c9068270..892e4407c 100644--- a/sdk/src/wasm.generated.ts+++ b/sdk/src/wasm.generated.ts@@ -235,6 +235,17 @@ export interface Interactable {raycastTarget: boolean;}+export interface Light2D {+ type: number;+ color: Vec4;+ intensity: number;+ radius: number;+ direction: Vec2;+ innerAngle: number;+ outerAngle: number;+ enabled: boolean;+}+export interface Parent {entity: number;}@@ -478,6 +489,10 @@ export interface Registry {getInteractable(entity: Entity): Interactable;addInteractable(entity: Entity, component: Interactable): void;removeInteractable(entity: Entity): void;+ hasLight2D(entity: Entity): boolean;+ getLight2D(entity: Entity): Light2D;+ addLight2D(entity: Entity, component: Light2D): void;+ removeLight2D(entity: Entity): void;hasParent(entity: Entity): boolean;getParent(entity: Entity): Parent;addParent(entity: Entity, component: Parent): void;@@ -565,6 +580,7 @@ export interface ESEngineModule {CircleCollider: new () => CircleCollider;FlexContainer: new () => FlexContainer;Interactable: new () => Interactable;+ Light2D: new () => Light2D;Parent: new () => Parent;ParticleEmitter: new () => ParticleEmitter;RigidBody: new () => RigidBody;diff --git a/sdk/src/wasm.ts b/sdk/src/wasm.tsindex 7a555d049..8ed5b5c1f 100644--- a/sdk/src/wasm.ts+++ b/sdk/src/wasm.ts@@ -91,8 +91,6 @@ export interface ESEngineModule {FS: EmscriptenFS;- materialDataProvider?: (materialId: number, outShaderIdPtr: number, outBlendModePtr: number, outUniformBufferPtr: number, outUniformCountPtr: number) => void;-initRenderer(): void;initRendererWithCanvas(canvasSelector: string): boolean;initRendererWithContext(contextHandle: number): boolean;@@ -160,9 +158,19 @@ export interface ESEngineModule {entity: number, layer: number, depth: number): void;- // Material cache- invalidateMaterialCache(materialId: number): void;- clearMaterialCache(): void;+ // Material store (engine-side resolved render state, keyed by material handle).+ // flags packs depthTest (bit 0), depthWrite (bit 1), CullMode (bits 2-3).+ // Compiles a .esshader through ShaderParser (auto-generating the MaterialConstants block ++ // the enabled #pragma switch / feature permutation from featuresCsv) and registers its param+ // layout; returns the shader resource handle (0 on failure).+ compileEsshader(source: string, featuresCsv: string): number;+ defineMaterial(materialId: number, shader: number, blendMode: number, flags: number): void;+ // Packs a named param's components into the material's std140 UBO by reflected offset.+ setMaterialUniform(materialId: number, name: string, arity: number,+ v0: number, v1: number, v2: number, v3: number): void;+ // Binds a texture param to its sampler unit; textureHandle is a texture resource handle.+ setMaterialTexture(materialId: number, name: string, textureHandle: number): void;+ undefineMaterial(materialId: number): void;// ImmediateDraw APIdraw_begin(matrixPtr: number): void;@@ -322,6 +330,11 @@ export interface ESEngineModule {renderer_getSnapshotSize(): number;renderer_getSnapshotWidth(): number;renderer_getSnapshotHeight(): number;+ renderer_renderMaterialPreview(materialId: number, w: number, h: number): void;+ renderer_getPreviewPtr(): number;+ renderer_getPreviewSize(): number;+ renderer_getPreviewWidth(): number;+ renderer_getPreviewHeight(): number;// UI SystemsuiLayout_update(registry: CppRegistry, camLeft: number, camBottom: number, camRight: number, camTop: number): void;diff --git a/sdk/tests/material.test.ts b/sdk/tests/material.test.tsindex b887dce04..b6639d7e5 100644--- a/sdk/tests/material.test.ts+++ b/sdk/tests/material.test.ts@@ -7,13 +7,12 @@ import {isTextureRef,initMaterialAPI,shutdownMaterialAPI,- registerMaterialCallback,+ CullMode,} from '../src/material';import type {MaterialHandle,ShaderHandle,TextureRef,- UniformValue,MaterialAssetData,} from '../src/material';import type { ESEngineModule } from '../src/wasm';@@ -25,32 +24,20 @@ import { initResourceManager, shutdownResourceManager } from '../src/resourceMan// =============================================================================function createMaterialMockModule() {- const heapBuffer = new ArrayBuffer(1024 * 1024);-const resourceManager = {createShader: vi.fn().mockReturnValue(1),releaseShader: vi.fn(),};const mock = {- _malloc: vi.fn((_size: number) => 1024),- _free: vi.fn(),- HEAPU8: new Uint8Array(heapBuffer),- HEAPU32: new Uint32Array(heapBuffer),- HEAPF32: new Float32Array(heapBuffer),getResourceManager: vi.fn(() => resourceManager),resourceManager,- invalidateMaterialCache: vi.fn(),- clearMaterialCache: vi.fn(),- materialDataProvider: null as- | ((- materialId: number,- outShaderIdPtr: number,- outBlendModePtr: number,- outUniformBufferPtr: number,- outUniformCountPtr: number,- ) => void)- | null,+ // The engine-side material store push (replaces the old pull callback + cache).+ compileEsshader: vi.fn().mockReturnValue(7),+ defineMaterial: vi.fn(),+ setMaterialUniform: vi.fn(),+ setMaterialTexture: vi.fn(),+ undefineMaterial: vi.fn(),};return mock;@@ -58,6 +45,12 @@ function createMaterialMockModule() {type MockModule = ReturnType<typeof createMaterialMockModule>;+// Render-state flags the SDK packs for defineMaterial: depthTest (bit 0),+// depthWrite (bit 1), CullMode (bits 2-3).+function flags(depthTest: boolean, depthWrite: boolean, cull: CullMode): number {+ return (depthTest ? 0x1 : 0) | (depthWrite ? 0x2 : 0) | ((cull & 0x3) << 2);+}+// =============================================================================// Tests// =============================================================================@@ -77,29 +70,10 @@ describe('Material API', () => {});// =========================================================================- // initMaterialAPI / shutdownMaterialAPI+ // shutdownMaterialAPI// =========================================================================- describe('initMaterialAPI', () => {- it('should register material callback', () => {- expect(mock.materialDataProvider).toBeTypeOf('function');- });- });-describe('shutdownMaterialAPI', () => {- it('should free uniform buffer if allocated', () => {- const mat = Material.create({ shader: 1 as ShaderHandle });- Material.setUniform(mat, 'u_val', 1.0);-- // Trigger callback to allocate uniform buffer- if (mock.materialDataProvider) {- mock.materialDataProvider(mat, 0, 4, 8, 12);- }-- shutdownMaterialAPI();- expect(mock._free).toHaveBeenCalled();- });-it('should clear materials map', () => {const mat = Material.create({ shader: 1 as ShaderHandle });shutdownMaterialAPI();@@ -175,10 +149,23 @@ describe('Material API', () => {expect(data!.shader).toBe(42);expect(data!.blendMode).toBe(BlendMode.Normal);expect(data!.depthTest).toBe(false);- expect(data!.dirty_).toBe(true);+ expect(data!.depthWrite).toBe(true);+ expect(data!.cull).toBe(CullMode.None);expect(data!.uniforms.size).toBe(0);});+ it('should push the resolved render state to the engine store', () => {+ const h = Material.create({+ shader: 42 as ShaderHandle,+ blendMode: BlendMode.Additive,+ depthTest: true,+ cull: CullMode.Back,+ });+ expect(mock.defineMaterial).toHaveBeenCalledWith(+ h, 42, BlendMode.Additive, flags(true, true, CullMode.Back),+ );+ });+it('should accept optional uniforms', () => {const h = Material.create({shader: 1 as ShaderHandle,@@ -230,22 +217,23 @@ describe('Material API', () => {});describe('Material.release', () => {- it('should delete material and call invalidateMaterialCache', () => {+ it('should delete material and undefine it in the engine store', () => {const h = Material.create({ shader: 1 as ShaderHandle });Material.release(h);expect(Material.isValid(h)).toBe(false);- expect(mock.invalidateMaterialCache).toHaveBeenCalledWith(h);+ expect(mock.undefineMaterial).toHaveBeenCalledWith(h);});});describe('Material.releaseAll', () => {- it('should clear all materials and call clearMaterialCache', () => {+ it('should clear all materials and undefine each in the engine store', () => {const h1 = Material.create({ shader: 1 as ShaderHandle });const h2 = Material.create({ shader: 1 as ShaderHandle });Material.releaseAll();expect(Material.isValid(h1)).toBe(false);expect(Material.isValid(h2)).toBe(false);- expect(mock.clearMaterialCache).toHaveBeenCalled();+ expect(mock.undefineMaterial).toHaveBeenCalledWith(h1);+ expect(mock.undefineMaterial).toHaveBeenCalledWith(h2);});});@@ -260,16 +248,6 @@ describe('Material API', () => {expect(Material.getUniform(h, 'u_time')).toBe(3.14);});- it('should mark dirty and invalidate cache on setUniform', () => {- const h = Material.create({ shader: 1 as ShaderHandle });- const data = Material.get(h)!;- data.dirty_ = false;-- Material.setUniform(h, 'u_val', 1.0);- expect(data.dirty_).toBe(true);- expect(mock.invalidateMaterialCache).toHaveBeenCalledWith(h);- });-it('should return undefined for non-existing uniform', () => {const h = Material.create({ shader: 1 as ShaderHandle });expect(Material.getUniform(h, 'nonexistent')).toBeUndefined();@@ -306,7 +284,7 @@ describe('Material API', () => {});// =========================================================================- // BlendMode / DepthTest / Shader+ // BlendMode / DepthTest / DepthWrite / Cull / Shader// =========================================================================describe('BlendMode', () => {@@ -316,11 +294,13 @@ describe('Material API', () => {expect(Material.getBlendMode(h)).toBe(BlendMode.Multiply);});- it('should call invalidateMaterialCache on setBlendMode', () => {+ it('should push the new state on setBlendMode', () => {const h = Material.create({ shader: 1 as ShaderHandle });- mock.invalidateMaterialCache.mockClear();+ mock.defineMaterial.mockClear();Material.setBlendMode(h, BlendMode.Additive);- expect(mock.invalidateMaterialCache).toHaveBeenCalledWith(h);+ expect(mock.defineMaterial).toHaveBeenCalledWith(+ h, 1, BlendMode.Additive, flags(false, true, CullMode.None),+ );});it('should return Normal for invalid handle', () => {@@ -328,14 +308,35 @@ describe('Material API', () => {});});- describe('DepthTest', () => {- it('should set depth test and invalidate cache', () => {+ describe('DepthTest / DepthWrite / Cull', () => {+ it('should set depth test and push state', () => {const h = Material.create({ shader: 1 as ShaderHandle });- mock.invalidateMaterialCache.mockClear();+ mock.defineMaterial.mockClear();Material.setDepthTest(h, true);- const data = Material.get(h)!;- expect(data.depthTest).toBe(true);- expect(mock.invalidateMaterialCache).toHaveBeenCalledWith(h);+ expect(Material.get(h)!.depthTest).toBe(true);+ expect(mock.defineMaterial).toHaveBeenCalledWith(+ h, 1, BlendMode.Normal, flags(true, true, CullMode.None),+ );+ });++ it('should set depth write and push state', () => {+ const h = Material.create({ shader: 1 as ShaderHandle });+ mock.defineMaterial.mockClear();+ Material.setDepthWrite(h, false);+ expect(Material.get(h)!.depthWrite).toBe(false);+ expect(mock.defineMaterial).toHaveBeenCalledWith(+ h, 1, BlendMode.Normal, flags(false, false, CullMode.None),+ );+ });++ it('should set cull mode and push state', () => {+ const h = Material.create({ shader: 1 as ShaderHandle });+ mock.defineMaterial.mockClear();+ Material.setCull(h, CullMode.Front);+ expect(Material.get(h)!.cull).toBe(CullMode.Front);+ expect(mock.defineMaterial).toHaveBeenCalledWith(+ h, 1, BlendMode.Normal, flags(false, true, CullMode.Front),+ );});});@@ -355,107 +356,69 @@ describe('Material API', () => {// =========================================================================describe('Material.createFromAsset', () => {+ const baseAsset = (extra: Partial<MaterialAssetData>): MaterialAssetData => ({+ version: '1.0',+ type: 'material',+ shader: 'test.shader',+ blendMode: BlendMode.Normal,+ depthTest: false,+ properties: {},+ ...extra,+ });+it('should parse number properties', () => {- const assetData: MaterialAssetData = {- version: '1.0',- type: 'material',- shader: 'test.shader',- blendMode: BlendMode.Normal,- depthTest: false,- properties: { u_intensity: 0.75 },- };- const h = Material.createFromAsset(assetData, 10 as ShaderHandle);+ const h = Material.createFromAsset(baseAsset({ properties: { u_intensity: 0.75 } }), 10 as ShaderHandle);expect(Material.getUniform(h, 'u_intensity')).toBe(0.75);});it('should parse Color (with "a" key) as Vec4', () => {- const assetData: MaterialAssetData = {- version: '1.0',- type: 'material',- shader: 'test.shader',- blendMode: BlendMode.Normal,- depthTest: false,- properties: {- u_color: { r: 1, g: 0.5, b: 0.25, a: 1 },- },- };- const h = Material.createFromAsset(assetData, 10 as ShaderHandle);+ const h = Material.createFromAsset(+ baseAsset({ properties: { u_color: { r: 1, g: 0.5, b: 0.25, a: 1 } } }), 10 as ShaderHandle);const val = Material.getUniform(h, 'u_color') as { x: number; y: number; z: number; w: number };expect(val).toEqual({ x: 1, y: 0.5, z: 0.25, w: 1 });});it('should parse Vec4 (with "w" key)', () => {- const assetData: MaterialAssetData = {- version: '1.0',- type: 'material',- shader: 'test.shader',- blendMode: BlendMode.Normal,- depthTest: false,- properties: {- u_rect: { x: 0, y: 1, z: 2, w: 3 },- },- };- const h = Material.createFromAsset(assetData, 10 as ShaderHandle);+ const h = Material.createFromAsset(+ baseAsset({ properties: { u_rect: { x: 0, y: 1, z: 2, w: 3 } } }), 10 as ShaderHandle);const val = Material.getUniform(h, 'u_rect') as { x: number; y: number; z: number; w: number };expect(val).toEqual({ x: 0, y: 1, z: 2, w: 3 });});it('should parse Vec3 (with "z" key)', () => {- const assetData: MaterialAssetData = {- version: '1.0',- type: 'material',- shader: 'test.shader',- blendMode: BlendMode.Normal,- depthTest: false,- properties: {- u_pos: { x: 1, y: 2, z: 3 },- },- };- const h = Material.createFromAsset(assetData, 10 as ShaderHandle);+ const h = Material.createFromAsset(+ baseAsset({ properties: { u_pos: { x: 1, y: 2, z: 3 } } }), 10 as ShaderHandle);const val = Material.getUniform(h, 'u_pos') as { x: number; y: number; z: number };expect(val).toEqual({ x: 1, y: 2, z: 3 });});it('should parse Vec2 (with "y" key)', () => {- const assetData: MaterialAssetData = {- version: '1.0',- type: 'material',- shader: 'test.shader',- blendMode: BlendMode.Normal,- depthTest: false,- properties: {- u_offset: { x: 5, y: 10 },- },- };- const h = Material.createFromAsset(assetData, 10 as ShaderHandle);+ const h = Material.createFromAsset(+ baseAsset({ properties: { u_offset: { x: 5, y: 10 } } }), 10 as ShaderHandle);const val = Material.getUniform(h, 'u_offset') as { x: number; y: number };expect(val).toEqual({ x: 5, y: 10 });});- it('should use blendMode and depthTest from asset data', () => {- const assetData: MaterialAssetData = {- version: '1.0',- type: 'material',- shader: 'test.shader',- blendMode: BlendMode.Screen,- depthTest: true,- properties: {},- };- const h = Material.createFromAsset(assetData, 10 as ShaderHandle);+ it('should use blendMode, depthTest, depthWrite and cull from asset data', () => {+ const h = Material.createFromAsset(+ baseAsset({ blendMode: BlendMode.Screen, depthTest: true, depthWrite: false, cull: CullMode.Back }),+ 10 as ShaderHandle);expect(Material.getBlendMode(h)).toBe(BlendMode.Screen);- expect(Material.get(h)!.depthTest).toBe(true);+ const data = Material.get(h)!;+ expect(data.depthTest).toBe(true);+ expect(data.depthWrite).toBe(false);+ expect(data.cull).toBe(CullMode.Back);+ });++ it('should default depthWrite/cull when absent from asset data', () => {+ const h = Material.createFromAsset(baseAsset({}), 10 as ShaderHandle);+ const data = Material.get(h)!;+ expect(data.depthWrite).toBe(true);+ expect(data.cull).toBe(CullMode.None);});it('should use provided shaderHandle', () => {- const assetData: MaterialAssetData = {- version: '1.0',- type: 'material',- shader: 'test.shader',- blendMode: BlendMode.Normal,- depthTest: false,- properties: {},- };- const h = Material.createFromAsset(assetData, 77 as ShaderHandle);+ const h = Material.createFromAsset(baseAsset({}), 77 as ShaderHandle);expect(Material.getShader(h)).toBe(77);});});@@ -465,7 +428,7 @@ describe('Material API', () => {// =========================================================================describe('Material.createInstance', () => {- it('should copy shader, uniforms, blendMode, depthTest from source', () => {+ it('should inherit shader, uniforms, blendMode, depthTest from the parent', () => {const src = Material.create({shader: 42 as ShaderHandle,uniforms: { u_time: 1.5 },@@ -477,14 +440,19 @@ describe('Material API', () => {expect(Material.getShader(inst)).toBe(42);expect(Material.getUniform(inst, 'u_time')).toBe(1.5);expect(Material.getBlendMode(inst)).toBe(BlendMode.Additive);- expect(Material.get(inst)!.depthTest).toBe(true);});- it('should create independent instance (modifying instance does not affect source)', () => {- const src = Material.create({- shader: 1 as ShaderHandle,- uniforms: { u_val: 10 },- });+ it('should push the flattened (inherited) instance to the engine store', () => {+ const src = Material.create({ shader: 5 as ShaderHandle, blendMode: BlendMode.Multiply });+ mock.defineMaterial.mockClear();+ const inst = Material.createInstance(src);+ expect(mock.defineMaterial).toHaveBeenCalledWith(+ inst, 5, BlendMode.Multiply, flags(false, true, CullMode.None),+ );+ });++ it('an instance override does not affect the parent', () => {+ const src = Material.create({ shader: 1 as ShaderHandle, uniforms: { u_val: 10 } });const inst = Material.createInstance(src);Material.setUniform(inst, 'u_val', 20);@@ -492,15 +460,40 @@ describe('Material API', () => {expect(Material.getUniform(inst, 'u_val')).toBe(20);});- it('should create independent instance (modifying source does not affect instance)', () => {- const src = Material.create({- shader: 1 as ShaderHandle,- uniforms: { u_val: 10 },- });+ it('a parent edit PROPAGATES to a non-overriding instance', () => {+ const src = Material.create({ shader: 1 as ShaderHandle, uniforms: { u_val: 10 } });+ const inst = Material.createInstance(src);++ Material.setUniform(src, 'u_val', 99);+ expect(Material.getUniform(inst, 'u_val')).toBe(99); // inherited the change+ });++ it('an overridden param shields the instance from parent edits', () => {+ const src = Material.create({ shader: 1 as ShaderHandle, uniforms: { u_val: 10 } });+ const inst = Material.createInstance(src);+ Material.setUniform(inst, 'u_val', 20); // override++ Material.setUniform(src, 'u_val', 99);+ expect(Material.getUniform(inst, 'u_val')).toBe(20); // override wins+ });++ it('an instance can override render state independently of the parent', () => {+ const src = Material.create({ shader: 1 as ShaderHandle, blendMode: BlendMode.Normal });const inst = Material.createInstance(src);+ Material.setBlendMode(inst, BlendMode.Additive);++ expect(Material.getBlendMode(inst)).toBe(BlendMode.Additive);+ expect(Material.getBlendMode(src)).toBe(BlendMode.Normal);+ });+ it('a parent edit re-pushes the instance to the engine (propagation)', () => {+ const src = Material.create({ shader: 1 as ShaderHandle, uniforms: { u_val: 10 } });+ const inst = Material.createInstance(src);+ mock.setMaterialUniform.mockClear();Material.setUniform(src, 'u_val', 99);- expect(Material.getUniform(inst, 'u_val')).toBe(10);+ // Both the parent and the inheriting instance are re-pushed with the new value.+ expect(mock.setMaterialUniform).toHaveBeenCalledWith(src, 'u_val', 1, 99, 0, 0, 0);+ expect(mock.setMaterialUniform).toHaveBeenCalledWith(inst, 'u_val', 1, 99, 0, 0, 0);});it('should throw for invalid source', () => {@@ -517,6 +510,47 @@ describe('Material API', () => {});});+ // =========================================================================+ // Material instance serialization (diff)+ // =========================================================================++ describe('Material instance serialization', () => {+ it('serializes an instance as a diff (instanceOf + only overrides)', () => {+ const src = Material.create({+ shader: 9 as ShaderHandle,+ uniforms: { u_a: 1, u_b: 2 },+ blendMode: BlendMode.Normal,+ });+ const inst = Material.createInstance(src);+ Material.setUniform(inst, 'u_a', 5); // override one param+ Material.setBlendMode(inst, BlendMode.Additive); // override render state++ const asset = Material.toAssetData(inst, '', 'parent.esmaterial')!;+ expect(asset.instanceOf).toBe('parent.esmaterial');+ expect(asset.properties).toEqual({ u_a: 5 }); // only the overridden param+ expect(asset.blendMode).toBe(BlendMode.Additive);+ expect(asset.depthTest).toBeUndefined(); // not overridden -> omitted+ });++ it('round-trips an instance via createFromAsset(parentHandle)', () => {+ const src = Material.create({ shader: 3 as ShaderHandle, uniforms: { u_a: 1 } });+ const asset: MaterialAssetData = {+ version: '1.0', type: 'material', shader: '', instanceOf: 'p.esmaterial',+ properties: { u_a: 7 },+ };+ const inst = Material.createFromAsset(asset, 0, src);+ expect(Material.getShader(inst)).toBe(3); // inherited shader+ expect(Material.getUniform(inst, 'u_a')).toBe(7); // overridden value+ });++ it('a base material still serializes its full state', () => {+ const h = Material.create({ shader: 1 as ShaderHandle, blendMode: BlendMode.Multiply });+ const asset = Material.toAssetData(h, 'x.esshader')!;+ expect(asset.instanceOf).toBeUndefined();+ expect(asset.blendMode).toBe(BlendMode.Multiply);+ });+ });+// =========================================================================// toAssetData// =========================================================================@@ -536,6 +570,8 @@ describe('Material API', () => {shader: 'shaders/custom.shader',blendMode: BlendMode.Multiply,depthTest: true,+ depthWrite: true,+ cull: CullMode.None,properties: { u_time: 0.5 },});});@@ -608,214 +644,52 @@ describe('Material API', () => {});// =========================================================================- // registerMaterialCallback- // =========================================================================-- describe('registerMaterialCallback', () => {- it('should set materialDataProvider on module', () => {- expect(mock.materialDataProvider).toBeTypeOf('function');- });-- it('should be idempotent (second call is no-op)', () => {- const firstProvider = mock.materialDataProvider;- registerMaterialCallback();- expect(mock.materialDataProvider).toBe(firstProvider);- });- });-- // =========================================================================- // materialDataProvider callback- // =========================================================================-- describe('materialDataProvider callback', () => {- it('should write shader and blendMode to outPtrs for valid material', () => {- const h = Material.create({- shader: 7 as ShaderHandle,- blendMode: BlendMode.Additive,- });-- const outShader = 256;- const outBlend = 260;- const outUniBuf = 264;- const outUniCount = 268;-- mock.materialDataProvider!(h, outShader, outBlend, outUniBuf, outUniCount);-- expect(mock.HEAPU32[outShader >> 2]).toBe(7);- expect(mock.HEAPU32[outBlend >> 2]).toBe(BlendMode.Additive);- });-- it('should write zeros for unknown materialId', () => {- const outShader = 256;- const outBlend = 260;- const outUniBuf = 264;- const outUniCount = 268;-- mock.materialDataProvider!(999, outShader, outBlend, outUniBuf, outUniCount);-- expect(mock.HEAPU32[outShader >> 2]).toBe(0);- expect(mock.HEAPU32[outBlend >> 2]).toBe(0);- expect(mock.HEAPU32[outUniBuf >> 2]).toBe(0);- expect(mock.HEAPU32[outUniCount >> 2]).toBe(0);- });-- it('should serialize uniforms and report count', () => {- const h = Material.create({- shader: 1 as ShaderHandle,- uniforms: { u_time: 1.0, u_scale: 2.0 },- });-- const outShader = 256;- const outBlend = 260;- const outUniBuf = 264;- const outUniCount = 268;-- mock.materialDataProvider!(h, outShader, outBlend, outUniBuf, outUniCount);-- const uniformCount = mock.HEAPU32[outUniCount >> 2];- expect(uniformCount).toBe(2);- expect(mock.HEAPU32[outUniBuf >> 2]).toBeGreaterThan(0);- });-- it('should skip TextureRef uniforms in serialization count', () => {- const h = Material.create({- shader: 1 as ShaderHandle,- uniforms: {- u_time: 1.0,- u_tex: Material.tex(5),- },- });-- const outShader = 256;- const outBlend = 260;- const outUniBuf = 264;- const outUniCount = 268;-- mock.materialDataProvider!(h, outShader, outBlend, outUniBuf, outUniCount);-- const uniformCount = mock.HEAPU32[outUniCount >> 2];- expect(uniformCount).toBe(1);- });- });-- // =========================================================================- // serializeUniforms (tested via materialDataProvider callback)+ // Material parameter push (P1: reflection-driven MaterialConstants UBO)// =========================================================================- describe('serializeUniforms (via callback)', () => {- function callProvider(h: MaterialHandle) {- const outShader = 256;- const outBlend = 260;- const outUniBuf = 264;- const outUniCount = 268;- mock.materialDataProvider!(h, outShader, outBlend, outUniBuf, outUniCount);- return {- count: mock.HEAPU32[outUniCount >> 2],- bufferPtr: mock.HEAPU32[outUniBuf >> 2],- };- }-- it('should serialize number uniform (type 0)', () => {- const h = Material.create({- shader: 1 as ShaderHandle,- uniforms: { u_val: 42.5 },- });-- const { count, bufferPtr } = callProvider(h);- expect(count).toBe(1);-- // Read name length- const nameLen = mock.HEAPU32[bufferPtr >> 2];- expect(nameLen).toBe(5); // "u_val"-- // Read type after padded name- const namePadded = Math.ceil(nameLen / 4) * 4;- const typeOffset = bufferPtr + 4 + namePadded;- const type = mock.HEAPU32[typeOffset >> 2];- expect(type).toBe(0); // number type-- // Read first float value- const valOffset = typeOffset + 4;- expect(mock.HEAPF32[valOffset >> 2]).toBeCloseTo(42.5);+ describe('material parameter push', () => {+ it('compileShader proxies to module.compileEsshader (no switches => empty features)', () => {+ const h = Material.compileShader('#pragma shader "x"');+ expect(h).toBe(7);+ expect(mock.compileEsshader).toHaveBeenCalledWith('#pragma shader "x"', '');});- it('should serialize Vec2 uniform (type 1)', () => {- const h = Material.create({- shader: 1 as ShaderHandle,- uniforms: { uv: { x: 3, y: 4 } },- });-- const { count, bufferPtr } = callProvider(h);- expect(count).toBe(1);-- const nameLen = mock.HEAPU32[bufferPtr >> 2];- const namePadded = Math.ceil(nameLen / 4) * 4;- const typeOffset = bufferPtr + 4 + namePadded;- expect(mock.HEAPU32[typeOffset >> 2]).toBe(1);-- const valOffset = typeOffset + 4;- expect(mock.HEAPF32[valOffset >> 2]).toBeCloseTo(3);- expect(mock.HEAPF32[(valOffset + 4) >> 2]).toBeCloseTo(4);+ it('compileShader passes enabled switches as a CSV feature set', () => {+ mock.compileEsshader.mockClear();+ Material.compileShader('src', ['USE_A', 'USE_B']);+ expect(mock.compileEsshader).toHaveBeenCalledWith('src', 'USE_A,USE_B');});- it('should serialize Vec3 uniform (type 2)', () => {- const h = Material.create({- shader: 1 as ShaderHandle,- uniforms: { pos: { x: 1, y: 2, z: 3 } },- });-- const { count, bufferPtr } = callProvider(h);- expect(count).toBe(1);-- const nameLen = mock.HEAPU32[bufferPtr >> 2];- const namePadded = Math.ceil(nameLen / 4) * 4;- const typeOffset = bufferPtr + 4 + namePadded;- expect(mock.HEAPU32[typeOffset >> 2]).toBe(2);-- const valOffset = typeOffset + 4;- expect(mock.HEAPF32[valOffset >> 2]).toBeCloseTo(1);- expect(mock.HEAPF32[(valOffset + 4) >> 2]).toBeCloseTo(2);- expect(mock.HEAPF32[(valOffset + 8) >> 2]).toBeCloseTo(3);+ it('stores static switches and round-trips them through toAssetData', () => {+ const h = Material.create({ shader: 1 as ShaderHandle, switches: { USE_GREEN: true } });+ expect(Material.getSwitch(h, 'USE_GREEN')).toBe(true);+ expect(Material.getSwitch(h, 'USE_NOPE')).toBe(false);+ const asset = Material.toAssetData(h, 'x.esshader')!;+ expect(asset.switches).toEqual({ USE_GREEN: true });});- it('should serialize Vec4 uniform (type 3)', () => {+ it('pushes uniform values to the engine on create', () => {const h = Material.create({shader: 1 as ShaderHandle,- uniforms: { col: { x: 0.1, y: 0.2, z: 0.3, w: 0.4 } },+ uniforms: { u_tint: { x: 1, y: 0, z: 0, w: 1 } },});-- const { count, bufferPtr } = callProvider(h);- expect(count).toBe(1);-- const nameLen = mock.HEAPU32[bufferPtr >> 2];- const namePadded = Math.ceil(nameLen / 4) * 4;- const typeOffset = bufferPtr + 4 + namePadded;- expect(mock.HEAPU32[typeOffset >> 2]).toBe(3);-- const valOffset = typeOffset + 4;- expect(mock.HEAPF32[valOffset >> 2]).toBeCloseTo(0.1);- expect(mock.HEAPF32[(valOffset + 4) >> 2]).toBeCloseTo(0.2);- expect(mock.HEAPF32[(valOffset + 8) >> 2]).toBeCloseTo(0.3);- expect(mock.HEAPF32[(valOffset + 12) >> 2]).toBeCloseTo(0.4);+ expect(mock.setMaterialUniform).toHaveBeenCalledWith(h, 'u_tint', 4, 1, 0, 0, 1);});- it('should skip TextureRef uniforms', () => {- const h = Material.create({- shader: 1 as ShaderHandle,- uniforms: {- u_tex: Material.tex(1),- u_val: 5.0,- },- });-- const { count } = callProvider(h);- expect(count).toBe(1);+ it('pushes the value on setUniform', () => {+ const h = Material.create({ shader: 1 as ShaderHandle });+ mock.setMaterialUniform.mockClear();+ Material.setUniform(h, 'u_strength', 2.5);+ expect(mock.setMaterialUniform).toHaveBeenCalledWith(h, 'u_strength', 1, 2.5, 0, 0, 0);});- it('should handle material with no uniforms', () => {+ it('routes texture refs to setMaterialTexture (not the std140 uniform path)', () => {const h = Material.create({ shader: 1 as ShaderHandle });- const { count } = callProvider(h);- expect(count).toBe(0);+ mock.setMaterialUniform.mockClear();+ mock.setMaterialTexture.mockClear();+ Material.setUniform(h, 'u_tex', Material.tex(5));+ expect(mock.setMaterialUniform).not.toHaveBeenCalled();+ expect(mock.setMaterialTexture).toHaveBeenCalledWith(h, 'u_tex', 5);});});diff --git a/sdk/tests/materialGraph.test.ts b/sdk/tests/materialGraph.test.tsnew file mode 100644index 000000000..3370a4aa2--- /dev/null+++ b/sdk/tests/materialGraph.test.ts@@ -0,0 +1,182 @@+// SPDX-License-Identifier: LicenseRef-PolyForm-Noncommercial-1.0.0+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team+import { describe, it, expect } from 'vitest';+import {+ compileMaterialGraph,+ newMaterialGraph,+ addNode,+ connect,+ disconnect,+ removeNode,+ moveNode,+ NODE_SPECS,+ type MaterialGraph,+} from '../src/materialGraph';++// TextureSample(u_albedo) × ConstColor(u_tint) → Output — a tint material as a graph.+const tintGraph: MaterialGraph = {+ name: 'GraphTint',+ output: 'out',+ nodes: [+ { id: 'tex', type: 'textureSample', params: { name: 'u_albedo', default: 'white' } },+ { id: 'tint', type: 'constColor', params: { name: 'u_tint', value: [1, 1, 1, 1] } },+ { id: 'mul', type: 'multiply', inputs: { a: 'tex', b: 'tint' } },+ { id: 'out', type: 'output', inputs: { color: 'mul' } },+ ],+};++describe('compileMaterialGraph', () => {+ it('emits const/texture nodes as reflected #pragma params', () => {+ const src = compileMaterialGraph(tintGraph);+ expect(src).toContain('#pragma param u_albedo texture default(white)');+ expect(src).toContain('#pragma param u_tint color default(1,1,1,1)');+ expect(src).toContain('#pragma domain Unlit2D');+ expect(src).toContain('#pragma shader "GraphTint"');+ });++ it('emits a topologically ordered fragment body ending at fragColor', () => {+ const src = compileMaterialGraph(tintGraph);+ expect(src).toContain('vec4 n0 = texture(u_albedo, v_texCoord);');+ expect(src).toContain('vec4 n1 = n0 * u_tint;');+ expect(src).toContain('fragColor = n1;');+ // the texture sample must precede the multiply that consumes it+ expect(src.indexOf('texture(u_albedo')).toBeLessThan(src.indexOf('n0 * u_tint'));+ });++ it('reuses a shared node once (DAG, not a tree)', () => {+ const g: MaterialGraph = {+ output: 'out',+ nodes: [+ { id: 'c', type: 'constColor', params: { name: 'u_c', value: [1, 0, 0, 1] } },+ { id: 'm', type: 'multiply', inputs: { a: 'c', b: 'c' } }, // u_c used twice+ { id: 'out', type: 'output', inputs: { color: 'm' } },+ ],+ };+ const src = compileMaterialGraph(g);+ // The param is declared exactly once even though two edges reference it.+ expect(src.match(/#pragma param u_c color/g)?.length).toBe(1);+ expect(src).toContain('u_c * u_c');+ });++ it('promotes a non-vec4 output to vec4', () => {+ const g: MaterialGraph = {+ output: 'out',+ nodes: [+ { id: 'f', type: 'constFloat', params: { name: 'u_g', value: 0.5 } },+ { id: 'out', type: 'output', inputs: { color: 'f' } },+ ],+ };+ expect(compileMaterialGraph(g)).toContain('fragColor = vec4(vec3(u_g), 1.0);');+ });++ it('passes a Lit2D domain through', () => {+ expect(compileMaterialGraph({ ...tintGraph, domain: 'Lit2D' })).toContain('#pragma domain Lit2D');+ });++ it('emits oneMinus / saturate preserving the input type', () => {+ const g: MaterialGraph = {+ output: 'out',+ nodes: [+ { id: 'tex', type: 'textureSample', params: { name: 'u_a', default: 'white' } },+ { id: 'inv', type: 'oneMinus', inputs: { x: 'tex' } },+ { id: 'sat', type: 'saturate', inputs: { x: 'inv' } },+ { id: 'out', type: 'output', inputs: { color: 'sat' } },+ ],+ };+ const src = compileMaterialGraph(g);+ expect(src).toContain('vec4 n1 = 1.0 - n0;');+ expect(src).toContain('vec4 n2 = clamp(n1, 0.0, 1.0);');+ });++ it('throws on a cycle', () => {+ const g: MaterialGraph = {+ output: 'out',+ nodes: [+ { id: 'a', type: 'multiply', inputs: { a: 'b', b: 'b' } },+ { id: 'b', type: 'multiply', inputs: { a: 'a', b: 'a' } },+ { id: 'out', type: 'output', inputs: { color: 'a' } },+ ],+ };+ expect(() => compileMaterialGraph(g)).toThrow(/cycle/);+ });++ it('throws on a missing node / input / bad output', () => {+ expect(() => compileMaterialGraph({ output: 'out', nodes: [{ id: 'out', type: 'output', inputs: { color: 'nope' } }] }))+ .toThrow(/missing node/);+ expect(() => compileMaterialGraph({ output: 'out', nodes: [{ id: 'out', type: 'output' }] }))+ .toThrow(/missing input/);+ expect(() => compileMaterialGraph({ output: 'x', nodes: [{ id: 'x', type: 'uv' }] }))+ .toThrow(/"output"/);+ });+});++describe('material graph editor ops', () => {+ it('the default graph compiles', () => {+ expect(() => compileMaterialGraph(newMaterialGraph())).not.toThrow();+ });++ it('addNode gives a fresh id + default params and stays immutable', () => {+ const g = newMaterialGraph();+ const { graph, id } = addNode(g, 'constColor', 10, 20);+ expect(g.nodes).toHaveLength(2); // original untouched+ const node = graph.nodes.find((n) => n.id === id)!;+ expect(node.type).toBe('constColor');+ expect(node.params).toEqual({ name: `u_${id}`, value: [1, 1, 1, 1] });+ expect(node.x).toBe(10);+ });++ it('connect wires an input and the result compiles', () => {+ let g = newMaterialGraph();+ const added = addNode(g, 'constColor', 0, 0);+ g = added.graph;+ g = connect(g, added.id, 'tex', 'uv'); // not meaningful but valid slot... use a real one:+ // wire the color node into a multiply, then into output+ const mul = addNode(g, 'multiply', 0, 0);+ g = mul.graph;+ g = connect(g, 'tex', mul.id, 'a');+ g = connect(g, added.id, mul.id, 'b');+ g = connect(g, mul.id, 'out', 'color');+ expect(g.nodes.find((n) => n.id === 'out')!.inputs!.color).toBe(mul.id);+ expect(() => compileMaterialGraph(g)).not.toThrow();+ });++ it('connect rejects a cycle (graph unchanged)', () => {+ let g = newMaterialGraph();+ const m = addNode(g, 'multiply', 0, 0);+ g = m.graph;+ g = connect(g, 'tex', m.id, 'a'); // tex → multiply+ const looped = connect(g, m.id, 'tex', 'uv'); // multiply → tex would loop+ expect(looped).toBe(g); // unchanged reference: rejected+ });++ it('connect rejects an unknown slot', () => {+ const g = newMaterialGraph();+ expect(connect(g, 'tex', 'out', 'nope')).toBe(g);+ });++ it('disconnect clears a slot', () => {+ const g = disconnect(newMaterialGraph(), 'out', 'color');+ expect(g.nodes.find((n) => n.id === 'out')!.inputs?.color).toBeUndefined();+ });++ it('removeNode drops the node + edges into it, but never the output', () => {+ const g = removeNode(newMaterialGraph(), 'tex');+ expect(g.nodes.find((n) => n.id === 'tex')).toBeUndefined();+ expect(g.nodes.find((n) => n.id === 'out')!.inputs?.color).toBeUndefined(); // edge cleaned+ expect(removeNode(g, 'out').nodes.some((n) => n.id === 'out')).toBe(true); // output kept+ });++ it('moveNode updates layout only', () => {+ const g = moveNode(newMaterialGraph(), 'tex', 99, 77);+ const n = g.nodes.find((m) => m.id === 'tex')!;+ expect([n.x, n.y]).toEqual([99, 77]);+ });++ it('NODE_SPECS covers every node type the compiler handles', () => {+ for (const type of Object.keys(NODE_SPECS)) {+ expect(NODE_SPECS[type as keyof typeof NODE_SPECS].label).toBeTruthy();+ }+ expect(NODE_SPECS.output.addable).toBe(false);+ expect(NODE_SPECS.multiply.inputs.map((p) => p.name)).toEqual(['a', 'b']);+ });+});diff --git a/src/esengine/bindings/EditorAPI.generated.cpp b/src/esengine/bindings/EditorAPI.generated.cppindex 367c3e33b..a91cc292a 100644--- a/src/esengine/bindings/EditorAPI.generated.cpp+++ b/src/esengine/bindings/EditorAPI.generated.cpp@@ -2,10 +2,10 @@* @file EditorAPI.generated.cpp* @brief Auto-generated editor API with string-dispatched component access* @details Generated by EHT - DO NOT EDIT- * @schema_hash a1287b16b459bbd1+ * @schema_hash 517314ab9b2a2e13*/-#define ES_EDITOR_API_SCHEMA_HASH "a1287b16b459bbd1"+#define ES_EDITOR_API_SCHEMA_HASH "517314ab9b2a2e13"#include <emscripten/bind.h>#include <string>@@ -18,6 +18,7 @@#include "../ecs/components/FlexContainer.hpp"#include "../ecs/components/Hierarchy.hpp"#include "../ecs/components/Interactable.hpp"+#include "../ecs/components/Light2D.hpp"#include "../ecs/components/ParticleEmitter.hpp"#include "../ecs/components/RigidBody.hpp"#include "../ecs/components/ShapeRenderer.hpp"@@ -60,6 +61,7 @@ std::vector<std::string> editor_getComponentNames() {"CircleCollider","FlexContainer","Interactable",+ "Light2D","Parent","ParticleEmitter","RigidBody",@@ -189,6 +191,21 @@ std::string editor_getComponentSchema(const std::string& name) {{"key":"blockRaycast","type":"bool","group":"Interactable"},{"key":"raycastTarget","type":"bool","group":"Interactable"}])JSON";+ } else if (name == "Light2D") {+ return R"JSON([+ {"key":"type","type":"int","group":"Light2D"},+ {"key":"color.r","type":"color","group":"Light2D"},+ {"key":"color.g","type":"color","group":"Light2D"},+ {"key":"color.b","type":"color","group":"Light2D"},+ {"key":"color.a","type":"color","group":"Light2D"},+ {"key":"intensity","type":"float","group":"Light2D"},+ {"key":"radius","type":"float","group":"Light2D"},+ {"key":"direction.x","type":"float","group":"Light2D"},+ {"key":"direction.y","type":"float","group":"Light2D"},+ {"key":"innerAngle","type":"float","group":"Light2D"},+ {"key":"outerAngle","type":"float","group":"Light2D"},+ {"key":"enabled","type":"bool","group":"Light2D"}+ ])JSON";} else if (name == "Parent") {return R"JSON([{"key":"entity","type":"entity","group":"Parent"}@@ -487,6 +504,9 @@ bool editor_addComponent(Registry& reg, u32 e, const std::string& name) {} else if (name == "Interactable") {if (!reg.has<esengine::ecs::Interactable>(entity)) reg.emplace<esengine::ecs::Interactable>(entity);return true;+ } else if (name == "Light2D") {+ if (!reg.has<esengine::ecs::Light2D>(entity)) reg.emplace<esengine::ecs::Light2D>(entity);+ return true;} else if (name == "Parent") {if (!reg.has<esengine::ecs::Parent>(entity)) reg.emplace<esengine::ecs::Parent>(entity);return true;@@ -560,6 +580,8 @@ bool editor_removeComponent(Registry& reg, u32 e, const std::string& name) {if (reg.has<esengine::ecs::FlexContainer>(entity)) { reg.remove<esengine::ecs::FlexContainer>(entity); return true; }} else if (name == "Interactable") {if (reg.has<esengine::ecs::Interactable>(entity)) { reg.remove<esengine::ecs::Interactable>(entity); return true; }+ } else if (name == "Light2D") {+ if (reg.has<esengine::ecs::Light2D>(entity)) { reg.remove<esengine::ecs::Light2D>(entity); return true; }} else if (name == "Parent") {if (reg.has<esengine::ecs::Parent>(entity)) { reg.remove<esengine::ecs::Parent>(entity); return true; }} else if (name == "ParticleEmitter") {@@ -608,6 +630,7 @@ bool editor_hasComponent(Registry& reg, u32 e, const std::string& name) {if (name == "CircleCollider") return reg.has<esengine::ecs::CircleCollider>(entity);if (name == "FlexContainer") return reg.has<esengine::ecs::FlexContainer>(entity);if (name == "Interactable") return reg.has<esengine::ecs::Interactable>(entity);+ if (name == "Light2D") return reg.has<esengine::ecs::Light2D>(entity);if (name == "Parent") return reg.has<esengine::ecs::Parent>(entity);if (name == "ParticleEmitter") return reg.has<esengine::ecs::ParticleEmitter>(entity);if (name == "RigidBody") return reg.has<esengine::ecs::RigidBody>(entity);@@ -642,6 +665,7 @@ std::vector<std::string> editor_getComponents(Registry& reg, u32 e) {if (reg.has<esengine::ecs::CircleCollider>(entity)) result.push_back("CircleCollider");if (reg.has<esengine::ecs::FlexContainer>(entity)) result.push_back("FlexContainer");if (reg.has<esengine::ecs::Interactable>(entity)) result.push_back("Interactable");+ if (reg.has<esengine::ecs::Light2D>(entity)) result.push_back("Light2D");if (reg.has<esengine::ecs::Parent>(entity)) result.push_back("Parent");if (reg.has<esengine::ecs::ParticleEmitter>(entity)) result.push_back("ParticleEmitter");if (reg.has<esengine::ecs::RigidBody>(entity)) result.push_back("RigidBody");@@ -748,6 +772,21 @@ bool editor_setFloat(Registry& reg, u32 e, const std::string& comp, const std::selse if (field == "padding.bottom") { c.padding.bottom = value; }else { return false; }return true;+ } else if (comp == "Light2D") {+ if (!reg.has<esengine::ecs::Light2D>(entity)) return false;+ auto& c = reg.get<esengine::ecs::Light2D>(entity);+ if (field == "color.r") { c.color.r = value; }+ else if (field == "color.g") { c.color.g = value; }+ else if (field == "color.b") { c.color.b = value; }+ else if (field == "color.a") { c.color.a = value; }+ else if (field == "intensity") { c.intensity = value; }+ else if (field == "radius") { c.radius = value; }+ else if (field == "direction.x") { c.direction.x = value; }+ else if (field == "direction.y") { c.direction.y = value; }+ else if (field == "innerAngle") { c.innerAngle = value; }+ else if (field == "outerAngle") { c.outerAngle = value; }+ else { return false; }+ return true;} else if (comp == "ParticleEmitter") {if (!reg.has<esengine::ecs::ParticleEmitter>(entity)) return false;auto& c = reg.get<esengine::ecs::ParticleEmitter>(entity);@@ -1043,6 +1082,19 @@ f32 editor_getFloat(Registry& reg, u32 e, const std::string& comp, const std::stelse if (field == "padding.top") { return c.padding.top; }else if (field == "padding.right") { return c.padding.right; }else if (field == "padding.bottom") { return c.padding.bottom; }+ } else if (comp == "Light2D") {+ if (!reg.has<esengine::ecs::Light2D>(entity)) return 0.0f;+ const auto& c = reg.get<esengine::ecs::Light2D>(entity);+ if (field == "color.r") { return c.color.r; }+ else if (field == "color.g") { return c.color.g; }+ else if (field == "color.b") { return c.color.b; }+ else if (field == "color.a") { return c.color.a; }+ else if (field == "intensity") { return c.intensity; }+ else if (field == "radius") { return c.radius; }+ else if (field == "direction.x") { return c.direction.x; }+ else if (field == "direction.y") { return c.direction.y; }+ else if (field == "innerAngle") { return c.innerAngle; }+ else if (field == "outerAngle") { return c.outerAngle; }} else if (comp == "ParticleEmitter") {if (!reg.has<esengine::ecs::ParticleEmitter>(entity)) return 0.0f;const auto& c = reg.get<esengine::ecs::ParticleEmitter>(entity);@@ -1287,6 +1339,12 @@ bool editor_setInt(Registry& reg, u32 e, const std::string& comp, const std::strelse if (field == "alignContent") { c.alignContent = static_cast<AlignContent>(value); }else { return false; }return true;+ } else if (comp == "Light2D") {+ if (!reg.has<esengine::ecs::Light2D>(entity)) return false;+ auto& c = reg.get<esengine::ecs::Light2D>(entity);+ if (field == "type") { c.type = static_cast<i32>(value); }+ else { return false; }+ return true;} else if (comp == "Parent") {if (!reg.has<esengine::ecs::Parent>(entity)) return false;auto& c = reg.get<esengine::ecs::Parent>(entity);@@ -1432,6 +1490,10 @@ i32 editor_getInt(Registry& reg, u32 e, const std::string& comp, const std::strielse if (field == "justifyContent") { return static_cast<i32>(c.justifyContent); }else if (field == "alignItems") { return static_cast<i32>(c.alignItems); }else if (field == "alignContent") { return static_cast<i32>(c.alignContent); }+ } else if (comp == "Light2D") {+ if (!reg.has<esengine::ecs::Light2D>(entity)) return 0;+ const auto& c = reg.get<esengine::ecs::Light2D>(entity);+ if (field == "type") { return static_cast<i32>(c.type); }} else if (comp == "Parent") {if (!reg.has<esengine::ecs::Parent>(entity)) return 0;const auto& c = reg.get<esengine::ecs::Parent>(entity);@@ -1555,6 +1617,12 @@ bool editor_setBool(Registry& reg, u32 e, const std::string& comp, const std::stelse if (field == "raycastTarget") { c.raycastTarget = value; }else { return false; }return true;+ } else if (comp == "Light2D") {+ if (!reg.has<esengine::ecs::Light2D>(entity)) return false;+ auto& c = reg.get<esengine::ecs::Light2D>(entity);+ if (field == "enabled") { c.enabled = value; }+ else { return false; }+ return true;} else if (comp == "ParticleEmitter") {if (!reg.has<esengine::ecs::ParticleEmitter>(entity)) return false;auto& c = reg.get<esengine::ecs::ParticleEmitter>(entity);@@ -1668,6 +1736,10 @@ bool editor_getBool(Registry& reg, u32 e, const std::string& comp, const std::stif (field == "enabled") { return c.enabled; }else if (field == "blockRaycast") { return c.blockRaycast; }else if (field == "raycastTarget") { return c.raycastTarget; }+ } else if (comp == "Light2D") {+ if (!reg.has<esengine::ecs::Light2D>(entity)) return false;+ const auto& c = reg.get<esengine::ecs::Light2D>(entity);+ if (field == "enabled") { return c.enabled; }} else if (comp == "ParticleEmitter") {if (!reg.has<esengine::ecs::ParticleEmitter>(entity)) return false;const auto& c = reg.get<esengine::ecs::ParticleEmitter>(entity);diff --git a/src/esengine/bindings/EngineState.hpp b/src/esengine/bindings/EngineState.hppindex 952c9921a..f764c6c6c 100644--- a/src/esengine/bindings/EngineState.hpp+++ b/src/esengine/bindings/EngineState.hpp@@ -4,7 +4,6 @@#include <glm/glm.hpp>#include "../core/Types.hpp"-#include "MaterialCache.hpp"namespace esengine {@@ -19,7 +18,6 @@ struct EngineState {glm::mat4 current_view_projection{1.0f};f32 delta_time = 0.016f;bool transforms_updated = false;- MaterialCache material_cache;};} // namespace esenginediff --git a/src/esengine/bindings/MaterialCache.hpp b/src/esengine/bindings/MaterialCache.hppdeleted file mode 100644index 91bfb6e6f..000000000--- a/src/esengine/bindings/MaterialCache.hpp+++ /dev/null@@ -1,43 +0,0 @@-// SPDX-License-Identifier: LicenseRef-PolyForm-Noncommercial-1.0.0-// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team-#pragma once--#include "../core/Types.hpp"-#include <unordered_map>-#include <vector>-#include <cstring>--namespace esengine {--struct MaterialUniformData {- char name[32];- u32 type;- f32 values[4];-};--struct CachedMaterialData {- u32 shaderId = 0;- u32 blendMode = 0;- std::vector<MaterialUniformData> uniforms;-};--class MaterialCache {-public:- void clear() { cache_.clear(); }-- void invalidate(u32 materialId) { cache_.erase(materialId); }-- const CachedMaterialData* find(u32 materialId) const {- auto it = cache_.find(materialId);- return it != cache_.end() ? &it->second : nullptr;- }-- void store(u32 materialId, CachedMaterialData data) {- cache_[materialId] = std::move(data);- }--private:- std::unordered_map<u32, CachedMaterialData> cache_;-};--} // namespace esenginediff --git a/src/esengine/bindings/RendererBindings.cpp b/src/esengine/bindings/RendererBindings.cppindex a14eb16d7..37d1235fd 100644--- a/src/esengine/bindings/RendererBindings.cpp+++ b/src/esengine/bindings/RendererBindings.cpp@@ -16,6 +16,8 @@#include "../ecs/components/Camera.hpp"#include "../ecs/components/Canvas.hpp"#include "../ecs/components/Transform.hpp"+#include "../ecs/components/Sprite.hpp"+#include "../ecs/components/Light2D.hpp"#include "../ecs/components/Hierarchy.hpp"#include "../core/Log.hpp"#ifdef ES_ENABLE_PARTICLES@@ -649,6 +651,47 @@ u32 renderer_getSnapshotHeight() {return g_renderFrame->getSnapshotHeight();}+void renderer_renderMaterialPreview(u32 materialId, i32 w, i32 h) {+ if (!g_renderFrame || w <= 0 || h <= 0) return;++ // A throwaway one-sprite scene: a 2×2 quad filling the ortho [-1,1] with the material, lit by+ // one white directional light so Lit2D materials preview lit (Unlit2D ignores it).+ ecs::Registry reg;+ auto quad = reg.create();+ reg.emplace<ecs::Transform>(quad);+ auto& sprite = reg.emplace<ecs::Sprite>(quad);+ sprite.material = materialId;+ sprite.size = glm::vec2(2.0f, 2.0f);++ auto light = reg.create();+ reg.emplace<ecs::Transform>(light);+ reg.emplace<ecs::Light2D>(light).type = static_cast<i32>(ecs::Light2DType::Directional);++ if (g_transformSystem) {+ esengine::World world{reg, ctx().services(), 0.0f};+ g_transformSystem->update(world);+ }++ const glm::mat4 vp = glm::ortho(-1.0f, 1.0f, -1.0f, 1.0f, -1.0f, 1.0f);+ g_renderFrame->renderToTarget(reg, vp, static_cast<u32>(w), static_cast<u32>(h));+}++uintptr_t renderer_getPreviewPtr() {+ return g_renderFrame ? reinterpret_cast<uintptr_t>(g_renderFrame->getPreviewPixels()) : 0;+}++u32 renderer_getPreviewSize() {+ return g_renderFrame ? g_renderFrame->getPreviewSize() : 0;+}++u32 renderer_getPreviewWidth() {+ return g_renderFrame ? g_renderFrame->getPreviewWidth() : 0;+}++u32 renderer_getPreviewHeight() {+ return g_renderFrame ? g_renderFrame->getPreviewHeight() : 0;+}+void renderer_setTextureParams(u32 textureId, i32 minFilter, i32 magFilter, i32 wrapS, i32 wrapT) {auto* device = g_device;if (!device) return;diff --git a/src/esengine/bindings/RendererBindings.hpp b/src/esengine/bindings/RendererBindings.hppindex 38acfb8a3..9a50fd1ec 100644--- a/src/esengine/bindings/RendererBindings.hpp+++ b/src/esengine/bindings/RendererBindings.hpp@@ -139,6 +139,12 @@ u32 renderer_getSnapshotSize();u32 renderer_getSnapshotWidth();u32 renderer_getSnapshotHeight();+void renderer_renderMaterialPreview(u32 materialId, i32 w, i32 h);+uintptr_t renderer_getPreviewPtr();+u32 renderer_getPreviewSize();+u32 renderer_getPreviewWidth();+u32 renderer_getPreviewHeight();+void renderer_setTextureParams(u32 textureId, i32 minFilter, i32 magFilter, i32 wrapS, i32 wrapT);i32 registry_getCanvasEntity(ecs::Registry& registry);diff --git a/src/esengine/bindings/WebBindings.generated.cpp b/src/esengine/bindings/WebBindings.generated.cppindex 385ed757f..f86220eed 100644--- a/src/esengine/bindings/WebBindings.generated.cpp+++ b/src/esengine/bindings/WebBindings.generated.cpp@@ -18,6 +18,7 @@#include "../ecs/components/FlexContainer.hpp"#include "../ecs/components/Hierarchy.hpp"#include "../ecs/components/Interactable.hpp"+#include "../ecs/components/Light2D.hpp"#include "../ecs/components/ParticleEmitter.hpp"#include "../ecs/components/RigidBody.hpp"#include "../ecs/components/ShapeRenderer.hpp"@@ -890,6 +891,16 @@ EMSCRIPTEN_BINDINGS(esengine_components) {.field("blockRaycast", &esengine::ecs::Interactable::blockRaycast).field("raycastTarget", &esengine::ecs::Interactable::raycastTarget);+ value_object<esengine::ecs::Light2D>("Light2D")+ .field("type", &esengine::ecs::Light2D::type)+ .field("color", &esengine::ecs::Light2D::color)+ .field("intensity", &esengine::ecs::Light2D::intensity)+ .field("radius", &esengine::ecs::Light2D::radius)+ .field("direction", &esengine::ecs::Light2D::direction)+ .field("innerAngle", &esengine::ecs::Light2D::innerAngle)+ .field("outerAngle", &esengine::ecs::Light2D::outerAngle)+ .field("enabled", &esengine::ecs::Light2D::enabled);+value_object<ParentJS>("Parent").field("entity", &ParentJS::entity);@@ -1278,6 +1289,27 @@ EMSCRIPTEN_BINDINGS(esengine_registry) {r.remove<esengine::ecs::Interactable>(entity);}))+ // Light2D+ .function("hasLight2D", optional_override([](Registry& r, u32 e) {+ return r.has<esengine::ecs::Light2D>(static_cast<Entity>(e));+ }))+ .function("getLight2D", optional_override([](Registry& r, u32 e) -> esengine::ecs::Light2D& {+ auto entity = static_cast<Entity>(e);+ static esengine::ecs::Light2D s_dummy{};+ if (!r.valid(entity) || !r.has<esengine::ecs::Light2D>(entity)) return s_dummy;+ return r.get<esengine::ecs::Light2D>(entity);+ }), allow_raw_pointers())+ .function("addLight2D", optional_override([](Registry& r, u32 e, const esengine::ecs::Light2D& c) {+ auto entity = static_cast<Entity>(e);+ if (!r.valid(entity)) return;+ r.emplaceOrReplace<esengine::ecs::Light2D>(entity, c);+ }))+ .function("removeLight2D", optional_override([](Registry& r, u32 e) {+ auto entity = static_cast<Entity>(e);+ if (!r.valid(entity) || !r.has<esengine::ecs::Light2D>(entity)) return;+ r.remove<esengine::ecs::Light2D>(entity);+ }))+// Parent.function("hasParent", optional_override([](Registry& r, u32 e) {return r.has<esengine::ecs::Parent>(static_cast<Entity>(e));@@ -1632,6 +1664,7 @@ emscripten::val esengineGetBuiltinComponentNames() {arr.set(i++, val(std::string("CircleCollider")));arr.set(i++, val(std::string("FlexContainer")));arr.set(i++, val(std::string("Interactable")));+ arr.set(i++, val(std::string("Light2D")));arr.set(i++, val(std::string("Parent")));arr.set(i++, val(std::string("ParticleEmitter")));arr.set(i++, val(std::string("RigidBody")));@@ -1721,6 +1754,14 @@ static_assert(offsetof(esengine::ecs::FlexContainer, gap) == 8, "ABI offset drifstatic_assert(offsetof(esengine::ecs::Interactable, enabled) == 0, "ABI offset drift: esengine::ecs::Interactable.enabled (EHT expected 0)");static_assert(offsetof(esengine::ecs::Interactable, blockRaycast) == 1, "ABI offset drift: esengine::ecs::Interactable.blockRaycast (EHT expected 1)");static_assert(offsetof(esengine::ecs::Interactable, raycastTarget) == 2, "ABI offset drift: esengine::ecs::Interactable.raycastTarget (EHT expected 2)");+static_assert(offsetof(esengine::ecs::Light2D, type) == 0, "ABI offset drift: esengine::ecs::Light2D.type (EHT expected 0)");+static_assert(offsetof(esengine::ecs::Light2D, color) == 4, "ABI offset drift: esengine::ecs::Light2D.color (EHT expected 4)");+static_assert(offsetof(esengine::ecs::Light2D, intensity) == 20, "ABI offset drift: esengine::ecs::Light2D.intensity (EHT expected 20)");+static_assert(offsetof(esengine::ecs::Light2D, radius) == 24, "ABI offset drift: esengine::ecs::Light2D.radius (EHT expected 24)");+static_assert(offsetof(esengine::ecs::Light2D, direction) == 28, "ABI offset drift: esengine::ecs::Light2D.direction (EHT expected 28)");+static_assert(offsetof(esengine::ecs::Light2D, innerAngle) == 36, "ABI offset drift: esengine::ecs::Light2D.innerAngle (EHT expected 36)");+static_assert(offsetof(esengine::ecs::Light2D, outerAngle) == 40, "ABI offset drift: esengine::ecs::Light2D.outerAngle (EHT expected 40)");+static_assert(offsetof(esengine::ecs::Light2D, enabled) == 44, "ABI offset drift: esengine::ecs::Light2D.enabled (EHT expected 44)");static_assert(offsetof(esengine::ecs::ParticleEmitter, rate) == 0, "ABI offset drift: esengine::ecs::ParticleEmitter.rate (EHT expected 0)");static_assert(offsetof(esengine::ecs::ParticleEmitter, burstCount) == 4, "ABI offset drift: esengine::ecs::ParticleEmitter.burstCount (EHT expected 4)");static_assert(offsetof(esengine::ecs::ParticleEmitter, burstInterval) == 8, "ABI offset drift: esengine::ecs::ParticleEmitter.burstInterval (EHT expected 8)");@@ -1853,7 +1894,7 @@ static_assert(offsetof(esengine::ecs::Velocity, angular) == 12, "ABI offset drif// ABI Hash -- runtime handshake against the SDK bundle// =============================================================================-static const char* kEsAbiLayoutHash = "ffbf3c8be66d1354";+static const char* kEsAbiLayoutHash = "2896a68ab5ef40b7";std::string esengineGetAbiLayoutHash() {return std::string(kEsAbiLayoutHash);diff --git a/src/esengine/bindings/WebSDKEntry.cpp b/src/esengine/bindings/WebSDKEntry.cppindex 0a99da79d..84111e297 100644--- a/src/esengine/bindings/WebSDKEntry.cpp+++ b/src/esengine/bindings/WebSDKEntry.cpp@@ -38,6 +38,7 @@#include "../renderer/ImmediateDraw.hpp"#include "../renderer/CustomGeometry.hpp"#include "../resource/ResourceManager.hpp"+#include "../resource/ShaderParser.hpp"#include "../text/SdfGenerator.hpp"#include "../ecs/TransformSystem.hpp"#include "../core/World.hpp"@@ -75,109 +76,141 @@ static EstellaContext& ctx() { return activeCtx(); }#define g_particleSystem (ctx().tryGet<particle::ParticleSystem>())#endif-EM_JS(void, callMaterialProvider, (int materialId, int outShaderIdPtr, int outBlendModePtr, int outUniformBufPtr, int outUniformCountPtr), {- var fn = Module['materialDataProvider'];- if (fn) {- fn(materialId, outShaderIdPtr, outBlendModePtr, outUniformBufPtr, outUniformCountPtr);- } else {- HEAPU32[outShaderIdPtr >> 2] = 0;- HEAPU32[outBlendModePtr >> 2] = 0;- HEAPU32[outUniformBufPtr >> 2] = 0;- HEAPU32[outUniformCountPtr >> 2] = 0;+// Float component count for a std140 param type (textures have no block slot).+static u32 materialParamArity(resource::ShaderPropertyType t) {+ using PT = resource::ShaderPropertyType;+ switch (t) {+ case PT::Float: case PT::Int: return 1;+ case PT::Vec2: return 2;+ case PT::Vec3: return 3;+ case PT::Vec4: case PT::Color: return 4;+ default: return 0;}-});--void clearMaterialCache() { ctx().state().material_cache.clear(); }--void invalidateMaterialCache(u32 materialId) {- ctx().state().material_cache.invalidate(materialId);}-bool getMaterialData(u32 materialId, u32& shaderId, u32& blendMode) {- if (materialId == 0) {- return false;+// Build the engine-side layout from a parsed shader's #pragma param reflection: non-texture+// params into the std140 block (declared order == offset order), texture params into sampler+// slots (their reflected units, >= MATERIAL_TEXTURE_UNIT_BASE).+static MaterialUniformLayout buildMaterialLayout(const resource::ParsedShader& parsed,+ const RenderContext& rc) {+ MaterialUniformLayout layout;+ layout.blockSize = parsed.materialBlockSize;+ for (const auto& p : parsed.properties) {+ if (!p.fromParam) continue;+ if (p.type == resource::ShaderPropertyType::Texture) {+ if (p.textureUnit >= 0) {+ // Resolve the param's `default(<name>)` to a built-in default texture, bound when+ // a material leaves the param unset.+ layout.textures.push_back({ p.name, static_cast<u32>(p.textureUnit),+ rc.defaultTextureByName(p.defaultValue) });+ }+ } else if (p.std140Offset >= 0) {+ layout.params.push_back({ p.name, static_cast<u32>(p.std140Offset), materialParamArity(p.type) });+ }}- u32 uniformBufferPtr = 0;- u32 uniformCount = 0;- auto toPtr = [](auto* p) { return static_cast<int>(reinterpret_cast<uintptr_t>(p)); };- callMaterialProvider(materialId,- toPtr(&shaderId),- toPtr(&blendMode),- toPtr(&uniformBufferPtr),- toPtr(&uniformCount));- return shaderId != 0;-}--bool getMaterialDataWithUniforms(u32 materialId, u32& shaderId, u32& blendMode,- std::vector<MaterialUniformData>& uniforms) {- if (materialId == 0) {- return false;+ return layout;+}++// Compiles a .esshader (material shader) through the full ShaderParser path — assembling the+// auto-generated MaterialConstants block + the requested feature/switch permutation (each+// feature -> `#define NAME 1`) — and registers its param layout. @p featuresCsv is the enabled+// `#pragma switch` set (comma-separated), so a material's static switches select a permutation;+// the SDK loader caches one compiled program per (shader, switch-set). Returns the shader+// resource handle (0 on failure). Reflection-aware replacement for the loader's old regex.+u32 compileEsshader(const std::string& source, const std::string& featuresCsv) {+ auto* rm = g_resourceManager;+ if (!rm) return 0;+ resource::ParsedShader parsed = resource::ShaderParser::parse(source);+ if (!parsed.valid) {+ ES_LOG_ERROR("compileEsshader: parse failed: {}", parsed.errorMessage);+ return 0;}-- auto& cache = ctx().state().material_cache;- const auto* cached = cache.find(materialId);- if (cached) {- shaderId = cached->shaderId;- blendMode = cached->blendMode;- uniforms = cached->uniforms;- return shaderId != 0;+ std::vector<std::string> features;+ for (usize start = 0; start <= featuresCsv.size();) {+ const usize comma = featuresCsv.find(',', start);+ const usize end = comma == std::string::npos ? featuresCsv.size() : comma;+ std::string f = featuresCsv.substr(start, end - start);+ // trim+ const usize a = f.find_first_not_of(" \t");+ const usize b = f.find_last_not_of(" \t");+ if (a != std::string::npos) features.push_back(f.substr(a, b - a + 1));+ if (comma == std::string::npos) break;+ start = comma + 1;}-- u32 uniformBufferPtr = 0;- u32 uniformCount = 0;- auto toPtr = [](auto* p) { return static_cast<int>(reinterpret_cast<uintptr_t>(p)); };- callMaterialProvider(materialId,- toPtr(&shaderId),- toPtr(&blendMode),- toPtr(&uniformBufferPtr),- toPtr(&uniformCount));-- if (shaderId == 0) {- cache.store(materialId, {});- return false;+ const std::string vert = resource::ShaderParser::assembleStage(parsed, resource::ShaderStage::Vertex, "", features);+ const std::string frag = resource::ShaderParser::assembleStage(parsed, resource::ShaderStage::Fragment, "", features);+ resource::ShaderHandle handle = rm->createShader(vert, frag);+ if (!handle.isValid()) return 0;+ if (auto* rc = g_renderContext) {+ if (Shader* s = rm->getShader(handle)) {+ rc->materials().registerLayout(s->getProgramId(), buildMaterialLayout(parsed, *rc));+ // Point each texture param's sampler at its unit, once per program (GLSL ES 300 has+ // no layout(binding=); mirrors the batch path's u_textures setup in RenderFrame).+ s->bind();+ for (const auto& p : parsed.properties) {+ if (p.fromParam && p.type == resource::ShaderPropertyType::Texture && p.textureUnit >= 0) {+ s->setUniform(p.name, static_cast<i32>(p.textureUnit));+ }+ }+ s->unbind();+ }}-- constexpr u32 MAX_UNIFORMS = 64;- if (uniformCount > MAX_UNIFORMS) {- ES_LOG_ERROR("Material {} has {} uniforms (max {}), clamping",- materialId, uniformCount, MAX_UNIFORMS);- uniformCount = MAX_UNIFORMS;+ return handle.id();+}++// Materials are engine-side data: the SDK pushes a material's resolved render state here when+// it is created or edited, and the render path reads it by the handle a component carries+// (Sprite::material, etc.). `shaderHandle` is the SDK shader resource handle, translated here+// to the GL program id the render path binds. flags packs depthTest (bit 0), depthWrite+// (bit 1) and CullMode (bits 2-3). Per-material uniform values arrive via setMaterialUniform.+void defineMaterial(u32 materialId, u32 shaderHandle, u32 blendMode, u32 flags) {+ auto* rc = g_renderContext;+ if (!rc) return;+ u32 programId = 0;+ if (shaderHandle != 0) {+ if (auto* rm = g_resourceManager) {+ if (Shader* s = rm->getShader(resource::ShaderHandle(shaderHandle))) {+ programId = s->getProgramId();+ }+ }}-- if (uniformCount > 0 && uniformBufferPtr != 0) {- const u8* ptr = reinterpret_cast<const u8*>(uniformBufferPtr);- constexpr usize MAX_BUFFER_SIZE = MAX_UNIFORMS * (4 + 256 + 4 + 16);- const u8* bufferEnd = ptr + MAX_BUFFER_SIZE;-- for (u32 i = 0; i < uniformCount; ++i) {- if (ptr + 4 > bufferEnd) break;- u32 nameLen = *reinterpret_cast<const u32*>(ptr);- ptr += 4;-- if (nameLen > 256) break;- usize alignedNameLen = ((nameLen + 3) / 4) * 4;- if (ptr + alignedNameLen > bufferEnd) break;-- MaterialUniformData ud;- usize copyLen = std::min<usize>(nameLen, 31);- std::memcpy(ud.name, reinterpret_cast<const char*>(ptr), copyLen);- ud.name[copyLen] = '\0';- ptr += alignedNameLen;-- if (ptr + 4 > bufferEnd) break;- ud.type = *reinterpret_cast<const u32*>(ptr);- ptr += 4;-- if (ptr + 16 > bufferEnd) break;- std::memcpy(ud.values, ptr, 16);- ptr += 16;-- uniforms.push_back(ud);+ MaterialRecord rec;+ rec.shader = programId;+ rec.blend = static_cast<BlendMode>(blendMode);+ rec.depthTest = (flags & 0x1u) != 0;+ rec.depthWrite = (flags & 0x2u) != 0;+ rec.cull = static_cast<CullMode>((flags >> 2) & 0x3u);+ rc->materials().define(materialId, rec);+}++// Packs a named param's float components into the material's std140 buffer (by reflected+// offset). A no-op for materials whose shader declares no matching #pragma param.+void setMaterialUniform(u32 materialId, const std::string& name, u32 arity,+ f32 v0, f32 v1, f32 v2, f32 v3) {+ auto* rc = g_renderContext;+ if (!rc) return;+ const f32 vals[4] = { v0, v1, v2, v3 };+ rc->materials().setUniform(materialId, name, vals, arity);+}++// Binds a texture param to its sampler unit. `textureHandle` is the SDK texture resource+// handle, resolved here to the GL texture id the render path binds. No-op for an unknown param.+void setMaterialTexture(u32 materialId, const std::string& name, u32 textureHandle) {+ auto* rc = g_renderContext;+ if (!rc) return;+ u32 glTex = 0;+ if (textureHandle != 0) {+ if (auto* rm = g_resourceManager) {+ if (Texture* t = rm->getTexture(resource::TextureHandle(textureHandle))) {+ glTex = t->getId();+ }}}+ rc->materials().setTexture(materialId, name, glTex);+}- cache.store(materialId, { shaderId, blendMode, uniforms });- return true;+void undefineMaterial(u32 materialId) {+ if (auto* rc = g_renderContext) rc->materials().undefine(materialId);}bool initRendererInternal(const char* canvasSelector) {@@ -380,8 +413,11 @@ EMSCRIPTEN_BINDINGS(esengine_renderer) {#endifemscripten::function("renderer_submitTextBatch", &esengine::renderer_submitTextBatch);- emscripten::function("invalidateMaterialCache", &esengine::invalidateMaterialCache);- emscripten::function("clearMaterialCache", &esengine::clearMaterialCache);+ emscripten::function("compileEsshader", &esengine::compileEsshader);+ emscripten::function("defineMaterial", &esengine::defineMaterial);+ emscripten::function("setMaterialUniform", &esengine::setMaterialUniform);+ emscripten::function("setMaterialTexture", &esengine::setMaterialTexture);+ emscripten::function("undefineMaterial", &esengine::undefineMaterial);emscripten::function("draw_begin", &esengine::draw_begin);emscripten::function("draw_end", &esengine::draw_end);@@ -517,6 +553,11 @@ EMSCRIPTEN_BINDINGS(esengine_renderer) {emscripten::function("renderer_getSnapshotSize", &esengine::renderer_getSnapshotSize);emscripten::function("renderer_getSnapshotWidth", &esengine::renderer_getSnapshotWidth);emscripten::function("renderer_getSnapshotHeight", &esengine::renderer_getSnapshotHeight);+ emscripten::function("renderer_renderMaterialPreview", &esengine::renderer_renderMaterialPreview);+ emscripten::function("renderer_getPreviewPtr", &esengine::renderer_getPreviewPtr);+ emscripten::function("renderer_getPreviewSize", &esengine::renderer_getPreviewSize);+ emscripten::function("renderer_getPreviewWidth", &esengine::renderer_getPreviewWidth);+ emscripten::function("renderer_getPreviewHeight", &esengine::renderer_getPreviewHeight);emscripten::function("renderer_setTextureParams", &esengine::renderer_setTextureParams);}diff --git a/src/esengine/ecs/components/Light2D.hpp b/src/esengine/ecs/components/Light2D.hppnew file mode 100644index 000000000..b9e11d9fe--- /dev/null+++ b/src/esengine/ecs/components/Light2D.hpp@@ -0,0 +1,85 @@+// SPDX-License-Identifier: LicenseRef-PolyForm-Noncommercial-1.0.0+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team+/**+ * @file Light2D.hpp+ * @brief 2D light source component for the Lit2D material domain.+ * @details A scene's Light2D components are gathered by the render collect path into the+ * per-frame LightConstants UBO (binding 2); Lit2D-domain material shaders read them+ * via the injected es_applyLighting2D() helper. Point/Directional lights occupy a+ * light slot; Ambient lights sum into the ambient term. World position comes from the+ * entity's Transform — this component carries only the light's intrinsic parameters.+ *+ * @author ESEngine Team+ * @date 2026+ *+ * @copyright Copyright (c) 2026 ESEngine Team+ * Licensed under the PolyForm Noncommercial License 1.0.0.+ */+#pragma once++#include "../../core/Types.hpp"+#include "../../core/Reflection.hpp"+#include "../../math/Math.hpp"++namespace esengine::ecs {++/**+ * @brief 2D light kind. Point uses the Transform position + radius falloff; Directional uses+ * `direction` with no attenuation; Ambient adds a flat term independent of normal/position.+ */+enum class Light2DType : i32 {+ Point = 0,+ Directional = 1,+ Ambient = 2,+ Spot = 3,+};++/**+ * @brief A 2D light contributing to Lit2D-shaded materials.+ *+ * @code+ * auto& light = registry.emplace<Light2D>(e);+ * light.type = static_cast<i32>(Light2DType::Directional);+ * light.color = {0, 1, 0}; // green+ * light.intensity = 1.0f;+ * @endcode+ */+ES_COMPONENT()+struct Light2D {+ /** @brief Light kind: 0 = Point, 1 = Directional, 2 = Ambient (see Light2DType). */+ ES_PROPERTY()+ i32 type{0};++ /** @brief Light color, multiplied by intensity. RGBA for editor color-picker consistency+ * with every other engine color (Sprite/Shape/Text); the alpha is unused (a light's+ * strength is `intensity`, which can exceed 1 for HDR). */+ ES_PROPERTY(animatable)+ glm::vec4 color{1.0f, 1.0f, 1.0f, 1.0f};++ /** @brief Light strength multiplier. */+ ES_PROPERTY(animatable)+ f32 intensity{1.0f};++ /** @brief Point/Spot falloff radius in world units (ignored by Directional/Ambient). */+ ES_PROPERTY(animatable)+ f32 radius{200.0f};++ /** @brief Direction in the 2D plane: Directional light direction, or Spot cone axis+ * ({0,0} = straight at the screen / cone aims down). Ignored by Point/Ambient. */+ ES_PROPERTY()+ glm::vec2 direction{0.0f, 0.0f};++ /** @brief Spot inner cone angle in degrees (full angle; fully lit inside). */+ ES_PROPERTY(animatable)+ f32 innerAngle{30.0f};++ /** @brief Spot outer cone angle in degrees (full angle; fades to dark by here). */+ ES_PROPERTY(animatable)+ f32 outerAngle{45.0f};++ /** @brief Disabled lights are skipped during collection. */+ ES_PROPERTY()+ bool enabled{true};+};++} // namespace esengine::ecsdiff --git a/src/esengine/renderer/BatchBuilder.cpp b/src/esengine/renderer/BatchBuilder.cppindex 96dc39bf8..bacaba2d4 100644--- a/src/esengine/renderer/BatchBuilder.cpp+++ b/src/esengine/renderer/BatchBuilder.cpp@@ -50,7 +50,7 @@ void pushBatchDraw(DrawList& drawList, const ClipState& clips,DrawCommand cmd{};cmd.sort_key = DrawCommand::buildSortKey(key.stage, key.layer, key.shaderId,- key.blend, 0, key.depth);+ key.blend, 0, key.depth, key.materialId);cmd.index_offset = indexOffset;cmd.index_count = indexCount;cmd.vertex_byte_offset = vertexByteOffset;@@ -58,6 +58,10 @@ void pushBatchDraw(DrawList& drawList, const ClipState& clips,cmd.shader_id = key.shaderId;cmd.blend_mode = key.blend;cmd.layout_id = LayoutId::Batch;+ cmd.material_id = key.materialId;+ cmd.depth_test = key.depthTest;+ cmd.depth_write = key.depthWrite;+ cmd.cull = key.cull;cmd.texture_count = 1;cmd.texture_ids[0] = key.textureId;cmd.entity = key.entity;diff --git a/src/esengine/renderer/BatchBuilder.hpp b/src/esengine/renderer/BatchBuilder.hppindex d475f42af..8b835597e 100644--- a/src/esengine/renderer/BatchBuilder.hpp+++ b/src/esengine/renderer/BatchBuilder.hpp@@ -81,6 +81,11 @@ struct BatchDrawKey {f32 depth = 0.0f;Entity entity = INVALID_ENTITY;RenderType type = RenderType::Sprite;+ // Material handle + the render state resolved from it (defaults when materialId == 0).+ u32 materialId = 0;+ bool depthTest = false;+ bool depthWrite = true;+ u8 cull = 0; ///< CullMode: 0 = none, 1 = back, 2 = front.};/**diff --git a/src/esengine/renderer/DrawCommand.hpp b/src/esengine/renderer/DrawCommand.hppindex 58d50bc51..d40accf78 100644--- a/src/esengine/renderer/DrawCommand.hpp+++ b/src/esengine/renderer/DrawCommand.hpp@@ -31,6 +31,15 @@ struct DrawCommand {BlendMode blend_mode = BlendMode::Normal;LayoutId layout_id = LayoutId::Batch;+ // The material handle this draw resolved from (0 = none). Identity for sort + merge so+ // distinct materials never coalesce, and the lookup key for per-material GPU state.+ u32 material_id = 0;+ // Pipeline depth/cull state, resolved from the material (or defaults). depth_write stays+ // on with the test off — the engine's 2D state — unless a material overrides it.+ bool depth_test = false;+ bool depth_write = true;+ u8 cull = 0; ///< CullMode: 0 = none, 1 = back, 2 = front.+u8 texture_count = 0;u32 texture_ids[MAX_CMD_TEXTURE_SLOTS] = {};@@ -55,8 +64,10 @@ struct DrawCommand {// Texture is no longer part of the sort key: dropping it lets draws that differ only// by texture sort adjacent and coalesce into one multi-texture batch (up to 8 textures,// selected per-vertex in the shader). Order within a layer is otherwise unchanged.+ // Material identity sorts above depth (like shader does) so same-material draws group+ // adjacent for the merge, at the usual batching-over-cross-material-depth tradeoff.static u64 buildSortKey(RenderStage stage, i32 layer, u32 shaderId,- BlendMode blend, u16 stateFlags, f32 depth) {+ BlendMode blend, u16 stateFlags, f32 depth, u32 materialId = 0) {u64 stageKey = static_cast<u64>(stage) << 60;i32 normalizedLayer = std::clamp(layer + 32768, 0, 65535);@@ -65,6 +76,7 @@ struct DrawCommand {u64 shaderKey = static_cast<u64>(shaderId & 0xFF) << 36;u64 blendKey = static_cast<u64>(blend) << 33;u64 flagsKey = static_cast<u64>(stateFlags & 0x03) << 31;+ u64 materialKey = (static_cast<u64>(materialId) & 0x1FFFF) << 14;u32 depthBits;if (stage == RenderStage::Transparent || stage == RenderStage::Overlay) {@@ -76,7 +88,7 @@ struct DrawCommand {}u64 depthKey = static_cast<u64>(depthBits & 0x3FFF);- return stageKey | layerKey | shaderKey | blendKey | flagsKey | depthKey;+ return stageKey | layerKey | shaderKey | blendKey | flagsKey | materialKey | depthKey;}/** @brief Finds @p texId in this command's texture set, adds it (returns its slot), or@@ -96,6 +108,9 @@ struct DrawCommand {if (shader_id != next.shader_id) return false;if (blend_mode != next.blend_mode) return false;if (layout_id != next.layout_id) return false;+ // Same material handle => same uniforms/textures/depth/cull; different ones must not+ // coalesce. material_id 0 (no material) shares the path's defaults, so they still merge.+ if (material_id != next.material_id) return false;if (state_flags != next.state_flags) return false;if (state_flags & CMD_STATE_SCISSOR) {if (scissor != next.scissor) return false;diff --git a/src/esengine/renderer/DrawList.cpp b/src/esengine/renderer/DrawList.cppindex 40523222c..6baf8a35e 100644--- a/src/esengine/renderer/DrawList.cpp+++ b/src/esengine/renderer/DrawList.cpp@@ -2,6 +2,7 @@// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team#include "DrawList.hpp"#include "BatchVertex.hpp"+#include "MaterialStore.hpp"#include <glm/glm.hpp>#include <algorithm>@@ -98,7 +99,7 @@ void DrawList::finalize(TransientBufferPool& pool) {}void DrawList::execute(GfxDevice& device, TransientBufferPool& buffers,- FrameCapture* capture) {+ MaterialStore& materials, FrameCapture* capture) {PipelineDesc lastDesc{};PipelineHandle lastHandle = PipelineHandle::Invalid;@@ -109,18 +110,19 @@ void DrawList::execute(GfxDevice& device, TransientBufferPool& buffers,if (cmd.state_flags & CMD_STATE_STENCIL_WRITE) stencil = GfxStencilMode::Write;else if (cmd.state_flags & CMD_STATE_STENCIL_TEST) stencil = GfxStencilMode::Test;- // Resolve the immutable pipeline. depthWrite stays on with the test off, matching- // the engine's 2D state. createPipeline caches; a one-entry memo skips the lookup- // for the common run of identical consecutive (sorted) commands.+ // Resolve the immutable pipeline. Depth/cull come from the command (resolved from+ // its material, or the 2D defaults: depth_write on with the test off). createPipeline+ // caches; a one-entry memo skips the lookup for identical consecutive (sorted) commands.PipelineDesc desc{};desc.program = cmd.shader_id;desc.vertexLayout = cmd.layout_id;desc.blend = cmd.blend_mode;desc.blendEnabled = true;- desc.depthTest = false;- desc.depthWrite = true;+ desc.depthTest = cmd.depth_test;+ desc.depthWrite = cmd.depth_write;desc.stencil = stencil;- desc.cullEnabled = false;+ desc.cullEnabled = cmd.cull != 0;+ desc.cullFront = cmd.cull == 2;if (lastHandle == PipelineHandle::Invalid || !(desc == lastDesc)) {lastHandle = device.createPipeline(desc);@@ -128,6 +130,12 @@ void DrawList::execute(GfxDevice& device, TransientBufferPool& buffers,}device.setPipeline(lastHandle);+ // Per-material constants (binding 1): upload-if-dirty + bind this draw's material UBO.+ // A no-op for material 0 and for materials whose shader declares no params.+ if (cmd.material_id != 0) {+ materials.bindForDraw(cmd.material_id);+ }+// Dynamic per-draw state (sorted+merged draws already group these coarsely).if (cmd.state_flags & CMD_STATE_SCISSOR) {device.setScissorTest(true);diff --git a/src/esengine/renderer/DrawList.hpp b/src/esengine/renderer/DrawList.hppindex 8cd8d8a38..56e4a9ece 100644--- a/src/esengine/renderer/DrawList.hpp+++ b/src/esengine/renderer/DrawList.hpp@@ -12,6 +12,8 @@namespace esengine {+class MaterialStore;+class DrawList {public:void clear();@@ -25,9 +27,10 @@ public:// Each merged command resolves to an immutable pipeline (program + layout + blend +// depth + stencil + cull) bound via GfxDevice::setPipeline; per-draw dynamic state// (scissor, stencil ref, textures) is applied directly. Per-frame constants come from- // the FrameConstants UBO bound by RenderContext.+ // the FrameConstants UBO bound by RenderContext; per-material constants from each+ // command's material UBO, bound here via MaterialStore::bindForDraw.void execute(GfxDevice& device, TransientBufferPool& buffers,- FrameCapture* capture = nullptr);+ MaterialStore& materials, FrameCapture* capture = nullptr);u32 commandCount() const { return static_cast<u32>(commands_.size()); }u32 mergedDrawCallCount() const { return merged_draw_calls_; }diff --git a/src/esengine/renderer/LightConstants.hpp b/src/esengine/renderer/LightConstants.hppnew file mode 100644index 000000000..08f6f4206--- /dev/null+++ b/src/esengine/renderer/LightConstants.hpp@@ -0,0 +1,64 @@+// SPDX-License-Identifier: LicenseRef-PolyForm-Noncommercial-1.0.0+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team+/**+ * @file LightConstants.hpp+ * @brief Per-frame 2D lighting constants — the third tier of the engine's constant-buffer+ * layering (after per-frame FrameConstants at 0 and per-material MaterialConstants at 1).+ * @details A Lit2D-domain material shader (#pragma domain Lit2D) gets a `layout(std140) uniform+ * LightConstants { ... }` block auto-injected by ShaderParser, and Shader::compile links+ * it to LIGHT_CONSTANTS_BINDING. LightStore (owned by RenderContext) collects the scene's+ * Light2D components into this CPU mirror each frame and uploads it once. The GLSL struct+ * layout MUST match this std140 mirror exactly — a mismatch silently corrupts lighting.+ */+#pragma once++#include "../core/Types.hpp"++#include <glm/glm.hpp>++namespace esengine {++/** @brief Indexed UBO binding point for the per-frame LightConstants block. */+inline constexpr u32 LIGHT_CONSTANTS_BINDING = 2;++/** @brief GLSL block name; must match ShaderParser's injected block + Shader::compile lookup. */+inline constexpr const char* LIGHT_CONSTANTS_BLOCK = "LightConstants";++/**+ * @brief Max simultaneous 2D lights packed into the UBO. The injected fragment loop is a fixed+ * bound; inactive slots are zeroed (intensity 0) so they contribute nothing. Must match+ * the `u_lights[..]` array size in ShaderParser's injected GLSL.+ */+inline constexpr u32 MAX_LIGHTS_2D = 16;++/**+ * @brief One 2D light, std140-packed (three vec4s, 48 bytes, 16-aligned).+ * @details posDir: xy = world position (point/spot) or direction (directional); z = type+ * (0 = point, 1 = directional, 2 = spot); w = falloff radius (point/spot, world units).+ * color: rgb = light color, a = intensity.+ * spot: xy = normalized cone axis, z = cos(innerHalfAngle), w = cos(outerHalfAngle)+ * (spot only; zero for other types). Ambient lights are folded into+ * LightConstants::ambient instead of occupying a slot.+ */+struct GpuLight2D {+ glm::vec4 posDir{0.0f};+ glm::vec4 color{0.0f};+ glm::vec4 spot{0.0f};+};++/**+ * @brief CPU mirror of the GLSL LightConstants block (std140).+ * @details ambient: rgb = summed ambient color, a = active light count (informational).+ * std140 array-of-struct stride is 32 (each GpuLight2D is already 16-aligned), so+ * lights start at offset 16 and the whole block is 16 + 32*MAX_LIGHTS_2D bytes.+ */+struct LightConstants {+ glm::vec4 ambient{0.0f};+ GpuLight2D lights[MAX_LIGHTS_2D];+};++static_assert(sizeof(GpuLight2D) == 48, "GpuLight2D must be std140-tight (three vec4s)");+static_assert(sizeof(LightConstants) == 16 + 48 * MAX_LIGHTS_2D,+ "LightConstants must match the std140 GLSL block layout");++} // namespace esenginediff --git a/src/esengine/renderer/LightStore.cpp b/src/esengine/renderer/LightStore.cppnew file mode 100644index 000000000..3c161214a--- /dev/null+++ b/src/esengine/renderer/LightStore.cpp@@ -0,0 +1,37 @@+// SPDX-License-Identifier: LicenseRef-PolyForm-Noncommercial-1.0.0+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team+/**+ * @file LightStore.cpp+ * @brief GPU-touching parts of LightStore (the per-frame lighting UBO lifecycle + binding).+ */+#include "LightStore.hpp"++#include "GfxDevice.hpp"+#include "GfxEnums.hpp"++namespace esengine {++void LightStore::uploadAndBind() {+ if (!device_) return;++ if (ubo_ == 0) {+ ubo_ = device_->createBuffer();+ dirty_ = true;+ }+ device_->bindUniformBuffer(ubo_);+ if (dirty_) {+ device_->bufferData(GfxBufferTarget::Uniform, &data_, sizeof(LightConstants), /*dynamic=*/true);+ dirty_ = false;+ }+ device_->bindBufferBase(LIGHT_CONSTANTS_BINDING, ubo_);+}++void LightStore::free() {+ if (ubo_ != 0 && device_) {+ device_->deleteBuffer(ubo_);+ ubo_ = 0;+ }+ dirty_ = true;+}++} // namespace esenginediff --git a/src/esengine/renderer/LightStore.hpp b/src/esengine/renderer/LightStore.hppnew file mode 100644index 000000000..0fb125281--- /dev/null+++ b/src/esengine/renderer/LightStore.hpp@@ -0,0 +1,81 @@+// SPDX-License-Identifier: LicenseRef-PolyForm-Noncommercial-1.0.0+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team+/**+ * @file LightStore.hpp+ * @brief Engine-side 2D light registry — the per-frame LightConstants UBO and its CPU mirror.+ * @details The render collect path clears this each frame, then accumulates the scene's enabled+ * Light2D components into it (point/directional into the lights array, ambient summed+ * into the ambient term). flush() uploads the mirror once and binds it at+ * LIGHT_CONSTANTS_BINDING, so every Lit2D shader reads the same lighting UBO. Owned by+ * RenderContext so both the render path and any future SDK push reach one store / one UBO.+ *+ * @author ESEngine Team+ * @date 2026+ *+ * @copyright Copyright (c) 2026 ESEngine Team+ * Licensed under the PolyForm Noncommercial License 1.0.0.+ */+#pragma once++#include "LightConstants.hpp"++#include <glm/glm.hpp>++namespace esengine {++class GfxDevice;++/**+ * @brief Holds the per-frame 2D lights and their GPU UBO. Mirrors MaterialStore's UBO lifecycle+ * (lazy create, dirty upload, device-owned free).+ */+class LightStore {+public:+ /// The render path uses this device to create/upload/delete the lighting UBO.+ void setDevice(GfxDevice* device) { device_ = device; }++ /// Begins a frame's collection: zeroes ambient + all light slots (inactive slots contribute+ /// nothing because their intensity is 0) and marks the UBO for re-upload.+ void clear() {+ data_ = LightConstants{};+ count_ = 0;+ dirty_ = true;+ }++ /// Adds an ambient term (rgb already scaled by intensity). Ambient lights sum rather than+ /// occupy a slot. The alpha tracks the active non-ambient light count for shader early-out.+ void addAmbient(const glm::vec3& color) {+ data_.ambient.x += color.x;+ data_.ambient.y += color.y;+ data_.ambient.z += color.z;+ dirty_ = true;+ }++ /// Appends a point/directional light. Silently drops past MAX_LIGHTS_2D (the fixed shader loop+ /// bound); callers keep the most significant lights first if they exceed the cap.+ void addLight(const GpuLight2D& light) {+ if (count_ >= MAX_LIGHTS_2D) return;+ data_.lights[count_++] = light;+ data_.ambient.w = static_cast<f32>(count_);+ dirty_ = true;+ }++ /// Uploads the mirror (when dirty) and binds it at LIGHT_CONSTANTS_BINDING. Called once per+ /// frame in flush(); the binding persists, only the contents change. No-op without a device.+ void uploadAndBind();++ /// Frees the GPU UBO. Call while the device is still valid (RenderContext::shutdown).+ void free();++ u32 count() const { return count_; }+ const LightConstants& data() const { return data_; }++private:+ LightConstants data_{};+ u32 count_ = 0;+ u32 ubo_ = 0;+ bool dirty_ = true;+ GfxDevice* device_ = nullptr;+};++} // namespace esenginediff --git a/src/esengine/renderer/MaterialConstants.hpp b/src/esengine/renderer/MaterialConstants.hppnew file mode 100644index 000000000..7eedb3694--- /dev/null+++ b/src/esengine/renderer/MaterialConstants.hpp@@ -0,0 +1,28 @@+// SPDX-License-Identifier: LicenseRef-PolyForm-Noncommercial-1.0.0+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team+/**+ * @file MaterialConstants.hpp+ * @brief Binding points for per-material shader constants — the second tier of the+ * engine's constant-buffer layering (after per-frame FrameConstants at binding 0).+ * @details A material shader authored with `#pragma param` gets a `layout(std140) uniform+ * MaterialConstants { ... }` block auto-generated by ShaderParser; Shader::compile+ * links it to MATERIAL_CONSTANTS_BINDING, and the render path binds the material's+ * UBO there per draw. Material texture parameters get sampler units starting at+ * MATERIAL_TEXTURE_UNIT_BASE, above the batch path's 0..7 multi-texture slots.+ */+#pragma once++#include "../core/Types.hpp"++namespace esengine {++/** @brief Indexed UBO binding point for the per-material MaterialConstants block. */+inline constexpr u32 MATERIAL_CONSTANTS_BINDING = 1;++/** @brief GLSL block name; must match ShaderParser's generated block + Shader::compile lookup. */+inline constexpr const char* MATERIAL_CONSTANTS_BLOCK = "MaterialConstants";++/** @brief First sampler unit a material texture parameter may use (batch owns units 0..7). */+inline constexpr u32 MATERIAL_TEXTURE_UNIT_BASE = 8;++} // namespace esenginediff --git a/src/esengine/renderer/MaterialStore.cpp b/src/esengine/renderer/MaterialStore.cppnew file mode 100644index 000000000..a99d3affe--- /dev/null+++ b/src/esengine/renderer/MaterialStore.cpp@@ -0,0 +1,69 @@+// SPDX-License-Identifier: LicenseRef-PolyForm-Noncommercial-1.0.0+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team+/**+ * @file MaterialStore.cpp+ * @brief GPU-touching parts of MaterialStore (per-material UBO lifecycle + binding).+ */+#include "MaterialStore.hpp"++#include "GfxDevice.hpp"+#include "GfxEnums.hpp"+#include "MaterialConstants.hpp"++namespace esengine {++void MaterialStore::undefine(u32 materialId) {+ auto it = materials_.find(materialId);+ if (it == materials_.end()) return;+ if (it->second.ubo != 0 && device_) device_->deleteBuffer(it->second.ubo);+ materials_.erase(it);+}++void MaterialStore::clear() {+ if (device_) {+ for (auto& [id, rec] : materials_) {+ if (rec.ubo != 0) device_->deleteBuffer(rec.ubo);+ }+ }+ materials_.clear();+ layouts_.clear();+}++void MaterialStore::bindForDraw(u32 materialId) {+ if (!device_) return;+ auto it = materials_.find(materialId);+ if (it == materials_.end()) return;+ MaterialRecord& rec = it->second;++ // Per-material constants UBO (binding 1) — present only when the shader declares params.+ if (!rec.uboBytes.empty()) {+ if (rec.ubo == 0) {+ rec.ubo = device_->createBuffer();+ rec.uboDirty = true;+ }+ device_->bindUniformBuffer(rec.ubo);+ if (rec.uboDirty) {+ device_->bufferData(GfxBufferTarget::Uniform, rec.uboBytes.data(),+ static_cast<u32>(rec.uboBytes.size()), /*dynamic=*/true);+ rec.uboDirty = false;+ }+ device_->bindBufferBase(MATERIAL_CONSTANTS_BINDING, rec.ubo);+ }++ // Texture params — bound to their sampler units (>= MATERIAL_TEXTURE_UNIT_BASE), above the+ // batch path's 0..7. Iterate the shader's layout (not just the material's explicit bindings)+ // so an unset param binds its declared default (white/black/flatnormal) instead of sampling+ // whatever stale texture is at the unit.+ auto lit = layouts_.find(rec.shader);+ if (lit != layouts_.end()) {+ for (const auto& slot : lit->second.textures) {+ u32 glTexture = slot.defaultGlTexture;+ for (const auto& b : rec.textures) {+ if (b.unit == slot.unit) { glTexture = b.glTexture; break; }+ }+ if (glTexture != 0) device_->bindTexture(slot.unit, glTexture);+ }+ }+}++} // namespace esenginediff --git a/src/esengine/renderer/MaterialStore.hpp b/src/esengine/renderer/MaterialStore.hppnew file mode 100644index 000000000..a87cd3d00--- /dev/null+++ b/src/esengine/renderer/MaterialStore.hpp@@ -0,0 +1,205 @@+// SPDX-License-Identifier: LicenseRef-PolyForm-Noncommercial-1.0.0+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team+/**+ * @file MaterialStore.hpp+ * @brief Engine-side material registry — the resolved "how to draw" for a material handle.+ * @details A material is a first-class engine object: the SDK pushes its resolved render+ * state here (defineMaterial) when the material is created or edited, and the+ * render path looks it up by the handle a component carries (e.g. Sprite::material).+ * This replaces the dead pull-callback + cache, where C++ called back into JS per+ * material and the resolved data never reached a draw.+ *+ * Per-material shader parameters live in a std140 MaterialConstants UBO (binding 1):+ * a shader authored with `#pragma param` registers its layout here, and setUniform+ * packs named values into the material's byte buffer by reflected offset. The render+ * path uploads (when dirty) and binds that UBO per draw via bindForDraw.+ *+ * @author ESEngine Team+ * @date 2026+ *+ * @copyright Copyright (c) 2026 ESEngine Team+ * Licensed under the PolyForm Noncommercial License 1.0.0.+ */+#pragma once++#include "../core/Types.hpp"+#include "BlendMode.hpp"++#include <algorithm>+#include <cstring>+#include <string>+#include <unordered_map>+#include <vector>++namespace esengine {++class GfxDevice;++/** @brief Triangle culling mode baked into a material's pipeline. */+enum class CullMode : u8 {+ None = 0,+ Back = 1,+ Front = 2,+};++/** @brief One scalar/vector param's slot in a shader's std140 MaterialConstants block. */+struct MaterialParamSlot {+ std::string name;+ u32 offset = 0; ///< std140 byte offset within the block.+ u32 arity = 1; ///< Float component count (1..4); textures are not slots.+};++/** @brief A texture param's sampler unit (>= MATERIAL_TEXTURE_UNIT_BASE, above the batch's 0..7). */+struct MaterialTextureSlot {+ std::string name;+ u32 unit = 0;+ /// GL texture bound when a material leaves this param unset — the shader's declared+ /// `default(white|black|flatnormal)`. Resolved once when the layout is registered.+ u32 defaultGlTexture = 0;+};++/** @brief A material's bound texture: the GL texture id at a sampler unit. */+struct MaterialTextureBinding {+ u32 unit = 0;+ u32 glTexture = 0;+};++/** @brief A shader's layout: std140 block (scalar/vector params) + texture sampler slots. */+struct MaterialUniformLayout {+ u32 blockSize = 0;+ std::vector<MaterialParamSlot> params;+ std::vector<MaterialTextureSlot> textures;++ const MaterialParamSlot* find(const std::string& name) const {+ for (const auto& p : params) {+ if (p.name == name) return &p;+ }+ return nullptr;+ }+ const MaterialTextureSlot* findTexture(const std::string& name) const {+ for (const auto& t : textures) {+ if (t.name == name) return &t;+ }+ return nullptr;+ }+};++/**+ * @brief A material's resolved render state (P0) plus its packed std140 constants (P1).+ */+struct MaterialRecord {+ u32 shader = 0; ///< Shader program; 0 means "use the path's default batch shader".+ BlendMode blend = BlendMode::Normal;+ bool depthTest = false;+ bool depthWrite = true;+ CullMode cull = CullMode::None;++ /// Packed std140 MaterialConstants payload (sized to the shader's blockSize), the GPU+ /// UBO it uploads to (lazy), and whether the bytes changed since the last upload.+ std::vector<u8> uboBytes;+ u32 ubo = 0;+ bool uboDirty = false;++ /// Texture params bound to sampler units (GL texture ids, resolved at set time).+ std::vector<MaterialTextureBinding> textures;+};++/**+ * @brief Maps a material handle to its resolved record. Owned by RenderContext so it is+ * reachable from both the SDK binding (push) and the render collect path (read).+ */+class MaterialStore {+public:+ /// The render path uses this device to create/upload/delete per-material UBOs.+ void setDevice(GfxDevice* device) { device_ = device; }++ /// Registers (or replaces) a shader's MaterialConstants layout — called when a shader+ /// authored with #pragma param is compiled, so materials on it can pack their uniforms.+ void registerLayout(u32 shaderId, MaterialUniformLayout layout) {+ if (shaderId != 0) layouts_[shaderId] = std::move(layout);+ }++ /// Pushes a material's resolved render state. Preserves any already-packed constants+ /// (an edit such as setBlendMode re-pushes state without clobbering uniforms); a shader+ /// change invalidates the old constants since the layout differs.+ void define(u32 materialId, const MaterialRecord& record) {+ if (materialId == 0) return;+ auto it = materials_.find(materialId);+ if (it == materials_.end()) {+ materials_[materialId] = record;+ return;+ }+ MaterialRecord& rec = it->second;+ const bool shaderChanged = rec.shader != record.shader;+ const u32 ubo = rec.ubo;+ std::vector<u8> bytes = std::move(rec.uboBytes);+ std::vector<MaterialTextureBinding> texs = std::move(rec.textures);+ rec = record; // render state+ rec.ubo = ubo; // keep the GPU buffer+ if (shaderChanged) {+ rec.uboBytes.clear(); // old layout invalid; re-packed on next set+ rec.textures.clear();+ } else {+ rec.uboBytes = std::move(bytes);+ rec.textures = std::move(texs);+ }+ rec.uboDirty = true; // re-upload on next bind+ }++ /// Writes a named param's float components into the material's std140 buffer at the+ /// offset its shader's layout reflects. No-op if the material/layout/param is unknown.+ void setUniform(u32 materialId, const std::string& name, const f32* values, u32 arity) {+ auto it = materials_.find(materialId);+ if (it == materials_.end()) return;+ MaterialRecord& rec = it->second;+ auto lit = layouts_.find(rec.shader);+ if (lit == layouts_.end()) return;+ const MaterialParamSlot* slot = lit->second.find(name);+ if (!slot) return;+ if (rec.uboBytes.size() < lit->second.blockSize) {+ rec.uboBytes.resize(lit->second.blockSize, 0);+ }+ const u32 n = std::min(arity, slot->arity);+ std::memcpy(rec.uboBytes.data() + slot->offset, values, n * sizeof(f32));+ rec.uboDirty = true;+ }++ /// Binds a GL texture id to a named texture param's sampler unit. No-op if the material,+ /// its layout, or the texture param is unknown. Render path binds it in bindForDraw.+ void setTexture(u32 materialId, const std::string& name, u32 glTexture) {+ auto it = materials_.find(materialId);+ if (it == materials_.end()) return;+ auto lit = layouts_.find(it->second.shader);+ if (lit == layouts_.end()) return;+ const MaterialTextureSlot* slot = lit->second.findTexture(name);+ if (!slot) return;+ for (auto& b : it->second.textures) {+ if (b.unit == slot->unit) { b.glTexture = glTexture; return; }+ }+ it->second.textures.push_back({ slot->unit, glTexture });+ }++ void undefine(u32 materialId);++ /// The record for @p materialId, or nullptr if the handle is 0 / unregistered.+ const MaterialRecord* find(u32 materialId) const {+ if (materialId == 0) return nullptr;+ auto it = materials_.find(materialId);+ return it != materials_.end() ? &it->second : nullptr;+ }++ /// Uploads (when dirty) and binds the material's MaterialConstants UBO at binding 1.+ /// No-op for materials whose shader declares no params (uboBytes stays empty).+ void bindForDraw(u32 materialId);++ /// Frees every per-material GPU UBO and clears all records/layouts. Call while the+ /// device is still valid (RenderContext::shutdown).+ void clear();++private:+ std::unordered_map<u32, MaterialRecord> materials_;+ std::unordered_map<u32, MaterialUniformLayout> layouts_;+ GfxDevice* device_ = nullptr;+};++} // namespace esenginediff --git a/src/esengine/renderer/RenderContext.cpp b/src/esengine/renderer/RenderContext.cppindex 7c1a9b9b7..95178b9b0 100644--- a/src/esengine/renderer/RenderContext.cpp+++ b/src/esengine/renderer/RenderContext.cpp@@ -37,8 +37,10 @@ void RenderContext::init() {}device_.init();- initWhiteTexture();+ initDefaultTextures();initFrameUbo();+ materials_.setDevice(&device_);+ lights_.setDevice(&device_);initialized_ = true;}@@ -48,9 +50,11 @@ void RenderContext::shutdown() {return;}- if (whiteTextureId_ != 0) {- device_.deleteTexture(whiteTextureId_);- whiteTextureId_ = 0;+ for (u32* tex : {&whiteTextureId_, &blackTextureId_, &flatNormalTextureId_}) {+ if (*tex != 0) {+ device_.deleteTexture(*tex);+ *tex = 0;+ }}if (frameUbo_ != 0) {@@ -58,20 +62,35 @@ void RenderContext::shutdown() {frameUbo_ = 0;}+ materials_.clear(); // free per-material UBOs while the device is still valid+ lights_.free(); // free the lighting UBO while the device is still valid+device_.shutdown();initialized_ = false;ES_LOG_INFO("RenderContext shutdown");}-void RenderContext::initWhiteTexture() {- whiteTextureId_ = device_.createTexture();-- u32 whiteData = 0xFFFFFFFF;- device_.texImage2D(whiteTextureId_, 1, 1, GfxPixelFormat::RGBA8, &whiteData);- device_.setTextureParams(whiteTextureId_, TextureFilter::Nearest, TextureFilter::Nearest,+u32 RenderContext::make1x1Texture(u32 rgba) {+ u32 id = device_.createTexture();+ device_.texImage2D(id, 1, 1, GfxPixelFormat::RGBA8, &rgba);+ device_.setTextureParams(id, TextureFilter::Nearest, TextureFilter::Nearest,TextureWrap::ClampToEdge, TextureWrap::ClampToEdge);+ return id;+}++void RenderContext::initDefaultTextures() {+ // Byte order in memory is R,G,B,A; these u32s are little-endian (so 0xAABBGGRR).+ whiteTextureId_ = make1x1Texture(0xFFFFFFFF); // RGBA(255,255,255,255)+ blackTextureId_ = make1x1Texture(0xFF000000); // RGBA(0,0,0,255)+ flatNormalTextureId_ = make1x1Texture(0xFFFF8080); // RGB(128,128,255) → normal (0,0,1)+ ES_LOG_DEBUG("Default textures created (white {}, black {}, flatNormal {})",+ whiteTextureId_, blackTextureId_, flatNormalTextureId_);+}- ES_LOG_DEBUG("White texture created (ID: {})", whiteTextureId_);+u32 RenderContext::defaultTextureByName(const std::string& name) const {+ if (name == "black") return blackTextureId_;+ if (name == "flatnormal" || name == "normal") return flatNormalTextureId_;+ return whiteTextureId_; // "white" / empty / unknown}void RenderContext::initFrameUbo() {diff --git a/src/esengine/renderer/RenderContext.hpp b/src/esengine/renderer/RenderContext.hppindex eb3a876f2..1a0ebab75 100644--- a/src/esengine/renderer/RenderContext.hpp+++ b/src/esengine/renderer/RenderContext.hpp@@ -21,6 +21,8 @@// Project includes#include "../core/Types.hpp"#include "Buffer.hpp"+#include "LightStore.hpp"+#include "MaterialStore.hpp"#include "Shader.hpp"// Third-party@@ -140,6 +142,14 @@ public:*/u32 getWhiteTextureId() const { return whiteTextureId_; }+ /**+ * @brief GL texture id for a named built-in default texture, used to resolve a material+ * texture param's `#pragma param ... texture default(<name>)`.+ * @details "black" → opaque black, "flatnormal"/"normal" → a flat tangent-space normal+ * (RGB 128,128,255 → (0,0,1)); anything else (incl. "white" / empty) → white.+ */+ u32 defaultTextureByName(const std::string& name) const;+/*** @brief Uploads the per-frame view-projection into the shared FrameConstants UBO.* @details Called once per render pass before its draws; every engine shader reads@@ -147,15 +157,38 @@ public:*/void updateFrameConstants(const glm::mat4& viewProjection);+ /**+ * @brief The engine-side material registry (handle -> resolved render state).+ * @details Written by the SDK material binding (defineMaterial) and read by the render+ * collect path to resolve a component's material handle into shader + pipeline+ * state. Lives here so both sides reach it without a global lookup.+ */+ MaterialStore& materials() { return materials_; }+ const MaterialStore& materials() const { return materials_; }++ /**+ * @brief The engine-side per-frame 2D light registry (binding 2 LightConstants UBO).+ * @details Filled by the render collect path from the scene's Light2D components and uploaded+ * once per frame; Lit2D material shaders read it. Lives here next to materials() so+ * the render path reaches one store / one UBO without a global lookup.+ */+ LightStore& lights() { return lights_; }+ const LightStore& lights() const { return lights_; }+private:- void initWhiteTexture();+ void initDefaultTextures();+ u32 make1x1Texture(u32 rgba);void initFrameUbo();glm::mat4 viewProjection_{1.0f};RenderContextStats stats_;u32 whiteTextureId_ = 0;+ u32 blackTextureId_ = 0;+ u32 flatNormalTextureId_ = 0;u32 frameUbo_ = 0;+ MaterialStore materials_;+ LightStore lights_;GfxDevice& device_;bool initialized_ = false;diff --git a/src/esengine/renderer/RenderFrame.cpp b/src/esengine/renderer/RenderFrame.cppindex 2bff13989..7817b1c36 100644--- a/src/esengine/renderer/RenderFrame.cpp+++ b/src/esengine/renderer/RenderFrame.cpp@@ -3,12 +3,17 @@#include "RenderFrame.hpp"#include "Shader.hpp"#include "ShaderEmbeds.generated.hpp"+#include "LightStore.hpp"+#include "../ecs/components/Transform.hpp"+#include "../ecs/components/Light2D.hpp"#include "../resource/ShaderParser.hpp"#include "../core/Log.hpp"#include <glm/gtc/type_ptr.hpp>+#include <algorithm>#include <cmath>+#include <vector>namespace esengine {@@ -183,7 +188,8 @@ void RenderFrame::flush() {pool_.upload();context_.updateFrameConstants(view_projection_);- draw_list_.execute(device_, pool_, &frame_capture_);+ context_.lights().uploadAndBind();+ draw_list_.execute(device_, pool_, context_.materials(), &frame_capture_);stats_.draw_calls = draw_list_.mergedDrawCallCount();for (u32 i = 0; i < draw_list_.commandCount(); ++i) {@@ -264,7 +270,8 @@ void RenderFrame::replayToDrawCall(i32 stopAtDrawCall) {frame_capture_.setReplayMode(stopAtDrawCall + 1);context_.updateFrameConstants(view_projection_);- draw_list_.execute(device_, pool_, &frame_capture_);+ context_.lights().uploadAndBind();+ draw_list_.execute(device_, pool_, context_.materials(), &frame_capture_);// Leave scissor/stencil disabled for whatever renders next; invalidate so the next// setPipeline re-applies (we changed stencil/scissor outside the pipeline here).@@ -282,6 +289,53 @@ void RenderFrame::replayToDrawCall(i32 stopAtDrawCall) {rt->unbind();}+void RenderFrame::renderToTarget(ecs::Registry& registry, const glm::mat4& viewProjection, u32 w, u32 h) {+ if (w == 0 || h == 0) return;++ if (preview_rt_ == 0) {+ preview_rt_ = target_manager_.create(w, h, /*depth=*/false, /*linearFilter=*/false);+ } else if (auto* existing = target_manager_.get(preview_rt_);+ existing && (existing->getWidth() != w || existing->getHeight() != h)) {+ existing->resize(w, h);+ }+ auto* rt = target_manager_.get(preview_rt_);+ if (!rt) return;++ rt->bind();+ device_.setViewport(0, 0, w, h);+ device_.setClearColor(0.0f, 0.0f, 0.0f, 0.0f);+ device_.clear(true, false, false);+ device_.invalidatePipelineCache();++ // A self-contained collect (begin()'s setup minus post-process) + execute (flush()'s body),+ // drawn to the bound preview target. Reuses the real collect+material+execute path so a+ // preview is pixel-identical to the viewport.+ view_projection_ = viewProjection;+ frustum_.extractFromMatrix(viewProjection);+ current_stage_ = RenderStage::Transparent;+ pool_.beginFrame();+ draw_list_.clear();+ clip_state_.clear();+ frame_capture_.beginCapture();++ collectAll(registry);++ draw_list_.finalize(pool_);+ pool_.upload();+ context_.updateFrameConstants(viewProjection);+ context_.lights().uploadAndBind();+ draw_list_.execute(device_, pool_, context_.materials(), &frame_capture_);+ frame_capture_.endCapture();++ preview_w_ = w;+ preview_h_ = h;+ preview_pixels_.resize(static_cast<usize>(w) * h * 4);+ device_.readPixels(0, 0, w, h, GfxPixelFormat::RGBA8, preview_pixels_.data());++ rt->unbind();+ device_.invalidatePipelineCache();+}+void RenderFrame::setEntityClipRect(u32 entity, i32 x, i32 y, i32 w, i32 h) {clip_rects_[entity] = ScissorRect{x, y, w, h};}@@ -345,12 +399,67 @@ RenderFrameContext RenderFrame::makeContext() {context_.getWhiteTextureId(),batch_shader_id_,current_stage_,- view_projection_+ view_projection_,+ &context_.materials()};}+void RenderFrame::collectLights(ecs::Registry& registry) {+ LightStore& lights = context_.lights();+ lights.clear();++ // Gather non-ambient lights, then (if over the UBO's cap) keep the most intense — the+ // brightest contribute most, and an explicit importance cull beats silently dropping+ // whichever happened to come last in iteration order. Ambient lights sum without a cap.+ std::vector<GpuLight2D> collected;++ auto view = registry.view<ecs::Transform, ecs::Light2D>();+ for (auto entity : view) {+ const auto& light = view.get<ecs::Light2D>(entity);+ if (!light.enabled || light.intensity <= 0.0f) continue;++ const auto type = static_cast<ecs::Light2DType>(light.type);+ const glm::vec3 rgb{light.color}; // color.a is unused; intensity carries the strength+ if (type == ecs::Light2DType::Ambient) {+ lights.addAmbient(rgb * light.intensity);+ continue;+ }++ GpuLight2D gpu;+ gpu.color = glm::vec4(rgb, light.intensity);+ if (type == ecs::Light2DType::Directional) {+ // Direction in the 2D plane; z=1 flags directional (no attenuation) in the shader.+ gpu.posDir = glm::vec4(light.direction.x, light.direction.y, 1.0f, 0.0f);+ } else { // Point / Spot — world position from the Transform, w=falloff radius.+ auto& transform = view.get<ecs::Transform>(entity);+ transform.ensureDecomposed();+ const glm::vec3 p = transform.worldPosition;+ const f32 typeId = (type == ecs::Light2DType::Spot) ? 2.0f : 0.0f;+ gpu.posDir = glm::vec4(p.x, p.y, typeId, light.radius);+ if (type == ecs::Light2DType::Spot) {+ glm::vec2 aim = light.direction;+ aim = (glm::dot(aim, aim) > 1e-8f) ? glm::normalize(aim) : glm::vec2(0.0f, -1.0f);+ gpu.spot = glm::vec4(aim.x, aim.y,+ std::cos(glm::radians(light.innerAngle * 0.5f)),+ std::cos(glm::radians(light.outerAngle * 0.5f)));+ }+ }+ collected.push_back(gpu);+ }++ if (collected.size() > MAX_LIGHTS_2D) {+ std::partial_sort(collected.begin(), collected.begin() + MAX_LIGHTS_2D, collected.end(),+ [](const GpuLight2D& a, const GpuLight2D& b) { return a.color.a > b.color.a; });+ ES_LOG_WARN("collectLights: {} lights exceed the {}-light cap; keeping the brightest",+ collected.size(), MAX_LIGHTS_2D);+ collected.resize(MAX_LIGHTS_2D);+ }+ for (const auto& gpu : collected) lights.addLight(gpu);+}+void RenderFrame::collectAll(ecs::Registry& registry, u32 skipFlags) {buildClipState();+ collectLights(registry);auto ctx = makeContext();diff --git a/src/esengine/renderer/RenderFrame.hpp b/src/esengine/renderer/RenderFrame.hppindex 39a9e4441..2df0c4fbf 100644--- a/src/esengine/renderer/RenderFrame.hpp+++ b/src/esengine/renderer/RenderFrame.hpp@@ -127,6 +127,18 @@ public:u32 getSnapshotWidth() const { return width_; }u32 getSnapshotHeight() const { return height_; }+ /**+ * Render @p registry once to an offscreen @p w×@p h target with @p viewProjection and read+ * the RGBA pixels back (queried via getPreview*). A self-contained mini-frame (no+ * post-process) reusing the real collect+execute path, so a material preview matches the+ * viewport exactly. Clobbers the transient draw list/pool, which the next real frame rebuilds.+ */+ void renderToTarget(ecs::Registry& registry, const glm::mat4& viewProjection, u32 w, u32 h);+ const u8* getPreviewPixels() const { return preview_pixels_.data(); }+ u32 getPreviewSize() const { return static_cast<u32>(preview_pixels_.size()); }+ u32 getPreviewWidth() const { return preview_w_; }+ u32 getPreviewHeight() const { return preview_h_; }+void addPlugin(std::unique_ptr<RenderTypePlugin> plugin);void collectAll(ecs::Registry& registry, u32 skipFlags = 0);@@ -159,6 +171,10 @@ private:FrameCapture frame_capture_;std::vector<u8> snapshot_pixels_;RenderTargetManager::Handle replay_rt_ = 0;+ std::vector<u8> preview_pixels_;+ RenderTargetManager::Handle preview_rt_ = 0;+ u32 preview_w_ = 0;+ u32 preview_h_ = 0;bool in_frame_ = false;bool flushed_ = false;u32 width_ = 0;@@ -183,6 +199,10 @@ private:RenderFrameContext makeContext();void buildClipState();+ /// Gathers the scene's enabled Light2D components into the per-frame LightConstants UBO+ /// (point/directional into the light array, ambient summed). Run each frame in collectAll;+ /// flush() uploads + binds the result so Lit2D material shaders read it.+ void collectLights(ecs::Registry& registry);u32 initBatchShader();u32 compileBatchVariant(const std::vector<std::string>& features);};diff --git a/src/esengine/renderer/RenderTypePlugin.hpp b/src/esengine/renderer/RenderTypePlugin.hppindex 0df569b57..a7e93b3df 100644--- a/src/esengine/renderer/RenderTypePlugin.hpp+++ b/src/esengine/renderer/RenderTypePlugin.hpp@@ -18,6 +18,7 @@ namespace esengine {struct Frustum;class RenderContext;+class MaterialStore;struct RenderFrameContext {RenderContext& render_context;@@ -26,6 +27,7 @@ struct RenderFrameContext {u32 batch_shader_id = 0;RenderStage current_stage = RenderStage::Transparent;glm::mat4 view_projection{1.0f};+ const MaterialStore* materials = nullptr;};struct RenderCollectContext {diff --git a/src/esengine/renderer/Shader.cpp b/src/esengine/renderer/Shader.cppindex 25282e3a1..c7337d74b 100644--- a/src/esengine/renderer/Shader.cpp+++ b/src/esengine/renderer/Shader.cpp@@ -17,6 +17,8 @@#include "Shader.hpp"#include "GfxDevice.hpp"#include "FrameConstants.hpp"+#include "MaterialConstants.hpp"+#include "LightConstants.hpp"#include "../core/Log.hpp"#include <fstream>@@ -163,6 +165,20 @@ bool Shader::compile(const std::string& vertexSrc, const std::string& fragmentSrdevice_->uniformBlockBinding(programId_, frameBlock, FRAME_CONSTANTS_BINDING);}+ // Same for the per-material constants block (ShaderParser auto-generates it for shaders+ // authored with #pragma param); the render path binds each material's UBO here per draw.+ u32 materialBlock = device_->getUniformBlockIndex(programId_, MATERIAL_CONSTANTS_BLOCK);+ if (materialBlock != GFX_INVALID_UNIFORM_BLOCK) {+ device_->uniformBlockBinding(programId_, materialBlock, MATERIAL_CONSTANTS_BINDING);+ }++ // Same for the per-frame 2D light block (ShaderParser injects it for Lit2D-domain shaders);+ // the render path uploads + binds the shared LightConstants UBO here once per frame.+ u32 lightBlock = device_->getUniformBlockIndex(programId_, LIGHT_CONSTANTS_BLOCK);+ if (lightBlock != GFX_INVALID_UNIFORM_BLOCK) {+ device_->uniformBlockBinding(programId_, lightBlock, LIGHT_CONSTANTS_BINDING);+ }+ES_LOG_DEBUG("Shader compiled successfully (program ID: {}, active uniforms: {})",programId_, activeUniforms_.size());return true;diff --git a/src/esengine/renderer/plugins/SpritePlugin.cpp b/src/esengine/renderer/plugins/SpritePlugin.cppindex 63cf46ad4..38661159c 100644--- a/src/esengine/renderer/plugins/SpritePlugin.cpp+++ b/src/esengine/renderer/plugins/SpritePlugin.cpp@@ -1,6 +1,7 @@// SPDX-License-Identifier: LicenseRef-PolyForm-Noncommercial-1.0.0// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team#include "SpritePlugin.hpp"+#include "../MaterialStore.hpp"#include "../RenderContext.hpp"#include "../RenderFrame.hpp"#include "../Texture.hpp"@@ -77,12 +78,10 @@ void SpritePlugin::collect(RenderCollectContext& collect_ctx) {bool hasTiling = sprite.tileSize.x > 0.0f && sprite.tileSize.y > 0.0f;- u32 shaderId = (sprite.material != 0) ? sprite.material : batch_shader_id_;-BatchDrawKey key{.stage = ctx.current_stage,.layer = sprite.layer,- .shaderId = shaderId,+ .shaderId = batch_shader_id_,.blend = BlendMode::Normal,.textureId = textureId,.depth = position.z,@@ -90,6 +89,20 @@ void SpritePlugin::collect(RenderCollectContext& collect_ctx) {.type = RenderType::Sprite,};+ // Resolve the material handle to its engine-side render state. An unregistered+ // handle falls back to the default batch shader (treated as no material), so a+ // dangling reference renders plainly instead of binding a bogus program.+ if (sprite.material != 0) {+ if (const MaterialRecord* m = ctx.materials ? ctx.materials->find(sprite.material) : nullptr) {+ key.shaderId = (m->shader != 0) ? m->shader : batch_shader_id_;+ key.blend = m->blend;+ key.materialId = sprite.material;+ key.depthTest = m->depthTest;+ key.depthWrite = m->depthWrite;+ key.cull = static_cast<u8>(m->cull);+ }+ }+if (hasTiling) {emitTiledQuads(buffers, draw_list, clips,glm::vec2(position), finalSize, sprite.pivot,diff --git a/src/esengine/resource/ShaderParser.cpp b/src/esengine/resource/ShaderParser.cppindex 7daef81bf..4c1bfe938 100644--- a/src/esengine/resource/ShaderParser.cpp+++ b/src/esengine/resource/ShaderParser.cpp@@ -17,6 +17,7 @@#include <sstream>#include <algorithm>#include <cctype>+#include <cstdlib>#include <unordered_set>namespace esengine::resource {@@ -167,6 +168,39 @@ ParsedShader ShaderParser::parse(const std::string& source, const ShaderIncludeRcontinue;}+ if (directive == "param") {+ // Declarative material parameter: ShaderParser owns its std140 slot in the+ // generated MaterialConstants block (or a sampler unit for textures).+ ShaderProperty prop = parseParamDirective(argument);+ if (!prop.name.empty()) result.properties.push_back(prop);+ continue;+ }++ if (directive == "domain") {+ if (!argument.empty()) result.domain = argument;+ continue;+ }++ if (directive == "switch") {+ // Material-controlled compile-time toggle: `#pragma switch NAME [default(on|off)]`.+ std::istringstream sw(argument);+ ShaderSwitch decl;+ sw >> decl.name;+ if (!decl.name.empty()) {+ const usize p = argument.find("default(");+ if (p != std::string::npos) {+ const usize open = p + 8;+ const usize close = argument.find(')', open);+ if (close != std::string::npos) {+ const std::string v = trim(argument.substr(open, close - open));+ decl.defaultOn = (v == "on" || v == "true" || v == "1");+ }+ }+ result.switches.push_back(decl);+ }+ continue;+ }+if (directive == "properties") {if (state != ParseState::Global) {result.errorMessage = "Unexpected #pragma properties at line " + std::to_string(lineNumber);@@ -285,6 +319,8 @@ ParsedShader ShaderParser::parse(const std::string& source, const ShaderIncludeRreturn result;}+ computeMaterialLayout(result);+result.valid = true;return result;}@@ -317,6 +353,18 @@ u32 countNewlines(const std::string& s) {return n;}+const char* glslTypeName(ShaderPropertyType t) {+ switch (t) {+ case ShaderPropertyType::Float: return "float";+ case ShaderPropertyType::Vec2: return "vec2";+ case ShaderPropertyType::Vec3: return "vec3";+ case ShaderPropertyType::Vec4:+ case ShaderPropertyType::Color: return "vec4";+ case ShaderPropertyType::Int: return "int";+ default: return "float";+ }+}+} // namespaceShaderParser::AssembledStage ShaderParser::assembleStageEx(const ParsedShader& parsed,@@ -346,6 +394,85 @@ ShaderParser::AssembledStage ShaderParser::assembleStageEx(const ParsedShader& p++headerLines;}+ // Auto-generated material params (#pragma param): the std140 MaterialConstants block+ // (non-texture params in declared order == std140 offset order) plus sampler uniforms.+ // Injected after the #defines so both stages share one block and the body can use the+ // params by name. A stage that doesn't reference them just carries an unused block.+ // Members carry an explicit `highp` so the block is self-contained: a fragment shader+ // has no default float precision until its own `precision` line, which follows this+ // injected header — qualifying each member avoids a "no precision specified" error.+ if (parsed.materialBlockSize > 0) {+ assembled << "layout(std140) uniform MaterialConstants {\n";+ ++headerLines;+ for (const auto& p : parsed.properties) {+ if (!p.fromParam || p.std140Offset < 0) continue;+ assembled << " highp " << glslTypeName(p.type) << " " << p.name << ";\n";+ ++headerLines;+ }+ assembled << "};\n";+ ++headerLines;+ }+ for (const auto& p : parsed.properties) {+ if (p.fromParam && p.type == ShaderPropertyType::Texture) {+ assembled << "uniform highp sampler2D " << p.name << ";\n";+ ++headerLines;+ }+ }++ // Lit2D domain: inject the shared LightConstants block (std140) + the es_applyLighting2D()+ // helper into the fragment stage. Authors write the surface (albedo) and a world-position+ // varying, then call the helper — the engine owns the std140 layout so a hand-written struct+ // can't silently mismatch renderer/LightConstants.hpp and corrupt lighting. Members + locals+ // carry explicit highp for the same reason MaterialConstants does: a fragment shader has no+ // default float precision until its `precision` line, which follows this injected header.+ // The light-array size and packing here MUST match renderer/LightConstants.hpp (MAX_LIGHTS_2D,+ // GpuLight2D = two vec4s).+ if (stage == ShaderStage::Fragment && parsed.domain == "Lit2D") {+ static const char* kLit2DHeader =+ "struct es_Light2D { highp vec4 posDir; highp vec4 color; highp vec4 spot; };\n"+ "layout(std140) uniform LightConstants {\n"+ " highp vec4 u_ambient;\n"+ " es_Light2D u_lights[16];\n"+ "};\n"+ // Engine-owned normal-map convention (RGB[0,1] -> normal[-1,1], normalized), so every+ // Lit2D shader unpacks tangent-space normals the same way. 2D applies it screen-space+ // (no per-sprite tangent frame); a flat surface uses vec3(0,0,1).+ "highp vec3 es_sampleNormal(in highp sampler2D map, in highp vec2 uv) {\n"+ " return normalize(texture(map, uv).xyz * 2.0 - 1.0);\n"+ "}\n"+ "highp vec3 es_applyLighting2D(highp vec3 albedo, highp vec3 N, highp vec2 worldPos) {\n"+ " highp vec3 lit = u_ambient.rgb;\n"+ " for (int i = 0; i < 16; ++i) {\n"+ " highp vec4 pd = u_lights[i].posDir;\n"+ " highp vec4 col = u_lights[i].color;\n"+ " highp vec3 L;\n"+ " highp float atten;\n"+ " if (pd.z < 0.5) {\n"+ " highp vec2 d = pd.xy - worldPos;\n"+ " highp float dist = length(d);\n"+ " atten = max(0.0, 1.0 - dist / max(pd.w, 0.0001));\n"+ " L = normalize(vec3(d, max(pd.w, 1.0)));\n"+ " } else if (pd.z < 1.5) {\n"+ " atten = 1.0;\n"+ " L = normalize(vec3(-pd.xy, 1.0));\n"+ " } else {\n"+ " highp vec4 sp = u_lights[i].spot;\n"+ " highp vec2 d = pd.xy - worldPos;\n"+ " highp float dist = length(d);\n"+ " atten = max(0.0, 1.0 - dist / max(pd.w, 0.0001));\n"+ " L = normalize(vec3(d, max(pd.w, 1.0)));\n"+ " highp vec2 toFrag = (dist > 0.0001) ? (-d / dist) : sp.xy;\n"+ " atten *= smoothstep(sp.w, sp.z, dot(sp.xy, toFrag));\n"+ " }\n"+ " highp float ndotl = max(dot(N, L), 0.0);\n"+ " lit += col.rgb * (col.a * ndotl * atten);\n"+ " }\n"+ " return albedo * lit;\n"+ "}\n";+ assembled << kLit2DHeader;+ headerLines += countNewlines(kLit2DHeader);+ }+if (!platform.empty()) {auto variantIt = parsed.variants.find(platform);if (variantIt != parsed.variants.end()) {@@ -476,6 +603,90 @@ void ShaderParser::parseDirective(const std::string& line,}}+ShaderProperty ShaderParser::parseParamDirective(const std::string& argument) {+ ShaderProperty prop;+ prop.fromParam = true;++ std::istringstream ss(argument);+ std::string typeStr;+ ss >> prop.name >> typeStr;+ if (prop.name.empty() || typeStr.empty()) {+ prop.name.clear(); // signal invalid → caller drops it+ return prop;+ }+ prop.type = stringToPropertyType(typeStr);++ // Extract the contents of a `key(...)` clause from the directive argument.+ auto clause = [&](const char* key) -> std::optional<std::string> {+ const std::string token = std::string(key) + "(";+ usize p = argument.find(token);+ if (p == std::string::npos) return std::nullopt;+ usize open = p + token.size();+ usize close = argument.find(')', open);+ if (close == std::string::npos) return std::nullopt;+ return trim(argument.substr(open, close - open));+ };++ if (auto d = clause("default")) prop.defaultValue = *d;+ if (auto u = clause("ui")) prop.ui = *u;+ if (auto r = clause("range")) {+ usize comma = r->find(',');+ if (comma != std::string::npos) {+ prop.rangeMin = static_cast<f32>(std::atof(trim(r->substr(0, comma)).c_str()));+ prop.rangeMax = static_cast<f32>(std::atof(trim(r->substr(comma + 1)).c_str()));+ prop.hasRange = true;+ }+ }++ // Default display name: strip a leading u_ and capitalize.+ prop.displayName = prop.name;+ if (prop.displayName.size() > 2 && prop.displayName.substr(0, 2) == "u_") {+ prop.displayName = prop.displayName.substr(2);+ }+ if (!prop.displayName.empty()) {+ prop.displayName[0] = static_cast<char>(std::toupper(prop.displayName[0]));+ }+ return prop;+}++void ShaderParser::computeMaterialLayout(ParsedShader& shader) {+ // std140 size/alignment for the supported scalar/vector param types.+ auto sizeAlign = [](ShaderPropertyType t, u32& size, u32& align) {+ switch (t) {+ case ShaderPropertyType::Float:+ case ShaderPropertyType::Int: size = 4; align = 4; break;+ case ShaderPropertyType::Vec2: size = 8; align = 8; break;+ case ShaderPropertyType::Vec3: size = 12; align = 16; break;+ case ShaderPropertyType::Vec4:+ case ShaderPropertyType::Color: size = 16; align = 16; break;+ default: size = 0; align = 0; break;+ }+ };+ auto alignUp = [](u32 v, u32 a) -> u32 { return a == 0 ? v : (v + a - 1) & ~(a - 1); };++ // Material texture units start above the batch path's 0..7 slots+ // (must match renderer/MaterialConstants.hpp MATERIAL_TEXTURE_UNIT_BASE).+ u32 textureUnit = 8;+ u32 offset = 0;++ for (auto& p : shader.properties) {+ if (!p.fromParam) continue; // legacy properties-block entries are reflection-only+ if (p.type == ShaderPropertyType::Texture) {+ p.textureUnit = static_cast<i32>(textureUnit++);+ p.std140Offset = -1;+ continue;+ }+ u32 size = 0, align = 0;+ sizeAlign(p.type, size, align);+ if (size == 0) { p.std140Offset = -1; continue; } // Unknown — not packed+ offset = alignUp(offset, align);+ p.std140Offset = static_cast<i32>(offset);+ offset += size;+ }++ shader.materialBlockSize = (offset == 0) ? 0 : alignUp(offset, 16);+}+ShaderProperty ShaderParser::parsePropertyAnnotation(const std::string& line) {ShaderProperty prop;diff --git a/src/esengine/resource/ShaderParser.hpp b/src/esengine/resource/ShaderParser.hppindex 65db435d2..d5d40e82b 100644--- a/src/esengine/resource/ShaderParser.hpp+++ b/src/esengine/resource/ShaderParser.hpp@@ -83,8 +83,36 @@ enum class ShaderPropertyType : u8 {struct ShaderProperty {std::string name; ///< Uniform nameShaderPropertyType type; ///< Property type- std::string defaultValue; ///< Default value as string+ std::string defaultValue; ///< Default value as string (comma-separated for vectors)std::string displayName; ///< Display name for editor++ /// True when declared via `#pragma param` (the modern path: ShaderParser owns the GLSL+ /// codegen + std140 layout). False for the legacy `#pragma properties` block, which is+ /// reflection-only — the shader declares those uniforms itself, so they are not codegen'd.+ bool fromParam = false;++ /// Byte offset of this param inside the std140 MaterialConstants block, or -1 for+ /// texture params (which are samplers, not block members).+ i32 std140Offset = -1;+ /// Sampler unit for a texture param (>= MATERIAL_TEXTURE_UNIT_BASE), or -1 otherwise.+ i32 textureUnit = -1;++ /// Optional editor metadata (range slider bounds, UI hint). Drives the inspector panel;+ /// not used in codegen. hasRange == false leaves the field a plain numeric input.+ bool hasRange = false;+ f32 rangeMin = 0.0f;+ f32 rangeMax = 1.0f;+ std::string ui; ///< UI hint, e.g. "slider", "color" (free-form).+};++/**+ * @brief A material-controlled static switch (#pragma switch): a boolean the material sets,+ * selecting a compile-time shader permutation via a #define. Distinct from #pragma+ * feature (an engine-chosen variant keyword) only in being material-facing + defaulted.+ */+struct ShaderSwitch {+ std::string name;+ bool defaultOn = false;};// =============================================================================@@ -104,7 +132,12 @@ struct ParsedShader {std::unordered_map<ShaderStage, std::string> stages; ///< Stage source codestd::unordered_map<std::string, std::string> variants; ///< Platform variantsstd::vector<std::string> features; ///< Declared #pragma feature keywords (compile-time variants)- std::vector<ShaderProperty> properties; ///< Exposed properties+ std::vector<ShaderSwitch> switches; ///< Material-controlled #pragma switch toggles (name + default)+ std::vector<ShaderProperty> properties; ///< Exposed material params (#pragma param / properties block)+ std::string domain = "Unlit2D"; ///< #pragma domain (Unlit2D/Lit2D/PostProcess/UI)+ /// std140 byte size of the generated MaterialConstants block (16-aligned), 0 if no+ /// non-texture params. The render path sizes the per-material UBO to this.+ u32 materialBlockSize = 0;std::string errorMessage; ///< Parse error if anybool valid = false; ///< True if parsing succeeded@@ -236,6 +269,13 @@ private:std::string& directive,std::string& argument);+ /// Parses a `#pragma param <name> <type> [default(..)] [range(min,max)] [ui(..)]` line.+ static ShaderProperty parseParamDirective(const std::string& argument);++ /// Assigns std140 offsets to non-texture params and sampler units to texture params,+ /// and sets ParsedShader::materialBlockSize. Run once after all params are collected.+ static void computeMaterialLayout(ParsedShader& shader);+static ShaderProperty parsePropertyAnnotation(const std::string& line);static ShaderPropertyType stringToPropertyType(const std::string& typeStr);