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
fix(render): batching outranked the order that makes the picture
esengine9ab2b9569591
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex 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 arrayit hands back is the query cache's own entry, not a copy — sorting or pushing toit reorders or corrupts what every later reader of that query sees. Nothing indiff --git a/src/esengine/renderer/draw/DrawCommand.hpp b/src/esengine/renderer/draw/DrawCommand.hppindex 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] materialstatic 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 fordiff --git a/tests/renderer/test_batch_builder.cpp b/tests/renderer/test_batch_builder.cppindex 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 — decidCHECK((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);+}