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(renderer): the cull counter had never counted, and triangles meant two things
yhh2c40bf011759
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex e902ab795..412347d82 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -14,8 +14,47 @@ published separately; it ships inside the editor.## [Unreleased]+### Added++- **The 3D path can be held to what it COST, not just to what it drew.**+ `render.meshes` and `render.triangles` join the counters a pixel gate can pin+ through `ESTELLA_VERIFY_COUNTERS`, and the new gate `mesh-cost` pins them: nine+ 50-unit cubes inside an ortho view, six more a thousand units out either side,+ same mesh and same material — where they stand is the only thing that separates+ them. It asserts 9 meshes, 6 culled, 108 triangles and ONE draw call.++ Why a gate for numbers no pixel shows: with the mesh frustum cull disabled+ entirely, `mesh-instanced`, `mesh-shadow` and `mesh-builtin` all still pass.+ Measured, not argued — the whole 3D corpus is blind to a cull that stopped+ working, because instancing merges the extra geometry into the same one draw+ call and the extra cubes land behind the ones in front. `mesh-cost` catches it+ as 15 meshes and 0 culled. The other direction is a data sabotage: move one of+ the six off-screen cubes in behind a visible one and all four pixel probes and+ `batch.draws` still pass, while the three counters read 10 / 5 / 120.+### Fixed+- **`render.culled` counted nothing, and had never counted anything.** It is+ published every frame, read back by `renderer_getCulled()`, and printed in the+ editor’s stats overlay as "Culled" — and `stats_.culled` had no `++` anywhere+ in the engine, so all three read zero for every scene ever profiled. Six render+ plugins cull (sprite, mesh, shape, text, trail, UI element) and not one of them+ recorded doing it.++ A cull is the one part of a frame’s cost that leaves no draw, no pixel and no+ trace of itself, so the only place it can be counted is where it happens: the+ collect context carries the tally and each plugin bumps it at its `continue`.+ The camera’s collect only — a shadow face has a context of its own, and what+ its frustum skipped is already `render.shadow.collects`.++- **`triangles` meant two different things on the two draw paths.** A batched+ command merges its indices in and draws once, so `index_count / 3` is the whole+ truth for it; an instanced command holds ONE copy of the geometry and draws it+ `instance_count` times, and counting its indices once under-reports by exactly+ the factor instancing saved. Measured on `mesh-instanced`: four cubes reported+ 12 triangles, which is one cube. It reports 48 now, in the counter and in the+ editor’s stats overlay.+- **The editor grid stops changing plane mid-orbit.** Turning a 3D view downtoward the horizon used to swap the grid off the ground and onto a verticalplane as it passed about 6 degrees: the frame you judge a scene against turneddiff --git a/fixtures/scenes/mesh-cost.esscene b/fixtures/scenes/mesh-cost.esscenenew file mode 100644index 000000000..490b057e3--- /dev/null+++ b/fixtures/scenes/mesh-cost.esscene@@ -0,0 +1,634 @@+{+ "version": 3,+ "name": "MeshCost",+ "entities": [+ {+ "id": 0,+ "name": "Camera",+ "parent": null,+ "children": [],+ "visible": true,+ "components": [+ {+ "type": "Transform",+ "data": {+ "position": {+ "x": 0,+ "y": 0,+ "z": 300+ }+ }+ },+ {+ "type": "Camera",+ "data": {+ "projectionType": 1,+ "orthoSize": 150,+ "isActive": true,+ "priority": 0+ }+ }+ ]+ },+ {+ "id": 1,+ "name": "In1",+ "parent": null,+ "children": [],+ "visible": true,+ "components": [+ {+ "type": "Transform",+ "data": {+ "position": {+ "x": -100,+ "y": 100,+ "z": 0+ },+ "scale": {+ "x": 0.5,+ "y": 0.5,+ "z": 0.5+ }+ }+ },+ {+ "type": "MeshRenderer",+ "data": {+ "mesh": "builtin:cube",+ "color": {+ "r": 1,+ "g": 0,+ "b": 0,+ "a": 1+ },+ "lit": false,+ "opaque": true,+ "cullBackfaces": true,+ "enabled": true+ }+ }+ ]+ },+ {+ "id": 2,+ "name": "In2",+ "parent": null,+ "children": [],+ "visible": true,+ "components": [+ {+ "type": "Transform",+ "data": {+ "position": {+ "x": 0,+ "y": 100,+ "z": 0+ },+ "scale": {+ "x": 0.5,+ "y": 0.5,+ "z": 0.5+ }+ }+ },+ {+ "type": "MeshRenderer",+ "data": {+ "mesh": "builtin:cube",+ "color": {+ "r": 0,+ "g": 1,+ "b": 0,+ "a": 1+ },+ "lit": false,+ "opaque": true,+ "cullBackfaces": true,+ "enabled": true+ }+ }+ ]+ },+ {+ "id": 3,+ "name": "In3",+ "parent": null,+ "children": [],+ "visible": true,+ "components": [+ {+ "type": "Transform",+ "data": {+ "position": {+ "x": 100,+ "y": 100,+ "z": 0+ },+ "scale": {+ "x": 0.5,+ "y": 0.5,+ "z": 0.5+ }+ }+ },+ {+ "type": "MeshRenderer",+ "data": {+ "mesh": "builtin:cube",+ "color": {+ "r": 0,+ "g": 0,+ "b": 1,+ "a": 1+ },+ "lit": false,+ "opaque": true,+ "cullBackfaces": true,+ "enabled": true+ }+ }+ ]+ },+ {+ "id": 4,+ "name": "In4",+ "parent": null,+ "children": [],+ "visible": true,+ "components": [+ {+ "type": "Transform",+ "data": {+ "position": {+ "x": -100,+ "y": 0,+ "z": 0+ },+ "scale": {+ "x": 0.5,+ "y": 0.5,+ "z": 0.5+ }+ }+ },+ {+ "type": "MeshRenderer",+ "data": {+ "mesh": "builtin:cube",+ "color": {+ "r": 1,+ "g": 1,+ "b": 0,+ "a": 1+ },+ "lit": false,+ "opaque": true,+ "cullBackfaces": true,+ "enabled": true+ }+ }+ ]+ },+ {+ "id": 5,+ "name": "In5",+ "parent": null,+ "children": [],+ "visible": true,+ "components": [+ {+ "type": "Transform",+ "data": {+ "position": {+ "x": 0,+ "y": 0,+ "z": 0+ },+ "scale": {+ "x": 0.5,+ "y": 0.5,+ "z": 0.5+ }+ }+ },+ {+ "type": "MeshRenderer",+ "data": {+ "mesh": "builtin:cube",+ "color": {+ "r": 1,+ "g": 0,+ "b": 1,+ "a": 1+ },+ "lit": false,+ "opaque": true,+ "cullBackfaces": true,+ "enabled": true+ }+ }+ ]+ },+ {+ "id": 6,+ "name": "In6",+ "parent": null,+ "children": [],+ "visible": true,+ "components": [+ {+ "type": "Transform",+ "data": {+ "position": {+ "x": 100,+ "y": 0,+ "z": 0+ },+ "scale": {+ "x": 0.5,+ "y": 0.5,+ "z": 0.5+ }+ }+ },+ {+ "type": "MeshRenderer",+ "data": {+ "mesh": "builtin:cube",+ "color": {+ "r": 0,+ "g": 1,+ "b": 1,+ "a": 1+ },+ "lit": false,+ "opaque": true,+ "cullBackfaces": true,+ "enabled": true+ }+ }+ ]+ },+ {+ "id": 7,+ "name": "In7",+ "parent": null,+ "children": [],+ "visible": true,+ "components": [+ {+ "type": "Transform",+ "data": {+ "position": {+ "x": -100,+ "y": -100,+ "z": 0+ },+ "scale": {+ "x": 0.5,+ "y": 0.5,+ "z": 0.5+ }+ }+ },+ {+ "type": "MeshRenderer",+ "data": {+ "mesh": "builtin:cube",+ "color": {+ "r": 1,+ "g": 1,+ "b": 1,+ "a": 1+ },+ "lit": false,+ "opaque": true,+ "cullBackfaces": true,+ "enabled": true+ }+ }+ ]+ },+ {+ "id": 8,+ "name": "In8",+ "parent": null,+ "children": [],+ "visible": true,+ "components": [+ {+ "type": "Transform",+ "data": {+ "position": {+ "x": 0,+ "y": -100,+ "z": 0+ },+ "scale": {+ "x": 0.5,+ "y": 0.5,+ "z": 0.5+ }+ }+ },+ {+ "type": "MeshRenderer",+ "data": {+ "mesh": "builtin:cube",+ "color": {+ "r": 1,+ "g": 0,+ "b": 0,+ "a": 1+ },+ "lit": false,+ "opaque": true,+ "cullBackfaces": true,+ "enabled": true+ }+ }+ ]+ },+ {+ "id": 9,+ "name": "In9",+ "parent": null,+ "children": [],+ "visible": true,+ "components": [+ {+ "type": "Transform",+ "data": {+ "position": {+ "x": 100,+ "y": -100,+ "z": 0+ },+ "scale": {+ "x": 0.5,+ "y": 0.5,+ "z": 0.5+ }+ }+ },+ {+ "type": "MeshRenderer",+ "data": {+ "mesh": "builtin:cube",+ "color": {+ "r": 0,+ "g": 1,+ "b": 0,+ "a": 1+ },+ "lit": false,+ "opaque": true,+ "cullBackfaces": true,+ "enabled": true+ }+ }+ ]+ },+ {+ "id": 10,+ "name": "Out10",+ "parent": null,+ "children": [],+ "visible": true,+ "components": [+ {+ "type": "Transform",+ "data": {+ "position": {+ "x": -1000,+ "y": 100,+ "z": 0+ },+ "scale": {+ "x": 0.5,+ "y": 0.5,+ "z": 0.5+ }+ }+ },+ {+ "type": "MeshRenderer",+ "data": {+ "mesh": "builtin:cube",+ "color": {+ "r": 1,+ "g": 1,+ "b": 1,+ "a": 1+ },+ "lit": false,+ "opaque": true,+ "cullBackfaces": true,+ "enabled": true+ }+ }+ ]+ },+ {+ "id": 11,+ "name": "Out11",+ "parent": null,+ "children": [],+ "visible": true,+ "components": [+ {+ "type": "Transform",+ "data": {+ "position": {+ "x": 1000,+ "y": 100,+ "z": 0+ },+ "scale": {+ "x": 0.5,+ "y": 0.5,+ "z": 0.5+ }+ }+ },+ {+ "type": "MeshRenderer",+ "data": {+ "mesh": "builtin:cube",+ "color": {+ "r": 1,+ "g": 1,+ "b": 1,+ "a": 1+ },+ "lit": false,+ "opaque": true,+ "cullBackfaces": true,+ "enabled": true+ }+ }+ ]+ },+ {+ "id": 12,+ "name": "Out12",+ "parent": null,+ "children": [],+ "visible": true,+ "components": [+ {+ "type": "Transform",+ "data": {+ "position": {+ "x": -1000,+ "y": 0,+ "z": 0+ },+ "scale": {+ "x": 0.5,+ "y": 0.5,+ "z": 0.5+ }+ }+ },+ {+ "type": "MeshRenderer",+ "data": {+ "mesh": "builtin:cube",+ "color": {+ "r": 1,+ "g": 1,+ "b": 1,+ "a": 1+ },+ "lit": false,+ "opaque": true,+ "cullBackfaces": true,+ "enabled": true+ }+ }+ ]+ },+ {+ "id": 13,+ "name": "Out13",+ "parent": null,+ "children": [],+ "visible": true,+ "components": [+ {+ "type": "Transform",+ "data": {+ "position": {+ "x": 1000,+ "y": 0,+ "z": 0+ },+ "scale": {+ "x": 0.5,+ "y": 0.5,+ "z": 0.5+ }+ }+ },+ {+ "type": "MeshRenderer",+ "data": {+ "mesh": "builtin:cube",+ "color": {+ "r": 1,+ "g": 1,+ "b": 1,+ "a": 1+ },+ "lit": false,+ "opaque": true,+ "cullBackfaces": true,+ "enabled": true+ }+ }+ ]+ },+ {+ "id": 14,+ "name": "Out14",+ "parent": null,+ "children": [],+ "visible": true,+ "components": [+ {+ "type": "Transform",+ "data": {+ "position": {+ "x": -1000,+ "y": -100,+ "z": 0+ },+ "scale": {+ "x": 0.5,+ "y": 0.5,+ "z": 0.5+ }+ }+ },+ {+ "type": "MeshRenderer",+ "data": {+ "mesh": "builtin:cube",+ "color": {+ "r": 1,+ "g": 1,+ "b": 1,+ "a": 1+ },+ "lit": false,+ "opaque": true,+ "cullBackfaces": true,+ "enabled": true+ }+ }+ ]+ },+ {+ "id": 15,+ "name": "Out15",+ "parent": null,+ "children": [],+ "visible": true,+ "components": [+ {+ "type": "Transform",+ "data": {+ "position": {+ "x": 1000,+ "y": -100,+ "z": 0+ },+ "scale": {+ "x": 0.5,+ "y": 0.5,+ "z": 0.5+ }+ }+ },+ {+ "type": "MeshRenderer",+ "data": {+ "mesh": "builtin:cube",+ "color": {+ "r": 1,+ "g": 1,+ "b": 1,+ "a": 1+ },+ "lit": false,+ "opaque": true,+ "cullBackfaces": true,+ "enabled": true+ }+ }+ ]+ }+ ]+}diff --git a/src/esengine/renderer/RenderTypePlugin.hpp b/src/esengine/renderer/RenderTypePlugin.hppindex c3864c598..fc6cee349 100644--- a/src/esengine/renderer/RenderTypePlugin.hpp+++ b/src/esengine/renderer/RenderTypePlugin.hpp@@ -93,6 +93,16 @@ struct RenderCollectContext {DrawList& draw_list;RenderFrameContext& frame_context;CameraView camera;++ /**+ * @brief How many renderables this collect's frustum rejected.+ *+ * @details Written by the plugins at their `continue`: a cull leaves no draw+ * and no pixel, so where it happens is the only place to count it.+ * Counts THIS collect — a shadow face has a context of its own, and+ * what its frustum skipped is `render.shadow.collects`.+ */+ u32 culled = 0;};/** @brief Decomposes @p transform and returns its world position shifted toward thediff --git a/src/esengine/renderer/frame/RenderFrame.cpp b/src/esengine/renderer/frame/RenderFrame.cppindex da5e5129c..4cb03f57e 100644--- a/src/esengine/renderer/frame/RenderFrame.cpp+++ b/src/esengine/renderer/frame/RenderFrame.cpp@@ -378,7 +378,10 @@ void RenderFrame::flush() {stats_.draw_calls = draw_list_.mergedDrawCallCount();for (u32 i = 0; i < draw_list_.commandCount(); ++i) {const auto& cmd = draw_list_.command(i);- stats_.triangles += cmd.index_count / 3;+ // An instanced command holds ONE copy of the geometry and draws it+ // instance_count times; a batched one merged its indices in already. The+ // multiply is what stops the number meaning two things on the two paths.+ stats_.triangles += (cmd.index_count / 3) * (cmd.instance_count ? cmd.instance_count : 1);switch (cmd.type) {case RenderType::Sprite:case RenderType::UIElement:@@ -399,6 +402,11 @@ void RenderFrame::flush() {ES_PROFILE_COUNTER("render.culled", stats_.culled);ES_PROFILE_COUNTER("render.sprites", stats_.sprites);+ // The 3D path had no counter at all, and its cost is the one a pixel hides+ // best: identical geometry drawn N times merges into ONE instanced call, so+ // batch.draws does not move when a cull stops working. These two do.+ ES_PROFILE_COUNTER("render.meshes", stats_.meshes);+ ES_PROFILE_COUNTER("render.triangles", stats_.triangles);ES_PROFILE_COUNTER("render.text", stats_.text);ES_PROFILE_COUNTER("render.shapes", stats_.shapes);#ifdef ES_ENABLE_PARTICLES@@ -1256,6 +1264,11 @@ void RenderFrame::collectAll(ecs::Registry& registry) {collectSky(collectCtx);for (auto& plugin : plugins_) plugin->collect(collectCtx);+ // The other half of what the frame cost: what it did NOT draw. Accumulated+ // like the per-type counts beside it, so a frame composited from several+ // cameras reports every cull each of them made.+ stats_.culled += collectCtx.culled;+// OR-ed across the frame's cameras, applied at the next beginFrame and never// mid-frame: the capture is scratch each camera composites out of, and the// editor's grid draws into it between begin() and this collect.diff --git a/src/esengine/renderer/plugins/MeshPlugin.cpp b/src/esengine/renderer/plugins/MeshPlugin.cppindex e833e149d..0b640c6c0 100644--- a/src/esengine/renderer/plugins/MeshPlugin.cpp+++ b/src/esengine/renderer/plugins/MeshPlugin.cpp@@ -201,7 +201,7 @@ void MeshPlugin::collect(RenderCollectContext& collect_ctx) {glm::vec3 aabbCenter(0.0f), halfExtents(0.0f);orientedWorldAabb(position, rotation, scale, localMin, localMax, aabbCenter, halfExtents);- if (!frustum.intersectsAABB(aabbCenter, halfExtents)) continue;+ if (!frustum.intersectsAABB(aabbCenter, halfExtents)) { ++collect_ctx.culled; continue; }u32 textureId = ctx.white_texture_id;if (mesh.texture.isValid()) {diff --git a/src/esengine/renderer/plugins/ShapePlugin.cpp b/src/esengine/renderer/plugins/ShapePlugin.cppindex 603d0ce61..49eb40e63 100644--- a/src/esengine/renderer/plugins/ShapePlugin.cpp+++ b/src/esengine/renderer/plugins/ShapePlugin.cpp@@ -59,6 +59,7 @@ void ShapePlugin::collect(RenderCollectContext& collect_ctx) {flatTurnZ(rotation),glm::vec3(shape.size.x * scale.x, shape.size.y * scale.y, 0.0f) * 0.5f);if (!frustum.intersectsAABB(position, halfExtents)) {+ ++collect_ctx.culled;continue;}diff --git a/src/esengine/renderer/plugins/SpritePlugin.cpp b/src/esengine/renderer/plugins/SpritePlugin.cppindex 002530768..181643461 100644--- a/src/esengine/renderer/plugins/SpritePlugin.cpp+++ b/src/esengine/renderer/plugins/SpritePlugin.cpp@@ -47,6 +47,7 @@ void SpritePlugin::collect(RenderCollectContext& collect_ctx) {glm::vec3 halfExtents = flatHalfExtents(turn, glm::vec3(std::abs(finalSize.x), std::abs(finalSize.y), 0.0f) * 0.5f);if (!frustum.intersectsAABB(aabbCenter, halfExtents)) {+ ++collect_ctx.culled;continue;}diff --git a/src/esengine/renderer/plugins/TextPlugin.cpp b/src/esengine/renderer/plugins/TextPlugin.cppindex 016ad1225..bbbb0b61e 100644--- a/src/esengine/renderer/plugins/TextPlugin.cpp+++ b/src/esengine/renderer/plugins/TextPlugin.cpp@@ -163,6 +163,7 @@ void TextPlugin::collect(RenderCollectContext& collect_ctx) {0.0f);if (!frustum.intersectsAABB(position, halfExtents)) {+ ++collect_ctx.culled;continue;}diff --git a/src/esengine/renderer/plugins/TrailPlugin.cpp b/src/esengine/renderer/plugins/TrailPlugin.cppindex 590ed99a6..0f77d57a4 100644--- a/src/esengine/renderer/plugins/TrailPlugin.cpp+++ b/src/esengine/renderer/plugins/TrailPlugin.cpp@@ -76,7 +76,7 @@ void TrailPlugin::collect(RenderCollectContext& collect_ctx) {glm::vec3 aabbCenter((minX + maxX) * 0.5f, (minY + maxY) * 0.5f, headWorld.z);glm::vec3 halfExtents((maxX - minX) * 0.5f + maxHalf,(maxY - minY) * 0.5f + maxHalf, 0.0f);- if (!frustum.intersectsAABB(aabbCenter, halfExtents)) continue;+ if (!frustum.intersectsAABB(aabbCenter, halfExtents)) { ++collect_ctx.culled; continue; }// --- Draw key (mirrors MeshPlugin: material owns shading when present). ------u32 textureId = ctx.white_texture_id;diff --git a/src/esengine/renderer/plugins/UIElementPlugin.cpp b/src/esengine/renderer/plugins/UIElementPlugin.cppindex 68484d965..873b6183c 100644--- a/src/esengine/renderer/plugins/UIElementPlugin.cpp+++ b/src/esengine/renderer/plugins/UIElementPlugin.cpp@@ -90,7 +90,7 @@ void UIElementPlugin::collect(RenderCollectContext& collect_ctx) {// `position` above already carries the turned offset, so only the extents do.glm::vec3 halfExtents = flatHalfExtents(flatTurnZ(rotation), glm::vec3(w * scale.x, h * scale.y, 0.0f) * 0.5f);- if (!frustum.intersectsAABB(position, halfExtents)) continue;+ if (!frustum.intersectsAABB(position, halfExtents)) { ++collect_ctx.culled; continue; }f32 angle = 2.0f * std::atan2(rotation.z, rotation.w);i32 layer = UI_BASE_LAYER + renderer.uiOrder;diff --git a/tools/renderScenes.mjs b/tools/renderScenes.mjsindex fc752ad71..e7c08a2c9 100644--- a/tools/renderScenes.mjs+++ b/tools/renderScenes.mjs@@ -155,6 +155,10 @@ export const SCENES = [// read 255·cos22.5 and 255·cos67.5, swapped if the winding is inside out; the sphere// reads 155 at -25 against 236 at its middle, which a flat quad could not.{ id: "mesh-instanced", tier: "pr", webgpu: true, env: { ESTELLA_VERIFY_SCENE: "/scenes/mesh-instanced.esscene", ESTELLA_VERIFY_W: "256", ESTELLA_VERIFY_H: "256", ESTELLA_VERIFY_STEPS: "2", ESTELLA_VERIFY_DRAW_CALLS: "1", ESTELLA_VERIFY_EXPECT: "[{\"x\":0.25,\"y\":0.25,\"rgb\":[255,0,0],\"tol\":20},{\"x\":0.75,\"y\":0.25,\"rgb\":[0,255,0],\"tol\":20},{\"x\":0.25,\"y\":0.75,\"rgb\":[0,0,255],\"tol\":20},{\"x\":0.75,\"y\":0.75,\"rgb\":[255,255,0],\"tol\":20},{\"x\":0.5,\"y\":0.5,\"rgb\":[0,0,0],\"tol\":20}]" } },+ // What the frame COST: nine cubes inside the ortho view and six a thousand units out,+ // same mesh and same material, so render.culled is the only place the six can show.+ // batch.draws holds the nine to ONE instanced call; render.triangles counts 9 x 12.+ { id: "mesh-cost", tier: "pr", webgpu: true, env: { ESTELLA_VERIFY_SCENE: "/scenes/mesh-cost.esscene", ESTELLA_VERIFY_W: "256", ESTELLA_VERIFY_H: "256", ESTELLA_VERIFY_STEPS: "2", ESTELLA_VERIFY_COUNTERS: "{\"render.meshes\":9,\"render.culled\":6,\"render.triangles\":108,\"batch.draws\":1}", ESTELLA_VERIFY_EXPECT: "[{\"x\":0.1667,\"y\":0.1667,\"rgb\":[255,0,0],\"tol\":20},{\"x\":0.5,\"y\":0.5,\"rgb\":[255,0,255],\"tol\":20},{\"x\":0.8333,\"y\":0.8333,\"rgb\":[0,255,0],\"tol\":20},{\"x\":0.3,\"y\":0.5,\"rgb\":[0,0,0],\"tol\":10}]" } },// Two opaque cubes overlapping on screen, the red one 120 units nearer. Declares NO// depth layer and boots LINEAR — the cheap way to engage the post-process capture.// Opaque sorts front-to-back, so with no attachment the far cube paints over.