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): whether a surface has normals does not decide where its light is

esengine6e995ecc2c38
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 88f6f5b12..dea98e92c 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -14,6 +14,24 @@ published separately; it ships inside the editor.
## [Unreleased]
+### Fixed
+
+- **Whether a surface has normals no longer decides where its light is.** Two
+ facts had one switch: `MESH_NORMALS` said "this geometry carries a normal
+ channel", and the injected lighting read it as "so measure the light in three
+ dimensions". A mesh's fragment gets its real world position either way — the
+ channel is about the surface's *orientation* — so geometry imported without
+ normals was lit by a lamp hovering its own falloff radius above the plane while
+ standing 120 units above it, and the two lit the same surface differently for a
+ reason that had nothing to do with lighting.
+
+ `ES_SURFACE_3D` is now that second fact, set by the vertex sources that give a
+ fragment a real world position. A sprite still does not: it has no depth of its
+ own to measure against, which is the whole compatibility story and unchanged.
+ **Flat-shaded 3D geometry near a point or spot light does change appearance** —
+ the new gate measures the difference at 74 colour levels, and the old behaviour
+ flattened three probes that should differ to within four.
+
### Added
- **A directional shadow spends its texels on what is near.** One 1024 map covered
diff --git a/desktop/public/scenes/mesh-flat-point-3d.esscene b/desktop/public/scenes/mesh-flat-point-3d.esscene
new file mode 100644
index 000000000..2ab068021
--- /dev/null
+++ b/desktop/public/scenes/mesh-flat-point-3d.esscene
@@ -0,0 +1,101 @@
+{
+ "version": 1,
+ "name": "MeshFlatPoint3D",
+ "entities": [
+ {
+ "id": 0,
+ "name": "Camera",
+ "parent": null,
+ "children": [],
+ "visible": true,
+ "components": [
+ {
+ "type": "Transform",
+ "data": {
+ "position": {
+ "x": 0,
+ "y": 0,
+ "z": 10
+ }
+ }
+ },
+ {
+ "type": "Camera",
+ "data": {
+ "projectionType": 1,
+ "orthoSize": 300,
+ "isActive": true,
+ "priority": 0
+ }
+ }
+ ]
+ },
+ {
+ "id": 1,
+ "name": "Panel",
+ "parent": null,
+ "children": [],
+ "visible": true,
+ "components": [
+ {
+ "type": "Transform",
+ "data": {
+ "position": {
+ "x": 0,
+ "y": 0,
+ "z": 0
+ }
+ }
+ },
+ {
+ "type": "Mesh2D",
+ "data": {
+ "mesh": "/scenes/white-triangles.esmesh",
+ "color": {
+ "r": 1,
+ "g": 1,
+ "b": 1,
+ "a": 1
+ },
+ "lit": true,
+ "opaque": true,
+ "enabled": true
+ }
+ }
+ ]
+ },
+ {
+ "id": 2,
+ "name": "Lamp",
+ "parent": null,
+ "children": [],
+ "visible": true,
+ "components": [
+ {
+ "type": "Transform",
+ "data": {
+ "position": {
+ "x": 0,
+ "y": 0,
+ "z": 120
+ }
+ }
+ },
+ {
+ "type": "Light2D",
+ "data": {
+ "type": 0,
+ "color": {
+ "r": 1,
+ "g": 1,
+ "b": 1,
+ "a": 1
+ },
+ "intensity": 1,
+ "radius": 1000
+ }
+ }
+ ]
+ }
+ ]
+}
diff --git a/src/esengine/renderer/plugins/MeshPlugin.cpp b/src/esengine/renderer/plugins/MeshPlugin.cpp
index fb566ffe8..f924e483d 100644
--- a/src/esengine/renderer/plugins/MeshPlugin.cpp
+++ b/src/esengine/renderer/plugins/MeshPlugin.cpp
@@ -126,6 +126,10 @@ u32 MeshPlugin::meshProgram(RenderFrameContext& ctx, bool normals, bool lit, boo
else if (lit) {
features.emplace_back("ES_RECEIVE_SHADOW");
if (envMapped) features.emplace_back("ES_ENV_MAP");
+ // Resident geometry's world position is the real one whether or not it
+ // carries normals: two separate facts, and reading a light's distance in
+ // the plane on a surface that HAS depth is the 2D convention misapplied.
+ features.emplace_back("ES_SURFACE_3D");
}
// Authored as mesh.esshader, WGSL twin included. Its vertex stage is the one
diff --git a/src/esengine/renderer/store/MaterialStore.cpp b/src/esengine/renderer/store/MaterialStore.cpp
index f0d671589..711ec7c30 100644
--- a/src/esengine/renderer/store/MaterialStore.cpp
+++ b/src/esengine/renderer/store/MaterialStore.cpp
@@ -77,6 +77,9 @@ u32 MaterialStore::meshProgram(u32 materialId, resource::ResourceManager& resour
// is why these ride the mesh path.
features.push_back("ES_RECEIVE_SHADOW");
if (envMapped) features.push_back("ES_ENV_MAP");
+ // As above: this vertex source gives the fragment a real world position, so a
+ // positional light is read from where it is rather than from the plane.
+ features.push_back("ES_SURFACE_3D");
const auto target = resources.preferredShaderTarget();
const std::string vert = resource::ShaderParser::assembleStage(
parsed, resource::ShaderStage::Vertex, "", features, target);
diff --git a/src/esengine/resource/ShaderParser.cpp b/src/esengine/resource/ShaderParser.cpp
index d47b9b0ca..891695df5 100644
--- a/src/esengine/resource/ShaderParser.cpp
+++ b/src/esengine/resource/ShaderParser.cpp
@@ -917,7 +917,10 @@ fn envRadiance(R : vec3f, roughness : f32) -> vec3f {
let b = envSampleMip(R, min(lo + 1.0, lc.u_envParams.z));
return lc.u_ambient.rgb + mix(a, b, lod - lo) * lc.u_envTint.rgb;
}
-#ifdef MESH_NORMALS
+// Which definition of "where is the light" this surface is shaded with. One with a
+// real third coordinate measures against the light's own; a sprite has no depth to
+// measure against, so a positional light goes on hovering its radius above it.
+#ifdef ES_SURFACE_3D
fn lightVector(pd : vec4f, sh : vec4f, worldPos : vec3f) -> vec3f {
return vec3f(pd.xy, sh.z) - worldPos;
}
@@ -1536,7 +1539,10 @@ ShaderParser::AssembledStage ShaderParser::assembleStageEx(const ParsedShader& p
// Where a positional light is, from here, and how far. Real geometry measures
// against the light's own world height; a sprite has no depth of its own and
// keeps the plane's convention of one hovering its falloff radius above it.
- "#ifdef MESH_NORMALS\n"
+ // Which definition of "where is the light" this surface is shaded with.
+ // One with a real third coordinate measures against the light's own; a
+ // sprite has none, so a light goes on hovering its radius above it.
+ "#ifdef ES_SURFACE_3D\n"
"highp vec3 lightVector(in highp vec4 pd, in highp vec4 sh, in highp vec3 worldPos) {\n"
" return vec3(pd.xy, sh.z) - worldPos;\n"
"}\n"
diff --git a/tools/renderScenes.mjs b/tools/renderScenes.mjs
index 387c8aaa9..fb1569bfc 100644
--- a/tools/renderScenes.mjs
+++ b/tools/renderScenes.mjs
@@ -70,6 +70,7 @@ export const SCENES = [
// A lamp 120 units ABOVE a panel, a height only real geometry measures against.
// Hand-derived, 255·NdotL·atten: 224 under it and 101 at world +200, where the
// plane's convention reads 255 and 200.
+ { id: "mesh-flat-point-3d", tier: "pr", webgpu: true, env: { ESTELLA_VERIFY_SCENE: "/scenes/mesh-flat-point-3d.esscene", ESTELLA_VERIFY_W: "256", ESTELLA_VERIFY_H: "256", ESTELLA_VERIFY_STEPS: "2", ESTELLA_VERIFY_EXPECT: "[{\"x\":0.7,\"y\":0.5,\"rgb\":[149,149,149],\"tol\":20},{\"x\":0.7,\"y\":0.6,\"rgb\":[139,139,139],\"tol\":20},{\"x\":0.5,\"y\":0.5,\"rgb\":[0,0,0],\"tol\":10}]" } },
{ id: "mesh-point-3d", tier: "pr", webgpu: true, env: { ESTELLA_VERIFY_SCENE: "/scenes/mesh-point-3d.esscene", ESTELLA_VERIFY_W: "256", ESTELLA_VERIFY_H: "256", ESTELLA_VERIFY_STEPS: "2", ESTELLA_VERIFY_EXPECT: "[{\"x\":0.5,\"y\":0.5,\"rgb\":[224,224,224],\"tol\":20},{\"x\":0.833,\"y\":0.5,\"rgb\":[102,102,102],\"tol\":20}]" } },
// Geometry with no file under it. Sun 22.5° off the view axis: the cube's two faces
// read 255·cos22.5 and 255·cos67.5, swapped if the winding is inside out; the sphere