
## Setting Advanced Collisions

Checking collisions on complex objects can have a big impact on performance, even for cameras and meshes
using the `.moveWithCollisions` method. The editor provides a tool to easily set up collision shapes on any mesh object in the scene
in order to improve performance.

## Introduction
### Basic Collisions
By default, Babylon.JS checks 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, checking collisions on the bounding box is more than sufficient.

The method would consist of:
- 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 follow the transform of the mesh, and the 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 imagine a more complex scenario where box and sphere collisions are not sufficient: **the stairs**. In that case, only "per triangle" collisions will allow you to go upstairs in a natural way.

If the stairs 3D model is too complex, and in order to save performance, the solution would be to provide
(or generate on the fly) a less detailed 3D model for the stairs.

The method would consist of creating a lower level-of-detail object for 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 detail takes time, and simplifying a mesh using the simplification method
is asynchronous.

### Editor To The Rescue
The editor provides a tool to generate these `colliders` for each mesh to save time and improve performance.

## Editing Advanced Collisions
To edit advanced collisions, select a mesh in the graph, scroll in the inspector to find the `Collisions` section,
and click the `Edit Advanced Collisions...` button. When clicked, a new tool opens over the inspector showing the current
state of the object's collisions.

![AdvancedCollisions](/img/extensions/Editor/AdvancedCollisions/advanced_collisions.webp)

## Understanding The Tool
Once opened, the tool shows the current collision state of the object (here `None`). To select a collider type,
just open the list box and select 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, all instances are updated to introduce the new collider
component.*

### Cube Collider
The `Cube` collider is the most performant collider and allows collisions to be checked only on the bounding box of the mesh.

![CubeColliderTool](/img/extensions/Editor/AdvancedCollisions/cube_collider_tool.webp)

In other words, just imagine that the following model will have collisions checked as if it were a cube instead of a complex mesh:

![CubeCollider](/img/extensions/Editor/AdvancedCollisions/cube_collider.webp)

### Sphere Collider
As with the `Cube` collider, the `Sphere` collider checks collisions on the bounding sphere of the mesh
instead of 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), the tool allows you to create an Auto-LOD according to a few properties.
It uses the `QuadraticErrorSimplification` implementation in Babylon.JS and allows you to pre-generate the lower level of detail
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.

For information, the tool shows the base vertex count vs. the LOD vertex count. This can help you understand how much the mesh
has been simplified. Take care not to simplify too much in order to keep the overall topology of the mesh in the 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.webp)

Once the properties are set, just click the `Compute...` button to generate the LOD, and an overlay appears to indicate that the
algorithm is working. Once done, the `Infos` section is updated to show the new vertex count value, and the collider mesh in the preview
is updated as well:

![LODCollider](/img/extensions/Editor/AdvancedCollisions/lod_collider.webp)



## Setting Basic Collisions
Using the inspector, collision 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.webp)

And scroll in the inspector to find the section named `Collisions`:

![SceneGraph](/img/extensions/Editor/BasicCollisions/scene_collisions.webp)

To enable collisions, simply check the `Enabled` checkbox and provide the desired gravity values for the current scene.

## Enabling Collisions For Camera
Cameras do not necessarily check for collisions by default. If your camera does not check for collisions, simply select the desired
camera in the graph and scroll in the inspector to find the section named `Collisions`.

*Note: According to the selected camera type, not 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 `FreeCamera` type is the most common camera type 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 set up the desired values according to the nature of the current scene being edited in the Editor.

The `Apply Gravity` property, if enabled, applies the gravity previously set in the scene and can be disabled only by unchecking the
property.

![SceneGraph](/img/extensions/Editor/BasicCollisions/free_camera.webp)

### Arc Rotate Camera
As with the `FreeCamera`, arc rotate cameras can have their collisions enabled using the `Enabled` checkbox.
Unlike the free camera, the ellipsoid property is replaced by the `Collisions Radius` property. Check the
[following documentation](/features/featuresDeepDive/cameras/camera_collisions#arcrotatecamera) in order to understand and set up
the desired value for the collisions radius.

![SceneGraph](/img/extensions/Editor/BasicCollisions/arc_rotate_camera.webp)

## Enabling Collisions For Meshes
Once the 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.
Do not hesitate to also check 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.webp)

## Using The ".moveWithCollisions" Method In Code
The Babylon.JS API provides a method named `.moveWithCollisions` on the `Mesh` class. This method works like it does 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 recomputing the world matrix is an expensive operation and not something we want to do multiple times per frame. If you must call `moveWithCollisions` 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 the current frame, it will recompute the world matrix on the current node and all of its parents, so the complexity is O(d), where d is the depth of NodeN.
- On the next frame, when `computeWorldMatrix` is called by default by the render loop, all children of NodeN will see that the node is not synchronized with its parent, which will force a recomputation of those nodes. Note that if we had not called `computeWorldMatrix(true)` on NodeN, then its children would skip the recalculation because they would be synchronized with the parent.

So the complexity of forcing recalculation on NodeN increases by the number of ancestors (for the current frame) and the number of descendants (for the next frame).

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


## Introduction
The Editor allows you to set up 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 uses `CannonJS`.

## Setting up physics
By selecting a mesh or mesh instance (basically any object extending `AbstractMesh`) in the scene, the inspector is updated to show the object's properties. For meshes and mesh instances, some properties related to physics are located in the section named `Physics`. By default, all unconfigured meshes have no impostor (`NoImpostor`).

At the moment, the available impostors are:
* `BoxImpostor`
* `SphereImpostor`
* `CylinderImpostor`

When you select a new impostor, the tool is 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, physics cannot be previewed in the Editor. To preview the result, run the project to see the physics effect and adjust the properties if needed by clicking the `Play` button 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.webp)

## Changing gravity
When selecting the scene in the scene graph, there are 2 editable gravity properties:
* Collisions gravity
* Physics gravity

Depending on the desired effect, both gravity values can be different. In the `Physics` section of the scene inspector, the gravity applied by the physics engine can be customized:

![SettingGravity](/img/extensions/Editor/UsingPhysics/setting_gravity.webp)

## Choosing physics engine
Using the inspector, the scene's properties allow you to change the physics engine used by the project. By default, `CannonJS` is used and can be replaced by OimoJS or AmmoJS. Changing the physics engine can be done without having to reset or redefine the existing impostors.

![SettingEngine](/img/extensions/Editor/UsingPhysics/setting_engine.webp)

Once the desired physics engine is selected, the project must be updated as well. By default, the project templates use `CannonJS`, and the library is imported in the `index.html` file. If you use `OimoJS`, for example, this import must be replaced with 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 `Oimo.js` file from a CDN or the 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>
```

For example, with `AmmoJS` this becomes:

```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>
```

Configuring collisions in Babylon.JS Editor

Coming next

Advanced Collisions

Understanding how to create and edit advanced collisions in a Babylon.JS Editor project

Basic Collisions

Understanding how to create and edit basic collisions in a Babylon.JS Editor project