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 2D shadow caster can carry its own outline

esenginef983e4fecf79
diff --git a/CHANGELOG.md b/CHANGELOG.md
index ef0da0973..4d0c404b9 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -16,6 +16,19 @@ published separately; it ships inside the editor.
### Fixed
+- **A 2D shadow caster can carry its own outline.** Every occluder was a box, so a
+ round prop threw a rectangle and a wall that was not rectangular threw the wrong
+ wall. `ShadowCaster2D.path` is the shape itself — three points or more in the
+ entity's own space, placed and turned by its Transform, and the box stands where
+ there is none. The shadow pass already drew rings rather than boxes, so a polygon
+ costs what its point count costs and nothing else.
+
+ What it needed was a boundary that can carry a point list. One now crosses to the
+ web as a JS array and to a native host through a generated pair of bindings — its
+ storage is a pointer, so it can never travel in the zero-copy component buffer the
+ rest of a component's fields cross in. A field type the boundary cannot carry is
+ refused at generation time instead of failing when a scene adds the component.
+
- **A 2D shadow caster turns with the entity it is on.** Its box was built from the
entity's world position and its own size, and from nothing else: a wall laid at an angle
cast the shadow of an upright wall, and turning the wall changed nothing on screen. The
diff --git a/docs/astro/src/data/components.generated.json b/docs/astro/src/data/components.generated.json
index 04b0233c9..e83f0df40 100644
--- a/docs/astro/src/data/components.generated.json
+++ b/docs/astro/src/data/components.generated.json
@@ -3497,9 +3497,14 @@
"key": "size",
"type": "Vec2",
"default": "(32, 32)",
- "doc": "Occluder box size in world units (centred on the entity, turning with it).",
+ "doc": "Occluder box size in world units (centred on the entity, turning with it). Unused when the caster has an outline.",
"range": "≥ 0"
},
+ {
+ "key": "path",
+ "type": "array",
+ "default": "empty"
+ },
{
"key": "enabled",
"type": "boolean",
diff --git a/fixtures/scenes/mat-lit-shadow-outline.esscene b/fixtures/scenes/mat-lit-shadow-outline.esscene
new file mode 100644
index 000000000..766cade57
--- /dev/null
+++ b/fixtures/scenes/mat-lit-shadow-outline.esscene
@@ -0,0 +1,146 @@
+{
+ "version": 4,
+ "name": "Main",
+ "entities": [
+ {
+ "id": 0,
+ "name": "Camera",
+ "parent": null,
+ "children": [],
+ "components": [
+ {
+ "type": "Transform",
+ "data": {
+ "position": {
+ "x": 0,
+ "y": 0,
+ "z": 10
+ }
+ }
+ },
+ {
+ "type": "Camera",
+ "data": {
+ "projectionType": 1,
+ "orthoSize": 300,
+ "isActive": true,
+ "priority": 0
+ }
+ }
+ ],
+ "visible": true
+ },
+ {
+ "id": 1,
+ "name": "Lit",
+ "parent": null,
+ "children": [],
+ "components": [
+ {
+ "type": "Transform",
+ "data": {
+ "position": {
+ "x": 0,
+ "y": 0,
+ "z": 0
+ }
+ }
+ },
+ {
+ "type": "Sprite",
+ "data": {
+ "size": {
+ "x": 400,
+ "y": 400
+ },
+ "color": {
+ "r": 1,
+ "g": 1,
+ "b": 1,
+ "a": 1
+ },
+ "material": "/scenes/mat-lit/lit.esmaterial"
+ }
+ }
+ ],
+ "visible": true
+ },
+ {
+ "id": 2,
+ "name": "GreenPointLight",
+ "parent": null,
+ "children": [],
+ "components": [
+ {
+ "type": "Transform",
+ "data": {
+ "position": {
+ "x": -150,
+ "y": 0,
+ "z": 0
+ }
+ }
+ },
+ {
+ "type": "Light",
+ "data": {
+ "type": 0,
+ "color": {
+ "r": 0,
+ "g": 1,
+ "b": 0,
+ "a": 1
+ },
+ "intensity": 1,
+ "radius": 800,
+ "shadowSoftness": 0
+ }
+ }
+ ],
+ "visible": true
+ },
+ {
+ "id": 3,
+ "name": "Outline",
+ "parent": null,
+ "children": [],
+ "components": [
+ {
+ "type": "Transform",
+ "data": {
+ "position": {
+ "x": 0,
+ "y": 0,
+ "z": 0
+ }
+ }
+ },
+ {
+ "type": "ShadowCaster2D",
+ "data": {
+ "size": {
+ "x": 20,
+ "y": 20
+ },
+ "path": [
+ {
+ "x": -60,
+ "y": -60
+ },
+ {
+ "x": 60,
+ "y": -60
+ },
+ {
+ "x": 0,
+ "y": 60
+ }
+ ],
+ "enabled": true
+ }
+ }
+ ],
+ "visible": true
+ }
+ ]
+}
diff --git a/fixtures/scenes/mat-lit-shadow-outline.textures.json b/fixtures/scenes/mat-lit-shadow-outline.textures.json
new file mode 100644
index 000000000..0967ef424
--- /dev/null
+++ b/fixtures/scenes/mat-lit-shadow-outline.textures.json
@@ -0,0 +1 @@
+{}
diff --git a/sdk/etc/index.api.md b/sdk/etc/index.api.md
index b13dc583c..0b0ce9231 100644
--- a/sdk/etc/index.api.md
+++ b/sdk/etc/index.api.md
@@ -5,7 +5,7 @@ Symbols: 114 public · 94 beta · 1681 experimental · 3 deprecated
## ABI_LAYOUT_HASH — const @experimental
```
-"73a4e6e098cc7a9b"
+"f8b3b5501ea0afe4"
```
## ANCHOR_AXES — const @experimental
@@ -7837,6 +7837,7 @@ BuiltinComponentDef<ShadowCaster2DData>
## ShadowCaster2DData — interface @experimental
```
enabled: boolean
+path: Vec2[]
size: Vec2
```
diff --git a/sdk/etc/index.native.api.md b/sdk/etc/index.native.api.md
index 96cbe1f05..d78faf557 100644
--- a/sdk/etc/index.native.api.md
+++ b/sdk/etc/index.native.api.md
@@ -5,7 +5,7 @@ Symbols: 114 public · 99 beta · 1700 experimental · 3 deprecated
## ABI_LAYOUT_HASH — const @experimental
```
-"73a4e6e098cc7a9b"
+"f8b3b5501ea0afe4"
```
## ANCHOR_AXES — const @experimental
@@ -8030,6 +8030,7 @@ BuiltinComponentDef<ShadowCaster2DData>
## ShadowCaster2DData — interface @experimental
```
enabled: boolean
+path: Vec2[]
size: Vec2
```
diff --git a/sdk/etc/index.node.api.md b/sdk/etc/index.node.api.md
index 038fd0524..139bf3663 100644
--- a/sdk/etc/index.node.api.md
+++ b/sdk/etc/index.node.api.md
@@ -7832,6 +7832,7 @@ BuiltinComponentDef<ShadowCaster2DData>
## ShadowCaster2DData — interface @experimental
```
enabled: boolean
+path: Vec2[]
size: Vec2
```
diff --git a/sdk/etc/minigame.api.md b/sdk/etc/minigame.api.md
index 010529106..db9b2a077 100644
--- a/sdk/etc/minigame.api.md
+++ b/sdk/etc/minigame.api.md
@@ -8078,6 +8078,7 @@ BuiltinComponentDef<ShadowCaster2DData>
## ShadowCaster2DData — interface @experimental
```
enabled: boolean
+path: Vec2[]
size: Vec2
```
diff --git a/sdk/etc/wechat.api.md b/sdk/etc/wechat.api.md
index 387abda20..3f1c98bb0 100644
--- a/sdk/etc/wechat.api.md
+++ b/sdk/etc/wechat.api.md
@@ -7839,6 +7839,7 @@ BuiltinComponentDef<ShadowCaster2DData>
## ShadowCaster2DData — interface @experimental
```
enabled: boolean
+path: Vec2[]
size: Vec2
```
diff --git a/sdk/src/ecs/bridge/nativeRegistry.ts b/sdk/src/ecs/bridge/nativeRegistry.ts
index 6183b3844..e39da7c74 100644
--- a/sdk/src/ecs/bridge/nativeRegistry.ts
+++ b/sdk/src/ecs/bridge/nativeRegistry.ts
@@ -25,6 +25,12 @@ import { convertForWasm, convertFromWasm } from './BuiltinBridge';
type BufferFn = (entity: number) => ArrayBuffer | null | undefined;
type HasFn = (entity: number) => boolean;
type RemoveFn = (entity: number) => void;
+/** The generated pair a list field crosses by — see COMPONENT_META.listFields. */
+interface ListFieldBinding {
+ field: string;
+ get: (entity: number) => unknown;
+ set: (entity: number, value: unknown) => void;
+}
function views(buf: ArrayBuffer): [Float32Array, Uint32Array, Uint8Array] {
// Float32Array/Uint32Array require a byteLength that is a multiple of 4, but a
@@ -162,6 +168,18 @@ export function createNativeRegistry(
continue;
}
const colorFields = (COMPONENT_META[cppName]?.colorFields ?? []) as readonly string[];
+ // A list field's storage is a pointer, so it is absent from the buffer the
+ // accessors write through: it crosses as its own generated pair, and a host
+ // without them keeps none of the field rather than half of it.
+ const listFields = ((COMPONENT_META[cppName]?.listFields ?? []) as readonly string[])
+ .map((field) => ({
+ field,
+ get: scope[`es_${cppName}_${field}_get`] as ((e: Entity) => unknown) | undefined,
+ set: scope[`es_${cppName}_${field}_set`] as
+ ((e: Entity, v: unknown) => void) | undefined,
+ }))
+ .filter((l): l is ListFieldBinding =>
+ typeof l.get === 'function' && typeof l.set === 'function');
// add: emplace (the buffer binding getOrEmplaces) + write every field. The
// SDK hands embind-shape data ({x,y,z,w} colors); ptrAccessors want
@@ -172,6 +190,7 @@ export function createNativeRegistry(
const ptrData = colorFields.length ? convertFromWasm(data, colorFields) : data;
const [f32, u32, u8] = views(buf);
accessor.write(f32, u32, u8, 0, ptrData);
+ for (const l of listFields) l.set(entity, (data as Record<string, unknown>)[l.field] ?? []);
};
// get: read into a fresh object (embind returns fresh, so callers may
@@ -186,6 +205,7 @@ export function createNativeRegistry(
accessor.fill(f32, u32, u8, 0, out);
}
}
+ for (const l of listFields) out[l.field] = l.get(entity);
return colorFields.length ? convertForWasm(out, colorFields) : out;
};
diff --git a/sdk/src/ecs/bridge/ptrAccessors.generated.ts b/sdk/src/ecs/bridge/ptrAccessors.generated.ts
index a6365f47f..67a73bc51 100644
--- a/sdk/src/ecs/bridge/ptrAccessors.generated.ts
+++ b/sdk/src/ecs/bridge/ptrAccessors.generated.ts
@@ -1443,7 +1443,7 @@ export function fillShadowCaster2D(
ptr: number, out: ShadowCaster2DPtrData,
): void {
const size_ = out.size; size_.x = f32[ptr >> 2]; size_.y = f32[(ptr >> 2) + 1];
- out.enabled = u8[ptr + 8] !== 0;
+ out.enabled = u8[ptr + 20] !== 0;
}
export function writeShadowCaster2D(
@@ -1451,7 +1451,7 @@ export function writeShadowCaster2D(
ptr: number, data: ShadowCaster2DPtrData,
): void {
f32[ptr >> 2] = data.size.x; f32[(ptr >> 2) + 1] = data.size.y;
- u8[ptr + 8] = data.enabled ? 1 : 0;
+ u8[ptr + 20] = data.enabled ? 1 : 0;
}
export function createShadowCaster2DData(): ShadowCaster2DPtrData {
diff --git a/sdk/src/ecs/component.generated.ts b/sdk/src/ecs/component.generated.ts
index 58ec24333..0e9042051 100644
--- a/sdk/src/ecs/component.generated.ts
+++ b/sdk/src/ecs/component.generated.ts
@@ -15,7 +15,7 @@ import type { AlignContent, AlignItems, AlignSelf, BodyType, CanvasScaleMode, Cl
* getAbiLayoutHash(); BuiltinBridge.connect() compares them and refuses to
* run on mismatch, because mismatched offsets read the wrong heap bytes.
*/
-export const ABI_LAYOUT_HASH = '73a4e6e098cc7a9b';
+export const ABI_LAYOUT_HASH = 'f8b3b5501ea0afe4';
/**
* One asset-valued field of a component: which field, and what kind of
@@ -67,6 +67,14 @@ export interface ComponentMetaEntry {
assetFields: AssetFieldMeta[];
skeletal?: SkeletalFieldMeta;
entityFields: string[];
+ /**
+ * Fields whose value is a LIST, which has no place in the zero-copy
+ * component buffer a native host writes through — its storage is a
+ * pointer. Each crosses as its own generated
+ * `es_<Component>_<field>_get/_set` pair. Entity lists predate this
+ * and keep the hand-written pair the registry wires them by.
+ */
+ listFields?: string[];
colorFields: string[];
animatableFields: string[];
/**
@@ -760,15 +768,17 @@ export const COMPONENT_META: Record<string, ComponentMetaEntry> = {
ShadowCaster2D: {
defaults: {
size: { x: 32, y: 32 },
+ path: [],
enabled: true,
},
renderableField: 'enabled',
assetFields: [],
entityFields: [],
+ listFields: ['path'],
colorFields: [],
animatableFields: ['size.x', 'size.y'],
fields: {
- size: { min: 0, tooltip: "Occluder box size in world units (centred on the entity, turning with it)." },
+ size: { min: 0, tooltip: "Occluder box size in world units (centred on the entity, turning with it). Unused when the caster has an outline." },
},
},
ShapeRenderer: {
@@ -1491,6 +1501,7 @@ export interface SegmentCollider2DData {
export interface ShadowCaster2DData {
size: Vec2;
+ path: Vec2[];
enabled: boolean;
}
diff --git a/sdk/src/wasm/ptrLayouts.generated.ts b/sdk/src/wasm/ptrLayouts.generated.ts
index ec73c3403..cde271df0 100644
--- a/sdk/src/wasm/ptrLayouts.generated.ts
+++ b/sdk/src/wasm/ptrLayouts.generated.ts
@@ -387,7 +387,7 @@ export const PTR_LAYOUTS: Record<string, PtrLayout> = {
ptrFn: 'getShadowCaster2DPtr',
fields: [
{ name: 'size', type: 'vec2', offset: 0 },
- { name: 'enabled', type: 'bool', offset: 8 },
+ { name: 'enabled', type: 'bool', offset: 20 },
],
},
ShapeRenderer: {
diff --git a/sdk/src/wasm/wasm.generated.ts b/sdk/src/wasm/wasm.generated.ts
index 6d982ccb1..7a4296d4f 100644
--- a/sdk/src/wasm/wasm.generated.ts
+++ b/sdk/src/wasm/wasm.generated.ts
@@ -693,6 +693,7 @@ export interface SegmentCollider2D {
export interface ShadowCaster2D {
size: Vec2;
+ path: Vec2[];
enabled: boolean;
}
diff --git a/sdk/tests/__snapshots__/component-fieldmeta-golden.test.ts.snap b/sdk/tests/__snapshots__/component-fieldmeta-golden.test.ts.snap
index a79d26fe7..14701cfd4 100644
--- a/sdk/tests/__snapshots__/component-fieldmeta-golden.test.ts.snap
+++ b/sdk/tests/__snapshots__/component-fieldmeta-golden.test.ts.snap
@@ -871,7 +871,7 @@ exports[`builtin FieldMeta (RC9-1 equivalence gate) > matches the golden snapsho
"ShadowCaster2D": {
"size": {
"min": 0,
- "tooltip": "Occluder box size in world units (centred on the entity, turning with it).",
+ "tooltip": "Occluder box size in world units (centred on the entity, turning with it). Unused when the caster has an outline.",
},
},
"ShapeRenderer": {
diff --git a/sdk/tests/native-registry.test.ts b/sdk/tests/native-registry.test.ts
index 6bd3a011a..80ba47f8f 100644
--- a/sdk/tests/native-registry.test.ts
+++ b/sdk/tests/native-registry.test.ts
@@ -178,6 +178,34 @@ describe('createNativeRegistry', () => {
expect((reg.getMeshSkin(4) as { joints: number[] }).joints).toEqual([]);
});
+ it('a list field crosses by its own pair, beside the buffer the rest goes through', () => {
+ // ShadowCaster2D is the first component with BOTH a POD field the accessors
+ // write into the zero-copy buffer and one whose storage is a pointer. Skip
+ // the pair and a native game's polygon walls silently become boxes.
+ const paths = new Map<number, unknown>();
+ const buffers = new Map<number, ArrayBuffer>();
+ const scope: Record<string, unknown> = {
+ es_ShadowCaster2D_buffer: (e: number) => {
+ let b = buffers.get(e);
+ if (!b) { b = new ArrayBuffer(64); buffers.set(e, b); }
+ return b;
+ },
+ es_ShadowCaster2D_has: (e: number) => buffers.has(e),
+ es_ShadowCaster2D_remove: (e: number) => { buffers.delete(e); paths.delete(e); },
+ es_ShadowCaster2D_path_set: (e: number, v: unknown) => { paths.set(e, v); },
+ es_ShadowCaster2D_path_get: (e: number) => paths.get(e) ?? [],
+ };
+ const reg = createNativeRegistry(scope) as unknown as Record<string, Function>;
+ const outline = [{ x: -1, y: -1 }, { x: 1, y: -1 }, { x: 0, y: 2 }];
+ reg.addShadowCaster2D(3, { size: { x: 20, y: 20 }, path: outline, enabled: true });
+ const got = reg.getShadowCaster2D(3) as { size: { x: number }; path: unknown };
+ expect(got.path).toEqual(outline);
+ expect(got.size.x).toBe(20);
+ // A caster authored with no outline says so, rather than keeping the last one.
+ reg.addShadowCaster2D(3, { size: { x: 20, y: 20 }, enabled: true });
+ expect((reg.getShadowCaster2D(3) as { path: unknown }).path).toEqual([]);
+ });
+
it('getChildren.entities is iterable (for...of) as well as vector-shaped', () => {
// The timeline/animator child-path resolver walks children with a for-of and
// types the field `Entity[]`; the VectorEntity shim must answer Symbol.iterator
diff --git a/src/esengine/bindings/EditorAPI.generated.cpp b/src/esengine/bindings/EditorAPI.generated.cpp
index 9bb1cd4d0..7f3d6be9d 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 a9261da2a8edb96e
+ * @schema_hash 62b2c5d11cb4451c
*/
-#define ES_EDITOR_API_SCHEMA_HASH "a9261da2a8edb96e"
+#define ES_EDITOR_API_SCHEMA_HASH "62b2c5d11cb4451c"
#include <emscripten/bind.h>
#include <string>
diff --git a/src/esengine/bindings/WebBindings.generated.cpp b/src/esengine/bindings/WebBindings.generated.cpp
index 2b05f39cd..cb66b040c 100644
--- a/src/esengine/bindings/WebBindings.generated.cpp
+++ b/src/esengine/bindings/WebBindings.generated.cpp
@@ -1021,6 +1021,35 @@ RigidBody3DJS rigidbody3dToJS(const esengine::ecs::RigidBody3D& c) {
return js;
}
+struct ShadowCaster2DJS {
+ glm::vec2 size;
+ emscripten::val path = emscripten::val::array();
+ bool enabled;
+};
+
+void shadowcaster2dApplyJS(esengine::ecs::ShadowCaster2D& c, const ShadowCaster2DJS& js) {
+ c.size = js.size;
+ { const size_t n = js.path["length"].as<size_t>();
+ c.path.clear(); c.path.reserve(n);
+ for (size_t i = 0; i < n; ++i) c.path.push_back(js.path[i].as<glm::vec2>()); }
+ c.enabled = js.enabled;
+}
+
+esengine::ecs::ShadowCaster2D shadowcaster2dFromJS(const ShadowCaster2DJS& js) {
+ esengine::ecs::ShadowCaster2D c;
+ shadowcaster2dApplyJS(c, js);
+ return c;
+}
+
+ShadowCaster2DJS shadowcaster2dToJS(const esengine::ecs::ShadowCaster2D& c) {
+ ShadowCaster2DJS js;
+ js.size = c.size;
+ js.path = emscripten::val::array();
+ for (size_t i = 0; i < c.path.size(); ++i) js.path.set(i, emscripten::val(c.path[i]));
+ js.enabled = c.enabled;
+ return js;
+}
+
struct SpriteJS {
u32 texture;
glm::vec4 color;
@@ -1708,9 +1737,10 @@ EMSCRIPTEN_BINDINGS(esengine_components) {
.field("categoryBits", &esengine::ecs::SegmentCollider2D::categoryBits)
.field("maskBits", &esengine::ecs::SegmentCollider2D::maskBits);
- value_object<esengine::ecs::ShadowCaster2D>("ShadowCaster2D")
- .field("size", &esengine::ecs::ShadowCaster2D::size)
- .field("enabled", &esengine::ecs::ShadowCaster2D::enabled);
+ value_object<ShadowCaster2DJS>("ShadowCaster2D")
+ .field("size", &ShadowCaster2DJS::size)
+ .field("path", &ShadowCaster2DJS::path)
+ .field("enabled", &ShadowCaster2DJS::enabled);
value_object<esengine::ecs::ShapeRenderer>("ShapeRenderer")
.field("shapeType", &esengine::ecs::ShapeRenderer::shapeType)
@@ -2488,16 +2518,19 @@ EMSCRIPTEN_BINDINGS(esengine_registry) {
.function("hasShadowCaster2D", optional_override([](Registry& r, u32 e) {
return r.has<esengine::ecs::ShadowCaster2D>(static_cast<Entity>(e));
}))
- .function("getShadowCaster2D", optional_override([](Registry& r, u32 e) -> esengine::ecs::ShadowCaster2D& {
+ .function("getShadowCaster2D", optional_override([](Registry& r, u32 e) {
auto entity = static_cast<Entity>(e);
- static esengine::ecs::ShadowCaster2D s_dummy{};
- if (!r.valid(entity) || !r.has<esengine::ecs::ShadowCaster2D>(entity)) return s_dummy;
- return r.get<esengine::ecs::ShadowCaster2D>(entity);
- }), allow_raw_pointers())
- .function("addShadowCaster2D", optional_override([](Registry& r, u32 e, const esengine::ecs::ShadowCaster2D& c) {
+ if (!r.valid(entity) || !r.has<esengine::ecs::ShadowCaster2D>(entity)) return ShadowCaster2DJS{};
+ return shadowcaster2dToJS(r.get<esengine::ecs::ShadowCaster2D>(entity));
+ }))
+ .function("addShadowCaster2D", optional_override([](Registry& r, u32 e, const ShadowCaster2DJS& js) {
auto entity = static_cast<Entity>(e);
if (!r.valid(entity)) return;
- r.emplaceOrReplace<esengine::ecs::ShadowCaster2D>(entity, c);
+ if (auto* existing = r.tryGet<esengine::ecs::ShadowCaster2D>(entity)) {
+ shadowcaster2dApplyJS(*existing, js);
+ return;
+ }
+ r.emplaceOrReplace<esengine::ecs::ShadowCaster2D>(entity, shadowcaster2dFromJS(js));
}))
.function("removeShadowCaster2D", optional_override([](Registry& r, u32 e) {
auto entity = static_cast<Entity>(e);
@@ -3157,7 +3190,7 @@ static_assert(offsetof(esengine::ecs::SegmentCollider2D, enabled) == 29, "ABI of
static_assert(offsetof(esengine::ecs::SegmentCollider2D, categoryBits) == 32, "ABI offset drift: esengine::ecs::SegmentCollider2D.categoryBits (EHT expected 32)");
static_assert(offsetof(esengine::ecs::SegmentCollider2D, maskBits) == 36, "ABI offset drift: esengine::ecs::SegmentCollider2D.maskBits (EHT expected 36)");
static_assert(offsetof(esengine::ecs::ShadowCaster2D, size) == 0, "ABI offset drift: esengine::ecs::ShadowCaster2D.size (EHT expected 0)");
-static_assert(offsetof(esengine::ecs::ShadowCaster2D, enabled) == 8, "ABI offset drift: esengine::ecs::ShadowCaster2D.enabled (EHT expected 8)");
+static_assert(offsetof(esengine::ecs::ShadowCaster2D, enabled) == 20, "ABI offset drift: esengine::ecs::ShadowCaster2D.enabled (EHT expected 20)");
static_assert(offsetof(esengine::ecs::ShapeRenderer, shapeType) == 0, "ABI offset drift: esengine::ecs::ShapeRenderer.shapeType (EHT expected 0)");
static_assert(offsetof(esengine::ecs::ShapeRenderer, color) == 4, "ABI offset drift: esengine::ecs::ShapeRenderer.color (EHT expected 4)");
static_assert(offsetof(esengine::ecs::ShapeRenderer, size) == 20, "ABI offset drift: esengine::ecs::ShapeRenderer.size (EHT expected 20)");
@@ -3294,7 +3327,7 @@ static_assert(offsetof(esengine::ecs::Velocity, angular) == 12, "ABI offset drif
// ABI Hash -- runtime handshake against the SDK bundle
// =============================================================================
-static const char* kEsAbiLayoutHash = "73a4e6e098cc7a9b";
+static const char* kEsAbiLayoutHash = "f8b3b5501ea0afe4";
std::string esengineGetAbiLayoutHash() {
return std::string(kEsAbiLayoutHash);
diff --git a/src/esengine/ecs/components/ShadowCaster2D.hpp b/src/esengine/ecs/components/ShadowCaster2D.hpp
index 8b8855647..dc8d83f38 100644
--- a/src/esengine/ecs/components/ShadowCaster2D.hpp
+++ b/src/esengine/ecs/components/ShadowCaster2D.hpp
@@ -3,8 +3,9 @@
/**
* @file ShadowCaster2D.hpp
* @brief Marks an entity as a 2D shadow occluder for the Lit lighting path.
- * @details The render collect path turns each enabled caster into the four world-space edges
- * of a box placed by its Transform, and the 2D shadow pass DRAWS what those edges
+ * @details The render collect path turns each enabled caster into a world-space ring — its
+ * own outline, or the four edges of a box — placed by its Transform, and the 2D
+ * shadow pass DRAWS what that ring
* hide from each casting light into a screen-space mask. A Lit fragment then reads
* its light's channel of that mask. Drawn rather than solved per pixel, which is what
* lets a scene hold as many occluders as it has walls.
@@ -18,6 +19,8 @@
#include "../../core/Reflection.hpp"
#include "../../math/Math.hpp"
+#include <vector>
+
namespace esengine::ecs {
/**
@@ -26,10 +29,21 @@ namespace esengine::ecs {
*/
ES_COMPONENT(renderable=enabled)
struct ShadowCaster2D {
- /** @brief Occluder box size in world units (full width/height; centered on the Transform). */
- ES_PROPERTY(animatable, min=0, tooltip="Occluder box size in world units (centred on the entity, turning with it).")
+ /** @brief Occluder box size in world units (full width/height; centered on the Transform).
+ * Ignored by a caster that carries a @ref path. */
+ ES_PROPERTY(animatable, min=0, tooltip="Occluder box size in world units (centred on the entity, turning with it). Unused when the caster has an outline.")
glm::vec2 size{32.0f, 32.0f};
+ /**
+ * @brief The occluder's outline in local units, or empty for @ref size's box.
+ * @details Three points or more, in order round the shape; where it sits and how
+ * it is turned is the Transform's, exactly as the box's is. Traced from
+ * the sprite's own alpha in the editor, which is where a shape that
+ * matches the artwork comes from.
+ */
+ ES_PROPERTY()
+ std::vector<glm::vec2> path;
+
/** @brief Disabled casters are skipped during collection. */
ES_PROPERTY()
bool enabled{true};
diff --git a/src/esengine/renderer/frame/RenderFrameShadow2D.cpp b/src/esengine/renderer/frame/RenderFrameShadow2D.cpp
index 9d3d5adcb..c2f561196 100644
--- a/src/esengine/renderer/frame/RenderFrameShadow2D.cpp
+++ b/src/esengine/renderer/frame/RenderFrameShadow2D.cpp
@@ -55,22 +55,31 @@ void RenderFrame::collectShadow2D(ecs::Registry& registry) {
auto& transform = casters.get<ecs::Transform>(entity);
transform.ensureDecomposed();
const glm::vec3 p = transform.worldPosition;
- const f32 hx = caster.size.x * 0.5f;
- const f32 hy = caster.size.y * 0.5f;
- if (hx <= 0.0f || hy <= 0.0f) continue;
- // The box turns with the entity, the way a collider on it does — a wall laid
+ // The shape turns with the entity, the way a collider on it does — a wall laid
// at an angle casts the shadow of a wall at that angle. Its SIZE is its own,
// also like a collider's: scaling the entity does not resize the occluder.
const glm::vec2 turn = flatTurnZ(transform.worldRotation);
- const auto corner = [&](f32 sx, f32 sy) {
- return glm::vec2{p.x + sx * hx * turn.x - sy * hy * turn.y,
- p.y + sx * hx * turn.y + sy * hy * turn.x};
+ const auto place = [&](f32 lx, f32 ly) {
+ return glm::vec2{p.x + lx * turn.x - ly * turn.y, p.y + lx * turn.y + ly * turn.x};
};
+ // An outline of its own, or the box. Two points enclose nothing, so a path
+ // short of a triangle is not a shape and the box stands.
+ if (caster.path.size() >= 3) {
+ shadow_rings_2d_.push_back({static_cast<u32>(shadow_points_2d_.size()),
+ static_cast<u32>(caster.path.size())});
+ for (const glm::vec2& local : caster.path) {
+ shadow_points_2d_.push_back(place(local.x, local.y));
+ }
+ continue;
+ }
+ const f32 hx = caster.size.x * 0.5f;
+ const f32 hy = caster.size.y * 0.5f;
+ if (hx <= 0.0f || hy <= 0.0f) continue;
shadow_rings_2d_.push_back({static_cast<u32>(shadow_points_2d_.size()), 4});
- shadow_points_2d_.push_back(corner(-1.0f, -1.0f));
- shadow_points_2d_.push_back(corner(1.0f, -1.0f));
- shadow_points_2d_.push_back(corner(1.0f, 1.0f));
- shadow_points_2d_.push_back(corner(-1.0f, 1.0f));
+ shadow_points_2d_.push_back(place(-hx, -hy));
+ shadow_points_2d_.push_back(place(hx, -hy));
+ shadow_points_2d_.push_back(place(hx, hy));
+ shadow_points_2d_.push_back(place(-hx, hy));
}
if (shadow_rings_2d_.empty()) return;
diff --git a/tests/aot/generated/conformance/handshake.h b/tests/aot/generated/conformance/handshake.h
index 096a1f704..695172dde 100644
--- a/tests/aot/generated/conformance/handshake.h
+++ b/tests/aot/generated/conformance/handshake.h
@@ -1,5 +1,5 @@
/* GENERATED by sdk/tests/aot-conformance.test.ts — do not edit. */
/* The contract half of the handshake. The width half is the harness. */
-#define ES_CONF_EXPECTED_CONTRACT_HASH 0xde68c21baa4ee1b4ULL
+#define ES_CONF_EXPECTED_CONTRACT_HASH 0x2d9ebb9002fcf15aULL
/* And which BUILD the artifact beside this one is. */
#define ES_CONF_EXPECTED_MODULE_CONTRACT 0xc3d0e057d5701a2eULL
diff --git a/tests/aot/generated/conformance/systems_decl.c b/tests/aot/generated/conformance/systems_decl.c
index 8d0f958bc..20c96d870 100644
--- a/tests/aot/generated/conformance/systems_decl.c
+++ b/tests/aot/generated/conformance/systems_decl.c
@@ -10,7 +10,7 @@
answer, it is a read of a different field. The address width belongs
to the MACHINE, so it mixes in here rather than in the compiler and a
32-bit artifact cannot load into a 64-bit host. */
-#define ES_ABI_ENGINE_DIGEST 0xde68c21baa4ee1b4ULL
+#define ES_ABI_ENGINE_DIGEST 0x2d9ebb9002fcf15aULL
ES_EXPORT const uint64_t es_abi_hash =
ES_ABI_ENGINE_DIGEST ^ (0x9e3779b97f4a7c15ULL * (uint64_t)sizeof(es_addr_t));
diff --git a/tools/eht/generators/embind.py b/tools/eht/generators/embind.py
index dbcdf3dcb..2339ba021 100644
--- a/tools/eht/generators/embind.py
+++ b/tools/eht/generators/embind.py
@@ -216,10 +216,10 @@ class EmbindGenerator:
lines.append(f' c.{prop.name}.reserve(js.{prop.name}.size());')
lines.append(f' for (auto v : js.{prop.name}) c.{prop.name}.push_back(Entity(v));')
elif self.types.is_struct_vector(t):
- elem = self.types.vector_elem(t)
+ elem = self.types.vector_elem_cpp(t)
lines.append(f' {{ const size_t n = js.{prop.name}["length"].as<size_t>();')
lines.append(f' c.{prop.name}.clear(); c.{prop.name}.reserve(n);')
- lines.append(f' for (size_t i = 0; i < n; ++i) c.{prop.name}.push_back(js.{prop.name}[i].as<esengine::{elem}>()); }}')
+ lines.append(f' for (size_t i = 0; i < n; ++i) c.{prop.name}.push_back(js.{prop.name}[i].as<{elem}>()); }}')
else:
lines.append(f' c.{prop.name} = js.{prop.name};')
lines.append('}')
diff --git a/tools/eht/generators/metadata.py b/tools/eht/generators/metadata.py
index 35d906577..28067aa2b 100644
--- a/tools/eht/generators/metadata.py
+++ b/tools/eht/generators/metadata.py
@@ -269,7 +269,7 @@ class MetadataGenerator:
if self.types.is_entity_vector(t):
return 'Entity[]'
if self.types.is_struct_vector(t):
- return f'{self.types.vector_elem(t)}[]'
+ return f'{self.types.vector_elem_ts(t)}[]'
if self.types.is_handle(t):
return 'number'
if 'entity_ref' in prop.annotations or self.types.is_entity(t):
@@ -423,6 +423,14 @@ class MetadataGenerator:
' assetFields: AssetFieldMeta[];',
' skeletal?: SkeletalFieldMeta;',
' entityFields: string[];',
+ ' /**',
+ ' * Fields whose value is a LIST, which has no place in the zero-copy',
+ ' * component buffer a native host writes through — its storage is a',
+ ' * pointer. Each crosses as its own generated',
+ ' * `es_<Component>_<field>_get/_set` pair. Entity lists predate this',
+ ' * and keep the hand-written pair the registry wires them by.',
+ ' */',
+ ' listFields?: string[];',
' colorFields: string[];',
' animatableFields: string[];',
' /**',
@@ -499,6 +507,12 @@ class MetadataGenerator:
else:
lines.append(' entityFields: [],')
+ list_fields = [p.name for p in comp.properties
+ if self.types.is_struct_vector(p.cpp_type)]
+ if list_fields:
+ parts = ', '.join(f"'{f}'" for f in list_fields)
+ lines.append(f' listFields: [{parts}],')
+
if color_fields:
parts = ', '.join(f"'{f}'" for f in color_fields)
lines.append(f' colorFields: [{parts}],')
diff --git a/tools/eht/generators/native_bindings.py b/tools/eht/generators/native_bindings.py
index b94019c19..1e7086db5 100644
--- a/tools/eht/generators/native_bindings.py
+++ b/tools/eht/generators/native_bindings.py
@@ -55,8 +55,72 @@ class NativeBindingsGenerator:
# id returned by a resource binding (es_createTexture); reconstruct it.
return (f' {{ double _v; if (esn_getnum(ctx, o, "{n}", &_v)) '
f'c.{n} = decltype(c.{n})(static_cast<esengine::u32>(static_cast<long long>(_v))); }}')
+ if self.types.is_struct_vector(ct):
+ return f' // {n}: a list, carried by its own _set/_get pair'
return f' // skip {n}: {t} (entity / vector / struct — needs a bespoke binding)'
+
+ def _list_fields(self, comp):
+ """(property, [member names]) for every field carried as a JS array.
+
+ A variable-length field has no place in the zero-copy component buffer the
+ ptr accessors write through — its storage is a pointer — so it crosses as
+ its own pair of bindings. Entity lists predate this and keep the
+ hand-written pair the registry wires them by (MeshSkin, Children).
+ """
+ out = []
+ for prop in comp.properties:
+ t = self.types.clean_type(prop.cpp_type)
+ if not self.types.is_struct_vector(t):
+ continue
+ elem = self.types.vector_elem(t)
+ members = ([m for m, _ in self.types.CUSTOM_STRUCTS[elem]]
+ if elem in self.types.CUSTOM_STRUCTS
+ else ['x', 'y', 'z', 'w'][:_GLM_ARITY[elem]])
+ out.append((prop, members))
+ return out
+
+ def _list_binding(self, comp, full, prop, members) -> List[str]:
+ get_name = f'es_{comp.name}_{prop.name}_get'
+ set_name = f'es_{comp.name}_{prop.name}_set'
+ out = [f'static JSValue {get_name}(JSContext* ctx, JSValueConst, int argc, JSValueConst* argv) {{',
+ ' JSValue arr = JS_NewArray(ctx);',
+ ' if (argc < 1) return arr;',
+ f' const auto* c = esn_reg().tryGet<{full}>(esn_entity(ctx, argv[0]));',
+ ' if (!c) return arr;',
+ ' uint32_t i = 0;',
+ f' for (const auto& v : c->{prop.name}) {{',
+ ' JSValue o = JS_NewObject(ctx);']
+ for m in members:
+ out.append(f' JS_SetPropertyStr(ctx, o, "{m}", JS_NewFloat64(ctx, v.{m}));')
+ out += [' JS_SetPropertyUint32(ctx, arr, i++, o);',
+ ' }',
+ ' return arr;',
+ '}',
+ f'static JSValue {set_name}(JSContext* ctx, JSValueConst, int argc, JSValueConst* argv) {{',
+ ' if (argc < 2) return JS_UNDEFINED;',
+ f' auto& c = esn_reg().getOrEmplace<{full}>(esn_entity(ctx, argv[0]));',
+ f' c.{prop.name}.clear();',
+ ' uint32_t len = 0;',
+ ' JSValue lenv = JS_GetPropertyStr(ctx, argv[1], "length");',
+ ' JS_ToUint32(ctx, &len, lenv);',
+ ' JS_FreeValue(ctx, lenv);',
+ f' c.{prop.name}.reserve(len);',
+ ' for (uint32_t i = 0; i < len; ++i) {',
+ ' JSValue e = JS_GetPropertyUint32(ctx, argv[1], i);',
+ f' decltype(c.{prop.name})::value_type v{{}};',
+ ' double n = 0;']
+ for m in members:
+ out += [f' {{ JSValue f = JS_GetPropertyStr(ctx, e, "{m}");',
+ f' if (JS_ToFloat64(ctx, &n, f) == 0) v.{m} = static_cast<decltype(v.{m})>(n);',
+ ' JS_FreeValue(ctx, f); }']
+ out += [f' c.{prop.name}.push_back(v);',
+ ' JS_FreeValue(ctx, e);',
+ ' }',
+ ' return JS_UNDEFINED;',
+ '}']
+ return out
+
def _component(self, comp: Component) -> List[str]:
full = f'{comp.namespace}::{comp.name}' if comp.namespace else comp.name
# Per-field setter: es_set_<Component>(entityId, obj).
@@ -97,6 +161,8 @@ class NativeBindingsGenerator:
out.append(f' if (esn_reg().has<{full}>(e)) esn_reg().remove<{full}>(e);')
out.append(' return JS_UNDEFINED;')
out.append('}')
+ for prop, members in self._list_fields(comp):
+ out.extend(self._list_binding(comp, full, prop, members))
out.append('')
return out
@@ -137,6 +203,11 @@ class NativeBindingsGenerator:
f'JS_NewCFunction(ctx, {has}, "{has}", 1));')
lines.append(f' JS_SetPropertyStr(ctx, global, "{remove}", '
f'JS_NewCFunction(ctx, {remove}, "{remove}", 1));')
+ for prop, _members in self._list_fields(comp):
+ for fn, arity in ((f'es_{comp.name}_{prop.name}_get', 1),
+ (f'es_{comp.name}_{prop.name}_set', 2)):
+ lines.append(f' JS_SetPropertyStr(ctx, global, "{fn}", '
+ f'JS_NewCFunction(ctx, {fn}, "{fn}", {arity}));')
lines.append('}')
lines.append('')
return '\n'.join(lines)
diff --git a/tools/eht/test_validation.py b/tools/eht/test_validation.py
index 3b1cb128c..1c0d99c2f 100644
--- a/tools/eht/test_validation.py
+++ b/tools/eht/test_validation.py
@@ -251,7 +251,9 @@ carries('a primitive crosses', 'ES_PROPERTY()\n float x = 0.0f;', uncarried=0
carries('glm::vec2 crosses', 'ES_PROPERTY()\n glm::vec2 size;', uncarried=0)
carries('a handle crosses', 'ES_PROPERTY(asset=texture)\n resource::TextureHandle tex;', uncarried=0)
carries('std::vector<Entity> crosses', 'ES_PROPERTY()\n std::vector<Entity> entities;', uncarried=0)
-carries('a point list does NOT', 'ES_PROPERTY()\n std::vector<glm::vec2> path;', uncarried=1)
+carries('a point list crosses', 'ES_PROPERTY()\n std::vector<glm::vec2> path;', uncarried=0)
+carries('a list of an unknown element does NOT',
+ 'ES_PROPERTY()\n std::vector<SomeThing> things;', uncarried=1)
carries('an unknown struct does NOT', 'ES_PROPERTY()\n SomeThing thing;', uncarried=1)
if _failures:
diff --git a/tools/eht/type_system.py b/tools/eht/type_system.py
index c349ffd34..2a57d5353 100644
--- a/tools/eht/type_system.py
+++ b/tools/eht/type_system.py
@@ -84,20 +84,27 @@ class TypeSystem:
return m.group(1).strip() if m else None
def is_struct_vector(self, cpp_type: str) -> bool:
- """`std::vector<S>` where S is a registered CUSTOM_STRUCT (REARCH_GUI F5).
- Marshalled via embind register_vector<S> + value_object<S>; never
- pointer-accessed."""
+ """`std::vector<S>` where S is an element the boundary converts one at a
+ time — a registered CUSTOM_STRUCT, or a glm vector, both of which embind
+ knows as value_objects. Carried as a JS array; never pointer-accessed.
+ """
+ elem = self.vector_elem(cpp_type)
+ return elem is not None and (elem in self.CUSTOM_STRUCTS or elem in self.GLM_TYPES)
+
+ def vector_elem_cpp(self, cpp_type: str) -> str:
+ """The element type as generated C++ must SPELL it: a custom struct lives in
+ esengine::, a glm one names its own namespace."""
elem = self.vector_elem(cpp_type)
- return elem is not None and elem in self.CUSTOM_STRUCTS
+ return elem if elem in self.GLM_TYPES else f'esengine::{elem}'
+
+ def vector_elem_ts(self, cpp_type: str) -> str:
+ """The element's TypeScript name — `Vec2`, not `glm::vec2`."""
+ elem = self.vector_elem(cpp_type)
+ return self.CPP_TO_TS.get(elem, elem)
def is_any_vector(self, cpp_type: str) -> bool:
return self.is_vector(cpp_type) or self.is_struct_vector(cpp_type)
- def struct_vector_js_name(self, cpp_type: str) -> str:
- """embind register_vector binding name for a struct-vector, e.g.
- std::vector<Foo> -> VectorFoo."""
- return f'Vector{self.vector_elem(cpp_type)}'
-
def is_skip(self, cpp_type: str) -> bool:
t = self.clean_type(cpp_type)
return t in self.SKIP_TYPES
@@ -183,7 +190,7 @@ class TypeSystem:
if t in self.VECTOR_TYPES:
return self.VECTOR_TYPES[t][2]
if self.is_struct_vector(t):
- return f'{self.vector_elem(t)}[]'
+ return f'{self.vector_elem_ts(t)}[]'
if t in self.CUSTOM_STRUCTS:
return t # the struct name is its own TS interface name
return 'unknown'
diff --git a/tools/renderScenes.mjs b/tools/renderScenes.mjs
index 191a9accb..c6baf5571 100644
--- a/tools/renderScenes.mjs
+++ b/tools/renderScenes.mjs
@@ -401,6 +401,10 @@ export const SCENES = [
// light's line is inside an UNTURNED box's shadow and outside this one's,
// and a turn the other way would put it back in.
{ id: "shadow2d-turned", tier: "pr", webgpu: true, env: { ESTELLA_VERIFY_SCENE: "/scenes/mat-lit-shadow-turned.esscene", ESTELLA_VERIFY_MANIFEST: "/scenes/mat-lit-shadow-turned.textures.json", ESTELLA_VERIFY_W: "256", ESTELLA_VERIFY_H: "256", ESTELLA_VERIFY_STEPS: "2", ESTELLA_VERIFY_EXPECT: "[{\"x\":0.25,\"y\":0.5,\"rgb\":[0,255,0],\"tol\":60},{\"x\":0.75,\"y\":0.5,\"rgb\":[0,0,0],\"tol\":40},{\"x\":0.75,\"y\":0.7332,\"rgb\":[0,149,0],\"tol\":60}]" } },
+ // An occluder with an OUTLINE of its own: a triangle whose shadow reaches where
+ // the box beside it (20 units, and still authored) never could. The lower probe
+ // is the discriminating one — lit the moment the outline stops being read.
+ { id: "shadow2d-outline", tier: "pr", webgpu: true, env: { ESTELLA_VERIFY_SCENE: "/scenes/mat-lit-shadow-outline.esscene", ESTELLA_VERIFY_MANIFEST: "/scenes/mat-lit-shadow-outline.textures.json", ESTELLA_VERIFY_W: "256", ESTELLA_VERIFY_H: "256", ESTELLA_VERIFY_STEPS: "2", ESTELLA_VERIFY_EXPECT: "[{\"x\":0.75,\"y\":0.7332,\"rgb\":[0,0,0],\"tol\":40},{\"x\":0.75,\"y\":0.5,\"rgb\":[0,0,0],\"tol\":40},{\"x\":0.5833,\"y\":0.25,\"rgb\":[0,175,0],\"tol\":60}]" } },
// Two probes inside the penumbra, where a hard shadow reads 0 and an unshadowed
// surface reads 166: a soft edge is the only thing that lands between them.
{ id: "shadow2d-soft", tier: "pr", webgpu: true, env: { ESTELLA_VERIFY_SCENE: "/scenes/mat-lit-shadow-soft.esscene", ESTELLA_VERIFY_MANIFEST: "/scenes/mat-lit-shadow-soft.textures.json", ESTELLA_VERIFY_W: "256", ESTELLA_VERIFY_H: "256", ESTELLA_VERIFY_STEPS: "2", ESTELLA_VERIFY_EXPECT: "[{\"x\":0.25,\"y\":0.5,\"rgb\":[0,255,0],\"tol\":60},{\"x\":0.75,\"y\":0.5,\"rgb\":[0,0,0],\"tol\":40},{\"x\":0.75,\"y\":0.30,\"rgb\":[0,44,0],\"tol\":22},{\"x\":0.75,\"y\":0.70,\"rgb\":[0,52,0],\"tol\":22}]" } },