# BatchManager

Class · category: Graphics

Source: https://github.com/playcanvas/engine/blob/970d89f6d3bc6667f4e1f88153abd6e7e82ed52c/src/scene/batching/batch-manager.js#L66

Glues many mesh instances into a single one for better performance.

## Constructors

### constructor

```ts
new BatchManager(device: GraphicsDevice, root: Entity, scene: Scene)
```

Create a new BatchManager instance.

**Parameters**

- `device` ([`GraphicsDevice`](https://api.playcanvas.com/engine/classes/GraphicsDevice.md)): The graphics device used by the batch manager.
- `root` ([`Entity`](https://api.playcanvas.com/engine/classes/Entity.md)): The entity under which batched models are added.
- `scene` ([`Scene`](https://api.playcanvas.com/engine/classes/Scene.md)): The scene that the batch manager affects.

## Methods

### addGroup

```ts
addGroup(name: string, dynamic: boolean, maxAabbSize: number, id?: number, layers?: number[]): BatchGroup
```

Adds new global batch group.

**Parameters**

- `name` (`string`): Custom name.
- `dynamic` (`boolean`): Is this batch group dynamic? Will these objects move/rotate/scale
  after being batched?
- `maxAabbSize` (`number`): Maximum size of any dimension of a bounding box around batched
  objects. [prepare](https://api.playcanvas.com/engine/classes/BatchManager.md#prepare) will split objects into local groups based on this size.
- `id` (`number`, optional): Optional custom unique id for the group (will be generated
  automatically otherwise).
- `layers` (`number[]`, optional): Optional layer ID array. Default is [[LAYERID_WORLD](https://api.playcanvas.com/engine/variables/LAYERID_WORLD.md)].
  The whole batch group will belong to these layers. Layers of source models will be ignored.

**Returns** [`BatchGroup`](https://api.playcanvas.com/engine/classes/BatchGroup.md): Group object.

### create

```ts
create(meshInstances: MeshInstance[], dynamic: boolean, batchGroupId?: number): Batch
```

Takes a mesh instance list that has been prepared by [prepare](https://api.playcanvas.com/engine/classes/BatchManager.md#prepare), and
returns a [Batch](https://api.playcanvas.com/engine/classes/Batch.md) object. This method assumes that all mesh instances provided can be
rendered in a single draw call.

**Parameters**

- `meshInstances` ([`MeshInstance`](https://api.playcanvas.com/engine/classes/MeshInstance.md)`[]`): Input list of mesh instances.
- `dynamic` (`boolean`): Is it a static or dynamic batch? Will objects be transformed
  after batching?
- `batchGroupId` (`number`, optional): Link this batch to a specific batch group. This is done
  automatically with default batches.

**Returns** [`Batch`](https://api.playcanvas.com/engine/classes/Batch.md): The resulting batch object.

### generate

```ts
generate(groupIds?: number[]): void
```

Destroys all batches and creates new based on scene models. Hides original models. Called by
engine automatically on app start, and if batchGroupIds on models are changed.

**Parameters**

- `groupIds` (`number[]`, optional): Optional array of batch group IDs to update. Otherwise all
  groups are updated.

### getGroupById

```ts
getGroupById(id: number): BatchGroup | null
```

Retrieves a [BatchGroup](https://api.playcanvas.com/engine/classes/BatchGroup.md) object with a corresponding id, if it exists, or null
otherwise.

**Parameters**

- `id` (`number`): The batch group id.

**Returns** [`BatchGroup`](https://api.playcanvas.com/engine/classes/BatchGroup.md) `| null`: The batch group matching the id or null if not found.

### getGroupByName

```ts
getGroupByName(name: string): BatchGroup | null
```

Retrieves a [BatchGroup](https://api.playcanvas.com/engine/classes/BatchGroup.md) object with a corresponding name, if it exists, or null
otherwise.

**Parameters**

- `name` (`string`): Name.

**Returns** [`BatchGroup`](https://api.playcanvas.com/engine/classes/BatchGroup.md) `| null`: The batch group matching the name or null if not found.

### markGroupDirty

```ts
markGroupDirty(id: number): void
```

Mark a specific batch group as dirty. Dirty groups are re-batched before the next frame is
rendered. Note, re-batching a group is a potentially expensive operation.

**Parameters**

- `id` (`number`): Batch Group ID to mark as dirty.

### prepare

```ts
prepare(meshInstances: MeshInstance[], dynamic: boolean, maxAabbSize?: number, translucent: boolean): MeshInstance[][]
```

Takes a list of mesh instances to be batched and sorts them into lists one for each draw
call. The input list will be split, if:

- Mesh instances use different materials.
- Mesh instances have different parameters (e.g. lightmaps or static lights).
- Mesh instances have different shader defines (shadow receiving, being aligned to screen
space, etc).
- Too many vertices for a single batch (65535 is maximum).
- Too many instances for a single batch (hardware-dependent, expect 128 on low-end and 1024
on high-end).
- Bounding box of a batch is larger than maxAabbSize in any dimension.
- Mesh instances differ in shadow casting ([MeshInstance#castShadow](https://api.playcanvas.com/engine/classes/MeshInstance.md#castshadow)) or directional
shadow cascade mask ([MeshInstance#shadowCascadeMask](https://api.playcanvas.com/engine/classes/MeshInstance.md#shadowcascademask)).

**Parameters**

- `meshInstances` ([`MeshInstance`](https://api.playcanvas.com/engine/classes/MeshInstance.md)`[]`): Input list of mesh instances
- `dynamic` (`boolean`): Are we preparing for a dynamic batch? Instance count will matter
  then (otherwise not).
- `maxAabbSize` (`number`, optional, default `Number.POSITIVE_INFINITY`): Maximum size of any dimension of a bounding box around batched
  objects.
- `translucent` (`boolean`): Are we batching UI elements or sprites
  This is useful to keep a balance between the number of draw calls and the number of drawn
  triangles, because smaller batches can be hidden when not visible in camera.

**Returns** [`MeshInstance`](https://api.playcanvas.com/engine/classes/MeshInstance.md)`[][]`: An array of arrays of mesh instances, each valid to pass to
[create](https://api.playcanvas.com/engine/classes/BatchManager.md#create).

### removeGroup

```ts
removeGroup(id: number): void
```

Remove global batch group by id. Note, this traverses the entire scene graph and clears the
batch group id from all components.

**Parameters**

- `id` (`number`): Batch Group ID.