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.

fix(render): `lit` is a field the mesh path actually reads

esengine2c3f4c4787d2
diff --git a/desktop/public/scenes/lit-triangles.esprefab b/desktop/public/scenes/lit-triangles.esprefab
index 79b3d0769..cef61fe7b 100644
--- a/desktop/public/scenes/lit-triangles.esprefab
+++ b/desktop/public/scenes/lit-triangles.esprefab
@@ -18,6 +18,7 @@
"type": "Mesh2D",
"data": {
"mesh": "scenes/lit-triangles.esmesh",
+ "lit": true,
"enabled": true
}
}
diff --git a/desktop/public/scenes/mesh-flat-lit.esscene b/desktop/public/scenes/mesh-flat-lit.esscene
new file mode 100644
index 000000000..4f2b9d9ff
--- /dev/null
+++ b/desktop/public/scenes/mesh-flat-lit.esscene
@@ -0,0 +1,105 @@
+{
+ "version": 1,
+ "name": "MeshFlatLit",
+ "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": "Sun",
+ "parent": null,
+ "children": [],
+ "components": [
+ {
+ "type": "Transform",
+ "data": {
+ "position": {
+ "x": 0,
+ "y": 0,
+ "z": 0
+ }
+ }
+ },
+ {
+ "type": "Light2D",
+ "data": {
+ "type": 1,
+ "color": {
+ "r": 1,
+ "g": 0,
+ "b": 0,
+ "a": 1
+ },
+ "intensity": 1,
+ "direction": {
+ "x": 0,
+ "y": 0
+ },
+ "enabled": true
+ }
+ }
+ ],
+ "visible": true
+ },
+ {
+ "id": 2,
+ "name": "FlatTriangles",
+ "parent": null,
+ "children": [],
+ "components": [
+ {
+ "type": "Transform",
+ "data": {
+ "position": {
+ "x": 0,
+ "y": 0,
+ "z": 0
+ }
+ }
+ },
+ {
+ "type": "Mesh2D",
+ "data": {
+ "color": {
+ "r": 1,
+ "g": 1,
+ "b": 1,
+ "a": 1
+ },
+ "layer": 0,
+ "enabled": true,
+ "lit": true,
+ "mesh": "/scenes/two-triangles.esmesh"
+ }
+ }
+ ],
+ "visible": true
+ }
+ ]
+}
diff --git a/desktop/public/scenes/mesh-flat-lit.textures.json b/desktop/public/scenes/mesh-flat-lit.textures.json
new file mode 100644
index 000000000..0967ef424
--- /dev/null
+++ b/desktop/public/scenes/mesh-flat-lit.textures.json
@@ -0,0 +1 @@
+{}
diff --git a/desktop/public/scenes/mesh-lit.esscene b/desktop/public/scenes/mesh-lit.esscene
index 02604e02d..837bc8edc 100644
--- a/desktop/public/scenes/mesh-lit.esscene
+++ b/desktop/public/scenes/mesh-lit.esscene
@@ -1,39 +1,105 @@
{
- "version": 1,
- "name": "MeshLit",
- "entities": [
+ "version": 1,
+ "name": "MeshLit",
+ "entities": [
+ {
+ "id": 0,
+ "name": "Camera",
+ "parent": null,
+ "children": [],
+ "components": [
{
- "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
+ "type": "Transform",
+ "data": {
+ "position": {
+ "x": 0,
+ "y": 0,
+ "z": 10
+ }
+ }
},
{
- "id": 1,
- "name": "Sun",
- "parent": null,
- "children": [],
- "components": [
- { "type": "Transform", "data": { "position": { "x": 0, "y": 0, "z": 0 } } },
- { "type": "Light2D", "data": { "type": 1, "color": { "r": 1, "g": 1, "b": 1, "a": 1 }, "intensity": 1, "direction": { "x": 0, "y": 0 }, "enabled": true } }
- ],
- "visible": true
+ "type": "Camera",
+ "data": {
+ "projectionType": 1,
+ "orthoSize": 300,
+ "isActive": true,
+ "priority": 0
+ }
+ }
+ ],
+ "visible": true
+ },
+ {
+ "id": 1,
+ "name": "Sun",
+ "parent": null,
+ "children": [],
+ "components": [
+ {
+ "type": "Transform",
+ "data": {
+ "position": {
+ "x": 0,
+ "y": 0,
+ "z": 0
+ }
+ }
+ },
+ {
+ "type": "Light2D",
+ "data": {
+ "type": 1,
+ "color": {
+ "r": 1,
+ "g": 1,
+ "b": 1,
+ "a": 1
+ },
+ "intensity": 1,
+ "direction": {
+ "x": 0,
+ "y": 0
+ },
+ "enabled": true
+ }
+ }
+ ],
+ "visible": true
+ },
+ {
+ "id": 2,
+ "name": "LitTriangles",
+ "parent": null,
+ "children": [],
+ "components": [
+ {
+ "type": "Transform",
+ "data": {
+ "position": {
+ "x": 0,
+ "y": 0,
+ "z": 0
+ }
+ }
},
{
- "id": 2,
- "name": "LitTriangles",
- "parent": null,
- "children": [],
- "components": [
- { "type": "Transform", "data": { "position": { "x": 0, "y": 0, "z": 0 } } },
- { "type": "Mesh2D", "data": { "color": { "r": 1, "g": 1, "b": 1, "a": 1 }, "layer": 0, "enabled": true } }
- ],
- "visible": true
+ "type": "Mesh2D",
+ "data": {
+ "color": {
+ "r": 1,
+ "g": 1,
+ "b": 1,
+ "a": 1
+ },
+ "layer": 0,
+ "enabled": true,
+ "lit": true,
+ "mesh": "/scenes/lit-triangles.esmesh"
+ }
}
- ]
+ ],
+ "visible": true
+ }
+ ]
}
diff --git a/desktop/public/scenes/normalmap-quad.esprefab b/desktop/public/scenes/normalmap-quad.esprefab
index ca6d31dd3..13500a611 100644
--- a/desktop/public/scenes/normalmap-quad.esprefab
+++ b/desktop/public/scenes/normalmap-quad.esprefab
@@ -18,6 +18,7 @@
"type": "Mesh2D",
"data": {
"mesh": "scenes/normalmap-quad.esmesh",
+ "lit": true,
"normalMap": "scenes/normalmap-quad_0.png",
"color": {
"r": 1,
diff --git a/pipeline/src/assets/gltfImport.ts b/pipeline/src/assets/gltfImport.ts
index b13b29574..eb98f90e8 100644
--- a/pipeline/src/assets/gltfImport.ts
+++ b/pipeline/src/assets/gltfImport.ts
@@ -945,6 +945,10 @@ function meshComponent(mesh: ImportedMesh, refs: ProductRefs): ComponentData {
const color = mesh.material?.baseColor;
return { type: 'Mesh2D', data: {
mesh: `${prefix}${mesh.name}.esmesh`,
+ // Geometry that carries normals was authored to be shaded, so the product
+ // says so. Written rather than assumed: `lit` is a field a user can turn
+ // off, and an import that left it out would be one the engine had to guess.
+ ...(hasNormals ? { lit: true } : {}),
...(texture ? { texture } : {}),
...(normalMap ? { normalMap } : {}),
...(color ? { color: { r: color[0], g: color[1], b: color[2], a: color[3] } } : {}),
diff --git a/src/esengine/data/shaders/mesh.esshader b/src/esengine/data/shaders/mesh.esshader
index ffb681a9f..adbeb0ad3 100644
--- a/src/esengine/data/shaders/mesh.esshader
+++ b/src/esengine/data/shaders/mesh.esshader
@@ -7,9 +7,14 @@
// copied, and the std140 block stays the engine's to own.
#pragma domain Lit2D
-// The variant a mesh WITH normals is drawn by. A layout may not declare an
-// attribute its shader does not consume, so normals and the normal matrix are
-// inside the switch on both sides.
+// What the GEOMETRY carries. A layout may not declare an attribute its shader
+// does not consume, so the normal channel and the per-object normal matrix are
+// inside this switch on both sides — whether or not the draw asks to be lit.
+#pragma feature MESH_NORMALS
+
+// What the DRAW asks for. Orthogonal to the above on purpose: geometry with
+// normals can be drawn unlit, and geometry without them can still take light
+// (off a constant normal, which is what a 2D surface has).
#pragma feature LIT
// A normal map on top of those normals. Its tangent frame comes from the shared
@@ -26,7 +31,7 @@
layout(location = 0) in vec3 a_position;
layout(location = 1) in vec4 a_color;
layout(location = 2) in vec2 a_texCoord;
-#ifdef LIT
+#ifdef MESH_NORMALS
layout(location = 3) in vec3 a_normal;
#endif
@@ -37,7 +42,7 @@ layout(location = 9) in vec4 a_model1;
layout(location = 10) in vec4 a_model2;
layout(location = 11) in vec4 a_model3;
layout(location = 12) in vec4 a_instTint;
-#ifdef LIT
+#ifdef MESH_NORMALS
// The normal matrix (inverse transpose of the model's 3x3), per object: under a
// non-uniform scale the model matrix skews a normal, and inverting one per
// vertex is the alternative.
@@ -66,7 +71,12 @@ void main() {
v_texCoord = a_texCoord;
v_color = a_color * a_instTint;
#ifdef LIT
+#ifdef MESH_NORMALS
v_worldNormal = mat3(a_nrm0, a_nrm1, a_nrm2) * a_normal;
+#else
+ // A surface with no normal channel faces the viewer, exactly as a sprite does.
+ v_worldNormal = vec3(0.0, 0.0, 1.0);
+#endif
v_worldPos = world.xyz;
#endif
}
@@ -111,7 +121,7 @@ struct VSIn {
@location(0) a_position : vec3f,
@location(1) a_color : vec4f,
@location(2) a_texCoord : vec2f,
-#ifdef LIT
+#ifdef MESH_NORMALS
@location(3) a_normal : vec3f,
#endif
@location(8) a_model0 : vec4f,
@@ -119,7 +129,7 @@ struct VSIn {
@location(10) a_model2 : vec4f,
@location(11) a_model3 : vec4f,
@location(12) a_instTint : vec4f,
-#ifdef LIT
+#ifdef MESH_NORMALS
@location(13) a_nrm0 : vec3f,
@location(14) a_nrm1 : vec3f,
@location(15) a_nrm2 : vec3f,
@@ -144,7 +154,12 @@ struct VSOut {
out.v_texCoord = v.a_texCoord;
out.v_color = v.a_color * v.a_instTint;
#ifdef LIT
+#ifdef MESH_NORMALS
out.v_worldNormal = mat3x3f(v.a_nrm0, v.a_nrm1, v.a_nrm2) * v.a_normal;
+#else
+ // A surface with no normal channel faces the viewer, exactly as a sprite does.
+ out.v_worldNormal = vec3f(0.0, 0.0, 1.0);
+#endif
out.v_worldPos = world.xyz;
#endif
return out;
diff --git a/src/esengine/renderer/plugins/MeshPlugin.cpp b/src/esengine/renderer/plugins/MeshPlugin.cpp
index 5680a9613..f56de92cd 100644
--- a/src/esengine/renderer/plugins/MeshPlugin.cpp
+++ b/src/esengine/renderer/plugins/MeshPlugin.cpp
@@ -33,16 +33,45 @@ u32 mulColor(u32 a, u32 b) {
u32 al = (((a >> 24) & 0xFF) * ((b >> 24) & 0xFF)) / 255u;
return r | (g << 8) | (bl << 16) | (al << 24);
}
+/// Which program a draw needs: what the GEOMETRY carries and what the DRAW asked
+/// for are separate questions, so they are separate bits.
+u32 meshVariant(bool normals, bool lit, bool normalMapped) {
+ return (normals ? 1u : 0u) | (lit ? 2u : 0u) | (normalMapped ? 4u : 0u);
+}
} // namespace
void MeshPlugin::init(RenderFrameContext& ctx) {
+ // A rebuild after a lost device runs this again, and every program minted
+ // against the dead context is gone — so the cache empties here rather than
+ // handing out ids that name nothing.
+ mesh_compiled_.fill(false);
+ mesh_programs_.fill(0);
+ // The base variant now, so a broken shader is a boot-time failure rather than
+ // one that waits for the first mesh; the rest compile when a draw asks.
+ meshProgram(ctx, false, false, false);
+}
+
+/**
+ * One permutation of the resident-mesh program, compiled on demand.
+ *
+ * A vertex layout may only declare attributes its shader consumes, so the
+ * geometry's own channels pick half of it; the draw's `lit` picks the other half,
+ * and unlit geometry carrying normals still has to declare them.
+ */
+u32 MeshPlugin::meshProgram(RenderFrameContext& ctx, bool normals, bool lit, bool normalMapped) {
+ const u32 variant = meshVariant(normals, lit, normalMapped);
+ if (mesh_compiled_[variant]) return mesh_programs_[variant];
+ mesh_compiled_[variant] = true;
+
+ std::vector<std::string> features;
+ if (normals) features.emplace_back("MESH_NORMALS");
+ if (lit) features.emplace_back("LIT");
+ if (normalMapped) features.emplace_back("NORMAL_MAP");
+
// Authored as mesh.esshader, WGSL twin included. Its vertex stage is the one
// that reads a model matrix, which is what lets the vertices stay local.
const auto target = ctx.resources.preferredShaderTarget();
auto parsed = resource::ShaderParser::parse(ShaderEmbeds::MESH);
- // Two permutations, because a vertex layout may only declare attributes its
- // shader consumes: geometry without normals must not be drawn by a program
- // that reads them, and the reverse leaves the normals unlit.
auto compile = [&](std::vector<std::string> features) -> u32 {
const bool normalMapped = std::find(features.begin(), features.end(), "NORMAL_MAP")
!= features.end();
@@ -61,9 +90,8 @@ void MeshPlugin::init(RenderFrameContext& ctx) {
}
return shader->getProgramId();
};
- mesh_shader_id_ = compile({});
- mesh_lit_shader_id_ = compile({"LIT"});
- mesh_normalmap_shader_id_ = compile({"LIT", "NORMAL_MAP"});
+ mesh_programs_[variant] = compile(features);
+ return mesh_programs_[variant];
}
void MeshPlugin::collect(RenderCollectContext& collect_ctx) {
@@ -109,9 +137,9 @@ void MeshPlugin::collect(RenderCollectContext& collect_ctx) {
textureId = tex->getId();
}
}
- // Only meaningful with normals to perturb, so it is read where that is known.
+ // Only meaningful with normals to perturb AND a draw that takes light.
u32 normalTextureId = 0;
- if (mesh.normalMap.isValid() && resident && resident->hasNormals) {
+ if (mesh.normalMap.isValid() && mesh.lit && resident && resident->hasNormals) {
if (Texture* tex = ctx.resources.getTexture(mesh.normalMap)) {
normalTextureId = tex->getId();
}
@@ -161,10 +189,12 @@ void MeshPlugin::collect(RenderCollectContext& collect_ctx) {
// Resident geometry: only the transform is written for the frame. Its
// vertices are local-space and untouched, so the CPU loop below — which
// exists to bake world space into every vertex — is skipped entirely.
- if (resident && mesh_shader_id_ != 0) {
- const u32 residentShader = normalTextureId != 0 && mesh_normalmap_shader_id_ != 0
- ? mesh_normalmap_shader_id_
- : (resident->hasNormals ? mesh_lit_shader_id_ : mesh_shader_id_);
+ if (resident && mesh_programs_[0] != 0) {
+ // `lit` is the draw's own word and is honoured either way: geometry
+ // with normals can be drawn unlit, and geometry without them takes
+ // light off the constant normal a 2D surface has.
+ const u32 residentShader =
+ meshProgram(ctx, resident->hasNormals, mesh.lit, normalTextureId != 0);
if (resident->isDrawable() && residentShader != 0) {
const u32 stride = resident->hasNormals
? MESH_INSTANCE_STRIDE_LIT : MESH_INSTANCE_STRIDE;
diff --git a/src/esengine/renderer/plugins/MeshPlugin.hpp b/src/esengine/renderer/plugins/MeshPlugin.hpp
index 7ff5f55aa..0238461b8 100644
--- a/src/esengine/renderer/plugins/MeshPlugin.hpp
+++ b/src/esengine/renderer/plugins/MeshPlugin.hpp
@@ -2,6 +2,7 @@
// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
#pragma once
+#include <array>
#include "../RenderTypePlugin.hpp"
#include "../draw/BatchVertex.hpp"
@@ -23,9 +24,12 @@ public:
private:
std::vector<BatchVertex> scratch_; ///< Reused per mesh; amortizes the transform buffer.
- u32 mesh_shader_id_ = 0; ///< Resident geometry with a per-object transform.
- u32 mesh_lit_shader_id_ = 0; ///< The same for geometry carrying normals.
- u32 mesh_normalmap_shader_id_ = 0; ///< Those normals, perturbed by a normal map.
+ /// Resident-geometry programs, indexed by {has normals, lit, normal-mapped}:
+ /// what the geometry carries and what the draw asked for are separate
+ /// questions. Compiled on first use — a scene draws one or two of the five.
+ std::array<u32, 8> mesh_programs_{};
+ std::array<bool, 8> mesh_compiled_{};
+ u32 meshProgram(RenderFrameContext& ctx, bool normals, bool lit, bool normalMapped);
bool warned_material_ = false; ///< A material on resident geometry is said once.
};
diff --git a/src/esengine/renderer/rhi/ShaderEmbeds.generated.hpp b/src/esengine/renderer/rhi/ShaderEmbeds.generated.hpp
index f0cc14d0f..942fe008b 100644
--- a/src/esengine/renderer/rhi/ShaderEmbeds.generated.hpp
+++ b/src/esengine/renderer/rhi/ShaderEmbeds.generated.hpp
@@ -280,9 +280,14 @@ inline constexpr const char* MESH = R"esshader(#pragma shader "Mesh"
// copied, and the std140 block stays the engine's to own.
#pragma domain Lit2D
-// The variant a mesh WITH normals is drawn by. A layout may not declare an
-// attribute its shader does not consume, so normals and the normal matrix are
-// inside the switch on both sides.
+// What the GEOMETRY carries. A layout may not declare an attribute its shader
+// does not consume, so the normal channel and the per-object normal matrix are
+// inside this switch on both sides — whether or not the draw asks to be lit.
+#pragma feature MESH_NORMALS
+
+// What the DRAW asks for. Orthogonal to the above on purpose: geometry with
+// normals can be drawn unlit, and geometry without them can still take light
+// (off a constant normal, which is what a 2D surface has).
#pragma feature LIT
// A normal map on top of those normals. Its tangent frame comes from the shared
@@ -299,7 +304,7 @@ inline constexpr const char* MESH = R"esshader(#pragma shader "Mesh"
layout(location = 0) in vec3 a_position;
layout(location = 1) in vec4 a_color;
layout(location = 2) in vec2 a_texCoord;
-#ifdef LIT
+#ifdef MESH_NORMALS
layout(location = 3) in vec3 a_normal;
#endif
@@ -310,7 +315,7 @@ layout(location = 9) in vec4 a_model1;
layout(location = 10) in vec4 a_model2;
layout(location = 11) in vec4 a_model3;
layout(location = 12) in vec4 a_instTint;
-#ifdef LIT
+#ifdef MESH_NORMALS
// The normal matrix (inverse transpose of the model's 3x3), per object: under a
// non-uniform scale the model matrix skews a normal, and inverting one per
// vertex is the alternative.
@@ -339,7 +344,12 @@ void main() {
v_texCoord = a_texCoord;
v_color = a_color * a_instTint;
#ifdef LIT
+#ifdef MESH_NORMALS
v_worldNormal = mat3(a_nrm0, a_nrm1, a_nrm2) * a_normal;
+#else
+ // A surface with no normal channel faces the viewer, exactly as a sprite does.
+ v_worldNormal = vec3(0.0, 0.0, 1.0);
+#endif
v_worldPos = world.xyz;
#endif
}
@@ -384,7 +394,7 @@ struct VSIn {
@location(0) a_position : vec3f,
@location(1) a_color : vec4f,
@location(2) a_texCoord : vec2f,
-#ifdef LIT
+#ifdef MESH_NORMALS
@location(3) a_normal : vec3f,
#endif
@location(8) a_model0 : vec4f,
@@ -392,7 +402,7 @@ struct VSIn {
@location(10) a_model2 : vec4f,
@location(11) a_model3 : vec4f,
@location(12) a_instTint : vec4f,
-#ifdef LIT
+#ifdef MESH_NORMALS
@location(13) a_nrm0 : vec3f,
@location(14) a_nrm1 : vec3f,
@location(15) a_nrm2 : vec3f,
@@ -417,7 +427,12 @@ struct VSOut {
out.v_texCoord = v.a_texCoord;
out.v_color = v.a_color * v.a_instTint;
#ifdef LIT
+#ifdef MESH_NORMALS
out.v_worldNormal = mat3x3f(v.a_nrm0, v.a_nrm1, v.a_nrm2) * v.a_normal;
+#else
+ // A surface with no normal channel faces the viewer, exactly as a sprite does.
+ out.v_worldNormal = vec3f(0.0, 0.0, 1.0);
+#endif
out.v_worldPos = world.xyz;
#endif
return out;
diff --git a/tools/renderScenes.mjs b/tools/renderScenes.mjs
index 86efba6b1..8c7d5bbc3 100644
--- a/tools/renderScenes.mjs
+++ b/tools/renderScenes.mjs
@@ -127,7 +127,7 @@ export const SCENES = [
// What a normal is FOR: two coplanar triangles, one white colour, normals
// facing the viewer and +X, under a head-on directional light. Only a shader
// reading them can tell the halves apart — which is what the two probes are.
- { id: "mesh-lit", tier: "pr", webgpu: true, env: { ESTELLA_VERIFY_MESH_ASSET: "/scenes/lit-triangles.esmesh", 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,255,255],\"tol\":40},{\"x\":0.70,\"y\":0.556,\"rgb\":[0,0,0],\"tol\":40}]" } },
+ { id: "mesh-lit", tier: "pr", webgpu: true, env: { 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,255,255],\"tol\":40},{\"x\":0.70,\"y\":0.556,\"rgb\":[0,0,0],\"tol\":40}]" } },
// A whole glTF import on screen, through the prefab it produced: geometry, the
// inline image, and the baseColor factor as the tint. The probes sit at the
// texel centres of a 2x2 image, so a flipped V swaps colours between them.
@@ -139,15 +139,24 @@ export const SCENES = [
// 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}]" } },
+ { id: "mesh-material-lit", tier: "pr", webgpu: true, env: { 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}]" } },
// The STOCK lit template on the same geometry: a flat normal there would light
// an imported model like a sprite — a wrong picture, not a missing one. Red
// tint, so the engine's own mesh shader (white) cannot pass for it.
- { id: "mesh-builtin-lit", tier: "pr", webgpu: true, env: { ESTELLA_VERIFY_MESH_ASSET: "/scenes/lit-triangles.esmesh", ESTELLA_VERIFY_MESH_MATERIAL: "/scenes/mesh-material-lit/builtinlit.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}]" } },
+ { id: "mesh-builtin-lit", tier: "pr", webgpu: true, env: { ESTELLA_VERIFY_MESH_MATERIAL: "/scenes/mesh-material-lit/builtinlit.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}]" } },
+ // `lit` is the DRAW's word, honoured whatever the geometry carries: a mesh with
+ // NO normal channel, under a red light. Lit, its green half goes black off the
+ // constant normal a 2D surface has; unlit, both halves are their vertex colours.
+ { id: "mesh-flat-lit", tier: "pr", webgpu: true, env: { ESTELLA_VERIFY_SCENE: "/scenes/mesh-flat-lit.esscene", ESTELLA_VERIFY_MANIFEST: "/scenes/mesh-flat-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\":30}]" } },
+ { id: "mesh-flat-lit-off", tier: "pr", webgpu: true, env: { ESTELLA_VERIFY_SET_FIELD: "{\"entity\":2,\"component\":\"Mesh2D\",\"key\":\"lit\",\"value\":false}", ESTELLA_VERIFY_SCENE: "/scenes/mesh-flat-lit.esscene", ESTELLA_VERIFY_MANIFEST: "/scenes/mesh-flat-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,255,0],\"tol\":40}]" } },
+ // The other half of that word: geometry that DOES carry normals, told not to
+ // take light. Its layout still declares the channel — the permutation a backend
+ // is strictest about — and both halves come back their own colour.
+ { id: "mesh-lit-off", tier: "pr", webgpu: true, env: { ESTELLA_VERIFY_SET_FIELD: "{\"entity\":2,\"component\":\"Mesh2D\",\"key\":\"lit\",\"value\":false}", 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,255,255],\"tol\":40},{\"x\":0.70,\"y\":0.556,\"rgb\":[255,255,255],\"tol\":40}]" } },
// A thumbnail of the geometry itself, offscreen through the viewport's own
// path. What it adds over a material ball is the FRAMING: the gate asks for a
// clear border (nothing escaped) and an outer eighth reached (nothing shrank).
- { id: "mesh-preview", tier: "pr", webgpu: true, env: { ESTELLA_VERIFY_MESH_PREVIEW: "{\"w\":128,\"h\":128}", ESTELLA_VERIFY_MESH_ASSET: "/scenes/lit-triangles.esmesh", 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" } },
+ { id: "mesh-preview", tier: "pr", webgpu: true, env: { ESTELLA_VERIFY_MESH_PREVIEW: "{\"w\":128,\"h\":128}", 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" } },
// A SCENE camera that looks from somewhere else. Two sprites on the camera's
// own axis project to ONE point for a 2D camera; pitched 20 deg they land at
// 0.329 and 0.158 down the frame — arithmetic — and the centre is empty.