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.
TypeScript 2d-game-engine3d3d-game-engineandroidcppecsgame-editorgame-enginegamedeviostypescriptwebassemblywebglwebgpuwechat-minigame
feat(render): a sun has a size too, and it is an angle
yhhca768ce9b82c
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex 9444fbdd5..fab6c776e 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -16,6 +16,35 @@ published separately; it ships inside the editor.### Added+- **A sun has a size too, and it is an angle.** A light with a position carries its source+ as a half-extent in world units, and the penumbra follows from dividing that by the+ distance to what blocks it. A directional light has no such distance — its source is+ infinitely far away — so a length says nothing about its shadow's edge, and its cascades+ stayed hard while every other light's softened. `Light2D::sourceAngle` is what it+ carries instead: the full angle its source subtends, in degrees, 0.53 being the real+ sun's. Every engine that does this splits it the same way, and for the same reason.++ One expression still serves both, which is the point: the penumbra is the tangent of the+ angle the source subtends AT THE BLOCKER, times how far the receiver stands beyond it.+ A map with an eye divides a half-extent by the blocker's distance to get that tangent; a+ map without one measures its own w as 1 everywhere, so what it divides is the tangent+ itself. The shader picks between them on a property of the matrix — whether its w varies+ with position — and the same line computes the radius either way.++ What it costs to know the blocker's distance is nothing new either. The map's depth row+ has length A, and each kind of map inverts its own depth with it: hyperbolic where there+ is an eye, linear where there is not.++ Gates `sun-shadow` and `sun-shadow-contact`, both backends: one scene with the caster at+ two points along the SAME sunbeam, so its shadow lands in the same place and only the+ edge differs — 9 world units of penumbra with the caster 100 above the ground, 2.4 with+ it a quarter of that. Two of the four shared probes differ by 70 and 38.++ Verified against the defect and against the neighbouring field: with `sourceAngle` zeroed+ the edge collapses to one sample step (0 → 124 → 247) and both differing probes go red,+ and with `shadowSoftness` set to 200 on the same sun the frame does not move by a single+ value — a length is not what a sun's map reads.+- **A shadow map's edge is as soft as the light source is big.** `shadowSoftness` — thelight's half-extent in world units — reached only the 2D occluder path, which samplesfive points across the source and counts what each of them can see. A mesh shadow mapdiff --git a/desktop/public/scenes/sun-shadow-contact.esscene b/desktop/public/scenes/sun-shadow-contact.esscenenew file mode 100644index 000000000..abc9f2085--- /dev/null+++ b/desktop/public/scenes/sun-shadow-contact.esscene@@ -0,0 +1,34 @@+{+ "version": 1,+ "name": "SunShadowContact",+ "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": 40, "isActive": true, "priority": 0 } }+ ]+ },+ {+ "id": 1, "name": "Ground", "parent": null, "children": [], "visible": true,+ "components": [+ { "type": "Transform", "data": { "position": { "x": 0, "y": 0, "z": -100 }, "scale": { "x": 1000, "y": 1000, "z": 1 } } },+ { "type": "Mesh2D", "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": -1.25, "y": 0, "z": -75 }, "scale": { "x": 20, "y": 20, "z": 1 } } },+ { "type": "Mesh2D", "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": "Light2D", "data": { "type": 1, "color": { "r": 1, "g": 1, "b": 1, "a": 1 }, "intensity": 1, "direction": { "x": 0.25, "y": 0 }, "meshShadows": true, "shadowExtent": 500, "sourceAngle": 5.6 } }+ ]+ }+ ]+}diff --git a/desktop/public/scenes/sun-shadow.esscene b/desktop/public/scenes/sun-shadow.esscenenew file mode 100644index 000000000..12a7dae8b--- /dev/null+++ b/desktop/public/scenes/sun-shadow.esscene@@ -0,0 +1,34 @@+{+ "version": 1,+ "name": "SunShadow",+ "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": 40, "isActive": true, "priority": 0 } }+ ]+ },+ {+ "id": 1, "name": "Ground", "parent": null, "children": [], "visible": true,+ "components": [+ { "type": "Transform", "data": { "position": { "x": 0, "y": 0, "z": -100 }, "scale": { "x": 1000, "y": 1000, "z": 1 } } },+ { "type": "Mesh2D", "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": -20, "y": 0, "z": 0 }, "scale": { "x": 20, "y": 20, "z": 1 } } },+ { "type": "Mesh2D", "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": "Light2D", "data": { "type": 1, "color": { "r": 1, "g": 1, "b": 1, "a": 1 }, "intensity": 1, "direction": { "x": 0.25, "y": 0 }, "meshShadows": true, "shadowExtent": 500, "sourceAngle": 5.6 } }+ ]+ }+ ]+}diff --git a/docs/astro/src/data/components.generated.json b/docs/astro/src/data/components.generated.jsonindex 64d6fa05f..c014e66f5 100644--- a/docs/astro/src/data/components.generated.json+++ b/docs/astro/src/data/components.generated.json@@ -1592,6 +1592,14 @@"doc": "Shadow softness (light-source size); 0 = hard edge.","range": "≥ 0"},+ {+ "key": "sourceAngle",+ "type": "number",+ "default": "0",+ "doc": "Angular size of a Directional light's source; 0 = hard edge (sun ~0.53).",+ "range": "0–90",+ "advanced": true+ },{"key": "shadowDistance","type": "number",@@ -1642,6 +1650,7 @@"innerAngle","outerAngle","shadowSoftness",+ "sourceAngle","shadowDistance"]},diff --git a/sdk/etc/index.api.md b/sdk/etc/index.api.mdindex c23c4b8ba..2e55b6b5f 100644--- a/sdk/etc/index.api.md+++ b/sdk/etc/index.api.md@@ -5,7 +5,7 @@ Symbols: 113 public · 66 beta · 1481 experimental · 3 deprecated## ABI_LAYOUT_HASH — const @experimental```-"e868cc33a27b61d4"+"4f073fe384c59476"```## ANCHOR_AXES — const @experimental@@ -4020,6 +4020,7 @@ radius: numbershadowDistance: numbershadowExtent: numbershadowSoftness: number+sourceAngle: numbertype: number```diff --git a/sdk/etc/index.native.api.md b/sdk/etc/index.native.api.mdindex 14d72068e..688f0ce50 100644--- a/sdk/etc/index.native.api.md+++ b/sdk/etc/index.native.api.md@@ -5,7 +5,7 @@ Symbols: 113 public · 71 beta · 1500 experimental · 3 deprecated## ABI_LAYOUT_HASH — const @experimental```-"e868cc33a27b61d4"+"4f073fe384c59476"```## ANCHOR_AXES — const @experimental@@ -4028,6 +4028,7 @@ radius: numbershadowDistance: numbershadowExtent: numbershadowSoftness: number+sourceAngle: numbertype: number```diff --git a/sdk/etc/index.node.api.md b/sdk/etc/index.node.api.mdindex 043956bd3..eba1dfdad 100644--- a/sdk/etc/index.node.api.md+++ b/sdk/etc/index.node.api.md@@ -4015,6 +4015,7 @@ radius: numbershadowDistance: numbershadowExtent: numbershadowSoftness: number+sourceAngle: numbertype: number```diff --git a/sdk/etc/minigame.api.md b/sdk/etc/minigame.api.mdindex 2c17dfa23..507d308ae 100644--- a/sdk/etc/minigame.api.md+++ b/sdk/etc/minigame.api.md@@ -4015,6 +4015,7 @@ radius: numbershadowDistance: numbershadowExtent: numbershadowSoftness: number+sourceAngle: numbertype: number```diff --git a/sdk/etc/wechat.api.md b/sdk/etc/wechat.api.mdindex b3a9b4da9..74d536477 100644--- a/sdk/etc/wechat.api.md+++ b/sdk/etc/wechat.api.md@@ -4022,6 +4022,7 @@ radius: numbershadowDistance: numbershadowExtent: numbershadowSoftness: number+sourceAngle: numbertype: number```diff --git a/sdk/src/ecs/bridge/ptrAccessors.generated.ts b/sdk/src/ecs/bridge/ptrAccessors.generated.tsindex e00559db4..424009502 100644--- a/sdk/src/ecs/bridge/ptrAccessors.generated.ts+++ b/sdk/src/ecs/bridge/ptrAccessors.generated.ts@@ -693,6 +693,7 @@ export interface Light2DPtrData {innerAngle: number;outerAngle: number;shadowSoftness: number;+ sourceAngle: number;shadowDistance: number;meshShadows: boolean;shadowExtent: number;@@ -712,12 +713,13 @@ export function fillLight2D(out.innerAngle = f32[(ptr + 28) >> 2];out.outerAngle = f32[(ptr + 32) >> 2];out.shadowSoftness = f32[(ptr + 36) >> 2];- out.shadowDistance = f32[(ptr + 40) >> 2];- out.meshShadows = u8[ptr + 44] !== 0;- out.shadowExtent = f32[(ptr + 48) >> 2];- out.environment = u32[(ptr + 52) >> 2];- out.drawEnvironment = u8[ptr + 56] !== 0;- out.enabled = u8[ptr + 57] !== 0;+ out.sourceAngle = f32[(ptr + 40) >> 2];+ out.shadowDistance = f32[(ptr + 44) >> 2];+ out.meshShadows = u8[ptr + 48] !== 0;+ out.shadowExtent = f32[(ptr + 52) >> 2];+ out.environment = u32[(ptr + 56) >> 2];+ out.drawEnvironment = u8[ptr + 60] !== 0;+ out.enabled = u8[ptr + 61] !== 0;}export function writeLight2D(@@ -731,12 +733,13 @@ export function writeLight2D(f32[(ptr + 28) >> 2] = data.innerAngle;f32[(ptr + 32) >> 2] = data.outerAngle;f32[(ptr + 36) >> 2] = data.shadowSoftness;- f32[(ptr + 40) >> 2] = data.shadowDistance;- u8[ptr + 44] = data.meshShadows ? 1 : 0;- f32[(ptr + 48) >> 2] = data.shadowExtent;- u32[(ptr + 52) >> 2] = data.environment;- u8[ptr + 56] = data.drawEnvironment ? 1 : 0;- u8[ptr + 57] = data.enabled ? 1 : 0;+ f32[(ptr + 40) >> 2] = data.sourceAngle;+ f32[(ptr + 44) >> 2] = data.shadowDistance;+ u8[ptr + 48] = data.meshShadows ? 1 : 0;+ f32[(ptr + 52) >> 2] = data.shadowExtent;+ u32[(ptr + 56) >> 2] = data.environment;+ u8[ptr + 60] = data.drawEnvironment ? 1 : 0;+ u8[ptr + 61] = data.enabled ? 1 : 0;}export function createLight2DData(): Light2DPtrData {@@ -748,6 +751,7 @@ export function createLight2DData(): Light2DPtrData {innerAngle: 0,outerAngle: 0,shadowSoftness: 0,+ sourceAngle: 0,shadowDistance: 0,meshShadows: false,shadowExtent: 0,diff --git a/sdk/src/ecs/component.generated.ts b/sdk/src/ecs/component.generated.tsindex 750c5083e..9389de579 100644--- a/sdk/src/ecs/component.generated.ts+++ b/sdk/src/ecs/component.generated.ts@@ -15,7 +15,7 @@ import type { Dimension, Padding } from '../wasm/wasm.generated';* getAbiLayoutHash(); BuiltinBridge.connect() compares them and refuses to* run on mismatch, because mismatched offsets read the wrong heap bytes.*/-export const ABI_LAYOUT_HASH = 'e868cc33a27b61d4';+export const ABI_LAYOUT_HASH = '4f073fe384c59476';/*** One asset-valued field of a component: which field, and what kind of@@ -395,6 +395,7 @@ export const COMPONENT_META: Record<string, ComponentMetaEntry> = {innerAngle: 30,outerAngle: 45,shadowSoftness: 0,+ sourceAngle: 0,shadowDistance: 0,meshShadows: false,shadowExtent: 0,@@ -406,7 +407,7 @@ export const COMPONENT_META: Record<string, ComponentMetaEntry> = {assetFields: [{ field: 'environment', type: 'environment' as AssetFieldType }],entityFields: [],colorFields: ['color'],- animatableFields: ['color.r', 'color.g', 'color.b', 'color.a', 'intensity', 'radius', 'innerAngle', 'outerAngle', 'shadowSoftness', 'shadowDistance'],+ animatableFields: ['color.r', 'color.g', 'color.b', 'color.a', 'intensity', 'radius', 'innerAngle', 'outerAngle', 'shadowSoftness', 'sourceAngle', 'shadowDistance'],fields: {type: { enum: [{ label: 'Point', value: 0 }, { label: 'Directional', value: 1 }, { label: 'Ambient', value: 2 }, { label: 'Spot', value: 3 }], tooltip: "Point, Directional, Ambient, or Spot." },intensity: { min: 0, tooltip: "Brightness multiplier of the light." },@@ -414,6 +415,7 @@ export const COMPONENT_META: Record<string, ComponentMetaEntry> = {innerAngle: { min: 0, max: 180, unit: "°", advanced: true },outerAngle: { min: 0, max: 180, unit: "°", advanced: true },shadowSoftness: { min: 0, tooltip: "Shadow softness (light-source size); 0 = hard edge." },+ sourceAngle: { min: 0, max: 90, unit: "°", tooltip: "Angular size of a Directional light's source; 0 = hard edge (sun ~0.53).", advanced: true },shadowDistance: { min: 0, tooltip: "Directional shadow distance; 0 = no directional shadow.", advanced: true },meshShadows: { tooltip: "Cast a shadow map over 3D meshes (Directional, Spot, Point)." },shadowExtent: { min: 0, tooltip: "Shadow map coverage radius; 0 = fit the view.", advanced: true },@@ -1205,6 +1207,7 @@ export interface Light2DData {innerAngle: number;outerAngle: number;shadowSoftness: number;+ sourceAngle: number;shadowDistance: number;meshShadows: boolean;shadowExtent: number;diff --git a/sdk/src/wasm/ptrLayouts.generated.ts b/sdk/src/wasm/ptrLayouts.generated.tsindex 5959d5716..978ec47ca 100644--- a/sdk/src/wasm/ptrLayouts.generated.ts+++ b/sdk/src/wasm/ptrLayouts.generated.ts@@ -206,12 +206,13 @@ export const PTR_LAYOUTS: Record<string, PtrLayout> = {{ name: 'innerAngle', type: 'f32', offset: 28 },{ name: 'outerAngle', type: 'f32', offset: 32 },{ name: 'shadowSoftness', type: 'f32', offset: 36 },- { name: 'shadowDistance', type: 'f32', offset: 40 },- { name: 'meshShadows', type: 'bool', offset: 44 },- { name: 'shadowExtent', type: 'f32', offset: 48 },- { name: 'environment', type: 'u32', offset: 52 },- { name: 'drawEnvironment', type: 'bool', offset: 56 },- { name: 'enabled', type: 'bool', offset: 57 },+ { name: 'sourceAngle', type: 'f32', offset: 40 },+ { name: 'shadowDistance', type: 'f32', offset: 44 },+ { name: 'meshShadows', type: 'bool', offset: 48 },+ { name: 'shadowExtent', type: 'f32', offset: 52 },+ { name: 'environment', type: 'u32', offset: 56 },+ { name: 'drawEnvironment', type: 'bool', offset: 60 },+ { name: 'enabled', type: 'bool', offset: 61 },],},Mesh2D: {diff --git a/sdk/src/wasm/wasm.generated.ts b/sdk/src/wasm/wasm.generated.tsindex c1979c0fb..df349910d 100644--- a/sdk/src/wasm/wasm.generated.ts+++ b/sdk/src/wasm/wasm.generated.ts@@ -378,6 +378,7 @@ export interface Light2D {innerAngle: number;outerAngle: number;shadowSoftness: number;+ sourceAngle: number;shadowDistance: number;meshShadows: boolean;shadowExtent: number;diff --git a/src/esengine/bindings/EditorAPI.generated.cpp b/src/esengine/bindings/EditorAPI.generated.cppindex cc265f43e..e0236bbd2 100644--- a/src/esengine/bindings/EditorAPI.generated.cpp+++ b/src/esengine/bindings/EditorAPI.generated.cpp@@ -2,10 +2,10 @@* @file EditorAPI.generated.cpp* @brief Auto-generated editor API with string-dispatched component access* @details Generated by EHT - DO NOT EDIT- * @schema_hash 4fbe43821df1cf73+ * @schema_hash 03aa2865f562634e*/-#define ES_EDITOR_API_SCHEMA_HASH "4fbe43821df1cf73"+#define ES_EDITOR_API_SCHEMA_HASH "03aa2865f562634e"#include <emscripten/bind.h>#include <string>@@ -296,6 +296,7 @@ std::string editor_getComponentSchema(const std::string& name) {{"key":"innerAngle","type":"float","group":"Light2D"},{"key":"outerAngle","type":"float","group":"Light2D"},{"key":"shadowSoftness","type":"float","group":"Light2D"},+ {"key":"sourceAngle","type":"float","group":"Light2D"},{"key":"shadowDistance","type":"float","group":"Light2D"},{"key":"meshShadows","type":"bool","group":"Light2D"},{"key":"shadowExtent","type":"float","group":"Light2D"},@@ -1144,6 +1145,7 @@ bool editor_setFloat(Registry& reg, u32 e, const std::string& comp, const std::selse if (field == "innerAngle") { c.innerAngle = value; }else if (field == "outerAngle") { c.outerAngle = value; }else if (field == "shadowSoftness") { c.shadowSoftness = value; }+ else if (field == "sourceAngle") { c.sourceAngle = value; }else if (field == "shadowDistance") { c.shadowDistance = value; }else if (field == "shadowExtent") { c.shadowExtent = value; }else { return false; }@@ -1597,6 +1599,7 @@ f32 editor_getFloat(Registry& reg, u32 e, const std::string& comp, const std::stelse if (field == "innerAngle") { return c.innerAngle; }else if (field == "outerAngle") { return c.outerAngle; }else if (field == "shadowSoftness") { return c.shadowSoftness; }+ else if (field == "sourceAngle") { return c.sourceAngle; }else if (field == "shadowDistance") { return c.shadowDistance; }else if (field == "shadowExtent") { return c.shadowExtent; }} else if (comp == "Mesh2D") {diff --git a/src/esengine/bindings/WebBindings.generated.cpp b/src/esengine/bindings/WebBindings.generated.cppindex 11aded93e..6cd61e04b 100644--- a/src/esengine/bindings/WebBindings.generated.cpp+++ b/src/esengine/bindings/WebBindings.generated.cpp@@ -479,6 +479,7 @@ struct Light2DJS {f32 innerAngle;f32 outerAngle;f32 shadowSoftness;+ f32 sourceAngle;f32 shadowDistance;bool meshShadows;f32 shadowExtent;@@ -495,6 +496,7 @@ void light2dApplyJS(esengine::ecs::Light2D& c, const Light2DJS& js) {c.innerAngle = js.innerAngle;c.outerAngle = js.outerAngle;c.shadowSoftness = js.shadowSoftness;+ c.sourceAngle = js.sourceAngle;c.shadowDistance = js.shadowDistance;c.meshShadows = js.meshShadows;c.shadowExtent = js.shadowExtent;@@ -518,6 +520,7 @@ Light2DJS light2dToJS(const esengine::ecs::Light2D& c) {js.innerAngle = c.innerAngle;js.outerAngle = c.outerAngle;js.shadowSoftness = c.shadowSoftness;+ js.sourceAngle = c.sourceAngle;js.shadowDistance = c.shadowDistance;js.meshShadows = c.meshShadows;js.shadowExtent = c.shadowExtent;@@ -1437,6 +1440,7 @@ EMSCRIPTEN_BINDINGS(esengine_components) {.field("innerAngle", &Light2DJS::innerAngle).field("outerAngle", &Light2DJS::outerAngle).field("shadowSoftness", &Light2DJS::shadowSoftness)+ .field("sourceAngle", &Light2DJS::sourceAngle).field("shadowDistance", &Light2DJS::shadowDistance).field("meshShadows", &Light2DJS::meshShadows).field("shadowExtent", &Light2DJS::shadowExtent)@@ -2781,12 +2785,13 @@ static_assert(offsetof(esengine::ecs::Light2D, radius) == 24, "ABI offset drift:static_assert(offsetof(esengine::ecs::Light2D, innerAngle) == 28, "ABI offset drift: esengine::ecs::Light2D.innerAngle (EHT expected 28)");static_assert(offsetof(esengine::ecs::Light2D, outerAngle) == 32, "ABI offset drift: esengine::ecs::Light2D.outerAngle (EHT expected 32)");static_assert(offsetof(esengine::ecs::Light2D, shadowSoftness) == 36, "ABI offset drift: esengine::ecs::Light2D.shadowSoftness (EHT expected 36)");-static_assert(offsetof(esengine::ecs::Light2D, shadowDistance) == 40, "ABI offset drift: esengine::ecs::Light2D.shadowDistance (EHT expected 40)");-static_assert(offsetof(esengine::ecs::Light2D, meshShadows) == 44, "ABI offset drift: esengine::ecs::Light2D.meshShadows (EHT expected 44)");-static_assert(offsetof(esengine::ecs::Light2D, shadowExtent) == 48, "ABI offset drift: esengine::ecs::Light2D.shadowExtent (EHT expected 48)");-static_assert(offsetof(esengine::ecs::Light2D, environment) == 52, "ABI offset drift: esengine::ecs::Light2D.environment (EHT expected 52)");-static_assert(offsetof(esengine::ecs::Light2D, drawEnvironment) == 56, "ABI offset drift: esengine::ecs::Light2D.drawEnvironment (EHT expected 56)");-static_assert(offsetof(esengine::ecs::Light2D, enabled) == 57, "ABI offset drift: esengine::ecs::Light2D.enabled (EHT expected 57)");+static_assert(offsetof(esengine::ecs::Light2D, sourceAngle) == 40, "ABI offset drift: esengine::ecs::Light2D.sourceAngle (EHT expected 40)");+static_assert(offsetof(esengine::ecs::Light2D, shadowDistance) == 44, "ABI offset drift: esengine::ecs::Light2D.shadowDistance (EHT expected 44)");+static_assert(offsetof(esengine::ecs::Light2D, meshShadows) == 48, "ABI offset drift: esengine::ecs::Light2D.meshShadows (EHT expected 48)");+static_assert(offsetof(esengine::ecs::Light2D, shadowExtent) == 52, "ABI offset drift: esengine::ecs::Light2D.shadowExtent (EHT expected 52)");+static_assert(offsetof(esengine::ecs::Light2D, environment) == 56, "ABI offset drift: esengine::ecs::Light2D.environment (EHT expected 56)");+static_assert(offsetof(esengine::ecs::Light2D, drawEnvironment) == 60, "ABI offset drift: esengine::ecs::Light2D.drawEnvironment (EHT expected 60)");+static_assert(offsetof(esengine::ecs::Light2D, enabled) == 61, "ABI offset drift: esengine::ecs::Light2D.enabled (EHT expected 61)");static_assert(offsetof(esengine::ecs::Mesh2D, texture) == 0, "ABI offset drift: esengine::ecs::Mesh2D.texture (EHT expected 0)");static_assert(offsetof(esengine::ecs::Mesh2D, normalMap) == 4, "ABI offset drift: esengine::ecs::Mesh2D.normalMap (EHT expected 4)");static_assert(offsetof(esengine::ecs::Mesh2D, color) == 8, "ABI offset drift: esengine::ecs::Mesh2D.color (EHT expected 8)");@@ -3019,7 +3024,7 @@ static_assert(offsetof(esengine::ecs::Velocity, angular) == 12, "ABI offset drif// ABI Hash -- runtime handshake against the SDK bundle// =============================================================================-static const char* kEsAbiLayoutHash = "e868cc33a27b61d4";+static const char* kEsAbiLayoutHash = "4f073fe384c59476";std::string esengineGetAbiLayoutHash() {return std::string(kEsAbiLayoutHash);diff --git a/src/esengine/ecs/components/Light2D.hpp b/src/esengine/ecs/components/Light2D.hppindex 88a4b4370..f184e9ffd 100644--- a/src/esengine/ecs/components/Light2D.hpp+++ b/src/esengine/ecs/components/Light2D.hpp@@ -85,6 +85,14 @@ struct Light2D {ES_PROPERTY(animatable, min=0, tooltip="Shadow softness (light-source size); 0 = hard edge.")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. */+ ES_PROPERTY(animatable, min=0, max=90, unit="°", advanced,+ tooltip="Angular size of a Directional light's source; 0 = hard edge (sun ~0.53).")+ f32 sourceAngle{0.0f};+/** @brief Directional-light shadow reach in world units: how far back toward the light a* fragment searches for an occluder. 0 = a Directional light casts no shadow (default).* Ignored by Point/Spot, which shadow along the segment to the light position. */diff --git a/src/esengine/renderer/frame/RenderFrame.cpp b/src/esengine/renderer/frame/RenderFrame.cppindex 6f805a928..e5f910896 100644--- a/src/esengine/renderer/frame/RenderFrame.cpp+++ b/src/esengine/renderer/frame/RenderFrame.cpp@@ -720,6 +720,11 @@ void RenderFrame::collectLights(ecs::Registry& registry) {// that slot on their falloff radius.const glm::vec3 aim = lightForward(registry.tryGet<ecs::Transform>(entity));gpu.posDir = glm::vec4(aim.x, aim.y, 1.0f, aim.z);+ // A source infinitely far away has no half-extent a map can divide by a+ // distance, so what it carries is the angle it subtends — as its tangent,+ // which is what the penumbra is made of either way.+ gpu.shadowMap.z = std::tan(glm::radians(+ std::clamp(light.sourceAngle, 0.0f, 179.0f) * 0.5f));// One sun: a second set of cascades would claim the atlas a first one is// already spending, and two suns is not a scene anybody authors.if (light.meshShadows && !haveSun) {diff --git a/src/esengine/renderer/store/LightConstants.hpp b/src/esengine/renderer/store/LightConstants.hppindex 85721281c..d1ca48c94 100644--- a/src/esengine/renderer/store/LightConstants.hpp+++ b/src/esengine/renderer/store/LightConstants.hpp@@ -98,8 +98,11 @@ struct GpuLight2D {glm::vec4 color{0.0f};glm::vec4 spot{0.0f};glm::vec4 shadow{0.0f};- /// x = this light's first tile in the shadow atlas, y = how many it owns; zw unused.+ /// x = this light's first tile in the shadow atlas, y = how many it owns; w unused./// y = 0 is a light with no map, which is every light that did not ask for one.+ /// z = how wide its source is where its own map cannot measure a distance to divide+ /// by: the tangent of the angle it subtends, which is what a directional light has+ /// instead of a half-extent. Zero for a light that stands somewhere.glm::vec4 shadowMap{0.0f};};diff --git a/src/esengine/renderer/store/LightStore.hpp b/src/esengine/renderer/store/LightStore.hppindex b5719674a..1ce4e5bf5 100644--- a/src/esengine/renderer/store/LightStore.hpp+++ b/src/esengine/renderer/store/LightStore.hpp@@ -87,8 +87,10 @@ public:/// the zeroed count, which is a light with no map.void setLightShadowTiles(u32 slot, u32 first, u32 tiles) {if (slot >= count_) return;- data_.lights[slot].shadowMap = glm::vec4(static_cast<f32>(first),- static_cast<f32>(tiles), 0.0f, 0.0f);+ // The two the atlas decides, and nothing else: z is the light's own source size,+ // written when it was collected and not this pass's to overwrite.+ data_.lights[slot].shadowMap.x = static_cast<f32>(first);+ data_.lights[slot].shadowMap.y = static_cast<f32>(tiles);dirty_ = true;}diff --git a/src/esengine/resource/ShaderParser.cpp b/src/esengine/resource/ShaderParser.cppindex 2c0677d7b..118a5fe70 100644--- a/src/esengine/resource/ShaderParser.cpp+++ b/src/esengine/resource/ShaderParser.cpp@@ -771,9 +771,16 @@ fn diskTap(i : i32, n : i32, radius : f32) -> vec2f {// A spiral, not a table: the golden angle spreads any number of taps evenly over a// disc, so the pattern follows the count instead of being pasted in beside it.let a = f32(i) * 2.3999632;- return radius * sqrt((f32(i) + 0.5) / f32(n)) * vec2f(cos(a), sin(a));+ // Turned over in v for the reason the tile's rect is: an offset in texture space+ // follows the axis the texture is sampled along, and this backend's runs the other+ // way. A spiral is not its own mirror, so without this the two average other points.+ return radius * sqrt((f32(i) + 0.5) / f32(n)) * vec2f(cos(a), -sin(a));}-fn shadowFactor3D(worldPos : vec3f, N : vec3f, L : vec3f, softness : f32,+// The widest disc the tap count below can average over: past it the samples sit further+// apart than the texels they average, and a penumbra bands instead of blurring. It bounds+// the search too — a blocker outside it cannot widen an edge that cannot be drawn wider.+const kShadowDisc = 8.0;+fn shadowFactor3D(worldPos : vec3f, N : vec3f, L : vec3f, source : vec2f,first : i32, count : i32) -> f32 {#ifndef ES_RECEIVE_SHADOWreturn 1.0;@@ -820,10 +827,13 @@ fn shadowFactor3D(worldPos : vec3f, N : vec3f, L : vec3f, softness : f32,let at0 = base + vec2f(uv.x, 1.0 - uv.y) * rect.z;let lo = base + lc.u_shadowParams.y * 0.5;let hi = base + rect.z - lc.u_shadowParams.y * 0.5;- // A source with no size — or a map whose w does not vary with position, which is- // a map with no eye and so no distance to measure a source against — throws one- // edge, and four taps are its whole cost.- if (softness <= 0.0 || length(vec3f(m[0].w, m[1].w, m[2].w)) < 0.5) {+ // How wide the source is in the unit this map measures depth in: world units+ // where its w varies with position, so it has an eye to measure them from, and+ // 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.+ if (src <= 0.0) {var lit = 0.0;for (var y = 0; y < 2; y++) {for (var x = 0; x < 2; x++) {@@ -833,31 +843,33 @@ fn shadowFactor3D(worldPos : vec3f, N : vec3f, L : vec3f, softness : f32,}return lit * 0.25;}- // What blocks this fragment. The search is the source's own half-extent in- // texels, capped: the tap count is fixed, so a wider disc than this samples too- // sparsely to average.- let searchR = clamp(softness / texel, 1.0, 8.0);- // Against a depth that forgives the reach, not the texel: a tap r texels away- // lands r texels along the surface too, and comparing it to a one-texel bias- // counts the receiver's own slope as the thing shadowing it.- let reach = shadowDepth(m, worldPos + L * stepFor(texel, slope, searchR));+ // 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+ // texels along the surface and a one-texel bias would call the slope a blocker.+ let reach = shadowDepth(m, worldPos + L * stepFor(texel, slope, kShadowDisc));var sum = 0.0;var hits = 0.0;for (var i = 0; i < 8; i++) {- let at = clamp(at0 + diskTap(i, 8, searchR) * lc.u_shadowParams.y, lo, hi);+ let at = clamp(at0 + diskTap(i, 8, kShadowDisc) * lc.u_shadowParams.y, lo, hi);let d = unpackDepth(textureSampleLevel(t2, s2, at, 0.0).rgb);if (d < reach) { sum += d; hits += 1.0; }}if (hits < 0.5) { return 1.0; }- // How far from the light that blocker stands, out of the map's own depth: this- // projection writes z = A - A*near/d, and A is the length of its depth row, so- // one stored depth and this fragment's own distance inverts the other exactly.+ // 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.let A = length(vec3f(m[0].z, m[1].z, m[2].z));- let db = lcp.w * (A - proj.z) / max(A - (2.0 * (sum / hits) - 1.0), 1e-6);- // A source of half-extent `softness` at db throws this much penumbra across a- // receiver at lcp.w — which is why a shadow hardens as its caster nears the- // surface, and why one number governs both.- let radius = clamp(softness * (lcp.w - db) / max(db * texel, 1e-4), 0.5, 8.0);+ let zb = 2.0 * (sum / hits) - 1.0;+ var dbw = 1.0;+ var span = (proj.z - zb) / max(A, 1e-9);+ if (hasEye) {+ dbw = lcp.w * (A - proj.z) / max(A - zb, 1e-6);+ span = lcp.w - dbw;+ }+ // A source subtending src/dbw at the blocker throws that much penumbra across the+ // span beyond it — which is why a shadow hardens as its caster nears what it+ // falls on, and why a sun's angle and a lamp's size are the same expression.+ let radius = clamp(src * span / max(dbw * texel, 1e-4), 0.5, kShadowDisc);let wide = shadowDepth(m, worldPos + L * stepFor(texel, slope, radius));// Thirty-two, where the hard edge needs four: the disc is as wide as the source// makes it, and a penumbra averaged over too few taps bands instead of blurring.@@ -1072,7 +1084,7 @@ fn applyLightingPBR(albedo : vec3f, N : vec3f, worldPos : vec3f, V : vec3f, meta}let sm = lc.u_lights[i].shadowMap;if (sm.y > 0.0 && atten > 0.0) {- atten *= shadowFactor3D(worldPos, N, L, sh.x, i32(sm.x), i32(sm.y));+ atten *= shadowFactor3D(worldPos, N, L, vec2f(sh.x, sm.z), i32(sm.x), i32(sm.y));}let ndotl = max(dot(N, L), 0.0);let radiance = col.rgb * (col.a * ndotl * atten);@@ -1440,6 +1452,10 @@ ShaderParser::AssembledStage ShaderParser::assembleStageEx(const ParsedShader& p" return 1.0;\n""#endif\n""}\n"+ // The widest disc the tap count below can average over: past it the samples+ // sit further apart than the texels they average, and a penumbra bands rather+ // than blurs. It bounds the search too, which can find no wider an edge.+ "const highp float kShadowDisc = 8.0;\n"// A spiral, not a table: the golden angle spreads any number of taps evenly// over a disc, so the pattern follows the count instead of sitting beside it."highp vec2 diskTap(in int i, in int n, in highp float radius) {\n"@@ -1450,7 +1466,7 @@ ShaderParser::AssembledStage ShaderParser::assembleStageEx(const ParsedShader& p// written and compared through the SAME matrix and expression, so the two// backends' clip-z conventions cancel. 2x2 taps: one is a staircase."highp float shadowFactor3D(in highp vec3 worldPos, in highp vec3 N, in highp vec3 L,\n"- " in highp float softness, in int first, in int count) {\n"+ " in highp vec2 source, in int first, in int count) {\n""#ifndef ES_RECEIVE_SHADOW\n"" return 1.0;\n""#else\n"@@ -1494,11 +1510,13 @@ ShaderParser::AssembledStage ShaderParser::assembleStageEx(const ParsedShader& p" highp vec2 at0 = rect.xy + uv * rect.z;\n"" highp vec2 lo = rect.xy + u_shadowParams.y * 0.5;\n"" highp vec2 hi = rect.xy + rect.z - u_shadowParams.y * 0.5;\n"- // A source with no size — or a map whose w does not vary with position, which- // is a map with no eye and so no distance to measure a source against —- // throws one edge, and four taps are its whole cost.- " if (softness <= 0.0\n"- " || length(vec3(m[0][3], m[1][3], m[2][3])) < 0.5) {\n"+ // How wide the source is in the unit this map measures depth in: world units+ // where its w varies with position, so it has an eye to measure them from, and+ // 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.+ " if (src <= 0.0) {\n"" highp float lit = 0.0;\n"" for (int y = 0; y < 2; ++y) {\n"" for (int x = 0; x < 2; ++x) {\n"@@ -1508,33 +1526,34 @@ ShaderParser::AssembledStage ShaderParser::assembleStageEx(const ParsedShader& p" }\n"" return lit * 0.25;\n"" }\n"- // What blocks this fragment. The search is the source's own half-extent in- // texels, capped: the tap count is fixed, so a wider disc than this samples- // too sparsely to average.- " highp float searchR = clamp(softness / texel, 1.0, 8.0);\n"- // Against a depth that forgives the reach, not the texel: a tap r texels away- // lands r texels along the surface too, and comparing it to a one-texel bias- // counts the receiver's own slope as the thing shadowing it.- " highp float reach = shadowDepth(m, worldPos + L * stepFor(texel, slope, searchR));\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+ // texels along the surface and a one-texel bias would call the slope one.+ " highp float reach = shadowDepth(m, worldPos + L * stepFor(texel, slope, kShadowDisc));\n"" highp float sum = 0.0;\n"" highp float hits = 0.0;\n"" for (int i = 0; i < 8; ++i) {\n"- " highp vec2 at = clamp(at0 + diskTap(i, 8, searchR) * u_shadowParams.y, lo, hi);\n"+ " highp vec2 at = clamp(at0 + diskTap(i, 8, kShadowDisc) * u_shadowParams.y, lo, hi);\n"" highp float d = unpackDepth(texture(u_shadowMap, at).rgb);\n"" if (d < reach) { sum += d; hits += 1.0; }\n"" }\n"" if (hits < 0.5) return 1.0;\n"- // How far from the light that blocker stands, out of the map's own depth:- // this projection writes z = A - A*near/d, and A is the length of its depth- // row, so one stored depth and this fragment's distance invert the other.+ // 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+ // inverts its own with it: hyperbolic where it has an eye, linear where w is 1." highp float A = length(vec3(m[0][2], m[1][2], m[2][2]));\n"- " highp float db = lc.w * (A - proj.z)\n"- " / max(A - (2.0 * (sum / hits) - 1.0), 1e-6);\n"- // A source of half-extent `softness` at db throws this much penumbra across a- // receiver at lc.w — which is why a shadow hardens as its caster nears the- // surface, and why one number governs both.- " highp float radius = clamp(softness * (lc.w - db) / max(db * texel, 1e-4),\n"- " 0.5, 8.0);\n"+ " highp float zb = 2.0 * (sum / hits) - 1.0;\n"+ " highp float dbw = 1.0;\n"+ " highp float span = (proj.z - zb) / max(A, 1e-9);\n"+ " if (hasEye) {\n"+ " dbw = lc.w * (A - proj.z) / max(A - zb, 1e-6);\n"+ " span = lc.w - dbw;\n"+ " }\n"+ // A source subtending src/dbw at the blocker throws that much penumbra across+ // the span beyond it — which is why a shadow hardens as its caster nears what+ // it falls on, and why a sun's angle and a lamp's size are one expression.+ " highp float radius = clamp(src * span / max(dbw * texel, 1e-4),\n"+ " 0.5, kShadowDisc);\n"" highp float wide = shadowDepth(m, worldPos + L * stepFor(texel, slope, radius));\n"// Thirty-two, where the hard edge needs four: the disc is as wide as the// source makes it, and a penumbra averaged over too few taps bands rather@@ -1807,7 +1826,8 @@ ShaderParser::AssembledStage ShaderParser::assembleStageEx(const ParsedShader& p// seen from somewhere no light reaching it is standing." highp vec4 sm = u_lights[i].shadowMap;\n"" if (sm.y > 0.0 && atten > 0.0) {\n"- " atten *= shadowFactor3D(worldPos, N, L, sh.x, int(sm.x), int(sm.y));\n"+ " atten *= shadowFactor3D(worldPos, N, L, vec2(sh.x, sm.z),\n"+ " int(sm.x), int(sm.y));\n"" }\n"" highp float ndotl = max(dot(N, L), 0.0);\n"" highp vec3 radiance = col.rgb * (col.a * ndotl * atten);\n"diff --git a/tools/renderScenes.mjs b/tools/renderScenes.mjsindex 8d5779634..132baae02 100644--- a/tools/renderScenes.mjs+++ b/tools/renderScenes.mjs@@ -84,6 +84,14 @@ export const SCENES = [// face it lands in. TWO shadows in two faces is what makes that choice visible: report// one tile for every tile and both come back lit. The casters are probed as well.{ id: "point-shadow", tier: "pr", webgpu: true, env: { ESTELLA_VERIFY_SCENE: "/scenes/point-shadow.esscene", ESTELLA_VERIFY_W: "256", ESTELLA_VERIFY_H: "256", ESTELLA_VERIFY_STEPS: "2", ESTELLA_VERIFY_EXPECT: "[{\"x\":0.167,\"y\":0.5,\"rgb\":[0,0,0],\"tol\":20},{\"x\":0.5,\"y\":0.833,\"rgb\":[0,0,0],\"tol\":20},{\"x\":0.333,\"y\":0.5,\"rgb\":[108,108,108],\"tol\":25},{\"x\":0.833,\"y\":0.5,\"rgb\":[102,102,102],\"tol\":25},{\"x\":0.5,\"y\":0.5,\"rgb\":[242,242,242],\"tol\":20}]" } },+ // A SUN WITH A SIZE: its source is infinitely far away, so what it carries is an angle+ // and not a length — the penumbra is tan(sourceAngle/2) times how far the caster stands+ // above what it falls on. Its ramp sits one sample step along on the second backend.+ { id: "sun-shadow", tier: "pr", webgpu: { ESTELLA_VERIFY_EXPECT: "[{\"x\":0.62,\"y\":0.5,\"rgb\":[0,0,0],\"tol\":20},{\"x\":0.66,\"y\":0.5,\"rgb\":[39,39,39],\"tol\":30},{\"x\":0.72,\"y\":0.5,\"rgb\":[186,186,186],\"tol\":30},{\"x\":0.85,\"y\":0.5,\"rgb\":[247,247,247],\"tol\":20}]" }, env: { ESTELLA_VERIFY_SCENE: "/scenes/sun-shadow.esscene", ESTELLA_VERIFY_W: "256", ESTELLA_VERIFY_H: "256", ESTELLA_VERIFY_STEPS: "2", ESTELLA_VERIFY_EXPECT: "[{\"x\":0.62,\"y\":0.5,\"rgb\":[0,0,0],\"tol\":20},{\"x\":0.66,\"y\":0.5,\"rgb\":[70,70,70],\"tol\":35},{\"x\":0.72,\"y\":0.5,\"rgb\":[209,209,209],\"tol\":25},{\"x\":0.85,\"y\":0.5,\"rgb\":[247,247,247],\"tol\":20}]" } },+ // The same scene with the caster moved DOWN the sun's own ray: its shadow lands where it+ // did and the edge sharpens by the ratio of the distances. Two of these four probes+ // differ from the gate above by 70 and 38, which a fixed blur could not produce.+ { id: "sun-shadow-contact", tier: "pr", webgpu: true, env: { ESTELLA_VERIFY_SCENE: "/scenes/sun-shadow-contact.esscene", ESTELLA_VERIFY_W: "256", ESTELLA_VERIFY_H: "256", ESTELLA_VERIFY_STEPS: "2", ESTELLA_VERIFY_EXPECT: "[{\"x\":0.62,\"y\":0.5,\"rgb\":[0,0,0],\"tol\":20},{\"x\":0.66,\"y\":0.5,\"rgb\":[0,0,0],\"tol\":20},{\"x\":0.72,\"y\":0.5,\"rgb\":[247,247,247],\"tol\":25},{\"x\":0.85,\"y\":0.5,\"rgb\":[247,247,247],\"tol\":20}]" } },// A SOURCE WITH SIZE. The light's half-extent, the blocker's distance from it and the// receiver's are the whole penumbra, so these probes read a soft edge here and a hard// one in the gate below, where the same scene's caster stands near what it falls on.