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): a sorting layer can resolve by depth instead of painter's order

esengine7fd4aaed9a71
diff --git a/sdk/src/app/app.ts b/sdk/src/app/app.ts
index af337de36..4f130b3e8 100644
--- a/sdk/src/app/app.ts
+++ b/sdk/src/app/app.ts
@@ -1168,6 +1168,14 @@ export interface WebAppOptions {
* setting (Project Settings → Rendering); change later via Renderer.setYSortLayers.
*/
ySortLayers?: number;
+ /**
+ * Bitmask of render layers (bits 0..31) that resolve by real depth instead of
+ * painter's order — the 2.5D opt-in. Opaque draws in such a layer write the
+ * depth buffer and sort front-to-back; blended ones test without writing and
+ * stay back-to-front. A layer that also y-sorts keeps y-sorting.
+ * Project-level setting (Project Settings → Rendering).
+ */
+ depthLayers?: number;
/**
* Project color space (Project Settings → Rendering). 'linear' renders in
* linear light: sRGB decode on sample, linear blending in sRGB-format
@@ -1222,6 +1230,7 @@ export function createWebApp(module: ESEngineModule, options?: WebAppOptions): A
// Always applied (not only when set): the renderer outlives the App on realm
// reloads, so a fresh App must reset a prior session's y-sort state too.
module.renderer_setYSortLayers?.((options?.ySortLayers ?? 0) >>> 0);
+ module.renderer_setDepthLayers?.((options?.depthLayers ?? 0) >>> 0);
app.addPlugin(corePlugin);
app.setPipeline(new RenderPipeline());
diff --git a/sdk/src/ecs/bridge/nativeBindings.ts b/sdk/src/ecs/bridge/nativeBindings.ts
index ddb9b4f64..b2279786f 100644
--- a/sdk/src/ecs/bridge/nativeBindings.ts
+++ b/sdk/src/ecs/bridge/nativeBindings.ts
@@ -105,6 +105,7 @@ export const RENDERER_BINDINGS = {
setStage: 'es_renderer_setStage',
setViewport: 'es_renderer_setViewport',
setYSortLayers: 'es_renderer_setYSortLayers',
+ setDepthLayers: 'es_renderer_setDepthLayers',
/** Host-specific: the drawable size, which no wasm entry point has. */
surfaceSize: 'es_renderer_surfaceSize',
} as const;
diff --git a/sdk/src/ecs/bridge/nativeEngineApi.generated.ts b/sdk/src/ecs/bridge/nativeEngineApi.generated.ts
index 7a5db462e..0f72e5c6d 100644
--- a/sdk/src/ecs/bridge/nativeEngineApi.generated.ts
+++ b/sdk/src/ecs/bridge/nativeEngineApi.generated.ts
@@ -144,6 +144,7 @@ export interface NativeEngineApi {
renderer_resize?(width: number, height: number): void;
renderer_setClearColor?(r: number, g: number, b: number, a: number): void;
renderer_setColorSpace?(linear: number): void;
+ renderer_setDepthLayers?(mask: number): void;
renderer_setEntityClipRect?(entity: number, x: number, y: number, w: number, h: number): void;
renderer_setEntityDrawOrder?(registry: unknown, entitiesPtr: number, count: number): void;
renderer_setEntityStencilMask?(entity: number, refValue: number): void;
@@ -373,6 +374,7 @@ export function createNativeEngineApi(
bind('renderer_resize', 'es_renderer_resize', false);
bind('renderer_setClearColor', 'es_renderer_setClearColor', false);
bind('renderer_setColorSpace', 'es_renderer_setColorSpace', false);
+ bind('renderer_setDepthLayers', 'es_renderer_setDepthLayers', false);
bind('renderer_setEntityClipRect', 'es_renderer_setEntityClipRect', false);
bind('renderer_setEntityDrawOrder', 'es_renderer_setEntityDrawOrder', true);
bind('renderer_setEntityStencilMask', 'es_renderer_setEntityStencilMask', false);
diff --git a/sdk/src/runtime/miniGameRuntime.ts b/sdk/src/runtime/miniGameRuntime.ts
index bfaec0a7d..95c498505 100644
--- a/sdk/src/runtime/miniGameRuntime.ts
+++ b/sdk/src/runtime/miniGameRuntime.ts
@@ -90,6 +90,8 @@ export interface MiniGameRuntimeConfig {
audioConfig?: AudioProjectConfig;
/** Bitmask of render layers (0..31) that y-sort within the layer (Project Settings → Rendering). */
ySortLayers?: number;
+ /** Bitmask of render layers (0..31) that resolve by real depth (2.5D). */
+ depthLayers?: number;
/** Project color space — 'linear' boots the linear-light pipeline (Project Settings → Rendering). */
colorSpace?: 'gamma' | 'linear';
/** Project camera fit (Project Settings → Display) — letterboxes the design resolution
@@ -150,6 +152,7 @@ export async function initMiniGameRuntime(config: MiniGameRuntimeConfig): Promis
const app = createWebApp(module, {
renderSurface: { kind: 'gl-context', handle: glHandle },
ySortLayers: config.ySortLayers,
+ depthLayers: config.depthLayers,
colorSpace: config.colorSpace,
screenFit: config.screenFit,
getViewportSize: () => ({
diff --git a/sdk/src/runtime/packagedRuntime.ts b/sdk/src/runtime/packagedRuntime.ts
index 3743e9455..1ff77a18c 100644
--- a/sdk/src/runtime/packagedRuntime.ts
+++ b/sdk/src/runtime/packagedRuntime.ts
@@ -37,6 +37,8 @@ export interface PackagedGameConfig {
scenes?: Array<{ name: string; path: string }>;
/** Bitmask of render layers (0..31) that y-sort within the layer. */
ySortLayers?: number;
+ /** Bitmask of render layers (0..31) that resolve by real depth (2.5D). */
+ depthLayers?: number;
/** Project color space — 'linear' boots the linear-light pipeline. */
colorSpace?: 'gamma' | 'linear';
/** Project camera fit (design resolution + scale mode) — letterboxes the main
diff --git a/sdk/src/runtime/playableRuntime.ts b/sdk/src/runtime/playableRuntime.ts
index a5a498e26..9785cbe2b 100644
--- a/sdk/src/runtime/playableRuntime.ts
+++ b/sdk/src/runtime/playableRuntime.ts
@@ -47,6 +47,8 @@ export interface PlayableRuntimeConfig {
audioConfig?: AudioProjectConfig;
/** Bitmask of render layers (0..31) that y-sort within the layer (Project Settings → Rendering). */
ySortLayers?: number;
+ /** Bitmask of render layers (0..31) that resolve by real depth (2.5D). */
+ depthLayers?: number;
manifest?: AddressableManifest | null;
}
@@ -82,6 +84,7 @@ export async function initPlayableRuntime(config: PlayableRuntimeConfig): Promis
// The playable boot pre-creates the app, so the project's y-sort layers are
// applied here rather than through createWebApp options.
if (config.ySortLayers) module.renderer_setYSortLayers?.(config.ySortLayers >>> 0);
+ if (config.depthLayers) module.renderer_setDepthLayers?.(config.depthLayers >>> 0);
// Alias logical paths onto the embedded map (both spellings the cook may
// emit) — the aliases point at the SAME data-URL strings, so path refs cost
diff --git a/sdk/src/wasm.ts b/sdk/src/wasm.ts
index 50e408aec..22df65690 100644
--- a/sdk/src/wasm.ts
+++ b/sdk/src/wasm.ts
@@ -368,6 +368,7 @@ export interface ESEngineModule {
renderer_setViewport(x: number, y: number, w: number, h: number): void;
/** 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_setColorSpace?(linear: number): void;
renderer_setTextureParams(textureId: number, minFilter: number, magFilter: number, wrapS: number, wrapT: number): void;
diff --git a/src/esengine/bindings/RendererBindings.cpp b/src/esengine/bindings/RendererBindings.cpp
index c48a8b077..3335e2109 100644
--- a/src/esengine/bindings/RendererBindings.cpp
+++ b/src/esengine/bindings/RendererBindings.cpp
@@ -569,6 +569,12 @@ void renderer_setYSortLayers(u32 mask) {
if (auto* frame = g_renderFrame) frame->setYSortLayers(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_setDepthLayers(u32 mask) {
+ if (auto* frame = g_renderFrame) frame->setDepthLayers(mask);
+}
+
void renderer_setColorSpace(u32 linear) {
// Valid pre-init: the global reaches every later shader compile, and
// RenderFrame::init adopts it. A live frame applies immediately (editor
diff --git a/src/esengine/bindings/RendererBindings.hpp b/src/esengine/bindings/RendererBindings.hpp
index b9d034487..a187dd466 100644
--- a/src/esengine/bindings/RendererBindings.hpp
+++ b/src/esengine/bindings/RendererBindings.hpp
@@ -109,6 +109,8 @@ f64 renderer_getTextureBytes();
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);
+/** 2.5D opt-in: bit i ⇒ layer i resolves by real depth. Same shape as y-sort. */
+void renderer_setDepthLayers(u32 mask);
/** Project colorSpace: 1 = linear-light rendering (set before shaders compile). */
void renderer_setColorSpace(u32 linear);
void renderer_diagnose();
diff --git a/src/esengine/bindings/WebSDKEntry.cpp b/src/esengine/bindings/WebSDKEntry.cpp
index cf5301ebd..f87842d78 100644
--- a/src/esengine/bindings/WebSDKEntry.cpp
+++ b/src/esengine/bindings/WebSDKEntry.cpp
@@ -529,6 +529,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_setDepthLayers", &esengine::renderer_setDepthLayers);
emscripten::function("renderer_setColorSpace", &esengine::renderer_setColorSpace);
emscripten::function("renderer_setEntityClipRect", &esengine::renderer_setEntityClipRect);
emscripten::function("renderer_clearEntityClipRect", &esengine::renderer_clearEntityClipRect);
diff --git a/src/esengine/renderer/draw/BatchBuilder.cpp b/src/esengine/renderer/draw/BatchBuilder.cpp
index 64e6656e1..ef3af00df 100644
--- a/src/esengine/renderer/draw/BatchBuilder.cpp
+++ b/src/esengine/renderer/draw/BatchBuilder.cpp
@@ -49,14 +49,32 @@ void pushBatchDraw(DrawList& drawList, const ClipState& clips,
if (indexCount == 0) return;
DrawCommand cmd{};
- const bool ysorted = key.layer >= 0 && key.layer < 32 &&
- ((drawList.ySortMask() >> key.layer) & 1u) != 0;
- cmd.sort_key = ysorted
- ? DrawCommand::buildSortKeyYSorted(key.stage, key.layer, key.y, key.shaderId,
+ const auto order = drawList.layerOrder(key.layer);
+
+ // A depth layer decides its own stage and depth state; every other layer takes
+ // what the caller resolved from the material. The rule is the physical one, so
+ // it is derived rather than declared: an opaque draw may write depth and sorts
+ // front-to-back (the key inverts its depth bits for the Opaque stage, which is
+ // what makes early-z pay off), while a blended draw MUST NOT write — writing is
+ // how translucent sprites clip each other into black edges — so it only tests,
+ // and stays in back-to-front painter's order. Nobody should have to declare a
+ // fact about alpha compositing per material.
+ RenderStage stage = key.stage;
+ bool depthTest = key.depthTest;
+ bool depthWrite = key.depthWrite;
+ if (order == DrawList::LayerOrder::Depth) {
+ const bool opaque = key.blend == BlendMode::None;
+ stage = opaque ? RenderStage::Opaque : RenderStage::Transparent;
+ depthTest = true;
+ depthWrite = opaque;
+ }
+
+ cmd.sort_key = order == DrawList::LayerOrder::YSort
+ ? DrawCommand::buildSortKeyYSorted(stage, key.layer, key.y, key.shaderId,
key.blend, 0)
- : DrawCommand::buildSortKey(key.stage, key.layer, key.shaderId,
+ : DrawCommand::buildSortKey(stage, key.layer, key.shaderId,
key.blend, 0, key.depth, key.materialId);
- cmd.stage = key.stage;
+ cmd.stage = stage;
cmd.index_offset = indexOffset;
cmd.index_count = indexCount;
cmd.vertex_byte_offset = vertexByteOffset;
@@ -66,8 +84,8 @@ void pushBatchDraw(DrawList& drawList, const ClipState& clips,
cmd.blend_mode = key.blend;
cmd.layout_id = key.layoutId;
cmd.material_id = key.materialId;
- cmd.depth_test = key.depthTest;
- cmd.depth_write = key.depthWrite;
+ cmd.depth_test = depthTest;
+ cmd.depth_write = depthWrite;
cmd.cull = key.cull;
// The Batch stream always samples a texture (white fallback at minimum); other
// streams bind one only when the draw actually has one (the shape stream is
diff --git a/src/esengine/renderer/draw/DrawList.hpp b/src/esengine/renderer/draw/DrawList.hpp
index b1b7a7938..62ee875e7 100644
--- a/src/esengine/renderer/draw/DrawList.hpp
+++ b/src/esengine/renderer/draw/DrawList.hpp
@@ -48,6 +48,34 @@ public:
void setYSortMask(u32 mask) { ysort_mask_ = mask; }
u32 ySortMask() const { return ysort_mask_; }
+ // 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.
+ void setDepthMask(u32 mask) { depth_mask_ = mask; }
+ u32 depthMask() const { return depth_mask_; }
+
+ /** @brief How one sorting layer resolves the draws inside it. */
+ enum class LayerOrder : u8 { Painter, YSort, Depth };
+
+ /**
+ * @brief The one answer for @p layer, from two masks that are two spellings of
+ * the same question.
+ *
+ * @details Y-sort is a depth PROJECTED from world Y and depth is the real thing;
+ * a layer declaring both has said two contradictory things, and there is
+ * no order that satisfies them. Y-sort wins so that a project which had
+ * it before renders exactly as it did — the resolution belongs here, in
+ * one pure function, rather than in each caller's idea of precedence.
+ * Layers outside 0..31 have no bit and are therefore painter-ordered.
+ */
+ LayerOrder layerOrder(i32 layer) const {
+ if (layer < 0 || layer >= 32) return LayerOrder::Painter;
+ const u32 bit = 1u << layer;
+ if (ysort_mask_ & bit) return LayerOrder::YSort;
+ if (depth_mask_ & bit) return LayerOrder::Depth;
+ return LayerOrder::Painter;
+ }
+
private:
struct SortEntry {
u64 key;
@@ -60,6 +88,7 @@ private:
// per-frame heap alloc in finalize()
u32 merged_draw_calls_ = 0;
u32 ysort_mask_ = 0;
+ u32 depth_mask_ = 0;
};
} // namespace esengine
diff --git a/src/esengine/renderer/frame/PostProcessPipeline.cpp b/src/esengine/renderer/frame/PostProcessPipeline.cpp
index 7e228f6dd..e58341895 100644
--- a/src/esengine/renderer/frame/PostProcessPipeline.cpp
+++ b/src/esengine/renderer/frame/PostProcessPipeline.cpp
@@ -82,7 +82,7 @@ void PostProcessPipeline::ensureFBOs() {
FramebufferSpec origSpec;
origSpec.width = width_;
origSpec.height = height_;
- origSpec.depthStencil = false;
+ origSpec.depthStencil = scene_needs_depth_;
origSpec.colorFormat = interFmt;
// Bilinear intermediates: fullscreen passes sample at texel centers
// (where LINEAR == NEAREST), but Kawase blur deliberately samples at
diff --git a/src/esengine/renderer/frame/PostProcessPipeline.hpp b/src/esengine/renderer/frame/PostProcessPipeline.hpp
index d0ae83247..090256429 100644
--- a/src/esengine/renderer/frame/PostProcessPipeline.hpp
+++ b/src/esengine/renderer/frame/PostProcessPipeline.hpp
@@ -179,6 +179,24 @@ public:
* carries the linear->sRGB encode. Overrides bypass.
*/
void setLinearOutput(bool linear) { linear_output_ = linear; }
+
+ /**
+ * @brief Whether the scene target needs a depth attachment.
+ *
+ * @details A depth buffer is per-frame memory and clear bandwidth (≈8MB at 1080p),
+ * which a project with no depth layer should not pay for a feature it does
+ * not use. Drops the scene FBO when the answer changes so the next
+ * ensureFBOs rebuilds it with the right attachments — the same way resize
+ * handles a size change.
+ */
+ void setSceneNeedsDepth(bool needs) {
+ if (needs == scene_needs_depth_) return;
+ scene_needs_depth_ = needs;
+ if (fboOriginalCreated_) {
+ fboOriginal_.reset();
+ fboOriginalCreated_ = false;
+ }
+ }
bool linearOutput() const { return linear_output_; }
/**
@@ -285,6 +303,7 @@ private:
bool inFrame_ = false;
bool bypass_ = false;
bool linear_output_ = false;
+ bool scene_needs_depth_ = false;
u32 currentFBO_ = 0;
TextureHandle sceneTexture_ = TextureHandle::Invalid;
diff --git a/src/esengine/renderer/frame/RenderFrame.cpp b/src/esengine/renderer/frame/RenderFrame.cpp
index 47b75b11a..0f85e1d78 100644
--- a/src/esengine/renderer/frame/RenderFrame.cpp
+++ b/src/esengine/renderer/frame/RenderFrame.cpp
@@ -137,6 +137,9 @@ void RenderFrame::init(u32 width, u32 height) {
#ifdef ES_ENABLE_POSTPROCESS
post_process_ = makeUnique<PostProcessPipeline>(device_, context_, resource_manager_);
post_process_->setLinearOutput(linear_color_);
+ // Depth layers may have been declared before the pipeline existed (the mask
+ // arrives with the project, init happens on the first frame).
+ post_process_->setSceneNeedsDepth(draw_list_.depthMask() != 0);
post_process_->init(width, height);
#endif
diff --git a/src/esengine/renderer/frame/RenderFrame.hpp b/src/esengine/renderer/frame/RenderFrame.hpp
index feee022f0..a3390b731 100644
--- a/src/esengine/renderer/frame/RenderFrame.hpp
+++ b/src/esengine/renderer/frame/RenderFrame.hpp
@@ -160,6 +160,13 @@ public:
/// Layers (bits 0..31) that sort by world Y within the layer — see DrawList::setYSortMask.
void setYSortLayers(u32 mask) { draw_list_.setYSortMask(mask); }
+ void setDepthLayers(u32 mask) {
+ draw_list_.setDepthMask(mask);
+ // The scene target needs a depth attachment exactly when some layer resolves
+ // by depth; before init there is no pipeline yet, and it reads the mask itself.
+ if (post_process_) post_process_->setSceneNeedsDepth(mask != 0);
+ }
+ u32 depthLayers() const { return draw_list_.depthMask(); }
/**
* @brief Switch the frame to linear-light rendering (project colorSpace).
diff --git a/tests/renderer/test_batch_builder.cpp b/tests/renderer/test_batch_builder.cpp
index bb45e4094..536b292b4 100644
--- a/tests/renderer/test_batch_builder.cpp
+++ b/tests/renderer/test_batch_builder.cpp
@@ -308,3 +308,63 @@ TEST_CASE("finalize: draws with different depth state never coalesce") {
CHECK(h.list.mergedDrawCallCount() == 2);
}
+
+// A depth layer resolves its own stage and depth state from the one physical fact
+// that decides them: whether the draw reads the destination. Nobody declares this
+// per material, because getting it wrong is not a preference — a blended draw that
+// writes depth clips its neighbours into black edges.
+TEST_CASE("depth layer: an opaque draw writes depth and lands in the Opaque stage") {
+ Harness h;
+ h.list.setDepthMask(1u << 4);
+ BatchVertex quad[4] = {};
+
+ BatchDrawKey key = quadKey(42, /*layer=*/4);
+ key.blend = BlendMode::None;
+ appendQuad(h.pool, h.list, h.clips, quad, key);
+
+ REQUIRE(h.list.commandCount() == 1);
+ CHECK(h.list.command(0).stage == RenderStage::Opaque);
+ CHECK(h.list.command(0).depth_test == true);
+ CHECK(h.list.command(0).depth_write == true);
+}
+
+TEST_CASE("depth layer: a blended draw tests depth but never writes it") {
+ Harness h;
+ h.list.setDepthMask(1u << 4);
+ BatchVertex quad[4] = {};
+
+ appendQuad(h.pool, h.list, h.clips, quad, quadKey(42, /*layer=*/4));
+
+ REQUIRE(h.list.commandCount() == 1);
+ CHECK(h.list.command(0).stage == RenderStage::Transparent);
+ CHECK(h.list.command(0).depth_test == true);
+ CHECK(h.list.command(0).depth_write == false);
+}
+
+// The whole point of making it a layer property: a project that declares no depth
+// layer must render exactly as it did, down to the pipeline state.
+TEST_CASE("depth layer: a painter layer is untouched by the opt-in") {
+ Harness h;
+ h.list.setDepthMask(1u << 4);
+ BatchVertex quad[4] = {};
+
+ BatchDrawKey key = quadKey(42, /*layer=*/5); // not the depth layer
+ key.blend = BlendMode::None;
+ appendQuad(h.pool, h.list, h.clips, quad, key);
+
+ REQUIRE(h.list.commandCount() == 1);
+ CHECK(h.list.command(0).stage == RenderStage::Transparent);
+ CHECK(h.list.command(0).depth_test == false);
+}
+
+// Y-sort is a depth projected from world Y; real depth is the thing itself. A layer
+// claiming both has said two contradictory things, and y-sort wins so that a project
+// which had it keeps rendering as it did.
+TEST_CASE("depth layer: y-sort wins when a layer declares both") {
+ Harness h;
+ h.list.setYSortMask(1u << 4);
+ h.list.setDepthMask(1u << 4);
+
+ CHECK(h.list.layerOrder(4) == DrawList::LayerOrder::YSort);
+ CHECK(h.list.layerOrder(5) == DrawList::LayerOrder::Painter);
+}