
## Setting Advanced Collisions

Checking collisions on complex objects can have a big impact on performances even for cameras and meshes
using the `.moveWithCollisions` method. The editor provides a tool to easily setup collisions shapes on any mesh object in the scene
in order to save performances.

## Introduction
### Basic Collisions
By default, Babylon.JS will check for collisions using a complex algorithm that checks collisions per triangle for each mesh near the camera
or the mesh being moved with collisions. Sometimes (often), checking collisions on the bounding box is highly sufficient.

The method would consist on:
- Create by code a new cube mesh or sphere mesh (named `collider`)
- Add the collider as a child of the mesh
- Apply the bounding box properties of the mesh to the collider
- Disable collisions on the mesh and enable collisions on the collider.

In that way, the collider will always extend the transform of the mesh and camera will only check collisions on the cube or sphere collider
instead of checking collisions on the entire mesh per triangle.

### Advanced Collisions
Let's image a more complex scenario where box and sphere collisions are not sufficient: **the stairs**. In that case, only "per triangle" collisions will allow to upstair in a natural way.

In case the stairs 3d model is too complex, and in order to save performances, the solution would be to provide
(or generate on the fly) a lower detailed 3d model for the stair.

The method would consist on creating a lower level of details object of the source mesh (instead of a cube or sphere) made by an
artist or using the [Auto-LOD Simplification Tool of Babylon.JS](/features/featuresDeepDive/mesh/simplifyingMeshes)
and perform the same next steps for `Basic Collisions`.

The problem here is that generating a lower level of details has a cost in time and simplifying a mesh using the simplification method
is asynchronous.

### Editor To The Rescue
The editor provides a tool to generate these `colliders` per mesh to save time and performances.

## Editing Advanced Collisions
To edit the advanced collisions, select a mesh in the graph, scroll in the inspector to find the `Collisions` section
and click the button `Edit Advanced Collisions...`. On clicked, a new tool is opened over the inspector showing the current
state of the collisions of the object.

![AdvancedCollisions](/img/extensions/Editor/AdvancedCollisions/advanced_collisions.png)

## Understanding The Tool
Once opened, the tool shows the current stage of the collisions of the object (here `None`). To select a collider type,
just open the listbox and selected the desired collider type. Each time a collider type is changed, the mesh's collision component
is updated in the preview and shown in red.

*Note: For meshes that have instances, each time a collider type is changed then all instances are updated to introduce the new collider
component.*

### Cube Collider
The `Cube` collider is the most performant collider that allows to check collisions only on the bounding box of the mesh.

![CubeColliderTool](/img/extensions/Editor/AdvancedCollisions/cube_collider_tool.png)

In other words, just imagine that the following model will have collisions check like it was a cube instead of a complex mesh:

![CubeCollider](/img/extensions/Editor/AdvancedCollisions/cube_collider.png)

### Sphere Collider
As well as the `Cube` collider, the `Sphere` collider will allow to check the collisions on the bounding sphere of the mesh
insteadof the bounding box of the mesh. In some cases, that collider can be useful especially if the moving platform is a sphere.

### LOD Collider
Taking the specific scenario example (the stairs), to tool allows to create an Auto-LOD according to few properties.
It uses the `QuadraticErrorSimplification` implementation in Babylon.JS and allows to pre-generate the lower level of details
that will be saved as well as the rest of the scene. In other words, no extra work is needed.

To understand the properties, check the
[following documentation](/features/featuresDeepDive/mesh/simplifyingMeshes#mesh-optimization-startingbabylonjs-21)
for the `Optimize Mesh` property and the
[following documentation](/features/featuresDeepDive/mesh/simplifyingMeshes#usage---simplifying-a-mesh)
for the quality property.

As informations, the tool shows the base vertices count vs. the LOD vertices count. This can help to understand how much the mesh
has been simplified. Take care to don't simplify too much in order to keep the overall topology of the mesh in case of, for example,
the stairs.

In most cases, setting the quality as "0.01" works where the vertices count can change from `77 424` to `882`.

![LODColliderTool](/img/extensions/Editor/AdvancedCollisions/lod_collider_tool.png)

Once properties are set, just click the `Compute...` button to generate the LOD and an overlay will appear to notify that the
algorithm is working. Once done, the `Infos` section is updated to show the new vertices count value and the collider mesh in the preview
is updated as well:

![LODCollider](/img/extensions/Editor/AdvancedCollisions/lod_collider.png)



## Setting Basic Collisions
Using the inspector, collisions properties can be customized per object:
- `meshes`: set whether the edited mesh checks for collisions.
- `cameras`: set whether the edited camera checks collisions on meshes and if gravity should be applied.
- `scene`: set whether collisions are enabled in the scene and configure the gravity values.

## Enabling Collisions In Scene
To enable collisions in the scene, simply select the `Scene` in the graph:

![SceneGraph](/img/extensions/Editor/BasicCollisions/scene_graph.png)

And scroll in the inspector to find the section named `Collisions`:

![SceneGraph](/img/extensions/Editor/BasicCollisions/scene_collisions.png)

To enable collisions, simply check the `Enabled` checkbox and provide the gravity values desired for the current scene.

## Enabling Collisions For Camera
Cameras don't necessary check for collisions by default. If your camera doesn't check for collisions, simply select the desired
camera in the graph and scroll in the inspector to find the section named `Collisions`.

*Note: According the type of the selected camera, no all properties will be shown. For example, the `Apply Gravity` option will not be shown
for `Arc Rotate Camera` as it makes no sense.*

### Free Camera
The cameras of type `FreeCamera` are the most common types of camera in projects. To enable collisions, simply check the
`Check Collisions` checkbox and configure the ellipsoid values. For ellipsoids, check the
[following documentation](/features/featuresDeepDive/cameras/camera_collisions#2-define-an-ellipsoid) in order to understand
and setup the desired values according the nature of the current scene being edited in the Editor.

The property `Apply Gravity`, if enabled, will apply the gravity previously set in the scene and can be disabled only by unchecking the
property.

![SceneGraph](/img/extensions/Editor/BasicCollisions/free_camera.png)

### Arc Rotate Camera
As for the `FreeCamera`, the arc rotate cameras can have their collisions enabled using the checkbox `Enabled`.
Opposed to the free camera, the ellipsoid property is replaced by `Collisions Radius` property. Check the
[following documentation](/features/featuresDeepDive/cameras/camera_collisions#arcrotatecamera) in order to understand and setup
the desired value for the collisions radius.

![SceneGraph](/img/extensions/Editor/BasicCollisions/arc_rotate_camera.png)

## Enabling Collisions For Meshes
Once scene and camera(s) have been configured, the last step is to configure which mesh(es) will have collisions enabled in order
to block the camera.

To enable collisions, simply check the `Check Collisions` checkbox and configure its optional `Ellipsoid` and `Ellipsoid Offset` properties.
Don't hesitate to check as well the
[following documentation](/features/featuresDeepDive/cameras/camera_collisions#4-object-vs-object-collision) to
understand ellipsoid and ellipsoid offset properties on meshes.

![SceneGraph](/img/extensions/Editor/BasicCollisions/mesh.png)

## Using The ".moveWithCollisions" Method In Code
The Babylon.JS API provides a method named `.moveWithCollisions` on `Mesh` class. This method will work like for cameras without any,
extra configuration. It'll check collisions on all meshes that have collisions enabled in the scene.

NOTE: If you try calling moveWithCollisions twice within a single frame, you will receive unexpected results as the collision detection logic is based off the mesh's position at the start of the frame, not based on the mesh's position after the first call to `moveWithCollisions`. See [this playground](https://playground.babylonjs.com/#T5JJ6Z#1) demonstrating that behavior. 

This is by design, as re-computing the world matrix is an expensive operation and not something we want to do multiple times per-frame. If you must call move with collisions more than once within a single frame, you can force the world matrix recomputation on the mesh using `mesh.computeWorldMatrix(true)`. See the updated playground [here](https://playground.babylonjs.com/#T5JJ6Z#2).

Please use this approach with caution, as it is not cheap. Calling `computeWorldMatrix(true)` on NodeN will have the following impact

- In current frame it will recompute the world matrix on current node and all of its parents, so the complexity is O(d), where d is the depth of NodeN (this aligns with your analysis above)
- On the next frame, when computeWorldMatrix is called default by the render loop, all the children of NodeN will see that the node is not synchronized with its parent, which will force a recomputation of that node (and thus their children will also not be synchronized with their parent. - Note that if we hadn’t called computeWorldMatrix(true) on NodeN, then its children would skip the recalculation because theyd be syncronized with parent.

So the complexity of forcing recalculation on NodeN increases by # of ancestors (for current frame) and # of descendants (for next frame).


Descriptions of how to create and edit collisions on meshes in scene using the Babylon.js Editor.


## Introduction
The Editor allows to setup and edit physics impostors for meshes in the scene using the inspector. All physics engines are supported:
* `CannonJS`
* `OimoJS`
* `AmmoJS`

By default, physics is enabled in the project and is using `CannonJS`.

## Setting up physics
By selecting a mesh or mesh instance (basically any object extending `AbstractMesh`) in the scene, the inspector will be updated to show the object's properties. For meshes and meshes instances, some properties are focusing on physics located in the folder named `Physics`. By default, all unconfigured meshes have no impostor (`NoImpostor`).

At the moment, the available impostors are:
* `BoxImpostor`
* `SphereImpostor`
* `CylinderImpostor`

By selecting a new impostor, the tool will be updated to show the common properties which are:
* `Mass`
* `Restitution`
* `Friction`

A documentation for all these options is [available here](/features/featuresDeepDive/physics/usingPhysicsEngine#options).

Once these properties are configured, the physics is not preview-able in the Editor. To preview the result, just run the project to see the physics effect and adjust the properties if needed by clicking on the button `Play` in the tools toolbar.

In the following example, the box and ground already have an impostor set to `BoxImpostor` where the box has a mass of 1 and the ground has a mass of 0 (to stay static).

![SettingPhysics](/img/extensions/Editor/UsingPhysics/setting_physics.gif)

## Changing gravity
When selecting the scene in the scene graph, there are 2 editable gravity properties:
* Collisions gravity
* Physics gravity

According to the wanted effect, both gravity values can be distinct. In the `Physics` folder of the scene inspector the gravity applied by the physics engine can be customized:

![SettingGravity](/img/extensions/Editor/UsingPhysics/setting_gravity.gif)

## Choosing physics engine
Using the inspector, the scene's properties allow to change the physics engine that should be used by the project. By default, `CannonJS` is used and can be replaced by OimoJS and AmmoJS. Changing the physics engine can be done without having to reset or redefine the impostors already existing.

![SettingEngine](/img/extensions/Editor/UsingPhysics/setting_engine.gif)

Once desired physics engine is selected, the project must be updated as well. In fact, by default the project templates are using `CannonJS` where the library is imported in the `index.html` file. In case of using `OimoJS` for example, this import must be replaced by the one that imports `OimoJS`. The default template looks like:

```html
<!DOCTYPE html>
<html xmlns="http://www.w3.org/1999/xhtml">

    <head>
        <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
        <title>Babylon.js Generated Template</title>

        
        <script src="./dist/bundle.js" type="text/javascript"></script>

        
        <script src="./node_modules/cannon/build/cannon.js" type="text/javascript"></script>

        ...
    </head>

    <body>
        ...
    </body>

</html>
```

In other words, for this example, the `CannonJS` import should be replaced to load the file `Oimo.js` from CDN or any other corresponding file in `node_modules`:

```html
<script src="https://cdn.babylonjs.com/Oimo.js" type="text/javascript"></script>
```

Or using `AmmoJS`:

```html
<script src="https://cdn.babylonjs.com/ammo.js" type="text/javascript"></script>
```

Which gives, for example with `AmmoJS`:

```html
<!DOCTYPE html>
<html xmlns="http://www.w3.org/1999/xhtml">

    <head>
        <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
        <title>Babylon.js Generated Template</title>

        
        <script src="./dist/bundle.js" type="text/javascript"></script>

        
        <script src="https://cdn.babylonjs.com/ammo.js" type="text/javascript"></script>

        ...
    </head>

    <body>
        ...
    </body>

</html>
```