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(lod): the frame records the whole decision, so the editor can explain it

esengine9327e21ef987
diff --git a/desktop b/desktop
index 28d74bc82..855dbbdfc 160000
--- a/desktop
+++ b/desktop
@@ -1 +1 @@
-Subproject commit 28d74bc828c8027abc4fd0f12ea45fe7f8111441
+Subproject commit 855dbbdfcc2332b299cb582be1f0bbe62c20c11c
diff --git a/docs/astro/src/data/apiStability.generated.json b/docs/astro/src/data/apiStability.generated.json
index 5f181036f..1820faaa1 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": 1796,
+ "experimental": 1797,
"deprecated": 3
},
- "total": 2000,
+ "total": 2001,
"subsystems": [
{
"id": "ecs",
diff --git a/sdk/etc/index.api.md b/sdk/etc/index.api.md
index b30d3a8a2..9b591af63 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 · 1632 experimental · 3 deprecated
+Symbols: 113 public · 84 beta · 1633 experimental · 3 deprecated
## ABI_LAYOUT_HASH — const @experimental
```
@@ -4609,6 +4609,14 @@ static new (opts?: LocalizationOptions): LocalizationPlugin
static prototype: LocalizationPlugin
```
+## LodDecision — interface @experimental
+```
+level: number | null
+levels: number
+screenSize: number
+unbiased: number | null
+```
+
## LogEntry — interface @experimental
```
category: string
@@ -6823,7 +6831,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; 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; 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
diff --git a/sdk/etc/index.native.api.md b/sdk/etc/index.native.api.md
index c044e981e..3f98529c8 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 · 1651 experimental · 3 deprecated
+Symbols: 113 public · 89 beta · 1652 experimental · 3 deprecated
## ABI_LAYOUT_HASH — const @experimental
```
@@ -4617,6 +4617,14 @@ static new (opts?: LocalizationOptions): LocalizationPlugin
static prototype: LocalizationPlugin
```
+## LodDecision — interface @experimental
+```
+level: number | null
+levels: number
+screenSize: number
+unbiased: number | null
+```
+
## LogEntry — interface @experimental
```
category: string
@@ -7016,7 +7024,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; 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; 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
diff --git a/sdk/etc/index.node.api.md b/sdk/etc/index.node.api.md
index 116f1b7f1..1ac9ea47f 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 · 1631 experimental · 3 deprecated
+Symbols: 113 public · 86 beta · 1632 experimental · 3 deprecated
## ANCHOR_AXES — const @experimental
```
@@ -4604,6 +4604,14 @@ static new (opts?: LocalizationOptions): LocalizationPlugin
static prototype: LocalizationPlugin
```
+## LodDecision — interface @experimental
+```
+level: number | null
+levels: number
+screenSize: number
+unbiased: number | null
+```
+
## LogEntry — interface @experimental
```
category: string
@@ -6818,7 +6826,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; 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; 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
diff --git a/sdk/etc/minigame.api.md b/sdk/etc/minigame.api.md
index 5b53810a9..2fb2fc4b1 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 · 1653 experimental · 3 deprecated
+Symbols: 113 public · 84 beta · 1654 experimental · 3 deprecated
## ANCHOR_AXES — const @experimental
```
@@ -4604,6 +4604,14 @@ static new (opts?: LocalizationOptions): LocalizationPlugin
static prototype: LocalizationPlugin
```
+## LodDecision — interface @experimental
+```
+level: number | null
+levels: number
+screenSize: number
+unbiased: number | null
+```
+
## LogEntry — interface @experimental
```
category: string
@@ -7064,7 +7072,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; 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; 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
diff --git a/sdk/etc/wasm.api.md b/sdk/etc/wasm.api.md
index 96667798d..514116653 100644
--- a/sdk/etc/wasm.api.md
+++ b/sdk/etc/wasm.api.md
@@ -393,6 +393,7 @@ renderer_getTextureBytes: (() => number) | undefined
renderer_getTriangles: () => number
renderer_hasCapturedData: () => boolean
renderer_init: (width: number, height: number) => void
+renderer_lodInspect: ((view: number, entity: number, outPtr: number) => number) | undefined
renderer_pollFrameCapture: ((handle: number) => number) | undefined
renderer_pollPreviewReadback: () => number
renderer_pollSkeletalPreview: (preview: number) => number
@@ -408,6 +409,7 @@ renderer_setColorSpace: ((linear: number) => void) | undefined
renderer_setCullingMask: ((mask: number) => void) | undefined
renderer_setDepthLayers: ((mask: number) => void) | undefined
renderer_setEntityDrawOrder: ((registry: CppRegistry, entitiesPtr: number, count: number) => void) | undefined
+renderer_setLodPreview: ((view: number, entity: number, level: number) => void) | undefined
renderer_setStage: (stage: number) => void
renderer_setTextureParams: (textureId: number, minFilter: number, magFilter: number, wrapS: number, wrapT: number) => void
renderer_setViewId: ((view: number) => void) | undefined
diff --git a/sdk/etc/wechat.api.md b/sdk/etc/wechat.api.md
index 096fb1c1e..4f3431acb 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 · 1643 experimental · 3 deprecated
+Symbols: 113 public · 84 beta · 1644 experimental · 3 deprecated
## ANCHOR_AXES — const @experimental
```
@@ -4611,6 +4611,14 @@ static new (opts?: LocalizationOptions): LocalizationPlugin
static prototype: LocalizationPlugin
```
+## LodDecision — interface @experimental
+```
+level: number | null
+levels: number
+screenSize: number
+unbiased: number | null
+```
+
## LogEntry — interface @experimental
```
category: string
@@ -6825,7 +6833,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; 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; 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
diff --git a/sdk/src/core-render.ts b/sdk/src/core-render.ts
index 612946f67..c9ed60359 100644
--- a/sdk/src/core-render.ts
+++ b/sdk/src/core-render.ts
@@ -169,6 +169,7 @@ export {
shutdownRendererAPI,
type RenderTargetHandle,
type RenderStats,
+ type LodDecision,
} from './render/renderer';
// =============================================================================
diff --git a/sdk/src/ecs/bridge/nativeBindings.ts b/sdk/src/ecs/bridge/nativeBindings.ts
index f96dcd1ce..32f2d5e05 100644
--- a/sdk/src/ecs/bridge/nativeBindings.ts
+++ b/sdk/src/ecs/bridge/nativeBindings.ts
@@ -184,6 +184,11 @@ export const RENDERER_OPTIONAL_BINDINGS = {
endScreenOverlay: 'es_renderer_endScreenOverlay',
/** The view a collect looks from; hosts predating it share one LOD memory. */
setViewId: 'es_renderer_setViewId',
+ /** What a view decided about one object's level, and holding another level up
+ * to look at instead. An editor's questions — a host that binds neither runs
+ * no editor, and the game it does run is unaffected either way. */
+ lodInspect: 'es_renderer_lodInspect',
+ setLodPreview: 'es_renderer_setLodPreview',
} 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 351dbe593..e7c68c460 100644
--- a/sdk/src/ecs/bridge/nativeEngineApi.generated.ts
+++ b/sdk/src/ecs/bridge/nativeEngineApi.generated.ts
@@ -147,6 +147,7 @@ export interface NativeEngineApi {
renderer_getTriangles?(): number;
renderer_hasCapturedData?(): boolean;
renderer_init?(width: number, height: number): void;
+ renderer_lodInspect?(view: number, entity: number, outPtr: number): number;
renderer_pollFrameCapture?(handle: number): number;
renderer_pollPreviewReadback?(): number;
renderer_pollSkeletalPreview?(preview: number): number;
@@ -162,6 +163,7 @@ export interface NativeEngineApi {
renderer_setCullingMask?(mask: number): void;
renderer_setDepthLayers?(mask: number): void;
renderer_setEntityDrawOrder?(registry: unknown, entitiesPtr: number, count: number): void;
+ renderer_setLodPreview?(view: number, entity: number, level: number): void;
renderer_setStage?(stage: number): void;
renderer_setTextureParams?(textureId: number, minFilter: number, magFilter: number, wrapS: number, wrapT: number): void;
renderer_setViewId?(view: number): void;
@@ -393,6 +395,7 @@ export function createNativeEngineApi(
bind('renderer_getTriangles', 'es_renderer_getTriangles', false);
bind('renderer_hasCapturedData', 'es_renderer_hasCapturedData', false);
bind('renderer_init', 'es_renderer_init', false);
+ bind('renderer_lodInspect', 'es_renderer_lodInspect', false);
bind('renderer_pollFrameCapture', 'es_renderer_pollFrameCapture', false);
bind('renderer_pollPreviewReadback', 'es_renderer_pollPreviewReadback', false);
bind('renderer_pollSkeletalPreview', 'es_renderer_pollSkeletalPreview', false);
@@ -408,6 +411,7 @@ export function createNativeEngineApi(
bind('renderer_setCullingMask', 'es_renderer_setCullingMask', false);
bind('renderer_setDepthLayers', 'es_renderer_setDepthLayers', false);
bind('renderer_setEntityDrawOrder', 'es_renderer_setEntityDrawOrder', true);
+ bind('renderer_setLodPreview', 'es_renderer_setLodPreview', false);
bind('renderer_setStage', 'es_renderer_setStage', false);
bind('renderer_setTextureParams', 'es_renderer_setTextureParams', false);
bind('renderer_setViewId', 'es_renderer_setViewId', false);
diff --git a/sdk/src/ecs/bridge/nativeRenderer.ts b/sdk/src/ecs/bridge/nativeRenderer.ts
index 8b5bc9629..59b3d0557 100644
--- a/sdk/src/ecs/bridge/nativeRenderer.ts
+++ b/sdk/src/ecs/bridge/nativeRenderer.ts
@@ -19,10 +19,20 @@
import type { CppRegistry } from '../../wasm';
import type { RendererBackend, RenderStats } from '../../render/renderer';
import { RENDERER_BINDINGS, RENDERER_OPTIONAL_BINDINGS, RENDERER_STATS_BINDINGS } from './nativeBindings';
+import { createNativeHeap, type NativeHeap } from './nativeHeap';
/** Invoke a host-provided global by name; throws if the host did not bind it
* (these are the frame contract — a missing one is a broken host, not a
* degraded frame). */
+/**
+ * Four floats a LOD decision is read back through, allocated once.
+ *
+ * Held for the process rather than per call: it is sixteen bytes against a heap
+ * whose views must not be rebuilt (see nativeHeap.ts), and an inspect runs while
+ * a panel is open, which is every frame.
+ */
+let lodScratch: { heap: NativeHeap; ptr: number } | null = null;
+
function hostCall(scope: Record<string, unknown>, name: string, args: unknown[]): unknown {
const fn = scope[name];
if (typeof fn !== 'function') {
@@ -51,6 +61,13 @@ function optional(
export function createNativeRendererBackend(
scope: Record<string, unknown> = globalThis as unknown as Record<string, unknown>,
): RendererBackend {
+ const lodHeap = (): { heap: NativeHeap; ptr: number } | null => {
+ if (lodScratch) return lodScratch;
+ const heap = createNativeHeap(scope);
+ if (!heap) return null;
+ lodScratch = { heap, ptr: heap._malloc(4 * 4) };
+ return lodScratch;
+ };
return {
// The renderer is already up: the host created the device and sized the
// surface before the SDK booted. Resizing still matters (rotation).
@@ -115,6 +132,28 @@ export function createNativeRendererBackend(
const fn = scope[RENDERER_OPTIONAL_BINDINGS.setViewId];
if (typeof fn === 'function') (fn as (v: number) => void)(view >>> 0);
},
+ lodInspect: (view, entity) => {
+ const fn = scope[RENDERER_OPTIONAL_BINDINGS.lodInspect];
+ const heap = lodHeap();
+ if (typeof fn !== 'function' || !heap) return null;
+ if (!(fn as (v: number, e: number, p: number) => number)(view >>> 0, entity >>> 0, heap.ptr)) {
+ return null;
+ }
+ const f = heap.heap.HEAPF32;
+ const i = heap.ptr >> 2;
+ return {
+ level: f[i]! < 0 ? null : f[i]!,
+ unbiased: f[i + 1]! < 0 ? null : f[i + 1]!,
+ levels: f[i + 2]!,
+ screenSize: f[i + 3]!,
+ };
+ },
+ setLodPreview: (view, entity, level): void => {
+ const fn = scope[RENDERER_OPTIONAL_BINDINGS.setLodPreview];
+ if (typeof fn === 'function') {
+ (fn as (v: number, e: number, l: number) => void)(view >>> 0, entity >>> 0, level ?? -1);
+ }
+ },
getStats: (): RenderStats => {
const read = (name: string): number => {
const fn = scope[name];
diff --git a/sdk/src/render/renderer.ts b/sdk/src/render/renderer.ts
index 42b3bc6a5..990e1b5d6 100644
--- a/sdk/src/render/renderer.ts
+++ b/sdk/src/render/renderer.ts
@@ -71,14 +71,38 @@ export interface RendererBackend {
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;
getStats(): RenderStats;
}
+/**
+ * What a view decided about one object's level, read back from where the decision
+ * was made. @experimental
+ *
+ * Never recomputed by a reader: the whole point of carrying `unbiased` is that an
+ * explanation of a level has to be the frame's own, and a second selector written
+ * beside this one would be free to disagree with the picture on screen.
+ */
+export interface LodDecision {
+ /** The level drawn, or `null` when the object was small enough to be culled. */
+ level: number | null;
+ /** What the bare thresholds ask for with no memory behind them; differing from
+ * `level` is hysteresis holding the coarser (or finer) side. */
+ unbiased: number | null;
+ /** Stand-ins the group actually reaches — levels beyond it do not exist. */
+ levels: number;
+ /** Fraction of the viewport HEIGHT the object covered when it was measured. */
+ screenSize: number;
+}
+
const NO_STATS: RenderStats = { drawCalls: 0, triangles: 0, sprites: 0, text: 0, skeletal: 0, meshes: 0, culled: 0 };
const bridge = new CoreApiBridge('renderer');
let module: ESEngineModule | null = null;
let viewProjectionPtr: number = 0;
+/** Four floats a LOD decision is read back through. */
+let lodInspectPtr: number = 0;
let backend: RendererBackend | null = null;
/** The wasm backend: every call marshals through the module's heap, exactly as
@@ -162,6 +186,19 @@ function wasmBackend(m: ESEngineModule): RendererBackend {
setDepthLayers: (mask) => m.renderer_setDepthLayers?.(mask >>> 0),
setCullingMask: (mask) => m.renderer_setCullingMask?.(mask >>> 0),
setViewId: (view) => m.renderer_setViewId?.(view >>> 0),
+ lodInspect: (view, entity) => {
+ if (!m.renderer_lodInspect || !lodInspectPtr) return null;
+ if (!m.renderer_lodInspect(view >>> 0, entity >>> 0, lodInspectPtr)) return null;
+ const f = m.HEAPF32.subarray(lodInspectPtr >> 2, (lodInspectPtr >> 2) + 4);
+ return {
+ level: f[0]! < 0 ? null : f[0]!,
+ unbiased: f[1]! < 0 ? null : f[1]!,
+ levels: f[2]!,
+ screenSize: f[3]!,
+ };
+ },
+ setLodPreview: (view, entity, level) =>
+ m.renderer_setLodPreview?.(view >>> 0, entity >>> 0, level ?? -1),
getStats: () => ({
drawCalls: m.renderer_getDrawCalls(),
triangles: m.renderer_getTriangles(),
@@ -345,6 +382,7 @@ export function initRendererAPI(wasmModule: ESEngineModule): void {
module = bridge.module;
installContextLossGuard(module);
viewProjectionPtr = module._malloc(16 * 4);
+ lodInspectPtr = module._malloc(4 * 4);
backend = wasmBackend(module);
}
@@ -359,6 +397,10 @@ export function shutdownRendererAPI(): void {
module._free(viewProjectionPtr);
viewProjectionPtr = 0;
}
+ if (module && lodInspectPtr) {
+ module._free(lodInspectPtr);
+ lodInspectPtr = 0;
+ }
bridge.disconnect();
module = null;
backend = null;
@@ -495,6 +537,27 @@ export const Renderer = {
backend?.setViewId(view);
},
+ /**
+ * What @p view decided about `entity`'s LOD last time it drew it, or null when
+ * that view has not measured it — off screen, or carrying no LODGroup, which
+ * is not the same as measuring it at level 0. @experimental
+ */
+ lodInspect(view: number, entity: number): LodDecision | null {
+ return backend?.lodInspect(view, entity) ?? null;
+ },
+
+ /**
+ * Show `level` for `entity` in `view` instead of the level that view chose;
+ * `null` goes back to choosing. @experimental
+ *
+ * View state, never component state: a group is authored policy and reads the
+ * same everywhere. The choice goes on being made underneath, so leaving a
+ * preview obeys the selector again rather than resuming from what was held up.
+ */
+ setLodPreview(view: number, entity: number, level: number | null): void {
+ backend?.setLodPreview(view, entity, level);
+ },
+
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 8c05db531..7ca5f884f 100644
--- a/sdk/src/wasm.ts
+++ b/sdk/src/wasm.ts
@@ -531,6 +531,8 @@ export interface ESEngineModule {
renderer_setDepthLayers?(mask: number): void;
renderer_setCullingMask?(mask: number): void;
renderer_setViewId?(view: number): void;
+ renderer_lodInspect?(view: number, entity: number, outPtr: number): number;
+ renderer_setLodPreview?(view: number, entity: number, level: number): void;
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 06fd5e24b..2ee50c1db 100644
--- a/sdk/tests/camera-render-order.test.ts
+++ b/sdk/tests/camera-render-order.test.ts
@@ -64,6 +64,7 @@ describe('render order: transforms resolve before cameras are read', () => {
setStage: () => {}, setViewport: () => {},
setYSortLayers: () => {}, setDepthLayers: () => {}, setCullingMask: () => {},
setViewId: () => {},
+ lodInspect: () => null, setLodPreview: () => {},
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 1cde28c47..298e8f37f 100644
--- a/src/esengine/bindings/RendererBindings.cpp
+++ b/src/esengine/bindings/RendererBindings.cpp
@@ -9,6 +9,7 @@
#include "BoundarySpan.hpp"
#include "../renderer/rhi/GfxDevice.hpp"
#include "../renderer/frame/RenderFrame.hpp"
+#include "../renderer/lod/LodSelection.hpp"
#include "../renderer/frame/RenderContext.hpp"
#include "../core/FrameProfiler.hpp"
#include "../renderer/frame/RenderStage.hpp"
@@ -781,6 +782,31 @@ void renderer_setViewId(u32 view) {
if (auto* frame = g_renderFrame) frame->setViewId(view);
}
+i32 renderer_lodInspect(u32 view, u32 entity, uintptr_t outPtr) {
+ auto* out = boundarySpanMut<f32>(outPtr, 4, "renderer_lodInspect.out");
+ if (!out) return 0;
+ out[0] = out[1] = out[2] = out[3] = 0.0f;
+ if (!g_renderFrame) return 0;
+ u8 level = 0, unbiased = 0, levels = 0;
+ f32 size = 0.0f;
+ if (!g_renderFrame->lodInspect(view, Entity::fromRaw(entity), level, unbiased, levels, size)) {
+ return 0;
+ }
+ // Culled is a level nothing draws, not a big number: handed over as -1 so a
+ // reader that forgets to check it gets an impossible level rather than 255.
+ out[0] = level == lod::kCulled ? -1.0f : static_cast<f32>(level);
+ out[1] = unbiased == lod::kCulled ? -1.0f : static_cast<f32>(unbiased);
+ out[2] = static_cast<f32>(levels);
+ out[3] = size;
+ return 1;
+}
+
+void renderer_setLodPreview(u32 view, u32 entity, i32 level) {
+ if (!g_renderFrame) return;
+ const u8 held = level < 0 ? lod::kNoPreview : static_cast<u8>(level);
+ g_renderFrame->setLodPreview(view, Entity::fromRaw(entity), held);
+}
+
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 e574578d8..dd38ebba4 100644
--- a/src/esengine/bindings/RendererBindings.hpp
+++ b/src/esengine/bindings/RendererBindings.hpp
@@ -149,6 +149,22 @@ void renderer_setCullingMask(u32 mask);
/** Names the view the next collect looks from, which its LOD levels are remembered
* under. Set per camera, before renderer_submitAll; 0 = the shared default view. */
void renderer_setViewId(u32 view);
+
+/**
+ * @brief What @p view decided about @p entity's LOD, into four floats at
+ * @p outPtr: level, the level the bare thresholds ask for, how many
+ * stand-ins are reachable, and the screen size measured.
+ *
+ * @details A level of -1 is culled. Returns 0 when this view has not measured the
+ * entity, which is not level 0 and must not be shown as one.
+ */
+i32 renderer_lodInspect(u32 view, u32 entity, uintptr_t outPtr);
+
+/**
+ * @brief Draw @p level for @p entity in @p view instead of the chosen one; a
+ * negative @p level goes back to the view's own choice.
+ */
+void renderer_setLodPreview(u32 view, u32 entity, i32 level);
/** 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 6427eb9a7..35f3e9e40 100644
--- a/src/esengine/bindings/WebSDKEntry.cpp
+++ b/src/esengine/bindings/WebSDKEntry.cpp
@@ -725,6 +725,8 @@ EMSCRIPTEN_BINDINGS(esengine_renderer) {
emscripten::function("renderer_setDepthLayers", &esengine::renderer_setDepthLayers);
emscripten::function("renderer_setCullingMask", &esengine::renderer_setCullingMask);
emscripten::function("renderer_setViewId", &esengine::renderer_setViewId);
+ emscripten::function("renderer_lodInspect", &esengine::renderer_lodInspect);
+ emscripten::function("renderer_setLodPreview", &esengine::renderer_setLodPreview);
emscripten::function("renderer_setColorSpace", &esengine::renderer_setColorSpace);
diff --git a/src/esengine/renderer/frame/RenderFrame.hpp b/src/esengine/renderer/frame/RenderFrame.hpp
index 13fac3316..98398025c 100644
--- a/src/esengine/renderer/frame/RenderFrame.hpp
+++ b/src/esengine/renderer/frame/RenderFrame.hpp
@@ -282,6 +282,34 @@ public:
*/
void setViewId(u32 view) { view_id_ = view; }
+ /**
+ * @brief The LOD decision @p view last made about @p entity: the level, what
+ * the bare thresholds asked for, the stand-ins reachable, the size.
+ *
+ * @details A read of what was RECORDED where the choice was made: an editor
+ * explaining a level has to agree with the frame that drew it, and
+ * the only way to be sure is to not compute it twice.
+ */
+ bool lodInspect(u32 view, Entity entity, u8& outLevel, u8& outUnbiased,
+ u8& outLevels, f32& outSize) const {
+ return lod_view_state_.inspect(view, entity, outLevel, outUnbiased, outLevels, outSize);
+ }
+
+ /**
+ * @brief Show @p level for @p entity in @p view instead of the level that
+ * view chose; @ref lod::kNoPreview goes back to choosing.
+ *
+ * @details View state, never component state: a group is authored policy and
+ * is the same everywhere. The choice is still made and remembered
+ * while a preview stands, so leaving one obeys the selector again.
+ */
+ void setLodPreview(u32 view, Entity entity, u8 level) {
+ lod_view_state_.preview(view, entity, level);
+ }
+
+ /** @brief How many (view, entity) pairs are held up for inspection. */
+ usize lodPreviewCount() const { return lod_view_state_.previewCount(); }
+
/**
* @brief Switch the frame to linear-light rendering (project colorSpace).
* @details Sets the global ES_LINEAR shader input, linearizes CPU-side
diff --git a/src/esengine/renderer/lod/LodViewState.hpp b/src/esengine/renderer/lod/LodViewState.hpp
index 7b1530b37..902d37a5d 100644
--- a/src/esengine/renderer/lod/LodViewState.hpp
+++ b/src/esengine/renderer/lod/LodViewState.hpp
@@ -2,7 +2,8 @@
// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
/**
* @file LodViewState.hpp
- * @brief The level each view last drew an object at — what hysteresis remembers.
+ * @brief What a view knows about an object's level: what it chose, why, and
+ * whether something is being held up for inspection instead.
*/
#pragma once
@@ -13,6 +14,9 @@
namespace esengine::lod {
+/** @brief A preview slot holding no level, so the view's own choice is drawn. */
+inline constexpr u8 kNoPreview = 0xFEu;
+
/**
* @brief Levels remembered per (view, entity) pair.
*
@@ -20,6 +24,11 @@ namespace esengine::lod {
* from HERE": a minimap and a main camera looking at one object in one
* frame must be able to disagree. Kept on the entity it would be one
* answer, and whichever camera drew last would decide for all of them.
+ *
+ * The entry carries the whole DECISION, not just its outcome: the size
+ * measured, and what that size asks for with no memory behind it. An
+ * editor explaining a level then reads facts recorded where the choice
+ * was made rather than running the selector a second time.
*/
class LodViewState {
public:
@@ -43,20 +52,82 @@ public:
return it == entries_.end() ? 0 : it->second.level;
}
- void remember(u32 view, Entity entity, u8 level) {
+ /**
+ * @brief Record a decision: what was chosen, what the bare thresholds asked
+ * for, how many stand-ins were reachable, and the size all of it read.
+ *
+ * @details `chosen` and `unbiased` differing IS hysteresis holding a level,
+ * which is the one explanation a creator cannot reconstruct from the
+ * component: the numbers on screen would say the other level.
+ */
+ void remember(u32 view, Entity entity, u8 chosen, u8 unbiased, u8 levels, f32 size) {
auto& entry = entries_[key(view, entity)];
- entry.level = level;
+ entry.level = chosen;
+ entry.unbiased = unbiased;
+ entry.levels = levels;
+ entry.size = size;
entry.stamp = frame_;
}
- void clear() { entries_.clear(); }
+ /** @brief The whole recorded decision, or false when this view has not
+ * measured this entity — which is not the same as measuring it at 0. */
+ bool inspect(u32 view, Entity entity, u8& outLevel, u8& outUnbiased, u8& outLevels,
+ f32& outSize) const {
+ const auto it = entries_.find(key(view, entity));
+ if (it == entries_.end()) return false;
+ outLevel = it->second.level;
+ outUnbiased = it->second.unbiased;
+ outLevels = it->second.levels;
+ outSize = it->second.size;
+ return true;
+ }
+
+ /**
+ * @brief Hold @p level up for inspection in this view, or @ref kNoPreview to
+ * stop.
+ *
+ * @details Deliberately NOT on the component. Written to the entity it would
+ * reach a shipped game, a second camera and the shadow pass, none of
+ * which anybody asked to change.
+ */
+ void preview(u32 view, Entity entity, u8 level) {
+ if (level == kNoPreview) previews_.erase(key(view, entity));
+ else previews_[key(view, entity)] = level;
+ }
+
+ /** @brief The level this view was told to show, or @ref kNoPreview. */
+ u8 previewOf(u32 view, Entity entity) const {
+ const auto it = previews_.find(key(view, entity));
+ return it == previews_.end() ? kNoPreview : it->second;
+ }
+
+ /**
+ * @brief What to DRAW: the preview if one names a level this group reaches,
+ * otherwise @p chosen.
+ *
+ * @details A preview past the last stand-in is ignored rather than clamped: a
+ * clamp would answer LOD1 to a request for LOD3 and look like the
+ * selector had spoken, and the level asked for does not exist.
+ */
+ u8 drawn(u32 view, Entity entity, u8 chosen, u8 levels) const {
+ const u8 held = previewOf(view, entity);
+ return held != kNoPreview && held <= levels ? held : chosen;
+ }
+
+ void clear() { entries_.clear(); previews_.clear(); }
usize size() const { return entries_.size(); }
+ /** @brief How many (view, entity) pairs are currently held up for inspection. */
+ usize previewCount() const { return previews_.size(); }
+
private:
struct Entry {
u64 stamp = 0;
+ f32 size = 0.0f;
u8 level = 0;
+ u8 unbiased = 0;
+ u8 levels = 0;
};
static u64 key(u32 view, Entity entity) {
@@ -64,6 +135,7 @@ private:
}
std::unordered_map<u64, Entry> entries_;
+ std::unordered_map<u64, u8> previews_;
u64 frame_ = 0;
};
diff --git a/src/esengine/renderer/plugins/MeshPlugin.cpp b/src/esengine/renderer/plugins/MeshPlugin.cpp
index 3bb519334..4a0497726 100644
--- a/src/esengine/renderer/plugins/MeshPlugin.cpp
+++ b/src/esengine/renderer/plugins/MeshPlugin.cpp
@@ -307,12 +307,20 @@ void MeshPlugin::collect(RenderCollectContext& collect_ctx) {
lod::boundingSphere(position, rotation, scale, localMin, localMax, centre, radius);
const f32 screenSize = lod::screenRelativeSize(ctx.view_projection, centre, radius);
auto& state = *collect_ctx.lod.state;
- const u8 level = lod::selectLevel(levels.set, screenSize,
- state.lastLevel(collect_ctx.lod.view, entity));
- state.remember(collect_ctx.lod.view, entity, level);
+ const u32 view = collect_ctx.lod.view;
+ const u8 level = lod::selectLevel(levels.set, screenSize, state.lastLevel(view, entity));
+ // The same size with no memory behind it. Recorded rather than derived
+ // later: the two differing IS hysteresis holding a level, and an editor
+ // that recomputed it would be a second selector free to disagree.
+ const u8 unbiased = lod::selectLevel(levels.set, screenSize, 0);
+ state.remember(view, entity, level, unbiased, levels.set.count, screenSize);
+ // The POLICY's answer, not the one a creator is holding up to look at:
+ // a preview is an editor's question about this view, and counting it
+ // would put it in a shipped frame's profile.
if (collect_ctx.lod.counts) collect_ctx.lod.counts->record(level);
- if (level == lod::kCulled) { ++collect_ctx.culled; continue; }
- resident = levels.mesh[level];
+ const u8 shown = state.drawn(view, entity, level, levels.set.count);
+ if (shown == lod::kCulled) { ++collect_ctx.culled; continue; }
+ resident = levels.mesh[shown];
}
u32 textureId = ctx.white_texture_id;
diff --git a/tests/renderer/test_lod_selection.cpp b/tests/renderer/test_lod_selection.cpp
index fd9a70542..5776d67b8 100644
--- a/tests/renderer/test_lod_selection.cpp
+++ b/tests/renderer/test_lod_selection.cpp
@@ -157,8 +157,8 @@ static void testViewOwnership() {
state.beginFrame();
CHECK(state.lastLevel(mainCamera, object) == 0, "an unseen pair starts unbiased");
- state.remember(mainCamera, object, 0);
- state.remember(minimap, object, 2);
+ state.remember(mainCamera, object, 0, 0, 2, 0.52f);
+ state.remember(minimap, object, 2, 2, 2, 0.52f);
CHECK(state.lastLevel(mainCamera, object) == 0 && state.lastLevel(minimap, object) == 2,
"one object is remembered at two levels by two views");
@@ -174,12 +174,66 @@ static void testViewOwnership() {
CHECK(before == 2 && state.size() == 0, "a pair no view asks about again is dropped");
}
+static void testDecisionRecorded() {
+ lod::LodViewState state;
+ const Entity object = Entity::make(9, 1);
+ const u32 view = 3;
+ u8 level = 9, unbiased = 9, levels = 9;
+ f32 size = -1.0f;
+
+ CHECK(!state.inspect(view, object, level, unbiased, levels, size),
+ "a pair this view never measured reports nothing, not level 0");
+
+ state.beginFrame();
+ state.remember(view, object, 0, 1, 2, 0.149f);
+ CHECK(state.inspect(view, object, level, unbiased, levels, size),
+ "a measured pair reports");
+ CHECK(level == 0 && unbiased == 1 && levels == 2 && size == 0.149f,
+ "the whole decision comes back, not just its outcome");
+ // The one explanation the component cannot give: the numbers on screen say
+ // LOD1 and the frame drew LOD0, and only the recorded pair says why.
+ CHECK(level != unbiased, "chosen and unbiased differing is hysteresis holding");
+}
+
+static void testPreviewOwnership() {
+ lod::LodViewState state;
+ const Entity object = Entity::make(4, 1);
+ const u32 edit = 1, play = 2;
+
+ state.beginFrame();
+ state.remember(edit, object, 0, 0, 2, 0.6f);
+ state.remember(play, object, 0, 0, 2, 0.6f);
+ CHECK(state.drawn(edit, object, 0, 2) == 0, "with no preview the chosen level is drawn");
+
+ state.preview(edit, object, 2);
+ CHECK(state.drawn(edit, object, 0, 2) == 2, "a preview is what that view draws");
+ CHECK(state.drawn(play, object, 0, 2) == 0, "and only that view — the pair is the key");
+
+ u8 level = 9, unbiased = 9, levels = 9;
+ f32 size = -1.0f;
+ state.inspect(edit, object, level, unbiased, levels, size);
+ CHECK(level == 0, "the recorded choice is untouched — a preview is not a decision");
+
+ // Leaving a preview must obey the selector again, not resume from what was
+ // held up: the choice went on being made and remembered underneath it.
+ state.preview(edit, object, lod::kNoPreview);
+ CHECK(state.drawn(edit, object, 0, 2) == 0, "back to auto is back to the chosen level");
+ CHECK(state.previewCount() == 0, "and the slot is gone, not merely equal to the choice");
+
+ // A group with two stand-ins has no LOD3 to hold up.
+ state.preview(edit, object, 3);
+ CHECK(state.drawn(edit, object, 0, 2) == 0,
+ "a preview past the last stand-in is ignored, not clamped to the last one");
+}
+
int main() {
testProjection();
testBoundingSphere();
testSelection();
testHysteresis();
testViewOwnership();
+ testDecisionRecorded();
+ testPreviewOwnership();
std::printf(g_failures ? "\n%d failure(s)\n" : "\nall LOD selection claims hold\n",
g_failures);
return g_failures ? 1 : 0;
diff --git a/tools/check-lod-authoring.mjs b/tools/check-lod-authoring.mjs
new file mode 100644
index 000000000..833281191
--- /dev/null
+++ b/tools/check-lod-authoring.mjs
@@ -0,0 +1,117 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+/**
+ * @file check-lod-authoring.mjs — a LODGroup is explainable, in both creator
+ * surfaces, without becoming component state.
+ *
+ * A LODGroup was authorable in the sense that its thresholds could be typed into,
+ * and in no other: nothing said which level was on screen, nothing said why, and
+ * the only way to see LOD2 was to walk the camera back until it appeared. What
+ * the `lod-authoring` editor check proves BEHAVES, this holds in SHAPE — the three
+ * ways it could be undone with no behaviour changing on the day it happened:
+ *
+ * 1 the editor working out a level itself, which is a second selector free to
+ * report LOD1 over a viewport drawing LOD0
+ * 2 the explanation reaching only one creator surface — the panel a person
+ * reads or the tool an agent calls, but not both
+ * 3 the preview becoming a field, which would put "what I am looking at" into
+ * a shipped game, a second camera and the shadow pass
+ *
+ * Deliberately about ONE component. Nothing in a name makes a view-dependent
+ * creator decision discoverable the way a `radius` makes a spatial one, and
+ * inventing a rule for the four that do not exist yet would be exactly the
+ * hand-written-list mistake check-gizmo-coverage was built out of. It generalises
+ * when there is a second subject to generalise FROM.
+ */
+import { readFileSync, existsSync, readdirSync, statSync } from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const EDITOR = path.join(ROOT, 'desktop', 'src');
+const SNAPSHOT = path.join(ROOT, 'docs', 'astro', 'src', 'data', 'components.generated.json');
+const TOOLS = path.join(ROOT, 'desktop', 'shared', 'toolCatalog.mjs');
+const DECORATORS = path.join(EDITOR, 'panels', 'inspector', 'componentDecorators.tsx');
+const VIEW_STATE = path.join(ROOT, 'src', 'esengine', 'renderer', 'lod', 'LodViewState.hpp');
+
+// The editor is an optional submodule and two of the three claims live in it.
+// Reported, never rounded down to a pass.
+if (!existsSync(EDITOR)) {
+ console.log('check-lod-authoring: no editor checkout — nothing was judged.');
+ process.exit(0);
+}
+
+const read = (p) => readFileSync(p, 'utf8');
+const problems = [];
+
+/** Every editor source, so claim 1 is about the editor rather than about one file. */
+function editorSources(dir = EDITOR, out = []) {
+ for (const entry of readdirSync(dir)) {
+ const full = path.join(dir, entry);
+ if (statSync(full).isDirectory()) editorSources(full, out);
+ else if (/\.tsx?$/.test(entry)) out.push(full);
+ }
+ return out;
+}
+
+// 1. The panel's level is the engine's, read back — and the band is not copied.
+// The weakest claim here, and it says so: a comparison is unfindable by text,
+// so what is held is the two steps a second selector must take first.
+
+const BAND = /\(\s*1(?:\.0)?\s*\+[^)]{0,60}hysteresis/i;
+for (const file of editorSources()) {
+ const src = read(file);
+ if (BAND.test(src)) {
+ problems.push(`${path.relative(ROOT, file)} applies the hysteresis band — that arithmetic is`
+ + " lod::selectLevel's, and a copy here is a second selector free to disagree with the picture");
+ }
+}
+if (!/Renderer\.lodInspect\(/.test(read(DECORATORS))) {
+ problems.push('the LODGroup panel no longer reads the level back from the frame that drew it'
+ + ' (Renderer.lodInspect) — whatever it shows now is its own opinion of the viewport');
+}
+
+// 2. Both creator surfaces, or neither is finished. An explanation a person can
+// read and an agent cannot is the same gap as a setting an agent can write and
+// a person cannot (check-project-settings, AUTHORING.audioConfig).
+if (!/id: 'core\.lodgroup\.[\w.]+'/.test(read(DECORATORS))) {
+ problems.push('no inspector decorator is registered for LODGroup — a person opening Details'
+ + ' cannot see which level the view chose');
+}
+const tools = read(TOOLS);
+for (const tool of ['get_lod_decision', 'set_lod_preview']) {
+ if (!tools.includes(`name: '${tool}'`)) {
+ problems.push(`the automation surface has no ${tool} — an agent asked to tune a LODGroup`
+ + ' cannot see what a person sees in Details');
+ }
+}
+
+// 3. A preview is what one view is showing, so it cannot be a field: on the
+// component it is one answer for every view, it serializes into the scene, and
+// it reaches a shipped game.
+const group = JSON.parse(read(SNAPSHOT)).components.find((c) => c.name === 'LODGroup');
+if (!group) {
+ problems.push('LODGroup is not in the component snapshot — has it been renamed?');
+} else {
+ const authored = (group.fields ?? []).filter((f) => /preview|forced|override/i.test(f.key));
+ if (authored.length) {
+ problems.push(`LODGroup declares ${authored.map((f) => f.key).join(', ')} — a level held up for`
+ + ' inspection belongs to a (view, entity) pair, not to the entity every view shares');
+ }
+}
+
+// An explanation is only one while the frame records BOTH answers: what it chose,
+// and what the bare thresholds asked for. Lose the second and "why is it still
+// LOD0" has nothing to answer it — the panel can only restate the level it showed.
+if (!/unbiased/.test(read(VIEW_STATE))) {
+ problems.push('LodViewState no longer remembers the unbiased level, so hysteresis holding a level'
+ + ' becomes unexplainable');
+}
+
+if (problems.length) {
+ console.error(`check-lod-authoring: ${problems.length} problem(s)`);
+ for (const p of problems) console.error(` ${p}`);
+ process.exit(1);
+}
+console.log('check-lod-authoring: the level is read back, both creator surfaces explain it,'
+ + ' and no preview is authored onto the component.');
diff --git a/tools/gates.mjs b/tools/gates.mjs
index b0ffceff7..9e4211fdf 100644
--- a/tools/gates.mjs
+++ b/tools/gates.mjs
@@ -185,6 +185,7 @@ export const GATES = [
{ id: 'shader-literals', run: 'node tools/check-shader-literals.mjs' },
{ id: 'import-settings', run: 'node tools/check-import-settings.mjs' },
{ id: 'gizmo-coverage', run: 'node tools/check-gizmo-coverage.mjs', needs: 'editor' },
+ { id: 'lod-authoring', run: 'node tools/check-lod-authoring.mjs', needs: 'editor' },
{ id: 'dirty-source', run: 'node tools/check-dirty-source.mjs', needs: 'editor' },
{ id: 'path-sandbox', run: 'node tools/check-path-sandbox.mjs' },
{ id: 'key-codes', run: 'node tools/check-key-codes.mjs' },