
# 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

A character controller is a specialized component designed to manage the movement and interactions of a character within a game world. Conceptually, it resides between the game/experiment code and the physics engine.

## Creating a Controller

Users can either create and provide a physics shape to the controller or let it create a capsule by providing its dimensions.

```javascript
let h = 1.8;
let r = 0.6;
let displayCapsule = BABYLON.MeshBuilder.CreateCapsule("CharacterDisplay", { height: h, radius: r }, scene);
let characterPosition = new BABYLON.Vector3(3, 0.3, -8);
let characterController = new BABYLON.PhysicsCharacterController(characterPosition, { capsuleHeight: h, capsuleRadius: r }, scene);
```

## moveWithCollisions

`moveWithCollisions` is a synchronous function that moves the character to the target position while taking care of collisions along the way.

<Playground id="WO0H1U#165" title="Character Controller moveWithCollisions" description="Character Controller moveWithCollisions" />

## Kinematic platforms

Physics bodies of `PhysicsMotionType.ANIMATED` can interact with the character. This allows the creation of lifts, platforms, and more.

<Playground id="WO0H1U#166" title="Character Controller animated platform" description="Character Controller animated platform" />

## Observable

The custom collision observable lets you get collision information specific to the character controller.

```javascript
characterController.onTriggerCollisionObservable.add((event)=>{
    console.log(`Character collision : ${event.collider.transformNode.name} at ${event.impulsePosition.toString()} `);
});
```
Here, the event type is `ICharacterControllerCollisionEvent` and it contains information about the collider, position, and impulse.

<Playground id="WO0H1U#169" title="Character Controller collision observer" description="Character Controller collision observer" />

## The loop

There are 3 major steps:

- Getting the support: on what surface the character is
- Setting the desired velocity: what the character's velocity is based on its properties and state
- Tick update on the controller

Then, it's possible to get the character position using `characterController.getPosition()` and set a skinned mesh position, for example.

In the following example, velocity is a function of the character state. That state can be `START_JUMP`, `IN_AIR`, or `ON_GROUND`. These different steps allow for different behaviors and movement speeds.
Depending on user needs, it's possible to have speed and velocity control for swimming, for example.

The main loop can be summarized with these calls:

```javascript
const support = characterController.checkSupport(dt, down);
const desiredLinearVelocity = getDesiredVelocity(dt, support, characterCurrentOrientation, characterCurrentVelocity);
characterController.setVelocity(desiredLinearVelocity);
characterController.integrate(dt, support, characterGravity);
const newPosition = characterController.getPosition();
```

The test room PG provides an example to compute the desired velocity based on a finite state.

<Playground id="WO0H1U#13" title="Character Controller testing room" description="Character Controller testing room" />



## 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" />



## 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 act on the two bodies to maintain the pivot position/orientation across the two constrained bodies. For example, a ball-and-socket constraint applies forces to the bodies so that the pivot point positions (defined in each body's local space) coincide. Likewise, a hinge constraint also maintains the common rotation axis.

![Constraint Space](/img/how_to/physics/constraintbasics.webp)

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 because they are attached together at a point, but they are completely free to rotate around the constraint pivot point. In a hinge constraint, the objects have no linear freedom and also have restricted relative orientation. In addition, limits can be provided for each degree of freedom. For example, limiting the rotation of a hinge constraint allows you to create a door that will not rotate beyond a given angle.

![Constraint Linear Limits](/img/how_to/physics/constraintlimitslinear.webp)

![Constraint Angular Limits](/img/how_to/physics/constraintlimitsangular.webp)

## 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.webp) 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.webp) 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.webp) 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.webp) 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.webp) 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.webp) 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 constrain the bodies to maintain 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);
```

When creating a constraint, if `axisA` or `axisB` is not set, a default value of `(1, 0, 0)` is used.

## Debug visualization

The physics viewer allows you to display the angular and linear limits of constraints.
The 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);
```

For performance reasons, the limit debug mesh is not recreated when constraints change. The user is responsible for removing and re-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.webp)

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.webp)

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 way to mitigate this is to tweak the mass ratios of the constrained bodies: increase the mass and inertia of bodies that are closer to the "root" of the chain, and decrease them as the bodies get farther from the root. For example, if you have a ragdoll, ensure that the torso has the most mass and decrease the mass as you move down the limbs.


## 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"/>


## How to use it

Neither forces nor impulses have any effect on bodies whose mass is 0.

```javascript
body.applyForce(
    new BABYLON.Vector3(0, 10, 0), // direction and magnitude of the applied force
    new BABYLON.Vector3(0, 0, 0) // point in WORLD space where the force will be applied    
);

// .... OR .....

body.applyImpulse(
    new BABYLON.Vector3(0, 10, 0), // direction and magnitude of the applied impulse
    new BABYLON.Vector3(0, 0, 0) // point in WORLD space where the impulse will be applied    
);
```

As a reminder, if a body's transform node contains Thin Instances, you can choose which instance to apply the force/impulse to by passing `instanceIndex` as a parameter:

```javascript
// Apply a force to the first instance ONLY
body.applyForce(new BABYLON.Vector3(100, 0, 0), new BABYLON.Vector3(0, 0, 0), 0); 
```

If no index is provided, the force/impulse is applied to all instances.

## Difference between a force and an impulse

A force is a continuous effect that is applied to an object over time, which can change the object's velocity or direction of motion. For example, a force could be used to simulate gravity, wind resistance, or a player pushing an object.

An impulse, on the other hand, is a sudden, instantaneous effect that changes the velocity of an object. It is a specific amount of force applied over a very short duration of time, often modeled as a single frame in a game. For example, a collision between two objects might generate an impulse that changes the direction and speed of both objects.

In summary, a force is a *continuous* effect over time, while an impulse is a sudden, *instantaneous* effect that changes the velocity of an object. Click on the sphere in the following examples to experiment with forces and impulses.

<Playground id="#R66K4K#1" title="applyForce" description="An example of using applyForce" category="Physics"/>

<Playground id="#Z8HTUN#677" title="applyImpulse" description="An example of using applyImpulse" category="Physics"/>



## Physics Helper

The helper assists you with creating some phenomena like radial explosions or vortices.

```javascript
var physicsHelper = new BABYLON.PhysicsHelper(scene);

var origin = BABYLON.Vector3(0, 0, 0);
var radius = 10;
var strength = 20;
var falloff = BABYLON.PhysicsRadialImpulseFalloff.Linear; // or BABYLON.PhysicsRadialImpulseFalloff.Constant

var explosionEvent = physicsHelper.applyRadialExplosionImpulse( // or .applyRadialExplosionForce
    origin,
    radius,
    strength,
    falloff
);
// the second `radius` argument can also act as options: `.applyRadialExplosionImpulse(origin, { radius: radius, strength: strength, falloff: falloff })`

// or

var gravitationalFieldEvent = physicsHelper.gravitationalField(
    origin,
    radius,
    strength,
    falloff
);
// the second `radius` argument can also act as options: `.gravitationalField(origin, { radius: radius, strength: strength, falloff: falloff })`
gravitationalFieldEvent.enable(); // call this if you want to activate the gravitational field
setTimeout(() => gravitationalFieldEvent.disable(), 3000);

// or

var updraftEvent = physicsHelper.updraft(
    origin,
    radius,
    strength,
    height,
    BABYLON.PhysicsUpdraftMode.Center // or BABYLON.PhysicsUpdraftMode.Perpendicular
);
// the second `radius` argument can also act as options: `.updraft(origin, { radius: radius, strength: strength, height: height, updraftMode: PhysicsUpdraftMode.Center })`
updraftEvent.enable();
setTimeout(() => updraftEvent.disable(), 5000);

// or

var vortexEvent = physicsHelper.vortex(
    origin,
    radius,
    strength,
    height
);
// the second `radius` argument can also act as options: `.vortex(origin, { radius: radius, strength: strength, height: height, centripetalForceThreshold: 0.7, centripetalForceMultiplier: 5, centrifugalForceMultiplier: 0.5, updraftForceMultiplier: 0.02 })`
vortexEvent.enable();
setTimeout(() => vortexEvent.disable(), 5000);
```

*For a more detailed explanation, please take a look at the playground example below.*

<Playground id="#E5URLZ#20" title="Physics helpers" description="Show how to use physics helpers and add various effects with forces" isMain={true} category="Physics"/>


# Using Havok and the Havok Plugin

## Havok and Babylon.js

The Havok integration in Babylon.js consists of two different modules that work together.
The first is the Havok engine itself, which is a WebAssembly module that is responsible for the actual physics calculations.
The second is the Babylon Havok plugin, which is responsible for the integration of the Havok physics engine into Babylon.js.

## The Havok physics engine

_To read about the Babylon plugin directly, [skip to the next section](#the-babylon-havok-plugin)._

Havok is now available for the web, using a WebAssembly version of the engine. It is available free to use under the MIT license.
The engine is available both as [the npm package](https://www.npmjs.com/package/@babylonjs/havok) `@babylonjs/havok` and on our CDN under the URLs `https://cdn.babylonjs.com/havok/HavokPhysics_umd.js` or `https://cdn.babylonjs.com/havok/HavokPhysics_es.js` when using the `module` script.
Please note that it requires WebAssembly SIMD, which is not supported on iOS < 16.4.

<Alert severity="warning" title="Warning" description="The CDN should not be used in production environments. The purpose of our CDN is to serve Babylon packages to users learning how to use the platform or running small experiments. Once you've built an application and are ready to share it with the world at large, you should serve all packages from your own CDN."/>

The NPM package contains the same two flavors as the CDN: an ES modules version and a UMD version for CommonJS and AMD projects. Your bundler will select the right file for you.

The engine requires initialization before it can be used in Babylon.js. This is done by calling the function returned by the package or the online version. This function initializes the wasm file and returns an object that can be used to initialize Babylon's Havok plugin.

### Using the npm package

To use the npm package, install the Havok package in your project:

```bash
npm install @babylonjs/havok
```

Then, import the package and call the function returned by the package:

```javascript
import HavokPhysics from "@babylonjs/havok";

async function getInitializedHavok() {
  return await HavokPhysics();
}
```

A different way to use the imported package would be to call the function returned by the package directly:

```javascript
import HavokPhysics from "@babylonjs/havok";
let initializedHavok;

HavokPhysics().then((havok) => {
  initializedHavok = havok;
});
```

### Using the CDN

The main difference between the CDN and the npm package is the way the HavokPhysics object becomes available in your browser.
Whereas using npm you need to import/require the package, using the CDN you get the object directly from the global scope.

<Alert severity="warning" title="Warning" description="The CDN should not be used in production environments. The purpose of our CDN is to serve Babylon packages to users learning how to use the platform or running small experiments. Once you've built an application and are ready to share it with the world at large, you should serve all packages from your own CDN."/>

```html
<script src="https://cdn.babylonjs.com/havok/HavokPhysics_umd.js"></script>
<script>
  // before initializing your babylon scene:
  let havokInstance;
  HavokPhysics().then((havok) => {
    // Havok is now available
    havokInstance = havok;
  });

  // later in code you can use havokInstance to initialize the plugin
</script>
```

A way to use the CDN without polluting the global scope is to use the `module` script:

```html
<script type="module">
  import HavokPhysics from "https://cdn.babylonjs.com/havok/HavokPhysics_es.js";
  let havokInstance;
  HavokPhysics().then((havok) => {
    // Havok is now available
    havokInstance = havok;
  });

  // later in code you can use havokInstance to initialize the plugin
</script>
```

## The Babylon Havok plugin

When the Havok instance is created and available, you can use it to initialize the Babylon Havok plugin.

An example of initializing the plugin:

```javascript
// Assuming HavokPhysics is available, whether by importing or by using the CDN

async function createScene() {
  // generate your scene, do your magic!

  // initialize the plugin using the HavokPlugin constructor
  const havokInstance = await HavokPhysics();
  const havokPlugin = new BABYLON.HavokPlugin(true, havokInstance);
}
```

You are now ready to use the Havok plugin in your Babylon.js scene.

### The HK global variable

To simplify the initialization process of the plugin, the Havok plugin will look in the `HK` global variable for an initialized Havok instance. If it is available, it will use it to initialize the plugin. If it is not available, it will use the Havok instance passed to the constructor.

This code will work (assuming the UMD version was loaded in the browser):

```javascript
globalThis.HK = await HavokPhysics();
```

This is the way we are using Havok in our playgrounds.
However, **the recommended way** for a project you fully control is not to pollute the global namespace and to **pass the Havok instance to the plugin**.

### Example using npm

A working example using NPM and ES modules can be found in the [Babylon.js template repository](https://github.com/RaananW/babylonjs-webpack-es6/blob/master/src/scenes/physicsWithHavok.ts).
Note that engine initialization happens in a different file (https://github.com/RaananW/babylonjs-webpack-es6/blob/master/src/externals/havok.ts), but it is nonetheless the same architecture.

### Full in-browser example using the UMD version

```html
<!DOCTYPE html>
<html>
  <head>
    <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />

    <title>Babylon.js using Havok</title>

    
    <script src="https://cdn.babylonjs.com/havok/HavokPhysics_umd.js"></script>
    <script src="https://cdn.babylonjs.com/babylon.js"></script>
    <script src="https://cdn.babylonjs.com/gui/babylon.gui.min.js"></script>

    <style>
      html,
      body {
        overflow: hidden;
        width: 100%;
        height: 100%;
        margin: 0;
        padding: 0;
      }

      #renderCanvas {
        width: 100%;
        height: 100%;
        touch-action: none;
      }

      #canvasZone {
        width: 100%;
        height: 100%;
      }
    </style>
  </head>
  <body>
    <div id="canvasZone"><canvas id="renderCanvas"></canvas></div>
    <script>
      const canvas = document.getElementById("renderCanvas");
      const engine = new BABYLON.Engine(canvas, true, { preserveDrawingBuffer: true, stencil: true, disableWebGL2Support: false });
      const createScene = async function () {
        // This creates a basic Babylon Scene object (non-mesh)
        const scene = new BABYLON.Scene(engine);

        // This creates and positions a free camera (non-mesh)
        const camera = new BABYLON.FreeCamera("camera1", new BABYLON.Vector3(0, 5, -10), scene);

        // This targets the camera to scene origin
        camera.setTarget(BABYLON.Vector3.Zero());

        // This attaches the camera to the canvas
        camera.attachControl(canvas, true);

        // This creates a light, aiming 0,1,0 - to the sky (non-mesh)
        const light = new BABYLON.HemisphericLight("light", new BABYLON.Vector3(0, 1, 0), scene);

        // Default intensity is 1. Let's dim the light a small amount
        light.intensity = 0.7;

        // Our built-in 'sphere' shape.
        const sphere = BABYLON.MeshBuilder.CreateSphere("sphere", { diameter: 2, segments: 32 }, scene);

        // Move the sphere upward at 4 units
        sphere.position.y = 4;

        // Our built-in 'ground' shape.
        const ground = BABYLON.MeshBuilder.CreateGround("ground", { width: 10, height: 10 }, scene);

        // initialize plugin
        const havokInstance = await HavokPhysics();
        // pass the engine to the plugin
        const hk = new BABYLON.HavokPlugin(true, havokInstance);
        // enable physics in the scene with a gravity
        scene.enablePhysics(new BABYLON.Vector3(0, -9.8, 0), hk);

        // Create a sphere shape and the associated body. Size will be determined automatically.
        const sphereAggregate = new BABYLON.PhysicsAggregate(sphere, BABYLON.PhysicsShapeType.SPHERE, { mass: 1, restitution: 0.75 }, scene);

        // Create a static box shape.
        const groundAggregate = new BABYLON.PhysicsAggregate(ground, BABYLON.PhysicsShapeType.BOX, { mass: 0 }, scene);

        return scene;
      };

      createScene().then((scene) => {
        engine.runRenderLoop(function () {
          if (scene) {
            scene.render();
          }
        });
      });
      // Resize
      window.addEventListener("resize", function () {
        engine.resize();
      });
    </script>
  </body>
</html>
```


# Migrate from Physics V1

Babylon 6.0 brought a new physics architecture, which aims to provide functionality closer to what most existing physics engines provide. However, it also includes some extra classes to make this migration easier. Here, we show two ways to migrate your existing V1 scene to V2:

## Option 1: Using Aggregates

[Aggregates](/features/featuresDeepDive/physics/aggregates) work very similarly to the V1 Physics Impostors, creating all necessary objects automatically based on the parameters. So, if you have this code in V1:

```javascript
const sphere = BABYLON.MeshBuilder.CreateSphere("sphere", { diameter: 2, segments: 32 }, scene);
const impostor = new BABYLON.PhysicsImpostor(sphere, BABYLON.PhysicsImpostor.SphereImpostor, { mass: 1, friction: 0.2, restitution: 0.3 }, scene);
```

You only need to change it to:

```javascript
const sphere = BABYLON.MeshBuilder.CreateSphere("sphere", { diameter: 2, segments: 32 }, scene);
const aggregate = new BABYLON.PhysicsAggregate(sphere, BABYLON.PhysicsShapeType.SPHERE, { mass: 1, friction: 0.2, restitution: 0.3 }, scene);
```

Note we switched the constructor from `PhysicsImpostor` to `PhysicsAggregate`, and the second parameter (the type of the physical shape) from `BABYLON.PhysicsImpostor.SphereImpostor` to `BABYLON.PhysicsShapeType.SPHERE`. [Here are the available types of shapes](/features/featuresDeepDive/physics/rigidBodies#shape).

## Option 2: No Aggregates

One of the most important new features in the new architecture is the ability to fine-tune collision shapes and reuse them, improving memory usage and customizability. So it is also possible to create bodies and shapes separately:

```javascript
const sphere = BABYLON.MeshBuilder.CreateSphere("sphere", { diameter: 2, segments: 32 }, scene);
const impostor = new BABYLON.PhysicsImpostor(sphere, BABYLON.PhysicsImpostor.SphereImpostor, { mass: 1, friction: 0.2, restitution: 0.3 }, scene);
```

Would become:

```javascript
const sphere = BABYLON.MeshBuilder.CreateSphere("sphere", { diameter: 2, segments: 32 }, scene);
const sphereShape = new BABYLON.PhysicsShapeSphere(new BABYLON.Vector3(0, 0, 0), 1, scene);
const sphereBody = new BABYLON.PhysicsBody(sphere, BABYLON.PhysicsMotionType.DYNAMIC, false, scene);
sphereShape.material = { friction: 0.2, restitution: 0.3 };
sphereBody.shape = sphereShape;
sphereBody.setMassProperties({ mass: 1 });
```

The advantage of this approach is that, if you have another mesh you want to use with the same collider shape and material, you can reuse the shape:

```javascript
const complexModel = await BABYLON.ImportMeshAsync(...);
const body = new BABYLON.PhysicsBody(complexModel, BABYLON.PhysicsMotionType.DYNAMIC, false, scene);
body.shape = sphereShape;
body.setMassProperties({mass: complexModelMass});
```

<Playground id="#Q6TJRN#7" title="Shapes test" description="Use all available shapes with or without aggregates."/>



# Performance Tips

## ♻️ Reduce, Reuse, Recycle ♻️

The main point to take advantage of when using the API is to reuse as many objects as possible. For example, if you have a bowling game, instead of disposing of and recreating your ball and pins on every shot, you could keep the same objects and just reset their positions to the "default" state. By default, when you change the properties of the node associated with a body, there will be no effect. That is because the pre-step that updates the physics body with the values from the transform node is disabled by default to improve performance. You can solve this by enabling the pre-step for a frame and then disabling it again on the next frame:

```javascript
body.disablePreStep = false;
// The position where you want to move the body to
body.transformNode.position.set(1, 2, 3);
scene.onAfterRenderObservable.addOnce(() => {
    // Turn disablePreStep on again for maximum performance
    body.disablePreStep = true;
})
```

Please note that doing so may or may not allow the body to enter sleep mode, depending on the physics engine.

The reuse part also applies to collision shapes. Since bowling pins have the same shape, you can create only one PhysicsShape for all of them.

## Use simpler shapes

Whenever possible, don't use the entire mesh as a collision shape, especially when it's a very high poly mesh. Try to use [compounds](/features/featuresDeepDive/physics/compounds) or [convex hull shapes](/features/featuresDeepDive/physics/shapes) instead.

## Keep collision observables simple

[Collision observables](/features/featuresDeepDive/physics/collisionEvents) are functions that run every time a body collides with another. Since this can happen as often as every frame, it's important to avoid complex computations, or else the simulation will have to wait for these observables to finish before continuing.

<Playground id="#PX6E6C#25" title="Stress test" description="Instantiate many bodies to test the Physics engine performance" isMain={true} category="Physics"/>

<Playground id="#W3YL7Z#1" title="Convex Hull Vs Mesh Test" description="Compare Convex hull and Mesh shapes"/>



## What is it

The prestep is the process that happens just before a physics tick. It consists of updating the position and orientation of physics entities from the scene transform node state. This process can be costly and is disabled by default.
It can be enabled manually and, when enabled, two modes exist: teleport mode and action mode. Teleport mode causes the body to have limited interaction with shapes in contact, whereas action mode makes the body effectively move through the world and interact with shapes in contact.
Teleport mode is better suited for placing objects with a Gizmo, for example. Action mode is better suited for in-game use.

## How to use

There are 2 ways to enable prestep. The first is to use the `disablePreStep` boolean. When it is set to true, it enables Teleport mode.

```javascript
aggregate.body.disablePreStep = false;
```

The second allows finer control.

```javascript
aggregate.body.setPrestepType(PhysicsPrestepType.ACTION);
```

Depending on the Motion Type applied, prestep makes the body behave differently.
For Static motion, this will have no influence.

The following Playground shows 2 types of Prestep with the 3 types of Motion.
<Playground id="E9R16H#1" title="Prestep and Motion example" description="Prestep and Motion example" />
           
## Performance

As stated in Perf Tips, it can be costly to enable prestep for all physics bodies. 


# Ragdolls

## Defining a ragdoll

A ragdoll is a physicalized system that controls a skeleton and its skinned mesh. That system is composed of shapes for collision detection and constraints between those shapes.
A shape can be used for multiple bones and is large enough to contain the skinned geometry deformed by those bones.
Defining a ragdoll consists of listing each physics shape in the system, which bone it is controlling, and some properties such as shape size and rotation axis constraints.
The current implementation does not allow automatic size computation.

```javascript
const config = [
            { bones: ["root"], size: 0.6, boxOffset: 0.1 },
            // Arms.
            {
                bones: ["arm_r", "arm_l"],
                depth: 0.3,
                size: 0.3,
                width: 0.6,
                rotationAxis: BABYLON.Axis.Z,
                min: -1,
                max: 1,
                boxOffset: 0.3,
                boneOffsetAxis: BABYLON.Axis.X
            }
            ...
```

In this example, 3 shapes are created: 1 for the root bone and 2 for arm_r and arm_l. Because the properties for the arms are the same due to symmetry, there is no need to set 2 entries in the configuration.
`size` property is used if `depth`, `width` or `height` are not set. 
`rotationAxis` defines the axis whose angles will be constrained. `min` and `max` define those limits.
`boneOffsetAxis` sets the axis used to offset the shape. `boxOffset` is the world-size value used to shift the shape along that axis. By default, physics shapes are centered on the bone.
This offset allows one side of the shape to sit on the bone.

```javascript
const ragdoll = new BABYLON.Ragdoll(skeleton, newMeshes[0], config);
```

The next step is to create the ragdoll instance. This is done in one line, and the user must provide the skeleton, the skinned mesh, and the configuration.
Once instantiated, the ragdoll is in Kinematic mode: physicalized bones can interact with other physics bodies, but the animation drives the physics.

At any point after that, to make the ragdoll update dynamically, call:

```javascript
ragdoll.ragdoll();
```

Dispose the ragdoll to stop it.

## Interactions

Get the aggregate associated with a bone with the `getAggregate` function. The returned aggregate works like any other aggregate: it is possible to get the shape or body and apply an impulse.

```javascript
ragdoll.getAggregate(0)?.body.applyImpulse(new BABYLON.Vector3(200,200,200), BABYLON.Vector3.ZeroReadOnly);
```
## Interactions

A few steps are needed to physicalize a bone:

```javascript
// attach sphere to a bone
sph.attachToBone(scene.getBoneByName("bone52"), result.meshes[0]);
// physics sphere is moved to a target (and not teleported) 
boxAggregate2.body.setPrestepType(BABYLON.PhysicsPrestepType.ACTION);
// no feedback from physics to transform
boxAggregate2.body.disableSync = true;
```

<Playground id="#HLZE74#0" title="Physicalized bone" description="Playground that loads an animated character and physicalize one bone" category="Physics"/>

## Limitations

Imported glTF/GLB files only work as ragdolls in right-handed scenes. In left-handed scenes, an intermediate transform node is added at the root to perform the handedness conversion described in [Coordinate Systems and Handedness](/features/featuresDeepDive/mesh/transforms/coordinateSystems#loading-gltf-in-babylonjs).
This intermediate transform is not supported by the ragdoll physics-to-bone conversion.

<Playground id="#V6FLZP#1" title="Bunny ragdoll" description="Ragdoll sample using a bunny plush" isMain={true} category="Physics"/>

<Playground id="#DLPNQT#0" title="Animated character" description="Ragdoll with an animated character and the ability to apply impulse" isMain={true} category="Physics"/>



## What is Raycast

In a collision detection scenario, a raycast can be used to determine whether a line of sight exists between two objects or whether a collision is imminent. By casting a ray from one object to another, the physics engine can determine whether the ray intersects with any other objects in its path, allowing the game to determine whether the two objects can "see" each other or whether a collision has occurred.

## How to use it

Here is an example of a raycast:

```javascript
var raycastResult = new BABYLON.PhysicsRaycastResult();
var start = new BABYLON.Vector3(1, 20, 2);
var end = new BABYLON.Vector3(1, -20, 2);
physicsEngine.raycastToRef(start, end, raycastResult);
if (raycastResult.hasHit) {
    console.log("Collision at ", raycastResult.hitPointWorld);
}
```

The important thing to note here is that `raycastResult` can (and should!) be reused between calls. This is the main difference from Physics V1 raycasting.

The result object has some information about the properties of the intersection, such as the intersection point, the body that was hit, and the index of the triangle hit in case it hit a Mesh Shape. You can find all the fields in the [PhysicsRaycastResult](/api/classes/BABYLON.PhysicsRaycastResult) class.

<Playground id="#I6AR8X" title="RayPicking Vs Raycast" description="Compare Raypicking with raycast feature of the Physics Engine" isMain={true} category="Physics"/>

## Raycast queries

You can use raycast queries to make the raycast test for specific objects only. The test utilizes the `membership` and `collideWith` fields, as follows:

```javascript
bool doesCollide = (ray.membership & shape.collideWith) && (shape.membership & ray.collideWith)
```

Where `&` represents the [bitwise AND](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Expressions_and_operators#bitwise_operators) operation and `&&` the [logical AND](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Expressions_and_operators#logical_operators). By default, if not specified, the values for both the `membership` and `collideWith` fields are `0xffffffff`, which is the identity for the bitwise operation.

```javascript
var shapeA = new PhysicsShape(...);
var shapeB = new PhysicsShape(...);

shapeA.filterMembershipMask = 1; // 01 in binary
shapeB.filterMembershipMask = 2; // 10 in binary

/**
 *  EXAMPLE 1: will test only for shape A 
 */
physicsEngine.raycastToRef(start, end, raycastResult, {collideWith: 1});

/**
 *  EXAMPLE 2: will test only for shape B 
 */
physicsEngine.raycastToRef(start, end, raycastResult, {collideWith: 2});

/**
 *  EXAMPLE 3: will test for shape A AND shape B (as 3 is 11 in binary)
 */
physicsEngine.raycastToRef(start, end, raycastResult, {collideWith: 3});
```

Here's a diagram of the operation for the second example's test on shapeA (which does not collide with the ray):

![Diagram of the ray collision test](/img/features/physics/raycast_diagram.webp)

<Playground id="#PY59V9#7" title="Raycast Filtering Example" description="Example of the raycast filtering feature" isMain={true} category="Physics" />



## Core concepts

A physics engine enables a game engine to simulate how real-world objects would behave. This means objects will fall down due to gravity, collide and bounce off each other. The simulation used by Havok is sometimes called a *rigid body* simulation, which is simply a term which means objects which don't change shape due to squashing or stretching.

The most basic object in the physics engine is a body (`PhysicsBody`), which can be associated with a `TransformNode`. A body represents an object in the simulation. The simulation processes all bodies, attempts to make them behave in a physically realistic manner, and then updates the `TransformNode` to match the position of the simulated body. One obvious example is collision detection, which prevents bodies from intersecting. For a pair of bodies to detect collisions, each body needs a shape. However, collision detection can require a lot of calculations, so rather than using an object's visual meshes, the `PhysicsBody` uses a shape (`PhysicsShape`) that is usually simpler than the render meshes and enables the engine to minimize the amount of calculation needed to simulate the world. Shapes are described in more detail in a [future chapter](/features/featuresDeepDive/physics/shapes).

Bodies and shapes have properties that approximate how they behave in the real world. Bodies have mass distributions and velocities. Velocity is the speed at which a body is moving, while the mass distribution describes how that velocity changes when two bodies interact. Shapes themselves are geometric objects used to detect when bodies are colliding with each other. These shapes also have material properties (`PhysicsMaterial`) such as friction and restitution, which describe how a collision affects bodies when sliding and bouncing, as well as density, which can be used to calculate mass properties.

The final important object is a constraint (`PhysicsConstraint`) which allows you to link two bodies together in some manner. Two bodies linked together by a constraint still behave like independent bodies, but their movement is restricted by the constraint. A common example of a constraint is a door hinge, which allows one of the bodies to rotate around the hinge axis. Constraints are covered in more detail in a [future chapter](/features/featuresDeepDive/physics/constraints).


## Body

A physics body is a virtual object that represents a physical object in a simulation, with properties like mass, position, and velocity. When you interact with the physics engine, you'll usually be working with bodies. The first thing you need to consider is a body's *motion type*.

### Motion type

There are three motion types (`PhysicsMotionType`) that a body can have.

Static bodies are bodies which never move. Use this motion type for your terrain or any kind of object which should not move, but should still affect other bodies in the engine.

Dynamic bodies, on the other hand, are bodies which *can* move. You can apply forces to these bodies and change their velocities yourself. When stepping the physics engine, the velocity of a body will be taken into account when resolving collisions and constraints and, when the simulation step is complete, the position of the body will be updated.

The final motion type is *animated* - bodies with this motion type are similar to dynamic bodies; you can change their velocities and the physics engine will update the body positions. However, the difference is that bodies with an animated motion type won't be affected by any other bodies. Animated bodies will still push dynamic bodies out of the way and pull on constraints but the animated body won't be affected by those collisions. This is useful for important objects where you need them to reach a particular goal - e.g. an elevator which should always reach the correct floor, no matter how many other bodies are inside the elevator.

### Sleep mode

When creating a body, you can request that it starts in *sleep mode*. Bodies in this mode will have their physics calculations skipped until the engine needs them to collide with another body or until a force is applied to them. This can improve performance if you're loading a scene where you know the bodies are at rest. However, *sleep mode is not an absolute guarantee*. Other factors, such as a nearby body that is not sleeping, can cause the body to wake up from this mode, so avoid having behavior that depends on it and use it only as a performance aid. Even if you don't request that a body start in sleep mode, the physics engine will automatically put bodies to sleep when they have come to rest and wake them up when appropriate.

<Playground id="#KJ0945#1" title="Sleep mode" description="Shows how sleep mode has influence on created bodies dynamics"/>

### Creating a body

You can create a body using the `PhysicsBody` constructor. It takes the `TransformNode` associated with that body, a motion type (static vs dynamic vs animated), a boolean indicating whether the body will start in sleep mode, and a scene (which needs to have an active Physics Engine).

```javascript
const sphere = BABYLON.MeshBuilder.CreateSphere("sphere");
const body = new BABYLON.PhysicsBody(sphere, BABYLON.PhysicsMotionType.DYNAMIC, false, scene);
```

<Playground id="#RQIZD3#1" title="Add bodies" description="Add bodies on demand"/>

<Playground id="#MZCQC4" title="Clone" description="Cloned mesh with attached body also duplicates physics properties"/>

### Setting the mass of a body

A body has *mass properties* that affect how it responds to physical stimuli. 

The mass properties are: *mass*, which determines how "heavy" an object is, *center of mass*, which determines the point that a body spins around, *inertia*, which is similar to mass, but describes how far away the mass is distributed from the center of mass, affecting rotations, and *inertia orientation* which determines the axes that a body spins around.

Some physics engines, such as Havok, can automatically determine the mass properties of a body from the body's shape, so it is very common to supply only the mass parameter and allow the engine to derive the rest of the properties (although the engine will also compute a mass if one is not provided).

These mass properties are very important for achieving physically-realistic behaviour. An object with an incorrect inertia or center of mass will appear to rotate in an unnatural way, while a body with an incorrect mass might appear to be unnaturally heavy (or light!)

```javascript
// Setting only the basic mass properties
const body = new BABYLON.PhysicsBody(sphere, BABYLON.PhysicsMotionType.DYNAMIC, false, scene);
body.setMassProperties({
  mass: 1,
});
```

```javascript
// Setting the full mass properties. ONLY DO THIS IF YOU KNOW WHAT YOU'RE DOING!
const body = new BABYLON.PhysicsBody(sphere, BABYLON.PhysicsMotionType.DYNAMIC, false, scene);
body.setMassProperties({
  mass: 1,
  centerOfMass: new BABYLON.Vector3(0, 1, 0),
  inertia: new BABYLON.Vector3(1, 1, 1),
  inertiaOrientation: new BABYLON.Quaternion(0, 0, 0, 1)
});
```
<Playground id="#JVZAFL#1" title="Center of mass" description="Shos how the center of mass influences body motion"/>

### Instanced bodies

For meshes composed of [thin instances](/features/featuresDeepDive/mesh/copies/thinInstances), the body created by the engine is composed of multiple internal body instances. This allows faster rendering alongside the physics simulation. All instances must have the same shape, but they can have their own individual mass and have forces and constraints applied to them individually. Methods that can be applied at the instance level have an optional `instanceIndex` parameter that receives the index of the instance to which the method will be applied. If no `instanceIndex` is provided, the method will be applied to all instances. An example is shown here:

```javascript
const sphere = BABYLON.MeshBuilder.CreateSphere("sphere");

// This generates 3 thin instances based on the sphere mesh
sphere.thinInstanceAddSelf();
sphere.thinInstanceAddSelf();
sphere.thinInstanceAddSelf();

const body = new BABYLON.PhysicsBody(sphere, BABYLON.PhysicsMotionType.DYNAMIC, false, scene);

// Apply a vertical force on all the 3 spheres
body.applyForce(new BABYLON.Vector3(0, 100, 0), new BABYLON.Vector3(0, 0, 0));

// Apply a horizontal force to the first sphere ONLY
body.applyForce(new BABYLON.Vector3(100, 0, 0), new BABYLON.Vector3(0, 0, 0), 0); 
```

> ⚠️ Important: When setting the instance matrix using the `thinInstanceSetBuffer` method, you have to set the last argument to `false`. This ensures that the instance buffers are not static, which allows them to be changed by physics. So, the expected `setBuffer` call should be:
 ```
 box.thinInstanceSetBuffer("matrix", matricesData, 16, false);
 ```

<Playground id="#MZKDQT#5" title="Instances" description="How to use instances with physics" isMain={true} category="Physics"/>

<Playground id="#BJZ39H#2" title="Pendulum Instances" description="Pendulum Instances"/>

#### Limitations

There are a few limitations when using instanced bodies in this way. Currently, it is not supported to have different scales on each thin instance's matrix. It is also not supported to have transformations at the mesh level; i.e., the instanced mesh's position, rotation, and scale values must remain at their defaults.

## Shape

A physics shape is a virtual representation of the collision geometry of a physics body, used for collision detection and response. If multiple bodies share the same or similar enough geometry, the same shape can be reused for all of them, greatly increasing performance. A body needs a shape to be able to collide with other objects.

```javascript
const shape = new BABYLON.PhysicsShapeSphere(
  new BABYLON.Vector3(0,0,0), // center of the sphere in local space
  0.5, // radius of the sphere
  scene // containing scene
);
body.shape = shape;
body2.shape = shape;
body3.shape = shape;
// ...
```

The shape types supported by the V2 plugin are:

| Enum | Description | Image | Havok plugin support |
| --- | --- | --- | --- |
| SPHERE | Simple sphere | ![Sphere Shape](/img/features/physics/sphere_shape_viewer.webp) | ✅ |
| CAPSULE | A cylinder with a half sphere at top and bottom | ![capsule Shape](/img/features/physics/capsule_shape_viewer.webp) | ✅ |
| CYLINDER | Cylinder | ![cylinder Shape](/img/features/physics/cylinder_shape_viewer.webp) | ✅ |
| BOX | Box | ![box Shape](/img/features/physics/cube_shape_viewer.webp) | ✅ |
| CONVEX_HULL | A convex hull is the smallest convex shape containing points.| ![convex_hull Shape](/img/features/physics/convex_hull_shape_viewer.webp) | ✅ |
| MESH | Mesh used for rendering or a simpler version | ![mesh Shape](/img/features/physics/mesh_shape_viewer.webp) | ✅ |
| CONTAINER | Holder of other shapes | ![container Shape](/img/features/physics/compound_shape_viewer.webp) | ✅ |
| HEIGHTFIELD | A height field mesh is a 2D surface with height data. | ![heightfield Shape](/img/features/physics/heightfield_shape_viewer.webp) | ✅ |

[This page contains more detail about shapes and their parameters.](/features/featuresDeepDive/physics/shapes)

## Material

A Material holds friction and restitution and is associated with a Physics Shape.

Friction is a measure of how much resistance to sliding exists between two objects in contact. It describes how much force is needed to move an object against another surface or how much it will slide along that surface. Friction is often used to model the behavior of objects sliding, rolling, or sticking to each other.

Restitution, also known as elasticity or bounciness, is a measure of how much energy is conserved in a collision between two objects. It describes how much an object will bounce back after a collision, relative to how much it was moving before the collision. Restitution is often used to model the behavior of objects bouncing, colliding, or deforming.

Both friction and restitution are non-negative values, usually between 0 and 1, with higher values indicating greater resistance or energy conservation, respectively.

```javascript
const shape = new BABYLON.PhysicsShapeSphere(new BABYLON.Vector3(0,0,0), 0.5, scene);
const material = {friction: 0.2, restitution: 0.3};
shape.material = material;
```

## Disposing of your elements

When a Body or Shape is not needed anymore, it is good practice to dispose of it. This ensures that the Physics Engine doesn't waste time processing what it doesn't need to. You can dispose of them by calling the `dispose` method.

When a node associated with a Body is disposed, the corresponding Body is also disposed. However, *the shape used by the body is not automatically disposed*, as the same shape can be used by multiple bodies.

```javascript
const shape = new BABYLON.PhysicsShapeSphere(
  new BABYLON.Vector3(0,0,0), // center of the sphere in local space
  0.5, // radius of the sphere
  scene // containing scene
);
body.shape = shape;
body2.shape = shape;
body3.shape = shape;

// ...

// When disposing of the scene:
body.dispose();
body2.dispose();
body3.dispose();

// Don't forget to also dispose of the shape when it's not needed anymore!
shape.dispose();
```

## SetTargetTransform

SetTargetTransform is a method available on the PhysicsBody that takes a target position and orientation and sets the body's velocity so it reaches that target. It is useful when you know where the body should be and do not want to calculate its velocity yourself. This method is more commonly used with animated bodies.

<Playground id="#FLCVX1#2" title="SetTargetTransform" description="Playground showing how to use the setTargetTransform method to rotate a body"/>



# Shape cast

Shape casting groups different features related to using Physics V2 shapes to make queries in the physics world.
In short, use physics shapes to query collisions and distances to other physics shapes.
This API is specific to the Havok plugin.

## Common query interface

These two properties are common to all query interfaces:
```javascript
/**
 * Should trigger collisions be considered in the query?
 */
shouldHitTriggers: boolean;
/**
 * Should the query ignore the body that is passed in?
 */
ignoreBody?: PhysicsBody;
```

## Point Proximity Query

Query the closest shape within a `maxDistance` radius.

```javascript
export interface IPhysicsPointProximityQuery {
/**
* The position of the query
*/
position: Vector3;
/**
* Maximum distance to check for collisions. Can be set to 0 to check for overlaps.
*/
maxDistance: number;
/**
* Collision filter for the query.
*/
collisionFilter: IRaycastQuery;
}
```

Use this interface to do the query:

```javascript
var hk = new BABYLON.HavokPlugin();
hk.pointProximity(
    {
        position: ballPos,
        maxDistance: 0.1
    },
    result
);
```
See below for the result definition.

PG: <Playground id="#I6AR8X#21" title="Point Proximity" description="Find the closest shape from a point within a limit"/>

## Shape Proximity Query
Instead of a point, provide a shape. The interface becomes:

```javascript
hk.shapeProximity(
    {
        shape: shape1,
        position: mesh1.absolutePosition,
        rotation: mesh1.absoluteRotationQuaternion,
        maxDistance: 10
    },
    shapeLocalResult,
    hitWorldResult
);
```
Two results are returned: the first one is local to the shape. The second is in world space.

PG: <Playground id="#1VT1BK#11" title="Shape Proximity" description="Find the closest shape from another shape within a limit"/>

## Shape Cast query
When a shape moves from a start position to an end position, this query tells you at what fraction of that movement a collision occurs.
> Note: The result will not be correct for intersecting shapes.

```javascript
hk.shapeCast({
    shape: shape1,
    rotation: mesh1.rotationQuaternion,
    startPosition: castStartPosition,
    endPosition: castEndPosition,
    shouldHitTriggers: false,
}, shapeLocalResult, hitWorldResult);
```
For a positioned and oriented shape moving from `startPosition` to `endPosition`, `shapeLocalResult` and `hitWorldResult`—both of type `ShapeCastResult`—will have the `hasHit` property set to `true` when a collision occurs.
Then, get the fraction of that movement with the `hitFraction` property.

PG: <Playground id="#1VT1BK#12" title="Shape Cast" description="Find the closest shape from another shape within a limit"/>

## Queries result

Result information for these three queries is contained in:
- `ProximityCastResult` for proximity and shape proximity
- `ShapeCastResult` for shape cast

```javascript
export class CastingResult {
    /**
     * The Physics body that the query hit.
     */
    public body?: PhysicsBody;
    /**
     * The body Index in case the Physics body is using instances
     */
    public bodyIndex?: number;

    /**
     * The shape hit by the query.
     */
    public shape?: PhysicsShape;
    ...
```
Raycast results also inherit from this base class.

The `ProximityCastResult`-specific property is:

```javascript
/**
 * Gets the distance from the hit
 */
hitDistance: number;
```

The `ShapeCastResult`-specific property is:

```javascript
/**
 * Gets the hit fraction along the casting ray
 */
hitFraction: number
```


# Shapes

## What are they

Physics Shapes represent the geometry that a body will have when interacting with the world. Depending on the chosen shape, the body will react differently to colliding with other objects. Even if the visual mesh of an object is composed of many triangles, if it has a simple enough physics shape, its collisions can be computed quickly.

In general, the convex hull gives the best performance while closely matching the visual geometry. However, if you have highly concave meshes, which would be unsuitable for a convex shape, it's still possible to use a container with multiple simpler shapes.


## Available shapes and parameters

This section demonstrates how to create the available Physics Shapes and their parameters. Note that the shape parameters are determined in a **LOCAL** coordinate system. In other words, they don't depend on the body or mesh's position, rotation, or scaling in the world:

```javascript
const shape = new BABYLON.PhysicsShapeSphere(
    new BABYLON.Vector3(0, 0, 0),   // center of the sphere
    1,                              // radius of the sphere
    scene                           // scene of the shape
);
```

![Sphere Shape](/img/features/physics/sphere_shape.webp)

A sphere is probably the simplest shape that can be simulated. The sphere is described by a single point for the center and a radius.

```javascript
const shape = new BABYLON.PhysicsShapeCylinder(
    new BABYLON.Vector3(0, -0.5, 0),    // starting point of the cylinder segment
    new BABYLON.Vector3(0,  0.5, 0),    // ending point of the cylinder segment
    1,                                  // radius of the cylinder
    scene                               // scene of the shape
);
```

![Cylinder Shape](/img/features/physics/cylinder_shape.webp)

A cylinder shape is described by two points and a radius. It's a great choice for barrels, wheels, and glasses.

```javascript
const shape = new BABYLON.PhysicsShapeCapsule(
    new BABYLON.Vector3(0, -0.5, 0),    // starting point of the capsule segment
    new BABYLON.Vector3(0,  0.5, 0),    // ending point of the capsule segment
    1,                                  // radius of the capsule
    scene                               // scene of the shape
);
```

![Capsule Shape](/img/features/physics/capsule_shape.webp) Capsules are similar to cylinders, but they have two half-spheres, one on each end. They are a great choice for character limbs (sometimes called ragdolls).

```javascript
const shape = new BABYLON.PhysicsShapeBox(
    new BABYLON.Vector3(0, 0, 0),        // center of the box
    new BABYLON.Quaternion(0, 0, 0, 1),  // rotation of the box
    new BABYLON.Vector3(1, 1, 1),        // dimensions of the box
    scene                                // scene of the shape
);
```

A box is exactly what it sounds like—a box. It has a size, a center, and an orientation. This is a great choice for boxes, books, walls, or anything that needs to be flat.

```javascript
const shape = new BABYLON.PhysicsShapeConvexHull(
    mesh,   // mesh from which to produce the convex hull
    scene   // scene of the shape
);
```

A convex hull is the most versatile of the physics shapes. A convex object is one where you can draw a line between any two vertices without leaving the shape. While most real-world objects are not convex, for the purposes of physics simulation this is a great approximation for most objects. The input mesh can be concave—the physics engine will calculate the convex part of the geometry.

```javascript
const shape = new BABYLON.PhysicsShapeMesh(
    mesh,   // mesh from which to calculate the collisions
    scene   // scene of the shape
);
```

A mesh shape is simply a collection of triangles. All the triangles in the input mesh will become triangles in the physics engine. This is a great choice for static bodies, which often represent highly concave objects, because it gives the closest match to your render geometry. Be aware that when two complex mesh shapes collide with each other, the physics engine may need to calculate collisions between a huge number of triangles, which can slow down the simulation.

```javascript
const shape = new BABYLON.PhysicsShapeContainer(
    scene   // scene of the shape
)
```

A container shape doesn't have any geometry by itself. However, it does allow any other shape to be added as a child with an additional transform. If none of the other shape types are suitable for matching your render geometry, you can use a container and add a number of simpler shapes to approximate your visual mesh.

[The Container has its own page](/features/featuresDeepDive/physics/compounds) for more information.

A height field is essentially a grid of height values (often stored in a 2D array) that define the elevation of a surface at each point on a regular grid. This creates a 3D surface that can be used for collision detection and physics simulations more efficiently than using a high-resolution mesh of individual polygons. The example below constructs a height field from the `heightBuffer` returned by `CreateGroundFromHeightMap`:

```javascript
var ground = BABYLON.MeshBuilder.CreateGroundFromHeightMap("g", "https://image.jpeg", {
        subdivisions,
        width: size,
        height: size,
        maxHeight: 5,
        passHeightBufferInCallback: true,
        onReady: (mesh, heightBuffer) => {
            var shape = new BABYLON.PhysicsShapeHeightField(
                size, // size of the heightfield on the X axis
                size, // size of the heightfield on the Y axis
                subdivisions + 1, // number of samples along the X axis
                subdivisions + 1, // number of samples along the Y axis
                heightBuffer, // data for the heightfield
                scene);
        }
    });
```

If you want to construct a height field for a mesh that represents your "ground", but the mesh's vertices aren't evenly spaced, you could construct a height field with 10 subdivisions using x and z coordinates from `(-50, -50)` to `(50, 50)` in your scene as follows:

```
const planeSize = 100;
const subdivisions = 10;
const stepSize = planeSize / subdivisions;
const midPlane = Math.floor((planeSize / 2));
var heightField = new Float32Array((subdivisions + 1) * (subdivisions + 1));
for (var x = 0; x <= subdivisions; x++){
    for (var z = 0; z <= subdivisions; z++){
        var xCoord = (x * stepSize) - midPlane;
        var zCoord = -1 * ((z * stepSize) - midPlane);
        // getHeightAtCoordinates, which is not implemented here, would need
        // to get the height of the mesh at x, z coordinates.
        var height = getHeightAtCoordinates(xCoord, zCoord);
        var index = z * (subdivisions + 1) + x;
        heightField[index] = height;
    }
}
var shape = new BABYLON.PhysicsShapeHeightField(
    planeSize,
    planeSize,
    subdivisions + 1,
    subdivisions + 1,
    heightField,
    scene);
```

The following image shows a comparison of the Container, Mesh and Convex Hull shapes, from left to right:
![Comparison](/img/features/physics/shapes_comparison.webp)

<Playground id="#Z8HTUN#1" title="Simple scene" description="Simple falling sphere created with body and shape"/>
<Playground id="#EC934B" title="Simple ground mesh example with Havok Physics" description="Simple example of creating a ground collision mesh using the Mesh shape type"/>
<Playground id="#I37D8G#18" title="Height field shape example with Havok Physics" description="Height field physics shape created from a height map ground mesh"/>



# How to Use a Physics Engine

## Introduction

Babylon.js has a plugin system for physics engines that enables users to add physics interactions to scene objects.
Unlike the internal collision system, a physics engine calculates objects' body dynamics and emulates "real-life" interactions between them. So if two objects collide, they will "bounce" off one another, just like you would expect from a real-life object.

The plugin system allows us to use well-established physics engines and integrate them into the render loop. Apart from very advanced usage, there is no need to interact directly with the physics engine. Babylon.js does the work for you.

## Which physics engine is integrated

There is a plugin for the Havok Physics engine.

Read about the [Babylon.js Havok plugin](/features/featuresDeepDive/physics/havokPlugin) and how to use it directly.

## Basic usage

### Enabling the physics engine

To enable the physics engine, call the scene's `enablePhysics` function:

```javascript
var scene = new BABYLON.Scene(engine);
var gravityVector = new BABYLON.Vector3(0, -9.81, 0);
var physicsPlugin = new BABYLON.HavokPlugin();
scene.enablePhysics(gravityVector, physicsPlugin);
```

Both parameters are optional. The default parameters are shown in the example. This is the same as calling:

```javascript
scene.enablePhysics();
```

```javascript
scene.enablePhysics(new BABYLON.Vector3(0, -9.81, 0), new BABYLON.HavokPlugin());
```

Calling this function will create a new `PhysicsEngine` object that handles the physics interactions.

The physics engine is now enabled and is running during the render loop.

## Your first physics scene

Here we present a minimal example of a physics-enabled scene, using [Aggregates](/features/featuresDeepDive/physics/aggregates) for faster creation:

```javascript
var createScene = function () {
  // This creates a basic Babylon Scene object (non-mesh)
  var scene = new BABYLON.Scene(engine);

  // This creates and positions a free camera (non-mesh)
  var camera = new BABYLON.FreeCamera("camera1", new BABYLON.Vector3(0, 5, -10), scene);

  // This targets the camera to scene origin
  camera.setTarget(BABYLON.Vector3.Zero());

  // This attaches the camera to the canvas
  camera.attachControl(canvas, true);

  // This creates a light, aiming 0,1,0 - to the sky (non-mesh)
  var light = new BABYLON.HemisphericLight("light", new BABYLON.Vector3(0, 1, 0), scene);

  // Default intensity is 1. Let's dim the light a small amount
  light.intensity = 0.7;

  // Our built-in 'sphere' shape.
  var sphere = BABYLON.MeshBuilder.CreateSphere("sphere", {diameter: 2, segments: 32}, scene);

  // Move the sphere upward at 4 units
  sphere.position.y = 4;

  // Our built-in 'ground' shape.
  var ground = BABYLON.MeshBuilder.CreateGround("ground", {width: 10, height: 10}, scene);

  // initialize plugin
  var hk = new BABYLON.HavokPlugin();
  // enable physics in the scene with a gravity
  scene.enablePhysics(new BABYLON.Vector3(0, -9.8, 0), hk);

  // Create a sphere shape and the associated body. Size will be determined automatically.
  var sphereAggregate = new BABYLON.PhysicsAggregate(sphere, BABYLON.PhysicsShapeType.SPHERE, { mass: 1, restitution:0.75}, scene);

  // Create a static box shape.
  var groundAggregate = new BABYLON.PhysicsAggregate(ground, BABYLON.PhysicsShapeType.BOX, { mass: 0 }, scene);

  return scene;
};
```

<Playground id="#Z8HTUN#1" title="Simple scene" description="Simple falling sphere created with body and shape" isMain={true} category="Physics"/>

## Physicalize GLTF

An extra step is needed to physicalize meshes imported from glTF in a left-handed scene. Insert an extra transform node just before the `__root__` so the loader's right-to-left-handed conversion is transparent to the physics engine. See [Coordinate Systems and Handedness](/features/featuresDeepDive/mesh/transforms/coordinateSystems#loading-gltf-in-babylonjs) for an explanation of the imported root.

```javascript
const trParent = new BABYLON.TransformNode("tr", scene);
const root = scene.getMeshByName("__root__");
root.setParent(trParent);
```

<Playground id="#TOVMEA#0" title="Simple scene with gltf" description="Simple falling boombox mesh coming from gltf" isMain={true} category="Physics"/>

## Debugging your scene

Use the physics debug display when your scene and dynamics don't behave the way you think they should.
It will display geometry the way the physics engine sees the world.
There are two ways to invoke the display.

### Programmatically

```javascript
physicsViewer = new BABYLON.Debug.PhysicsViewer();
for (const mesh of scene.rootNodes) {
    if (mesh.physicsBody) {
        const debugMesh = physicsViewer.showBody(mesh.physicsBody);
    }
}
```

This snippet creates the PhysicsViewer and then adds every PhysicsBody available from the scene's meshes.

### Using the Inspector

You can turn on and off the Physics Viewer on the Debug Tab of the Inspector:

![Inspector Physics Viewer](/img/features/physics/inspector-physics-viewer.webp)



# Support for Physics Engines

Physics engines are third-party external programs that can be plugged into Babylon.js. Depending on their features, they emulate "real-life" interactions between objects, which can be meshes, solid particles from the solid particle system, or some cameras. One feature of a physics engine is the addition of gravity to a scene.

There are 2 physics architectures in Babylon.js.

- a Version 2 (V2 for short) with support for modern Physics Engines.

  > [🚀 You can find the V2 API documented here.](/features/featuresDeepDive/physics/usingPhysicsEngine)  

- Version 1 (V1 for short), which is a pre-6.0 Legacy API.

  > [⚠️ The documentation for V1 has been moved to the Legacy section.](/legacy/physics)

#### We strongly recommend using V2 over V1. [A migration guide is here](/features/featuresDeepDive/physics/migrate).

## Physics V2

There are plugins for 1 physics engine:

1. Havok - a powerful engine used in AAA games.

It needs to be enabled before use.

This architecture allows finer-grained control over your physics scene by distinguishing between collision shapes and physical bodies.
A typical use case is to have one collision shape used by numerous bodies.
This allows a lower memory footprint and more efficient memory addressing.
A special effort has been put into better performance for a huge number of bodies. This is also the case for the collision callback mechanism.

A broad overview of the Physics V2 advancements is available on this [Medium article](https://medium.com/@babylonjs/physics-v2-overview-ed36039ce1e7).

## Physics V1

There are plugins for 3 physics engines:

1. Cannon.js - a wonderful physics engine written entirely in JavaScript.
2. Oimo.js - a JS port of the lightweight Oimo physics engine.
3. Ammo.js - a JS port of the bullet physics engine.

All need to be enabled before use.

Interactions between objects are achieved by impostors, simple objects that are attached to complex objects in a scene. The impostor can be assigned physical attributes such as mass, friction, a coefficient of restitution, impulse, and linear and angular velocity.

Two imposters can be connected using joints such as a hinge or ball and socket.

Ammo also allows the creation of soft bodies.


Physics

Physics V2

Physics V1

Coming next

Aggregates

How to use Physics Aggregate for fast and easy physics scene creation.

Using Havok and the Havok Plugin

Learn how to use the Havok plugin offered by Babylon.js.

Using A Physics Engine

Learn how to use one of the available physics engines in Babylon.js.

Physics V2 core concepts

All the concepts and objects designed for Physics V2 plugins

Physics V2 Shapes

Describing Shapes

Forces

Learn all about applying physical forces in Babylon.js.

Physics Compounds

Learn how to use compounds to model complex objects with simple primitives.

Collision Events

Learn how to access collision events in Babylon.js.

Constraints

Learn all about using Constraints with Babylon.js.

Raycast

How to use Physics for fast raycasting.

Migrate from Physics V1

A guide on best practices to port a Physics V1 scene to V2

Performance Tips

A guide on best practices to achieve maximum performance with the Physics V2 API

Ragdolls

A guide on ragdoll creation with the Physics V2 API

Shape cast

A guide on shape casting with the Physics V2 API

Physics prestep

How to use prestep to apply changes from scene to physics world

Physics character controller

How to use the character controller