A fast 2D and 3D game engine — TypeScript SDK, C++/WebAssembly core, visual editor. Ship one project to web, desktop, WeChat MiniGames, playable ads, and native Android / iOS.
TypeScript 2d-game-engine3d3d-game-engineandroidcppecsgame-editorgame-enginegamedeviostypescriptwebassemblywebglwebgpuwechat-minigame
feat(lod): the frame records the whole decision, so the editor can explain it
esengine9327e21ef987
diff --git a/desktop b/desktopindex 28d74bc82..855dbbdfc 160000--- a/desktop+++ b/desktop@@ -1 +1 @@-Subproject commit 28d74bc828c8027abc4fd0f12ea45fe7f8111441+Subproject commit 855dbbdfcc2332b299cb582be1f0bbe62c20c11cdiff --git a/docs/astro/src/data/apiStability.generated.json b/docs/astro/src/data/apiStability.generated.jsonindex 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.mdindex 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): LocalizationPluginstatic 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 @experimentaldiff --git a/sdk/etc/index.native.api.md b/sdk/etc/index.native.api.mdindex 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): LocalizationPluginstatic 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 @experimentaldiff --git a/sdk/etc/index.node.api.md b/sdk/etc/index.node.api.mdindex 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): LocalizationPluginstatic 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 @experimentaldiff --git a/sdk/etc/minigame.api.md b/sdk/etc/minigame.api.mdindex 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): LocalizationPluginstatic 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 @experimentaldiff --git a/sdk/etc/wasm.api.md b/sdk/etc/wasm.api.mdindex 96667798d..514116653 100644--- a/sdk/etc/wasm.api.md+++ b/sdk/etc/wasm.api.md@@ -393,6 +393,7 @@ renderer_getTextureBytes: (() => number) | undefinedrenderer_getTriangles: () => numberrenderer_hasCapturedData: () => booleanrenderer_init: (width: number, height: number) => void+renderer_lodInspect: ((view: number, entity: number, outPtr: number) => number) | undefinedrenderer_pollFrameCapture: ((handle: number) => number) | undefinedrenderer_pollPreviewReadback: () => numberrenderer_pollSkeletalPreview: (preview: number) => number@@ -408,6 +409,7 @@ renderer_setColorSpace: ((linear: number) => void) | undefinedrenderer_setCullingMask: ((mask: number) => void) | undefinedrenderer_setDepthLayers: ((mask: number) => void) | undefinedrenderer_setEntityDrawOrder: ((registry: CppRegistry, entitiesPtr: number, count: number) => void) | undefined+renderer_setLodPreview: ((view: number, entity: number, level: number) => void) | undefinedrenderer_setStage: (stage: number) => voidrenderer_setTextureParams: (textureId: number, minFilter: number, magFilter: number, wrapS: number, wrapT: number) => voidrenderer_setViewId: ((view: number) => void) | undefineddiff --git a/sdk/etc/wechat.api.md b/sdk/etc/wechat.api.mdindex 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): LocalizationPluginstatic 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 @experimentaldiff --git a/sdk/src/core-render.ts b/sdk/src/core-render.tsindex 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.tsindex 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 drivingdiff --git a/sdk/src/ecs/bridge/nativeEngineApi.generated.ts b/sdk/src/ecs/bridge/nativeEngineApi.generated.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.cppindex 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 (editordiff --git a/src/esengine/bindings/RendererBindings.hpp b/src/esengine/bindings/RendererBindings.hppindex 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.cppindex 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.hppindex 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-sidediff --git a/src/esengine/renderer/lod/LodViewState.hpp b/src/esengine/renderer/lod/LodViewState.hppindex 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.cppindex 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.cppindex 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.mjsnew file mode 100644index 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.mjsindex 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' },