Skip to content

A fast 2D and 3D game engine — TypeScript SDK, C++/WebAssembly core, visual editor. Ship one project to web, desktop, WeChat MiniGames, playable ads, and native Android / iOS.

feat(render): layers painted in hierarchy order, so a panel covers the text of the panel under it; the Cocos UI layer uses it. Text takes an underline field; resources.load finds an image's spriteFrame and texture by path suffix

yhh21e0ee81a58d
diff --git a/sdk/etc/index.api.md b/sdk/etc/index.api.md
index d08d89c1a..74a3d7f9e 100644
--- a/sdk/etc/index.api.md
+++ b/sdk/etc/index.api.md
@@ -8345,7 +8345,7 @@ UIElement = 7
## Renderer — const @experimental
```
-{ init(width: number, height: number): void; resize(width: number, height: number): void; beginFrame(elapsedSec?: number): void; setOrigin(x: number, y: number, z: 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; setViewShading(view: number, mode: ViewShading): void; setMeshEdgeBuffers(enabled: boolean): void; setViewSkinWeights(view: number, entity: number | null, joint?: number): void; lightStatus(entity: number): LightStatus | null; shadowStatus(entity: number): ShadowStatus | null; setTextureParams(textureId: number, minFilter: number, magFilter: number, wrapS: number, wrapT: number): void; measureBitmapText(fontHandle: number, text: string, fontSize: number, spacing: number): { width: number; height: number; }; getStats(): RenderStats; captureNextFrame(): void; getCapturedData(): FrameCaptureData | null; hasCapturedData(): boolean; replayToDrawCall(drawCallIndex: number): void; getSnapshotImageData(): Promise<ImageData | null>; snapshotMatchesCapture(): boolean; }
+{ init(width: number, height: number): void; resize(width: number, height: number): void; beginFrame(elapsedSec?: number): void; setOrigin(x: number, y: number, z: 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; setTreeSortLayers(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; setViewShading(view: number, mode: ViewShading): void; setMeshEdgeBuffers(enabled: boolean): void; setViewSkinWeights(view: number, entity: number | null, joint?: number): void; lightStatus(entity: number): LightStatus | null; shadowStatus(entity: number): ShadowStatus | null; setTextureParams(textureId: number, minFilter: number, magFilter: number, wrapS: number, wrapT: number): void; measureBitmapText(fontHandle: number, text: string, fontSize: number, spacing: number): { width: number; height: number; }; getStats(): RenderStats; captureNextFrame(): void; getCapturedData(): FrameCaptureData | null; hasCapturedData(): boolean; replayToDrawCall(drawCallIndex: number): void; getSnapshotImageData(): Promise<ImageData | null>; snapshotMatchesCapture(): boolean; }
```
## ReplayReport — interface @experimental
diff --git a/sdk/etc/index.native.api.md b/sdk/etc/index.native.api.md
index 896edaced..460136ef5 100644
--- a/sdk/etc/index.native.api.md
+++ b/sdk/etc/index.native.api.md
@@ -8558,7 +8558,7 @@ UIElement = 7
## Renderer — const @experimental
```
-{ init(width: number, height: number): void; resize(width: number, height: number): void; beginFrame(elapsedSec?: number): void; setOrigin(x: number, y: number, z: 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; setViewShading(view: number, mode: ViewShading): void; setMeshEdgeBuffers(enabled: boolean): void; setViewSkinWeights(view: number, entity: number | null, joint?: number): void; lightStatus(entity: number): LightStatus | null; shadowStatus(entity: number): ShadowStatus | null; setTextureParams(textureId: number, minFilter: number, magFilter: number, wrapS: number, wrapT: number): void; measureBitmapText(fontHandle: number, text: string, fontSize: number, spacing: number): { width: number; height: number; }; getStats(): RenderStats; captureNextFrame(): void; getCapturedData(): FrameCaptureData | null; hasCapturedData(): boolean; replayToDrawCall(drawCallIndex: number): void; getSnapshotImageData(): Promise<ImageData | null>; snapshotMatchesCapture(): boolean; }
+{ init(width: number, height: number): void; resize(width: number, height: number): void; beginFrame(elapsedSec?: number): void; setOrigin(x: number, y: number, z: 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; setTreeSortLayers(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; setViewShading(view: number, mode: ViewShading): void; setMeshEdgeBuffers(enabled: boolean): void; setViewSkinWeights(view: number, entity: number | null, joint?: number): void; lightStatus(entity: number): LightStatus | null; shadowStatus(entity: number): ShadowStatus | null; setTextureParams(textureId: number, minFilter: number, magFilter: number, wrapS: number, wrapT: number): void; measureBitmapText(fontHandle: number, text: string, fontSize: number, spacing: number): { width: number; height: number; }; getStats(): RenderStats; captureNextFrame(): void; getCapturedData(): FrameCaptureData | null; hasCapturedData(): boolean; replayToDrawCall(drawCallIndex: number): void; getSnapshotImageData(): Promise<ImageData | null>; snapshotMatchesCapture(): boolean; }
```
## ReplayReport — interface @experimental
diff --git a/sdk/etc/index.node.api.md b/sdk/etc/index.node.api.md
index b328269df..4ffb03d50 100644
--- a/sdk/etc/index.node.api.md
+++ b/sdk/etc/index.node.api.md
@@ -8340,7 +8340,7 @@ UIElement = 7
## Renderer — const @experimental
```
-{ init(width: number, height: number): void; resize(width: number, height: number): void; beginFrame(elapsedSec?: number): void; setOrigin(x: number, y: number, z: 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; setViewShading(view: number, mode: ViewShading): void; setMeshEdgeBuffers(enabled: boolean): void; setViewSkinWeights(view: number, entity: number | null, joint?: number): void; lightStatus(entity: number): LightStatus | null; shadowStatus(entity: number): ShadowStatus | null; setTextureParams(textureId: number, minFilter: number, magFilter: number, wrapS: number, wrapT: number): void; measureBitmapText(fontHandle: number, text: string, fontSize: number, spacing: number): { width: number; height: number; }; getStats(): RenderStats; captureNextFrame(): void; getCapturedData(): FrameCaptureData | null; hasCapturedData(): boolean; replayToDrawCall(drawCallIndex: number): void; getSnapshotImageData(): Promise<ImageData | null>; snapshotMatchesCapture(): boolean; }
+{ init(width: number, height: number): void; resize(width: number, height: number): void; beginFrame(elapsedSec?: number): void; setOrigin(x: number, y: number, z: 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; setTreeSortLayers(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; setViewShading(view: number, mode: ViewShading): void; setMeshEdgeBuffers(enabled: boolean): void; setViewSkinWeights(view: number, entity: number | null, joint?: number): void; lightStatus(entity: number): LightStatus | null; shadowStatus(entity: number): ShadowStatus | null; setTextureParams(textureId: number, minFilter: number, magFilter: number, wrapS: number, wrapT: number): void; measureBitmapText(fontHandle: number, text: string, fontSize: number, spacing: number): { width: number; height: number; }; getStats(): RenderStats; captureNextFrame(): void; getCapturedData(): FrameCaptureData | null; hasCapturedData(): boolean; replayToDrawCall(drawCallIndex: number): void; getSnapshotImageData(): Promise<ImageData | null>; snapshotMatchesCapture(): boolean; }
```
## ReplayReport — interface @experimental
diff --git a/sdk/etc/minigame.api.md b/sdk/etc/minigame.api.md
index 3ea31e524..43b95ef14 100644
--- a/sdk/etc/minigame.api.md
+++ b/sdk/etc/minigame.api.md
@@ -8635,7 +8635,7 @@ UIElement = 7
## Renderer — const @experimental
```
-{ init(width: number, height: number): void; resize(width: number, height: number): void; beginFrame(elapsedSec?: number): void; setOrigin(x: number, y: number, z: 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; setViewShading(view: number, mode: ViewShading): void; setMeshEdgeBuffers(enabled: boolean): void; setViewSkinWeights(view: number, entity: number | null, joint?: number): void; lightStatus(entity: number): LightStatus | null; shadowStatus(entity: number): ShadowStatus | null; setTextureParams(textureId: number, minFilter: number, magFilter: number, wrapS: number, wrapT: number): void; measureBitmapText(fontHandle: number, text: string, fontSize: number, spacing: number): { width: number; height: number; }; getStats(): RenderStats; captureNextFrame(): void; getCapturedData(): FrameCaptureData | null; hasCapturedData(): boolean; replayToDrawCall(drawCallIndex: number): void; getSnapshotImageData(): Promise<ImageData | null>; snapshotMatchesCapture(): boolean; }
+{ init(width: number, height: number): void; resize(width: number, height: number): void; beginFrame(elapsedSec?: number): void; setOrigin(x: number, y: number, z: 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; setTreeSortLayers(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; setViewShading(view: number, mode: ViewShading): void; setMeshEdgeBuffers(enabled: boolean): void; setViewSkinWeights(view: number, entity: number | null, joint?: number): void; lightStatus(entity: number): LightStatus | null; shadowStatus(entity: number): ShadowStatus | null; setTextureParams(textureId: number, minFilter: number, magFilter: number, wrapS: number, wrapT: number): void; measureBitmapText(fontHandle: number, text: string, fontSize: number, spacing: number): { width: number; height: number; }; getStats(): RenderStats; captureNextFrame(): void; getCapturedData(): FrameCaptureData | null; hasCapturedData(): boolean; replayToDrawCall(drawCallIndex: number): void; getSnapshotImageData(): Promise<ImageData | null>; snapshotMatchesCapture(): boolean; }
```
## ReplayReport — interface @experimental
diff --git a/sdk/etc/wasm.api.md b/sdk/etc/wasm.api.md
index 7ebc66132..d16ee4cbd 100644
--- a/sdk/etc/wasm.api.md
+++ b/sdk/etc/wasm.api.md
@@ -542,6 +542,7 @@ renderer_setShadow2DSoftSamples: ((samples: number) => void) | undefined
renderer_setShadowDistance: ((distance: number) => void) | undefined
renderer_setStage: (stage: number) => void
renderer_setTextureParams: (textureId: number, minFilter: number, magFilter: number, wrapS: number, wrapT: number) => void
+renderer_setTreeSortLayers: ((mask: number) => void) | undefined
renderer_setViewId: ((view: number) => void) | undefined
renderer_setViewLighting: ((mode: number, rotationDegrees: number, keyIntensity: number, fillIntensity: number, skyIntensity: number, showSky: boolean) => void) | undefined
renderer_setViewShading: ((view: number, mode: number) => void) | undefined
diff --git a/sdk/etc/wechat.api.md b/sdk/etc/wechat.api.md
index 576033af0..c143e18fe 100644
--- a/sdk/etc/wechat.api.md
+++ b/sdk/etc/wechat.api.md
@@ -8347,7 +8347,7 @@ UIElement = 7
## Renderer — const @experimental
```
-{ init(width: number, height: number): void; resize(width: number, height: number): void; beginFrame(elapsedSec?: number): void; setOrigin(x: number, y: number, z: 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; setViewShading(view: number, mode: ViewShading): void; setMeshEdgeBuffers(enabled: boolean): void; setViewSkinWeights(view: number, entity: number | null, joint?: number): void; lightStatus(entity: number): LightStatus | null; shadowStatus(entity: number): ShadowStatus | null; setTextureParams(textureId: number, minFilter: number, magFilter: number, wrapS: number, wrapT: number): void; measureBitmapText(fontHandle: number, text: string, fontSize: number, spacing: number): { width: number; height: number; }; getStats(): RenderStats; captureNextFrame(): void; getCapturedData(): FrameCaptureData | null; hasCapturedData(): boolean; replayToDrawCall(drawCallIndex: number): void; getSnapshotImageData(): Promise<ImageData | null>; snapshotMatchesCapture(): boolean; }
+{ init(width: number, height: number): void; resize(width: number, height: number): void; beginFrame(elapsedSec?: number): void; setOrigin(x: number, y: number, z: 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; setTreeSortLayers(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; setViewShading(view: number, mode: ViewShading): void; setMeshEdgeBuffers(enabled: boolean): void; setViewSkinWeights(view: number, entity: number | null, joint?: number): void; lightStatus(entity: number): LightStatus | null; shadowStatus(entity: number): ShadowStatus | null; setTextureParams(textureId: number, minFilter: number, magFilter: number, wrapS: number, wrapT: number): void; measureBitmapText(fontHandle: number, text: string, fontSize: number, spacing: number): { width: number; height: number; }; getStats(): RenderStats; captureNextFrame(): void; getCapturedData(): FrameCaptureData | null; hasCapturedData(): boolean; replayToDrawCall(drawCallIndex: number): void; getSnapshotImageData(): Promise<ImageData | null>; snapshotMatchesCapture(): boolean; }
```
## ReplayReport — interface @experimental
diff --git a/sdk/src/cocos/assetManager.ts b/sdk/src/cocos/assetManager.ts
index 34b378d63..f261bc198 100644
--- a/sdk/src/cocos/assetManager.ts
+++ b/sdk/src/cocos/assetManager.ts
@@ -28,6 +28,8 @@ export interface ResourceEntry {
kind: string;
/** The Cocos uuid of the asset, which `loadAny({ uuid })` names it by. */
uuid?: string;
+ /** For a sub-asset of an image named by a path suffix (`icon/spriteFrame`): which asset of the file it is. @internal */
+ as?: 'SpriteFrame' | 'Texture2D';
}
export type ResourceManifest = Record<string, Record<string, ResourceEntry>>;
@@ -103,7 +105,8 @@ function named<T extends Asset>(asset: T, entry: ResourceEntry): T {
/** An asset of a kind the layer does not load: not a fault of the asset, so a directory load goes on without it. */
export class UnsupportedAssetKind extends Error {}
-async function loadEntry(entry: ResourceEntry, type: AssetCtor | null): Promise<Asset> {
+async function loadEntry(entry: ResourceEntry, asked: AssetCtor | null): Promise<Asset> {
+ const type = asked ?? (entry.as === 'SpriteFrame' ? SpriteFrame : entry.as === 'Texture2D' ? Texture2D : null);
const assets = assetsFor(getCurrentWorld());
switch (entry.kind) {
case 'prefab': {
@@ -164,8 +167,13 @@ export class Bundle {
private async entry_(path: string): Promise<ResourceEntry> {
const entries = await this.entries_();
const found = entries[stripExt(path)] ?? entries[path];
- if (!found) throw new Error(`cocos compat: bundle "${this.name}" has no asset "${path}"`);
- return found;
+ if (found) return found;
+ // An image is one file here and three assets in Cocos: the image (`icon`), its texture (`icon/texture`) and its sprite frame
+ // (`icon/spriteFrame`). The suffix names which one a script wants, and the file is the same.
+ const sub = /^(.*)\/(spriteFrame|texture)$/.exec(path);
+ const image = sub ? entries[sub[1]!] : undefined;
+ if (sub && image?.kind === 'texture') return { ...image, as: sub[2] === 'spriteFrame' ? 'SpriteFrame' : 'Texture2D' };
+ throw new Error(`cocos compat: bundle "${this.name}" has no asset "${path}"`);
}
load(...args: unknown[]): void {
@@ -176,7 +184,7 @@ export class Bundle {
const out: Asset[] = [];
for (let i = 0; i < list.length; i++) {
const entry = await this.entry_(list[i]!);
- const key = `${this.name}/${entry.path}`;
+ const key = `${this.name}/${entry.path}#${entry.as ?? type?.name ?? ''}`;
let asset = loaded.get(key);
if (!asset) loaded.add(key, (asset = named(await loadEntry(entry, type), entry)));
out.push(asset);
@@ -200,7 +208,7 @@ export class Bundle {
for (let i = 0; i < keys.length; i++) {
const entry = entries[keys[i]!]!;
try {
- const key = `${this.name}/${entry.path}`;
+ const key = `${this.name}/${entry.path}#${entry.as ?? type?.name ?? ''}`;
let asset = loaded.get(key);
if (!asset) loaded.add(key, (asset = named(await loadEntry(entry, type), entry)));
out.push(asset);
diff --git a/sdk/src/cocos/ui/pass.ts b/sdk/src/cocos/ui/pass.ts
index 26a840e67..e9488b5aa 100644
--- a/sdk/src/cocos/ui/pass.ts
+++ b/sdk/src/cocos/ui/pass.ts
@@ -15,6 +15,7 @@ import { setCurrentWorld } from '../node';
import { declareWidget } from './widget';
import { rectAnchorsPlugin, setRectAnchorsScreenFallback } from '../../ui/layout/rect-anchors';
import { SystemLabel } from '../../ecs/systemLabels';
+import { Renderer } from '../../render/renderer';
import { getDefaultContext } from '../../ecs/context';
import { layoutAll, declareLayout } from './layout';
import { declareControls } from './controls';
@@ -33,6 +34,9 @@ function screenOrVisible(screen: ScreenLayoutData | undefined): ScreenLayoutData
return { valid: true, left: -halfW, right: halfW, bottom: -halfH, top: halfH, safeLeft: -halfW, safeRight: halfW, safeBottom: -halfH, safeTop: halfH, scale: 1, viewportW: v.width, viewportH: v.height };
}
+/** Cocos's UI_2D layer, as a bit of the engine's layer mask. */
+const TREE_ORDERED_LAYERS = (1 << 25) >>> 0;
+
export function declareUiPass(): void {
declareWidget();
declareLayout();
@@ -60,6 +64,9 @@ export function declareUiPass(): void {
addSystemToSchedule(Schedule.PreUpdate, defineSystem(
[Res(UICameraInfo), Res(ScreenLayout), Res(ScreenScaling)],
(camera, screen: ScreenLayoutData | undefined, scaling: ScreenScalingData | undefined) => {
+ // Cocos paints a layer's nodes in hierarchy order, a label no different from an image: a popup covers the text of the view under
+ // it. The UI layer is therefore painted in tree order, which is a setting of the renderer and so is stated where the pass is.
+ Renderer.setTreeSortLayers(TREE_ORDERED_LAYERS);
if (scaling) setProjectDesign(scaling.designWidth, scaling.designHeight, scaling.scaleMode);
setUiCameraData(camera ?? null);
setScreenLayout(screenOrVisible(screen));
diff --git a/sdk/src/ecs/bridge/nativeBindings.ts b/sdk/src/ecs/bridge/nativeBindings.ts
index b30919f80..04dbb4da1 100644
--- a/sdk/src/ecs/bridge/nativeBindings.ts
+++ b/sdk/src/ecs/bridge/nativeBindings.ts
@@ -188,6 +188,8 @@ export const RENDERER_OPTIONAL_BINDINGS = {
setOrigin: 'es_renderer_setOrigin',
/** 2.5D depth layers; hosts predating the feature simply stay painter-ordered. */
setDepthLayers: 'es_renderer_setDepthLayers',
+ /** Layers painted in hierarchy order (cocos compat); hosts predating it paint them as before. */
+ setTreeSortLayers: 'es_renderer_setTreeSortLayers',
/** Camera culling mask; hosts predating it draw every layer, as they always did. */
setCullingMask: 'es_renderer_setCullingMask',
/** Closes the frame. A host predating it released the swapchain image at
diff --git a/sdk/src/ecs/bridge/nativeEngineApi.generated.ts b/sdk/src/ecs/bridge/nativeEngineApi.generated.ts
index be76dc8da..083b6e27f 100644
--- a/sdk/src/ecs/bridge/nativeEngineApi.generated.ts
+++ b/sdk/src/ecs/bridge/nativeEngineApi.generated.ts
@@ -218,6 +218,7 @@ export interface NativeEngineApi {
renderer_setColorSpace?(linear: number): void;
renderer_setCullingMask?(mask: number): void;
renderer_setDepthLayers?(mask: number): void;
+ renderer_setTreeSortLayers?(mask: number): void;
renderer_setDepthPrepass?(on: boolean): void;
renderer_setEntityDrawOrder?(registry: unknown, entitiesPtr: number, count: number): void;
renderer_setLodPreview?(view: number, entity: number, level: number): void;
@@ -555,6 +556,7 @@ export function createNativeEngineApi(
bind('renderer_setColorSpace', 'es_renderer_setColorSpace', false);
bind('renderer_setCullingMask', 'es_renderer_setCullingMask', false);
bind('renderer_setDepthLayers', 'es_renderer_setDepthLayers', false);
+ bind('renderer_setTreeSortLayers', 'es_renderer_setTreeSortLayers', false);
bind('renderer_setDepthPrepass', 'es_renderer_setDepthPrepass', false);
bind('renderer_setEntityDrawOrder', 'es_renderer_setEntityDrawOrder', true);
bind('renderer_setLodPreview', 'es_renderer_setLodPreview', false);
diff --git a/sdk/src/ecs/bridge/nativeRenderer.ts b/sdk/src/ecs/bridge/nativeRenderer.ts
index a73bf659b..fbe6a0d5f 100644
--- a/sdk/src/ecs/bridge/nativeRenderer.ts
+++ b/sdk/src/ecs/bridge/nativeRenderer.ts
@@ -129,6 +129,10 @@ export function createNativeRendererBackend(
const fn = scope[RENDERER_OPTIONAL_BINDINGS.setDepthLayers];
if (typeof fn === 'function') (fn as (m: number) => void)(mask >>> 0);
},
+ setTreeSortLayers: (mask): void => {
+ const fn = scope[RENDERER_OPTIONAL_BINDINGS.setTreeSortLayers];
+ if (typeof fn === 'function') (fn as (m: number) => void)(mask >>> 0);
+ },
setCullingMask: (mask): void => {
const fn = scope[RENDERER_OPTIONAL_BINDINGS.setCullingMask];
if (typeof fn === 'function') (fn as (m: number) => void)(mask >>> 0);
diff --git a/sdk/src/render/renderer.ts b/sdk/src/render/renderer.ts
index bef7b1295..e87ce6b45 100644
--- a/sdk/src/render/renderer.ts
+++ b/sdk/src/render/renderer.ts
@@ -73,6 +73,7 @@ export interface RendererBackend {
setViewport(x: number, y: number, w: number, h: number): void;
setYSortLayers(mask: number): void;
setDepthLayers(mask: number): void;
+ setTreeSortLayers(mask: number): void;
setCullingMask(mask: number): void;
setViewId(view: number): void;
lodInspect(view: number, entity: number): LodDecision | null;
@@ -250,6 +251,7 @@ function wasmBackend(m: ESEngineModule): RendererBackend {
setViewport: (x, y, w, h) => m.renderer_setViewport(x, y, w, h),
setYSortLayers: (mask) => m.renderer_setYSortLayers?.(mask >>> 0),
setDepthLayers: (mask) => m.renderer_setDepthLayers?.(mask >>> 0),
+ setTreeSortLayers: (mask) => m.renderer_setTreeSortLayers?.(mask >>> 0),
setCullingMask: (mask) => m.renderer_setCullingMask?.(mask >>> 0),
setViewId: (view) => m.renderer_setViewId?.(view >>> 0),
lodInspect: (view, entity) => {
@@ -662,6 +664,15 @@ export const Renderer = {
backend?.setDepthLayers(mask);
},
+ /**
+ * Layers (bits 0..31) whose draws are painted in hierarchy order: a sprite, a label and a shape stack as their entities do in the tree
+ * (a preorder walk), instead of by shader and depth. The order a scene of nodes has in an authoring tool, and the one in which a panel
+ * covers the text of the panel under it.
+ */
+ setTreeSortLayers(mask: number): void {
+ backend?.setTreeSortLayers(mask);
+ },
+
/**
* Sorting layers (bits 0..31) the NEXT collect draws — `Camera.cullingMask`.
* Set per camera before submitting it; a layer with no bit (outside 0..31) is
diff --git a/sdk/src/ui/core/text.ts b/sdk/src/ui/core/text.ts
index 40500940f..43cd8bdb6 100644
--- a/sdk/src/ui/core/text.ts
+++ b/sdk/src/ui/core/text.ts
@@ -169,6 +169,7 @@ export const Text = defineComponent<TextData>('Text', {
shadowBlur: 0,
shadowOffsetX: 0,
shadowOffsetY: 0,
+ underline: false,
richText: false,
renderMode: TextRenderMode.Auto,
layer: 0,
@@ -195,6 +196,7 @@ export const Text = defineComponent<TextData>('Text', {
enum: enumOptions(TextOverflow),
tooltip: 'What text too big for its box does. Needs a layout box: Clip and Ellipsis drop the lines past its height and trim a line past its width; Shrink sets the text smaller until it fits both.',
},
+ underline: { tooltip: 'Draw a line under each line of text, using the underscore of the font.' },
renderMode: { enum: enumOptions(TextRenderMode) },
boxWidth: { tooltip: 'Layout box width for a text with no UINode (0 = no box: the origin is the box). Alignment, wrapping and overflow work inside it. A UINode, if present, decides the box instead.' },
boxHeight: { tooltip: 'Layout box height (0 = none). Vertical alignment and Clip/Ellipsis need it.' },
diff --git a/sdk/src/wasm.ts b/sdk/src/wasm.ts
index d94850433..ca00501dd 100644
--- a/sdk/src/wasm.ts
+++ b/sdk/src/wasm.ts
@@ -714,6 +714,7 @@ export interface ESEngineModule {
/** Bitmask of layers 0..31 that y-sort within the layer (top-down occlusion). */
renderer_setYSortLayers?(mask: number): void;
renderer_setDepthLayers?(mask: number): void;
+ renderer_setTreeSortLayers?(mask: number): void;
renderer_setQualityBudgets?(atlasSize: number, cellSize: number,
cascades: number, particleLimit: number): void;
renderer_setShadowDistance?(distance: number): void;
diff --git a/sdk/tests/cocos/globals.test.ts b/sdk/tests/cocos/globals.test.ts
index 21ae3141c..8f1bcfeb4 100644
--- a/sdk/tests/cocos/globals.test.ts
+++ b/sdk/tests/cocos/globals.test.ts
@@ -175,6 +175,11 @@ describe('resources and assetManager', () => {
// an image needs the engine's loader to become a texture, and says so when there is none
const texture = await load<unknown>((cb) => resources.load('icon/gold', cb));
expect(texture.err?.message).toMatch(/asset loader/);
+ // the sprite frame and the texture of an image are named by a suffix on its path, and are found as the image is
+ const frame = await load<unknown>((cb) => resources.load('icon/gold/spriteFrame', cb));
+ expect(frame.err?.message).toMatch(/asset loader/);
+ const asTexture = await load<unknown>((cb) => resources.load('icon/gold/texture', cb));
+ expect(asTexture.err?.message).toMatch(/asset loader/);
});
it('has bundles by name, from the manifest', async () => {
diff --git a/src/esengine/bindings/RendererBindings.cpp b/src/esengine/bindings/RendererBindings.cpp
index c92738fc8..e07a42447 100644
--- a/src/esengine/bindings/RendererBindings.cpp
+++ b/src/esengine/bindings/RendererBindings.cpp
@@ -1243,6 +1243,10 @@ void renderer_setYSortLayers(u32 mask) {
if (auto* frame = g_renderFrame) frame->setYSortLayers(mask);
}
+void renderer_setTreeSortLayers(u32 mask) {
+ if (auto* frame = g_renderFrame) frame->setTreeSortLayers(mask);
+}
+
// The 2.5D opt-in, per sorting layer. Same shape as setYSortLayers because it is
// the same kind of declaration: how a layer resolves the draws inside it.
void renderer_setQualityBudgets(u32 atlasSize, u32 cellSize, u32 cascades, u32 particleLimit) {
diff --git a/src/esengine/bindings/RendererBindings.hpp b/src/esengine/bindings/RendererBindings.hpp
index df431ccac..4968e4f5f 100644
--- a/src/esengine/bindings/RendererBindings.hpp
+++ b/src/esengine/bindings/RendererBindings.hpp
@@ -270,6 +270,7 @@ void engine_prepareMeshPrograms(u32 rowsPtr, u32 count, u32 outPtr);
void renderer_setClearColor(f32 r, f32 g, f32 b, f32 a);
void renderer_setViewport(i32 x, i32 y, i32 w, i32 h);
void renderer_setYSortLayers(u32 mask);
+void renderer_setTreeSortLayers(u32 mask);
/** 2.5D opt-in: bit i ⇒ layer i resolves by real depth. Same shape as y-sort. */
void renderer_setDepthLayers(u32 mask);
/** Sorting layers the next collect draws (bit i = layer i). Set per camera. */
diff --git a/src/esengine/bindings/WebSDKEntry.cpp b/src/esengine/bindings/WebSDKEntry.cpp
index 5833ceb91..ddc2bdbfe 100644
--- a/src/esengine/bindings/WebSDKEntry.cpp
+++ b/src/esengine/bindings/WebSDKEntry.cpp
@@ -791,6 +791,7 @@ EMSCRIPTEN_BINDINGS(esengine_renderer) {
emscripten::function("renderer_setClearColor", &esengine::renderer_setClearColor);
emscripten::function("renderer_setViewport", &esengine::renderer_setViewport);
emscripten::function("renderer_setYSortLayers", &esengine::renderer_setYSortLayers);
+ emscripten::function("renderer_setTreeSortLayers", &esengine::renderer_setTreeSortLayers);
emscripten::function("renderer_setDepthLayers", &esengine::renderer_setDepthLayers);
emscripten::function("renderer_setQualityBudgets", &esengine::renderer_setQualityBudgets);
emscripten::function("renderer_setShadowDistance", &esengine::renderer_setShadowDistance);
diff --git a/src/esengine/renderer/draw/BatchBuilder.cpp b/src/esengine/renderer/draw/BatchBuilder.cpp
index acaf8cd0f..562fd91ca 100644
--- a/src/esengine/renderer/draw/BatchBuilder.cpp
+++ b/src/esengine/renderer/draw/BatchBuilder.cpp
@@ -96,6 +96,9 @@ void pushBatchDraw(DrawList& drawList, const ClipState& clips,
cmd.sort_key = resolve == DrawList::LayerOrder::YSort
? DrawCommand::buildSortKeyYSorted(stage, layer, key.y, key.shaderId,
key.blend, 0, order)
+ : resolve == DrawList::LayerOrder::Tree
+ ? DrawCommand::buildSortKeyTree(stage, layer, drawList.treeSequenceOf(key.entity), key.shaderId,
+ key.blend, 0, order)
: DrawCommand::buildSortKey(stage, layer, key.shaderId,
key.blend, 0, key.depth, key.materialId, order,
key.instanceCount != 0 && key.vertexBuffer != BufferHandle::Invalid
diff --git a/src/esengine/renderer/draw/DrawCommand.hpp b/src/esengine/renderer/draw/DrawCommand.hpp
index e78754a3c..41ae8d929 100644
--- a/src/esengine/renderer/draw/DrawCommand.hpp
+++ b/src/esengine/renderer/draw/DrawCommand.hpp
@@ -318,6 +318,24 @@ struct DrawCommand {
return stageKey | layerKey | orderBits(order) | yKey | shaderKey | blendKey | flagsKey;
}
+ // Tree-ordered variant: the entity's place in the hierarchy walk takes the field worldY has in a y-sorted layer, so draws of every kind
+ // stack as their nodes do, and shader/blend/flags only separate what shares a node.
+ static u64 buildSortKeyTree(RenderStage stage, i32 layer, u32 sequence,
+ u32 shaderId, BlendMode blend, u16 stateFlags,
+ i32 order = 0) {
+ i32 normalizedLayer = std::clamp(layer + 32768, 0, 65535);
+ u64 layerKey = static_cast<u64>(normalizedLayer & 0xFFFF) << 48;
+
+ u64 stageKey = static_cast<u64>(stage) << 38;
+ u64 sequenceKey = static_cast<u64>(sequence & 0xFFFFFF) << 14;
+
+ u64 shaderKey = static_cast<u64>(shaderId & 0xFF) << 6;
+ u64 blendKey = blendBits(blend) << 3;
+ u64 flagsKey = static_cast<u64>(stateFlags & 0x03) << 1;
+
+ return stageKey | layerKey | orderBits(order) | sequenceKey | shaderKey | blendKey | flagsKey;
+ }
+
/** @brief Finds @p texId in this command's texture set, adds it (returns its slot), or
* -1 if the set is full. Used by the merge to assign per-vertex sampler slots.
* @p limit is how many slots the merge may spend: a frame with a 2D shadow
diff --git a/src/esengine/renderer/draw/DrawList.hpp b/src/esengine/renderer/draw/DrawList.hpp
index f8929047e..82f2441eb 100644
--- a/src/esengine/renderer/draw/DrawList.hpp
+++ b/src/esengine/renderer/draw/DrawList.hpp
@@ -125,6 +125,20 @@ public:
void setYSortMask(u32 mask) { ysort_mask_ = mask; }
u32 ySortMask() const { return ysort_mask_; }
+ // Bit i set ⇒ layer i (0..31) is painted in TREE order: its draws sort by where their entity stands in the hierarchy (a preorder walk,
+ // children in their list order), whatever they are — a sprite, a label, a shape. That is how a scene of nodes is stacked in an authoring
+ // tool that has no per-material or per-depth ordering, and it is the only order in which a panel can cover the text of the panel
+ // beneath it: ordered by shader, every label would land above every image of the layer.
+ void setTreeMask(u32 mask) { tree_mask_ = mask; }
+ u32 treeMask() const { return tree_mask_; }
+ /// The preorder position of each entity, by entity index. Rebuilt once per collect, only while a layer is tree-ordered.
+ void setTreeSequence(std::vector<u32>&& sequence) { tree_sequence_ = std::move(sequence); }
+ void clearTreeSequence() { tree_sequence_.clear(); }
+ u32 treeSequenceOf(Entity entity) const {
+ const u32 index = entity.index();
+ return index < tree_sequence_.size() ? tree_sequence_[index] : 0u;
+ }
+
// Bit i set ⇒ layer i resolves its contents by real depth: opaque draws write
// the depth buffer and sort front-to-back, blended ones test against it without
// writing and stay in painter's order. This is the 2.5D opt-in.
@@ -158,7 +172,7 @@ public:
}
/** @brief How one sorting layer resolves the draws inside it. */
- enum class LayerOrder : u8 { Painter, YSort, Depth };
+ enum class LayerOrder : u8 { Painter, YSort, Depth, Tree };
/**
* @brief The one answer for @p layer, from two masks that are two spellings of
@@ -175,6 +189,8 @@ public:
if (layer < 0 || layer >= 32) return LayerOrder::Painter;
const u32 bit = 1u << layer;
if (ysort_mask_ & bit) return LayerOrder::YSort;
+ // Tree order is a stated painter's order and depth is a measured one; a layer saying both has asked for the stated one.
+ if (tree_mask_ & bit) return LayerOrder::Tree;
if (depth_mask_ & bit) return LayerOrder::Depth;
return LayerOrder::Painter;
}
@@ -276,6 +292,8 @@ private:
/// Members of a SortingGroup, by entity id — empty in the common frame.
std::unordered_map<u32, GroupIdentity> group_identities_;
u32 ysort_mask_ = 0;
+ u32 tree_mask_ = 0;
+ std::vector<u32> tree_sequence_;
u32 depth_mask_ = 0;
/// Any command pushed this collect that tests or writes depth — see needsDepth.
bool depth_required_ = false;
diff --git a/src/esengine/renderer/frame/RenderFrame.cpp b/src/esengine/renderer/frame/RenderFrame.cpp
index 61381669c..09fec1510 100644
--- a/src/esengine/renderer/frame/RenderFrame.cpp
+++ b/src/esengine/renderer/frame/RenderFrame.cpp
@@ -1320,6 +1320,39 @@ void RenderFrame::buildSortingGroups(ecs::Registry& registry) {
}
}
+void RenderFrame::buildTreeSequence(ecs::Registry& registry) {
+ if (draw_list_.treeMask() == 0) {
+ draw_list_.clearTreeSequence();
+ return;
+ }
+ // One preorder walk over every tree of the world: a root is an entity with no live parent, taken in storage order (which is the painter's
+ // order of roots), and its children follow in their list order. The same order a scene's nodes stack in.
+ std::vector<u32> sequence;
+ u32 counter = 1;
+ std::vector<Entity> pending;
+ auto walk = [&](Entity root) {
+ pending.push_back(root);
+ while (!pending.empty()) {
+ const Entity entity = pending.back();
+ pending.pop_back();
+ if (!registry.valid(entity)) continue;
+ const u32 index = entity.index();
+ if (index >= sequence.size()) sequence.resize(index + 1, 0u);
+ sequence[index] = counter++;
+ const auto* children = registry.tryGet<ecs::Children>(entity);
+ if (!children) continue;
+ for (auto child = children->entities.rbegin(); child != children->entities.rend(); ++child) pending.push_back(*child);
+ }
+ };
+ auto transforms = registry.view<ecs::Transform>();
+ for (auto entity : transforms) {
+ const auto* parent = registry.tryGet<ecs::Parent>(entity);
+ if (parent && parent->entity != INVALID_ENTITY && registry.valid(parent->entity)) continue;
+ walk(entity);
+ }
+ draw_list_.setTreeSequence(std::move(sequence));
+}
+
void RenderFrame::buildSpriteMasks(ecs::Registry& registry) {
// 255 is the stencil attachment's, not a budget: refs are per FRAME and a mask past
// the last one is dropped rather than aliased onto another mask's cut.
@@ -2523,7 +2556,7 @@ void RenderFrame::collectAll(ecs::Registry& registry, bool sceneGBuffer) {
// gathering lights and walking one render type's population are different
// work that a single total cannot be told apart by.
{ ES_PROFILE_SCOPE("render.collect.clip"); buildClipState(); }
- { ES_PROFILE_SCOPE("render.collect.sorting"); buildSortingGroups(registry); }
+ { ES_PROFILE_SCOPE("render.collect.sorting"); buildSortingGroups(registry); buildTreeSequence(registry); }
// After the groups, because a mask's reach is stated in the order a group may own.
{ ES_PROFILE_SCOPE("render.collect.spriteMasks"); buildSpriteMasks(registry); }
{ ES_PROFILE_SCOPE("render.collect.lights"); collectLights(registry); }
diff --git a/src/esengine/renderer/frame/RenderFrame.hpp b/src/esengine/renderer/frame/RenderFrame.hpp
index eab26ccb7..0217accdb 100644
--- a/src/esengine/renderer/frame/RenderFrame.hpp
+++ b/src/esengine/renderer/frame/RenderFrame.hpp
@@ -291,6 +291,8 @@ public:
/// Layers (bits 0..31) that sort by world Y within the layer — see DrawList::setYSortMask.
void setYSortLayers(u32 mask) { draw_list_.setYSortMask(mask); }
+ /// Layers (bits 0..31) that paint in hierarchy order within the layer — see DrawList::setTreeMask.
+ void setTreeSortLayers(u32 mask) { draw_list_.setTreeMask(mask); }
void setDepthLayers(u32 mask) {
draw_list_.setDepthMask(mask);
// Through the one applier: the mask is no longer the whole answer, only
@@ -669,6 +671,8 @@ private:
void buildSpriteMasks(ecs::Registry& registry);
/// Resolves every SortingGroup into the per-entity identity the draw path reads.
void buildSortingGroups(ecs::Registry& registry);
+ /// The hierarchy position of every entity, for the layers that paint in tree order (DrawList::setTreeMask).
+ void buildTreeSequence(ecs::Registry& registry);
/// Adds a finalized list's cost to this frame's tally (see the definition).
void accumulateStats(const DrawList& list);
/// The overlay pass's body: the projection its geometry was built for, then
diff --git a/tests/renderer/test_batch_builder.cpp b/tests/renderer/test_batch_builder.cpp
index 1eddf0031..da606b46a 100644
--- a/tests/renderer/test_batch_builder.cpp
+++ b/tests/renderer/test_batch_builder.cpp
@@ -2419,6 +2419,40 @@ TEST_CASE("depth layer: y-sort wins when a layer declares both") {
CHECK(h.list.layerOrder(5) == DrawList::LayerOrder::Painter);
}
+// A layer painted in tree order stacks its draws as their entities stand in the hierarchy walk, whatever they are drawn with: a label
+// (one shader) of a panel underneath must land below the image (another) of the panel above, which shader order cannot give.
+TEST_CASE("tree layer: draws stack by their entity's place in the walk, not by shader") {
+ Harness h;
+ h.list.setTreeMask(1u << 4);
+ // entity index 1 stands later in the walk than index 2
+ h.list.setTreeSequence({0u, 2u, 1u});
+ BatchVertex quad[4] = {};
+
+ BatchDrawKey later = quadKey(1, /*layer=*/4);
+ later.entity = Entity::fromRaw(1);
+ later.shaderId = 3; // shader order alone would draw this one first
+ BatchDrawKey earlier = quadKey(2, /*layer=*/4);
+ earlier.entity = Entity::fromRaw(2);
+ earlier.shaderId = 9;
+
+ appendQuad(h.pool, h.list, h.clips, quad, later);
+ appendQuad(h.pool, h.list, h.clips, quad, earlier);
+ h.list.finalize(h.pool);
+
+ CHECK(h.list.layerOrder(4) == DrawList::LayerOrder::Tree);
+ REQUIRE(h.list.mergedDrawCallCount() == 2);
+ CHECK(h.list.command(0).texture_ids[0] == 2);
+ CHECK(h.list.command(1).texture_ids[0] == 1);
+}
+
+// Y-sort is a stated order of its own; a layer asking for both keeps the one it had before tree order existed.
+TEST_CASE("tree layer: y-sort wins when a layer declares both") {
+ Harness h;
+ h.list.setYSortMask(1u << 4);
+ h.list.setTreeMask(1u << 4);
+ CHECK(h.list.layerOrder(4) == DrawList::LayerOrder::YSort);
+}
+
// ─── Order within a layer ────────────────────────────────────────────────────
// The author's explicit answer to "what is on top of what", inside one layer. Each case
// below is one the layer's own ordering gets wrong on purpose, so it measures an override.