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(shadow): the atlas answers per caster, and the answer keeps its distinctions

esengine021757a5110c
diff --git a/desktop b/desktop
index f074e5c0a..7a258faa0 160000
--- a/desktop
+++ b/desktop
@@ -1 +1 @@
-Subproject commit f074e5c0af54f114da9fbeeb2e4cf9d20f4f04d1
+Subproject commit 7a258faa0d65dd625cfca3e1c4ac5986dc4d4eae
diff --git a/docs/astro/src/data/apiStability.generated.json b/docs/astro/src/data/apiStability.generated.json
index 8ed4e0c83..1e754c0b8 100644
--- a/docs/astro/src/data/apiStability.generated.json
+++ b/docs/astro/src/data/apiStability.generated.json
@@ -3,10 +3,10 @@
"counts": {
"public": 113,
"beta": 91,
- "experimental": 1800,
+ "experimental": 1801,
"deprecated": 3
},
- "total": 2004,
+ "total": 2005,
"subsystems": [
{
"id": "ecs",
diff --git a/sdk/etc/index.api.md b/sdk/etc/index.api.md
index 974f3455d..c232324ba 100644
--- a/sdk/etc/index.api.md
+++ b/sdk/etc/index.api.md
@@ -1,7 +1,7 @@
# API surface — esengine/index
<!-- Generated by tools/api-surface.mjs — do not edit. Run --update to accept changes. -->
-Symbols: 113 public · 84 beta · 1636 experimental · 3 deprecated
+Symbols: 113 public · 84 beta · 1637 experimental · 3 deprecated
## ABI_LAYOUT_HASH — const @experimental
```
@@ -6847,7 +6847,7 @@ UIElement = 7
## Renderer — const @experimental
```
-{ init(width: number, height: number): void; resize(width: number, height: number): void; beginFrame(elapsedSec?: number): void; updateTransforms(registry: { _cpp: CppRegistry; }): void; begin(viewProjection: Float32Array, target?: RenderTargetHandle, clearFlags?: number, clearColor?: { x: number; y: number; z: number; w: number; }, clearRect?: { x: number; y: number; w: number; h: number; }): void; flush(): void; end(): void; endFrame(): void; hasScreenOverlay(): boolean; beginScreenOverlay(projection: Float32Array, vpX: number, vpY: number, vpW: number, vpH: number): void; submitScreenOverlay(registry: { _cpp: CppRegistry; }): void; endScreenOverlay(target?: RenderTargetHandle): void; submitAll(registry: { _cpp: CppRegistry; }, vpX: number, vpY: number, vpW: number, vpH: number): void; setStage(stage: RenderStage): void; createRenderTarget(width: number, height: number, flags?: number): RenderTargetHandle; releaseRenderTarget(handle: RenderTargetHandle): void; getTargetTexture(handle: RenderTargetHandle): number; getTargetDepthTexture(handle: RenderTargetHandle): number; setClearColor(r: number, g: number, b: number, a: number): void; setViewport(x: number, y: number, w: number, h: number): void; setYSortLayers(mask: number): void; setDepthLayers(mask: number): void; setCullingMask(mask: number): void; setViewId(view: number): void; lodInspect(view: number, entity: number): LodDecision | null; setLodPreview(view: number, entity: number, level: number | null): void; lightStatus(entity: number): LightStatus | null; setTextureParams(textureId: number, minFilter: number, magFilter: number, wrapS: number, wrapT: number): void; measureBitmapText(fontHandle: number, text: string, fontSize: number, spacing: number): { width: number; height: number; }; getStats(): RenderStats; captureNextFrame(): void; getCapturedData(): FrameCaptureData | null; hasCapturedData(): boolean; replayToDrawCall(drawCallIndex: number): void; getSnapshotImageData(): Promise<ImageData | null>; }
+{ init(width: number, height: number): void; resize(width: number, height: number): void; beginFrame(elapsedSec?: number): void; updateTransforms(registry: { _cpp: CppRegistry; }): void; begin(viewProjection: Float32Array, target?: RenderTargetHandle, clearFlags?: number, clearColor?: { x: number; y: number; z: number; w: number; }, clearRect?: { x: number; y: number; w: number; h: number; }): void; flush(): void; end(): void; endFrame(): void; hasScreenOverlay(): boolean; beginScreenOverlay(projection: Float32Array, vpX: number, vpY: number, vpW: number, vpH: number): void; submitScreenOverlay(registry: { _cpp: CppRegistry; }): void; endScreenOverlay(target?: RenderTargetHandle): void; submitAll(registry: { _cpp: CppRegistry; }, vpX: number, vpY: number, vpW: number, vpH: number): void; setStage(stage: RenderStage): void; createRenderTarget(width: number, height: number, flags?: number): RenderTargetHandle; releaseRenderTarget(handle: RenderTargetHandle): void; getTargetTexture(handle: RenderTargetHandle): number; getTargetDepthTexture(handle: RenderTargetHandle): number; setClearColor(r: number, g: number, b: number, a: number): void; setViewport(x: number, y: number, w: number, h: number): void; setYSortLayers(mask: number): void; setDepthLayers(mask: number): void; setCullingMask(mask: number): void; setViewId(view: number): void; lodInspect(view: number, entity: number): LodDecision | null; setLodPreview(view: number, entity: number, level: number | null): void; lightStatus(entity: number): LightStatus | null; shadowStatus(entity: number): ShadowStatus | null; setTextureParams(textureId: number, minFilter: number, magFilter: number, wrapS: number, wrapT: number): void; measureBitmapText(fontHandle: number, text: string, fontSize: number, spacing: number): { width: number; height: number; }; getStats(): RenderStats; captureNextFrame(): void; getCapturedData(): FrameCaptureData | null; hasCapturedData(): boolean; replayToDrawCall(drawCallIndex: number): void; getSnapshotImageData(): Promise<ImageData | null>; }
```
## Replicated — const @experimental
@@ -7680,6 +7680,15 @@ enabled: boolean
size: Vec2
```
+## ShadowStatus — interface @experimental
+```
+deniedCasters: number
+granted: number
+reducedCasters: number
+refusal: "none" | "tile-budget" | "tile-too-large" | "atlas-full"
+requested: number
+```
+
## ShapeRenderer — const @experimental
```
BuiltinComponentDef<ShapeRendererData>
diff --git a/sdk/etc/index.native.api.md b/sdk/etc/index.native.api.md
index bd0b3cd4b..0f9f8fd46 100644
--- a/sdk/etc/index.native.api.md
+++ b/sdk/etc/index.native.api.md
@@ -1,7 +1,7 @@
# API surface — esengine/index.native
<!-- Generated by tools/api-surface.mjs — do not edit. Run --update to accept changes. -->
-Symbols: 113 public · 89 beta · 1655 experimental · 3 deprecated
+Symbols: 113 public · 89 beta · 1656 experimental · 3 deprecated
## ABI_LAYOUT_HASH — const @experimental
```
@@ -7040,7 +7040,7 @@ UIElement = 7
## Renderer — const @experimental
```
-{ init(width: number, height: number): void; resize(width: number, height: number): void; beginFrame(elapsedSec?: number): void; updateTransforms(registry: { _cpp: CppRegistry; }): void; begin(viewProjection: Float32Array, target?: RenderTargetHandle, clearFlags?: number, clearColor?: { x: number; y: number; z: number; w: number; }, clearRect?: { x: number; y: number; w: number; h: number; }): void; flush(): void; end(): void; endFrame(): void; hasScreenOverlay(): boolean; beginScreenOverlay(projection: Float32Array, vpX: number, vpY: number, vpW: number, vpH: number): void; submitScreenOverlay(registry: { _cpp: CppRegistry; }): void; endScreenOverlay(target?: RenderTargetHandle): void; submitAll(registry: { _cpp: CppRegistry; }, vpX: number, vpY: number, vpW: number, vpH: number): void; setStage(stage: RenderStage): void; createRenderTarget(width: number, height: number, flags?: number): RenderTargetHandle; releaseRenderTarget(handle: RenderTargetHandle): void; getTargetTexture(handle: RenderTargetHandle): number; getTargetDepthTexture(handle: RenderTargetHandle): number; setClearColor(r: number, g: number, b: number, a: number): void; setViewport(x: number, y: number, w: number, h: number): void; setYSortLayers(mask: number): void; setDepthLayers(mask: number): void; setCullingMask(mask: number): void; setViewId(view: number): void; lodInspect(view: number, entity: number): LodDecision | null; setLodPreview(view: number, entity: number, level: number | null): void; lightStatus(entity: number): LightStatus | null; setTextureParams(textureId: number, minFilter: number, magFilter: number, wrapS: number, wrapT: number): void; measureBitmapText(fontHandle: number, text: string, fontSize: number, spacing: number): { width: number; height: number; }; getStats(): RenderStats; captureNextFrame(): void; getCapturedData(): FrameCaptureData | null; hasCapturedData(): boolean; replayToDrawCall(drawCallIndex: number): void; getSnapshotImageData(): Promise<ImageData | null>; }
+{ init(width: number, height: number): void; resize(width: number, height: number): void; beginFrame(elapsedSec?: number): void; updateTransforms(registry: { _cpp: CppRegistry; }): void; begin(viewProjection: Float32Array, target?: RenderTargetHandle, clearFlags?: number, clearColor?: { x: number; y: number; z: number; w: number; }, clearRect?: { x: number; y: number; w: number; h: number; }): void; flush(): void; end(): void; endFrame(): void; hasScreenOverlay(): boolean; beginScreenOverlay(projection: Float32Array, vpX: number, vpY: number, vpW: number, vpH: number): void; submitScreenOverlay(registry: { _cpp: CppRegistry; }): void; endScreenOverlay(target?: RenderTargetHandle): void; submitAll(registry: { _cpp: CppRegistry; }, vpX: number, vpY: number, vpW: number, vpH: number): void; setStage(stage: RenderStage): void; createRenderTarget(width: number, height: number, flags?: number): RenderTargetHandle; releaseRenderTarget(handle: RenderTargetHandle): void; getTargetTexture(handle: RenderTargetHandle): number; getTargetDepthTexture(handle: RenderTargetHandle): number; setClearColor(r: number, g: number, b: number, a: number): void; setViewport(x: number, y: number, w: number, h: number): void; setYSortLayers(mask: number): void; setDepthLayers(mask: number): void; setCullingMask(mask: number): void; setViewId(view: number): void; lodInspect(view: number, entity: number): LodDecision | null; setLodPreview(view: number, entity: number, level: number | null): void; lightStatus(entity: number): LightStatus | null; shadowStatus(entity: number): ShadowStatus | null; setTextureParams(textureId: number, minFilter: number, magFilter: number, wrapS: number, wrapT: number): void; measureBitmapText(fontHandle: number, text: string, fontSize: number, spacing: number): { width: number; height: number; }; getStats(): RenderStats; captureNextFrame(): void; getCapturedData(): FrameCaptureData | null; hasCapturedData(): boolean; replayToDrawCall(drawCallIndex: number): void; getSnapshotImageData(): Promise<ImageData | null>; }
```
## Replicated — const @experimental
@@ -7873,6 +7873,15 @@ enabled: boolean
size: Vec2
```
+## ShadowStatus — interface @experimental
+```
+deniedCasters: number
+granted: number
+reducedCasters: number
+refusal: "none" | "tile-budget" | "tile-too-large" | "atlas-full"
+requested: number
+```
+
## ShapeRenderer — const @experimental
```
BuiltinComponentDef<ShapeRendererData>
diff --git a/sdk/etc/index.node.api.md b/sdk/etc/index.node.api.md
index 76defca71..b93400cf5 100644
--- a/sdk/etc/index.node.api.md
+++ b/sdk/etc/index.node.api.md
@@ -1,7 +1,7 @@
# API surface — esengine/index.node
<!-- Generated by tools/api-surface.mjs — do not edit. Run --update to accept changes. -->
-Symbols: 113 public · 86 beta · 1635 experimental · 3 deprecated
+Symbols: 113 public · 86 beta · 1636 experimental · 3 deprecated
## ANCHOR_AXES — const @experimental
```
@@ -6842,7 +6842,7 @@ UIElement = 7
## Renderer — const @experimental
```
-{ init(width: number, height: number): void; resize(width: number, height: number): void; beginFrame(elapsedSec?: number): void; updateTransforms(registry: { _cpp: CppRegistry; }): void; begin(viewProjection: Float32Array, target?: RenderTargetHandle, clearFlags?: number, clearColor?: { x: number; y: number; z: number; w: number; }, clearRect?: { x: number; y: number; w: number; h: number; }): void; flush(): void; end(): void; endFrame(): void; hasScreenOverlay(): boolean; beginScreenOverlay(projection: Float32Array, vpX: number, vpY: number, vpW: number, vpH: number): void; submitScreenOverlay(registry: { _cpp: CppRegistry; }): void; endScreenOverlay(target?: RenderTargetHandle): void; submitAll(registry: { _cpp: CppRegistry; }, vpX: number, vpY: number, vpW: number, vpH: number): void; setStage(stage: RenderStage): void; createRenderTarget(width: number, height: number, flags?: number): RenderTargetHandle; releaseRenderTarget(handle: RenderTargetHandle): void; getTargetTexture(handle: RenderTargetHandle): number; getTargetDepthTexture(handle: RenderTargetHandle): number; setClearColor(r: number, g: number, b: number, a: number): void; setViewport(x: number, y: number, w: number, h: number): void; setYSortLayers(mask: number): void; setDepthLayers(mask: number): void; setCullingMask(mask: number): void; setViewId(view: number): void; lodInspect(view: number, entity: number): LodDecision | null; setLodPreview(view: number, entity: number, level: number | null): void; lightStatus(entity: number): LightStatus | null; setTextureParams(textureId: number, minFilter: number, magFilter: number, wrapS: number, wrapT: number): void; measureBitmapText(fontHandle: number, text: string, fontSize: number, spacing: number): { width: number; height: number; }; getStats(): RenderStats; captureNextFrame(): void; getCapturedData(): FrameCaptureData | null; hasCapturedData(): boolean; replayToDrawCall(drawCallIndex: number): void; getSnapshotImageData(): Promise<ImageData | null>; }
+{ init(width: number, height: number): void; resize(width: number, height: number): void; beginFrame(elapsedSec?: number): void; updateTransforms(registry: { _cpp: CppRegistry; }): void; begin(viewProjection: Float32Array, target?: RenderTargetHandle, clearFlags?: number, clearColor?: { x: number; y: number; z: number; w: number; }, clearRect?: { x: number; y: number; w: number; h: number; }): void; flush(): void; end(): void; endFrame(): void; hasScreenOverlay(): boolean; beginScreenOverlay(projection: Float32Array, vpX: number, vpY: number, vpW: number, vpH: number): void; submitScreenOverlay(registry: { _cpp: CppRegistry; }): void; endScreenOverlay(target?: RenderTargetHandle): void; submitAll(registry: { _cpp: CppRegistry; }, vpX: number, vpY: number, vpW: number, vpH: number): void; setStage(stage: RenderStage): void; createRenderTarget(width: number, height: number, flags?: number): RenderTargetHandle; releaseRenderTarget(handle: RenderTargetHandle): void; getTargetTexture(handle: RenderTargetHandle): number; getTargetDepthTexture(handle: RenderTargetHandle): number; setClearColor(r: number, g: number, b: number, a: number): void; setViewport(x: number, y: number, w: number, h: number): void; setYSortLayers(mask: number): void; setDepthLayers(mask: number): void; setCullingMask(mask: number): void; setViewId(view: number): void; lodInspect(view: number, entity: number): LodDecision | null; setLodPreview(view: number, entity: number, level: number | null): void; lightStatus(entity: number): LightStatus | null; shadowStatus(entity: number): ShadowStatus | null; setTextureParams(textureId: number, minFilter: number, magFilter: number, wrapS: number, wrapT: number): void; measureBitmapText(fontHandle: number, text: string, fontSize: number, spacing: number): { width: number; height: number; }; getStats(): RenderStats; captureNextFrame(): void; getCapturedData(): FrameCaptureData | null; hasCapturedData(): boolean; replayToDrawCall(drawCallIndex: number): void; getSnapshotImageData(): Promise<ImageData | null>; }
```
## Replicated — const @experimental
@@ -7675,6 +7675,15 @@ enabled: boolean
size: Vec2
```
+## ShadowStatus — interface @experimental
+```
+deniedCasters: number
+granted: number
+reducedCasters: number
+refusal: "none" | "tile-budget" | "tile-too-large" | "atlas-full"
+requested: number
+```
+
## ShapeRenderer — const @experimental
```
BuiltinComponentDef<ShapeRendererData>
diff --git a/sdk/etc/minigame.api.md b/sdk/etc/minigame.api.md
index c38258f12..d1b491564 100644
--- a/sdk/etc/minigame.api.md
+++ b/sdk/etc/minigame.api.md
@@ -1,7 +1,7 @@
# API surface — esengine/minigame
<!-- Generated by tools/api-surface.mjs — do not edit. Run --update to accept changes. -->
-Symbols: 113 public · 84 beta · 1657 experimental · 3 deprecated
+Symbols: 113 public · 84 beta · 1658 experimental · 3 deprecated
## ANCHOR_AXES — const @experimental
```
@@ -7088,7 +7088,7 @@ UIElement = 7
## Renderer — const @experimental
```
-{ init(width: number, height: number): void; resize(width: number, height: number): void; beginFrame(elapsedSec?: number): void; updateTransforms(registry: { _cpp: CppRegistry; }): void; begin(viewProjection: Float32Array, target?: RenderTargetHandle, clearFlags?: number, clearColor?: { x: number; y: number; z: number; w: number; }, clearRect?: { x: number; y: number; w: number; h: number; }): void; flush(): void; end(): void; endFrame(): void; hasScreenOverlay(): boolean; beginScreenOverlay(projection: Float32Array, vpX: number, vpY: number, vpW: number, vpH: number): void; submitScreenOverlay(registry: { _cpp: CppRegistry; }): void; endScreenOverlay(target?: RenderTargetHandle): void; submitAll(registry: { _cpp: CppRegistry; }, vpX: number, vpY: number, vpW: number, vpH: number): void; setStage(stage: RenderStage): void; createRenderTarget(width: number, height: number, flags?: number): RenderTargetHandle; releaseRenderTarget(handle: RenderTargetHandle): void; getTargetTexture(handle: RenderTargetHandle): number; getTargetDepthTexture(handle: RenderTargetHandle): number; setClearColor(r: number, g: number, b: number, a: number): void; setViewport(x: number, y: number, w: number, h: number): void; setYSortLayers(mask: number): void; setDepthLayers(mask: number): void; setCullingMask(mask: number): void; setViewId(view: number): void; lodInspect(view: number, entity: number): LodDecision | null; setLodPreview(view: number, entity: number, level: number | null): void; lightStatus(entity: number): LightStatus | null; setTextureParams(textureId: number, minFilter: number, magFilter: number, wrapS: number, wrapT: number): void; measureBitmapText(fontHandle: number, text: string, fontSize: number, spacing: number): { width: number; height: number; }; getStats(): RenderStats; captureNextFrame(): void; getCapturedData(): FrameCaptureData | null; hasCapturedData(): boolean; replayToDrawCall(drawCallIndex: number): void; getSnapshotImageData(): Promise<ImageData | null>; }
+{ init(width: number, height: number): void; resize(width: number, height: number): void; beginFrame(elapsedSec?: number): void; updateTransforms(registry: { _cpp: CppRegistry; }): void; begin(viewProjection: Float32Array, target?: RenderTargetHandle, clearFlags?: number, clearColor?: { x: number; y: number; z: number; w: number; }, clearRect?: { x: number; y: number; w: number; h: number; }): void; flush(): void; end(): void; endFrame(): void; hasScreenOverlay(): boolean; beginScreenOverlay(projection: Float32Array, vpX: number, vpY: number, vpW: number, vpH: number): void; submitScreenOverlay(registry: { _cpp: CppRegistry; }): void; endScreenOverlay(target?: RenderTargetHandle): void; submitAll(registry: { _cpp: CppRegistry; }, vpX: number, vpY: number, vpW: number, vpH: number): void; setStage(stage: RenderStage): void; createRenderTarget(width: number, height: number, flags?: number): RenderTargetHandle; releaseRenderTarget(handle: RenderTargetHandle): void; getTargetTexture(handle: RenderTargetHandle): number; getTargetDepthTexture(handle: RenderTargetHandle): number; setClearColor(r: number, g: number, b: number, a: number): void; setViewport(x: number, y: number, w: number, h: number): void; setYSortLayers(mask: number): void; setDepthLayers(mask: number): void; setCullingMask(mask: number): void; setViewId(view: number): void; lodInspect(view: number, entity: number): LodDecision | null; setLodPreview(view: number, entity: number, level: number | null): void; lightStatus(entity: number): LightStatus | null; shadowStatus(entity: number): ShadowStatus | null; setTextureParams(textureId: number, minFilter: number, magFilter: number, wrapS: number, wrapT: number): void; measureBitmapText(fontHandle: number, text: string, fontSize: number, spacing: number): { width: number; height: number; }; getStats(): RenderStats; captureNextFrame(): void; getCapturedData(): FrameCaptureData | null; hasCapturedData(): boolean; replayToDrawCall(drawCallIndex: number): void; getSnapshotImageData(): Promise<ImageData | null>; }
```
## Replicated — const @experimental
@@ -7921,6 +7921,15 @@ enabled: boolean
size: Vec2
```
+## ShadowStatus — interface @experimental
+```
+deniedCasters: number
+granted: number
+reducedCasters: number
+refusal: "none" | "tile-budget" | "tile-too-large" | "atlas-full"
+requested: number
+```
+
## ShapeRenderer — const @experimental
```
BuiltinComponentDef<ShapeRendererData>
diff --git a/sdk/etc/wasm.api.md b/sdk/etc/wasm.api.md
index c2463ed7b..99f8bb985 100644
--- a/sdk/etc/wasm.api.md
+++ b/sdk/etc/wasm.api.md
@@ -418,6 +418,7 @@ renderer_setTextureParams: (textureId: number, minFilter: number, magFilter: num
renderer_setViewId: ((view: number) => void) | undefined
renderer_setViewport: (x: number, y: number, w: number, h: number) => void
renderer_setYSortLayers: ((mask: number) => void) | undefined
+renderer_shadowStatus: ((entity: number, outPtr: number) => number) | undefined
renderer_submitAll: (registry: CppRegistry, vpX: number, vpY: number, vpW: number, vpH: number) => void
renderer_submitScreenOverlay: ((registry: CppRegistry) => void) | undefined
renderer_submitSkeletalBatchByEntity: ((registry: CppRegistry, verticesPtr: number, vertexCount: number, indicesPtr: number, indexCount: number, textureId: number, blendMode: number, entity: number, skelScale: number, flipX: boolean, flipY: boolean, layer: number, depth: number, materialId: number) => void) | undefined
diff --git a/sdk/etc/wechat.api.md b/sdk/etc/wechat.api.md
index c32930f27..cf54415d6 100644
--- a/sdk/etc/wechat.api.md
+++ b/sdk/etc/wechat.api.md
@@ -1,7 +1,7 @@
# API surface — esengine/wechat
<!-- Generated by tools/api-surface.mjs — do not edit. Run --update to accept changes. -->
-Symbols: 113 public · 84 beta · 1647 experimental · 3 deprecated
+Symbols: 113 public · 84 beta · 1648 experimental · 3 deprecated
## ANCHOR_AXES — const @experimental
```
@@ -6849,7 +6849,7 @@ UIElement = 7
## Renderer — const @experimental
```
-{ init(width: number, height: number): void; resize(width: number, height: number): void; beginFrame(elapsedSec?: number): void; updateTransforms(registry: { _cpp: CppRegistry; }): void; begin(viewProjection: Float32Array, target?: RenderTargetHandle, clearFlags?: number, clearColor?: { x: number; y: number; z: number; w: number; }, clearRect?: { x: number; y: number; w: number; h: number; }): void; flush(): void; end(): void; endFrame(): void; hasScreenOverlay(): boolean; beginScreenOverlay(projection: Float32Array, vpX: number, vpY: number, vpW: number, vpH: number): void; submitScreenOverlay(registry: { _cpp: CppRegistry; }): void; endScreenOverlay(target?: RenderTargetHandle): void; submitAll(registry: { _cpp: CppRegistry; }, vpX: number, vpY: number, vpW: number, vpH: number): void; setStage(stage: RenderStage): void; createRenderTarget(width: number, height: number, flags?: number): RenderTargetHandle; releaseRenderTarget(handle: RenderTargetHandle): void; getTargetTexture(handle: RenderTargetHandle): number; getTargetDepthTexture(handle: RenderTargetHandle): number; setClearColor(r: number, g: number, b: number, a: number): void; setViewport(x: number, y: number, w: number, h: number): void; setYSortLayers(mask: number): void; setDepthLayers(mask: number): void; setCullingMask(mask: number): void; setViewId(view: number): void; lodInspect(view: number, entity: number): LodDecision | null; setLodPreview(view: number, entity: number, level: number | null): void; lightStatus(entity: number): LightStatus | null; setTextureParams(textureId: number, minFilter: number, magFilter: number, wrapS: number, wrapT: number): void; measureBitmapText(fontHandle: number, text: string, fontSize: number, spacing: number): { width: number; height: number; }; getStats(): RenderStats; captureNextFrame(): void; getCapturedData(): FrameCaptureData | null; hasCapturedData(): boolean; replayToDrawCall(drawCallIndex: number): void; getSnapshotImageData(): Promise<ImageData | null>; }
+{ init(width: number, height: number): void; resize(width: number, height: number): void; beginFrame(elapsedSec?: number): void; updateTransforms(registry: { _cpp: CppRegistry; }): void; begin(viewProjection: Float32Array, target?: RenderTargetHandle, clearFlags?: number, clearColor?: { x: number; y: number; z: number; w: number; }, clearRect?: { x: number; y: number; w: number; h: number; }): void; flush(): void; end(): void; endFrame(): void; hasScreenOverlay(): boolean; beginScreenOverlay(projection: Float32Array, vpX: number, vpY: number, vpW: number, vpH: number): void; submitScreenOverlay(registry: { _cpp: CppRegistry; }): void; endScreenOverlay(target?: RenderTargetHandle): void; submitAll(registry: { _cpp: CppRegistry; }, vpX: number, vpY: number, vpW: number, vpH: number): void; setStage(stage: RenderStage): void; createRenderTarget(width: number, height: number, flags?: number): RenderTargetHandle; releaseRenderTarget(handle: RenderTargetHandle): void; getTargetTexture(handle: RenderTargetHandle): number; getTargetDepthTexture(handle: RenderTargetHandle): number; setClearColor(r: number, g: number, b: number, a: number): void; setViewport(x: number, y: number, w: number, h: number): void; setYSortLayers(mask: number): void; setDepthLayers(mask: number): void; setCullingMask(mask: number): void; setViewId(view: number): void; lodInspect(view: number, entity: number): LodDecision | null; setLodPreview(view: number, entity: number, level: number | null): void; lightStatus(entity: number): LightStatus | null; shadowStatus(entity: number): ShadowStatus | null; setTextureParams(textureId: number, minFilter: number, magFilter: number, wrapS: number, wrapT: number): void; measureBitmapText(fontHandle: number, text: string, fontSize: number, spacing: number): { width: number; height: number; }; getStats(): RenderStats; captureNextFrame(): void; getCapturedData(): FrameCaptureData | null; hasCapturedData(): boolean; replayToDrawCall(drawCallIndex: number): void; getSnapshotImageData(): Promise<ImageData | null>; }
```
## Replicated — const @experimental
@@ -7682,6 +7682,15 @@ enabled: boolean
size: Vec2
```
+## ShadowStatus — interface @experimental
+```
+deniedCasters: number
+granted: number
+reducedCasters: number
+refusal: "none" | "tile-budget" | "tile-too-large" | "atlas-full"
+requested: number
+```
+
## ShapeRenderer — const @experimental
```
BuiltinComponentDef<ShapeRendererData>
diff --git a/sdk/src/core-render.ts b/sdk/src/core-render.ts
index 528835364..826b283d8 100644
--- a/sdk/src/core-render.ts
+++ b/sdk/src/core-render.ts
@@ -171,6 +171,7 @@ export {
type RenderStats,
type LodDecision,
type LightStatus,
+ type ShadowStatus,
} from './render/renderer';
// =============================================================================
diff --git a/sdk/src/ecs/bridge/nativeBindings.ts b/sdk/src/ecs/bridge/nativeBindings.ts
index a2cedafed..8d9fb5a6e 100644
--- a/sdk/src/ecs/bridge/nativeBindings.ts
+++ b/sdk/src/ecs/bridge/nativeBindings.ts
@@ -191,6 +191,7 @@ export const RENDERER_OPTIONAL_BINDINGS = {
setLodPreview: 'es_renderer_setLodPreview',
/** Which lights the cap turned away — an editor's question, like the two above. */
lightStatus: 'es_renderer_lightStatus',
+ shadowStatus: 'es_renderer_shadowStatus',
} as const;
/** Whether the host bound the whole frame surface — the gate for the SDK driving
diff --git a/sdk/src/ecs/bridge/nativeEngineApi.generated.ts b/sdk/src/ecs/bridge/nativeEngineApi.generated.ts
index 7e5da7936..9820faf9a 100644
--- a/sdk/src/ecs/bridge/nativeEngineApi.generated.ts
+++ b/sdk/src/ecs/bridge/nativeEngineApi.generated.ts
@@ -172,6 +172,7 @@ export interface NativeEngineApi {
renderer_setViewId?(view: number): void;
renderer_setViewport?(x: number, y: number, w: number, h: number): void;
renderer_setYSortLayers?(mask: number): void;
+ renderer_shadowStatus?(entity: number, outPtr: number): number;
renderer_submitAll?(registry: unknown, vpX: number, vpY: number, vpW: number, vpH: number): void;
renderer_submitScreenOverlay?(registry: unknown): void;
renderer_submitSkeletalBatchByEntity?(registry: unknown, verticesPtr: number, vertexCount: number, indicesPtr: number, indexCount: number, textureId: number, blendMode: number, entity: number, skelScale: number, flipX: boolean, flipY: boolean, layer: number, depth: number, materialId: number): void;
@@ -423,6 +424,7 @@ export function createNativeEngineApi(
bind('renderer_setViewId', 'es_renderer_setViewId', false);
bind('renderer_setViewport', 'es_renderer_setViewport', false);
bind('renderer_setYSortLayers', 'es_renderer_setYSortLayers', false);
+ bind('renderer_shadowStatus', 'es_renderer_shadowStatus', false);
bind('renderer_submitAll', 'es_renderer_submitAll', true);
bind('renderer_submitScreenOverlay', 'es_renderer_submitScreenOverlay', true);
bind('renderer_submitSkeletalBatchByEntity', 'es_renderer_submitSkeletalBatchByEntity', true);
diff --git a/sdk/src/ecs/bridge/nativeRenderer.ts b/sdk/src/ecs/bridge/nativeRenderer.ts
index da5ac7057..9517233db 100644
--- a/sdk/src/ecs/bridge/nativeRenderer.ts
+++ b/sdk/src/ecs/bridge/nativeRenderer.ts
@@ -149,6 +149,19 @@ export function createNativeRendererBackend(
screenSize: f[i + 3]!,
};
},
+ shadowStatus: (entity) => {
+ const fn = scope[RENDERER_OPTIONAL_BINDINGS.shadowStatus];
+ const heap = lodHeap();
+ if (typeof fn !== 'function' || !heap) return null;
+ if (!(fn as (e: number, p: number) => number)(entity >>> 0, heap.ptr)) return null;
+ const f = heap.heap.HEAPF32;
+ const i = heap.ptr >> 2;
+ const refusal = (['none', 'tile-budget', 'tile-too-large', 'atlas-full'] as const)[f[i + 2]!];
+ return {
+ requested: f[i]!, granted: f[i + 1]!, refusal: refusal ?? 'none',
+ deniedCasters: f[i + 3]!, reducedCasters: f[i + 4]!,
+ };
+ },
lightStatus: (entity) => {
const fn = scope[RENDERER_OPTIONAL_BINDINGS.lightStatus];
const heap = lodHeap();
diff --git a/sdk/src/render/renderer.ts b/sdk/src/render/renderer.ts
index ea716c988..f42ba6070 100644
--- a/sdk/src/render/renderer.ts
+++ b/sdk/src/render/renderer.ts
@@ -74,9 +74,34 @@ export interface RendererBackend {
lodInspect(view: number, entity: number): LodDecision | null;
setLodPreview(view: number, entity: number, level: number | null): void;
lightStatus(entity: number): LightStatus | null;
+ shadowStatus(entity: number): ShadowStatus | null;
getStats(): RenderStats;
}
+/**
+ * What the shadow atlas gave one caster last frame. @experimental
+ *
+ * `granted` below `requested` and above zero is a REDUCTION: a sun that kept two
+ * cascades of four still casts, and calling that a rejection would throw away the
+ * distinction the frame records it for. Zero granted is a denial.
+ */
+export interface ShadowStatus {
+ /** Tiles asked for: a cascade set, a cube's six faces, or one. */
+ requested: number;
+ /** Tiles kept. 0 means this light casts no shadow at all this frame. */
+ granted: number;
+ /**
+ * Why it did not get what it asked for. Three answers, not one: only
+ * `atlas-full` is fixed by a bigger atlas, and `tile-budget` is the shader's
+ * array bound, which no size changes.
+ */
+ refusal: 'none' | 'tile-budget' | 'tile-too-large' | 'atlas-full';
+ /** Casters the frame denied outright, for a reader that wants the total. */
+ deniedCasters: number;
+ /** Casters that kept fewer tiles than they asked for. */
+ reducedCasters: number;
+}
+
/**
* What the light cap did to one light last frame, and what it did overall.
* @experimental
@@ -124,8 +149,11 @@ let module: ESEngineModule | null = null;
let viewProjectionPtr: number = 0;
/** Four floats a LOD decision is read back through. */
let lodInspectPtr: number = 0;
-/** Five floats a light's standing with the cap is read back through. */
+/** Five floats a light's standing with the cap or the atlas is read back
+ * through. One buffer: neither answer outlives the call that asks. */
let lightStatusPtr: number = 0;
+/** AtlasRefusal, in the order ShadowAtlas.hpp declares it. */
+const ATLAS_REFUSAL: ShadowStatus['refusal'][] = ['none', 'tile-budget', 'tile-too-large', 'atlas-full'];
let backend: RendererBackend | null = null;
/** The wasm backend: every call marshals through the module's heap, exactly as
@@ -222,6 +250,15 @@ function wasmBackend(m: ESEngineModule): RendererBackend {
},
setLodPreview: (view, entity, level) =>
m.renderer_setLodPreview?.(view >>> 0, entity >>> 0, level ?? -1),
+ shadowStatus: (entity) => {
+ if (!m.renderer_shadowStatus || !lightStatusPtr) return null;
+ if (!m.renderer_shadowStatus(entity >>> 0, lightStatusPtr)) return null;
+ const f = m.HEAPF32.subarray(lightStatusPtr >> 2, (lightStatusPtr >> 2) + 5);
+ return {
+ requested: f[0]!, granted: f[1]!, refusal: ATLAS_REFUSAL[f[2]!] ?? 'none',
+ deniedCasters: f[3]!, reducedCasters: f[4]!,
+ };
+ },
lightStatus: (entity) => {
if (!m.renderer_lightStatus || !lightStatusPtr) return null;
if (!m.renderer_lightStatus(entity >>> 0, lightStatusPtr)) return null;
@@ -608,6 +645,14 @@ export const Renderer = {
return backend?.lightStatus(entity) ?? null;
},
+ /**
+ * What the shadow atlas gave `entity` last frame, or null when it asked the
+ * atlas for nothing. @experimental
+ */
+ shadowStatus(entity: number): ShadowStatus | null {
+ return backend?.shadowStatus(entity) ?? null;
+ },
+
setTextureParams(textureId: number, minFilter: number, magFilter: number, wrapS: number, wrapT: number): void {
module?.renderer_setTextureParams?.(textureId, minFilter, magFilter, wrapS, wrapT);
},
diff --git a/sdk/src/wasm.ts b/sdk/src/wasm.ts
index cc437236a..b0dbbd9c7 100644
--- a/sdk/src/wasm.ts
+++ b/sdk/src/wasm.ts
@@ -536,6 +536,7 @@ export interface ESEngineModule {
renderer_lodInspect?(view: number, entity: number, outPtr: number): number;
renderer_setLodPreview?(view: number, entity: number, level: number): void;
renderer_lightStatus?(entity: number, outPtr: number): number;
+ renderer_shadowStatus?(entity: number, outPtr: number): number;
renderer_setColorSpace?(linear: number): void;
/** Reseed the engine's randomness so a run reproduces (core/RandomSource.hpp). */
engine_setRandomSeed?(seed: number): void;
diff --git a/sdk/tests/camera-render-order.test.ts b/sdk/tests/camera-render-order.test.ts
index 898952d66..42f295346 100644
--- a/sdk/tests/camera-render-order.test.ts
+++ b/sdk/tests/camera-render-order.test.ts
@@ -64,7 +64,7 @@ describe('render order: transforms resolve before cameras are read', () => {
setStage: () => {}, setViewport: () => {},
setYSortLayers: () => {}, setDepthLayers: () => {}, setCullingMask: () => {},
setViewId: () => {},
- lodInspect: () => null, setLodPreview: () => {}, lightStatus: () => null,
+ lodInspect: () => null, setLodPreview: () => {}, lightStatus: () => null, shadowStatus: () => null,
getStats: () => ({ drawCalls: 0, triangles: 0, sprites: 0, text: 0, skeletal: 0, meshes: 0, culled: 0 }),
};
}
diff --git a/src/esengine/bindings/RendererBindings.cpp b/src/esengine/bindings/RendererBindings.cpp
index 25098537a..7d52cd0be 100644
--- a/src/esengine/bindings/RendererBindings.cpp
+++ b/src/esengine/bindings/RendererBindings.cpp
@@ -12,6 +12,7 @@
#include "../renderer/frame/RenderFrame.hpp"
#include "../renderer/lod/LodSelection.hpp"
#include "../renderer/store/LightPlan.hpp"
+#include "../renderer/store/ShadowPlan.hpp"
#include "../renderer/frame/RenderContext.hpp"
#include "../core/FrameProfiler.hpp"
#include "../renderer/frame/RenderStage.hpp"
@@ -855,6 +856,22 @@ i32 renderer_lightStatus(u32 entity, uintptr_t outPtr) {
return 1;
}
+i32 renderer_shadowStatus(u32 entity, uintptr_t outPtr) {
+ auto* out = boundarySpanMut<f32>(outPtr, 5, "renderer_shadowStatus.out");
+ if (!out) return 0;
+ for (u32 i = 0; i < 5; ++i) out[i] = 0.0f;
+ if (!g_renderFrame) return 0;
+ const ShadowPlanReport& plan = g_renderFrame->shadowPlan();
+ const ShadowGrant* grant = plan.grantFor(Entity::fromRaw(entity));
+ if (!grant) return 0;
+ out[0] = static_cast<f32>(grant->requested);
+ out[1] = static_cast<f32>(grant->granted);
+ out[2] = static_cast<f32>(static_cast<u8>(grant->refusal));
+ out[3] = static_cast<f32>(plan.deniedCasters());
+ out[4] = static_cast<f32>(plan.reducedCasters());
+ return 1;
+}
+
void renderer_setColorSpace(u32 linear) {
// Valid pre-init: the global reaches every later shader compile, and
// RenderFrame::init adopts it. A live frame applies immediately (editor
diff --git a/src/esengine/bindings/RendererBindings.hpp b/src/esengine/bindings/RendererBindings.hpp
index c1f24dd64..7504efb3a 100644
--- a/src/esengine/bindings/RendererBindings.hpp
+++ b/src/esengine/bindings/RendererBindings.hpp
@@ -176,6 +176,16 @@ void renderer_setLodPreview(u32 view, u32 entity, i32 level);
* a frame that refused none.
*/
i32 renderer_lightStatus(u32 entity, uintptr_t outPtr);
+
+/**
+ * @brief What the shadow atlas gave @p entity last frame, into five floats at
+ * @p outPtr: requested, granted, refusal, deniedCasters, reducedCasters.
+ *
+ * @details `granted` below `requested` and above zero is a REDUCTION — a sun that
+ * kept two cascades of four still casts. Zero is a denial. Returns 0
+ * when this entity asked the atlas for nothing.
+ */
+i32 renderer_shadowStatus(u32 entity, uintptr_t outPtr);
/** Project colorSpace: 1 = linear-light rendering (set before shaders compile). */
void renderer_setColorSpace(u32 linear);
void renderer_diagnose();
diff --git a/src/esengine/bindings/WebSDKEntry.cpp b/src/esengine/bindings/WebSDKEntry.cpp
index 194c12fd9..5dfc5b2b9 100644
--- a/src/esengine/bindings/WebSDKEntry.cpp
+++ b/src/esengine/bindings/WebSDKEntry.cpp
@@ -736,6 +736,7 @@ EMSCRIPTEN_BINDINGS(esengine_renderer) {
emscripten::function("renderer_lodInspect", &esengine::renderer_lodInspect);
emscripten::function("renderer_setLodPreview", &esengine::renderer_setLodPreview);
emscripten::function("renderer_lightStatus", &esengine::renderer_lightStatus);
+ emscripten::function("renderer_shadowStatus", &esengine::renderer_shadowStatus);
emscripten::function("renderer_setColorSpace", &esengine::renderer_setColorSpace);
diff --git a/src/esengine/renderer/store/ShadowPlan.hpp b/src/esengine/renderer/store/ShadowPlan.hpp
index ab7b31779..edf20f4d0 100644
--- a/src/esengine/renderer/store/ShadowPlan.hpp
+++ b/src/esengine/renderer/store/ShadowPlan.hpp
@@ -64,6 +64,14 @@ struct ShadowPlanReport {
return n;
}
+ /** @brief What @p entity asked for and kept, or null when it asked nothing. */
+ const ShadowGrant* grantFor(Entity entity) const {
+ for (const ShadowGrant& g : grants) {
+ if (g.light.raw == entity.raw) return &g;
+ }
+ return nullptr;
+ }
+
u32 reducedCasters() const {
u32 n = 0;
for (const ShadowGrant& g : grants) n += g.reduced() ? 1u : 0u;
diff --git a/tools/check-shadow-plan.mjs b/tools/check-shadow-plan.mjs
index 2769f6a81..e2fbc16e2 100644
--- a/tools/check-shadow-plan.mjs
+++ b/tools/check-shadow-plan.mjs
@@ -13,7 +13,7 @@
* and a denial still reaches a reader. Each is a line somebody could delete
* without a pixel moving.
*/
-import { readFileSync } from 'node:fs';
+import { readFileSync, existsSync } from 'node:fs';
import path from 'node:path';
import { fileURLToPath } from 'node:url';
@@ -62,6 +62,27 @@ for (const counter of ['render.shadow.denied', 'render.shadow.requested']) {
}
}
+// 4. One reader, for the reason check-light-cap holds the same rule: the panel a
+// person reads and the tool an agent calls answer through one method, so the
+// behavioural check exercises both. Two calls is one of them never checked.
+const SURFACE = 'desktop/src/engine/EditorControlSurface.ts';
+const DECORATORS = 'desktop/src/panels/inspector/componentDecorators.tsx';
+if (existsSync(path.join(ROOT, 'desktop', 'src'))) {
+ if (!/Renderer\.shadowStatus\(/.test(read(SURFACE))) {
+ problems.push(`${SURFACE} no longer reads the frame back (Renderer.shadowStatus)`);
+ }
+ const decorators = read(DECORATORS);
+ if (!/EditorControlSurface\.shadowStatus\(/.test(decorators)) {
+ problems.push(`${DECORATORS} no longer asks the surface for a caster's standing`);
+ }
+ // Reduction and denial are the distinction the record exists for; a reader
+ // that only knows `denied` reports a sun with two cascades as casting nothing.
+ if (!/granted > 0 && \w+\.granted < /.test(decorators)) {
+ problems.push(`${DECORATORS} no longer tells a REDUCTION from a denial — a caster that kept`
+ + ' fewer tiles still casts, and the frame records the two apart');
+ }
+}
+
if (problems.length) {
console.error(`check-shadow-plan: ${problems.length} problem(s)`);
for (const p of problems) console.error(` - ${p}`);
diff --git a/tools/lib/runtimeDecisions.mjs b/tools/lib/runtimeDecisions.mjs
index 728a765fa..a8670e2a6 100644
--- a/tools/lib/runtimeDecisions.mjs
+++ b/tools/lib/runtimeDecisions.mjs
@@ -82,12 +82,8 @@ export const DECISIONS = [
kind: 'contended-resource',
owner: { path: 'src/esengine/renderer/store/ShadowPlan.hpp', probe: /inline ShadowGrant claimTiles/ },
runtime: { has: true, cite: { path: 'src/esengine/renderer/store/ShadowPlan.hpp', probe: /grant\.refusal = why/ } },
- editor: {
- has: false,
- owed: 'the frame now records who was refused and why (ShadowPlanReport, render.shadow.denied), '
- + 'and nothing reads it — a light stops casting and the viewport still gives no reason',
- },
- agent: { has: false, owed: 'nothing to read' },
+ editor: { has: true, cite: { path: 'desktop/src/panels/inspector/componentDecorators.tsx', probe: /EditorControlSurface\.shadowStatus\(/ } },
+ agent: { has: true, cite: { path: 'desktop/shared/toolCatalog.mjs', probe: /'get_shadow_status'/ } },
},
{
id: 'light.cap',