
## 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 2 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" to which this shape collides with.

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

A constraint represents a *connection* between two bodies. This connection can apply restrictions on the relative movement of the bodies, and allows us to model all sorts of physical connections between bodies such as ropes, doors, character joints, and more.

Because the two bodies are still simulated independently, A constraint (`PhysicsConstraint`) definition includes transforms from the local space of each body to the pivot position/orientation of the constraint on that body. Together these are known as the "constraint space". During simulation, constraints will act on the two bodies to maintain the pivot position/orientation across the two constrained bodies. For example, a ball-and-socket constraint will apply forces to the bodies so that the pivots point positions (defined respectively to each body's local space) will coincide. Likewise, a hinge constraint will also maintain the common rotation axis.

![Constraint Space](/img/how_to/physics/constraintbasics.png)

In rigid body dynamics, each body has 6 degrees of freedom: 3 translational degrees of freedom, and 3 rotational degrees of freedom. A constraint definition includes limitations on one or more of these degrees of freedom for its constrained bodies. Different types of constraints are generally defined by the number and type of these limitations. For example, in a ball-and-socket constraint, the constrained objects have no linear freedom relative to each other in any direction as they are attached together at the point, but are completely free to rotate around the constraint pivot point. In a hinge constraint, the objects no linear freedom and also have restricted relative orientation. In addition, limits can be provided for each degree of freedom. For example, limiting the distance rotation of a hinge constraint allows you for example to create a door that will not rotate beyond a given angle.

![Constraint Linear Limits](/img/how_to/physics/constraintlimitslinear.png)

![Constraint Angular Limits](/img/how_to/physics/constraintlimitsangular.png)

## Constraint Types

Babylon supports several constraint types; the most generic of which is the "6 DoF," which allows control over each degree of freedom individually. In addition to the 6 DoF, Babylon also provides several helper types for common constraints. Many of these constraints are specializations of the 6 DoF, but they don't require you to specify the full constraint space, which can make initialization easier in those cases.

| Enum | Name | Notes |
| --- | --- | --- |
| LOCK | Lock | ![Locked](/img/how_to/physics/locked.jpg) A locked joint attempts to keep the two constraint spaces completely lined up, allowing no relative movement. |
| BALL_AND_SOCKET  | Ball and socket| ![Ball and Socket](/img/how_to/physics/ballnsocket.jpg) A ball and socket joint attempts to line up the pivot *positions* but puts no restrictions on the relative rotation of the two bodies. |
| DISTANCE | Distance | ![Distance](/img/how_to/physics/distance.jpg) A distance joint attempts to keep the positions of the constraint spaces within a specified distance and provides no restriction on relative rotation. |
| HINGE | Hinge | ![Hinge](/img/how_to/physics/hinge.jpg) A hinge will keep the positions of the constraint spaces aligned as well as two of the angular axes, only allowing relative rotation around one axis. |
| PRISMATIC | Prismatic | ![Prismatic](/img/how_to/physics/prismatic.jpg) A prismatic joint allows the constraint spaces to translate along one axis and allows no relative rotation of the two spaces. |
| SLIDER | Slider | ![Slider](/img/how_to/physics/slider.jpg) Similar to the prismatic joint, but also allows the bodies to rotate around the translation axis. |
| SIX_DOF | 6 Degrees Of Freedom | <figure> <img src="/img/features/physics/6DOF.svg" alt="Image representing 6 Degrees of Freedom"/> <figcaption>6 degrees of freedom: three translational and three rotational axes. By GregorDS - Own work, CC BY-SA 4.0, https://commons.wikimedia.org/w/index.php?curid=38429678</figcaption> </figure> The most generic type. Does not provide any restrictions by default, so the limits can be applied as you choose. |

## How to use it

```javascript
const bodyA = new BABYLON.PhysicsBody(objectA, BABYLON.PhysicsMotionType.DYNAMIC, scene);
const bodyB = new BABYLON.PhysicsBody(objectB, BABYLON.PhysicsMotionType.DYNAMIC, scene);

const constraint = new BABYLON.DistanceConstraint(
  10, // max distance between the two bodies
  scene
);

bodyA.addConstraint(bodyB, constraint);
```

If one or both bodies are instanced, you need to specify the instance to which the constraint applies:

```javascript
// This will add a constraint between the instance in index 3 of body A, and the instance in index 2 of body B
bodyA.addConstraint(bodyB, constraint, 3, 2);
// The constraint can also be between two instances in the same body
bodyA.addConstraint(bodyA, constraint, 4, 7); 
```

For the 6DOF (6 Degrees of Freedom) constraint, you should pass an array with entries specifying the translational and rotational axis that have min and max limits:

```javascript
// This will constraint the bodies to mantain a distance of at least 1 and at most 2, and to rotate at most 1.58 rad along the perpendicular axis
let constraint = new BABYLON.Physics6DoFConstraint({
    pivotA: new BABYLON.Vector3(0, -0.5, 0),
    pivotB: new BABYLON.Vector3(0, 0.5, 0),
    perpAxisA: new BABYLON.Vector3(1, 0, 0),
    perpAxisB: new BABYLON.Vector3(1, 0, 0),
}, [
    {axis: BABYLON.PhysicsConstraintAxis.LINEAR_DISTANCE, minLimit: 1, maxLimit: 2},
    {axis: BABYLON.PhysicsConstraintAxis.ANGULAR_Y, minLimit: 0, maxLimit: 1.58}
], scene);
```
## Debug visualization

Physics viewer allows to display angular and linear limits of constraints.
Following example adds and immediately removes a constraint from debug visualization.

```javascript
physicsViewer = new BABYLON.Debug.PhysicsViewer(scene, visualizationSizeFactor);
let joint = new BABYLON.HingeConstraint(
    new BABYLON.Vector3(0, 0, -0.5),
    new BABYLON.Vector3(0, 0, 0.5),
    undefined,
    undefined,
    scene
);
agg1.body.addConstraint(agg2.body, joint);
  
physicsViewer.showConstraint(joint);
physicsViewer.hideConstraint(joint);
```

Because of performance, limit debug mesh is not recreated when constraints change. User is responsible for removing and adding the constraint if any limit is changed.

<Playground id="#RMF5CJ#38" title="Constraint Debug view" description="Edit angular and linear limits of a constraint" isMain={true} category="Physics"/>
<Playground id="#7DMWP8#693" title="Constraints limits" description="View limits for different type of constraints" isMain={true} category="Physics"/>

## Best practices

A problem that's very noticeable to users of your application is when a third body comes between the constraint spaces of a pair of constrained bodies, resulting in visual penetration, as seen in the picture below.

![Ragdoll bone gap](/img/how_to/physics/ragdollbonegap.jpg)

This can look very unnatural and, in addition, cause jitter between the constrained bodies, as the collision detection will "fight" against the constraint. Overlapping the constrained bodies greatly helps to avoid situations like this.

![Ragdoll with overlapping bones](/img/how_to/physics/ragdolloverlappedbones.jpg)

Even when the constraint is not attempting to force the bodies into an overlapping position, most use-cases for constraints still attempt to position the bodies very close to each other. To avoid the collision detection from "fighting" the constraint resolution, by default, we disable collisions between each pair of constrained bodies. If you *do* want the bodies to collide, however, this can be controlled by `PhysicsConstraint.isCollisionsEnabled`.

When simulating a long chain of constrained bodies, not all of the constraints might be solved perfectly by the physics engine, which can result in stretching or misalignment of the constraint - this is more likely to happen if the mass ratio between two constrained bodies is very high. A common approach to mitigate this is to tweak the mass ratios of the constrained bodies - increase the mass and inertia of bodies which are closer to the "root" of the chain and decrease as the bodies are further from the root. e.g. if you have a ragdoll, ensure that the torso has the most mass and decrease the mass as you move down the limbs of the ragdoll.


## Examples

<Playground id="#7DMWP8" title="Constraints" description="Shows all the different constraints available" isMain={true} category="Physics"/>

<Playground id="#NAMYYQ#2" title="Swinging pendulums" description="Example of using the Distance Constraint to model a pendulum" isMain={true} category="Physics"/>

<Playground id="#RMF5CJ" title="6 DoF Joint Tool" description="Simple tool for experimenting with commonly used Physics6DoFConstraint parameters" isMain={true} category="Physics"/>

<Playground id="#5KKGOT#1" title="Motor Constraints" description="Example of Motor Constraints targeting velocity and position" isMain={true} category="Physics"/>


# Physics Aggregate

## What is an Aggregate

The Physics Aggregate is an object that contains a Body and a Shape. It's a helper that allows creating all the objects necessary to physicalize your scene in just one call. In that sense, it's similar to Physics V1 Impostors, but with more control. Once created, you can easily get the individual parts and tweak them.

## How to use it

```javascript
const sphere = BABYLON.Mesh.CreateSphere("sphere", 16, 2, scene);
const aggregate = new BABYLON.PhysicsAggregate(sphere, BABYLON.PhysicsShapeType.SPHERE, { mass: 1 }, scene);
```

This is very similar to the Physics V1 Impostor.
At aggregate creation, a body and a shape are instantiated all at once. However, recreating shapes is not the most performant choice. You can alternatively pass the shape instead of the PhysicsShapeType, and the aggregate will reuse that shape:

```javascript
const sphere = BABYLON.Mesh.CreateSphere("sphere", 16, 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#1" 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 will dispose of the body and shape that were created by it, in case the shape was created by the aggregate. If the shape was passed as a parameter, then it will not be disposed, as it could still be in use by another body.
