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(shadow): a caster narrower than the blocker search's gaps no longer vanishes from a wide shadow map

yhha8604b229601
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 4e50ccfcf..8145cc379 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -39,6 +39,7 @@ published separately; it ships inside the editor.
### Fixed
+- **A small caster no longer drops out of a wide shadow map.** A light's soft shadow first looks for what blocks a point over a disc of 24 texels, with sixteen taps spread over it, none within four texels of the point: a caster narrower than the gaps between them (about a dozen texels) could stand right over the point and be missed, so with a sun whose `shadowExtent` is large (a texel of 30 units, a bush two of them wide) its shadow was speckled and then gone. The point's own texel and the four a step and a half round it are asked first now. A frame of the Terrain & Water example costs 0.2 to 0.4 ms more where it is lit, and the shadows of its bushes, stones and flowers are there.
- **A material's vertex hook reads its own textures when it casts a shadow.** The program a caster is drawn with into a shadow map had its texture samplers left on unit 0, so a hook that reads a texture (the terrain's height pages) read another texture there, and the terrain cast the shadow of heights that were not its own. The samplers are set on the units the material declares them on, as the program it is drawn with in colour has them.
## [0.95.0] - 2026-10-25
diff --git a/docs/TERRAIN_WATER_GPU_COST.md b/docs/TERRAIN_WATER_GPU_COST.md
index 511c47fcf..2f8e32e6e 100644
--- a/docs/TERRAIN_WATER_GPU_COST.md
+++ b/docs/TERRAIN_WATER_GPU_COST.md
@@ -458,4 +458,21 @@
画面与之前逐像素比(排除运行间本来就不同的部分):平均差 0.03 到 0.39/255,差超过 24 的像素为 0。`mesh-shadow-cull` 渲染场景在两个后端上钉住两件事:相机身后的投射体仍然给前面的地面投影,一个在图里但影子落在视野外的被画少一个(`render.shadow.castersCulled` = 1)。
-**没做的:缓存。**图的内容随相机变(植物只在相机的绘制距离内有),缓存一张整图要么常常失效,要么要像虚拟阴影图那样分页;这次的剔除是不改变任何像素的那一半,先拿了。**另一个发现:**把固定范围设成 8000(图的纹素约 4 个世界单位)时 60 单位宽的投射体的影子整个消失,3000 和 1500 正常,没有查,是另一个问题。
+**没做的:缓存。**图的内容随相机变(植物只在相机的绘制距离内有),缓存一张整图要么常常失效,要么要像虚拟阴影图那样分页;这次的剔除是不改变任何像素的那一半,先拿了。**另一个发现(已查清并修了,见下一节):**固定范围过大时小投射体的影子消失。
+
+### 固定范围过大时小投射体的影子消失(2026-10-26,查清并修了)
+
+**现象:**同一个场景(一块 60 单位宽的投射体在相机身后给前面的地面投影),`shadowExtent` 1500 和 3000 时影子正常,4000 时影子变成斑点,8000 时整个没有;把投射体放大到 200 单位,8000 时又正常。
+
+**原因:**不是图的分辨率不够,也不是偏置或深度精度。软阴影先在 24 个纹素半径的圆盘里找遮挡点(`kShadowDisc`),只用 16 个采样,而且这些采样按半径的平方根分布,**离这一点 4 个纹素以内一个采样也没有**,采样之间相隔约 12 个纹素。一个窄于这个间隔的投射体,即使正好站在这一点上方,也大概率一个采样都碰不到,`hits < 0.5` 就当成“没有遮挡”,返回全亮。纹素越大(范围越大)投射体占的纹素越少,所以随范围增大先变成斑点再消失。示例的太阳范围是 16000(纹素约 31 个世界单位),灌木、石头、花的影子就是这样没有的。
+
+**修:**先问这一点自己的纹素和它周围一步半的四个纹素(5 个采样),结果和后面 16 个一样进遮挡平均,`hits > 20.5` 才算在影子里面。两个后端都改了。
+
+| | 修之前 | 修之后 |
+|---|---|---|
+| 范围 8000,60 单位投射体 | 没有影子 | 有,边缘干净 |
+| 范围 4000 | 斑点 | 实心 |
+| 示例 Model 段(机位 1 / 3) | 6.72 / 6.69 ms | 7.13 / 6.86 ms(多 0.2 到 0.4) |
+| 画面平均差 | | 0.27 / 1.12 / 1.42(机位 1 / 0 / 3),差超过 24 的像素 0.1% 到 0.3%:灌木、石头、箱子的影子出现了 |
+
+`mesh-shadow-small` 渲染场景在两个后端上钉住它(范围 8000,60 单位投射体的影子必须在)。18 个阴影与光照场景在两个后端都通过。
diff --git a/fixtures/scenes/mesh-shadow-small.esscene b/fixtures/scenes/mesh-shadow-small.esscene
new file mode 100644
index 000000000..fb765a06b
--- /dev/null
+++ b/fixtures/scenes/mesh-shadow-small.esscene
@@ -0,0 +1,152 @@
+{
+ "version": 4,
+ "name": "MeshShadowSmall",
+ "entities": [
+ {
+ "id": 0,
+ "name": "Camera",
+ "parent": null,
+ "children": [],
+ "visible": true,
+ "components": [
+ {
+ "type": "Transform",
+ "data": {
+ "position": {
+ "x": 0,
+ "y": 0,
+ "z": 500
+ }
+ }
+ },
+ {
+ "type": "Camera",
+ "data": {
+ "projectionType": 0,
+ "fov": 45,
+ "nearPlane": 10,
+ "farPlane": 4000,
+ "isActive": true,
+ "priority": 0
+ }
+ }
+ ]
+ },
+ {
+ "id": 1,
+ "name": "Ground",
+ "parent": null,
+ "children": [],
+ "visible": true,
+ "components": [
+ {
+ "type": "Transform",
+ "data": {
+ "position": {
+ "x": 0,
+ "y": 0,
+ "z": 250
+ },
+ "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": "Caster",
+ "parent": null,
+ "children": [],
+ "visible": true,
+ "components": [
+ {
+ "type": "Transform",
+ "data": {
+ "position": {
+ "x": 0,
+ "y": 60,
+ "z": 900
+ },
+ "scale": {
+ "x": 60,
+ "y": 60,
+ "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": 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.05,
+ "y": 0
+ },
+ "meshShadows": true,
+ "shadowExtent": 8000
+ }
+ }
+ ]
+ }
+ ]
+}
\ No newline at end of file
diff --git a/src/esengine/resource/ShaderParser.cpp b/src/esengine/resource/ShaderParser.cpp
index 9a50db6af..0ceeb59de 100644
--- a/src/esengine/resource/ShaderParser.cpp
+++ b/src/esengine/resource/ShaderParser.cpp
@@ -1339,6 +1339,7 @@ const kSpiral8 = array<vec2f, 8>(
vec2f(-0.2340040, 0.8704838),
vec2f(-0.4462715, -0.8592682)
);
+const kInner5 = array<vec2f, 5>(vec2f(0.0), vec2f(1.5, 0.0), vec2f(-1.5, 0.0), vec2f(0.0, 1.5), vec2f(0.0, -1.5));
const kSpiral16 = array<vec2f, 16>(
vec2f(0.1767767, 0.0000000),
vec2f(-0.2257722, 0.2068258),
@@ -1499,6 +1500,16 @@ fn shadowFactor3D(worldPos : vec3f, N : vec3f, L : vec3f, source : vec2f,
let stepPer = texel * slope;
var sum = 0.0;
var hits = 0.0;
+ // See the GLSL twin: the fragment's own texel and the four a step and a half round it, before the sparse wide disc.
+ for (var i = 0; i < 5; i++) {
+ let p = kInner5[i];
+ let off = vec2f(p.x * turn.x - p.y * turn.y, -(p.x * turn.y + p.y * turn.x));
+ let at = clamp(at0 + off * lc.u_shadowParams.y, lo, hi);
+ let d = unpackDepth(textureSampleLevel(t2, s2, at, 0.0).rgb);
+ let cr = lcp + toLight * (stepBase + max(length(off), 1.0) * stepPer);
+ let reach = clamp(cr.z / max(cr.w, 1e-6) * 0.5 + 0.5, 0.0, 1.0);
+ if (d < reach) { sum += d; hits += 1.0; }
+ }
for (var i = 0; i < 16; i++) {
let p = kSpiral16[i];
let off = kShadowDisc * vec2f(p.x * turn.x - p.y * turn.y, -(p.x * turn.y + p.y * turn.x));
@@ -1510,7 +1521,7 @@ fn shadowFactor3D(worldPos : vec3f, N : vec3f, L : vec3f, source : vec2f,
}
if (hits < 0.5) { return 1.0; }
// See the GLSL twin: a blocker on every tap is the inside of a shadow.
- if (hits > 15.5) { return 0.0; }
+ if (hits > 20.5) { return 0.0; }
// How far the receiver stands beyond what blocks it, and how far from the light
// that blocker is. A is the length of the map's depth row, and each kind of map
// inverts its own with it: hyperbolic where it has an eye, linear where w is 1.
@@ -2590,6 +2601,7 @@ ShaderParser::AssembledStage ShaderParser::assembleStageEx(const ParsedShader& p
"}\n"
"// The spiral taps for 16 and 32 points, as numbers: the cos, the sin and the root of each tap do not change from one pixel to the next, so they are\n"
"// not worked out in the pixel (a sin, a cos and a sqrt a tap, forty-eight taps). Each is turned by the pixel's own spin where it is used.\n"
+ "const highp vec2 kInner5[5] = vec2[5](vec2(0.0), vec2(1.5, 0.0), vec2(-1.5, 0.0), vec2(0.0, 1.5), vec2(0.0, -1.5));\n"
"const highp vec2 kSpiral8[8] = vec2[8](\n"
" vec2(0.2500000, 0.0000000),\n"
" vec2(-0.3192901, 0.2924959),\n"
@@ -2752,6 +2764,18 @@ ShaderParser::AssembledStage ShaderParser::assembleStageEx(const ParsedShader& p
" highp float stepPer = texel * slope;\n"
" highp float sum = 0.0;\n"
" highp float hits = 0.0;\n"
+ // The search disc is wide (kShadowDisc texels) and its sixteen taps are sparse: a caster narrower than the gap between them can stand
+ // right over this fragment and be missed. The fragment's own texel and the four a step and a half round it are asked first, so a thin
+ // or small caster is found where it is, and what they find is part of the blocker average like any other tap.
+ " for (int i = 0; i < 5; ++i) {\n"
+ " highp vec2 p = kInner5[i];\n"
+ " highp vec2 off = vec2(p.x * turn.x - p.y * turn.y, p.x * turn.y + p.y * turn.x);\n"
+ " highp vec2 at = clamp(at0 + off * u_shadowParams.y, lo, hi);\n"
+ " highp float d = unpackDepth(texture(u_shadowMap, at).rgb);\n"
+ " highp vec4 cr = lc + toLight * (stepBase + max(length(off), 1.0) * stepPer);\n"
+ " highp float reach = clamp(cr.z / max(cr.w, 1e-6) * 0.5 + 0.5, 0.0, 1.0);\n"
+ " if (d < reach) { sum += d; hits += 1.0; }\n"
+ " }\n"
" for (int i = 0; i < 16; ++i) {\n"
" highp vec2 p = kSpiral16[i];\n"
" highp vec2 off = kShadowDisc * vec2(p.x * turn.x - p.y * turn.y, p.x * turn.y + p.y * turn.x);\n"
@@ -2764,7 +2788,7 @@ ShaderParser::AssembledStage ShaderParser::assembleStageEx(const ParsedShader& p
" if (hits < 0.5) return 1.0;\n"
" // A blocker on every tap of the disc an edge can reach across is the inside of a shadow, not an edge of one: nothing in the filter below would\n"
" // find light there, and its thirty-two taps are spent on a result of zero.\n"
- " if (hits > 15.5) return 0.0;\n"
+ " if (hits > 20.5) return 0.0;\n"
// How far the receiver stands beyond what blocks it, and how far from the
// light that blocker is. A is the length of the map's depth row, and each map
diff --git a/tools/releaseNotes.mjs b/tools/releaseNotes.mjs
index 98fcf5fdd..070d9fb5d 100644
--- a/tools/releaseNotes.mjs
+++ b/tools/releaseNotes.mjs
@@ -2994,4 +2994,6 @@ export const NOTED = {
{"note":"The sea takes the sun's shadow as one hard edge."},
"perf(shadow): a sun's map leaves out the casters whose shadow cannot reach what the camera sees":
{"note":"A sun's shadow map leaves out the casters that shade nothing the camera sees."},
+ "fix(shadow): a caster narrower than the blocker search's gaps no longer vanishes from a wide shadow map":
+ {"note":"A small caster no longer drops out of a wide shadow map."},
};
diff --git a/tools/renderScenes.mjs b/tools/renderScenes.mjs
index 3b8a65a65..9ee272894 100644
--- a/tools/renderScenes.mjs
+++ b/tools/renderScenes.mjs
@@ -226,6 +226,8 @@ export const SCENES = [
// orthographic one above and a sliver near the near plane for this one.
// The caster behind the camera still shades the floor in front of it (the sun-shadow cull keeps what reaches the view); one far off to the side, whose shadow falls outside it, is left out of the map.
{ id: "mesh-shadow-cull", tier: "pr", webgpu: true, env: { ESTELLA_VERIFY_SCENE: "/scenes/mesh-shadow-cull.esscene", ESTELLA_VERIFY_W: "256", ESTELLA_VERIFY_H: "256", ESTELLA_VERIFY_STEPS: "2", ESTELLA_VERIFY_COUNTERS: "{\"render.shadow.castersCulled\": 1}", ESTELLA_VERIFY_EXPECT: "[{\"x\":0.7,\"y\":0.21,\"rgb\":[0,0,0],\"tol\":20},{\"x\":0.48,\"y\":0.21,\"rgb\":[255,255,255],\"tol\":20},{\"x\":0.7,\"y\":0.6,\"rgb\":[255,255,255],\"tol\":20}]" } },
+ // A sun whose map spans 16000 units has texels of 31: a 60-unit caster is two of them wide, and the blocker search's sparse wide disc used to step over it, so it cast nothing.
+ { id: "mesh-shadow-small", tier: "pr", webgpu: true, env: { ESTELLA_VERIFY_SCENE: "/scenes/mesh-shadow-small.esscene", ESTELLA_VERIFY_W: "256", ESTELLA_VERIFY_H: "256", ESTELLA_VERIFY_STEPS: "2", ESTELLA_VERIFY_EXPECT: "[{\"x\":0.656,\"y\":0.22,\"rgb\":[0,0,0],\"tol\":30},{\"x\":0.2,\"y\":0.5,\"rgb\":[255,255,255],\"tol\":20}]" } },
{ id: "mesh-shadow-caster-behind", tier: "pr", webgpu: true, env: { ESTELLA_VERIFY_SCENE: "/scenes/mesh-shadow-caster-behind.esscene", ESTELLA_VERIFY_W: "256", ESTELLA_VERIFY_H: "256", ESTELLA_VERIFY_STEPS: "2", ESTELLA_VERIFY_EXPECT: "[{\"x\":0.7,\"y\":0.21,\"rgb\":[0,0,0],\"tol\":20},{\"x\":0.48,\"y\":0.21,\"rgb\":[255,255,255],\"tol\":20},{\"x\":0.7,\"y\":0.6,\"rgb\":[255,255,255],\"tol\":20}]" } },
// A CONE casting, through the tile and the pass a cascade uses. The shadow is offset
// from the caster because a point light projects rather than sweeps; the probes either