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

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


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

Physics prestep

What is it

How to use

Performance

Further reading

Performance Tips

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