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.

fix(render): batching outranked the order that makes the picture

esengine9ab2b9569591
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 8101a1494..dd0b06f5b 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -29,6 +29,21 @@ published separately; it ships inside the editor.
### Changed
+- **A blended draw now sorts by depth before material.** The sort key ranked
+ material above depth for every stage, so within one sorting layer three
+ semi-transparent sprites at different z on materials B, A, B did not necessarily
+ composite far-to-near — batching outranked the ordering that produces the
+ picture. Correctness comes first for the stages where order IS the result: the
+ Transparent and Overlay stages now spend the key's bits on depth, then shader,
+ blend, flags and material. Opaque is unchanged — its result does not depend on
+ the order, so material still groups first and depth only breaks ties for early-z.
+ Draws at one z (the ordinary 2D case, where the sorting layer does the work) keep
+ batching exactly as before, because their depth bits are identical and material
+ still decides. Blended depth also widened from 14 bits to 20 — about a 0.004 step
+ near z=10 — taking the bits from material, which is only a batching hint in the
+ key (`canMergeWith` compares the full handle, so a truncated one costs a merge and
+ never a wrong one).
+
- **`world.getEntitiesWithComponents()` returns a `readonly Entity[]`.** The array
it hands back is the query cache's own entry, not a copy — sorting or pushing to
it reorders or corrupts what every later reader of that query sees. Nothing in
diff --git a/src/esengine/renderer/draw/DrawCommand.hpp b/src/esengine/renderer/draw/DrawCommand.hpp
index a75b61150..a11042218 100644
--- a/src/esengine/renderer/draw/DrawCommand.hpp
+++ b/src/esengine/renderer/draw/DrawCommand.hpp
@@ -69,8 +69,9 @@ struct DrawCommand {
// Texture is no longer part of the sort key: dropping it lets draws that differ only
// by texture sort adjacent and coalesce into one multi-texture batch (up to 8 textures,
// selected per-vertex in the shader). Order within a layer is otherwise unchanged.
- // Material identity sorts above depth (like shader does) so same-material draws group
- // adjacent for the merge, at the usual batching-over-cross-material-depth tradeoff.
+ // Below stage the field order depends on it: a blended draw composites onto what is
+ // already there, so its depth order IS the result and outranks batching, while an
+ // opaque draw is order-independent, so material groups first and depth breaks ties.
//
// Layer outranks stage, and that order is load-bearing. A sorting layer is a promise
// the user made about what draws on top of what; a stage is how one layer resolves
@@ -80,8 +81,9 @@ struct DrawCommand {
// meaning inverted. Within a layer the 3D order is the right one: opaque first
// (front-to-back, early-z), then blended (back-to-front).
//
- // [63:48] layer | [47:44] stage | [43:36] shader | [35:33] blend
- // [32:31] flags | [30:14] material | [13:0] depth
+ // [63:48] layer | [47:44] stage, then 44 bits whose order the stage decides:
+ // opaque [43:36] shader | [35:33] blend | [32:31] flags | [30:14] material | [13:0] depth
+ // blended [43:24] depth | [23:16] shader | [15:13] blend | [12:11] flags | [10:0] material
static u64 buildSortKey(RenderStage stage, i32 layer, u32 shaderId,
BlendMode blend, u16 stateFlags, f32 depth, u32 materialId = 0) {
i32 normalizedLayer = std::clamp(layer + 32768, 0, 65535);
@@ -89,26 +91,32 @@ struct DrawCommand {
u64 stageKey = static_cast<u64>(stage) << 44;
- u64 shaderKey = static_cast<u64>(shaderId & 0xFF) << 36;
- u64 blendKey = static_cast<u64>(blend) << 33;
- u64 flagsKey = static_cast<u64>(stateFlags & 0x03) << 31;
- u64 materialKey = (static_cast<u64>(materialId) & 0x1FFFF) << 14;
-
// Order-preserving float mapping — monotonic over the FULL float range.
// The old [-1,1] normalize-and-truncate silently wrapped any real-world z
// (e.g. a backdrop at z=-5 sorted as if nearest), and had the painter's
// order inverted for the blended stages. Camera looks down -z, so larger
// z = nearer: transparent/overlay draw back-to-front (far first, near
// lands on top); opaque draws front-to-back (early-z friendly).
- u32 depthBits;
- if (stage == RenderStage::Transparent || stage == RenderStage::Overlay) {
- depthBits = orderedFloatBits(depth) >> 18;
- } else {
- depthBits = (~orderedFloatBits(depth)) >> 18;
+ const bool blended = stage == RenderStage::Transparent || stage == RenderStage::Overlay;
+ u32 orderedDepth = blended ? orderedFloatBits(depth) : ~orderedFloatBits(depth);
+
+ // Blended spends its bits on depth (20: sign, exponent, 11 mantissa — a step of
+ // ~0.004 around z=10) and leaves material 11. Material here is a batching hint,
+ // not identity: truncating it costs a merge, and canMergeWith compares in full.
+ if (blended) {
+ return layerKey | stageKey
+ | (static_cast<u64>(orderedDepth >> 12) << 24)
+ | (static_cast<u64>(shaderId & 0xFF) << 16)
+ | (static_cast<u64>(blend) << 13)
+ | (static_cast<u64>(stateFlags & 0x03) << 11)
+ | (static_cast<u64>(materialId) & 0x7FF);
}
- u64 depthKey = static_cast<u64>(depthBits & 0x3FFF);
-
- return stageKey | layerKey | shaderKey | blendKey | flagsKey | materialKey | depthKey;
+ return layerKey | stageKey
+ | (static_cast<u64>(shaderId & 0xFF) << 36)
+ | (static_cast<u64>(blend) << 33)
+ | (static_cast<u64>(stateFlags & 0x03) << 31)
+ | ((static_cast<u64>(materialId) & 0x1FFFF) << 14)
+ | static_cast<u64>(orderedDepth >> 18);
}
// Order-preserving float → u32: flip the sign bit for positives, all bits for
diff --git a/tests/renderer/test_batch_builder.cpp b/tests/renderer/test_batch_builder.cpp
index e970069bf..9d85444ea 100644
--- a/tests/renderer/test_batch_builder.cpp
+++ b/tests/renderer/test_batch_builder.cpp
@@ -465,3 +465,103 @@ TEST_CASE("stencil: on one layer, material — not submission or depth — decid
CHECK((h.list.command(0).state_flags & CMD_STATE_STENCIL_TEST) != 0);
CHECK((h.list.command(1).state_flags & CMD_STATE_STENCIL_WRITE) != 0);
}
+
+// ─── Blended depth ordering ──────────────────────────────────────────────────
+// A blended draw composites onto what is already there, so back-to-front IS the
+// result. Material may not outrank it — batching is the thing that yields.
+
+TEST_CASE("transparent: back-to-front holds across materials") {
+ Harness h;
+ BatchVertex quad[4] = {};
+
+ // Camera looks down -z, so larger z is nearer and must land last.
+ BatchDrawKey near = quadKey(1, /*layer=*/3);
+ near.materialId = 1; // lowest material — would have sorted first
+ near.depth = 50.0f;
+
+ BatchDrawKey middle = quadKey(2, /*layer=*/3);
+ middle.materialId = 90000;
+ middle.depth = 0.0f;
+
+ BatchDrawKey far = quadKey(3, /*layer=*/3);
+ far.materialId = 500;
+ far.depth = -50.0f;
+
+ appendQuad(h.pool, h.list, h.clips, quad, near);
+ appendQuad(h.pool, h.list, h.clips, quad, middle);
+ appendQuad(h.pool, h.list, h.clips, quad, far);
+ h.list.finalize(h.pool);
+
+ REQUIRE(h.list.mergedDrawCallCount() == 3);
+ CHECK(h.list.command(0).texture_ids[0] == 3); // far
+ CHECK(h.list.command(1).texture_ids[0] == 2); // middle
+ CHECK(h.list.command(2).texture_ids[0] == 1); // near
+}
+
+TEST_CASE("transparent: equal depth still groups by material for the merge") {
+ Harness h;
+ BatchVertex quad[4] = {};
+
+ BatchDrawKey a1 = quadKey(1, 3); a1.materialId = 7; a1.depth = 0.0f;
+ BatchDrawKey b = quadKey(2, 3); b.materialId = 8; b.depth = 0.0f;
+ BatchDrawKey a2 = quadKey(3, 3); a2.materialId = 7; a2.depth = 0.0f;
+
+ // Submitted adjacent so their index ranges stay contiguous — the merge needs
+ // that as well as adjacency after the sort.
+ appendQuad(h.pool, h.list, h.clips, quad, a1);
+ appendQuad(h.pool, h.list, h.clips, quad, a2);
+ appendQuad(h.pool, h.list, h.clips, quad, b);
+ h.list.finalize(h.pool);
+
+ REQUIRE(h.list.mergedDrawCallCount() == 2);
+ CHECK(h.list.command(0).material_id == 7);
+ CHECK(h.list.command(1).material_id == 8);
+}
+
+TEST_CASE("opaque: material still outranks depth, since order cannot change the result") {
+ Harness h;
+ BatchVertex quad[4] = {};
+
+ BatchDrawKey a1 = quadKey(1, 3); a1.stage = RenderStage::Opaque;
+ a1.blend = BlendMode::None; a1.materialId = 7; a1.depth = 100.0f;
+ BatchDrawKey b = quadKey(2, 3); b.stage = RenderStage::Opaque;
+ b.blend = BlendMode::None; b.materialId = 8; b.depth = 0.0f;
+ BatchDrawKey a2 = quadKey(3, 3); a2.stage = RenderStage::Opaque;
+ a2.blend = BlendMode::None; a2.materialId = 7; a2.depth = -100.0f;
+
+ appendQuad(h.pool, h.list, h.clips, quad, a1);
+ appendQuad(h.pool, h.list, h.clips, quad, a2);
+ appendQuad(h.pool, h.list, h.clips, quad, b);
+ h.list.finalize(h.pool);
+
+ // Both material-7 draws coalesce despite straddling material 8 in depth.
+ REQUIRE(h.list.mergedDrawCallCount() == 2);
+ CHECK(h.list.command(0).material_id == 7);
+ CHECK(h.list.command(1).material_id == 8);
+}
+
+// 20 bits is sign + exponent + 11 mantissa bits, so the step is ~2^-11 of the
+// exponent's range: about 0.004 around z=10. Closer than that shares a key and
+// keeps submission order, which is the quantization talking, not a rule.
+TEST_CASE("transparent: hundredths of depth separate; thousandths share a bucket") {
+ Harness h;
+ BatchVertex quad[4] = {};
+
+ BatchDrawKey nearer = quadKey(1, 3); nearer.materialId = 1; nearer.depth = 10.01f;
+ BatchDrawKey farther = quadKey(2, 3); farther.materialId = 1; farther.depth = 10.00f;
+ appendQuad(h.pool, h.list, h.clips, quad, nearer);
+ appendQuad(h.pool, h.list, h.clips, quad, farther);
+ h.list.finalize(h.pool);
+
+ REQUIRE(h.list.mergedDrawCallCount() == 2);
+ CHECK(h.list.command(0).texture_ids[0] == 2);
+ CHECK(h.list.command(1).texture_ids[0] == 1);
+
+ Harness fine;
+ BatchDrawKey a = quadKey(1, 3); a.materialId = 1; a.depth = 10.001f;
+ BatchDrawKey b = quadKey(2, 3); b.materialId = 1; b.depth = 10.000f;
+ appendQuad(fine.pool, fine.list, fine.clips, quad, a);
+ appendQuad(fine.pool, fine.list, fine.clips, quad, b);
+ fine.list.finalize(fine.pool);
+ CHECK(fine.list.mergedDrawCallCount() == 1);
+}