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(render): a material can draw geometry that carries normals

esenginecc2ab56b5439
diff --git a/desktop/public/scenes/mesh-material-lit/litmat.esmaterial b/desktop/public/scenes/mesh-material-lit/litmat.esmaterial
new file mode 100644
index 000000000..c43e902dd
--- /dev/null
+++ b/desktop/public/scenes/mesh-material-lit/litmat.esmaterial
@@ -0,0 +1,8 @@
+{
+ "version": "1.0",
+ "type": "material",
+ "shader": "litmat.esshader",
+ "blendMode": 0,
+ "depthTest": false,
+ "properties": {}
+}
diff --git a/desktop/public/scenes/mesh-material-lit/litmat.esshader b/desktop/public/scenes/mesh-material-lit/litmat.esshader
new file mode 100644
index 000000000..304cc1b1b
--- /dev/null
+++ b/desktop/public/scenes/mesh-material-lit/litmat.esshader
@@ -0,0 +1,42 @@
+#pragma shader "MeshLitMaterial"
+#pragma version 300 es
+#pragma domain Lit2D
+
+// Fragment only: the engine owns the vertex stage, and MESH_NORMALS is how it
+// says this draw's geometry carries normals — a material asks for them the same
+// way it asks for any other feature.
+#pragma fragment
+precision mediump float;
+
+in vec4 v_color;
+in vec2 v_texCoord;
+in highp vec2 v_worldPos;
+#ifdef MESH_NORMALS
+in highp vec3 v_worldNormal;
+in highp vec3 v_worldXYZ;
+#endif
+
+out vec4 fragColor;
+
+// Red, so a frame drawn by the engine's own mesh shader (the fallback when a
+// variant fails to compile) cannot pass for this one: it would be white.
+void main() {
+#ifdef MESH_NORMALS
+ highp vec3 albedo = v_color.rgb * vec3(1.0, 0.0, 0.0);
+ fragColor = vec4(applyLighting2D(albedo, normalize(v_worldNormal), v_worldPos), v_color.a);
+#else
+ fragColor = v_color;
+#endif
+}
+#pragma end
+
+#pragma fragment wgsl
+@fragment fn fs_main(v : VSOut) -> @location(0) vec4f {
+#ifdef MESH_NORMALS
+ let albedo = v.v_color.rgb * vec3f(1.0, 0.0, 0.0);
+ return vec4f(applyLighting2D(albedo, normalize(v.v_worldNormal), v.v_worldPos), v.v_color.a);
+#else
+ return v.v_color;
+#endif
+}
+#pragma end
diff --git a/src/esengine/renderer/plugins/MeshPlugin.cpp b/src/esengine/renderer/plugins/MeshPlugin.cpp
index 5616139af..e384373e8 100644
--- a/src/esengine/renderer/plugins/MeshPlugin.cpp
+++ b/src/esengine/renderer/plugins/MeshPlugin.cpp
@@ -179,7 +179,8 @@ void MeshPlugin::collect(RenderCollectContext& collect_ctx) {
// one compiled for THIS source; a failed variant falls back.
u32 materialProgram = 0;
if (key.materialId != 0 && ctx.materials) {
- materialProgram = ctx.materials->meshProgram(key.materialId, ctx.resources);
+ materialProgram = ctx.materials->meshProgram(key.materialId, ctx.resources,
+ resident->hasNormals);
if (materialProgram == 0) {
if (!warned_material_) {
warned_material_ = true;
diff --git a/src/esengine/renderer/store/MaterialStore.cpp b/src/esengine/renderer/store/MaterialStore.cpp
index 91e8614c5..98b53b42a 100644
--- a/src/esengine/renderer/store/MaterialStore.cpp
+++ b/src/esengine/renderer/store/MaterialStore.cpp
@@ -44,15 +44,18 @@ void MaterialStore::recreateGpuResources() {
}
}
-u32 MaterialStore::meshProgram(u32 materialId, resource::ResourceManager& resources) const {
+u32 MaterialStore::meshProgram(u32 materialId, resource::ResourceManager& resources,
+ bool withNormals) const {
const MaterialRecord* rec = find(materialId);
if (!rec || !rec->shaderRef.isValid()) return 0;
- const u32 key = rec->shaderRef.id();
+ // Keyed by shader AND vertex shape: a layout may not declare an attribute its
+ // shader ignores, so geometry with normals needs its own program.
+ const u64 key = static_cast<u64>(rec->shaderRef.id()) | (withNormals ? (1ull << 32) : 0ull);
auto cached = mesh_programs_.find(key);
if (cached != mesh_programs_.end()) return cached->second;
- auto src = sources_.find(key);
+ auto src = sources_.find(rec->shaderRef.id());
if (src == sources_.end()) {
mesh_programs_[key] = 0;
return 0;
@@ -64,6 +67,7 @@ u32 MaterialStore::meshProgram(u32 materialId, resource::ResourceManager& resour
resource::ParsedShader parsed = resource::ShaderParser::parse(src->second.source);
std::vector<std::string> features = resource::ShaderParser::splitFeatures(src->second.features);
features.push_back("MESH");
+ if (withNormals) features.push_back("MESH_NORMALS");
const auto target = resources.preferredShaderTarget();
const std::string vert = resource::ShaderParser::assembleStage(
parsed, resource::ShaderStage::Vertex, "", features, target);
diff --git a/src/esengine/renderer/store/MaterialStore.hpp b/src/esengine/renderer/store/MaterialStore.hpp
index 512f1f519..1f91d5ede 100644
--- a/src/esengine/renderer/store/MaterialStore.hpp
+++ b/src/esengine/renderer/store/MaterialStore.hpp
@@ -168,9 +168,11 @@ public:
}
/// The program that draws @p materialId on GPU-RESIDENT geometry, compiled on
- /// first use and cached. 0 when the material's source was never kept or the
- /// variant fails — the caller then falls back rather than drawing it wrong.
- u32 meshProgram(u32 materialId, resource::ResourceManager& resources) const;
+ /// first use and cached. @p withNormals selects the variant for geometry that
+ /// carries them. 0 when the material's source was never kept or the variant
+ /// fails — the caller then falls back rather than drawing it wrong.
+ u32 meshProgram(u32 materialId, resource::ResourceManager& resources,
+ bool withNormals = false) const;
/// 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.
@@ -289,7 +291,7 @@ private:
/// Handle → the program compiled for the mesh vertex source (0 = tried and
/// failed). Mutable because compiling it is memoization: the collect path
/// asks a read-only store, and the answer is the same every time.
- mutable std::unordered_map<u32, u32> mesh_programs_;
+ mutable std::unordered_map<u64, u32> mesh_programs_;
GfxDevice* device_ = nullptr;
resource::ResourceManager* resources_ = nullptr;
TextureHandle defaultWhite_ = TextureHandle::Invalid;
diff --git a/src/esengine/resource/ShaderParser.cpp b/src/esengine/resource/ShaderParser.cpp
index 257f25bd4..18fe2e897 100644
--- a/src/esengine/resource/ShaderParser.cpp
+++ b/src/esengine/resource/ShaderParser.cpp
@@ -105,6 +105,14 @@ std::string wgslCanonicalVSOut(bool lit) {
if (lit) {
src += " @location(2) v_worldPos : vec2f,\n";
}
+ // A mesh that HAS normals hands them on, with the full world position a
+ // tangent frame needs. v_worldPos stays vec2 so one fragment stage serves
+ // both vertex sources.
+ src +=
+ "#ifdef MESH_NORMALS\n"
+ " @location(3) v_worldNormal : vec3f,\n"
+ " @location(4) v_worldXYZ : vec3f,\n"
+ "#endif\n";
src += "};\n";
return src;
}
@@ -124,6 +132,9 @@ std::string canonical2DVertexStageWGSL(bool lit) {
" @location(0) a_position : vec3f,\n"
" @location(1) a_color : vec4f,\n"
" @location(2) a_texCoord : vec2f,\n"
+ "#ifdef MESH_NORMALS\n"
+ " @location(3) a_normal : vec3f,\n"
+ "#endif\n"
"#ifdef MESH\n"
" @location(8) a_model0 : vec4f,\n"
" @location(9) a_model1 : vec4f,\n"
@@ -131,6 +142,11 @@ std::string canonical2DVertexStageWGSL(bool lit) {
" @location(11) a_model3 : vec4f,\n"
" @location(12) a_instTint : vec4f,\n"
"#endif\n"
+ "#ifdef MESH_NORMALS\n"
+ " @location(13) a_nrm0 : vec3f,\n"
+ " @location(14) a_nrm1 : vec3f,\n"
+ " @location(15) a_nrm2 : vec3f,\n"
+ "#endif\n"
"};\n"
"\n"
"@vertex fn vs_main(v : VSIn) -> VSOut {\n"
@@ -143,7 +159,11 @@ std::string canonical2DVertexStageWGSL(bool lit) {
" out.v_color = v.a_color;\n"
"#endif\n"
" out.pos = frame.projection * world;\n"
- " out.v_texCoord = v.a_texCoord;\n";
+ " out.v_texCoord = v.a_texCoord;\n"
+ "#ifdef MESH_NORMALS\n"
+ " out.v_worldNormal = mat3x3f(v.a_nrm0, v.a_nrm1, v.a_nrm2) * v.a_normal;\n"
+ " out.v_worldXYZ = world.xyz;\n"
+ "#endif\n";
if (lit) {
src += " out.v_worldPos = world.xy;\n";
}
@@ -208,6 +228,9 @@ std::string canonical2DVertexStage(bool lit) {
"layout(location = 0) in vec3 a_position;\n"
"layout(location = 1) in vec4 a_color;\n"
"layout(location = 2) in vec2 a_texCoord;\n"
+ "#ifdef MESH_NORMALS\n"
+ "layout(location = 3) in vec3 a_normal;\n"
+ "#endif\n"
"#ifdef MESH\n"
"layout(location = 8) in vec4 a_model0;\n"
"layout(location = 9) in vec4 a_model1;\n"
@@ -215,13 +238,22 @@ std::string canonical2DVertexStage(bool lit) {
"layout(location = 11) in vec4 a_model3;\n"
"layout(location = 12) in vec4 a_instTint;\n"
"#endif\n"
+ "#ifdef MESH_NORMALS\n"
+ "layout(location = 13) in vec3 a_nrm0;\n"
+ "layout(location = 14) in vec3 a_nrm1;\n"
+ "layout(location = 15) in vec3 a_nrm2;\n"
+ "#endif\n"
"\n"
"layout(std140) uniform FrameConstants {\n"
" mat4 u_projection;\n"
"};\n"
"\n"
"out vec4 v_color;\n"
- "out vec2 v_texCoord;\n";
+ "out vec2 v_texCoord;\n"
+ "#ifdef MESH_NORMALS\n"
+ "out highp vec3 v_worldNormal;\n"
+ "out highp vec3 v_worldXYZ;\n"
+ "#endif\n";
if (lit) {
src += "out highp vec2 v_worldPos;\n";
}
@@ -236,7 +268,11 @@ std::string canonical2DVertexStage(bool lit) {
" v_color = a_color;\n"
"#endif\n"
" gl_Position = u_projection * world;\n"
- " v_texCoord = a_texCoord;\n";
+ " v_texCoord = a_texCoord;\n"
+ "#ifdef MESH_NORMALS\n"
+ " v_worldNormal = mat3(a_nrm0, a_nrm1, a_nrm2) * a_normal;\n"
+ " v_worldXYZ = world.xyz;\n"
+ "#endif\n";
if (lit) {
src += " v_worldPos = world.xy;\n";
}
diff --git a/tools/renderScenes.mjs b/tools/renderScenes.mjs
index a415253f2..d507536cd 100644
--- a/tools/renderScenes.mjs
+++ b/tools/renderScenes.mjs
@@ -136,6 +136,10 @@ export const SCENES = [
// offset to have reached the child, and the fourth is background only if the
// child's scale survived — ignore the tree and everything stacks on the origin.
{ id: "mesh-nodes", tier: "pr", webgpu: true, env: { ESTELLA_VERIFY_PREFAB: "/scenes/node-tree.esprefab", ESTELLA_VERIFY_SCENE: "/scenes/mesh-nodes.esscene", ESTELLA_VERIFY_MANIFEST: "/scenes/mesh-nodes.textures.json", ESTELLA_VERIFY_W: "256", ESTELLA_VERIFY_H: "256", ESTELLA_VERIFY_STEPS: "4", ESTELLA_VERIFY_EXPECT: "[{\"x\":0.3667,\"y\":0.40,\"rgb\":[255,0,0],\"tol\":40},{\"x\":0.45,\"y\":0.40,\"rgb\":[255,0,0],\"tol\":40},{\"x\":0.7667,\"y\":0.60,\"rgb\":[0,255,0],\"tol\":40},{\"x\":0.7667,\"y\":0.5333,\"rgb\":[0,0,0],\"tol\":30}]" } },
+ // mesh-lit's geometry and light, shaded by a MATERIAL whose fragment reads the
+ // normals the engine's vertex stage hands it. RED, so the fallback (the mesh
+ // shader, taken when a variant fails) cannot pass for it — that draws white.
+ { id: "mesh-material-lit", tier: "pr", webgpu: true, env: { ESTELLA_VERIFY_MESH_ASSET: "/scenes/lit-triangles.esmesh", ESTELLA_VERIFY_MESH_MATERIAL: "/scenes/mesh-material-lit/litmat.esmaterial", ESTELLA_VERIFY_SCENE: "/scenes/mesh-lit.esscene", ESTELLA_VERIFY_MANIFEST: "/scenes/mesh-lit.textures.json", ESTELLA_VERIFY_W: "256", ESTELLA_VERIFY_H: "256", ESTELLA_VERIFY_STEPS: "4", ESTELLA_VERIFY_EXPECT: "[{\"x\":0.30,\"y\":0.556,\"rgb\":[255,0,0],\"tol\":40},{\"x\":0.70,\"y\":0.556,\"rgb\":[0,0,0],\"tol\":40}]" } },
// A normal map over FLAT normals: the quad faces the viewer, so without the map
// both halves take the same light. Its texels point -X and +X, so the lit half
// and the unlit one are the tangent frame, derived per pixel from derivatives.