
# Physics Aggregate

## What is an Aggregate

The Physics Aggregate is an object that contains a body and a shape. It is a helper that allows you to create all the objects needed to physicalize your scene in just one call. In that sense, it is similar to Physics V1 Impostors, but with more control. Once created, you can easily access the individual parts and tweak them.

## How to use it

```javascript
const sphere = BABYLON.MeshBuilder.CreateSphere("sphere", { segments: 16, diameter: 2 }, scene);
const aggregate = new BABYLON.PhysicsAggregate(sphere, BABYLON.PhysicsShapeType.SPHERE, { mass: 1 }, scene);
```

This is very similar to the Physics V1 Impostor.
When the aggregate is created, a body and a shape are instantiated all at once. However, recreating shapes is not the most performant choice. You can instead pass the shape rather than the `PhysicsShapeType`, and the aggregate will reuse that shape:

```javascript
const sphere = BABYLON.MeshBuilder.CreateSphere("sphere", { segments: 16, diameter: 2 }, scene);
const sphere2 = sphere.clone("sphere2");

const aggregate = new BABYLON.PhysicsAggregate(sphere, BABYLON.PhysicsShapeType.SPHERE, { mass: 1 }, scene);
const aggregate2 = new BABYLON.PhysicsAggregate(sphere2, aggregate.shape, { mass: 1 }, scene);
```


<Playground id="#4Y813L#40" title="Reuse shapes with Aggregates" description="Reuse shapes with Aggregates"/>

<Playground id="#Z8HTUN" title="Simple scene with Aggregate" description="Simple falling sphere created with an aggregate"/>

## Tweaking and accessing individual components

You can access the individual physics components by using the accessors:

```javascript
const aggregate = new BABYLON.PhysicsAggregate(sphere, BABYLON.PhysicsShapeType.SPHERE, { mass: 1 }, scene);
aggregate.body.setMassProperties({mass: 10});
```

## Disposing of an Aggregate

You can dispose of an aggregate by using the `dispose` method. This disposes of the body and the shape that were created by it, if the shape was created by the aggregate. If the shape was passed as a parameter, then it will not be disposed of, as it could still be in use by another body.



## What is it?

Collision events are often used in game development to trigger events or reactions based on collisions. For example, a collision between a player character and an enemy could trigger damage to the player, while a collision between a player and a collectible item could trigger a pickup event. Collisions can either cause a physical response (like pushing the player back), or not, in which case they are called trigger collisions. The collision event system uses the Observable and Observer system, which is also used in other parts of Babylon.js.

## How to use

There are three types of **collision** events:

- COLLISION_STARTED
- COLLISION_CONTINUED
- COLLISION_FINISHED

And two types of **trigger** events:

- TRIGGER_ENTERED
- TRIGGER_EXITED

To use collision callbacks, first, the body needs to enable it. This can be achieved with `setCollisionCallbackEnabled`, for the COLLISION_STARTED and COLLISION_CONTINUED events, or with `setCollisionEndedCallbackEnabled` for the COLLISION_ENDED event. Then, we need to obtain the collision Observable by calling `getCollisionObservable` or `getCollisionEndedObservable` on the body. You can have either a body-specific callback or a world-wide callback. The second option requires filtering for the correct body to process, but it is more performant.

```javascript
// player is a PhysicsBody
player.setCollisionCallbackEnabled(true);

// You have two options:
// Body-specific callback
const observable = player.getCollisionObservable();
const observer = observable.add((collisionEvent) => {
  // Process collisions for the player
});

// OR

// world callback
const observable = plugin.onCollisionObservable;
const observer = observable.add((collisionEvent) => {
  // Check if the player is involved in the collision
  if (collisionEvent.collider === player || collisionEvent.collidedAgainst === player) {
    // Process collisions for the player
    // ...
  }
});
```

As for triggers, you need to mark the **shape** as a trigger by setting the property `isTrigger` to true, and then by creating a body for that shape. There is no body-specific callback for the triggers, only the world-wide callback.

```javascript
shape.isTrigger = true;

// create a body with that shape
// const body = new BABYLON.PhysicsBody(node, ...);

const observable = plugin.onTriggerCollisionObservable;
const observer = observable.add((collisionEvent) => {
  if (collisionEvent.type === "TRIGGER_ENTERED") {
    // do something when the trigger is entered
  } else {
    // do something when trigger is exited
  }
});
```

## Collision filtering

Collisions between two bodies can be ignored by using the filtering mechanism on their respective Physics Shapes.

The property `filterMembershipMask` is a bitmask of categories which this shape is a member of.

The property `filterCollideMask` is a bitmask of arbitrary "categories" with which this shape collides.

Given two shapes, the engine will check if the collide mask and membership overlap:

`shapeA.filterMembershipMask & shapeB.filterCollideMask`

If this value is zero (i.e. shapeB only collides with categories which shapeA is not a member of) then the shapes will not collide.

Note, the engine will also perform the same test with shapeA and shapeB swapped; the shapes will not collide if either shape has a collideMask which prevents collision with the other shape.

## Examples

- Use collision observer to log an output when bodies are colliding: <Playground id="#7JI3E8#1" title="Collision observers" description="Use collision observer to log an output when bodies are colliding"/>

- Using a trigger volume: <Playground id="#M0C2X5#1" title="Triggers" description="Using a trigger volume" />

- Logging the collision events that happen to a body: <Playground id="#Z8HTUN#613" title="Collision events" description="Logging the collision events that happen to a body"/>

- Collision filtering: <Playground id="#H4UR4Z#1" title="Collision filtering" description="Filtering collisions that happen to a body"/>



## What is it

The Compound is a special type of shape that acts as a "container" for other shapes. It allows you to model complex objects by using simple primitives, achieving a better approximation than using only one simple geometric shape.

## How to use

Imagine you have a mesh that represents a character. Character meshes are usually pretty complex, so we want to avoid using them directly for collision. We can approximate the shape of the character with a sphere representing the head and a box representing the rest of the body. We will create two meshes to represent these shapes, parent them to the character mesh, create two child physics shapes, and parent them to a `PhysicsShapeContainer`:

```javascript
const myMesh = BABYLON.ImportMeshAsync(...);

const headNode = new BABYLON.TransformNode("headNode");
headNode.position.y = 3;
headNode.parent = myMesh;
const bodyNode = new BABYLON.TransformNode("bodyNode");
bodyNode.parent = myMesh;

const boxShape = new BABYLON.PhysicsShapeBox(new BABYLON.Vector3(0, 0, 0), new BABYLON.Quaternion(0, 0, 0, 1), new BABYLON.Vector3(1, 2, 1), scene);
const sphereShape = new BABYLON.PhysicsShapeSphere(new BABYLON.Vector3(0, 0, 0), 1, scene);

const parentShape = new BABYLON.PhysicsShapeContainer(scene);

parentShape.addChildFromParent(myMesh, boxShape, bodyNode);
parentShape.addChildFromParent(myMesh, sphereShape, headNode);

const body = new BABYLON.PhysicsBody(myMesh, scene);
body.shape = parentShape;
```

The following Playground shows a simple example of creating a container body to approximate a mesh:
<Playground id="3H3DLR" title="Simple Physics Container example" description="Simple Physics Container example" />

The following Playground shows a comparison of using Container, Convex Hull and Mesh shapes on different meshes:
<Playground id="LKPBW5" title="Comparison of using Container, Convex Hull and Mesh shapes on different meshes" description="Comparison of using Container, Convex Hull and Mesh shapes on different meshes" />


Aggregates

What is an Aggregate

How to use it

Tweaking and accessing individual components

Disposing of an Aggregate

Further reading

Forces

Learn all about applying physical forces in Babylon.js.