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): 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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): Promisconst 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.tsindex 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 maindiff --git a/sdk/src/runtime/playableRuntime.ts b/sdk/src/runtime/playableRuntime.tsindex 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 costdiff --git a/sdk/src/wasm.ts b/sdk/src/wasm.tsindex 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.cppindex 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 (editordiff --git a/src/esengine/bindings/RendererBindings.hpp b/src/esengine/bindings/RendererBindings.hppindex 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.cppindex 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.cppindex 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 isdiff --git a/src/esengine/renderer/draw/DrawList.hpp b/src/esengine/renderer/draw/DrawList.hppindex 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 esenginediff --git a/src/esengine/renderer/frame/PostProcessPipeline.cpp b/src/esengine/renderer/frame/PostProcessPipeline.cppindex 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 atdiff --git a/src/esengine/renderer/frame/PostProcessPipeline.hpp b/src/esengine/renderer/frame/PostProcessPipeline.hppindex 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.cppindex 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_POSTPROCESSpost_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);#endifdiff --git a/src/esengine/renderer/frame/RenderFrame.hpp b/src/esengine/renderer/frame/RenderFrame.hppindex 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.cppindex 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);+}