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


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

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

Physics character controller

What is it

Creating a Controller

moveWithCollisions

Kinematic platforms

Observable

The loop

Further reading

Performance Tips

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