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.

feat(render): a directional light's source is the sun's size by default

esenginecbc7bca0a2ca
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 81c0fe70c..e9d9d8c1d 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -29,6 +29,7 @@ published separately; it ships inside the editor.
### Changed
+- **A Directional light's source is the sun's size by default, so its shadows have a penumbra.** `sourceAngle` defaulted to 0 — a source with no size, whose shadow edge is a knife-cut however far it falls. It is now 0.53°, the real sun's: a shadow close to its caster stays crisp and one cast far softens, as it does outdoors. A light that sets 0 keeps its hard edge.
- **A paused game is no longer covered or dimmed.** The PAUSED label sat over the middle of the game and the frame was darkened, which hid exactly what a pause is for looking at. The frame's ring turns amber instead; the toolbar and the status bar say paused.
### Fixed
diff --git a/docs/astro/src/data/components.generated.json b/docs/astro/src/data/components.generated.json
index 5dc7638a7..275be20b8 100644
--- a/docs/astro/src/data/components.generated.json
+++ b/docs/astro/src/data/components.generated.json
@@ -2070,8 +2070,8 @@
{
"key": "sourceAngle",
"type": "number",
- "default": "0",
- "doc": "Angular size of a Directional light's source; 0 = hard edge (sun ~0.53).",
+ "default": "0.53",
+ "doc": "Angular size of a Directional light's source (the sun is 0.53); 0 = hard edge.",
"range": "0–90",
"advanced": true
},
diff --git a/fixtures/scenes/mesh-shadow-tilt-sun.esscene b/fixtures/scenes/mesh-shadow-tilt-sun.esscene
new file mode 100644
index 000000000..0e2d61996
--- /dev/null
+++ b/fixtures/scenes/mesh-shadow-tilt-sun.esscene
@@ -0,0 +1,155 @@
+{
+ "version": 4,
+ "name": "MeshShadowTiltSun",
+ "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/fixtures/scenes/mesh-shadow-tilt.esscene b/fixtures/scenes/mesh-shadow-tilt.esscene
index dcc3fdbb7..8959580e2 100644
--- a/fixtures/scenes/mesh-shadow-tilt.esscene
+++ b/fixtures/scenes/mesh-shadow-tilt.esscene
@@ -146,7 +146,8 @@
"x": 0.5,
"y": 0
},
- "meshShadows": true
+ "meshShadows": true,
+ "sourceAngle": 0
}
}
]
diff --git a/sdk/src/ecs/component.generated.ts b/sdk/src/ecs/component.generated.ts
index 451b5f2dd..0292e3cdb 100644
--- a/sdk/src/ecs/component.generated.ts
+++ b/sdk/src/ecs/component.generated.ts
@@ -471,7 +471,7 @@ export const COMPONENT_META: Record<string, ComponentMetaEntry> = {
innerAngle: 30,
outerAngle: 45,
shadowSoftness: 0,
- sourceAngle: 0,
+ sourceAngle: 0.53,
shadowDistance: 0,
meshShadows: false,
shadowExtent: 0,
@@ -497,7 +497,7 @@ export const COMPONENT_META: Record<string, ComponentMetaEntry> = {
innerAngle: { min: 0, max: 180, unit: "°", advanced: true, shownWhen: { field: "type", values: [3] } },
outerAngle: { min: 0, max: 180, unit: "°", advanced: true, shownWhen: { field: "type", values: [3] } },
shadowSoftness: { min: 0, tooltip: "Shadow softness (light-source size); 0 = hard edge.", shownWhen: { field: "type", values: [0, 1, 3] } },
- sourceAngle: { min: 0, max: 90, unit: "°", tooltip: "Angular size of a Directional light's source; 0 = hard edge (sun ~0.53).", advanced: true, shownWhen: { field: "type", values: [1] } },
+ sourceAngle: { min: 0, max: 90, unit: "°", tooltip: "Angular size of a Directional light's source (the sun is 0.53); 0 = hard edge.", advanced: true, shownWhen: { field: "type", values: [1] } },
shadowDistance: { min: 0, tooltip: "Directional shadow distance; 0 = no directional shadow.", advanced: true, shownWhen: { field: "type", values: [1] } },
meshShadows: { tooltip: "Cast a shadow map over 3D meshes (Directional, Spot, Point).", shownWhen: { field: "type", values: [0, 1, 3] } },
shadowExtent: { min: 0, tooltip: "Shadow map coverage radius; 0 = fit the view.", advanced: true, shownWhen: { field: "type", values: [1] } },
diff --git a/src/esengine/ecs/components/Light.hpp b/src/esengine/ecs/components/Light.hpp
index 57daf4f42..654a82c22 100644
--- a/src/esengine/ecs/components/Light.hpp
+++ b/src/esengine/ecs/components/Light.hpp
@@ -131,12 +131,12 @@ struct Light {
f32 shadowSoftness{0.0f};
/** @brief How wide a Directional light's source is, as the angle it subtends — the full
- * angular diameter in degrees, 0.53 being the real sun's. A length cannot say it:
- * the source is infinitely far away, so only an angle carries a penumbra. 0 is a
- * hard edge (default); ignored by the types that have a position and a size. */
+ * angular diameter in degrees. A length cannot say it: the source is infinitely far
+ * away, so only an angle carries a penumbra. The default is the real sun's 0.53;
+ * 0 is a hard edge. Ignored by the types that have a position and a size. */
ES_PROPERTY(animatable, min=0, max=90, unit="°", advanced, shown_when=type:Directional,
- tooltip="Angular size of a Directional light's source; 0 = hard edge (sun ~0.53).")
- f32 sourceAngle{0.0f};
+ tooltip="Angular size of a Directional light's source (the sun is 0.53); 0 = hard edge.")
+ f32 sourceAngle{0.53f};
/** @brief Directional-light shadow reach in world units: how far its shadows are carried
* from whatever cast them. 0 = a Directional light casts no 2D shadow (default).
diff --git a/tools/releaseNotes.mjs b/tools/releaseNotes.mjs
index cfd16e54f..1a99556d6 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.' },
+ 'feat(render): a directional light\'s source is the sun\'s size by default':
+ { note: 'A Directional light\'s source is the sun\'s size by default, so its shadows have a penumbra.' },
'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':
diff --git a/tools/renderScenes.mjs b/tools/renderScenes.mjs
index ebec50482..e2ae3416d 100644
--- a/tools/renderScenes.mjs
+++ b/tools/renderScenes.mjs
@@ -159,9 +159,11 @@ 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.
+ // The same shadow turned 30 degrees with a hard source, so its edges cross the map's
+ // texel grid; a filter that draws that grid into them strays by a quarter pixel.
{ 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 with the light's default source, the sun's 0.53°: a penumbra, as clean.
+ { id: "mesh-shadow-tilt-sun", tier: "pr", webgpu: true, env: { ESTELLA_VERIFY_SCENE: "/scenes/mesh-shadow-tilt-sun.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