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.

docs(profiling): the batch-break vocabulary the renderer actually publishes

esengine09e659889edf
diff --git a/docs/astro/src/content/docs/performance/profiling.mdx b/docs/astro/src/content/docs/performance/profiling.mdx
index 44b1b67a9..4f95b329b 100644
--- a/docs/astro/src/content/docs/performance/profiling.mdx
+++ b/docs/astro/src/content/docs/performance/profiling.mdx
@@ -405,7 +405,7 @@ capture, let one frame render, then read back a record for **every draw call**
**why the previous batch broke**:
```typescript
-import { Renderer, RenderType, FlushReason } from 'esengine';
+import { Renderer, RenderType, BatchBreak } from 'esengine';
Renderer.captureNextFrame(); // arm: the NEXT rendered frame records
@@ -416,7 +416,7 @@ if (Renderer.hasCapturedData()) {
console.log(
`#${dc.index} ${RenderType[dc.type]} tex=${dc.textureId} ` +
`tris=${dc.triangleCount} entities=${dc.entityCount} ` +
- `flush=${FlushReason[dc.flushReason]}`
+ `break=${BatchBreak[dc.breakReason]}`
);
}
console.log(`${capture!.cameraCount} camera pass(es)`);
@@ -437,7 +437,7 @@ if (Renderer.hasCapturedData()) {
| `vertexCount` / `triangleCount` | Geometry submitted. |
| `entityCount` / `entityOffset` / `entities` | The entity ids batched into this call. |
| `layer` | Render layer of the batch. |
-| `flushReason` | Why this batch ended (`FlushReason`, below). |
+| `breakReason` | Why this call started instead of joining the one before it (`BatchBreak`, below). |
| `scissorX/Y/W/H`, `scissorEnabled` | Scissor rect state (UI masks). |
| `stencilWrite` / `stencilTest` / `stencilRef` | Stencil state (mask writers/readers). |
| `textureSlotUsage` | Texture slots the batch consumed. |
@@ -445,20 +445,33 @@ if (Renderer.hasCapturedData()) {
`RenderType` tells you what a call drew: `Sprite`, `Spine`, `Mesh`,
`ExternalMesh`, `Text`, `Particle`, `Shape`, `UIElement`.
-`FlushReason` is the batching story — each value names the state change that
-forced a new draw call, i.e. what to fix to batch better:
+`BatchBreak` is the batching story — each value names the state change that kept
+this call from joining the one before it, i.e. what to fix to batch better. Every
+member is a branch of the merge predicate itself, so the list cannot drift from
+the rule that produced it:
-| `FlushReason` | Meaning |
+| `BatchBreak` | Meaning |
|---|---|
-| `BatchFull` | Vertex batch hit capacity — a "good" flush; lots of content. |
-| `TextureSlotsFull` | Ran out of texture slots — atlas more textures together. |
-| `ScissorChange` | Scissor rect changed (a `UIMask` boundary). |
-| `StencilChange` | Stencil state changed (mask write/test boundary). |
-| `MaterialChange` | Material switched — group entities by material. |
-| `BlendModeChange` | Blend mode switched — interleaved additive/normal content. |
-| `StageEnd` | Render stage boundary. |
-| `TypeChange` | Content type switched (e.g. sprites → text → sprites). |
-| `FrameEnd` | Final flush of the frame. |
+| `RunStart` | Nothing to join — the first call of a run. |
+| `Instanced` | An instanced draw: one command per emitter, never coalesced. |
+| `Shader` | Shader switched — the state change nothing batches across. |
+| `Blend` | Blend mode switched — interleaved additive/normal content. |
+| `Layout` | Vertex layout switched (sprite quads vs mesh vertices). |
+| `Material` | Material switched — group entities by material. |
+| `Depth` | Depth test/write differ — opaque and blended content interleaved. |
+| `Cull` | Cull state differs. |
+| `State` | Some other render state flag differs. |
+| `Scissor` | Scissor rect changed (a `UIMask` boundary). |
+| `Stencil` | Stencil ref changed (mask write/test boundary). |
+| `IndexGap` | Indices are not contiguous — the sort put something between them. |
+| `TextureSlots` | Mergeable, but the combined set overflowed the 8 texture slots — atlas more textures together. |
+
+`None` is the merge's own answer and never appears on a captured call: a command
+that reaches it was folded into the one before it instead of starting a new one.
+
+The same reasons are published per frame as `batch.break.*` counters alongside
+`batch.draws` and `batch.merged`, so "6 draw calls" reads as "1 run start and
+5 index gaps, with 41 commands merged away" without capturing anything.
### Replaying to a draw call
@@ -564,9 +577,9 @@ is the equivalent.
- **Blame before optimizing** — read `systemTimings` / `phaseTimings` to find
*which* system is slow before touching code; the overlay's `max` column
catches one-frame spikes an average hides.
-- **Capture a frame to fix draw calls** — `flushReason` names the exact state
- change that broke each batch (`TextureSlotsFull` → atlas; `MaterialChange` →
- group by material).
+- **Capture a frame to fix draw calls** — `breakReason` names the exact state
+ change that broke each batch (`TextureSlots` → atlas; `Material` → group by
+ material).
- **Log with categories, not `console.log`** — structured entries let a
handler filter by channel and level, and `setLogLevel(LogLevel.Debug)` turns
verbosity on without code changes.
diff --git a/docs/astro/src/content/docs/zh-cn/performance/profiling.mdx b/docs/astro/src/content/docs/zh-cn/performance/profiling.mdx
index 6ace99e7a..fbe1807ab 100644
--- a/docs/astro/src/content/docs/zh-cn/performance/profiling.mdx
+++ b/docs/astro/src/content/docs/zh-cn/performance/profiling.mdx
@@ -358,7 +358,7 @@ flush 走引擎时钟而非定时器,因此后台标签页或被挂起的小游
什么状态,以及最关键的:**上一个批次为什么被打断**:
```typescript
-import { Renderer, RenderType, FlushReason } from 'esengine';
+import { Renderer, RenderType, BatchBreak } from 'esengine';
Renderer.captureNextFrame(); // arm: the NEXT rendered frame records
@@ -369,7 +369,7 @@ if (Renderer.hasCapturedData()) {
console.log(
`#${dc.index} ${RenderType[dc.type]} tex=${dc.textureId} ` +
`tris=${dc.triangleCount} entities=${dc.entityCount} ` +
- `flush=${FlushReason[dc.flushReason]}`
+ `break=${BatchBreak[dc.breakReason]}`
);
}
console.log(`${capture!.cameraCount} camera pass(es)`);
@@ -390,7 +390,7 @@ if (Renderer.hasCapturedData()) {
| `vertexCount` / `triangleCount` | 提交的几何量。 |
| `entityCount` / `entityOffset` / `entities` | 被批进该调用的实体 id。 |
| `layer` | 批次的渲染层。 |
-| `flushReason` | 该批次为何结束(`FlushReason`,见下)。 |
+| `breakReason` | 该调用为何没有并入前一个(`BatchBreak`,见下)。 |
| `scissorX/Y/W/H`、`scissorEnabled` | 裁剪矩形状态(UI 遮罩)。 |
| `stencilWrite` / `stencilTest` / `stencilRef` | 模板状态(遮罩写入/读取方)。 |
| `textureSlotUsage` | 批次占用的纹理槽数。 |
@@ -398,20 +398,32 @@ if (Renderer.hasCapturedData()) {
`RenderType` 说明一个调用画了什么:`Sprite`、`Spine`、`Mesh`、`ExternalMesh`、
`Text`、`Particle`、`Shape`、`UIElement`。
-`FlushReason` 就是合批的故事——每个值都点名了迫使新开一个 draw call 的那次状态
-变化,也就是想合批更好该修什么:
+`BatchBreak` 就是合批的故事——每个值都点名了让这个调用无法并入前一个的那次状态
+变化,也就是想合批更好该修什么。每个成员都是合批判定自身的一个分支,所以这张表不
+会和产生它的规则脱节:
-| `FlushReason` | 含义 |
+| `BatchBreak` | 含义 |
|---|---|
-| `BatchFull` | 顶点批次到达容量——"好"的 flush,说明内容多。 |
-| `TextureSlotsFull` | 纹理槽用尽——把更多贴图打进图集。 |
-| `ScissorChange` | 裁剪矩形变化(`UIMask` 边界)。 |
-| `StencilChange` | 模板状态变化(遮罩写入/测试边界)。 |
-| `MaterialChange` | 材质切换——按材质给实体分组。 |
-| `BlendModeChange` | 混合模式切换——加法/普通内容交错。 |
-| `StageEnd` | 渲染阶段边界。 |
-| `TypeChange` | 内容类型切换(如精灵 → 文本 → 精灵)。 |
-| `FrameEnd` | 该帧的最终 flush。 |
+| `RunStart` | 没有可并入的对象——一段的第一个调用。 |
+| `Instanced` | 实例化绘制:每个发射器一条命令,从不合并。 |
+| `Shader` | 着色器切换——没有任何东西能跨过去合批。 |
+| `Blend` | 混合模式切换——加法/普通内容交错。 |
+| `Layout` | 顶点布局切换(精灵四边形 vs 网格顶点)。 |
+| `Material` | 材质切换——按材质给实体分组。 |
+| `Depth` | 深度测试/写入不同——不透明与混合内容交错。 |
+| `Cull` | 剔除状态不同。 |
+| `State` | 其他某个渲染状态标志不同。 |
+| `Scissor` | 裁剪矩形变化(`UIMask` 边界)。 |
+| `Stencil` | 模板参考值变化(遮罩写入/测试边界)。 |
+| `IndexGap` | 索引不连续——排序把别的东西插在了两者之间。 |
+| `TextureSlots` | 本可合并,但合并后的贴图集合超出了 8 个纹理槽——把更多贴图打进图集。 |
+
+`None` 是合批自己的答案,永远不会出现在捕获到的调用上:走到它的命令被折进了前一
+个调用,而不是新开一个。
+
+同一套原因还会按帧发布成 `batch.break.*` 计数器,与 `batch.draws`、`batch.merged`
+并列——所以"6 个 draw call"不用捕获也能读成"1 次起始 + 5 次索引断裂,另有 41 条命
+令被合掉"。
### 重放到某个 draw call
@@ -506,8 +518,8 @@ FPS。对游戏内构建,上面的 `statsPlugin` 就是对应物。
剖析时再加。
- **先归因再优化** — 读 `systemTimings` / `phaseTimings` 找到*哪个*系统慢再动代码;
浮层的 `max` 列能抓住平均值掩盖的单帧尖峰。
-- **用帧捕获修 draw call** — `flushReason` 点名打断每个批次的那次状态变化
- (`TextureSlotsFull` → 打图集;`MaterialChange` → 按材质分组)。
+- **用帧捕获修 draw call** — `breakReason` 点名打断每个批次的那次状态变化
+ (`TextureSlots` → 打图集;`Material` → 按材质分组)。
- **用类别记日志,别用 `console.log`** — 结构化条目让 handler 能按通道和级别过滤,
`setLogLevel(LogLevel.Debug)` 不改代码就能打开详细输出。
- **生产环境关闭 `GLDebug`** — 逐调用的 GL 错误检查很贵;只在追渲染 bug 时开。