A fast 2D and 3D game engine — TypeScript SDK, C++/WebAssembly core, visual editor. Ship one project to web, desktop, WeChat MiniGames, playable ads, and native Android / iOS.
TypeScript 2d-game-engine3d3d-game-engineandroidcppecsgame-editorgame-enginegamedeviostypescriptwebassemblywebglwebgpuwechat-minigame
feat(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.esmaterialnew file mode 100644index 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.esshadernew file mode 100644index 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 enddiff --git a/src/esengine/renderer/plugins/MeshPlugin.cpp b/src/esengine/renderer/plugins/MeshPlugin.cppindex 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.cppindex 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& resourresource::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.hppindex 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.cppindex 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.mjsindex 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.