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.

test(render): the batcher is held to what it achieves

yhhf517a46abbe7
diff --git a/CHANGELOG.md b/CHANGELOG.md
index fa302f280..6cd1df6dd 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -14,6 +14,27 @@ published separately; it ships inside the editor.
## [Unreleased]
+### Added
+
+- **The batcher is held to what it achieves.** `DrawList` has been publishing
+ `batch.draws`, `batch.merged` and a counter per break REASON for a while, and
+ nothing read any of them — so the oldest performance promise in the engine, that
+ sprites sharing a texture reach the GPU as one draw, was the one thing no gate
+ could see. `sprite-batch` reads them: nineteen sprites over two textures, three
+ draws, sixteen merges, and the three draws accounted for to their reason — one
+ run head and two index gaps, no state break of any kind.
+
+ Sabotaged on the fixture rather than argued: give ONE of the nineteen sprites
+ `lit: true` and it needs a different program, so the batch breaks. `batch.draws`
+ goes 3 → 4 and `batch.merged` 16 → 15, while `render.sprites` stays at 19 — the
+ picture is complete and `sprite-default`, the smoke gate on the very same scene,
+ passes. That is the whole shape of the problem: a batching regression ships as a
+ slower game and nothing goes red.
+
+ `check-render-scenes` counts a counter as an assertion now. It listed the pixel,
+ grid and preview forms and not `ESTELLA_VERIFY_COUNTERS`, so a gate whose whole
+ subject is cost had to carry a probe it did not need to be allowed to exist.
+
### Changed
- **Every rasterizer draws the same penumbra, and `sun-shadow` now says so.** A
diff --git a/tools/check-render-scenes.mjs b/tools/check-render-scenes.mjs
index 77e747b99..1679bd827 100644
--- a/tools/check-render-scenes.mjs
+++ b/tools/check-render-scenes.mjs
@@ -40,9 +40,11 @@ for (const s of SCENES) {
}
// An expectation is the whole point: a scene with none passes as long as it
// renders anything at all. Allowed, as a sentence — the same bargain the
- // golden corpus strikes with parityGap.
+ // golden corpus strikes with parityGap. A COUNTER is an expectation too, and
+ // the sharper kind: what a frame cost is the half no pixel can show.
const asserts = s.env.ESTELLA_VERIFY_EXPECT || s.env.ESTELLA_VERIFY_GRID || s.env.ESTELLA_VERIFY_PREVIEW
|| s.env.ESTELLA_VERIFY_MESH_PREVIEW || s.env.ESTELLA_VERIFY_DEPTH_LAYERS
+ || s.env.ESTELLA_VERIFY_COUNTERS || s.env.ESTELLA_VERIFY_DRAW_CALLS
|| s.env.ESTELLA_VERIFY_YSORT || s.id === 'sprite-default';
if (!asserts && !s.rendersOnly) {
fail(`"${s.id}" asserts nothing — give it an ESTELLA_VERIFY_EXPECT, or say in rendersOnly why it has none`);
diff --git a/tools/renderScenes.mjs b/tools/renderScenes.mjs
index 747f8b3f3..b657f16db 100644
--- a/tools/renderScenes.mjs
+++ b/tools/renderScenes.mjs
@@ -57,6 +57,10 @@ export function sceneWatchdogMs(backend, host) {
*/
export const SCENES = [
{ id: "sprite-default", tier: "pr", webgpu: true, env: { } },
+ // What the BATCHER achieved, which no pixel can show: nineteen sprites over two
+ // textures reach the GPU as three draws. Every break is accounted for to its
+ // reason — one run head, two index gaps, no state break at all.
+ { id: "sprite-batch", tier: "pr", webgpu: true, env: { ESTELLA_VERIFY_SCENE: "/scenes/sprite-rendering.esscene", ESTELLA_VERIFY_MANIFEST: "/scenes/sprite-rendering.textures.json", ESTELLA_VERIFY_W: "256", ESTELLA_VERIFY_H: "256", ESTELLA_VERIFY_STEPS: "2", ESTELLA_VERIFY_COUNTERS: "{\"render.sprites\":19,\"batch.draws\":3,\"batch.merged\":16,\"batch.break.runStart\":1,\"batch.break.indexGap\":2}" } },
// Editor grid on/off pixel diff — guards the custom-draw reflected material path (drawMeshWithMaterial + MaterialConstants UBO).
{ id: "editor-grid", tier: "pr", webgpu: true, env: { ESTELLA_VERIFY_GRID: "64", ESTELLA_VERIFY_STEPS: "3" } },
// The same grid from straight above a 3D view. It stands on the ground there, so it fills the frame; the 2D plane would be edge-on and light one band.