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
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.mdindex 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 — nowruns 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 overplain per-frame data, so the live view, a pinned frame and a recorded sessioncannot each round their own way to a different answer. The editor's owndiff --git a/desktop/src/engine/EditorControlSurface.ts b/desktop/src/engine/EditorControlSurface.tsindex 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.tsindex 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.tsindex 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.mdindex bebc5b149..acf545d4e 100644--- a/sdk/etc/index.api.md+++ b/sdk/etc/index.api.md@@ -1067,6 +1067,24 @@ resolveUrl: (path: string) => stringsetBaseUrl: ((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 | undefinedbuild: (app: App) => voidcleanup: (app: App) => voidname: string+profileDomain: "diagnostics"static new (options_?: DiagnosticsPluginOptions): DiagnosticsPluginstatic prototype: DiagnosticsPlugin```@@ -2407,11 +2426,11 @@ textureRotated: (position: Vec2, size: Vec2, rotation: number, textureHandle: nu## DrawCallInfo — interface @experimental```blendMode: number+breakReason: BatchBreakcameraIndex: numberentities: number[]entityCount: numberentityOffset: number-flushReason: FlushReasonindex: numberlayer: numbermaterialId: number@@ -2664,6 +2683,7 @@ rows: EventBindingRow[]build: (app: App) => voidcleanup: () => voidname: string+profileDomain: "events"static new (): EventBindingPluginstatic 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[] | undefinedbuild: (app: App) => voidcleanup: () => voidname: string+profileDomain: "render"static new (): Mesh2DPluginstatic prototype: Mesh2DPlugin```@@ -5192,6 +5200,7 @@ static prototype: PostProcessAPIbuild: (app: App) => voidcleanup: (app?: App) => voidname: string+profileDomain: "render"static new (): PostProcessPluginstatic prototype: PostProcessPlugin```@@ -6352,6 +6361,7 @@ visitorEntity: number```build: (app: App) => voidname: string+profileDomain: "services"static new (): ServicesPluginstatic prototype: ServicesPlugin```@@ -8073,6 +8083,7 @@ generation: number```build: (app: App) => voidname: string+profileDomain: "ui"static new (): UILayoutPluginstatic prototype: UILayoutPlugin```diff --git a/sdk/etc/index.native.api.md b/sdk/etc/index.native.api.mdindex 430c6d318..bdda5c498 100644--- a/sdk/etc/index.native.api.md+++ b/sdk/etc/index.native.api.md@@ -1067,6 +1067,24 @@ resolveUrl: (path: string) => stringsetBaseUrl: ((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 | undefinedbuild: (app: App) => voidcleanup: (app: App) => voidname: string+profileDomain: "diagnostics"static new (options_?: DiagnosticsPluginOptions): DiagnosticsPluginstatic prototype: DiagnosticsPlugin```@@ -2415,11 +2434,11 @@ textureRotated: (position: Vec2, size: Vec2, rotation: number, textureHandle: nu## DrawCallInfo — interface @experimental```blendMode: number+breakReason: BatchBreakcameraIndex: numberentities: number[]entityCount: numberentityOffset: number-flushReason: FlushReasonindex: numberlayer: numbermaterialId: number@@ -2672,6 +2691,7 @@ rows: EventBindingRow[]build: (app: App) => voidcleanup: () => voidname: string+profileDomain: "events"static new (): EventBindingPluginstatic 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[] | undefinedbuild: (app: App) => voidcleanup: () => voidname: string+profileDomain: "render"static new (): Mesh2DPluginstatic prototype: Mesh2DPlugin```@@ -5375,6 +5383,7 @@ static prototype: PostProcessAPIbuild: (app: App) => voidcleanup: (app?: App) => voidname: string+profileDomain: "render"static new (): PostProcessPluginstatic prototype: PostProcessPlugin```@@ -6545,6 +6554,7 @@ visitorEntity: number```build: (app: App) => voidname: string+profileDomain: "services"static new (): ServicesPluginstatic prototype: ServicesPlugin```@@ -8266,6 +8276,7 @@ generation: number```build: (app: App) => voidname: string+profileDomain: "ui"static new (): UILayoutPluginstatic prototype: UILayoutPlugin```diff --git a/sdk/etc/index.node.api.md b/sdk/etc/index.node.api.mdindex 578370a23..e6d551d30 100644--- a/sdk/etc/index.node.api.md+++ b/sdk/etc/index.node.api.md@@ -1062,6 +1062,24 @@ resolveUrl: (path: string) => stringsetBaseUrl: ((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 | undefinedbuild: (app: App) => voidcleanup: (app: App) => voidname: string+profileDomain: "diagnostics"static new (options_?: DiagnosticsPluginOptions): DiagnosticsPluginstatic prototype: DiagnosticsPlugin```@@ -2402,11 +2421,11 @@ textureRotated: (position: Vec2, size: Vec2, rotation: number, textureHandle: nu## DrawCallInfo — interface @experimental```blendMode: number+breakReason: BatchBreakcameraIndex: numberentities: number[]entityCount: numberentityOffset: number-flushReason: FlushReasonindex: numberlayer: numbermaterialId: number@@ -2659,6 +2678,7 @@ rows: EventBindingRow[]build: (app: App) => voidcleanup: () => voidname: string+profileDomain: "events"static new (): EventBindingPluginstatic 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[] | undefinedbuild: (app: App) => voidcleanup: () => voidname: string+profileDomain: "render"static new (): Mesh2DPluginstatic prototype: Mesh2DPlugin```@@ -5187,6 +5195,7 @@ static prototype: PostProcessAPIbuild: (app: App) => voidcleanup: (app?: App) => voidname: string+profileDomain: "render"static new (): PostProcessPluginstatic prototype: PostProcessPlugin```@@ -6347,6 +6356,7 @@ visitorEntity: number```build: (app: App) => voidname: string+profileDomain: "services"static new (): ServicesPluginstatic prototype: ServicesPlugin```@@ -8068,6 +8078,7 @@ generation: number```build: (app: App) => voidname: string+profileDomain: "ui"static new (): UILayoutPluginstatic prototype: UILayoutPlugin```diff --git a/sdk/etc/minigame.api.md b/sdk/etc/minigame.api.mdindex a45927f9d..62231a716 100644--- a/sdk/etc/minigame.api.md+++ b/sdk/etc/minigame.api.md@@ -1062,6 +1062,24 @@ resolveUrl: (path: string) => stringsetBaseUrl: ((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 | undefinedbuild: (app: App) => voidcleanup: (app: App) => voidname: string+profileDomain: "diagnostics"static new (options_?: DiagnosticsPluginOptions): DiagnosticsPluginstatic prototype: DiagnosticsPlugin```@@ -2402,11 +2421,11 @@ textureRotated: (position: Vec2, size: Vec2, rotation: number, textureHandle: nu## DrawCallInfo — interface @experimental```blendMode: number+breakReason: BatchBreakcameraIndex: numberentities: number[]entityCount: numberentityOffset: number-flushReason: FlushReasonindex: numberlayer: numbermaterialId: number@@ -2659,6 +2678,7 @@ rows: EventBindingRow[]build: (app: App) => voidcleanup: () => voidname: string+profileDomain: "events"static new (): EventBindingPluginstatic 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[] | undefinedbuild: (app: App) => voidcleanup: () => voidname: string+profileDomain: "render"static new (): Mesh2DPluginstatic prototype: Mesh2DPlugin```@@ -5432,6 +5440,7 @@ static prototype: PostProcessAPIbuild: (app: App) => voidcleanup: (app?: App) => voidname: string+profileDomain: "render"static new (): PostProcessPluginstatic prototype: PostProcessPlugin```@@ -6592,6 +6601,7 @@ visitorEntity: number```build: (app: App) => voidname: string+profileDomain: "services"static new (): ServicesPluginstatic prototype: ServicesPlugin```@@ -8313,6 +8323,7 @@ generation: number```build: (app: App) => voidname: string+profileDomain: "ui"static new (): UILayoutPluginstatic prototype: UILayoutPlugin```diff --git a/sdk/etc/wechat.api.md b/sdk/etc/wechat.api.mdindex dc55d6aa1..1d64332e3 100644--- a/sdk/etc/wechat.api.md+++ b/sdk/etc/wechat.api.md@@ -1062,6 +1062,24 @@ resolveUrl: (path: string) => stringsetBaseUrl: ((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 | undefinedbuild: (app: App) => voidcleanup: (app: App) => voidname: string+profileDomain: "diagnostics"static new (options_?: DiagnosticsPluginOptions): DiagnosticsPluginstatic prototype: DiagnosticsPlugin```@@ -2402,11 +2421,11 @@ textureRotated: (position: Vec2, size: Vec2, rotation: number, textureHandle: nu## DrawCallInfo — interface @experimental```blendMode: number+breakReason: BatchBreakcameraIndex: numberentities: number[]entityCount: numberentityOffset: number-flushReason: FlushReasonindex: numberlayer: numbermaterialId: number@@ -2659,6 +2678,7 @@ rows: EventBindingRow[]build: (app: App) => voidcleanup: () => voidname: string+profileDomain: "events"static new (): EventBindingPluginstatic 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[] | undefinedbuild: (app: App) => voidcleanup: () => voidname: string+profileDomain: "render"static new (): Mesh2DPluginstatic prototype: Mesh2DPlugin```@@ -5194,6 +5202,7 @@ static prototype: PostProcessAPIbuild: (app: App) => voidcleanup: (app?: App) => voidname: string+profileDomain: "render"static new (): PostProcessPluginstatic prototype: PostProcessPlugin```@@ -6354,6 +6363,7 @@ visitorEntity: number```build: (app: App) => voidname: string+profileDomain: "services"static new (): ServicesPluginstatic prototype: ServicesPlugin```@@ -8075,6 +8085,7 @@ generation: number```build: (app: App) => voidname: string+profileDomain: "ui"static new (): UILayoutPluginstatic prototype: UILayoutPlugin```diff --git a/sdk/src/core-render.ts b/sdk/src/core-render.tsindex 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.tsindex 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.tsindex 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.tsindex 9154d6f02..0970b1080 100644--- a/sdk/src/eventBinding.ts+++ b/sdk/src/eventBinding.ts@@ -245,6 +245,7 @@ export function createEventBindingRuntime(host: EventBindingHost): EventBindingRexport 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.tsindex 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 andiff --git a/sdk/src/render/frameCapture.ts b/sdk/src/render/frameCapture.tsindex 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 | nconst 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 | ntextureId, 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.tsindex 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.tsindex 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.tsindex 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 storediff --git a/sdk/src/ui/behavior/plugin.ts b/sdk/src/ui/behavior/plugin.tsindex 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.tsindex 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 adiff --git a/sdk/src/ui/layout/layout.ts b/sdk/src/ui/layout/layout.tsindex 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.tsindex 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.tsindex 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.tsindex 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.hppindex 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.cppindex 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.cppindex 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, BlendModerecord.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.hppindex 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);