User Manual

Batching

Batching is the process of combining multiple mesh instances together into a single mesh instance, so that they can all be rendered in a single GPU draw call. PlayCanvas provides a handy feature on the Model, Sprite and Element components that lets you assign these components to batch groups which give the engine hints on how to combine meshes to reduce the overall draw call count.

There are a variety of rules which the engine will apply to see if mesh instances are able to be combined. The primary rule is that all mesh instances must share the same material.

Common batching use cases are:

The use of batching is currently not compatible with runtime lightmaps due to each lightmapped object requiring its own unique lightmap texture.

Creating Batch Groups

Creating Batch Groups

Batch Groups can be created from the Batch Groups section of the scene settings panel. Each batch group has a number of properties that are used to give the engine hints about how to create batches from this batch group.

Batch Group Properties

Adding a component to a Batch Group

Selecting Batch Groups

The Model component has a Batch Group property to assign a model into a batch group.

Rules for combining mesh instances

The rules for whether the engine can combine mesh instances are fairly complicated but a good summary is that all mesh instances that belong to a single batch must obey the following:

If a batch group contains components or mesh instances that do not obey all of the rules the batch group will produce multiple batches such that each individual batch contains mesh instance that follow all the rules.

Trigger re-batching

Based on Batch Groups the engine creates an optimized version of mesh instances. Further changes to many properties of the original mesh instances are not reflected in the optimized versions. To allow for good performance by using batching, while still allowing some further updates, you can request the engine to rebatch individual Batch Groups after you make changes to the original mesh instances. This is often useful with User Interface element components, where you might want to set up batching, but still need to do infrequent updates. Note that re-batching a group is a potentially expensive operation. In many cases, the impact of rebatching can be minimized by separating elements that need updating to separate Batch Group.

Here is an example of a simple script. The script updates textureAsset on an element, and marks the Batch Group as dirty.

// change textureAsset on element
element.textureAsset = this.hoverAsset;

// if this element has Batch Group set, mark it dirty to rebuild the group in the next frame
if (element.batchGroupId)
    this.app.batcher.markGroupDirty(element.batchGroupId);

Example - Batching a static environment

Western Scene

In this scene we have created a static environment from 7 separate model files, some of which are repeated in the scene. For example, the road tile is used to in 50 entities to create the long road through the center of the scene.

Western Animation

You can see in the animation each draw call as it is made. In this environment the engine makes over 50 draw calls to draw each of the models individually. However, apart from the ground, all of these models use the same material and so they can be combined into batch groups.

Western Animation Batched

In this animation we have created 4 batch groups for the buildings, the cacti, the road and the ground. Notice, that the road and the ground are not combined into single draw calls because the meshes are larger than the Max AABB Size defined on the batch group.

Terminology