Static Batching

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.

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.