Skip to content

A fast 2D and 3D game engine — TypeScript SDK, C++/WebAssembly core, visual editor. Ship one project to web, desktop, WeChat MiniGames, playable ads, and native Android / iOS.

feat(material): first-class material system — params, instances, Lit-2D, graph, preview

esenginec85f84ac6edc
diff --git a/CMakeLists.txt b/CMakeLists.txt
index 81ee1e02e..f45b752cd 100644
--- a/CMakeLists.txt
+++ b/CMakeLists.txt
@@ -54,6 +54,8 @@ set(ESENGINE_SOURCES
src/esengine/renderer/TransientBufferPool.cpp
src/esengine/renderer/DrawList.cpp
src/esengine/renderer/BatchBuilder.cpp
+ src/esengine/renderer/MaterialStore.cpp
+ src/esengine/renderer/LightStore.cpp
src/esengine/renderer/plugins/BatchPlugin.cpp
src/esengine/renderer/plugins/SpritePlugin.cpp
src/esengine/renderer/plugins/UIElementPlugin.cpp
diff --git a/desktop/package.json b/desktop/package.json
index 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.esscene
new file mode 100644
index 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.json
new file mode 100644
index 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.esmaterial
new file mode 100644
index 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.esmatgraph
new file mode 100644
index 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.esshader
new file mode 100644
index 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 end
diff --git a/desktop/public/scenes/mat-instance.esscene b/desktop/public/scenes/mat-instance.esscene
new file mode 100644
index 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.json
new file mode 100644
index 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.esscene
new file mode 100644
index 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.json
new file mode 100644
index 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.esmaterial
new file mode 100644
index 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.esshader
new file mode 100644
index 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 end
diff --git a/desktop/public/scenes/mat-lit-normal.esscene b/desktop/public/scenes/mat-lit-normal.esscene
new file mode 100644
index 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.json
new file mode 100644
index 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.esmaterial
new file mode 100644
index 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.esshader
new file mode 100644
index 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 end
diff --git a/desktop/public/scenes/mat-lit-normal/normal.png b/desktop/public/scenes/mat-lit-normal/normal.png
new file mode 100644
index 000000000..32638325b
Binary files /dev/null and b/desktop/public/scenes/mat-lit-normal/normal.png differ
diff --git a/desktop/public/scenes/mat-lit-point.esscene b/desktop/public/scenes/mat-lit-point.esscene
new file mode 100644
index 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.json
new file mode 100644
index 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.esscene
new file mode 100644
index 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.json
new file mode 100644
index 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.esscene
new file mode 100644
index 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.json
new file mode 100644
index 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.esmaterial
new file mode 100644
index 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.esshader
new file mode 100644
index 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 end
diff --git a/desktop/public/scenes/mat-sw.esscene b/desktop/public/scenes/mat-sw.esscene
new file mode 100644
index 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.json
new file mode 100644
index 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.esmaterial
new file mode 100644
index 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.esmaterial
new file mode 100644
index 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.esshader
new file mode 100644
index 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 end
diff --git a/desktop/public/scenes/mat-tex.esscene b/desktop/public/scenes/mat-tex.esscene
new file mode 100644
index 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.json
new file mode 100644
index 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.png
new file mode 100644
index 000000000..0e9295be7
Binary files /dev/null and b/desktop/public/scenes/mat-tex/green.png differ
diff --git a/desktop/public/scenes/mat-tex/masked.esmaterial b/desktop/public/scenes/mat-tex/masked.esmaterial
new file mode 100644
index 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.esshader
new file mode 100644
index 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 end
diff --git a/desktop/public/scenes/mat-tint.esscene b/desktop/public/scenes/mat-tint.esscene
new file mode 100644
index 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.json
new file mode 100644
index 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.esmaterial
new file mode 100644
index 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.esmaterial
new file mode 100644
index 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.esshader
new file mode 100644
index 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 end
diff --git a/desktop/scripts/headless-verify.mjs b/desktop/scripts/headless-verify.mjs
index 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.tsx
new file mode 100644
index 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.ts
index 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.ts
index 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.tsx
index 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.tsx
index 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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.tsx
index 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/assetMe
import { 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() {
<div
className={`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.tsx
index 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.tsx
new file mode 100644
index 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.tsx
index 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 'reac
import 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.ts
index 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.ts
index 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.ts
index 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.css
index 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.css
index 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.css
new file mode 100644
index 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.css
index 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.ts
index 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.ts
new file mode 100644
index 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.ts
deleted file mode 100644
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
new file mode 100644
index 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.ts
index 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.ts
index 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.ts
index 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 API
draw_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 Systems
uiLayout_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.ts
index 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.ts
new file mode 100644
index 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.cpp
index 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::s
else 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::st
else 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::str
else 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::stri
else 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::st
else 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::st
if (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.hpp
index 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 esengine
diff --git a/src/esengine/bindings/MaterialCache.hpp b/src/esengine/bindings/MaterialCache.hpp
deleted file mode 100644
index 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 esengine
diff --git a/src/esengine/bindings/RendererBindings.cpp b/src/esengine/bindings/RendererBindings.cpp
index 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.hpp
index 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.cpp
index 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 drif
static_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.cpp
index 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) {
#endif
emscripten::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.hpp
new file mode 100644
index 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::ecs
diff --git a/src/esengine/renderer/BatchBuilder.cpp b/src/esengine/renderer/BatchBuilder.cpp
index 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.hpp
index 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.hpp
index 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.cpp
index 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.hpp
index 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.hpp
new file mode 100644
index 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 esengine
diff --git a/src/esengine/renderer/LightStore.cpp b/src/esengine/renderer/LightStore.cpp
new file mode 100644
index 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 esengine
diff --git a/src/esengine/renderer/LightStore.hpp b/src/esengine/renderer/LightStore.hpp
new file mode 100644
index 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 esengine
diff --git a/src/esengine/renderer/MaterialConstants.hpp b/src/esengine/renderer/MaterialConstants.hpp
new file mode 100644
index 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 esengine
diff --git a/src/esengine/renderer/MaterialStore.cpp b/src/esengine/renderer/MaterialStore.cpp
new file mode 100644
index 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 esengine
diff --git a/src/esengine/renderer/MaterialStore.hpp b/src/esengine/renderer/MaterialStore.hpp
new file mode 100644
index 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 esengine
diff --git a/src/esengine/renderer/RenderContext.cpp b/src/esengine/renderer/RenderContext.cpp
index 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.hpp
index 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.cpp
index 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.hpp
index 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.hpp
index 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.cpp
index 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& fragmentSr
device_->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.cpp
index 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.cpp
index 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 ShaderIncludeR
continue;
}
+ 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 ShaderIncludeR
return 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";
+ }
+}
+
} // namespace
ShaderParser::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.hpp
index 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 name
ShaderPropertyType 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 code
std::unordered_map<std::string, std::string> variants; ///< Platform variants
std::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 any
bool 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);