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(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.mdindex 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 @experimentaldiff --git a/sdk/etc/index.native.api.md b/sdk/etc/index.native.api.mdindex 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 @experimentaldiff --git a/sdk/etc/index.node.api.md b/sdk/etc/index.node.api.mdindex 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 @experimentaldiff --git a/sdk/etc/minigame.api.md b/sdk/etc/minigame.api.mdindex 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 @experimentaldiff --git a/sdk/etc/wasm.api.md b/sdk/etc/wasm.api.mdindex 7ebc66132..d16ee4cbd 100644--- a/sdk/etc/wasm.api.md+++ b/sdk/etc/wasm.api.md@@ -542,6 +542,7 @@ renderer_setShadow2DSoftSamples: ((samples: number) => void) | undefinedrenderer_setShadowDistance: ((distance: number) => void) | undefinedrenderer_setStage: (stage: number) => voidrenderer_setTextureParams: (textureId: number, minFilter: number, magFilter: number, wrapS: number, wrapT: number) => void+renderer_setTreeSortLayers: ((mask: number) => void) | undefinedrenderer_setViewId: ((view: number) => void) | undefinedrenderer_setViewLighting: ((mode: number, rotationDegrees: number, keyIntensity: number, fillIntensity: number, skyIntensity: number, showSky: boolean) => void) | undefinedrenderer_setViewShading: ((view: number, mode: number) => void) | undefineddiff --git a/sdk/etc/wechat.api.md b/sdk/etc/wechat.api.mdindex 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 @experimentaldiff --git a/sdk/src/cocos/assetManager.ts b/sdk/src/cocos/assetManager.tsindex 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.tsindex 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): ScreenLayoutDatareturn { 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.tsindex 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 atdiff --git a/sdk/src/ecs/bridge/nativeEngineApi.generated.ts b/sdk/src/ecs/bridge/nativeEngineApi.generated.tsindex 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.tsindex 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.tsindex 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) isdiff --git a/sdk/src/ui/core/text.ts b/sdk/src/ui/core/text.tsindex 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.tsindex 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.tsindex 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 noneconst 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.cppindex 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.hppindex 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.cppindex 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.cppindex 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::Invaliddiff --git a/src/esengine/renderer/draw/DrawCommand.hpp b/src/esengine/renderer/draw/DrawCommand.hppindex 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 shadowdiff --git a/src/esengine/renderer/draw/DrawList.hpp b/src/esengine/renderer/draw/DrawList.hppindex 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.cppindex 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.hppindex 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, thendiff --git a/tests/renderer/test_batch_builder.cpp b/tests/renderer/test_batch_builder.cppindex 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.