
# 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.



## 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);
```

## The loop

There are 3 major steps:

- Getting the support: on what surface the character is
- Setting the desired velocity: What the character 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 function of the character state. That state can be `START_JUMP`, `IN_AIR` or `ON_GROUND`. These different steps allow to have different behaviors and different movement speeds.
Depending on user needs, it's possible to have speed and velocity control for swimming, for example.

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 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

The Compound is a special type of shape that acts as a "container" to other shapes. It allows modeling 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, thus we want to avoid using it 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 PhysicShapes 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 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"/>


## How to use it

Both forces and impulses don't 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    
);
```

A reminder that, if a body's transform node contains Thin Instances, you can choose which instance to apply the force/impulse 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 applied, 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 applyImpule" 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(); // need to call, 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 on both [the npm package](https://www.npmjs.com/package/@babylonjs/havok) `@babylonjs/havok` and on our CDN under the URL `https://cdn.babylonjs.com/havok/HavokPhysics_umd.js` or `https://cdn.babylonjs.com/havok/HavokPhysics_es.js` when using the `module` script.
Please note 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 common.js and AMD projects. Your bundler will select the right file for you.

The engine requires initialization in order to 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 which can be used to initialize the Babylon's Havok plugin.

### Using the npm package

To use the npm package, install the havok package to 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 generated 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 the engine initialization is happening 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 closer functionality to what most of the existing physic engines provide. However, it also includes some extra classes to make this migration easier. Here we show two ways of migrating 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 will just 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 the collision shapes and reuse them, improving memory usage and customizability. So it is also possible to separately create bodies and shapes:

```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 that should be taking 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 and recreating your ball and pins 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 to a body, there will be no effect. That's because the pre-step of updating the physic 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 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 body to get to 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 happening just before physics tick. It consists in updating physics entities position and orientation from scene transform node state. This process can be costly and is by default disabled.
It can be manually enabled and when enabled, 2 methods exists: a teleport mode and an action mode. The teleport mode makes the body to have limited interaction with shapes in contact. Whereas the action mode make the body to effective move in the world and interact with shapes in contact.
Teleport mode will be more suited when placing objects with a Gizmo for example. And Action mode when in game.

## How to use

There are 2 ways to enable prestep. First one is using `disablePreStep` boolean. When set to true, it will enable Teleport mode.

```javascript
aggregate.body.disablePreStep = false;
```

The second one allows finer control.

```javascript
aggregate.body.setPrestepType(PhysicsPrestepType.ACTION);
```

Depending on the Motion Type applied, the prestep will make the body to 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 body. 


# 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 these shapes.
A shape can be used for multiple bones and is big enough to contain the skinned geometry deformed this these bones.
Defining a ragdoll consists in listing each physic shape in the system, which bone it's controlling and some properties like shape size, rotation axis constraint.
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 root bone, 2 for arm_r and arm_l. As properties for arms are the same because symmetrical, 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 that will be constrained in angles. `min` and `max` define these limits.
`boneOffsetAxis` set the axis used to offset the shape on. `boxOffset` is the world size value to shift the shape along the axis. By default, physics shapes are centered on the bone.
This offset allows to have the shape to have one of its side on the bone.

```javascript
const ragdoll = new BABYLON.Ragdoll(skeleton, newMeshes[0], config);
```

Next step is to create the ragdoll instance. This is done in 1 line and 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 body but it's the animation that drives the physics.

At any moment after, to make the ragdoll dynamically updated, call:

```javascript
ragdoll.ragdoll();
```

Dispose the ragdoll to stop it.

## Interactions

Get the aggregate associated with a bone with `getAggregate` function. The returned aggregate functions like any other aggregate: it's possible to get the shape or body and apply impulse.

```javascript
ragdoll.getAggregate(0)?.body.applyImpulse(new BABYLON.Vector3(200,200,200), BABYLON.Vector3.ZeroReadOnly);
```

## Limitations

Imported .GLTF/.GLB will only work as ragdoll in Right Handed scenes. In Left Handed scenes, an intermediate Transform Node is added at the root to emulate the LH/RH coordinate switch.
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 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 the `raycastResult` that can (and should!) be reused between calls. This is the major difference with 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.png)

<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 will process all the bodies, attempt to make them behave in a physically realistic manner and then update the `TransformNode` to match the position of the simulated body. The most obvious way it does this is that the engine performs collision detection to prevent bodies from intersecting. In order for a pair of bodies to detect collisions, the bodies each need a shape; however, collision detection can require a lot of calculations, so, rather than using the visual meshes of an object, the `PhysicsBody` has a shape (`PhysicsShape`) which is usually simpler than the render meshes and enable the engine to minimize the amount of calculations necessary to simulate the world. Shapes are described in more detail in a [future chapter](/features/featuresDeepDive/physics/shapes).

Bodies and shapes have properties which approximate how they behave in the real world. Bodies have a mass distributions and velocities. The velocity is the speed the body is moving at, while the mass distribution describes how the velocity changes when two bodies interact.Shapes themselves are geometric objects which is used for detecting when bodies are colliding with each other; these shapes additionally have material properties (`PhysicsMaterial`) such as friction and restitution (which describe how a collision affects the bodies when sliding and bouncing) and a density (which can be used to calculate the 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 kinds of motion type (`PhysicsMotionType`) 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 physic calculations skipped until the engine needs them to collide with another body or if 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 not-sleeping body can cause the body to wake up from this mode, so avoid having behavior that depends on it, and use it only as an aid to performance. Even if you don't request a body to start in sleep mode, the physics engine will automatically put bodies to sleep when they have come to rest and wake those bodies 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 representing if the body will start in sleep mode or not, 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 a *mass properties* which affect how it responds to the physics 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 rest of the properties to be derived by the engine (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 along with the physics simulation. All instances must have the same shape, but they can have their own individual mass, have forces and constraints individually applied to them, etc. Methods that can be applied at instance level have an optional `instanceIndex` parameter that receives the index of the instance where the method will be applied to. If no `instanceIndex` is provided, the method will be applied to all instances. An example is 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 as `false`. This makes it so 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 have to be the default.

## 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.png) | ✅ |
| CAPSULE | A cylinder with a half sphere at top and bottom | ![capsule Shape](/img/features/physics/capsule_shape_viewer.png) | ✅ |
| CYLINDER | Cylinder | ![cylinder Shape](/img/features/physics/cylinder_shape_viewer.png) | ✅ |
| BOX | Box | ![box Shape](/img/features/physics/cube_shape_viewer.png) | ✅ |
| CONVEX_HULL | A convex hull is the smallest convex shape containing points.| ![convex_hull Shape](/img/features/physics/convex_hull_shape_viewer.png) | ✅ |
| MESH | Mesh used for rendering or a simpler version | ![mesh Shape](/img/features/physics/mesh_shape_viewer.png) | ✅ |
| CONTAINER | Holder of other shapes | ![container Shape](/img/features/physics/compound_shape_viewer.png) | ✅ |
| HEIGHTFIELD | A height field mesh is a 2D surface with height data. | | 🟥 |

[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 to 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 in a target position and orientation, and sets the velocity of the body to reach that target. It is useful when you have the information about where the body should be, and don't want to have to calculate its velocity. 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 cast regroup different features related to using Physics V2 Shapes to do queries in the Physics world.
To paraphrase it: use physics shapes to query collisions and distance to other physics shapes.
This API is specific to Havok plugin.

## Common query interface

These two properties are common to each query interface:
```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 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. 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 goes from a start position to an end position, if there is a collision, at which fraction of that movement does it happen?
> Note: Result will not be correct for intersecting shapes.

```javascript
hk.shapeCast({
    shape: shape1,
    rotation: mesh1.rotationQuaternion,
    startPosition: castStartPosition,
    endPosition: castEndPosition,
    shouldHitTriggers: false,
}, shapeLocalResult, hitWorldResult);
```
Basically, for a positioned and oriented shape, going from `startPosition` world position to `endPosition` world position, `shapeLocalResult` and `hitWorldResult`, both of `ShapeCastResult` type will have the `hasHit` property set to true.
Then, get the fraction of that move with `hitFraction` property.

PG: <Playground id="#1VT1BK#12" title="Shape Cast" description="Find the closest shape from another shape within a limit"/>

## Queries result

Result infos for these 3 queries are 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 result inherits as well from this base class.

Specific for `ProximityCastResult` consists in:

```javascript
/**
 * Gets the distance from the hit
 */
hitDistance: number;
```

Specific for `ShapeCastResult` consists in:

```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.png)

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.png)

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.png) Capsules are similar to cylinders, but have two half-spheres on each end. These 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 how it sounds - 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 your static bodies, as generally, those static bodies represent highly concave objects, so this will give the closest match to your render geometry. Be aware that when two complex mesh shapes collide with each other, it might require the physics engine 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 to match 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 in a more efficient manner compared to using a high-resolution mesh of individual polygons.

```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,
                    subdivisions+1,
                    subdivisions+1,
                    heightBuffer
                , 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.png)

<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 the user to add physics interactions to the 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 to 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.

## What physics engine are integrated

There is a plugin for 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 will be in charge of handling 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, utilizing [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"/>

## Debugging your scene

Use the physics debug display when your scene and dynamics doesn't behave the way you think it 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 will create the PhysicsViewer and then will add every PhysicsBody available thanks to the scene 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.gif)



# Support for Physics Engines

Physics engines are third party external programs that can be plugged into Babylon.js. They, depending on their features, 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 architecture 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.

All need to be enabled before use.

This architecture allows finer grain control on your physics scene by making the difference between collision shapes and physical body.
A typical use case is to have only 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 imposters, simple objects that are attached to any complex objects with a scene. The imposter can be assigned physical attributes such as mass, friction, a coefficient of restitution, impulse, and linear and angular.

Two imposters can be connected using joints such as a hinge or ball and socket.

Ammo also allows the creation of soft bodies.
