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(render): static batching reports what became of each mesh and why

yhh0dd391438896
diff --git a/CHANGELOG.md b/CHANGELOG.md
index abe60fafa..4559bf527 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -16,7 +16,7 @@ published separately; it ships inside the editor.
### Added
-- **Static batching.** Static meshes that share a material can be drawn as one. Add `StaticBatch` to a mesh that will not move, and the meshes that share its material, texture, colour and layer are merged while the game runs into one mesh per area, so a level built from many different props costs a few draws instead of one per distinct mesh. The renderer already drew copies of the same mesh as one instanced draw; this is for different meshes. The marked entities stay as authored — scripts find them, colliders collide, the editor picks them — and only their drawing moves to the merged mesh. A mesh is left out, and the reason recorded, when it is skinned, morphing, a level-of-detail group, blended, moving (a dynamic body or a character), lit by a bake or a probe volume, or alone in its group. Merging copies each part's vertices, so it spends memory to save draws; `StaticBatching` reports each merged mesh's size and what drawing its parts cost before.
+- **Static batching.** Static meshes that share a material can be drawn as one. Add `StaticBatch` to a mesh that will not move, and the meshes that share its material, texture, colour and layer are merged while the game runs into one mesh per area, so a level built from many different props costs a few draws instead of one per distinct mesh. The renderer already drew copies of the same mesh as one instanced draw; this is for different meshes. The marked entities stay as authored — scripts find them, colliders collide, the editor picks them — and only their drawing moves to the merged mesh. A mesh is left out, and the reason recorded, when it is skinned, morphing, a level-of-detail group, blended, moving (a dynamic body or a character), lit by a bake or a probe volume, or alone in its group. Merging copies each part's vertices, so it spends memory to save draws; `StaticBatching` reports each merged mesh's size and what drawing its parts cost before. In the editor the outliner's menu marks the selected meshes, a marked mesh's Details say whether it merged and why not, and the profiler lists every merged mesh and the meshes left out.
- **Camera shots and nested sequences on the timeline.** Timelines have camera and sequence tracks. A camera track is a row of shots: each bar is the camera that is the view for its span, bars that touch cut, and a bar dragged over the previous one blends across the overlap with its own curve. A sequence track plays another timeline in a window of this one, on its own clock, with a speed, a loop, and a node to bind to so one sequence can play on different characters. A timeline cannot play itself, directly or through another, and nesting stops at four levels. The Sequencer shows both as bars above the object tracks, with the shot or clip in Details, and the viewport's camera preview follows the shot while you scrub. Which shot and which nested frame show is a function of time alone, so scrubbing, jumping and playing backwards agree.
### Changed
diff --git a/desktop b/desktop
index d207feb7d..a9b3bd34c 160000
--- a/desktop
+++ b/desktop
@@ -1 +1 @@
-Subproject commit d207feb7d9f3f375e9dda1c75603e0a0f53ba5ce
+Subproject commit a9b3bd34c40987d33c052c22d8d03a20b39f8fe2
diff --git a/docs/astro/astro.config.mjs b/docs/astro/astro.config.mjs
index 0695addd9..7835ca2fb 100644
--- a/docs/astro/astro.config.mjs
+++ b/docs/astro/astro.config.mjs
@@ -324,6 +324,7 @@ export default defineConfig({
{ label: 'Profiling & Diagnostics', translations: { 'zh-CN': '性能剖析与诊断' }, slug: 'performance/profiling' },
{ label: 'Level of Detail', translations: { 'zh-CN': '细节层次(LOD)' }, slug: 'performance/level-of-detail' },
{ label: 'Occlusion Culling', translations: { 'zh-CN': '遮挡剔除' }, slug: 'performance/occlusion-culling' },
+ { label: 'Static Batching', translations: { 'zh-CN': '静态合并' }, slug: 'performance/static-batching' },
],
},
{
diff --git a/docs/astro/src/content/docs/performance/static-batching.mdx b/docs/astro/src/content/docs/performance/static-batching.mdx
new file mode 100644
index 000000000..7000be355
--- /dev/null
+++ b/docs/astro/src/content/docs/performance/static-batching.mdx
@@ -0,0 +1,55 @@
+---
+title: Static Batching
+description: Draw many static meshes that share a material as one — what to mark, what is left out and why, and what it costs in memory.
+---
+
+The renderer already draws **copies of the same mesh** as one instanced draw. What it
+cannot do is draw **different meshes** as one: every mesh is its own range of GPU memory,
+so a level built from fifty distinct props costs fifty draws per material.
+
+**`StaticBatch`** is for that. Add it to a mesh that will not move, and while the game runs
+the meshes that share its material, texture, colour and layer are merged into one mesh per
+area.
+
+```typescript
+world.insert(wall, MeshRenderer, { mesh: 'builtin:cube', material });
+world.insert(wall, StaticBatch, {});
+```
+
+In the editor, select the meshes and choose **Static Batch** from the outliner's menu.
+
+## What happens
+
+- Meshes are grouped by everything a draw owns — material, texture, normal map, colour,
+ layer, culling and lighting flags — and by the optional **group** on the component, so two
+ rooms can be kept apart.
+- Each group is cut into cells of the world, so a batch is a neighbourhood and culling still
+ has something to cull. A cell never holds more than 262,144 vertices.
+- The marked entities stay as authored: scripts find them, colliders collide and the editor
+ picks them. Only their drawing moves to the merged mesh, which is an entity of its own.
+- A marked mesh **does not move** after it has been merged. Destroying one is supported (its
+ batch is rebuilt without it); moving one is not, and nothing can notice.
+
+## What is left out
+
+A mesh that cannot be merged stays as it was, and says why — on the component while the game
+runs, and in the profiler's **Static batch** section.
+
+| Reason | Why |
+|---|---|
+| Skinned | One draw can only be in one pose. |
+| Morphing | One draw can only be in one shape. |
+| Level of detail | The renderer chooses among levels at run time. |
+| Blended | Its result depends on drawing order, and merging is the loss of order. |
+| Moves | A dynamic body or a character controller: a batch bakes where a mesh stands. |
+| Baked light | The scene has probes or a bake, and a merged mesh cannot keep each part's own. |
+| Alone in its group | Merging one mesh saves nothing and costs memory. |
+
+## What it costs
+
+Merging copies every part's vertices into the merged mesh, so it **spends memory to save
+draws**. A part that stood for a hundred instances becomes a hundred copies. The profiler shows,
+for each merged mesh, how many parts it holds, how many draws they cost before, and how much
+memory the copy takes — read the two numbers together.
+
+Use instancing for many copies of one mesh, and static batching for many different meshes.
diff --git a/docs/astro/src/content/docs/zh-cn/performance/static-batching.mdx b/docs/astro/src/content/docs/zh-cn/performance/static-batching.mdx
new file mode 100644
index 000000000..abf8c7a46
--- /dev/null
+++ b/docs/astro/src/content/docs/zh-cn/performance/static-batching.mdx
@@ -0,0 +1,52 @@
+---
+title: 静态合并
+description: 把许多共用材质的静态网格合成一次绘制 —— 该标记什么、哪些会被留下以及原因、以及它要花多少内存。
+---
+
+渲染器本来就会把**同一个网格的多份拷贝**合成一次实例化绘制。它做不到的是把**不同的网格**
+合成一次:每个网格在 GPU 里都是自己的一段内存,所以用五十种不同道具搭出来的关卡,每种材质
+要花五十次绘制。
+
+**`StaticBatch`** 就是为这个准备的。给一个不会动的网格加上它,游戏运行时,材质、贴图、
+颜色和层都相同的网格会按区域合并成一个网格。
+
+```typescript
+world.insert(wall, MeshRenderer, { mesh: 'builtin:cube', material });
+world.insert(wall, StaticBatch, {});
+```
+
+在编辑器里,选中网格后在大纲的菜单里选**静态合并**。
+
+## 会发生什么
+
+- 网格按一次绘制拥有的全部状态分组 —— 材质、贴图、法线贴图、颜色、层、剔除与光照开关 ——
+ 还可以用组件上的**分组**把两个房间分开。
+- 每一组再按世界里的格子切开,所以一个批是一小片区域,剔除仍然有东西可剔。
+ 一个格子里的顶点不超过 262,144 个。
+- 被标记的实体保持原样:脚本照样能找到,碰撞体照样碰撞,编辑器照样能选中。只是它们的绘制
+ 移到了合并后的网格上,那是另一个实体。
+- 被合并之后,标记的网格**不能再动**。销毁是支持的(这个批会去掉它重新合并);移动不支持,
+ 而且没有任何办法发现。
+
+## 哪些会被留下
+
+合并不了的网格保持原样,并说明原因 —— 游戏运行时写在组件上,也写在性能分析器的**静态合并**
+一节里。
+
+| 原因 | 为什么 |
+|---|---|
+| 带骨骼 | 一次绘制只能处于一个姿态。 |
+| 带形变 | 一次绘制只能处于一个形状。 |
+| 细节层级 | 渲染器在运行时选择用哪一级。 |
+| 半透明 | 结果取决于绘制顺序,而合并就是丢掉顺序。 |
+| 会动 | 动态刚体或角色控制器:合并把网格站的位置烘进了顶点。 |
+| 烘焙光照 | 场景有探针或烘焙,合并后的网格留不住每个部件各自的那一份。 |
+| 同组只有一个 | 只合并一个网格什么也省不了,还多占内存。 |
+
+## 它的代价
+
+合并会把每个部件的顶点复制进合并后的网格,所以它是**拿内存换绘制**。一个原本代表一百个实例的
+部件,会变成一百份拷贝。性能分析器会为每个合并网格显示:它含多少部件、这些部件原本花多少
+次绘制、这份拷贝占多少内存 —— 请把两个数字放在一起看。
+
+同一个网格的许多拷贝用实例化,许多不同的网格用静态合并。
diff --git a/docs/astro/src/data/apiStability.generated.json b/docs/astro/src/data/apiStability.generated.json
index 2fc18eefb..9922b74d6 100644
--- a/docs/astro/src/data/apiStability.generated.json
+++ b/docs/astro/src/data/apiStability.generated.json
@@ -3,10 +3,10 @@
"counts": {
"public": 115,
"beta": 164,
- "experimental": 2248,
+ "experimental": 2279,
"deprecated": 3
},
- "total": 2527,
+ "total": 2558,
"subsystems": [
{
"id": "mobile-controls",
diff --git a/docs/astro/src/data/componentDocs.ts b/docs/astro/src/data/componentDocs.ts
index 30596d03c..c059779ed 100644
--- a/docs/astro/src/data/componentDocs.ts
+++ b/docs/astro/src/data/componentDocs.ts
@@ -84,6 +84,7 @@ export const COMPONENT_DOCS: Record<string, ComponentDoc> = {
WorldStreamingSource: { category: 'world', summary: 'Asks for the places near it to exist; several sources are unioned.', doc: 'world/streaming', anchor: 'asking-for-places-streaming-sources', anchorZh: '请求地方存在流送源' },
SpriteMask: { category: 'graphics', summary: "Turns this entity's Sprite into a stencil that cuts the sprites drawn after it — a window, or a hole.", doc: 'graphics/sprites', anchor: 'sprite-masks', anchorZh: '精灵遮罩' },
SortingGroup: { category: 'graphics', summary: 'Makes an entity and its whole subtree sort as one unit — the group states the layer and order, members state their place inside it.', doc: 'graphics/sprites', anchor: 'sorting-groups', anchorZh: '排序组' },
+ StaticBatch: { category: 'graphics', summary: 'Marks a mesh that will not move, so the meshes sharing its material are merged into one draw while the game runs; it also records what became of this one.', doc: 'performance/static-batching', anchor: 'what-happens', anchorZh: '会发生什么' },
LODGroup: { category: 'graphics', summary: 'Cheaper stand-in meshes for a MeshRenderer, chosen by how much of the screen the object covers.', doc: 'performance/level-of-detail', anchor: 'the-lodgroup-component', anchorZh: 'lodgroup-组件' },
ReflectionProbe: { category: 'graphics', summary: 'A box inside which reflections come from a bake rather than from the sky — the specular half of what a light probe volume answers.', doc: 'graphics/lighting', anchor: 'baked-light', anchorZh: '烘焙光照' },
PlanarReflection: { category: 'graphics', summary: 'Captures a mirrored view for flat lit surfaces, with layer filtering, capture quality and update controls.', doc: 'graphics/lighting' },
diff --git a/docs/astro/src/data/components.generated.json b/docs/astro/src/data/components.generated.json
index 051a2cb58..abca55bb2 100644
--- a/docs/astro/src/data/components.generated.json
+++ b/docs/astro/src/data/components.generated.json
@@ -4682,6 +4682,49 @@
}
]
},
+ {
+ "name": "StaticBatch",
+ "source": "ts",
+ "fields": [
+ {
+ "key": "group",
+ "type": "string",
+ "default": "empty",
+ "doc": "Meshes batch only with others of the same group. Empty is the default group."
+ },
+ {
+ "key": "state",
+ "type": "enum",
+ "default": "Waiting",
+ "values": [
+ "Waiting",
+ "Merged",
+ "Not merged: skinned",
+ "Not merged: morphing",
+ "Not merged: level of detail",
+ "Not merged: blended",
+ "Not merged: moves",
+ "Not merged: baked light",
+ "Not merged: alone in its group",
+ "Not merged: no mesh",
+ "Not merged: vertex layout",
+ "Not merged: disabled"
+ ],
+ "readonly": true
+ },
+ {
+ "key": "batched",
+ "type": "number",
+ "default": "0",
+ "range": "≥ 0",
+ "readonly": true
+ }
+ ],
+ "animatable": [
+ "state",
+ "batched"
+ ]
+ },
{
"name": "StreamedWorld",
"source": "ts",
diff --git a/pipeline/src/assets/audioCook.ts b/pipeline/src/assets/audioCook.ts
index f69cd77a5..43336a9e3 100644
--- a/pipeline/src/assets/audioCook.ts
+++ b/pipeline/src/assets/audioCook.ts
@@ -111,6 +111,12 @@ export async function encodeWavToMp3(wav: Uint8Array, bitrateKbps: number): Prom
return out;
}
+/** What the importer asked of a clip when it is not left to the length, or null for `auto`. Read here, beside the other audio importer settings. */
+export function audioLoadTypeOf(importer: Record<string, unknown> | undefined): 'streaming' | 'decompress' | null {
+ const type = importer?.loadType;
+ return type === 'streaming' || type === 'decompress' ? type : null;
+}
+
/** Per-asset audio import settings from the `.meta` importer block (tolerant). */
export function audioImportSettings(importer: Record<string, unknown> | undefined): {
compress: boolean; bitrateKbps: number;
diff --git a/pipeline/src/assets/cookAssets.ts b/pipeline/src/assets/cookAssets.ts
index c11c20cbb..1991cc449 100644
--- a/pipeline/src/assets/cookAssets.ts
+++ b/pipeline/src/assets/cookAssets.ts
@@ -27,7 +27,8 @@ import { packAtlas, decodePngImage, encodePagePng, type AtlasInputImage } from '
// Per-asset texture cook settings (compress opt-out / format / size cap), read
// from the `.meta` `importer` block — the same registry the inspector edits, so a
// texture's ship-time compression is authored per asset, not one global switch.
-import { audioLoadTypeOf, readTextureCookSettings } from '../project/importSettings';
+import { readTextureCookSettings } from '../project/importSettings';
+import { audioLoadTypeOf } from './audioCook';
// The compression a build gives one texture, and the one reason it is that.
// The branch below IS this function — a cook that re-derived the choice would
// be a second answer to the question an inspector asks before a build runs.
diff --git a/pipeline/src/project/importSettings.ts b/pipeline/src/project/importSettings.ts
index efef630c4..f80aad9cc 100644
--- a/pipeline/src/project/importSettings.ts
+++ b/pipeline/src/project/importSettings.ts
@@ -260,12 +260,6 @@ export const IMPORTER_SCHEMAS: Record<string, ImporterFieldSpec[]> = {
video: VIDEO,
};
-/** What the importer asked of a clip when it is not left to the length, or null for `auto`. */
-export function audioLoadTypeOf(importer: Record<string, unknown> | undefined): 'streaming' | 'decompress' | null {
- const type = importer?.loadType;
- return type === 'streaming' || type === 'decompress' ? type : null;
-}
-
/** Cook-facing audio import settings, tolerant of hand-edited `.meta` blocks. */
export function readAudioImportSettings(importer: Record<string, unknown> | undefined): {
compress: boolean; bitrateKbps: number;
diff --git a/pipeline/tests/runtime-config.test.ts b/pipeline/tests/runtime-config.test.ts
index 60c00fa95..b75614d42 100644
--- a/pipeline/tests/runtime-config.test.ts
+++ b/pipeline/tests/runtime-config.test.ts
@@ -13,7 +13,8 @@ import { describe, it, expect } from 'vitest';
import {
DEFAULT_RUNTIME_CONFIG, packagedRuntimeFields, runtimeConfigOf, withAudioLoadTypes,
} from '../src/project/runtimeConfig';
-import { audioLoadTypeOf, importerDefaults } from '../src/project/importSettings';
+import { importerDefaults } from '../src/project/importSettings';
+import { audioLoadTypeOf } from '../src/assets/audioCook';
describe('runtimeConfigOf', () => {
it('carries the same normalized quality policy into exported builds', () => {
diff --git a/sdk/etc/index.api.md b/sdk/etc/index.api.md
index 60fb0d70d..eda2e1b4c 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 · 152 beta · 1649 experimental · 3 deprecated
+Symbols: 115 public · 152 beta · 1651 experimental · 3 deprecated
## ABI_LAYOUT_HASH — const @experimental
```
@@ -4154,6 +4154,7 @@ phases: Record<string, number>
quality: QualityReport | undefined
seq: number | undefined
sprites: number
+staticBatch: StaticBatchSummary | undefined
triangles: number
vramBytes: number
wasmBytes: number
@@ -8815,7 +8816,9 @@ ComponentDef<StaticBatchData>
## StaticBatchData — interface @experimental
```
+batched: number
group: string
+state: number
```
## StaticBatchGroup — interface @experimental
@@ -8872,6 +8875,17 @@ groups: StaticBatchGroup[]
refused: Map<number, StaticBatchRefusal>
```
+## StaticBatchState — const @experimental
+```
+{ readonly Pending: 0; readonly Merged: 1; readonly Skinned: 2; readonly Morph: 3; readonly Lod: 4; readonly Blended: 5; readonly Moves: 6; readonly Baked: 7; readonly Alone: 8; readonly NoMesh: 9; readonly Layout: 10; readonly Disabled: 11; }
+```
+
+## StaticBatchSummary — interface @experimental
+```
+groups: { entity: number; parts: number[]; partCount: number; triangles: number; bytes: number; drawsBefore: number; }[]
+refused: { reason: string; count: number; entities: number[]; }[]
+```
+
## StaticBatching — class @experimental
```
@internal busy_: boolean
@@ -8885,6 +8899,7 @@ limits: StaticBatchLimits
pending: number
rebuild: () => void
report: () => StaticBatchReport
+summary: () => StaticBatchSummary | null
static new (): StaticBatching
static prototype: StaticBatching
```
diff --git a/sdk/etc/index.native.api.md b/sdk/etc/index.native.api.md
index 892ff34aa..0ae10b9e5 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 · 157 beta · 1668 experimental · 3 deprecated
+Symbols: 115 public · 157 beta · 1670 experimental · 3 deprecated
## ABI_LAYOUT_HASH — const @experimental
```
@@ -4162,6 +4162,7 @@ phases: Record<string, number>
quality: QualityReport | undefined
seq: number | undefined
sprites: number
+staticBatch: StaticBatchSummary | undefined
triangles: number
vramBytes: number
wasmBytes: number
@@ -9028,7 +9029,9 @@ ComponentDef<StaticBatchData>
## StaticBatchData — interface @experimental
```
+batched: number
group: string
+state: number
```
## StaticBatchGroup — interface @experimental
@@ -9085,6 +9088,17 @@ groups: StaticBatchGroup[]
refused: Map<number, StaticBatchRefusal>
```
+## StaticBatchState — const @experimental
+```
+{ readonly Pending: 0; readonly Merged: 1; readonly Skinned: 2; readonly Morph: 3; readonly Lod: 4; readonly Blended: 5; readonly Moves: 6; readonly Baked: 7; readonly Alone: 8; readonly NoMesh: 9; readonly Layout: 10; readonly Disabled: 11; }
+```
+
+## StaticBatchSummary — interface @experimental
+```
+groups: { entity: number; parts: number[]; partCount: number; triangles: number; bytes: number; drawsBefore: number; }[]
+refused: { reason: string; count: number; entities: number[]; }[]
+```
+
## StaticBatching — class @experimental
```
@internal busy_: boolean
@@ -9098,6 +9112,7 @@ limits: StaticBatchLimits
pending: number
rebuild: () => void
report: () => StaticBatchReport
+summary: () => StaticBatchSummary | null
static new (): StaticBatching
static prototype: StaticBatching
```
diff --git a/sdk/etc/index.node.api.md b/sdk/etc/index.node.api.md
index 878495e5d..1e53544be 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 · 154 beta · 1648 experimental · 3 deprecated
+Symbols: 115 public · 154 beta · 1650 experimental · 3 deprecated
## ANCHOR_AXES — const @experimental
```
@@ -4149,6 +4149,7 @@ phases: Record<string, number>
quality: QualityReport | undefined
seq: number | undefined
sprites: number
+staticBatch: StaticBatchSummary | undefined
triangles: number
vramBytes: number
wasmBytes: number
@@ -8810,7 +8811,9 @@ ComponentDef<StaticBatchData>
## StaticBatchData — interface @experimental
```
+batched: number
group: string
+state: number
```
## StaticBatchGroup — interface @experimental
@@ -8867,6 +8870,17 @@ groups: StaticBatchGroup[]
refused: Map<number, StaticBatchRefusal>
```
+## StaticBatchState — const @experimental
+```
+{ readonly Pending: 0; readonly Merged: 1; readonly Skinned: 2; readonly Morph: 3; readonly Lod: 4; readonly Blended: 5; readonly Moves: 6; readonly Baked: 7; readonly Alone: 8; readonly NoMesh: 9; readonly Layout: 10; readonly Disabled: 11; }
+```
+
+## StaticBatchSummary — interface @experimental
+```
+groups: { entity: number; parts: number[]; partCount: number; triangles: number; bytes: number; drawsBefore: number; }[]
+refused: { reason: string; count: number; entities: number[]; }[]
+```
+
## StaticBatching — class @experimental
```
@internal busy_: boolean
@@ -8880,6 +8894,7 @@ limits: StaticBatchLimits
pending: number
rebuild: () => void
report: () => StaticBatchReport
+summary: () => StaticBatchSummary | null
static new (): StaticBatching
static prototype: StaticBatching
```
diff --git a/sdk/etc/minigame.api.md b/sdk/etc/minigame.api.md
index d503001b6..383ee4e0f 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 · 152 beta · 1670 experimental · 3 deprecated
+Symbols: 115 public · 152 beta · 1672 experimental · 3 deprecated
## ANCHOR_AXES — const @experimental
```
@@ -4149,6 +4149,7 @@ phases: Record<string, number>
quality: QualityReport | undefined
seq: number | undefined
sprites: number
+staticBatch: StaticBatchSummary | undefined
triangles: number
vramBytes: number
wasmBytes: number
@@ -9103,7 +9104,9 @@ ComponentDef<StaticBatchData>
## StaticBatchData — interface @experimental
```
+batched: number
group: string
+state: number
```
## StaticBatchGroup — interface @experimental
@@ -9160,6 +9163,17 @@ groups: StaticBatchGroup[]
refused: Map<number, StaticBatchRefusal>
```
+## StaticBatchState — const @experimental
+```
+{ readonly Pending: 0; readonly Merged: 1; readonly Skinned: 2; readonly Morph: 3; readonly Lod: 4; readonly Blended: 5; readonly Moves: 6; readonly Baked: 7; readonly Alone: 8; readonly NoMesh: 9; readonly Layout: 10; readonly Disabled: 11; }
+```
+
+## StaticBatchSummary — interface @experimental
+```
+groups: { entity: number; parts: number[]; partCount: number; triangles: number; bytes: number; drawsBefore: number; }[]
+refused: { reason: string; count: number; entities: number[]; }[]
+```
+
## StaticBatching — class @experimental
```
@internal busy_: boolean
@@ -9173,6 +9187,7 @@ limits: StaticBatchLimits
pending: number
rebuild: () => void
report: () => StaticBatchReport
+summary: () => StaticBatchSummary | null
static new (): StaticBatching
static prototype: StaticBatching
```
diff --git a/sdk/etc/wechat.api.md b/sdk/etc/wechat.api.md
index 72d5efe5b..6d47d05bb 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 · 152 beta · 1661 experimental · 3 deprecated
+Symbols: 115 public · 152 beta · 1663 experimental · 3 deprecated
## ANCHOR_AXES — const @experimental
```
@@ -4149,6 +4149,7 @@ phases: Record<string, number>
quality: QualityReport | undefined
seq: number | undefined
sprites: number
+staticBatch: StaticBatchSummary | undefined
triangles: number
vramBytes: number
wasmBytes: number
@@ -8817,7 +8818,9 @@ ComponentDef<StaticBatchData>
## StaticBatchData — interface @experimental
```
+batched: number
group: string
+state: number
```
## StaticBatchGroup — interface @experimental
@@ -8874,6 +8877,17 @@ groups: StaticBatchGroup[]
refused: Map<number, StaticBatchRefusal>
```
+## StaticBatchState — const @experimental
+```
+{ readonly Pending: 0; readonly Merged: 1; readonly Skinned: 2; readonly Morph: 3; readonly Lod: 4; readonly Blended: 5; readonly Moves: 6; readonly Baked: 7; readonly Alone: 8; readonly NoMesh: 9; readonly Layout: 10; readonly Disabled: 11; }
+```
+
+## StaticBatchSummary — interface @experimental
+```
+groups: { entity: number; parts: number[]; partCount: number; triangles: number; bytes: number; drawsBefore: number; }[]
+refused: { reason: string; count: number; entities: number[]; }[]
+```
+
## StaticBatching — class @experimental
```
@internal busy_: boolean
@@ -8887,6 +8901,7 @@ limits: StaticBatchLimits
pending: number
rebuild: () => void
report: () => StaticBatchReport
+summary: () => StaticBatchSummary | null
static new (): StaticBatching
static prototype: StaticBatching
```
diff --git a/sdk/src/core-content.ts b/sdk/src/core-content.ts
index abbc156c8..2f2da6039 100644
--- a/sdk/src/core-content.ts
+++ b/sdk/src/core-content.ts
@@ -777,7 +777,7 @@ export {
} from './render/meshRenderer';
export {
StaticBatch, StaticBatching, StaticBatchingRes, StaticBatchPlugin, staticBatchPlugin,
- type StaticBatchData,
+ StaticBatchState, type StaticBatchData, type StaticBatchSummary,
} from './render/staticBatchPlugin';
export {
mergeMeshes, planStaticBatches, STATIC_BATCH_DEFAULTS,
diff --git a/sdk/src/render/staticBatchPlugin.ts b/sdk/src/render/staticBatchPlugin.ts
index 1ed0d4a59..276a76662 100644
--- a/sdk/src/render/staticBatchPlugin.ts
+++ b/sdk/src/render/staticBatchPlugin.ts
@@ -23,7 +23,6 @@ import {
defineComponent, getComponent, MeshRenderer, Transform, SceneOwner,
type ComponentDef, type MeshRendererData, type TransformData,
} from '../ecs/component';
-import { RigidBody3D, CharacterController3D } from '../physics3d/Physics3DComponents';
import { BodyType } from '../wasm/wasm.generated';
import { playModeOnly } from '../ecs/env';
import { Assets } from '../asset/AssetPlugin';
@@ -36,10 +35,37 @@ import {
type StaticBatchReport,
} from './staticBatch';
+/** Where a marked mesh stands after the last pass: not decided yet, merged, or left out and why. @experimental */
+export const StaticBatchState = {
+ Pending: 0,
+ Merged: 1,
+ Skinned: 2,
+ Morph: 3,
+ Lod: 4,
+ Blended: 5,
+ Moves: 6,
+ Baked: 7,
+ Alone: 8,
+ NoMesh: 9,
+ Layout: 10,
+ Disabled: 11,
+} as const;
+
+const REFUSAL_STATE: Record<StaticBatchRefusal, number> = {
+ skinned: StaticBatchState.Skinned, morph: StaticBatchState.Morph, lod: StaticBatchState.Lod,
+ blended: StaticBatchState.Blended, moves: StaticBatchState.Moves, baked: StaticBatchState.Baked,
+ alone: StaticBatchState.Alone, 'no-mesh': StaticBatchState.NoMesh, layout: StaticBatchState.Layout,
+ disabled: StaticBatchState.Disabled,
+};
+
/** The fields of the `StaticBatch` component. @experimental */
export interface StaticBatchData {
/** Meshes batch only with others of the same group, so two rooms can be kept apart. */
group: string;
+ /** What the last pass did with this mesh (a {@link StaticBatchState}); written by the pass, 0 until it has run. */
+ state: number;
+ /** How many meshes were drawn together with this one, itself included; 0 unless merged. */
+ batched: number;
}
/**
@@ -50,9 +76,33 @@ export interface StaticBatchData {
*/
export const StaticBatch: ComponentDef<StaticBatchData> = defineComponent<StaticBatchData>('StaticBatch', {
group: '',
+ state: StaticBatchState.Pending,
+ batched: 0,
}, {
+ // The pass writes these into the running world; they are outputs, never authoring.
+ readonlyFields: ['state', 'batched'],
fields: {
group: { tooltip: 'Meshes batch only with others of the same group. Empty is the default group.' },
+ state: {
+ label: 'Status',
+ enum: [
+ { label: 'Waiting', value: StaticBatchState.Pending },
+ { label: 'Merged', value: StaticBatchState.Merged },
+ { label: 'Not merged: skinned', value: StaticBatchState.Skinned },
+ { label: 'Not merged: morphing', value: StaticBatchState.Morph },
+ { label: 'Not merged: level of detail', value: StaticBatchState.Lod },
+ { label: 'Not merged: blended', value: StaticBatchState.Blended },
+ { label: 'Not merged: moves', value: StaticBatchState.Moves },
+ { label: 'Not merged: baked light', value: StaticBatchState.Baked },
+ { label: 'Not merged: alone in its group', value: StaticBatchState.Alone },
+ { label: 'Not merged: no mesh', value: StaticBatchState.NoMesh },
+ { label: 'Not merged: vertex layout', value: StaticBatchState.Layout },
+ { label: 'Not merged: disabled', value: StaticBatchState.Disabled },
+ ],
+ // Nothing to say before a pass has run, so the row stays out of the way in the editor.
+ shownWhen: { field: 'state', values: [1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11] },
+ },
+ batched: { label: 'Batched meshes', min: 0, shownWhen: { field: 'state', values: [1] } },
},
});
@@ -72,6 +122,27 @@ export class StaticBatching {
return { groups: this.groups_.map((g) => g.report), refused: new Map(this.refused_) };
}
+ /** The last passes in the small form the profiler reports across a process boundary. */
+ summary(): StaticBatchSummary | null {
+ if (this.groups_.length === 0 && this.refused_.size === 0) return null;
+ const byReason = new Map<string, number[]>();
+ for (const [entity, why] of this.refused_) {
+ const list = byReason.get(why);
+ if (list) list.push(entity); else byReason.set(why, [entity]);
+ }
+ return {
+ groups: this.groups_.map((g) => ({
+ entity: g.entity,
+ parts: g.parts.slice(0, SUMMARY_IDS),
+ partCount: g.parts.length,
+ triangles: g.report.triangles,
+ bytes: g.report.bytes,
+ drawsBefore: g.report.drawsBefore,
+ })),
+ refused: [...byReason].map(([reason, entities]) => ({ reason, count: entities.length, entities: entities.slice(0, SUMMARY_IDS) })),
+ };
+ }
+
/** Marked entities the pass has not decided on yet (their mesh is still loading). */
get pending(): number {
return this.pending_;
@@ -84,6 +155,15 @@ export class StaticBatching {
}
}
+/** Entities named per group or reason in {@link StaticBatching.summary}: enough to select, small enough to poll. */
+const SUMMARY_IDS = 200;
+
+/** What the profiler shows of the batcher: one entry per merged mesh, and the meshes left out by reason. */
+export interface StaticBatchSummary {
+ groups: { entity: number; parts: number[]; partCount: number; triangles: number; bytes: number; drawsBefore: number }[];
+ refused: { reason: string; count: number; entities: number[] }[];
+}
+
/** The resource the plugin installs. @experimental */
export const StaticBatchingRes = defineResource<StaticBatching>(new StaticBatching(), 'StaticBatching');
@@ -162,9 +242,17 @@ export class StaticBatchPlugin implements Plugin {
return world.getEntitiesWithComponents([StaticBatch, MeshRenderer, Transform]).filter((e) => !state.seen_.has(e));
}
- private refuse(state: StaticBatching, entity: Entity, why: StaticBatchRefusal): void {
+ private refuse(app: App, state: StaticBatching, entity: Entity, why: StaticBatchRefusal): void {
state.refused_.set(entity, why);
state.seen_.add(entity);
+ this.stamp(app, entity, REFUSAL_STATE[why], 0);
+ }
+
+ /** Records on the component what became of it, which is where the editor reads it from. */
+ private stamp(app: App, entity: Entity, status: number, batched: number): void {
+ const world = app.world;
+ if (!world.valid(entity) || !world.has(entity, StaticBatch)) return;
+ world.insert(entity, StaticBatch, { ...(world.get(entity, StaticBatch) as StaticBatchData), state: status, batched });
}
private async pass(app: App, state: StaticBatching, assets: ReturnType<App['getResource']> & any, entities: Entity[]): Promise<void> {
@@ -173,6 +261,9 @@ export class StaticBatchPlugin implements Plugin {
const skinDef = getComponent('MeshSkin');
const probeDef = getComponent('LightProbeVolume');
const bakedDef = getComponent('BakedLighting');
+ // By name, not import: 3D physics is an optional subsystem and a static batch has no business carrying its solver.
+ const bodyDef = getComponent('RigidBody3D');
+ const characterDef = getComponent('CharacterController3D');
const probed = !!probeDef && world.getEntitiesWithComponents([probeDef]).length > 0;
const baked = !!bakedDef && world.getEntitiesWithComponents([bakedDef])
.some((e) => (world.get(e, bakedDef) as { bakedFrom?: string }).bakedFrom);
@@ -185,23 +276,23 @@ export class StaticBatchPlugin implements Plugin {
if (!world.valid(e)) continue;
const mr = world.get(e, MeshRenderer) as MeshRendererData;
const sb = world.get(e, StaticBatch) as StaticBatchData;
- if (!mr.enabled) { this.refuse(state, e, 'disabled'); continue; }
- if (!mr.opaque) { this.refuse(state, e, 'blended'); continue; }
- if (lodDef && world.has(e, lodDef)) { this.refuse(state, e, 'lod'); continue; }
- if (skinDef && world.has(e, skinDef)) { this.refuse(state, e, 'skinned'); continue; }
- if (world.has(e, CharacterController3D)
- || (world.has(e, RigidBody3D) && (world.get(e, RigidBody3D) as { bodyType: number }).bodyType !== BodyType.Static)) {
- this.refuse(state, e, 'moves');
+ if (!mr.enabled) { this.refuse(app, state, e, 'disabled'); continue; }
+ if (!mr.opaque) { this.refuse(app, state, e, 'blended'); continue; }
+ if (lodDef && world.has(e, lodDef)) { this.refuse(app, state, e, 'lod'); continue; }
+ if (skinDef && world.has(e, skinDef)) { this.refuse(app, state, e, 'skinned'); continue; }
+ if ((characterDef && world.has(e, characterDef))
+ || (bodyDef && world.has(e, bodyDef) && (world.get(e, bodyDef) as { bodyType: number }).bodyType !== BodyType.Static)) {
+ this.refuse(app, state, e, 'moves');
continue;
}
- if (probed) { this.refuse(state, e, 'baked'); continue; }
+ if (probed) { this.refuse(app, state, e, 'baked'); continue; }
if (!meshes.has(mr.mesh)) meshes.set(mr.mesh, await assets.readMeshData(mr.mesh));
const mesh = meshes.get(mr.mesh) ?? null;
- if (!mesh) { this.refuse(state, e, 'no-mesh'); continue; }
- if (baked && mesh.channels.some((c) => c.semantic === MeshChannel.TexCoord1)) { this.refuse(state, e, 'baked'); continue; }
+ if (!mesh) { this.refuse(app, state, e, 'no-mesh'); continue; }
+ if (baked && mesh.channels.some((c) => c.semantic === MeshChannel.TexCoord1)) { this.refuse(app, state, e, 'baked'); continue; }
const layout = layoutRefusal(mesh);
- if (layout) { this.refuse(state, e, layout); continue; }
+ if (layout) { this.refuse(app, state, e, layout); continue; }
if (!world.valid(e)) continue;
const t = world.get(e, Transform) as TransformData;
@@ -222,17 +313,17 @@ export class StaticBatchPlugin implements Plugin {
}
const plan = planStaticBatches(candidates, state.limits);
- for (const e of plan.alone) this.refuse(state, e as Entity, 'alone');
+ for (const e of plan.alone) this.refuse(app, state, e as Entity, 'alone');
for (const batch of plan.batches) {
const members = batch.entities.filter((e) => world.valid(e as Entity)) as Entity[];
- if (members.length < 2) { for (const e of members) this.refuse(state, e, 'alone'); continue; }
+ if (members.length < 2) { for (const e of members) this.refuse(app, state, e, 'alone'); continue; }
const parts: BatchPart[] = members.map((e) => ({ mesh: info.get(e)!.mesh, world: info.get(e)!.world }));
const merged = mergeMeshes(parts);
const handle = assets.createMesh(merged);
if (handle === 0) {
log.warn('staticBatch', `the engine refused a merged mesh of ${members.length} parts (${merged.vertexCount} vertices)`);
- for (const e of members) this.refuse(state, e, 'layout');
+ for (const e of members) this.refuse(app, state, e, 'layout');
continue;
}
const head = info.get(members[0]!)!;
@@ -244,6 +335,7 @@ export class StaticBatchPlugin implements Plugin {
const mr = world.get(e, MeshRenderer) as MeshRendererData;
world.insert(e, MeshRenderer, { ...mr, enabled: false });
state.seen_.add(e);
+ this.stamp(app, e, StaticBatchState.Merged, members.length);
}
state.groups_.push({
entity: holder, handle, parts: members,
@@ -286,7 +378,7 @@ export class StaticBatchPlugin implements Plugin {
const index = state.groups_.indexOf(g);
if (index < 0) return;
if (alive.length < 2) {
- for (const e of alive) this.restore(world, e);
+ for (const e of alive) { this.restore(world, e); this.stamp(app, e, StaticBatchState.Alone, 0); }
if (world.valid(g.entity)) world.despawn(g.entity);
assets.releaseBuiltMesh(g.handle);
state.groups_.splice(index, 1);
@@ -311,6 +403,7 @@ export class StaticBatchPlugin implements Plugin {
assets.releaseBuiltMesh(g.handle);
g.handle = handle;
g.parts = alive;
+ for (const e of alive) this.stamp(app, e, StaticBatchState.Merged, alive.length);
g.report = {
...g.report, parts: alive, vertices: merged.vertexCount, triangles: merged.indices.length / 3,
bytes: merged.vertices.byteLength + merged.indices.byteLength,
diff --git a/sdk/src/runtime/frameStats.ts b/sdk/src/runtime/frameStats.ts
index 1891b2b24..73626594a 100644
--- a/sdk/src/runtime/frameStats.ts
+++ b/sdk/src/runtime/frameStats.ts
@@ -9,6 +9,7 @@ import type { App, FrameCosts } from '../app/app';
import { engineApi } from '../ecs/bridge/engineApi';
import { Quality } from '../render/qualityRuntime';
import { Audio } from '../audio/Audio';
+import { StaticBatchingRes, type StaticBatchSummary } from '../render/staticBatchPlugin';
import type { QualityReport } from '../render/quality';
export interface FrameStatsReport {
@@ -32,6 +33,8 @@ export interface FrameStatsReport {
audioBytes?: number;
audioStreamedCount?: number;
audioStreamedSavedBytes?: number;
+ /** What static batching merged and left out; absent until a mesh has been marked. */
+ staticBatch?: StaticBatchSummary;
quality?: QualityReport;
}
@@ -63,6 +66,7 @@ export function frameStatsReport(app: App): FrameStatsReport {
wasmBytes: app.wasmModule?.HEAPU8?.byteLength ?? 0,
vramBytes: m?.renderer_getEstimatedGpuBytes?.() ?? 0,
...audioStats(app),
+ ...(app.hasResource(StaticBatchingRes) ? (() => { const s = app.getResource(StaticBatchingRes).summary(); return s ? { staticBatch: s } : {}; })() : {}),
quality: app.hasResource(Quality) ? app.getResource(Quality)?.report() : undefined,
};
}
diff --git a/tools/check-corpus-authoring.mjs b/tools/check-corpus-authoring.mjs
index 0a2bff059..459e8f08a 100644
--- a/tools/check-corpus-authoring.mjs
+++ b/tools/check-corpus-authoring.mjs
@@ -123,6 +123,7 @@ const DISPOSITION = {
// — owed: a creator-facing component nothing in the shipped corpus authors.
// Each reason names where the coverage belongs. —
+ StaticBatch: ['owed', 'no corpus scene marks a mesh yet: a marked mesh is merged while the game runs, which a golden project has no frame to certify — the static-batch-on / static-batch-off render scenes, tests/static-batch.test.ts and the static-batch editor check hold it'],
};
const snapshot = JSON.parse(readFileSync(SNAPSHOT, 'utf8'));
diff --git a/tools/goldenProjects.mjs b/tools/goldenProjects.mjs
index f747b3b4c..76bc641ea 100644
--- a/tools/goldenProjects.mjs
+++ b/tools/goldenProjects.mjs
@@ -92,8 +92,6 @@ export const CENSUS_FLOOR = '0.60.0';
* that does not exist, and release notes are a different act. Theirs is ungated.
*/
export const SHIPPED = {
- "Static batching.": { notCertifiable: "Static batching is covered by the static-batch SDK tests and the static-batch-on / static-batch-off render scenes (draw calls and pixels); no golden project marks a mesh StaticBatch." },
- "Camera shots and nested sequences on the timeline.": { notCertifiable: "Camera and sequence tracks are covered by the timeline-sequences, timeline-drive and camera-director SDK tests and the editor timeline-clips tests; no golden project plays a timeline with a camera or sequence track." },
"Dynamic planar reflections.": { notCertifiable: "Planar reflection is covered by the planar-reflection and planar-reflection-off render-scene pixel gates, tools/tests/planar-reflection.e2e.mjs, test_planar_reflection and the planar-reflection editor authoring check; no golden project carries a reflecting surface." },
"SUD OpenPaaS development export.": { notCertifiable: "The OpenPaaS export is covered by the pipeline export and package tests, the native SUD runtime end-to-end check and the packer verification; no golden project is packaged for OpenPaaS." },
"Plugin filesystem operations.": { notCertifiable: "Editor plugin file access is covered by the plugin-filesystem editor authoring check and the editor tests; a packaged game loads no editor plugin." },
diff --git a/tools/releaseNotes.mjs b/tools/releaseNotes.mjs
index 2e1fc7d2d..57a0b237f 100644
--- a/tools/releaseNotes.mjs
+++ b/tools/releaseNotes.mjs
@@ -2449,6 +2449,10 @@ export const NOTED = {
{"note":"Device quality profiles can be previewed in the editor."},
"fix(editor): opening a timeline opens the Sequencer":
{"note":"Opening a timeline opens the Sequencer."},
+ "feat(render): static batching reports what became of each mesh and why":
+ {"note":"Static meshes that share a material can be drawn as one."},
+ "feat(editor): the outliner marks static batches and the profiler lists what merged":
+ {"note":"Static meshes that share a material can be drawn as one."},
"feat(render): static batching draws marked meshes that share a material as one mesh":
{"note":"Static meshes that share a material can be drawn as one."},
"feat(timeline): camera and sequence tracks play shots and nested timelines":