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(render): the device counts every draw a frame asks of the GPU, every pass included, and a quality level holds a draw call budget against it
yhhf001348a9dad
diff --git a/desktop b/desktopindex 98b847df0..6522a4a66 160000--- a/desktop+++ b/desktop@@ -1 +1 @@-Subproject commit 98b847df0e354da9a5b52ea8417ffaedf31eb7bf+Subproject commit 6522a4a66da1ae75b6ced024d5cb265513bfb7eediff --git a/docs/astro/src/content/docs/performance/profiling.mdx b/docs/astro/src/content/docs/performance/profiling.mdxindex 865a47b6c..d4be9608f 100644--- a/docs/astro/src/content/docs/performance/profiling.mdx+++ b/docs/astro/src/content/docs/performance/profiling.mdx@@ -65,7 +65,9 @@ the render counters are the current frame's):| `entityCount` | number | Live entities in the world. || `systemTimings` | `Map<string, number>` | CPU ms per system this frame, keyed by system name. || `phaseTimings` | `Map<string, number>` | CPU ms per schedule phase this frame. |-| `drawCalls` | number | GPU draw calls issued this frame. |+| `drawCalls` | number | Draws of the scene's and the overlay's lists after batching: what the frame capture lists. |+| `gpuDraws` | number | Every draw the GPU was asked for this frame, every pass included: shadow maps, the depth pre-pass, reflections, motion vectors and post-processing as well as the scene. |+| `drawCallBudget` | number | The draw call budget of the quality level in force; 0 when the app has no quality levels. || `triangles` | number | Triangles submitted this frame. || `sprites` | number | Sprites rendered this frame. || `text` | number | Text entities rendered this frame. |@@ -108,7 +110,7 @@ addSystem(feedOverlay);The render counters in `FrameStats` come from `Renderer.getStats()`, which youcan also call directly (no stats plugin needed) — it returns a `RenderStats`-with the same seven fields: `drawCalls`, `triangles`, `sprites`, `text`,+with the same fields: `drawCalls`, `gpuDraws`, `triangles`, `sprites`, `text`,`skeletal`, `meshes`, `culled`.```typescript@@ -118,6 +120,28 @@ const rs = Renderer.getStats();console.log(`${rs.drawCalls} draw calls, ${rs.triangles} triangles`);```+### Where the draws went++`drawCalls` and `gpuDraws` are different numbers on purpose. On the `dusk-fort` example, a lit scene with a+shadowing sun and a post-process volume, the lists draw 18 times and the GPU is asked for 52: 17 shadow casters+and 17 post-processing and other passes the lists never see. A budget is held to `gpuDraws`.++`drawBudgetReport` splits a frame's `gpuDraws` by pass, from the engine counters a frame stats report carries+(`batch.draws`, `render.shadow.draws`, `render.prepass.draws`, `render.planar.draws`, `render.motion.draws`,+`render.cover.draws`). What no pass claims is `other`, so the shares always add up to the GPU's count. The per-pass+counters are published only while the frame profiler is on; without them, everything but the lists is `other`.++```typescript+import { drawBudgetReport } from 'esengine';++const r = drawBudgetReport(gpuDraws, budget, counters);+for (const p of r.passes) console.log(`${p.pass}: ${p.draws}`);+if (r.over > 0) console.warn(`${r.over} draws over the budget of ${r.budget}`);+```++The editor's Profiler shows the same breakdown in its **Render** module. The budget itself is a setting of each+[quality level](/docs/performance/quality-levels/).+## Building your own toolingTwo small utilities back the plugin and are exported for custom tooling:diff --git a/docs/astro/src/content/docs/performance/quality-levels.mdx b/docs/astro/src/content/docs/performance/quality-levels.mdxindex f7ae3a86d..3a670efb4 100644--- a/docs/astro/src/content/docs/performance/quality-levels.mdx+++ b/docs/astro/src/content/docs/performance/quality-levels.mdx@@ -29,7 +29,7 @@ to.| Group | Settings ||---|---|-| Rendering | Render scale, Min render scale, Anti-aliasing (MSAA or Temporal), MSAA, Depth pre-pass, Detail distance, 2D rain shelter mask |+| Rendering | Render scale, Min render scale, Anti-aliasing (MSAA or Temporal), MSAA, Depth pre-pass, Detail distance, Draw call budget, 2D rain shelter mask || Shadows | Atlas size, Cell size, Cascades, Distance, 2D soft-shadow samples || Reflections and particles | Planar reflection scale, max size and updates per second, Particle limit || Water | Water waves (1 to 4), Water ripple cells, and the Displacement, Mirror and Caustics switches. Shown once the level is not Off and the water module is in the build |@@ -54,6 +54,14 @@ at Medium.cheaper mesh at 60 m and is not drawn as itself past 150 m does so at 30 m and 75 m, and its far cards take over sooner.Low keeps 0.5, Medium 0.8 and High all of it, so the same world draws a fraction of the triangles on a phone.+**Draw call budget** is the most draws a frame at the level should ask of the GPU: 150 at Low, 400 at Medium and 1,500 at+High. Every pass counts, not only the scene's own list: each shadow cascade draws its casters again, the depth pre-pass draws+the opaque scene again, and post-processing adds a draw per pass. Nothing is held back to meet it. The Profiler's **Render**+module shows the frame's GPU draws against the budget and splits them by pass, and the stats overlay turns the count red past+it. A draw costs the CPU and the driver more than the GPU, and on a phone or in a mini game it is what a 3D scene runs out of+first. To bring it down, see [Static batching](/docs/performance/static-batching/) for many different meshes and fewer shadow+cascades for the shadow pass.+## Leaving effects outEvery post-process effect the engine has is in the list, ticked where the level runs it. An unticked effect is skippeddiff --git a/docs/astro/src/content/docs/zh-cn/performance/profiling.mdx b/docs/astro/src/content/docs/zh-cn/performance/profiling.mdxindex 116eb32c6..3cf3f2f20 100644--- a/docs/astro/src/content/docs/zh-cn/performance/profiling.mdx+++ b/docs/astro/src/content/docs/zh-cn/performance/profiling.mdx@@ -62,7 +62,9 @@ addSystem(watchPerf);| `entityCount` | number | 世界中的存活实体数。 || `systemTimings` | `Map<string, number>` | 本帧每个系统的 CPU 毫秒数,按系统名索引。 || `phaseTimings` | `Map<string, number>` | 本帧每个调度阶段的 CPU 毫秒数。 |-| `drawCalls` | number | 本帧发出的 GPU draw call 数。 |+| `drawCalls` | number | 场景和叠加层绘制列表合批后的 draw 数,也就是帧捕获列出的那些。 |+| `gpuDraws` | number | 本帧向 GPU 发出的全部 draw,所有 pass 都算:除了场景,还有阴影贴图、深度预通道、反射、运动矢量和后处理。 |+| `drawCallBudget` | number | 当前画质档位的 draw call 预算;应用没有画质档位时为 0。 || `triangles` | number | 本帧提交的三角形数。 || `sprites` | number | 本帧渲染的精灵数。 || `text` | number | 本帧渲染的文本实体数。 |@@ -100,7 +102,7 @@ addSystem(feedOverlay);## 渲染器计数 — `Renderer.getStats()``FrameStats` 里的渲染计数来自 `Renderer.getStats()`,也可以直接调用(不需要-stats 插件)——它返回一个 `RenderStats`,同样是那七个字段:`drawCalls`、+stats 插件)——它返回一个 `RenderStats`,字段相同:`drawCalls`、`gpuDraws`、`triangles`、`sprites`、`text`、`skeletal`、`meshes`、`culled`。```typescript@@ -110,6 +112,22 @@ const rs = Renderer.getStats();console.log(`${rs.drawCalls} draw calls, ${rs.triangles} triangles`);```+### draw 都去了哪里++`drawCalls` 和 `gpuDraws` 是有意不同的两个数。在 `dusk-fort` 示例里(有投影的太阳和后处理体积的光照场景),绘制列表画了 18 次,GPU 却收到 52 次:17 次是阴影投影物,17 次是后处理和其他绘制列表看不到的 pass。预算比的是 `gpuDraws`。++`drawBudgetReport` 根据帧统计报告里的引擎计数(`batch.draws`、`render.shadow.draws`、`render.prepass.draws`、`render.planar.draws`、`render.motion.draws`、`render.cover.draws`),把一帧的 `gpuDraws` 按 pass 拆开。没有被任何 pass 认领的算作 `other`,所以各部分加起来总是等于 GPU 的数。各 pass 的计数只在帧分析器开着时才发布;没有时,除了绘制列表都算在 `other` 里。++```typescript+import { drawBudgetReport } from 'esengine';++const r = drawBudgetReport(gpuDraws, budget, counters);+for (const p of r.passes) console.log(`${p.pass}: ${p.draws}`);+if (r.over > 0) console.warn(`超出预算 ${r.budget} 共 ${r.over}`);+```++编辑器 Profiler 的**渲染**模块显示同样的拆分。预算本身是每个[画质档位](/docs/zh-cn/performance/quality-levels/)的设置。+## 自建工具插件背后有两个小工具类,均已导出供自定义工具使用:diff --git a/docs/astro/src/content/docs/zh-cn/performance/quality-levels.mdx b/docs/astro/src/content/docs/zh-cn/performance/quality-levels.mdxindex faf3a61df..abd47a345 100644--- a/docs/astro/src/content/docs/zh-cn/performance/quality-levels.mdx+++ b/docs/astro/src/content/docs/zh-cn/performance/quality-levels.mdx@@ -27,7 +27,7 @@ import { Aside } from '@astrojs/starlight/components';| 分组 | 设置 ||---|---|-| 渲染 | 渲染比例、最小渲染比例、抗锯齿方式(MSAA 或时间性)、MSAA、深度预通道、细节距离、2D 雨遮罩尺寸 |+| 渲染 | 渲染比例、最小渲染比例、抗锯齿方式(MSAA 或时间性)、MSAA、深度预通道、细节距离、Draw call 预算、2D 雨遮罩尺寸 || 阴影 | 图集尺寸、单元尺寸、级联数、距离、2D 软阴影采样数 || 反射与粒子 | 平面反射的比例、最大尺寸和每秒更新次数,粒子上限 || 水体 | 水体波数(1 到 4)、水体涟漪格数,以及位移、镜面、焦散三个开关。档位不是关闭、且构建里带水体模块时才显示 |@@ -44,6 +44,8 @@ import { Aside } from '@astrojs/starlight/components';**细节距离**是一档里放置的植物保留多少比例的距离:0.5 时,原本 60 米换成更省网格、150 米外不再画本体的树,会在 30 米和 75 米处这样做,远景卡片也更早接手。低档保留 0.5、中档 0.8、高档全部,所以同一个世界在手机上画的三角形只有一小部分。+**Draw call 预算**是这一档每帧最多应向 GPU 发出的 draw 数:低档 150、中档 400、高档 1500。所有 pass 都算,不只是场景自己的绘制列表:每个阴影级联都要把投影物再画一次,深度预通道要把不透明场景再画一次,后处理每个 pass 也要一次 draw。不会为了达标而少画什么。Profiler 的**渲染**模块显示这一帧的 GPU draw 数和预算,并按 pass 拆开;统计浮层在超出时把数字标红。一次 draw 花在 CPU 和驱动上的比花在 GPU 上的多,在手机和小游戏里,3D 场景最先用完的就是它。要降下来,不同网格很多时看[静态合并](/docs/zh-cn/performance/static-batching/),阴影那部分则减少级联数。+## 去掉一些效果引擎有的每个后处理效果都在列表里,该档位运行的打勾。没勾选的效果在这个档位被跳过,不管相机的体积是否要求它——而且是整个跳过:diff --git a/sdk/etc/index.api.md b/sdk/etc/index.api.mdindex d5f27abd6..c234b213d 100644--- a/sdk/etc/index.api.md+++ b/sdk/etc/index.api.md@@ -1,7 +1,7 @@# API surface — esengine/index<!-- Generated by tools/api-surface.mjs — do not edit. Run --update to accept changes. -->-Symbols: 115 public · 161 beta · 1998 experimental · 3 deprecated+Symbols: 115 public · 161 beta · 2002 experimental · 3 deprecated## ABI_LAYOUT_HASH — const @experimental```@@ -3600,6 +3600,14 @@ textureRotated: (position: Vec2, size: Vec2, rotation: number, textureHandle: nuwithDepthState: (state: { test: boolean; write: boolean; }, draw: () => void) => boolean```+## DrawBudgetReport — interface @experimental+```+budget: number+draws: number+over: number+passes: DrawPassShare[]+```+## DrawCallInfo — interface @experimental```blendMode: number@@ -3641,6 +3649,17 @@ viewProjection: Float32Array<ArrayBufferLike>width: number```+## DrawPass — type @experimental+```+'lists' | 'shadow' | 'prepass' | 'reflection' | 'motion' | 'cover' | 'other'+```++## DrawPassShare — interface @experimental+```+draws: number+pass: DrawPass+```+## DrawRank — interface @experimental```groupInner: number | null | undefined@@ -4573,10 +4592,12 @@ systemTimings: Map<string, number>## FrameStats — interface @experimental```culled: number+drawCallBudget: numberdrawCalls: numberentityCount: numberfps: numberframeTimeMs: number+gpuDraws: numbermeshes: numberphaseTimings: Map<string, number>skeletal: number@@ -4597,6 +4618,7 @@ cppScopes: Record<string, number>drawCalls: numberentities: numberframeMs: number | undefined+gpuDraws: number | undefinedgpuMs: numbergpuScopes: Record<string, number>phases: Record<string, number>@@ -7997,6 +8019,7 @@ static prototype: QualityControllerantialiasing: "msaa" | "temporal"depthPrepass: booleandetailScale: number+drawCallBudget: numberminRenderScale: numbermsaaSamples: 2 | 1 | 4 | 8particleLimit: number@@ -8022,6 +8045,7 @@ waterWaves: number## QualityReport — interface @experimental```+drawCallBudget: numberframeMs: numberlevel: QualityLevellimitations: string[]@@ -8413,6 +8437,7 @@ Transparent = 2```culled: numberdrawCalls: number+gpuDraws: numbermeshes: numberskeletal: numbersprites: number@@ -14425,6 +14450,11 @@ DragPlugin(map: BasinMap, x: number, z: number): { x: number; z: number; y: number; }[]```+## drawBudgetReport — function @experimental+```+(gpuDraws: number, budget: number, counters: Readonly<Record<string, number>>, listDraws?: number): DrawBudgetReport+```+## drawPhysics3DDebug — function @experimental```(app: App, contacts?: readonly Contact3D[]): voiddiff --git a/sdk/etc/index.native.api.md b/sdk/etc/index.native.api.mdindex 1c87c2a1e..04d6527ff 100644--- a/sdk/etc/index.native.api.md+++ b/sdk/etc/index.native.api.md@@ -1,7 +1,7 @@# API surface — esengine/index.native<!-- Generated by tools/api-surface.mjs — do not edit. Run --update to accept changes. -->-Symbols: 115 public · 166 beta · 2017 experimental · 3 deprecated+Symbols: 115 public · 166 beta · 2021 experimental · 3 deprecated## ABI_LAYOUT_HASH — const @experimental```@@ -3608,6 +3608,14 @@ textureRotated: (position: Vec2, size: Vec2, rotation: number, textureHandle: nuwithDepthState: (state: { test: boolean; write: boolean; }, draw: () => void) => boolean```+## DrawBudgetReport — interface @experimental+```+budget: number+draws: number+over: number+passes: DrawPassShare[]+```+## DrawCallInfo — interface @experimental```blendMode: number@@ -3649,6 +3657,17 @@ viewProjection: Float32Array<ArrayBufferLike>width: number```+## DrawPass — type @experimental+```+'lists' | 'shadow' | 'prepass' | 'reflection' | 'motion' | 'cover' | 'other'+```++## DrawPassShare — interface @experimental+```+draws: number+pass: DrawPass+```+## DrawRank — interface @experimental```groupInner: number | null | undefined@@ -4581,10 +4600,12 @@ systemTimings: Map<string, number>## FrameStats — interface @experimental```culled: number+drawCallBudget: numberdrawCalls: numberentityCount: numberfps: numberframeTimeMs: number+gpuDraws: numbermeshes: numberphaseTimings: Map<string, number>skeletal: number@@ -4605,6 +4626,7 @@ cppScopes: Record<string, number>drawCalls: numberentities: numberframeMs: number | undefined+gpuDraws: number | undefinedgpuMs: numbergpuScopes: Record<string, number>phases: Record<string, number>@@ -8200,6 +8222,7 @@ static prototype: QualityControllerantialiasing: "msaa" | "temporal"depthPrepass: booleandetailScale: number+drawCallBudget: numberminRenderScale: numbermsaaSamples: 2 | 1 | 4 | 8particleLimit: number@@ -8225,6 +8248,7 @@ waterWaves: number## QualityReport — interface @experimental```+drawCallBudget: numberframeMs: numberlevel: QualityLevellimitations: string[]@@ -8626,6 +8650,7 @@ Transparent = 2```culled: numberdrawCalls: number+gpuDraws: numbermeshes: numberskeletal: numbersprites: number@@ -14678,6 +14703,11 @@ DragPlugin(map: BasinMap, x: number, z: number): { x: number; z: number; y: number; }[]```+## drawBudgetReport — function @experimental+```+(gpuDraws: number, budget: number, counters: Readonly<Record<string, number>>, listDraws?: number): DrawBudgetReport+```+## drawPhysics3DDebug — function @experimental```(app: App, contacts?: readonly Contact3D[]): voiddiff --git a/sdk/etc/index.node.api.md b/sdk/etc/index.node.api.mdindex 8b8922598..a5a9e04d7 100644--- a/sdk/etc/index.node.api.md+++ b/sdk/etc/index.node.api.md@@ -1,7 +1,7 @@# API surface — esengine/index.node<!-- Generated by tools/api-surface.mjs — do not edit. Run --update to accept changes. -->-Symbols: 115 public · 163 beta · 1997 experimental · 3 deprecated+Symbols: 115 public · 163 beta · 2001 experimental · 3 deprecated## ANCHOR_AXES — const @experimental```@@ -3595,6 +3595,14 @@ textureRotated: (position: Vec2, size: Vec2, rotation: number, textureHandle: nuwithDepthState: (state: { test: boolean; write: boolean; }, draw: () => void) => boolean```+## DrawBudgetReport — interface @experimental+```+budget: number+draws: number+over: number+passes: DrawPassShare[]+```+## DrawCallInfo — interface @experimental```blendMode: number@@ -3636,6 +3644,17 @@ viewProjection: Float32Array<ArrayBufferLike>width: number```+## DrawPass — type @experimental+```+'lists' | 'shadow' | 'prepass' | 'reflection' | 'motion' | 'cover' | 'other'+```++## DrawPassShare — interface @experimental+```+draws: number+pass: DrawPass+```+## DrawRank — interface @experimental```groupInner: number | null | undefined@@ -4568,10 +4587,12 @@ systemTimings: Map<string, number>## FrameStats — interface @experimental```culled: number+drawCallBudget: numberdrawCalls: numberentityCount: numberfps: numberframeTimeMs: number+gpuDraws: numbermeshes: numberphaseTimings: Map<string, number>skeletal: number@@ -4592,6 +4613,7 @@ cppScopes: Record<string, number>drawCalls: numberentities: numberframeMs: number | undefined+gpuDraws: number | undefinedgpuMs: numbergpuScopes: Record<string, number>phases: Record<string, number>@@ -7992,6 +8014,7 @@ static prototype: QualityControllerantialiasing: "msaa" | "temporal"depthPrepass: booleandetailScale: number+drawCallBudget: numberminRenderScale: numbermsaaSamples: 2 | 1 | 4 | 8particleLimit: number@@ -8017,6 +8040,7 @@ waterWaves: number## QualityReport — interface @experimental```+drawCallBudget: numberframeMs: numberlevel: QualityLevellimitations: string[]@@ -8408,6 +8432,7 @@ Transparent = 2```culled: numberdrawCalls: number+gpuDraws: numbermeshes: numberskeletal: numbersprites: number@@ -14420,6 +14445,11 @@ DragPlugin(map: BasinMap, x: number, z: number): { x: number; z: number; y: number; }[]```+## drawBudgetReport — function @experimental+```+(gpuDraws: number, budget: number, counters: Readonly<Record<string, number>>, listDraws?: number): DrawBudgetReport+```+## drawPhysics3DDebug — function @experimental```(app: App, contacts?: readonly Contact3D[]): voiddiff --git a/sdk/etc/minigame.api.md b/sdk/etc/minigame.api.mdindex 11b64a616..1cc304786 100644--- a/sdk/etc/minigame.api.md+++ b/sdk/etc/minigame.api.md@@ -1,7 +1,7 @@# API surface — esengine/minigame<!-- Generated by tools/api-surface.mjs — do not edit. Run --update to accept changes. -->-Symbols: 115 public · 161 beta · 2019 experimental · 3 deprecated+Symbols: 115 public · 161 beta · 2023 experimental · 3 deprecated## ANCHOR_AXES — const @experimental```@@ -3595,6 +3595,14 @@ textureRotated: (position: Vec2, size: Vec2, rotation: number, textureHandle: nuwithDepthState: (state: { test: boolean; write: boolean; }, draw: () => void) => boolean```+## DrawBudgetReport — interface @experimental+```+budget: number+draws: number+over: number+passes: DrawPassShare[]+```+## DrawCallInfo — interface @experimental```blendMode: number@@ -3636,6 +3644,17 @@ viewProjection: Float32Array<ArrayBufferLike>width: number```+## DrawPass — type @experimental+```+'lists' | 'shadow' | 'prepass' | 'reflection' | 'motion' | 'cover' | 'other'+```++## DrawPassShare — interface @experimental+```+draws: number+pass: DrawPass+```+## DrawRank — interface @experimental```groupInner: number | null | undefined@@ -4568,10 +4587,12 @@ systemTimings: Map<string, number>## FrameStats — interface @experimental```culled: number+drawCallBudget: numberdrawCalls: numberentityCount: numberfps: numberframeTimeMs: number+gpuDraws: numbermeshes: numberphaseTimings: Map<string, number>skeletal: number@@ -4592,6 +4613,7 @@ cppScopes: Record<string, number>drawCalls: numberentities: numberframeMs: number | undefined+gpuDraws: number | undefinedgpuMs: numbergpuScopes: Record<string, number>phases: Record<string, number>@@ -8287,6 +8309,7 @@ static prototype: QualityControllerantialiasing: "msaa" | "temporal"depthPrepass: booleandetailScale: number+drawCallBudget: numberminRenderScale: numbermsaaSamples: 2 | 1 | 4 | 8particleLimit: number@@ -8312,6 +8335,7 @@ waterWaves: number## QualityReport — interface @experimental```+drawCallBudget: numberframeMs: numberlevel: QualityLevellimitations: string[]@@ -8703,6 +8727,7 @@ Transparent = 2```culled: numberdrawCalls: number+gpuDraws: numbermeshes: numberskeletal: numbersprites: number@@ -14726,6 +14751,11 @@ DragPlugin(map: BasinMap, x: number, z: number): { x: number; z: number; y: number; }[]```+## drawBudgetReport — function @experimental+```+(gpuDraws: number, budget: number, counters: Readonly<Record<string, number>>, listDraws?: number): DrawBudgetReport+```+## drawPhysics3DDebug — function @experimental```(app: App, contacts?: readonly Contact3D[]): voiddiff --git a/sdk/etc/wasm.api.md b/sdk/etc/wasm.api.mdindex d16ee4cbd..f604560e3 100644--- a/sdk/etc/wasm.api.md+++ b/sdk/etc/wasm.api.md@@ -482,6 +482,7 @@ renderer_getCapturedTextures: () => numberrenderer_getCulled: () => numberrenderer_getDrawCalls: () => numberrenderer_getEstimatedGpuBytes: (() => number) | undefined+renderer_getGpuDrawCalls: (() => number) | undefinedrenderer_getGpuTimeMs: (() => number) | undefinedrenderer_getLiveObjects: (() => GfxLiveObjects | null) | undefinedrenderer_getMeshes: () => numberdiff --git a/sdk/etc/wechat.api.md b/sdk/etc/wechat.api.mdindex 9d2367b27..04ed520da 100644--- a/sdk/etc/wechat.api.md+++ b/sdk/etc/wechat.api.md@@ -1,7 +1,7 @@# API surface — esengine/wechat<!-- Generated by tools/api-surface.mjs — do not edit. Run --update to accept changes. -->-Symbols: 115 public · 161 beta · 2010 experimental · 3 deprecated+Symbols: 115 public · 161 beta · 2014 experimental · 3 deprecated## ANCHOR_AXES — const @experimental```@@ -3595,6 +3595,14 @@ textureRotated: (position: Vec2, size: Vec2, rotation: number, textureHandle: nuwithDepthState: (state: { test: boolean; write: boolean; }, draw: () => void) => boolean```+## DrawBudgetReport — interface @experimental+```+budget: number+draws: number+over: number+passes: DrawPassShare[]+```+## DrawCallInfo — interface @experimental```blendMode: number@@ -3636,6 +3644,17 @@ viewProjection: Float32Array<ArrayBufferLike>width: number```+## DrawPass — type @experimental+```+'lists' | 'shadow' | 'prepass' | 'reflection' | 'motion' | 'cover' | 'other'+```++## DrawPassShare — interface @experimental+```+draws: number+pass: DrawPass+```+## DrawRank — interface @experimental```groupInner: number | null | undefined@@ -4568,10 +4587,12 @@ systemTimings: Map<string, number>## FrameStats — interface @experimental```culled: number+drawCallBudget: numberdrawCalls: numberentityCount: numberfps: numberframeTimeMs: number+gpuDraws: numbermeshes: numberphaseTimings: Map<string, number>skeletal: number@@ -4592,6 +4613,7 @@ cppScopes: Record<string, number>drawCalls: numberentities: numberframeMs: number | undefined+gpuDraws: number | undefinedgpuMs: numbergpuScopes: Record<string, number>phases: Record<string, number>@@ -7999,6 +8021,7 @@ static prototype: QualityControllerantialiasing: "msaa" | "temporal"depthPrepass: booleandetailScale: number+drawCallBudget: numberminRenderScale: numbermsaaSamples: 2 | 1 | 4 | 8particleLimit: number@@ -8024,6 +8047,7 @@ waterWaves: number## QualityReport — interface @experimental```+drawCallBudget: numberframeMs: numberlevel: QualityLevellimitations: string[]@@ -8415,6 +8439,7 @@ Transparent = 2```culled: numberdrawCalls: number+gpuDraws: numbermeshes: numberskeletal: numbersprites: number@@ -14452,6 +14477,11 @@ DragPlugin(map: BasinMap, x: number, z: number): { x: number; z: number; y: number; }[]```+## drawBudgetReport — function @experimental+```+(gpuDraws: number, budget: number, counters: Readonly<Record<string, number>>, listDraws?: number): DrawBudgetReport+```+## drawPhysics3DDebug — function @experimental```(app: App, contacts?: readonly Contact3D[]): voiddiff --git a/sdk/src/core-content.ts b/sdk/src/core-content.tsindex 4de78b580..09249ad9d 100644--- a/sdk/src/core-content.ts+++ b/sdk/src/core-content.ts@@ -857,6 +857,7 @@ export {mergeMeshes, planStaticBatches, STATIC_BATCH_DEFAULTS,type StaticBatchGroup, type StaticBatchLimits, type StaticBatchRefusal, type StaticBatchReport,} from './render/staticBatch';+export { drawBudgetReport, type DrawBudgetReport, type DrawPass, type DrawPassShare } from './render/drawBudget';// =============================================================================// Tilemapdiff --git a/sdk/src/ecs/bridge/nativeBindings.ts b/sdk/src/ecs/bridge/nativeBindings.tsindex 04dbb4da1..d204f5f7b 100644--- a/sdk/src/ecs/bridge/nativeBindings.ts+++ b/sdk/src/ecs/bridge/nativeBindings.ts@@ -153,6 +153,7 @@ export const RENDERER_BINDINGS = {* module exposes under the same names, so the two paths report identically. */export const RENDERER_STATS_BINDINGS = {drawCalls: 'es_renderer_getDrawCalls',+ gpuDraws: 'es_renderer_getGpuDrawCalls',triangles: 'es_renderer_getTriangles',sprites: 'es_renderer_getSprites',text: 'es_renderer_getText',diff --git a/sdk/src/ecs/bridge/nativeEngineApi.generated.ts b/sdk/src/ecs/bridge/nativeEngineApi.generated.tsindex ece62d8ea..eb4a3d3a1 100644--- a/sdk/src/ecs/bridge/nativeEngineApi.generated.ts+++ b/sdk/src/ecs/bridge/nativeEngineApi.generated.ts@@ -173,6 +173,7 @@ export interface NativeEngineApi {renderer_getCulled?(): number;renderer_getDrawCalls?(): number;renderer_getEstimatedGpuBytes?(): number;+ renderer_getGpuDrawCalls?(): number;renderer_getGpuTimeMs?(): number;renderer_getMeshes?(): number;renderer_getPendingShaders?(): number;@@ -511,6 +512,7 @@ export function createNativeEngineApi(bind('renderer_getCulled', 'es_renderer_getCulled', false);bind('renderer_getDrawCalls', 'es_renderer_getDrawCalls', false);bind('renderer_getEstimatedGpuBytes', 'es_renderer_getEstimatedGpuBytes', false);+ bind('renderer_getGpuDrawCalls', 'es_renderer_getGpuDrawCalls', false);bind('renderer_getGpuTimeMs', 'es_renderer_getGpuTimeMs', false);bind('renderer_getMeshes', 'es_renderer_getMeshes', false);bind('renderer_getPendingShaders', 'es_renderer_getPendingShaders', false);diff --git a/sdk/src/ecs/bridge/nativeRenderer.ts b/sdk/src/ecs/bridge/nativeRenderer.tsindex fbe6a0d5f..cdb352504 100644--- a/sdk/src/ecs/bridge/nativeRenderer.ts+++ b/sdk/src/ecs/bridge/nativeRenderer.ts@@ -209,6 +209,7 @@ export function createNativeRendererBackend(};return {drawCalls: read(RENDERER_STATS_BINDINGS.drawCalls),+ gpuDraws: read(RENDERER_STATS_BINDINGS.gpuDraws),triangles: read(RENDERER_STATS_BINDINGS.triangles),sprites: read(RENDERER_STATS_BINDINGS.sprites),text: read(RENDERER_STATS_BINDINGS.text),diff --git a/sdk/src/render/drawBudget.ts b/sdk/src/render/drawBudget.tsnew file mode 100644index 000000000..836b0a682--- /dev/null+++ b/sdk/src/render/drawBudget.ts@@ -0,0 +1,73 @@+// SPDX-License-Identifier: Apache-2.0+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team+/**+ * @file drawBudget.ts+ * @brief Where a frame's draws went, pass by pass, held against the level's draw call budget.+ *+ * @details The device counts every draw it issues (`render.gpu.draws`); the scene's and the overlay's+ * lists count theirs after batching (`batch.draws`), and the passes that draw the scene again+ * count their own (shadow maps, the depth prepass, planar reflections, motion vectors, the+ * cover pass). What none of them claims — post-processing, a blit, the editor's grid — is+ * `other`, so the shares always add up to the device's total and a pass nobody counts is still+ * seen. The per-pass counters are published only while the frame profiler is on; without them+ * everything but the lists is `other`.+ */++/** A part of the frame, by what drew it. @experimental */+export type DrawPass = 'lists' | 'shadow' | 'prepass' | 'reflection' | 'motion' | 'cover' | 'other';++/** @experimental */+export interface DrawPassShare {+ pass: DrawPass;+ draws: number;+}++/** @experimental */+export interface DrawBudgetReport {+ /** Every draw the GPU was asked for. */+ draws: number;+ /** The budget it is held to; 0 is none. */+ budget: number;+ /** By how many it went past the budget; 0 within it. */+ over: number;+ /** The draws by pass, largest first, the empty ones left out. */+ passes: DrawPassShare[];+}++const COUNTERS: readonly [Exclude<DrawPass, 'other'>, string][] = [+ ['lists', 'batch.draws'],+ ['shadow', 'render.shadow.draws'],+ ['prepass', 'render.prepass.draws'],+ ['reflection', 'render.planar.draws'],+ ['motion', 'render.motion.draws'],+ ['cover', 'render.cover.draws'],+];++/**+ * A frame's draws by pass. @p gpuDraws is the device's own count; @p counters the frame's engine+ * counters by name (a frame stats report's `cppCounters`), and @p listDraws the lists' count to use+ * when the counters do not carry it (they are absent while the profiler is off).+ *+ * @experimental+ */+export function drawBudgetReport(+ gpuDraws: number, budget: number, counters: Readonly<Record<string, number>>, listDraws = 0,+): DrawBudgetReport {+ const passes: DrawPassShare[] = [];+ let claimed = 0;+ for (const [pass, name] of COUNTERS) {+ const value = counters[name] ?? (pass === 'lists' ? listDraws : 0);+ const draws = Math.max(0, Math.round(value));+ if (draws === 0) continue;+ passes.push({ pass, draws });+ claimed += draws;+ }+ // The device's count is the truth; a share a pass claims past it (a counter from a frame other than the+ // one counted) is not taken from `other`, which never goes below nothing.+ const total = Math.max(0, Math.round(gpuDraws));+ const other = total - claimed;+ if (other > 0) passes.push({ pass: 'other', draws: other });+ passes.sort((a, b) => b.draws - a.draws);+ const limit = Math.max(0, Math.round(budget));+ return { draws: total, budget: limit, over: limit > 0 ? Math.max(0, total - limit) : 0, passes };+}diff --git a/sdk/src/render/quality.ts b/sdk/src/render/quality.tsindex cbf1f7b43..5f0c78c2a 100644--- a/sdk/src/render/quality.ts+++ b/sdk/src/render/quality.ts@@ -78,6 +78,12 @@ export interface QualityProfile {* is that many silhouettes added up. Fewer is cheaper and shows the edge as bands; sixteen is where the bands stop reading as separate shadows.*/shadowSoftSamples: number;+ /**+ * The most draws a frame at this level should ask of the GPU, every pass counted (shadows, prepass, reflections and post-processing with the+ * scene). Nothing is held back to meet it: the profiler and the stats overlay show a frame over it, and the frame debugger says where the draws+ * went. Draw calls cost the CPU and the driver more than the GPU, and on a phone or in a mini game they are what a 3D scene runs out of first.+ */+ drawCallBudget: number;}export interface DeviceQualityRule {@@ -131,7 +137,7 @@ const PROFILES: Record<QualityLevel, QualityProfile> = {shadowDistance: 0, detailScale: 0.5, particleLimit: 1000, postProcess: true, ssao: false,waterWaves: 2, waterRippleCells: 32, waterDisplacement: false, waterMirror: false, waterCaustics: false,skipEffects: ['ssr', 'taa', 'depthOfField', 'lightShafts', 'motionBlur', 'lensFlare', 'gtao', 'subsurface', 'voxelGI'],- shelterMaskSize: 256, shadowSoftSamples: 8,+ shelterMaskSize: 256, shadowSoftSamples: 8, drawCallBudget: 150,},medium: {renderScale: 1, minRenderScale: 0.65, msaaSamples: 2, antialiasing: 'temporal',@@ -140,7 +146,7 @@ const PROFILES: Record<QualityLevel, QualityProfile> = {shadowDistance: 0, detailScale: 0.8, particleLimit: 5000, postProcess: true, ssao: true,waterWaves: 3, waterRippleCells: 64, waterDisplacement: true, waterMirror: true, waterCaustics: true,skipEffects: ['ssr', 'depthOfField'],- shelterMaskSize: 512, shadowSoftSamples: 12,+ shelterMaskSize: 512, shadowSoftSamples: 12, drawCallBudget: 400,},high: {renderScale: 1, minRenderScale: 0.75, msaaSamples: 4, antialiasing: 'msaa',@@ -151,7 +157,7 @@ const PROFILES: Record<QualityLevel, QualityProfile> = {shadowDistance: 0, detailScale: 1, particleLimit: 20000, postProcess: true, ssao: true,waterWaves: 4, waterRippleCells: 128, waterDisplacement: true, waterMirror: true, waterCaustics: true,skipEffects: [],- shelterMaskSize: 1024, shadowSoftSamples: 16,+ shelterMaskSize: 1024, shadowSoftSamples: 16, drawCallBudget: 1500,},};@@ -256,6 +262,7 @@ function resolveProfile(level: QualityLevel, value: unknown): QualityProfile {: base.skipEffects,shelterMaskSize: Math.round(finite(r.shelterMaskSize, base.shelterMaskSize, 64, 2048)),shadowSoftSamples: Math.round(finite(r.shadowSoftSamples, base.shadowSoftSamples, 1, 32)),+ drawCallBudget: Math.round(finite(r.drawCallBudget, base.drawCallBudget, 1, 100000)),};}@@ -288,6 +295,8 @@ export interface QualityReport {frameMs: number;reason: string;limitations: string[];+ /** The level's draw call budget (see `QualityProfile.drawCallBudget`). */+ drawCallBudget: number;}/** @experimental Per-app policy; authored scene components remain unchanged. */@@ -388,6 +397,7 @@ export class QualityController {mode: this.config_.mode ?? 'off', level: this.level_,renderScale: this.renderScale, targetFps: this.config_.targetFps ?? 60,frameMs: this.average_, reason: this.reason_, limitations: [...this.limitations_],+ drawCallBudget: this.profile_.drawCallBudget,};}}diff --git a/sdk/src/render/renderer.ts b/sdk/src/render/renderer.tsindex e87ce6b45..5628981d5 100644--- a/sdk/src/render/renderer.ts+++ b/sdk/src/render/renderer.ts@@ -21,7 +21,13 @@ export enum RenderStage {export type RenderTargetHandle = number;export interface RenderStats {+ /** The draws of the scene's and the overlay's lists, after batching: what the draw calls a frame debugger lists add up to. */drawCalls: number;+ /**+ * Every draw the GPU was asked for, every pass included: shadow maps, the depth prepass, reflections, motion vectors and post-processing as well as+ * the scene. This is the number a draw call budget is held to.+ */+ gpuDraws: number;triangles: number;sprites: number;text: number;@@ -158,7 +164,7 @@ export interface LodDecision {screenSize: number;}-const NO_STATS: RenderStats = { drawCalls: 0, triangles: 0, sprites: 0, text: 0, skeletal: 0, meshes: 0, culled: 0 };+const NO_STATS: RenderStats = { drawCalls: 0, gpuDraws: 0, triangles: 0, sprites: 0, text: 0, skeletal: 0, meshes: 0, culled: 0 };const bridge = new CoreApiBridge('renderer');let module: ESEngineModule | null = null;@@ -292,6 +298,7 @@ function wasmBackend(m: ESEngineModule): RendererBackend {},getStats: () => ({drawCalls: m.renderer_getDrawCalls(),+ gpuDraws: m.renderer_getGpuDrawCalls?.() ?? 0,triangles: m.renderer_getTriangles(),sprites: m.renderer_getSprites(),text: m.renderer_getText(),diff --git a/sdk/src/runtime/frameStats.ts b/sdk/src/runtime/frameStats.tsindex 73626594a..6acf56895 100644--- a/sdk/src/runtime/frameStats.ts+++ b/sdk/src/runtime/frameStats.ts@@ -20,6 +20,8 @@ export interface FrameStatsReport {* profile tree is folded from. Null while the app has stats off. */costs: FrameCosts | null;drawCalls: number;+ /** Every draw the GPU was asked for, every pass included; what `quality.drawCallBudget` is held to. */+ gpuDraws?: number;triangles: number;sprites: number;entities: number;@@ -56,6 +58,7 @@ export function frameStatsReport(app: App): FrameStatsReport {phases: Object.fromEntries(app.getPhaseTimings() ?? []),costs: app.getFrameCosts(),drawCalls: m?.renderer_getDrawCalls?.() ?? 0,+ gpuDraws: m?.renderer_getGpuDrawCalls?.() ?? 0,triangles: m?.renderer_getTriangles?.() ?? 0,sprites: m?.renderer_getSprites?.() ?? 0,entities: app.world.getAllEntities().length,diff --git a/sdk/src/stats-overlay.ts b/sdk/src/stats-overlay.tsindex c0e9111c1..1774cd418 100644--- a/sdk/src/stats-overlay.ts+++ b/sdk/src/stats-overlay.ts@@ -118,6 +118,8 @@ export class StatsOverlay {sections.push('<div style="color:#8c8c8c;border-bottom:1px solid rgba(60,60,60,0.8);padding-bottom:3px;margin-bottom:3px;margin-top:4px">Rendering</div>' +`<div>DC: <span style="color:#d19a66">${stats.drawCalls}</span>` ++ ` GPU: <span style="color:${stats.drawCallBudget > 0 && stats.gpuDraws > stats.drawCallBudget ? '#e06c75' : '#d19a66'}">${stats.gpuDraws}${stats.drawCallBudget > 0 ? ` / ${stats.drawCallBudget}` : ''}</span></div>` ++ `<div>` +` Tri: <span style="color:#d19a66">${stats.triangles}</span></div>` +`<div>Sprites: <span style="color:#d19a66">${stats.sprites}</span>` +` Culled: <span style="color:#d19a66">${stats.culled}</span></div>`diff --git a/sdk/src/stats.ts b/sdk/src/stats.tsindex 6d4066074..6d390c587 100644--- a/sdk/src/stats.ts+++ b/sdk/src/stats.ts@@ -5,6 +5,7 @@ import { defineResource, Res, Time } from './ecs/resource';import { defineSystem, GetWorld, Schedule } from './ecs/system';import type { App, Plugin } from './app/app';import { StatsOverlay, type StatsPosition } from './stats-overlay';+import { Quality } from './render/qualityRuntime';export interface FrameStats {fps: number;@@ -13,6 +14,10 @@ export interface FrameStats {systemTimings: Map<string, number>;phaseTimings: Map<string, number>;drawCalls: number;+ /** Every draw the GPU was asked for, every pass included (see `RenderStats.gpuDraws`). */+ gpuDraws: number;+ /** The draw call budget of the quality level in force; 0 when the app has no quality controller. */+ drawCallBudget: number;triangles: number;sprites: number;text: number;@@ -29,6 +34,8 @@ export function defaultFrameStats(): FrameStats {systemTimings: new Map(),phaseTimings: new Map(),drawCalls: 0,+ gpuDraws: 0,+ drawCallBudget: 0,triangles: 0,sprites: 0,text: 0,@@ -203,6 +210,8 @@ export class StatsPlugin implements Plugin {const renderStats = Renderer.getStats();stats.drawCalls = renderStats.drawCalls;+ stats.gpuDraws = renderStats.gpuDraws;+ stats.drawCallBudget = app.hasResource(Quality) ? app.getResource(Quality)?.profile.drawCallBudget ?? 0 : 0;stats.triangles = renderStats.triangles;stats.sprites = renderStats.sprites;stats.text = renderStats.text;diff --git a/sdk/src/wasm.ts b/sdk/src/wasm.tsindex 960d1c893..565b96182 100644--- a/sdk/src/wasm.ts+++ b/sdk/src/wasm.ts@@ -684,6 +684,8 @@ export interface ESEngineModule {*/es_getMallocBytes?(): number;renderer_getDrawCalls(): number;+ /** Every draw the GPU was asked for in the last frame, every pass included. Optional: older engine builds do not carry it. */+ renderer_getGpuDrawCalls?(): number;/*** GPU objects the device has created and not destroyed, for the resource* census. Null when no device is initialized — a census must record thosediff --git a/sdk/tests/draw-budget.test.ts b/sdk/tests/draw-budget.test.tsnew file mode 100644index 000000000..6d82ccbf4--- /dev/null+++ b/sdk/tests/draw-budget.test.ts@@ -0,0 +1,41 @@+// SPDX-License-Identifier: Apache-2.0+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team+import { describe, expect, it } from 'vitest';+import { drawBudgetReport } from '../src/render/drawBudget';+import { defaultQualityProfile, parseQualityConfig, resolveQualityProfile } from '../src/render/quality';++describe('a frame\'s draws by pass', () => {+ it('gives each counted pass its share and leaves the rest to other, so the shares add up to the device', () => {+ const r = drawBudgetReport(120, 150, { 'batch.draws': 40, 'render.shadow.draws': 50, 'render.prepass.draws': 20 });+ expect(r.passes).toEqual([+ { pass: 'shadow', draws: 50 }, { pass: 'lists', draws: 40 }, { pass: 'prepass', draws: 20 }, { pass: 'other', draws: 10 },+ ]);+ expect(r.passes.reduce((n, p) => n + p.draws, 0)).toBe(120);+ expect(r.over).toBe(0);+ });++ it('says by how much a frame went past its budget, and nothing when there is no budget', () => {+ expect(drawBudgetReport(180, 150, {}).over).toBe(30);+ expect(drawBudgetReport(180, 0, {}).over).toBe(0);+ });++ it('takes the lists\' own count while the profiler publishes no counters', () => {+ const r = drawBudgetReport(30, 150, {}, 12);+ expect(r.passes).toEqual([{ pass: 'other', draws: 18 }, { pass: 'lists', draws: 12 }]);+ });++ it('never has a negative other when a pass claims more than the device counted', () => {+ const r = drawBudgetReport(10, 150, { 'batch.draws': 12 });+ expect(r.passes).toEqual([{ pass: 'lists', draws: 12 }]);+ });+});++describe('the draw call budget of a quality level', () => {+ it('is smaller on the weaker levels, and a project can set its own', () => {+ expect(defaultQualityProfile('low').drawCallBudget).toBeLessThan(defaultQualityProfile('medium').drawCallBudget);+ expect(defaultQualityProfile('medium').drawCallBudget).toBeLessThan(defaultQualityProfile('high').drawCallBudget);+ expect(resolveQualityProfile('low', { drawCallBudget: 90 }).drawCallBudget).toBe(90);+ const config = parseQualityConfig({ mode: 'low', profiles: { low: { drawCallBudget: 'many' } } });+ expect(config.profiles?.low?.drawCallBudget).toBe(defaultQualityProfile('low').drawCallBudget);+ });+});diff --git a/sdk/tests/renderer.test.ts b/sdk/tests/renderer.test.tsindex 0281505af..fccfaa115 100644--- a/sdk/tests/renderer.test.ts+++ b/sdk/tests/renderer.test.ts@@ -47,6 +47,7 @@ function createRendererMockModule() {renderer_setStage: vi.fn(),renderer_getDrawCalls: vi.fn(() => 10),+ renderer_getGpuDrawCalls: vi.fn(() => 31),renderer_getTriangles: vi.fn(() => 500),renderer_getSprites: vi.fn(() => 25),renderer_getText: vi.fn(() => 5),@@ -131,6 +132,7 @@ describe('Renderer API', () => {const stats = Renderer.getStats();expect(stats).toEqual({drawCalls: 0,+ gpuDraws: 0,triangles: 0,sprites: 0,text: 0,@@ -376,6 +378,7 @@ describe('Renderer API', () => {const stats = Renderer.getStats();expect(stats).toEqual({drawCalls: 10,+ gpuDraws: 31,triangles: 500,sprites: 25,text: 5,diff --git a/src/esengine/bindings/RendererBindings.cpp b/src/esengine/bindings/RendererBindings.cppindex c83b25bf3..d8d5235c8 100644--- a/src/esengine/bindings/RendererBindings.cpp+++ b/src/esengine/bindings/RendererBindings.cpp@@ -1015,6 +1015,11 @@ u32 renderer_getDrawCalls() {return g_renderFrame->stats().draw_calls;}+u32 renderer_getGpuDrawCalls() {+ if (!g_renderFrame) return 0;+ return g_renderFrame->stats().gpu_draws;+}+#ifdef __EMSCRIPTEN__/*** The local-space XY box of what a MeshRenderer DRAWS — resident geometry when it hasdiff --git a/src/esengine/bindings/RendererBindings.hpp b/src/esengine/bindings/RendererBindings.hppindex 4968e4f5f..a2537a74e 100644--- a/src/esengine/bindings/RendererBindings.hpp+++ b/src/esengine/bindings/RendererBindings.hpp@@ -226,6 +226,8 @@ u32 renderer_getTargetDepthTexture(u32 handle);void renderer_releaseTarget(u32 handle);u32 renderer_getTargetTexture(u32 handle);u32 renderer_getDrawCalls();+/// Every draw the GPU was asked for in the last frame, every pass included (shadows, prepass, reflections, post-processing).+u32 renderer_getGpuDrawCalls();#ifdef __EMSCRIPTEN__/// GPU objects the device has not destroyed, for the resource census. Null when/// no device is initialized — absent counters, not zeroed ones.diff --git a/src/esengine/bindings/WebSDKEntry.cpp b/src/esengine/bindings/WebSDKEntry.cppindex ddc2bdbfe..30d691f31 100644--- a/src/esengine/bindings/WebSDKEntry.cpp+++ b/src/esengine/bindings/WebSDKEntry.cpp@@ -767,6 +767,7 @@ EMSCRIPTEN_BINDINGS(esengine_renderer) {emscripten::function("renderer_getTargetTexture", &esengine::renderer_getTargetTexture);emscripten::function("renderer_getTargetDepthTexture", &esengine::renderer_getTargetDepthTexture);emscripten::function("renderer_getDrawCalls", &esengine::renderer_getDrawCalls);+ emscripten::function("renderer_getGpuDrawCalls", &esengine::renderer_getGpuDrawCalls);emscripten::function("renderer_getLiveObjects", &esengine::renderer_getLiveObjects);emscripten::function("renderer_getTriangles", &esengine::renderer_getTriangles);emscripten::function("renderer_getSprites", &esengine::renderer_getSprites);diff --git a/src/esengine/renderer/frame/RenderFrame.cpp b/src/esengine/renderer/frame/RenderFrame.cppindex 5ecc379a4..c1f21c0ee 100644--- a/src/esengine/renderer/frame/RenderFrame.cpp+++ b/src/esengine/renderer/frame/RenderFrame.cpp@@ -618,6 +618,7 @@ void RenderFrame::flush() {void RenderFrame::endFrame() {frame_capture_.endFrame();device_.endFrame();+ stats_.gpu_draws = device_.takeDraws();publishFrameCounters();// Once per frame and not per camera: a commit at each camera's end kept only// the last camera's scopes and counters.@@ -636,6 +637,7 @@ void RenderFrame::tallyPass(const DrawList& list) {void RenderFrame::publishFrameCounters() {if (!FrameProfiler::get().enabled()) return;ES_PROFILE_COUNTER("batch.draws", stats_.draw_calls);+ ES_PROFILE_COUNTER("render.gpu.draws", stats_.gpu_draws);ES_PROFILE_COUNTER("batch.merged", frame_merged_);// 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.diff --git a/src/esengine/renderer/frame/RenderFrame.hpp b/src/esengine/renderer/frame/RenderFrame.hppindex 6024aebd3..368b4e8ba 100644--- a/src/esengine/renderer/frame/RenderFrame.hpp+++ b/src/esengine/renderer/frame/RenderFrame.hpp@@ -87,6 +87,8 @@ class RenderFrame {public:struct Stats {u32 draw_calls = 0;+ /// Every draw the GPU was asked for in the frame, every pass included; `draw_calls` is the scene's and the overlay's lists only.+ u32 gpu_draws = 0;u32 triangles = 0;u32 sprites = 0;u32 skeletal = 0;diff --git a/src/esengine/renderer/rhi/GLDevice.cpp b/src/esengine/renderer/rhi/GLDevice.cppindex 9c88b5714..ae530bee3 100644--- a/src/esengine/renderer/rhi/GLDevice.cpp+++ b/src/esengine/renderer/rhi/GLDevice.cpp@@ -1273,6 +1273,7 @@ u32 GLDevice::primitiveMode() const {void GLDevice::drawElements(u32 indexCount, GfxDataType indexType, u32 byteOffset) {if (!isDeviceUsable()) return;prepareVertexState();+ countDraw();glDrawElements(primitiveMode(), static_cast<GLsizei>(indexCount), toGLDataType(indexType),reinterpret_cast<const void*>(static_cast<uintptr_t>(byteOffset)));}@@ -1280,12 +1281,14 @@ void GLDevice::drawElements(u32 indexCount, GfxDataType indexType, u32 byteOffsevoid GLDevice::drawArrays(u32 first, u32 vertexCount) {if (!isDeviceUsable()) return;prepareVertexState();+ countDraw();glDrawArrays(primitiveMode(), static_cast<GLint>(first), static_cast<GLsizei>(vertexCount));}void GLDevice::drawElementsInstanced(u32 indexCount, GfxDataType indexType, u32 byteOffset, u32 instanceCount) {if (!isDeviceUsable()) return;prepareVertexState();+ countDraw();glDrawElementsInstanced(primitiveMode(), static_cast<GLsizei>(indexCount), toGLDataType(indexType),reinterpret_cast<const void*>(static_cast<uintptr_t>(byteOffset)),static_cast<GLsizei>(instanceCount));diff --git a/src/esengine/renderer/rhi/GfxDevice.hpp b/src/esengine/renderer/rhi/GfxDevice.hppindex 5b595de91..9398ccf22 100644--- a/src/esengine/renderer/rhi/GfxDevice.hpp+++ b/src/esengine/renderer/rhi/GfxDevice.hpp@@ -186,6 +186,14 @@ public:*/usize retainedBytes() const { return retained_bytes_; }+ /**+ * @brief Every draw the GPU was asked for since the last call, and the tally started again.+ * @details Counted where the backends issue them, so it holds every pass a frame has: the scene and+ * the overlay, and the shadow maps, depth prepass, reflections, motion vectors and+ * post-processing that the draw lists' own count leaves out. An instanced draw is one.+ */+ u32 takeDraws() { const u32 n = draws_; draws_ = 0; return n; }+/*** @brief Warns once when retainedBytes() grows past `bytes`; 0 never warns.* @details Falling back under it re-arms the warning.@@ -845,6 +853,9 @@ public:virtual u32 nativeTextureName(TextureHandle texture) const { (void)texture; return 0; }protected:+ /** @brief A backend has issued one draw (see takeDraws). */+ void countDraw() { ++draws_; }+// =========================================================================// Backend primitives. `id` is the handle's value; the backend maps it to its// own object for the current generation and nothing else.@@ -991,6 +1002,7 @@ private:GfxResourceRegistry registry_;u32 owed_count_ = 0;usize retained_bytes_ = 0;+ u32 draws_ = 0;usize retained_budget_ = 0;bool over_retained_budget_ = false;ShaderHandle current_program_ = ShaderHandle::Invalid;diff --git a/src/esengine/renderer/webgpu/WebGPUDevice.cpp b/src/esengine/renderer/webgpu/WebGPUDevice.cppindex f9610a582..88336f94d 100644--- a/src/esengine/renderer/webgpu/WebGPUDevice.cpp+++ b/src/esengine/renderer/webgpu/WebGPUDevice.cpp@@ -2160,12 +2160,14 @@ void WebGPUDevice::drawElements(u32 indexCount, GfxDataType indexType, u32 indexwgpuRenderPassEncoderSetIndexBuffer(pass_, it->second.buffer, toWGPUIndexFormat(indexType),0, it->second.size);const u32 indexSize = (indexType == GfxDataType::UnsignedShort) ? 2 : 4;+ countDraw();wgpuRenderPassEncoderDrawIndexed(pass_, indexCount, 1, indexByteOffset / indexSize, 0, 0);}void WebGPUDevice::drawArrays(u32 firstVertex, u32 vertexCount) {if (!isDeviceUsable() || !pass_) return;flushBindGroup();+ countDraw();wgpuRenderPassEncoderDraw(pass_, vertexCount, 1, firstVertex, 0);}@@ -2178,6 +2180,7 @@ void WebGPUDevice::drawElementsInstanced(u32 indexCount, GfxDataType indexType,wgpuRenderPassEncoderSetIndexBuffer(pass_, it->second.buffer, toWGPUIndexFormat(indexType),0, it->second.size);const u32 indexSize = (indexType == GfxDataType::UnsignedShort) ? 2 : 4;+ countDraw();wgpuRenderPassEncoderDrawIndexed(pass_, indexCount, instanceCount,indexByteOffset / indexSize, 0, 0);}diff --git a/tools/check-project-settings.mjs b/tools/check-project-settings.mjsindex 42b708b06..9a057a311 100644--- a/tools/check-project-settings.mjs+++ b/tools/check-project-settings.mjs@@ -299,6 +299,7 @@ const BLOCKS = [waterCaustics: { ui: 'project.rendering.quality.waterCaustics' },shelterMaskSize: { ui: 'project.rendering.quality.shelterMaskSize' },shadowSoftSamples: { ui: 'project.rendering.quality.shadowSoftSamples' },+ drawCallBudget: { ui: 'project.rendering.quality.drawCallBudget' },skipEffects: { ui: 'project.rendering.quality.effects' },},},