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): a hard shadow's edge is filtered, not stepped along the shadow map's grid

esengine34c8cb975485
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 83ece05b7..81c0fe70c 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -33,6 +33,7 @@ published separately; it ships inside the editor.
### Fixed
+- **A hard shadow's edge is a clean line, not a row of stair-steps.** Its four samples of the shadow map were weighted equally, so the edge moved in whole texels of the map, and wherever the shadow crossed the map's grid at an angle — which is almost everywhere — its edge showed the grid as dotted steps. It is now filtered over the 3×3 texels around each point, weighted by where it falls among them: on a shadow at 30° to the map the edge strays 0.05 px from a straight line, where it strayed 0.25.
- **A drawn sky is the panorama you imported, not a blur of it.** The sky was drawn from the environment's reflection atlas — the whole sphere in 128 texels a side, laid out so a straight horizon became a staircase and a round sun an oval, and filtered in its encoded form, which blotted every sharp edge. Importing a `.hdr` now also writes the panorama at its own resolution (up to 2048 wide; `skyWidth` in the import settings, 0 for none), the sky is drawn from it, and a package carries it. Environments imported before draw their sky from the atlas as they did. The `lighting-3d` example draws its sky, from a panorama generated at 1024×512.
- **A drawn sky no longer vanishes, or half-vanishes, as the view turns.** The sky was a quad on the far plane, and where rounding put it a hair past that plane it was clipped: in the editor, with its distant far plane, more than half the angles showed black behind the grid, or a sky cut along a diagonal. It now sits inside the view volume and fills the frame from every angle, in the editor and in the game.
- **With more than one camera, the profiler and the draw-call count cover the whole frame.** Each camera reset the frame's tally and closed the profiler's frame, so a split screen, or a scene with a UI camera, reported only the last camera's draw calls, triangles, merge counts and C++ timings, and the batch-break reasons of the others were lost. The frame now counts every camera and the screen overlay, once, and an asset preview rendered in between counts toward none of them.
diff --git a/fixtures/scenes/mesh-shadow-tilt.esscene b/fixtures/scenes/mesh-shadow-tilt.esscene
new file mode 100644
index 000000000..dcc3fdbb7
--- /dev/null
+++ b/fixtures/scenes/mesh-shadow-tilt.esscene
@@ -0,0 +1,155 @@
+{
+ "version": 4,
+ "name": "MeshShadowTilt",
+ "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": "Ground",
+ "parent": null,
+ "children": [],
+ "visible": true,
+ "components": [
+ {
+ "type": "Transform",
+ "data": {
+ "position": {
+ "x": 0,
+ "y": 0,
+ "z": -200
+ },
+ "scale": {
+ "x": 600,
+ "y": 600,
+ "z": 1
+ }
+ }
+ },
+ {
+ "type": "MeshRenderer",
+ "data": {
+ "mesh": "/scenes/shadow-quad.esmesh",
+ "color": {
+ "r": 1,
+ "g": 1,
+ "b": 1,
+ "a": 1
+ },
+ "lit": true,
+ "opaque": true,
+ "enabled": true
+ }
+ }
+ ]
+ },
+ {
+ "id": 2,
+ "name": "Blocker",
+ "parent": null,
+ "children": [],
+ "visible": true,
+ "components": [
+ {
+ "type": "Transform",
+ "data": {
+ "position": {
+ "x": 0,
+ "y": 0,
+ "z": 0
+ },
+ "scale": {
+ "x": 150,
+ "y": 150,
+ "z": 1
+ },
+ "rotation": {
+ "w": 0.965926,
+ "x": 0,
+ "y": 0,
+ "z": 0.258819
+ }
+ }
+ },
+ {
+ "type": "MeshRenderer",
+ "data": {
+ "mesh": "/scenes/shadow-quad.esmesh",
+ "color": {
+ "r": 1,
+ "g": 1,
+ "b": 1,
+ "a": 1
+ },
+ "lit": true,
+ "opaque": true,
+ "enabled": true
+ }
+ }
+ ]
+ },
+ {
+ "id": 3,
+ "name": "Sun",
+ "parent": null,
+ "children": [],
+ "visible": true,
+ "components": [
+ {
+ "type": "Transform",
+ "data": {
+ "position": {
+ "x": 0,
+ "y": 0,
+ "z": 0
+ }
+ }
+ },
+ {
+ "type": "Light",
+ "data": {
+ "type": 1,
+ "color": {
+ "r": 1,
+ "g": 1,
+ "b": 1,
+ "a": 1
+ },
+ "intensity": 1,
+ "direction": {
+ "x": 0.5,
+ "y": 0
+ },
+ "meshShadows": true
+ }
+ }
+ ]
+ }
+ ]
+}
diff --git a/src/esengine/resource/ShaderParser.cpp b/src/esengine/resource/ShaderParser.cpp
index 4f02d4924..4513fbe22 100644
--- a/src/esengine/resource/ShaderParser.cpp
+++ b/src/esengine/resource/ShaderParser.cpp
@@ -1143,16 +1143,23 @@ fn shadowFactor3D(worldPos : vec3f, N : vec3f, L : vec3f, source : vec2f,
// the tangent of the angle it subtends where its w is 1 everywhere.
let hasEye = length(vec3f(m[0].w, m[1].w, m[2].w)) > 0.5;
let src = select(source.y, source.x, hasEye);
- // A source with no size throws one edge, and four taps are its whole cost.
+ // A source with no size throws one edge: a tent over the 3x3 texels around the
+ // point, weighted by where it falls among them. Equal weights step at every
+ // texel and the map's grid shows along the edge; a 2x2 still stair-steps it.
if (src <= 0.0) {
+ let texelUv = lc.u_shadowParams.y;
+ let f = at0 / texelUv - 1.0;
+ let c = (floor(f) + 0.5) * texelUv;
+ let t = fract(f);
+ let wx = array<f32, 3>((1.0 - t.x) * 0.5, 0.5, t.x * 0.5);
+ let wy = array<f32, 3>((1.0 - t.y) * 0.5, 0.5, t.y * 0.5);
var lit = 0.0;
- for (var y = 0; y < 2; y++) {
- for (var x = 0; x < 2; x++) {
- let o = (vec2f(f32(x), f32(y)) - 0.5) * lc.u_shadowParams.y;
- lit += shadowTap(at0 + o, lo, hi, here);
+ for (var y = 0; y < 3; y++) {
+ for (var x = 0; x < 3; x++) {
+ lit += wx[x] * wy[y] * shadowTap(c + vec2f(f32(x), f32(y)) * texelUv, lo, hi, here);
}
}
- return lit * 0.25;
+ return lit;
}
// What blocks this fragment, over the whole disc an edge can reach across — and
// against a depth that forgives that reach, since a tap r texels away lands r
@@ -1961,16 +1968,24 @@ ShaderParser::AssembledStage ShaderParser::assembleStageEx(const ParsedShader& p
// the tangent of the angle it subtends where its w is 1 everywhere.
" bool hasEye = length(vec3(m[0][3], m[1][3], m[2][3])) > 0.5;\n"
" highp float src = hasEye ? source.x : source.y;\n"
- // A source with no size throws one edge, and four taps are its whole cost.
+ // A source with no size throws one edge: a tent over the 3x3 texels around the
+ // point, weighted by where it falls among them. Equal weights step at every
+ // texel and the map's grid shows along the edge; a 2x2 still stair-steps it.
" if (src <= 0.0) {\n"
+ " highp float texelUv = u_shadowParams.y;\n"
+ " highp vec2 f = at0 / texelUv - 1.0;\n"
+ " highp vec2 c = (floor(f) + 0.5) * texelUv;\n"
+ " highp vec2 t = fract(f);\n"
+ " highp vec3 wx = vec3((1.0 - t.x) * 0.5, 0.5, t.x * 0.5);\n"
+ " highp vec3 wy = vec3((1.0 - t.y) * 0.5, 0.5, t.y * 0.5);\n"
" highp float lit = 0.0;\n"
- " for (int y = 0; y < 2; ++y) {\n"
- " for (int x = 0; x < 2; ++x) {\n"
- " highp vec2 o = (vec2(float(x), float(y)) - 0.5) * u_shadowParams.y;\n"
- " lit += shadowTap(at0 + o, lo, hi, here);\n"
+ " for (int y = 0; y < 3; ++y) {\n"
+ " for (int x = 0; x < 3; ++x) {\n"
+ " lit += wx[x] * wy[y] * shadowTap(c + vec2(float(x), float(y)) * texelUv,\n"
+ " lo, hi, here);\n"
" }\n"
" }\n"
- " return lit * 0.25;\n"
+ " return lit;\n"
" }\n"
// What blocks this fragment, over the whole disc an edge can reach across —
// against a depth that forgives that reach, since a tap r texels out lands r
diff --git a/tools/check-render-scenes.mjs b/tools/check-render-scenes.mjs
index e0b5f0025..c5d9abdbe 100644
--- a/tools/check-render-scenes.mjs
+++ b/tools/check-render-scenes.mjs
@@ -46,7 +46,7 @@ for (const s of SCENES) {
|| s.env.ESTELLA_VERIFY_SEAM
|| s.env.ESTELLA_VERIFY_GRID || s.env.ESTELLA_VERIFY_PREVIEW
|| s.env.ESTELLA_VERIFY_MESH_PREVIEW || s.env.ESTELLA_VERIFY_DEPTH_LAYERS
- || s.env.ESTELLA_VERIFY_COUNTERS || s.env.ESTELLA_VERIFY_COUNTERS_MAX || s.env.ESTELLA_VERIFY_FRAME_DEBUG
+ || s.env.ESTELLA_VERIFY_COUNTERS || s.env.ESTELLA_VERIFY_COUNTERS_MAX || s.env.ESTELLA_VERIFY_FRAME_DEBUG || s.env.ESTELLA_VERIFY_EDGE
|| s.env.ESTELLA_VERIFY_DRAW_CALLS
|| s.env.ESTELLA_VERIFY_YSORT || s.id === 'sprite-default';
if (!asserts && !s.rendersOnly) {
diff --git a/tools/releaseNotes.mjs b/tools/releaseNotes.mjs
index 2ced364ad..cfd16e54f 100644
--- a/tools/releaseNotes.mjs
+++ b/tools/releaseNotes.mjs
@@ -988,6 +988,8 @@ export const NOTED = {
{ note: 'A frame can be captured draw call by draw call, and replayed up to any one of them.' },
'feat(render): a frame capture lists every texture a draw bound':
{ note: 'A frame can be captured draw call by draw call, and replayed up to any one of them.' },
+ 'fix(render): a hard shadow\'s edge is filtered, not stepped along the shadow map\'s grid':
+ { note: 'A hard shadow\'s edge is a clean line, not a row of stair-steps.' },
'feat(render): the sky is drawn from the panorama it was imported from':
{ note: 'A drawn sky is the panorama you imported, not a blur of it.' },
'feat(editor): importing a panorama writes the sky it is drawn from':
diff --git a/tools/render-host/run.mjs b/tools/render-host/run.mjs
index 89d66a711..20889424e 100644
--- a/tools/render-host/run.mjs
+++ b/tools/render-host/run.mjs
@@ -34,6 +34,7 @@
* ESTELLA_VERIFY_COUNTERS_MAX counters the frame must stay UNDER — a budget (JSON)
* ESTELLA_VERIFY_FRAME_DEBUG capture the frame and replay it (the frame debugger)
* ESTELLA_VERIFY_UNIFORM the frame is one colour on purpose; ESTELLA_VERIFY_COUNT says which
+ * ESTELLA_VERIFY_EDGE how straight a straight edge is drawn (JSON: box, lit, dark, maxJag)
* ESTELLA_VERIFY_SCALE copy the scene's content onto a grid (JSON), for a cost gate
* ESTELLA_VERIFY_OUTPUT_TRANSFORM the frame's output curve ("aces")
* ESTELLA_VERIFY_PROFILE record N further frames and report the TS/C++ cost split
@@ -214,7 +215,7 @@ function finish(result, server) {
(result.seam?.ok ?? true) &&
(result.resize?.ok ?? true) && (result.preview?.ok ?? true) &&
(result.meshPreview?.ok ?? true) && (result.grid?.ok ?? true) &&
- (result.draws?.ok ?? true) && (result.counters?.ok ?? true) && (result.frameDebug?.ok ?? true) &&
+ (result.draws?.ok ?? true) && (result.counters?.ok ?? true) && (result.frameDebug?.ok ?? true) && (result.edge?.ok ?? true) &&
(result.roundtrip?.ok ?? true) && deviceLossOk && meshOk && pickOk;
const why = assetsOk ? '' : `: could not load ${result.missingAssets.join(', ')}`;
console.log(`\n[verify:render] ${ok ? 'PASS' : 'FAIL'} — ${SCENE} (${BACKEND})${why}`);
@@ -744,6 +745,36 @@ app.whenReady().then(async () => {
return { points: out, ok: out.every((o) => o.ok) };
`);
}
+ // ESTELLA_VERIFY_EDGE = { box (0..1, top-left), lit, dark, maxJag }: how far each
+ // row's crossing of a straight edge, found from the right to sub-pixel, strays from
+ // a line through its neighbours — a sampling grid drawn into the edge shows as that.
+ let edge = null;
+ if (process.env.ESTELLA_VERIFY_EDGE) {
+ edge = await readFrame(`
+ const e = ${JSON.stringify(JSON.parse(process.env.ESTELLA_VERIFY_EDGE))};
+ const lum = (x, y) => { const i = (((h - 1) - y) * w + x) * 4; return (px[i] + px[i + 1] + px[i + 2]) / 3; };
+ const mid = (e.lit + e.dark) / 2;
+ const [x0, y0, x1, y1] = [e.box[0] * w, e.box[1] * h, e.box[2] * w, e.box[3] * h].map(Math.round);
+ const pos = [];
+ for (let y = y0; y < y1; y++) {
+ for (let x = x1 - 1; x > x0; x--) {
+ const a = lum(x, y), b = lum(x - 1, y);
+ if (a >= mid && b < mid) { pos.push([y, x - (a - mid) / (a - b)]); break; }
+ }
+ }
+ const res = [];
+ for (let k = 4; k < pos.length - 4; k++) {
+ const win = pos.slice(k - 4, k + 5);
+ const my = win.reduce((s, p) => s + p[0], 0) / win.length;
+ const mx = win.reduce((s, p) => s + p[1], 0) / win.length;
+ const sxy = win.reduce((s, p) => s + (p[0] - my) * (p[1] - mx), 0);
+ const syy = win.reduce((s, p) => s + (p[0] - my) ** 2, 0);
+ res.push(Math.abs(pos[k][1] - (mx + (sxy / syy) * (pos[k][0] - my))));
+ }
+ const jag = res.length ? res.reduce((s, v) => s + v, 0) / res.length : Infinity;
+ return { rows: pos.length, jag, maxJag: e.maxJag, ok: pos.length >= (y1 - y0) * 0.8 && jag <= e.maxJag };
+ `);
+ }
// ESTELLA_VERIFY_COUNT is a JSON array of { rgb:[r,g,b], tol?, atLeast?, atMost? }:
// HOW MANY pixels of the frame are that colour, rather than which ones — a
// point probe cannot ask that without also naming where a font put them.
@@ -942,7 +973,7 @@ app.whenReady().then(async () => {
`);
if (respaced != null) grid = { ...grid, respacedPixels: respaced, ok: grid.ok && respaced > 300 };
}
- finish({ ok: true, entityCount, missingAssets, drawCalls, draws, counters, frameDebug, profile, capture, expect, count, seam, resize, preview, meshPreview, grid, deviceLoss, roundtrip, meshResident, meshAsset, meshMaterial, meshPrefab, setField, animator, pick, cameraTarget }, server);
+ finish({ ok: true, entityCount, missingAssets, drawCalls, draws, counters, frameDebug, edge, profile, capture, expect, count, seam, resize, preview, meshPreview, grid, deviceLoss, roundtrip, meshResident, meshAsset, meshMaterial, meshPrefab, setField, animator, pick, cameraTarget }, server);
} catch (e) {
finish({ ok: false, error: String((e && e.stack) || e) }, server);
}
diff --git a/tools/renderScenes.mjs b/tools/renderScenes.mjs
index 2c1dc2c6f..ebec50482 100644
--- a/tools/renderScenes.mjs
+++ b/tools/renderScenes.mjs
@@ -159,6 +159,9 @@ export const SCENES = [
// x, so the shadow lands 100 along +x and x 75..175 is floor the light cannot see.
// The blocker itself stays lit — shadowing one's own caster is the classic bug.
{ id: "mesh-shadow", tier: "pr", webgpu: true, env: { ESTELLA_VERIFY_SCENE: "/scenes/mesh-shadow.esscene", ESTELLA_VERIFY_W: "256", ESTELLA_VERIFY_H: "256", ESTELLA_VERIFY_STEPS: "2", ESTELLA_VERIFY_EXPECT: "[{\"x\":0.708,\"y\":0.5,\"rgb\":[0,0,0],\"tol\":20},{\"x\":0.167,\"y\":0.5,\"rgb\":[228,228,228],\"tol\":20},{\"x\":0.5,\"y\":0.5,\"rgb\":[228,228,228],\"tol\":20}]" } },
+ // The same shadow turned 30 degrees, so its edges cross the map's texel grid; a
+ // filter that draws that grid into them strays by a quarter pixel, this one by 0.05.
+ { id: "mesh-shadow-tilt", tier: "pr", webgpu: true, env: { ESTELLA_VERIFY_SCENE: "/scenes/mesh-shadow-tilt.esscene", ESTELLA_VERIFY_W: "512", ESTELLA_VERIFY_H: "512", ESTELLA_VERIFY_STEPS: "2", ESTELLA_VERIFY_EDGE: "{\"box\":[0.6,0.36,0.9,0.52],\"lit\":228,\"dark\":0,\"maxJag\":0.12}", ESTELLA_VERIFY_EXPECT: "[{\"x\":0.167,\"y\":0.5,\"rgb\":[228,228,228],\"tol\":20}]" } },
// The same scene with a MATERIAL on the occluder, over three frames because a
// stale sampler unit needs a previous frame. Red at the centre says the material