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.

feat(profiler): a draw-call count says what it is made of, and domains speak one vocabulary

yhhdfd491ed07b4
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 1778f52ca..d71b7040d 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -94,6 +94,22 @@ published separately; it ships inside the editor.
was only ever checked below the scope, never across a system holding one — now
runs over every node of a frame that has a wait in it.
+- **A draw-call count now says what it is made of.** `FlushReason` had a member
+ for every way a batch can break and a decoder to read it, and the producer
+ wrote the constant `FrameEnd` for every draw call ever recorded — the
+ vocabulary existed and nothing populated it. The reasons were never anywhere
+ else either: they are the conditions `canMergeWith` tests, and it answered with
+ a bare boolean.
+
+ The predicate now answers with the reason. Each frame publishes `batch.draws`,
+ `batch.merged` and a `batch.break.*` counter per reason that actually
+ occurred — shader, blend, layout, material, depth, cull, state, scissor,
+ stencil, indexGap, textureSlots, instanced — so "6 draw calls" reads as
+ "1 run start and 5 index gaps, with 41 commands merged away", and the capture
+ records the true reason instead of the constant. The list cannot drift from the
+ rule, because every member is a branch of the rule. `FlushReason` is gone; the
+ names that replace it are the ones the merge actually uses.
+
- **One derivation, three readers.** `buildFrameProfile` is a pure function over
plain per-frame data, so the live view, a pinned frame and a recorded session
cannot each round their own way to a different answer. The editor's own
diff --git a/desktop/src/engine/EditorControlSurface.ts b/desktop/src/engine/EditorControlSurface.ts
index 061a2565c..ea2b1c843 100644
--- a/desktop/src/engine/EditorControlSurface.ts
+++ b/desktop/src/engine/EditorControlSurface.ts
@@ -40,6 +40,17 @@ import type { SelectionStore } from '@/store/selectionStore';
const r2 = (n: number): number => Math.round(n * 100) / 100;
+const BREAK_PREFIX = 'batch.break.';
+
+/** The `batch.break.*` counters as reason → draws, by their bare reason name. */
+function batchBreaks(counters: Record<string, number>): Record<string, number> {
+ const out: Record<string, number> = {};
+ for (const key in counters) {
+ if (key.startsWith(BREAK_PREFIX)) out[key.slice(BREAK_PREFIX.length)] = r2(counters[key]);
+ }
+ return out;
+}
+
/** A captured viewport frame: raw RGBA pixels (GL order: bottom-up rows). */
export interface ViewportCapture {
rgba: Uint8Array;
@@ -963,6 +974,13 @@ export class EditorControlSurfaceImpl {
// did the time go", and there are two dozen of them. Counted, not hidden.
domains: w.mean.domains.filter((d) => r2(d.ms) > 0).map((d) => ({ domain: d.id, ms: r2(d.ms) })),
freeDomains: w.mean.domains.filter((d) => r2(d.ms) === 0).length,
+ render: {
+ drawCalls: r2(w.drawCalls),
+ mergedAway: r2(w.counters['batch.merged'] ?? 0),
+ triangles: Math.round(w.triangles),
+ entities: Math.round(w.entities),
+ breaks: batchBreaks(w.counters),
+ },
systems: shown.map(({ domain, node }) => ({
name: node.label,
domain,
diff --git a/desktop/src/engine/PerfMonitor.ts b/desktop/src/engine/PerfMonitor.ts
index df5626305..5b8ed6377 100644
--- a/desktop/src/engine/PerfMonitor.ts
+++ b/desktop/src/engine/PerfMonitor.ts
@@ -182,6 +182,20 @@ export interface ProfileWindow {
worstFrameProfile: FrameProfile | null;
/** The window's cost, per frame. */
mean: FrameProfile;
+ drawCalls: number;
+ triangles: number;
+ entities: number;
+ /** Engine + editor named counters, averaged per frame. */
+ counters: Record<string, number>;
+}
+
+function meanCounters(frames: readonly FrameSample[]): Record<string, number> {
+ const total: Record<string, number> = {};
+ for (const f of frames) {
+ for (const k in f.counters) total[k] = (total[k] ?? 0) + f.counters[k];
+ }
+ for (const k in total) total[k] /= frames.length;
+ return total;
}
/** A recorded profiling session, serialized to JSON for offline analysis. */
@@ -393,6 +407,10 @@ class PerfMonitorImpl {
worstFrameMs: worst ? worst.dt : 0,
worstFrameProfile: worst ? profileOf(worst) : null,
mean: meanFrameProfile(profiles),
+ drawCalls: frames.length ? frames.reduce((a, s) => a + s.drawCalls, 0) / frames.length : 0,
+ triangles: frames.length ? frames.reduce((a, s) => a + s.triangles, 0) / frames.length : 0,
+ entities: frames.length ? frames.reduce((a, s) => a + s.entities, 0) / frames.length : 0,
+ counters: frames.length ? meanCounters(frames) : {},
};
}
diff --git a/desktop/src/engine/profileReport.ts b/desktop/src/engine/profileReport.ts
index 66af5ca12..59646bc6a 100644
--- a/desktop/src/engine/profileReport.ts
+++ b/desktop/src/engine/profileReport.ts
@@ -38,6 +38,19 @@ export interface ProfileReport {
domains: Array<{ domain: string; ms: number }>;
/** Domains that cost nothing this window — installed and idle. */
freeDomains: number;
+ /**
+ * Per frame. `breaks` is reason → draw calls that reason started, so `drawCalls`
+ * reads as what it is made of; `mergedAway` is what the batcher did fold in.
+ * Reasons are the merge predicate's own: shader, blend, layout, material,
+ * depth, cull, state, scissor, stencil, indexGap, textureSlots, instanced.
+ */
+ render: {
+ drawCalls: number;
+ mergedAway: number;
+ triangles: number;
+ entities: number;
+ breaks: Record<string, number>;
+ };
/** Costliest systems over the window, per frame. */
systems: ProfileReportSystem[];
/** Systems ranked below the cut. Zero means the list above is all of them. */
diff --git a/sdk/etc/index.api.md b/sdk/etc/index.api.md
index bebc5b149..acf545d4e 100644
--- a/sdk/etc/index.api.md
+++ b/sdk/etc/index.api.md
@@ -1067,6 +1067,24 @@ resolveUrl: (path: string) => string
setBaseUrl: ((url: string) => void) | undefined
```
+## BatchBreak — enum @experimental
+```
+Blend = 4
+Cull = 8
+Depth = 7
+IndexGap = 12
+Instanced = 2
+Layout = 5
+Material = 6
+None = 0
+RunStart = 1
+Scissor = 10
+Shader = 3
+State = 9
+Stencil = 11
+TextureSlots = 13
+```
+
## BehaviorContext — interface @experimental
```
commands: CommandsInstance
@@ -2230,6 +2248,7 @@ maxDistinct: number | undefined
build: (app: App) => void
cleanup: (app: App) => void
name: string
+profileDomain: "diagnostics"
static new (options_?: DiagnosticsPluginOptions): DiagnosticsPlugin
static prototype: DiagnosticsPlugin
```
@@ -2407,11 +2426,11 @@ textureRotated: (position: Vec2, size: Vec2, rotation: number, textureHandle: nu
## DrawCallInfo — interface @experimental
```
blendMode: number
+breakReason: BatchBreak
cameraIndex: number
entities: number[]
entityCount: number
entityOffset: number
-flushReason: FlushReason
index: number
layer: number
materialId: number
@@ -2664,6 +2683,7 @@ rows: EventBindingRow[]
build: (app: App) => void
cleanup: () => void
name: string
+profileDomain: "events"
static new (): EventBindingPlugin
static prototype: EventBindingPlugin
```
@@ -2858,19 +2878,6 @@ wrap: FlexWrap
(typeof FlexWrap)[keyof typeof FlexWrap]
```
-## FlushReason — enum @experimental
-```
-BatchFull = 0
-BlendModeChange = 5
-FrameEnd = 8
-MaterialChange = 4
-ScissorChange = 2
-StageEnd = 6
-StencilChange = 3
-TextureSlotsFull = 1
-TypeChange = 7
-```
-
## FocusManager — const @experimental
```
ResourceDef<FocusManagerState>
@@ -4156,6 +4163,7 @@ uvs: number[] | undefined
build: (app: App) => void
cleanup: () => void
name: string
+profileDomain: "render"
static new (): Mesh2DPlugin
static prototype: Mesh2DPlugin
```
@@ -5192,6 +5200,7 @@ static prototype: PostProcessAPI
build: (app: App) => void
cleanup: (app?: App) => void
name: string
+profileDomain: "render"
static new (): PostProcessPlugin
static prototype: PostProcessPlugin
```
@@ -6352,6 +6361,7 @@ visitorEntity: number
```
build: (app: App) => void
name: string
+profileDomain: "services"
static new (): ServicesPlugin
static prototype: ServicesPlugin
```
@@ -8073,6 +8083,7 @@ generation: number
```
build: (app: App) => void
name: string
+profileDomain: "ui"
static new (): UILayoutPlugin
static prototype: UILayoutPlugin
```
diff --git a/sdk/etc/index.native.api.md b/sdk/etc/index.native.api.md
index 430c6d318..bdda5c498 100644
--- a/sdk/etc/index.native.api.md
+++ b/sdk/etc/index.native.api.md
@@ -1067,6 +1067,24 @@ resolveUrl: (path: string) => string
setBaseUrl: ((url: string) => void) | undefined
```
+## BatchBreak — enum @experimental
+```
+Blend = 4
+Cull = 8
+Depth = 7
+IndexGap = 12
+Instanced = 2
+Layout = 5
+Material = 6
+None = 0
+RunStart = 1
+Scissor = 10
+Shader = 3
+State = 9
+Stencil = 11
+TextureSlots = 13
+```
+
## BehaviorContext — interface @experimental
```
commands: CommandsInstance
@@ -2238,6 +2256,7 @@ maxDistinct: number | undefined
build: (app: App) => void
cleanup: (app: App) => void
name: string
+profileDomain: "diagnostics"
static new (options_?: DiagnosticsPluginOptions): DiagnosticsPlugin
static prototype: DiagnosticsPlugin
```
@@ -2415,11 +2434,11 @@ textureRotated: (position: Vec2, size: Vec2, rotation: number, textureHandle: nu
## DrawCallInfo — interface @experimental
```
blendMode: number
+breakReason: BatchBreak
cameraIndex: number
entities: number[]
entityCount: number
entityOffset: number
-flushReason: FlushReason
index: number
layer: number
materialId: number
@@ -2672,6 +2691,7 @@ rows: EventBindingRow[]
build: (app: App) => void
cleanup: () => void
name: string
+profileDomain: "events"
static new (): EventBindingPlugin
static prototype: EventBindingPlugin
```
@@ -2866,19 +2886,6 @@ wrap: FlexWrap
(typeof FlexWrap)[keyof typeof FlexWrap]
```
-## FlushReason — enum @experimental
-```
-BatchFull = 0
-BlendModeChange = 5
-FrameEnd = 8
-MaterialChange = 4
-ScissorChange = 2
-StageEnd = 6
-StencilChange = 3
-TextureSlotsFull = 1
-TypeChange = 7
-```
-
## FocusManager — const @experimental
```
ResourceDef<FocusManagerState>
@@ -4169,6 +4176,7 @@ uvs: number[] | undefined
build: (app: App) => void
cleanup: () => void
name: string
+profileDomain: "render"
static new (): Mesh2DPlugin
static prototype: Mesh2DPlugin
```
@@ -5375,6 +5383,7 @@ static prototype: PostProcessAPI
build: (app: App) => void
cleanup: (app?: App) => void
name: string
+profileDomain: "render"
static new (): PostProcessPlugin
static prototype: PostProcessPlugin
```
@@ -6545,6 +6554,7 @@ visitorEntity: number
```
build: (app: App) => void
name: string
+profileDomain: "services"
static new (): ServicesPlugin
static prototype: ServicesPlugin
```
@@ -8266,6 +8276,7 @@ generation: number
```
build: (app: App) => void
name: string
+profileDomain: "ui"
static new (): UILayoutPlugin
static prototype: UILayoutPlugin
```
diff --git a/sdk/etc/index.node.api.md b/sdk/etc/index.node.api.md
index 578370a23..e6d551d30 100644
--- a/sdk/etc/index.node.api.md
+++ b/sdk/etc/index.node.api.md
@@ -1062,6 +1062,24 @@ resolveUrl: (path: string) => string
setBaseUrl: ((url: string) => void) | undefined
```
+## BatchBreak — enum @experimental
+```
+Blend = 4
+Cull = 8
+Depth = 7
+IndexGap = 12
+Instanced = 2
+Layout = 5
+Material = 6
+None = 0
+RunStart = 1
+Scissor = 10
+Shader = 3
+State = 9
+Stencil = 11
+TextureSlots = 13
+```
+
## BehaviorContext — interface @experimental
```
commands: CommandsInstance
@@ -2225,6 +2243,7 @@ maxDistinct: number | undefined
build: (app: App) => void
cleanup: (app: App) => void
name: string
+profileDomain: "diagnostics"
static new (options_?: DiagnosticsPluginOptions): DiagnosticsPlugin
static prototype: DiagnosticsPlugin
```
@@ -2402,11 +2421,11 @@ textureRotated: (position: Vec2, size: Vec2, rotation: number, textureHandle: nu
## DrawCallInfo — interface @experimental
```
blendMode: number
+breakReason: BatchBreak
cameraIndex: number
entities: number[]
entityCount: number
entityOffset: number
-flushReason: FlushReason
index: number
layer: number
materialId: number
@@ -2659,6 +2678,7 @@ rows: EventBindingRow[]
build: (app: App) => void
cleanup: () => void
name: string
+profileDomain: "events"
static new (): EventBindingPlugin
static prototype: EventBindingPlugin
```
@@ -2853,19 +2873,6 @@ wrap: FlexWrap
(typeof FlexWrap)[keyof typeof FlexWrap]
```
-## FlushReason — enum @experimental
-```
-BatchFull = 0
-BlendModeChange = 5
-FrameEnd = 8
-MaterialChange = 4
-ScissorChange = 2
-StageEnd = 6
-StencilChange = 3
-TextureSlotsFull = 1
-TypeChange = 7
-```
-
## FocusManager — const @experimental
```
ResourceDef<FocusManagerState>
@@ -4151,6 +4158,7 @@ uvs: number[] | undefined
build: (app: App) => void
cleanup: () => void
name: string
+profileDomain: "render"
static new (): Mesh2DPlugin
static prototype: Mesh2DPlugin
```
@@ -5187,6 +5195,7 @@ static prototype: PostProcessAPI
build: (app: App) => void
cleanup: (app?: App) => void
name: string
+profileDomain: "render"
static new (): PostProcessPlugin
static prototype: PostProcessPlugin
```
@@ -6347,6 +6356,7 @@ visitorEntity: number
```
build: (app: App) => void
name: string
+profileDomain: "services"
static new (): ServicesPlugin
static prototype: ServicesPlugin
```
@@ -8068,6 +8078,7 @@ generation: number
```
build: (app: App) => void
name: string
+profileDomain: "ui"
static new (): UILayoutPlugin
static prototype: UILayoutPlugin
```
diff --git a/sdk/etc/minigame.api.md b/sdk/etc/minigame.api.md
index a45927f9d..62231a716 100644
--- a/sdk/etc/minigame.api.md
+++ b/sdk/etc/minigame.api.md
@@ -1062,6 +1062,24 @@ resolveUrl: (path: string) => string
setBaseUrl: ((url: string) => void) | undefined
```
+## BatchBreak — enum @experimental
+```
+Blend = 4
+Cull = 8
+Depth = 7
+IndexGap = 12
+Instanced = 2
+Layout = 5
+Material = 6
+None = 0
+RunStart = 1
+Scissor = 10
+Shader = 3
+State = 9
+Stencil = 11
+TextureSlots = 13
+```
+
## BehaviorContext — interface @experimental
```
commands: CommandsInstance
@@ -2225,6 +2243,7 @@ maxDistinct: number | undefined
build: (app: App) => void
cleanup: (app: App) => void
name: string
+profileDomain: "diagnostics"
static new (options_?: DiagnosticsPluginOptions): DiagnosticsPlugin
static prototype: DiagnosticsPlugin
```
@@ -2402,11 +2421,11 @@ textureRotated: (position: Vec2, size: Vec2, rotation: number, textureHandle: nu
## DrawCallInfo — interface @experimental
```
blendMode: number
+breakReason: BatchBreak
cameraIndex: number
entities: number[]
entityCount: number
entityOffset: number
-flushReason: FlushReason
index: number
layer: number
materialId: number
@@ -2659,6 +2678,7 @@ rows: EventBindingRow[]
build: (app: App) => void
cleanup: () => void
name: string
+profileDomain: "events"
static new (): EventBindingPlugin
static prototype: EventBindingPlugin
```
@@ -2853,19 +2873,6 @@ wrap: FlexWrap
(typeof FlexWrap)[keyof typeof FlexWrap]
```
-## FlushReason — enum @experimental
-```
-BatchFull = 0
-BlendModeChange = 5
-FrameEnd = 8
-MaterialChange = 4
-ScissorChange = 2
-StageEnd = 6
-StencilChange = 3
-TextureSlotsFull = 1
-TypeChange = 7
-```
-
## FocusManager — const @experimental
```
ResourceDef<FocusManagerState>
@@ -4151,6 +4158,7 @@ uvs: number[] | undefined
build: (app: App) => void
cleanup: () => void
name: string
+profileDomain: "render"
static new (): Mesh2DPlugin
static prototype: Mesh2DPlugin
```
@@ -5432,6 +5440,7 @@ static prototype: PostProcessAPI
build: (app: App) => void
cleanup: (app?: App) => void
name: string
+profileDomain: "render"
static new (): PostProcessPlugin
static prototype: PostProcessPlugin
```
@@ -6592,6 +6601,7 @@ visitorEntity: number
```
build: (app: App) => void
name: string
+profileDomain: "services"
static new (): ServicesPlugin
static prototype: ServicesPlugin
```
@@ -8313,6 +8323,7 @@ generation: number
```
build: (app: App) => void
name: string
+profileDomain: "ui"
static new (): UILayoutPlugin
static prototype: UILayoutPlugin
```
diff --git a/sdk/etc/wechat.api.md b/sdk/etc/wechat.api.md
index dc55d6aa1..1d64332e3 100644
--- a/sdk/etc/wechat.api.md
+++ b/sdk/etc/wechat.api.md
@@ -1062,6 +1062,24 @@ resolveUrl: (path: string) => string
setBaseUrl: ((url: string) => void) | undefined
```
+## BatchBreak — enum @experimental
+```
+Blend = 4
+Cull = 8
+Depth = 7
+IndexGap = 12
+Instanced = 2
+Layout = 5
+Material = 6
+None = 0
+RunStart = 1
+Scissor = 10
+Shader = 3
+State = 9
+Stencil = 11
+TextureSlots = 13
+```
+
## BehaviorContext — interface @experimental
```
commands: CommandsInstance
@@ -2225,6 +2243,7 @@ maxDistinct: number | undefined
build: (app: App) => void
cleanup: (app: App) => void
name: string
+profileDomain: "diagnostics"
static new (options_?: DiagnosticsPluginOptions): DiagnosticsPlugin
static prototype: DiagnosticsPlugin
```
@@ -2402,11 +2421,11 @@ textureRotated: (position: Vec2, size: Vec2, rotation: number, textureHandle: nu
## DrawCallInfo — interface @experimental
```
blendMode: number
+breakReason: BatchBreak
cameraIndex: number
entities: number[]
entityCount: number
entityOffset: number
-flushReason: FlushReason
index: number
layer: number
materialId: number
@@ -2659,6 +2678,7 @@ rows: EventBindingRow[]
build: (app: App) => void
cleanup: () => void
name: string
+profileDomain: "events"
static new (): EventBindingPlugin
static prototype: EventBindingPlugin
```
@@ -2853,19 +2873,6 @@ wrap: FlexWrap
(typeof FlexWrap)[keyof typeof FlexWrap]
```
-## FlushReason — enum @experimental
-```
-BatchFull = 0
-BlendModeChange = 5
-FrameEnd = 8
-MaterialChange = 4
-ScissorChange = 2
-StageEnd = 6
-StencilChange = 3
-TextureSlotsFull = 1
-TypeChange = 7
-```
-
## FocusManager — const @experimental
```
ResourceDef<FocusManagerState>
@@ -4158,6 +4165,7 @@ uvs: number[] | undefined
build: (app: App) => void
cleanup: () => void
name: string
+profileDomain: "render"
static new (): Mesh2DPlugin
static prototype: Mesh2DPlugin
```
@@ -5194,6 +5202,7 @@ static prototype: PostProcessAPI
build: (app: App) => void
cleanup: (app?: App) => void
name: string
+profileDomain: "render"
static new (): PostProcessPlugin
static prototype: PostProcessPlugin
```
@@ -6354,6 +6363,7 @@ visitorEntity: number
```
build: (app: App) => void
name: string
+profileDomain: "services"
static new (): ServicesPlugin
static prototype: ServicesPlugin
```
@@ -8075,6 +8085,7 @@ generation: number
```
build: (app: App) => void
name: string
+profileDomain: "ui"
static new (): UILayoutPlugin
static prototype: UILayoutPlugin
```
diff --git a/sdk/src/core-render.ts b/sdk/src/core-render.ts
index bd1c74d6d..5dd3869f8 100644
--- a/sdk/src/core-render.ts
+++ b/sdk/src/core-render.ts
@@ -188,7 +188,7 @@ export {
} from './render/layerOrder';
export {
- FlushReason,
+ BatchBreak,
RenderType,
type DrawCallInfo,
type FrameCaptureData,
diff --git a/sdk/src/diagnostics/DiagnosticsPlugin.ts b/sdk/src/diagnostics/DiagnosticsPlugin.ts
index 1804cdd43..494b8e69e 100644
--- a/sdk/src/diagnostics/DiagnosticsPlugin.ts
+++ b/sdk/src/diagnostics/DiagnosticsPlugin.ts
@@ -71,6 +71,7 @@ class DiagnosticsLogHandler implements LogHandler {
export class DiagnosticsPlugin implements Plugin {
name = 'Diagnostics';
+ readonly profileDomain = 'diagnostics';
private unsubscribes_: (() => void)[] = [];
private handler_: DiagnosticsLogHandler | null = null;
diff --git a/sdk/src/ecs/timer.ts b/sdk/src/ecs/timer.ts
index 8a6a3bf2f..74eb815f1 100644
--- a/sdk/src/ecs/timer.ts
+++ b/sdk/src/ecs/timer.ts
@@ -231,6 +231,7 @@ const timerSystem = defineSystem(
export const timerPlugin: Plugin = {
name: 'Timer',
+ profileDomain: 'timer',
build(app) {
app.insertResource(TimerRes, new TimerManager());
// Timers advance game time — frozen in editor edit mode.
diff --git a/sdk/src/eventBinding.ts b/sdk/src/eventBinding.ts
index 9154d6f02..0970b1080 100644
--- a/sdk/src/eventBinding.ts
+++ b/sdk/src/eventBinding.ts
@@ -245,6 +245,7 @@ export function createEventBindingRuntime(host: EventBindingHost): EventBindingR
export class EventBindingPlugin implements Plugin {
name = 'eventBinding';
+ readonly profileDomain = 'events';
private runtime_: EventBindingRuntime | null = null;
diff --git a/sdk/src/postprocess/PostProcessPlugin.ts b/sdk/src/postprocess/PostProcessPlugin.ts
index 3a1a30d10..ef92ddf24 100644
--- a/sdk/src/postprocess/PostProcessPlugin.ts
+++ b/sdk/src/postprocess/PostProcessPlugin.ts
@@ -8,6 +8,7 @@ import { postProcessVolumeSystem, cleanupVolumeSystem, setVolumeTextureResolver,
export class PostProcessPlugin implements Plugin {
name = 'postProcess';
+ readonly profileDomain = 'render';
build(app: App): void {
// Per-App post-process API, injected into the render pipeline as an
diff --git a/sdk/src/render/frameCapture.ts b/sdk/src/render/frameCapture.ts
index 20f42eb3e..ad142568b 100644
--- a/sdk/src/render/frameCapture.ts
+++ b/sdk/src/render/frameCapture.ts
@@ -26,16 +26,25 @@ import { awaitReadback, READBACK_READY } from './readback';
* corruption.
*/
-export enum FlushReason {
- BatchFull = 0,
- TextureSlotsFull = 1,
- ScissorChange = 2,
- StencilChange = 3,
- MaterialChange = 4,
- BlendModeChange = 5,
- StageEnd = 6,
- TypeChange = 7,
- FrameEnd = 8,
+/**
+ * Why a draw call started rather than joining the one before it. Mirrors the
+ * engine's BatchBreak; each member is a condition the merge itself tests.
+ */
+export enum BatchBreak {
+ None = 0,
+ RunStart = 1,
+ Instanced = 2,
+ Shader = 3,
+ Blend = 4,
+ Layout = 5,
+ Material = 6,
+ Depth = 7,
+ Cull = 8,
+ State = 9,
+ Scissor = 10,
+ Stencil = 11,
+ IndexGap = 12,
+ TextureSlots = 13,
}
export enum RenderType {
@@ -63,7 +72,7 @@ export interface DrawCallInfo {
entityCount: number;
entityOffset: number;
layer: number;
- flushReason: FlushReason;
+ breakReason: BatchBreak;
scissorX: number;
scissorY: number;
scissorW: number;
@@ -115,7 +124,7 @@ export function decodeFrameCapture(module: ESEngineModule): FrameCaptureData | n
const dcEntityCount = view.getUint32(off + 32, true);
const entityOffset = view.getUint32(off + 36, true);
const layer = view.getInt32(off + 40, true);
- const flushReason = view.getUint8(off + 44) as FlushReason;
+ const breakReason = view.getUint8(off + 44) as BatchBreak;
const scissorX = view.getInt32(off + 48, true);
const scissorY = view.getInt32(off + 52, true);
const scissorW = view.getInt32(off + 56, true);
@@ -136,7 +145,7 @@ export function decodeFrameCapture(module: ESEngineModule): FrameCaptureData | n
textureId, materialId, shaderId,
vertexCount, triangleCount,
entityCount: dcEntityCount, entityOffset, layer,
- flushReason,
+ breakReason,
scissorX, scissorY, scissorW, scissorH, scissorEnabled,
stencilWrite, stencilTest, stencilRef,
textureSlotUsage, entities,
diff --git a/sdk/src/render/mesh2d.ts b/sdk/src/render/mesh2d.ts
index 4daebd373..b7e5cbbd6 100644
--- a/sdk/src/render/mesh2d.ts
+++ b/sdk/src/render/mesh2d.ts
@@ -98,6 +98,7 @@ export const Meshes2D = defineResource<Mesh2DAPI>(null!, 'Meshes2D');
export class Mesh2DPlugin implements Plugin {
name = 'mesh2d';
+ readonly profileDomain = 'render';
private offDespawn_: (() => void) | null = null;
build(app: App): void {
diff --git a/sdk/src/scene/scenePlugin.ts b/sdk/src/scene/scenePlugin.ts
index cb0db5a69..c764d619a 100644
--- a/sdk/src/scene/scenePlugin.ts
+++ b/sdk/src/scene/scenePlugin.ts
@@ -42,6 +42,7 @@ const sceneStreamingSystem = defineSystem(
export const sceneManagerPlugin: Plugin = {
name: 'sceneManager',
+ profileDomain: 'scene',
build(app: App): void {
const state = new SceneManagerState(app);
app.insertResource(SceneManager, state);
diff --git a/sdk/src/services/servicesPlugin.ts b/sdk/src/services/servicesPlugin.ts
index cd7f2a05c..3667e3572 100644
--- a/sdk/src/services/servicesPlugin.ts
+++ b/sdk/src/services/servicesPlugin.ts
@@ -29,6 +29,7 @@ import { getPlatform } from '../platform';
export class ServicesPlugin implements Plugin {
name = 'Services';
+ readonly profileDomain = 'services';
build(app: App): void {
// ONE ceremony for everything that covers the game. An ad and a store
diff --git a/sdk/src/ui/behavior/plugin.ts b/sdk/src/ui/behavior/plugin.ts
index 7ee093d13..b5a8fa2ad 100644
--- a/sdk/src/ui/behavior/plugin.ts
+++ b/sdk/src/ui/behavior/plugin.ts
@@ -40,6 +40,7 @@ const SCROLL_DRAG_THRESHOLD_PX = 5;
*/
export class UIBehaviorPlugin implements Plugin {
name = 'uiBehavior';
+ readonly profileDomain = 'ui';
dependencies = [PluginName.UIInteraction];
private events_: UIEventQueue | null = null;
diff --git a/sdk/src/ui/controller/plugin.ts b/sdk/src/ui/controller/plugin.ts
index b4614ef83..13b366692 100644
--- a/sdk/src/ui/controller/plugin.ts
+++ b/sdk/src/ui/controller/plugin.ts
@@ -18,6 +18,7 @@ import { ensureControllerAiRegistrations } from './ai-builtins';
export class UIControllerPlugin implements Plugin {
name = 'uiController';
+ readonly profileDomain = 'ui';
build(app: App): void {
// Register the `.esfsm`/`.esbt` → controller glue (idempotent) so a
diff --git a/sdk/src/ui/layout/layout.ts b/sdk/src/ui/layout/layout.ts
index 93a5dabbe..7806094ef 100644
--- a/sdk/src/ui/layout/layout.ts
+++ b/sdk/src/ui/layout/layout.ts
@@ -27,6 +27,7 @@ import { initUIHelpers } from '../util/helpers';
export class UILayoutPlugin implements Plugin {
name = 'uiLayout';
+ readonly profileDomain = 'ui';
build(app: App): void {
registerComponent('UINode', UINode);
diff --git a/sdk/src/ui/text/inline-image-plugin.ts b/sdk/src/ui/text/inline-image-plugin.ts
index cbb222b86..548995cdc 100644
--- a/sdk/src/ui/text/inline-image-plugin.ts
+++ b/sdk/src/ui/text/inline-image-plugin.ts
@@ -38,6 +38,7 @@ const WHITE = { r: 1, g: 1, b: 1, a: 1 };
export class InlineImagePlugin implements Plugin {
name = 'ui-inline-image';
+ readonly profileDomain = 'ui';
private cleanup_: (() => void) | null = null;
diff --git a/sdk/src/velocity.ts b/sdk/src/velocity.ts
index 05c054fbb..a69de0804 100644
--- a/sdk/src/velocity.ts
+++ b/sdk/src/velocity.ts
@@ -65,6 +65,7 @@ export const velocitySystem = defineSystem(
export const velocityPlugin: Plugin = {
name: 'Velocity',
+ profileDomain: 'velocity',
build(app) {
app.addSystemToSchedule(Schedule.Update, velocitySystem, { runIf: playModeOnly });
},
diff --git a/sdk/tests/frame-capture.test.ts b/sdk/tests/frame-capture.test.ts
index 8f2ccefa6..393a54fd5 100644
--- a/sdk/tests/frame-capture.test.ts
+++ b/sdk/tests/frame-capture.test.ts
@@ -7,7 +7,7 @@
* mutation or reuse of the WASM-backed source buffer.
*/
import { describe, expect, it } from 'vitest';
-import { decodeFrameCapture, getSnapshotImageData, RenderType, FlushReason } from '../src/render/frameCapture';
+import { decodeFrameCapture, getSnapshotImageData, RenderType, BatchBreak } from '../src/render/frameCapture';
import type { ESEngineModule } from '../src/wasm';
// Minimal ImageData shim for headless test runs. Mirrors the parts of the
@@ -165,6 +165,7 @@ describe('decodeFrameCapture', () => {
it('surfaces enum values with the typed names (smoke)', () => {
expect(RenderType.Sprite).toBe(0);
- expect(FlushReason.BatchFull).toBe(0);
+ expect(BatchBreak.None).toBe(0);
+ expect(BatchBreak.TextureSlots).toBe(13);
});
});
diff --git a/src/esengine/renderer/draw/DrawCommand.hpp b/src/esengine/renderer/draw/DrawCommand.hpp
index a11042218..fcde7971d 100644
--- a/src/esengine/renderer/draw/DrawCommand.hpp
+++ b/src/esengine/renderer/draw/DrawCommand.hpp
@@ -21,6 +21,52 @@ static constexpr u16 CMD_STATE_STENCIL_WRITE = 0x02;
static constexpr u16 CMD_STATE_STENCIL_TEST = 0x04;
static constexpr u16 CMD_STATE_CUSTOM_DRAW = 0x08;
+/**
+ * Why a draw call had to start rather than join the one before it. Every member
+ * is a condition the merge itself tests, so the list cannot drift from the rule.
+ */
+enum class BatchBreak : u8 {
+ None = 0,
+ RunStart,
+ Instanced,
+ Shader,
+ Blend,
+ Layout,
+ Material,
+ Depth,
+ Cull,
+ State,
+ Scissor,
+ Stencil,
+ IndexGap,
+ TextureSlots,
+ Count,
+};
+
+/**
+ * The profiler counter each reason publishes under. String LITERALS: FrameProfiler
+ * keys entries by the pointer's contents and never copies, so a built-up buffer
+ * would dangle the moment the frame ended.
+ */
+inline const char* batchBreakCounter(BatchBreak r) {
+ switch (r) {
+ case BatchBreak::RunStart: return "batch.break.runStart";
+ case BatchBreak::Instanced: return "batch.break.instanced";
+ case BatchBreak::Shader: return "batch.break.shader";
+ case BatchBreak::Blend: return "batch.break.blend";
+ case BatchBreak::Layout: return "batch.break.layout";
+ case BatchBreak::Material: return "batch.break.material";
+ case BatchBreak::Depth: return "batch.break.depth";
+ case BatchBreak::Cull: return "batch.break.cull";
+ case BatchBreak::State: return "batch.break.state";
+ case BatchBreak::Scissor: return "batch.break.scissor";
+ case BatchBreak::Stencil: return "batch.break.stencil";
+ case BatchBreak::IndexGap: return "batch.break.indexGap";
+ case BatchBreak::TextureSlots: return "batch.break.textureSlots";
+ default: return "batch.break.none";
+ }
+}
+
struct DrawCommand {
u64 sort_key = 0;
@@ -40,6 +86,7 @@ struct DrawCommand {
bool depth_test = false;
bool depth_write = true;
u8 cull = 0; ///< CullMode: 0 = none, 1 = back, 2 = front.
+ BatchBreak break_reason = BatchBreak::RunStart; ///< Why this draw call started.
u8 texture_count = 0;
u32 texture_ids[MAX_CMD_TEXTURE_SLOTS] = {};
@@ -164,15 +211,22 @@ struct DrawCommand {
return static_cast<i32>(texture_count++);
}
- bool canMergeWith(const DrawCommand& next) const {
+ /**
+ * Why `next` cannot join this draw, or None if it can.
+ *
+ * The predicate answers with the reason rather than a bare no: a frame is
+ * some number of draw calls, and the only actionable thing about that number
+ * is what kept them apart. canMergeWith is this, read as a bool.
+ */
+ BatchBreak mergeBlocker(const DrawCommand& next) const {
// Instanced draws are one command per emitter — never coalesce them.
- if (instance_count != 0 || next.instance_count != 0) return false;
- if (shader_id != next.shader_id) return false;
- if (blend_mode != next.blend_mode) return false;
- if (layout_id != next.layout_id) return false;
+ if (instance_count != 0 || next.instance_count != 0) return BatchBreak::Instanced;
+ if (shader_id != next.shader_id) return BatchBreak::Shader;
+ if (blend_mode != next.blend_mode) return BatchBreak::Blend;
+ if (layout_id != next.layout_id) return BatchBreak::Layout;
// Same material handle => same uniforms/textures; different ones must not
// coalesce. material_id 0 (no material) shares the path's defaults, so they still merge.
- if (material_id != next.material_id) return false;
+ if (material_id != next.material_id) return BatchBreak::Material;
// Depth state is checked on its own rather than trusted to follow from the
// material. It used to: every draw resolved its depth from a material, so equal
// material_id implied equal state, and material_id 0 meant one shared set of
@@ -182,20 +236,24 @@ struct DrawCommand {
// The symptom would be a blended sprite occasionally clipping what is behind it,
// depending on whether the two happened to land adjacent. Compared here as render
// state, not as stage: the stage is the reason, these three are the effect.
- if (depth_test != next.depth_test) return false;
- if (depth_write != next.depth_write) return false;
- if (cull != next.cull) return false;
- if (state_flags != next.state_flags) return false;
+ if (depth_test != next.depth_test) return BatchBreak::Depth;
+ if (depth_write != next.depth_write) return BatchBreak::Depth;
+ if (cull != next.cull) return BatchBreak::Cull;
+ if (state_flags != next.state_flags) return BatchBreak::State;
if (state_flags & CMD_STATE_SCISSOR) {
- if (scissor != next.scissor) return false;
+ if (scissor != next.scissor) return BatchBreak::Scissor;
}
if (state_flags & (CMD_STATE_STENCIL_WRITE | CMD_STATE_STENCIL_TEST)) {
- if (stencil_ref != next.stencil_ref) return false;
+ if (stencil_ref != next.stencil_ref) return BatchBreak::Stencil;
}
// Texture compatibility is decided by the merge (the combined set must fit in 8
// slots), not here, so different-texture draws can coalesce.
- if (index_offset + index_count != next.index_offset) return false;
- return true;
+ if (index_offset + index_count != next.index_offset) return BatchBreak::IndexGap;
+ return BatchBreak::None;
+ }
+
+ bool canMergeWith(const DrawCommand& next) const {
+ return mergeBlocker(next) == BatchBreak::None;
}
};
diff --git a/src/esengine/renderer/draw/DrawList.cpp b/src/esengine/renderer/draw/DrawList.cpp
index e15eab661..4cfafab2b 100644
--- a/src/esengine/renderer/draw/DrawList.cpp
+++ b/src/esengine/renderer/draw/DrawList.cpp
@@ -3,6 +3,7 @@
#include "./DrawList.hpp"
#include "./BatchVertex.hpp"
#include "../store/MaterialStore.hpp"
+#include "../../core/FrameProfiler.hpp"
#include <glm/glm.hpp>
#include <algorithm>
@@ -60,12 +61,15 @@ void DrawList::finalize(TransientBufferPool& pool) {
merged_draw_calls_ = 0;
u32 writeIdx = 0;
+ u32 breaks[static_cast<u32>(BatchBreak::Count)] = {};
for (u32 i = 0; i < count; ++i) {
bool didMerge = false;
+ BatchBreak blocker = BatchBreak::RunStart;
if (writeIdx > 0) {
DrawCommand& head = commands_[writeIdx - 1];
- if (head.canMergeWith(commands_[i])) {
+ blocker = head.mergeBlocker(commands_[i]);
+ if (blocker == BatchBreak::None) {
if (head.layout_id == LayoutId::Batch && commands_[i].texture_count >= 1) {
// Multi-texture: give this command's texture a slot in the head's set
// (or bail to a new draw if all 8 slots are taken), then stamp its verts.
@@ -78,6 +82,8 @@ void DrawList::finalize(TransientBufferPool& pool) {
head.index_count += commands_[i].index_count;
head.entity_count += commands_[i].entity_count;
didMerge = true;
+ } else {
+ blocker = BatchBreak::TextureSlots;
}
} else {
head.index_count += commands_[i].index_count;
@@ -90,6 +96,8 @@ void DrawList::finalize(TransientBufferPool& pool) {
if (writeIdx != i) {
commands_[writeIdx] = commands_[i];
}
+ commands_[writeIdx].break_reason = blocker;
+ ++breaks[static_cast<u32>(blocker)];
// The run head owns slot 0; staging verts already default to texIndex 0,
// so it needs no rewrite (this is the common single-texture case).
++writeIdx;
@@ -97,6 +105,18 @@ void DrawList::finalize(TransientBufferPool& pool) {
}
commands_.resize(writeIdx);
merged_draw_calls_ = writeIdx;
+
+ // What the frame's draw-call count is made of. Emitted per reason and only
+ // where it happened, so a clean frame publishes nothing rather than a wall
+ // of zeroes for a caller to read past.
+ if (FrameProfiler::get().enabled()) {
+ ES_PROFILE_COUNTER("batch.draws", merged_draw_calls_);
+ ES_PROFILE_COUNTER("batch.merged", count - merged_draw_calls_);
+ for (u32 r = 1; r < static_cast<u32>(BatchBreak::Count); ++r) {
+ if (breaks[r] == 0) continue;
+ FrameProfiler::get().counter(batchBreakCounter(static_cast<BatchBreak>(r)), breaks[r]);
+ }
+ }
}
void DrawList::execute(GfxDevice& device, TransientBufferPool& buffers,
@@ -193,7 +213,7 @@ void DrawList::execute(GfxDevice& device, TransientBufferPool& buffers,
0, cmd.shader_id,
0, cmd.index_count / 3,
cmd.layer,
- FlushReason::FrameEnd,
+ cmd.break_reason,
cmd.scissor,
(cmd.state_flags & CMD_STATE_SCISSOR) != 0,
(cmd.state_flags & CMD_STATE_STENCIL_WRITE) != 0,
diff --git a/src/esengine/renderer/frame/FrameCapture.cpp b/src/esengine/renderer/frame/FrameCapture.cpp
index 60daf3b65..8e47732cb 100644
--- a/src/esengine/renderer/frame/FrameCapture.cpp
+++ b/src/esengine/renderer/frame/FrameCapture.cpp
@@ -32,7 +32,7 @@ void FrameCapture::endCapture() {
void FrameCapture::recordDrawCall(RenderStage stage, RenderType type, BlendMode blend_mode,
u32 texture_id, u32 material_id, u32 shader_id,
u32 vertex_count, u32 triangle_count, i32 layer,
- FlushReason reason, const ScissorRect& scissor,
+ BatchBreak reason, const ScissorRect& scissor,
bool scissor_enabled, bool stencil_write, bool stencil_test,
i32 stencil_ref, u8 texture_slot_usage) {
if (replay_mode_) {
@@ -56,7 +56,7 @@ void FrameCapture::recordDrawCall(RenderStage stage, RenderType type, BlendMode
record.vertex_count = vertex_count;
record.triangle_count = triangle_count;
record.layer = layer;
- record.flush_reason = reason;
+ record.break_reason = reason;
record.scissor = scissor;
record.scissor_enabled = scissor_enabled;
record.stencil_write = stencil_write;
diff --git a/src/esengine/renderer/frame/FrameCapture.hpp b/src/esengine/renderer/frame/FrameCapture.hpp
index 891fb2e6e..8dc70a167 100644
--- a/src/esengine/renderer/frame/FrameCapture.hpp
+++ b/src/esengine/renderer/frame/FrameCapture.hpp
@@ -6,23 +6,12 @@
#include "../draw/RenderItem.hpp"
#include "./RenderStage.hpp"
#include "../draw/BlendMode.hpp"
+#include "../draw/DrawCommand.hpp"
#include <vector>
namespace esengine {
-enum class FlushReason : u8 {
- BatchFull = 0,
- TextureSlotsFull = 1,
- ScissorChange = 2,
- StencilChange = 3,
- MaterialChange = 4,
- BlendModeChange = 5,
- StageEnd = 6,
- TypeChange = 7,
- FrameEnd = 8,
-};
-
struct DrawCallRecord {
u32 index = 0;
u32 camera_index = 0;
@@ -37,7 +26,7 @@ struct DrawCallRecord {
u32 entity_count = 0;
u32 entity_offset = 0;
i32 layer = 0;
- FlushReason flush_reason = FlushReason::FrameEnd;
+ BatchBreak break_reason = BatchBreak::RunStart;
ScissorRect scissor;
bool scissor_enabled = false;
bool stencil_write = false;
@@ -64,7 +53,7 @@ public:
void recordDrawCall(RenderStage stage, RenderType type, BlendMode blend_mode,
u32 texture_id, u32 material_id, u32 shader_id,
u32 vertex_count, u32 triangle_count, i32 layer,
- FlushReason reason, const ScissorRect& scissor,
+ BatchBreak reason, const ScissorRect& scissor,
bool scissor_enabled, bool stencil_write, bool stencil_test,
i32 stencil_ref, u8 texture_slot_usage);