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 sun can be aimed out of the plane

yhhdee3295f5f1e
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 0c3151733..e860fecb8 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -16,6 +16,20 @@ published separately; it ships inside the editor.
### Added
+- **A sun can be aimed out of the plane.** A directional light's aim had two
+ components and a third the shader supplied as a constant, so every scene the
+ engine could express was lit from in front: the sun's elevation followed from
+ how far it was tilted within the plane, and nothing could put it low, behind, or
+ overhead. `Light2D.directionZ` is that third component, and the shadow map reads
+ the same aim, so the shadow goes where the light says rather than where the
+ constant did.
+
+ It defaults to -1, which is the direction a 2D scene's light has always come
+ from — every existing scene renders the same bytes, and all 87 pixel gates agree
+ on both backends. Point and spot lights still synthesize their depth from the
+ falloff radius; that is what gives a flat scene its shading, and giving them real
+ positions is a separate change with a compatibility story of its own.
+
- **FBX import.** A `.fbx` is a model source like a `.gltf` is: drop one in and it
writes the same products — `.esmesh` per material run, the images it embeds, an
`.esmaterial`, an `.estimeline` per take, and the `.esprefab` that assembles
diff --git a/desktop/public/scenes/mesh-shadow-aimed.esscene b/desktop/public/scenes/mesh-shadow-aimed.esscene
new file mode 100644
index 000000000..b6511ecc2
--- /dev/null
+++ b/desktop/public/scenes/mesh-shadow-aimed.esscene
@@ -0,0 +1,140 @@
+{
+ "version": 1,
+ "name": "MeshShadowAimed",
+ "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": "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": 0,
+ "y": 0,
+ "z": 0
+ },
+ "scale": {
+ "x": 150,
+ "y": 150,
+ "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": "Light2D",
+ "data": {
+ "type": 1,
+ "color": {
+ "r": 1,
+ "g": 1,
+ "b": 1,
+ "a": 1
+ },
+ "intensity": 1,
+ "direction": {
+ "x": 0.25,
+ "y": 0
+ },
+ "directionZ": -0.25,
+ "meshShadows": true
+ }
+ }
+ ]
+ }
+ ]
+}
diff --git a/docs/astro/src/data/components.generated.json b/docs/astro/src/data/components.generated.json
index 5e2f08724..6d6ce3e0c 100644
--- a/docs/astro/src/data/components.generated.json
+++ b/docs/astro/src/data/components.generated.json
@@ -1578,6 +1578,13 @@
"doc": "Aim direction (Directional / Spot).",
"advanced": true
},
+ {
+ "key": "directionZ",
+ "type": "number",
+ "default": "-1",
+ "doc": "Aim depth (Directional): -1 shines into the screen.",
+ "advanced": true
+ },
{
"key": "innerAngle",
"type": "number",
@@ -1640,6 +1647,7 @@
"color.a",
"intensity",
"radius",
+ "directionZ",
"innerAngle",
"outerAngle",
"shadowSoftness",
diff --git a/sdk/etc/index.api.md b/sdk/etc/index.api.md
index f560dc56a..2ec4092a8 100644
--- a/sdk/etc/index.api.md
+++ b/sdk/etc/index.api.md
@@ -5,7 +5,7 @@ Symbols: 113 public · 66 beta · 1450 experimental · 3 deprecated
## ABI_LAYOUT_HASH — const @experimental
```
-"7087d13f8df10c56"
+"ea9373ff870f868a"
```
## ANCHOR_AXES — const @experimental
@@ -3965,6 +3965,7 @@ BuiltinComponentDef<Light2DData>
```
color: Color
direction: Vec2
+directionZ: number
enabled: boolean
environment: number
innerAngle: number
diff --git a/sdk/etc/index.native.api.md b/sdk/etc/index.native.api.md
index f99cfcfe8..c562c73be 100644
--- a/sdk/etc/index.native.api.md
+++ b/sdk/etc/index.native.api.md
@@ -5,7 +5,7 @@ Symbols: 113 public · 71 beta · 1469 experimental · 3 deprecated
## ABI_LAYOUT_HASH — const @experimental
```
-"7087d13f8df10c56"
+"ea9373ff870f868a"
```
## ANCHOR_AXES — const @experimental
@@ -3973,6 +3973,7 @@ BuiltinComponentDef<Light2DData>
```
color: Color
direction: Vec2
+directionZ: number
enabled: boolean
environment: number
innerAngle: number
diff --git a/sdk/etc/index.node.api.md b/sdk/etc/index.node.api.md
index f5cd79de8..e860ac747 100644
--- a/sdk/etc/index.node.api.md
+++ b/sdk/etc/index.node.api.md
@@ -3960,6 +3960,7 @@ BuiltinComponentDef<Light2DData>
```
color: Color
direction: Vec2
+directionZ: number
enabled: boolean
environment: number
innerAngle: number
diff --git a/sdk/etc/minigame.api.md b/sdk/etc/minigame.api.md
index fde0a951e..7fe936285 100644
--- a/sdk/etc/minigame.api.md
+++ b/sdk/etc/minigame.api.md
@@ -3960,6 +3960,7 @@ BuiltinComponentDef<Light2DData>
```
color: Color
direction: Vec2
+directionZ: number
enabled: boolean
environment: number
innerAngle: number
diff --git a/sdk/etc/wechat.api.md b/sdk/etc/wechat.api.md
index 0804947c4..7766edba7 100644
--- a/sdk/etc/wechat.api.md
+++ b/sdk/etc/wechat.api.md
@@ -3967,6 +3967,7 @@ BuiltinComponentDef<Light2DData>
```
color: Color
direction: Vec2
+directionZ: number
enabled: boolean
environment: number
innerAngle: number
diff --git a/sdk/src/ecs/bridge/ptrAccessors.generated.ts b/sdk/src/ecs/bridge/ptrAccessors.generated.ts
index 488424951..98a5a7fb2 100644
--- a/sdk/src/ecs/bridge/ptrAccessors.generated.ts
+++ b/sdk/src/ecs/bridge/ptrAccessors.generated.ts
@@ -691,6 +691,7 @@ export interface Light2DPtrData {
intensity: number;
radius: number;
direction: Vec2;
+ directionZ: number;
innerAngle: number;
outerAngle: number;
shadowSoftness: number;
@@ -710,14 +711,15 @@ export function fillLight2D(
out.intensity = f32[(ptr + 20) >> 2];
out.radius = f32[(ptr + 24) >> 2];
const direction_ = out.direction; direction_.x = f32[(ptr + 28) >> 2]; direction_.y = f32[((ptr + 28) >> 2) + 1];
- out.innerAngle = f32[(ptr + 36) >> 2];
- out.outerAngle = f32[(ptr + 40) >> 2];
- out.shadowSoftness = f32[(ptr + 44) >> 2];
- out.shadowDistance = f32[(ptr + 48) >> 2];
- out.meshShadows = u8[ptr + 52] !== 0;
- out.shadowExtent = f32[(ptr + 56) >> 2];
- out.environment = u32[(ptr + 60) >> 2];
- out.enabled = u8[ptr + 64] !== 0;
+ out.directionZ = f32[(ptr + 36) >> 2];
+ out.innerAngle = f32[(ptr + 40) >> 2];
+ out.outerAngle = f32[(ptr + 44) >> 2];
+ out.shadowSoftness = f32[(ptr + 48) >> 2];
+ out.shadowDistance = f32[(ptr + 52) >> 2];
+ out.meshShadows = u8[ptr + 56] !== 0;
+ out.shadowExtent = f32[(ptr + 60) >> 2];
+ out.environment = u32[(ptr + 64) >> 2];
+ out.enabled = u8[ptr + 68] !== 0;
}
export function writeLight2D(
@@ -729,14 +731,15 @@ export function writeLight2D(
f32[(ptr + 20) >> 2] = data.intensity;
f32[(ptr + 24) >> 2] = data.radius;
f32[(ptr + 28) >> 2] = data.direction.x; f32[((ptr + 28) >> 2) + 1] = data.direction.y;
- f32[(ptr + 36) >> 2] = data.innerAngle;
- f32[(ptr + 40) >> 2] = data.outerAngle;
- f32[(ptr + 44) >> 2] = data.shadowSoftness;
- f32[(ptr + 48) >> 2] = data.shadowDistance;
- u8[ptr + 52] = data.meshShadows ? 1 : 0;
- f32[(ptr + 56) >> 2] = data.shadowExtent;
- u32[(ptr + 60) >> 2] = data.environment;
- u8[ptr + 64] = data.enabled ? 1 : 0;
+ f32[(ptr + 36) >> 2] = data.directionZ;
+ f32[(ptr + 40) >> 2] = data.innerAngle;
+ f32[(ptr + 44) >> 2] = data.outerAngle;
+ f32[(ptr + 48) >> 2] = data.shadowSoftness;
+ f32[(ptr + 52) >> 2] = data.shadowDistance;
+ u8[ptr + 56] = data.meshShadows ? 1 : 0;
+ f32[(ptr + 60) >> 2] = data.shadowExtent;
+ u32[(ptr + 64) >> 2] = data.environment;
+ u8[ptr + 68] = data.enabled ? 1 : 0;
}
export function createLight2DData(): Light2DPtrData {
@@ -746,6 +749,7 @@ export function createLight2DData(): Light2DPtrData {
intensity: 0,
radius: 0,
direction: { x: 0, y: 0 },
+ directionZ: 0,
innerAngle: 0,
outerAngle: 0,
shadowSoftness: 0,
diff --git a/sdk/src/ecs/component.generated.ts b/sdk/src/ecs/component.generated.ts
index 8bb716200..0dd9f5835 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 = '7087d13f8df10c56';
+export const ABI_LAYOUT_HASH = 'ea9373ff870f868a';
/**
* One asset-valued field of a component: which field, and what kind of
@@ -393,6 +393,7 @@ export const COMPONENT_META: Record<string, ComponentMetaEntry> = {
intensity: 1,
radius: 200,
direction: { x: 0, y: 0 },
+ directionZ: -1,
innerAngle: 30,
outerAngle: 45,
shadowSoftness: 0,
@@ -406,12 +407,13 @@ 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', 'directionZ', 'innerAngle', 'outerAngle', 'shadowSoftness', '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." },
radius: { min: 0, tooltip: "Falloff reach in world units (Point / Spot)." },
direction: { tooltip: "Aim direction (Directional / Spot).", advanced: true },
+ directionZ: { tooltip: "Aim depth (Directional): -1 shines into the screen.", advanced: true },
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." },
@@ -1203,6 +1205,7 @@ export interface Light2DData {
intensity: number;
radius: number;
direction: Vec2;
+ directionZ: number;
innerAngle: number;
outerAngle: number;
shadowSoftness: number;
diff --git a/sdk/src/wasm/ptrLayouts.generated.ts b/sdk/src/wasm/ptrLayouts.generated.ts
index 43be52a6f..465f7e270 100644
--- a/sdk/src/wasm/ptrLayouts.generated.ts
+++ b/sdk/src/wasm/ptrLayouts.generated.ts
@@ -204,14 +204,15 @@ export const PTR_LAYOUTS: Record<string, PtrLayout> = {
{ name: 'intensity', type: 'f32', offset: 20 },
{ name: 'radius', type: 'f32', offset: 24 },
{ name: 'direction', type: 'vec2', offset: 28 },
- { name: 'innerAngle', type: 'f32', offset: 36 },
- { name: 'outerAngle', type: 'f32', offset: 40 },
- { name: 'shadowSoftness', type: 'f32', offset: 44 },
- { name: 'shadowDistance', type: 'f32', offset: 48 },
- { name: 'meshShadows', type: 'bool', offset: 52 },
- { name: 'shadowExtent', type: 'f32', offset: 56 },
- { name: 'environment', type: 'u32', offset: 60 },
- { name: 'enabled', type: 'bool', offset: 64 },
+ { name: 'directionZ', type: 'f32', offset: 36 },
+ { name: 'innerAngle', type: 'f32', offset: 40 },
+ { name: 'outerAngle', type: 'f32', offset: 44 },
+ { name: 'shadowSoftness', type: 'f32', offset: 48 },
+ { name: 'shadowDistance', type: 'f32', offset: 52 },
+ { name: 'meshShadows', type: 'bool', offset: 56 },
+ { name: 'shadowExtent', type: 'f32', offset: 60 },
+ { name: 'environment', type: 'u32', offset: 64 },
+ { name: 'enabled', type: 'bool', offset: 68 },
],
},
Mesh2D: {
diff --git a/sdk/src/wasm/wasm.generated.ts b/sdk/src/wasm/wasm.generated.ts
index 24cc9cfb1..381c2df12 100644
--- a/sdk/src/wasm/wasm.generated.ts
+++ b/sdk/src/wasm/wasm.generated.ts
@@ -376,6 +376,7 @@ export interface Light2D {
intensity: number;
radius: number;
direction: Vec2;
+ directionZ: number;
innerAngle: number;
outerAngle: number;
shadowSoftness: number;
diff --git a/sdk/tests/__snapshots__/component-fieldmeta-golden.test.ts.snap b/sdk/tests/__snapshots__/component-fieldmeta-golden.test.ts.snap
index c291148ba..37cb63d77 100644
--- a/sdk/tests/__snapshots__/component-fieldmeta-golden.test.ts.snap
+++ b/sdk/tests/__snapshots__/component-fieldmeta-golden.test.ts.snap
@@ -165,6 +165,10 @@ exports[`builtin FieldMeta (RC9-1 equivalence gate) > matches the golden snapsho
"advanced": true,
"tooltip": "Aim direction (Directional / Spot).",
},
+ "directionZ": {
+ "advanced": true,
+ "tooltip": "Aim depth (Directional): -1 shines into the screen.",
+ },
"environment": {
"tooltip": "Baked environment (.esenv) this Ambient light casts.",
},
diff --git a/src/esengine/bindings/EditorAPI.generated.cpp b/src/esengine/bindings/EditorAPI.generated.cpp
index d3b9318b0..718919a5f 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 d160157386bf7a78
+ * @schema_hash 5c60fe026ad2d679
*/
-#define ES_EDITOR_API_SCHEMA_HASH "d160157386bf7a78"
+#define ES_EDITOR_API_SCHEMA_HASH "5c60fe026ad2d679"
#include <emscripten/bind.h>
#include <string>
@@ -295,6 +295,7 @@ std::string editor_getComponentSchema(const std::string& name) {
{"key":"radius","type":"float","group":"Light2D"},
{"key":"direction.x","type":"float","group":"Light2D"},
{"key":"direction.y","type":"float","group":"Light2D"},
+ {"key":"directionZ","type":"float","group":"Light2D"},
{"key":"innerAngle","type":"float","group":"Light2D"},
{"key":"outerAngle","type":"float","group":"Light2D"},
{"key":"shadowSoftness","type":"float","group":"Light2D"},
@@ -1144,6 +1145,7 @@ bool editor_setFloat(Registry& reg, u32 e, const std::string& comp, const std::s
else if (field == "radius") { c.radius = value; }
else if (field == "direction.x") { c.direction.x = value; }
else if (field == "direction.y") { c.direction.y = value; }
+ else if (field == "directionZ") { c.directionZ = value; }
else if (field == "innerAngle") { c.innerAngle = value; }
else if (field == "outerAngle") { c.outerAngle = value; }
else if (field == "shadowSoftness") { c.shadowSoftness = value; }
@@ -1599,6 +1601,7 @@ f32 editor_getFloat(Registry& reg, u32 e, const std::string& comp, const std::st
else if (field == "radius") { return c.radius; }
else if (field == "direction.x") { return c.direction.x; }
else if (field == "direction.y") { return c.direction.y; }
+ else if (field == "directionZ") { return c.directionZ; }
else if (field == "innerAngle") { return c.innerAngle; }
else if (field == "outerAngle") { return c.outerAngle; }
else if (field == "shadowSoftness") { return c.shadowSoftness; }
diff --git a/src/esengine/bindings/WebBindings.generated.cpp b/src/esengine/bindings/WebBindings.generated.cpp
index 21b604859..0a586d7bb 100644
--- a/src/esengine/bindings/WebBindings.generated.cpp
+++ b/src/esengine/bindings/WebBindings.generated.cpp
@@ -477,6 +477,7 @@ struct Light2DJS {
f32 intensity;
f32 radius;
glm::vec2 direction;
+ f32 directionZ;
f32 innerAngle;
f32 outerAngle;
f32 shadowSoftness;
@@ -493,6 +494,7 @@ void light2dApplyJS(esengine::ecs::Light2D& c, const Light2DJS& js) {
c.intensity = js.intensity;
c.radius = js.radius;
c.direction = js.direction;
+ c.directionZ = js.directionZ;
c.innerAngle = js.innerAngle;
c.outerAngle = js.outerAngle;
c.shadowSoftness = js.shadowSoftness;
@@ -516,6 +518,7 @@ Light2DJS light2dToJS(const esengine::ecs::Light2D& c) {
js.intensity = c.intensity;
js.radius = c.radius;
js.direction = c.direction;
+ js.directionZ = c.directionZ;
js.innerAngle = c.innerAngle;
js.outerAngle = c.outerAngle;
js.shadowSoftness = c.shadowSoftness;
@@ -1435,6 +1438,7 @@ EMSCRIPTEN_BINDINGS(esengine_components) {
.field("intensity", &Light2DJS::intensity)
.field("radius", &Light2DJS::radius)
.field("direction", &Light2DJS::direction)
+ .field("directionZ", &Light2DJS::directionZ)
.field("innerAngle", &Light2DJS::innerAngle)
.field("outerAngle", &Light2DJS::outerAngle)
.field("shadowSoftness", &Light2DJS::shadowSoftness)
@@ -2779,14 +2783,15 @@ static_assert(offsetof(esengine::ecs::Light2D, color) == 4, "ABI offset drift: e
static_assert(offsetof(esengine::ecs::Light2D, intensity) == 20, "ABI offset drift: esengine::ecs::Light2D.intensity (EHT expected 20)");
static_assert(offsetof(esengine::ecs::Light2D, radius) == 24, "ABI offset drift: esengine::ecs::Light2D.radius (EHT expected 24)");
static_assert(offsetof(esengine::ecs::Light2D, direction) == 28, "ABI offset drift: esengine::ecs::Light2D.direction (EHT expected 28)");
-static_assert(offsetof(esengine::ecs::Light2D, innerAngle) == 36, "ABI offset drift: esengine::ecs::Light2D.innerAngle (EHT expected 36)");
-static_assert(offsetof(esengine::ecs::Light2D, outerAngle) == 40, "ABI offset drift: esengine::ecs::Light2D.outerAngle (EHT expected 40)");
-static_assert(offsetof(esengine::ecs::Light2D, shadowSoftness) == 44, "ABI offset drift: esengine::ecs::Light2D.shadowSoftness (EHT expected 44)");
-static_assert(offsetof(esengine::ecs::Light2D, shadowDistance) == 48, "ABI offset drift: esengine::ecs::Light2D.shadowDistance (EHT expected 48)");
-static_assert(offsetof(esengine::ecs::Light2D, meshShadows) == 52, "ABI offset drift: esengine::ecs::Light2D.meshShadows (EHT expected 52)");
-static_assert(offsetof(esengine::ecs::Light2D, shadowExtent) == 56, "ABI offset drift: esengine::ecs::Light2D.shadowExtent (EHT expected 56)");
-static_assert(offsetof(esengine::ecs::Light2D, environment) == 60, "ABI offset drift: esengine::ecs::Light2D.environment (EHT expected 60)");
-static_assert(offsetof(esengine::ecs::Light2D, enabled) == 64, "ABI offset drift: esengine::ecs::Light2D.enabled (EHT expected 64)");
+static_assert(offsetof(esengine::ecs::Light2D, directionZ) == 36, "ABI offset drift: esengine::ecs::Light2D.directionZ (EHT expected 36)");
+static_assert(offsetof(esengine::ecs::Light2D, innerAngle) == 40, "ABI offset drift: esengine::ecs::Light2D.innerAngle (EHT expected 40)");
+static_assert(offsetof(esengine::ecs::Light2D, outerAngle) == 44, "ABI offset drift: esengine::ecs::Light2D.outerAngle (EHT expected 44)");
+static_assert(offsetof(esengine::ecs::Light2D, shadowSoftness) == 48, "ABI offset drift: esengine::ecs::Light2D.shadowSoftness (EHT expected 48)");
+static_assert(offsetof(esengine::ecs::Light2D, shadowDistance) == 52, "ABI offset drift: esengine::ecs::Light2D.shadowDistance (EHT expected 52)");
+static_assert(offsetof(esengine::ecs::Light2D, meshShadows) == 56, "ABI offset drift: esengine::ecs::Light2D.meshShadows (EHT expected 56)");
+static_assert(offsetof(esengine::ecs::Light2D, shadowExtent) == 60, "ABI offset drift: esengine::ecs::Light2D.shadowExtent (EHT expected 60)");
+static_assert(offsetof(esengine::ecs::Light2D, environment) == 64, "ABI offset drift: esengine::ecs::Light2D.environment (EHT expected 64)");
+static_assert(offsetof(esengine::ecs::Light2D, enabled) == 68, "ABI offset drift: esengine::ecs::Light2D.enabled (EHT expected 68)");
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 = "7087d13f8df10c56";
+static const char* kEsAbiLayoutHash = "ea9373ff870f868a";
std::string esengineGetAbiLayoutHash() {
return std::string(kEsAbiLayoutHash);
diff --git a/src/esengine/ecs/components/Light2D.hpp b/src/esengine/ecs/components/Light2D.hpp
index 805524d31..99c23a3e4 100644
--- a/src/esengine/ecs/components/Light2D.hpp
+++ b/src/esengine/ecs/components/Light2D.hpp
@@ -73,6 +73,12 @@ struct Light2D {
ES_PROPERTY(advanced, tooltip="Aim direction (Directional / Spot).")
glm::vec2 direction{0.0f, 0.0f};
+ /** @brief The third component of a Directional light's aim, so a sun can be placed in a
+ * 3D scene rather than only tilted within the plane. -1 shines into the screen,
+ * which is where a 2D scene's light has always come from. */
+ ES_PROPERTY(animatable, advanced, tooltip="Aim depth (Directional): -1 shines into the screen.")
+ f32 directionZ{-1.0f};
+
/** @brief Spot inner cone angle in degrees (full angle; fully lit inside). */
ES_PROPERTY(animatable, min=0, max=180, unit="°", advanced)
f32 innerAngle{30.0f};
diff --git a/src/esengine/renderer/frame/RenderFrame.cpp b/src/esengine/renderer/frame/RenderFrame.cpp
index 3f96c54b4..12b276ed7 100644
--- a/src/esengine/renderer/frame/RenderFrame.cpp
+++ b/src/esengine/renderer/frame/RenderFrame.cpp
@@ -637,6 +637,13 @@ RenderFrameContext RenderFrame::makeContext() {
};
}
+/// A directional light's aim depth. An aim of zero in all three has no direction to
+/// give, so it keeps the one a 2D scene has always had rather than dividing by zero.
+static f32 aimZ(const ecs::Light2D& light) {
+ const glm::vec3 aim(light.direction, light.directionZ);
+ return glm::dot(aim, aim) > 1e-8f ? light.directionZ : -1.0f;
+}
+
void RenderFrame::collectLights(ecs::Registry& registry) {
LightStore& lights = context_.lights();
lights.clear();
@@ -678,13 +685,15 @@ void RenderFrame::collectLights(ecs::Registry& registry) {
gpu.shadow = glm::vec4(std::max(light.shadowSoftness, 0.0f),
std::max(light.shadowDistance, 0.0f), 0.0f, 0.0f);
if (type == ecs::Light2DType::Directional) {
- // Direction in the 2D plane; z=1 flags directional (no attenuation) in the shader.
- gpu.posDir = glm::vec4(light.direction.x, light.direction.y, 1.0f, 0.0f);
+ // z=1 flags directional (no attenuation) in the shader; w carries the aim's third
+ // component, which only a directional light has a use for — point and spot spend
+ // that slot on their falloff radius.
+ gpu.posDir = glm::vec4(light.direction.x, light.direction.y, 1.0f, aimZ(light));
// Marked here and read back after the cap sort, so the slot recorded is the
// slot the shader will index. shadow.z is cleared before it reaches the GPU.
if (light.meshShadows && shadow_light_slot_ < 0) {
gpu.shadow.z = 1.0f;
- shadow_light_dir_ = light.direction;
+ shadow_light_dir_ = glm::vec3(light.direction, aimZ(light));
shadow_light_extent_ = std::max(light.shadowExtent, 0.0f);
}
} else { // Point / Spot — world position from the Transform, w=falloff radius.
@@ -819,9 +828,8 @@ void RenderFrame::renderShadowMap(ecs::Registry& registry) {
const glm::vec3 centre = haveBounds ? (boundsMin + boundsMax) * 0.5f
: glm::vec3(view.center.x, view.center.y, 0.0f);
- // The light's own direction, in the three dimensions the 2D field implies: the
- // shader lights a surface from normalize(-dir.xy, 1), so rays travel the other way.
- glm::vec3 toLight = glm::normalize(glm::vec3(-shadow_light_dir_.x, -shadow_light_dir_.y, 1.0f));
+ // The shader lights a surface from normalize(-aim), so rays travel the other way.
+ glm::vec3 toLight = glm::normalize(-shadow_light_dir_);
// An up that cannot be parallel to it, whichever way the light points.
const glm::vec3 up = std::abs(toLight.z) > 0.99f ? glm::vec3(0.0f, 1.0f, 0.0f)
: glm::vec3(0.0f, 0.0f, 1.0f);
diff --git a/src/esengine/renderer/frame/RenderFrame.hpp b/src/esengine/renderer/frame/RenderFrame.hpp
index d54c16da8..6635cfd50 100644
--- a/src/esengine/renderer/frame/RenderFrame.hpp
+++ b/src/esengine/renderer/frame/RenderFrame.hpp
@@ -322,7 +322,7 @@ private:
/// Which light slot casts the map, and the direction + coverage it asked for.
/// Written by collectLights, read by renderShadowMap; -1 = nobody asked.
i32 shadow_light_slot_ = -1;
- glm::vec2 shadow_light_dir_{0.0f};
+ glm::vec3 shadow_light_dir_{0.0f, 0.0f, -1.0f};
f32 shadow_light_extent_ = 0.0f;
RenderTargetManager::Handle shadow_rt_ = 0;
/// The map's colour texture, handed to every mesh that receives it. 0 = none this frame.
diff --git a/src/esengine/renderer/store/LightConstants.hpp b/src/esengine/renderer/store/LightConstants.hpp
index 759fed93d..128565561 100644
--- a/src/esengine/renderer/store/LightConstants.hpp
+++ b/src/esengine/renderer/store/LightConstants.hpp
@@ -54,8 +54,10 @@ inline constexpr u32 MAX_OCCLUDERS_2D = 8;
/**
* @brief One 2D light, std140-packed (four vec4s, 64 bytes, 16-aligned).
- * @details posDir: xy = world position (point/spot) or direction (directional); z = type
- * (0 = point, 1 = directional, 2 = spot); w = falloff radius (point/spot, world units).
+ * @details posDir: xy = world position (point/spot) or aim direction (directional); z = type
+ * (0 = point, 1 = directional, 2 = spot); w = falloff radius in world units for
+ * point/spot, and the aim's third component for directional — the two never share
+ * a use for it, which is what lets a sun be aimed out of the plane.
* color: rgb = light color, a = intensity.
* spot: xy = normalized cone axis, z = cos(innerHalfAngle), w = cos(outerHalfAngle)
* (spot only; zero for other types). Ambient lights are folded into
diff --git a/src/esengine/resource/ShaderParser.cpp b/src/esengine/resource/ShaderParser.cpp
index 932c0f419..f15f6d402 100644
--- a/src/esengine/resource/ShaderParser.cpp
+++ b/src/esengine/resource/ShaderParser.cpp
@@ -917,7 +917,7 @@ fn applyLightingPBR(albedo : vec3f, N : vec3f, worldPos : vec3f, V : vec3f, meta
L = normalize(vec3f(d, max(pd.w, 1.0)));
} else if (pd.z < 1.5) {
atten = 1.0;
- L = normalize(vec3f(-pd.xy, 1.0));
+ L = normalize(-vec3f(pd.xy, pd.w));
var toLight = vec2f(0.0, 0.0);
if (dot(pd.xy, pd.xy) > 1e-8) { toLight = normalize(-pd.xy); }
castShadow = sh.y > 0.0 && dot(toLight, toLight) > 0.5;
@@ -1500,7 +1500,8 @@ ShaderParser::AssembledStage ShaderParser::assembleStageEx(const ParsedShader& p
" L = normalize(vec3(d, max(pd.w, 1.0)));\n"
" } else if (pd.z < 1.5) {\n"
" atten = 1.0;\n"
- " L = normalize(vec3(-pd.xy, 1.0));\n"
+ // pd.w is the aim's third component here; point/spot spend that slot on radius.
+ " L = normalize(-vec3(pd.xy, pd.w));\n"
// Directional rays are parallel: aim at a far point toward the light source, opt in via
// a positive march distance, and require a real direction (a zeroed one casts nothing).
" highp vec2 toLight = (dot(pd.xy, pd.xy) > 1e-8) ? normalize(-pd.xy) : vec2(0.0);\n"
diff --git a/tools/renderScenes.mjs b/tools/renderScenes.mjs
index e871031e8..2e5b82767 100644
--- a/tools/renderScenes.mjs
+++ b/tools/renderScenes.mjs
@@ -60,6 +60,10 @@ export const SCENES = [
// coverage derived from the camera's NDC z=0 slice is the whole view for the
// orthographic one above and a sliver near the near plane for this one.
{ id: "mesh-shadow-perspective", tier: "pr", webgpu: true, env: { ESTELLA_VERIFY_SCENE: "/scenes/mesh-shadow-perspective.esscene", ESTELLA_VERIFY_W: "256", ESTELLA_VERIFY_H: "256", ESTELLA_VERIFY_STEPS: "2", ESTELLA_VERIFY_EXPECT: "[{\"x\":0.86,\"y\":0.5,\"rgb\":[0,0,0],\"tol\":20},{\"x\":0.10,\"y\":0.5,\"rgb\":[228,228,228],\"tol\":20},{\"x\":0.5,\"y\":0.5,\"rgb\":[228,228,228],\"tol\":20}]" } },
+ // A sun aimed OUT of the plane: 0.25 in x and 0.25 in depth throws the blocker's
+ // shadow to world +200, where a depth of -1 puts it at +50. Measured: the probe
+ // at 0.833 reads 247 at depth -1 and 0 at this one.
+ { id: "mesh-shadow-aimed", tier: "pr", webgpu: true, env: { ESTELLA_VERIFY_SCENE: "/scenes/mesh-shadow-aimed.esscene", ESTELLA_VERIFY_W: "256", ESTELLA_VERIFY_H: "256", ESTELLA_VERIFY_STEPS: "2", ESTELLA_VERIFY_EXPECT: "[{\"x\":0.833,\"y\":0.5,\"rgb\":[0,0,0],\"tol\":20},{\"x\":0.167,\"y\":0.5,\"rgb\":[180,180,180],\"tol\":20},{\"x\":0.5,\"y\":0.5,\"rgb\":[180,180,180],\"tol\":20}]" } },
// A baked panorama lighting a surface BY DIRECTION: two coplanar triangles, one
// white colour, normals up and down under a sky blue above and red below. A flat
// ambient term draws the halves identically, which is why the probes invert.