
## Mesh Collisions

In dynamic scenes, objects are moving and interacting with each other. To get the best rendering, you will want to know when your meshes are in contact with each other. In this tutorial, we are going to discover how the collision system works.

![Collisions](/img/how_to/Collisions%20Intersect/10.png)

_Final result_

## How can I do this?

This tutorial shows you two ways of detecting collisions: the first is to raise a collision event when two meshes are in contact, and the second is to detect contact between a mesh and a single point.

We are going to talk about the scene above. The first and second spheres (balloons) collide on the rotated ground, while the last one collides only at a single point. Once you have created this basic scene, continue reading to learn how to check collisions.

### Intersect mesh

The point here is to check contact between our balloons and the ground. We will use the `intersectsMesh()` function, with two parameters: the mesh to be checked, and the precision of the intersection (boolean).

```javascript
if (balloon1.intersectsMesh(plan1, false)) {
  balloon1.material.emissiveColor = new BABYLON.Color4(1, 0, 0, 1);
} else {
  balloon1.material.emissiveColor = new BABYLON.Color4(1, 1, 1, 1);
}
```

To avoid costly calculations from checking many details on a mesh, the Babylon.js engine creates a bounding box around the object and tests for intersections between this box and the colliding mesh. Here is an example of a bounding box:

![Collisions](/img/how_to/Collisions%20Intersect/10-1.png)

But this bounding box can be more or less precise, and that’s why we have our second parameter. In short, if this parameter is set to `true` (`false` by default), then the bounding box is closer to the mesh (OBB bounding type), but it is a more costly calculation. Be aware that this type of bounding box is especially useful when your mesh is rotated.

![Collisions](/img/how_to/Collisions%20Intersect/10-2.png)

So think about the collision precision you need before choosing.

If you want more information about this second parameter, you can have a look at this Wikipedia page, especially about AABB and OBB mode: [https://en.wikipedia.org/wiki/Bounding_volume](https://en.wikipedia.org/wiki/Bounding_volume)

### Intersect point

The other function you can use is `intersectsPoint()` with a specific point, like this:

```javascript
var pointToIntersect = new BABYLON.Vector3(10, -5, 0);
if (balloon3.intersectsPoint(pointToIntersect)){
  balloon3.material.emissiveColor = new BABYLON.Color4(1, 0, 0, 1);
}
```

We defined a precise point in our scene, and if our balloon intersects this point anywhere on the balloon, the condition is met and we change the color of the balloon.

You can play with the code used in this tutorial... by visiting the playground here: <Playground id="#KQV9SA" title="Mesh Intersection Example" description="Simple example of mesh intersections." isMain={true} category="Mesh"/>



## Raycasts

The rays are like sunrays.
They are used to check collisions or intersections in the scene between meshes and points.

In the [previous tutorial](/features/featuresDeepDive/scene/interactWithScenes), we used it to select meshes with the mouse (a ray goes from camera to mouse position in 3D),
using the function `scene.pick(scene.pointerX, scene.pointerY)`.

But here we will see that we can throw a ray from any point and in any direction.
For example, in a third-person shooting game, we can detect collisions between our bullets and obstacles.

**Documentation of classes :**

You must first [create a ray](/typedoc/classes/babylon.ray).

The method [scene.pickWithRay()](/typedoc/classes/babylon.scene#pickwithray) throws a ray in your scene to pick a mesh.

Use the [picking info](/typedoc/classes/babylon.pickinginfo) that is returned by [scene.pickWithRay()](/typedoc/classes/babylon.scene#pickwithray).

## Detect the first mesh touched by the ray

Check out an example here: <Playground id="#KNE0O#1327" title="Get First Mesh Hit By Ray" description="Simple example of getting the first mesh hit by a ray." isMain={true} category="Mesh"/>

(The following descriptions will reference this example. All line references are from the most recent example link)

![Raycast simple](/img/how_to/raycast01.webp)

In all our playgrounds, we will imagine that our character is the main box at the center.
It will shoot laser beams continually forward and detect which enemy (other boxes) is hit.

So with the mouse, you don't need to click but move to turn the box with this trigonometry function `mousemovef` _(line #34)_.
When it is created, a ray requires an origin, a direction, and a length.

First, we set `box.isPickable` to false to avoid the ray touching the box from the inside _(line #16)_.
Because we set the starting point (origin) of the ray in the center of the box.

The most important part is to get the correct direction vector _(line #57)_:

```javascript
var forward = new BABYLON.Vector3(0, 0, 1);
forward = vecToLocal(forward, box);

var direction = forward.subtract(origin);
direction = BABYLON.Vector3.Normalize(direction);
```

We want the forward vector relative to the box space and orientation.
Then, to get the direction, we subtract it from the origin, the box position.
The function `vecToLocal` is designed to transform a position from a mesh point of view by multiplying a vector by the mesh matrix.

Then, we create the ray with all elements given and a length of 100 for example _(line #65)_:

```javascript
var ray = new BABYLON.Ray(origin, direction, length);
```

Finally, we get the hit point of the ray if it touches a mesh _(line #68)_:

```javascript
var hit = scene.pickWithRay(ray);
```

And if a mesh is hit, we can do whatever we want with the picking info, such as getting the mesh name or the position of the point.
Here we change its size because it's more fun!

**You're not forced to set `box.isPickable` to false**, if you need later to check rays intersection on this box for example.
You can set the origin point of the vector in front of the box, the direction a little further and the length that you want _(line #55)_:

 <Playground id="#KNE0O#17" title="Ray Picking Example" description="Simple example of ray picking."/>

## Predicate function

It is a filter to choose which meshes will be selectable:

<Playground id="#KNE0O#18" title="Predicate Function Example" description="Simple example of the predicate function with ray picking."/>

![Raycast predicate](/img/how_to/raycast02.webp)

We added a new function predicate _(line #54)_:

```javascript
function predicate(mesh) {
  if (mesh == box2 || mesh == box) {
    return false;
  }
  return true;
}
```

and in parameter here:

```javascript
scene.pickWithRay(ray, predicate);
```

The `isPickable = false` argument becomes irrelevant, so we have to exclude the box.
We also exclude box2 for testing and allow the rest, box3 and box4 by default.

And the result is, only box3, the second blue one behind, and box4 will grow.
So it works as if box2 were transparent to the ray!

There is one other optional argument to the method `pickWithRay`. It's the boolean **fastCheck** (`false` by default).
`True` will return the first mesh that intersects with the ray (in the order of the meshes array), not the closest mesh to the ray's starting point.

## Triangle predicate

Starting with Babylon.js v4.0 you can define a custom predicate to filter the triangles selected to be tested against the incoming ray. The predicate will be called with the 3 vertices of each face and the upcoming ray:

```javascript
scene.pick(scene.pointerX, scene.pointerY, null, false, null, (p0, p1, p2, ray) => {
  var p0p1 = p0.subtract(p1);
  var p2p1 = p2.subtract(p1);
  var normal = BABYLON.Vector3.Cross(p0p1, p2p1);
  return BABYLON.Vector3.Dot(ray.direction, normal) < 0;
});
```

In this example we are filtering out all the triangles that are not facing towards the camera.

Live example: <Playground id="#EES9W5" title="Triangle Predicate" description="Simple example of ray picking with a triangle predicate."/>

---

## Multi pick

We can use `scene.multiPickWithRay` if we don't want the ray to stop at the first obstacle:

 <Playground id="#KNE0O#19" title="Get All Meshes Hit By Ray" description="Simple example of getting all meshes hit by a ray."/>

![Raycast multipick](/img/how_to/raycast02.webp)

The picking result will be an array _(line #68)_.

We can loop through the array to change all meshes hit. In the example you can see that the two blue boxes change in size.
It's like a strong bullet!

## Alternative picking methods
Another method of picking with a ray is to directly use the **Ray class**. There is one caveat to this method, however. When using `pickWithRay`, the method automatically transforms the ray from world coordinates to the local coordinates of the mesh being picked. If you want to use the **Ray class** itself, the conversion from the world coordinates of the ray to the local space of an intersecting mesh must be done manually. 

To do this, first create a ray and mesh to check for intersection, then convert the ray into the local space of the mesh to determine the correct intersection point on the mesh.

```javascript
// create a mesh to intersect
let box = BABYLON.MeshBuilder.CreateBox("box", {size: 1.0}, scene);

// define the ray origin, direction, and length
let origin = new BABYLON.Vector3(0.0, 0.0, 1.5);
let dir = new BABYLON.Vector3(0.0, 0.0, -1.0);
let length = 5.0;

// create the ray
let myRay = new BABYLON.Ray(origin, dir, length);

// use the ray helper to render the ray in the scene
let rayHelper = new BABYLON.RayHelper(myRay);
rayHelper.show(scene);

// transform the ray into the local space of the mesh to get an accurate intersection point - in this case we are using the inverse of the mesh's world matrix to transform
BABYLON.Ray.Transform(myRay, box.getWorldMatrix().invert())
```

Then simply check if the ray intersects the mesh and capture the picking information.

```javascript
// check to see if the ray intersects the mesh and capture the pick information
let pickingInfo = myRay.intersectsMesh(box);
```

<Playground id="#2IETSS" title="Picking a mesh with Ray.intersectsMesh" description="Simple alternative method for picking meshes."/>

## Picking Ray

Another handy feature is the createPickingRay. This special ray is cast from a camera, out to infinity, in the direction of the cursor (relative to the virtual lens). Confusing? Basically think of it as a ray that's cast out of the camera and 'aimed' by the cursor. This is another method for picking objects in your scene. Here's a playground and video to check out on the subject.

 <Playground id="#AC8XPN#81" title="Picking Ray Example" description="Simple example of using a picking ray."/>

<Youtube id="dgsWKpa7RcY"/>

## Debugging

It can be hard to understand where a ray starts and what its direction is. To help you debug, you can use the RayHelper.

You can either use a static function to create and show one:

```javascript
BABYLON.RayHelper.CreateAndShow(ray, scene, new BABYLON.Color3(1, 1, 0.1));
```

or you can use a more detailed version:

```javascript
var rayHelper = new BABYLON.RayHelper(ray);
rayHelper.show(scene);
```

The helper can also be attached to a mesh to track its direction:

```javascript
var localMeshDirection = new BABYLON.Vector3(0, 0, -1);
var localMeshOrigin = new BABYLON.Vector3(0, 0, -0.4);
var length = 3;
rayHelper.attachToMesh(box, localMeshDirection, localMeshOrigin, length);
```

<Playground id="#ZHDBJ#48" title="Picking and Debugging" description="Simple example of ray picking and debugging."/>

## GPU Picking

Picking can be an expensive feature to use as the CPU has to go through all the geometries to find the closest triangle which is intersecting with the picking ray.

Starting with Babylon v8.0, you can now use the GPU for your picking needs. This will mostly be useful if you have very complex objects where scanning all the triangles will kill your performance:

```javascript
var picker = new BABYLON.GPUPicker();
picker.setPickingList(myMeshes);

scene.onPointerObservable.add(() => {
  if (picker.pickingInProgress) {
    return;
  }
  picker.pickAsync(scene.pointerX, scene.pointerY, scene, false).then((pickingInfo) => {
    if (pickingInfo) {
      console.log(pickingInfo.mesh.name);
    }
  });
});
```

As you can see, you only need to create a `GPUPicker`, define the list of pickable meshes, and call the `pickAsync` function.

The system will then render the scene onto a texture and read from that texture at the given coordinates. Each mesh is rendered with a unique color, so the picker can return the picked mesh.

Thanks to the call to `setPickingList`, the picker can prepare all the instances and associate a new vertex buffer to store their unique colors.

<Playground id="#XJKQOC#14" title="GPU picking" description="Simple example of how to use GPU picking."/>

Please note that if you pick a mesh with thin instances then the `pickingInfo.thinInstanceIndex` will give you the index of the picked thin instance if any.

### GPU Multi picking

You can perform a picking operation on multiple coordinates at once by using `picker.multiPickAsync(coordinates: IVector2Like[])`. The function returns `Promise<BABYLON.IGPUMultiPickingInfo>`. 

```typescript
export interface IGPUMultiPickingInfo {
    /**
     * Picked mesh
     */
    meshes: Nullable<AbstractMesh>[];
    /**
     * Picked thin instance index
     */
    thinInstanceIndexes?: number[];
}
```

The `meshes` property always has the length of the array of meshes you set with the `picker.setPickingList` function, so you can use index-based lookup for a picking hit. If a `mesh` was not picked, the `meshes` property contains `undefined` at the given index. The `thinInstanceIndexes` property works the same way and returns indexes just as `pickAsync` does.

Before you can use multi picking, you have to set the meshes you intend to pick with `setPickingList`, just as you do when performing single picking.

You can use multi picking for occlusion detection, as demonstrated in the following Playground:

<Playground id="#GAB1RS#63" title="GPU Multipicking example" description="Demonstrates how can you use multipicking to get occlusion statuses of multiple meshes."/>

Multi picking is optimized and always renders only a portion of the picking texture defined by an area from the minimum to the maximum picking coordinates. If this area is too big, you should consider calling `multiPickAsync` multiple times with smaller areas or calling `pickAsync` multiple times with a single coordinate. 

### Important

The following applies to meshes in the picking list. Due to performance reasons, checks are not performed. It is up to the user to ensure all pickable meshes follow simple rules.

* All meshes in the picking list should always be enabled.
* Mesh enabled states are not checked when picking. If you have a pickable mesh with `mesh.setEnabled(false)`, pick results will be invalid. If you really need to disable a mesh, remove it from the picking list first, update the pick texture with `picker.setPickingList([...newList])`, then disable your mesh.
* Any instances in the picking list must also be accompanied by their root mesh, even if it is not meant to be picked.
* Any instances added/removed from the picking list needs a `picker.setPickingList([...list])` to update the pick texture. If you have to dispose said instance, remove instance from the picking list first, dispose said instance and then call `picker.setPickingList([...newList])`.
* For thin instances, if you make any changes to the matrix buffer, ie, add/remove thin instances, you have to call `picker.setPickingList([...list])` to update the pick texture after.
* GPU picking works with `mesh.visibility = 0` and `mesh.material.alpha = 0` but not with `mesh.isVisible = false`.
* `renderOverlay` does not work with GPU picking for meshes (no instances/thin instances) and cloned meshes.



## Interactions
Possibly the most important interactions are user interactions, such as picking a mesh in the scene. These can be achieved with scene observables.

You also often need to find whether two meshes are intersecting, or determine the position of a mesh relative to another mesh, a camera, or a point in space. In Babylon.js, these can be achieved using *intersectsMesh* for two meshes, and *Ray* and *intersect* for ray casting.


## How to use Thin Instances
Starting with Babylon.js v4.2, thin instances are a feature of meshes.

PG: <Playground id="#V1JE4Z#1" title="Thin Instances Example" description="Simple example of using thin instances."/>

As explained in [How To Use Instances](/features/featuresDeepDive/mesh/copies/instances), instances are an excellent way to use hardware-accelerated rendering to draw a huge number of identical meshes.

However, regular instances still have a performance penalty on the JavaScript side because each instance is its own object (`InstancedMesh`): if you have 10000 instances in your scene, the engine must loop over all those objects to perform a number of operations (visibility checks, etc.).

Thin instances don't create new objects, so you don't incur any penalty on the JavaScript side by having thousands of them. This performance increase does come with a cost:
* either all thin instances are drawn (if the mesh is deemed visible) or none are. It's all or nothing.
* adding / removing a thin instance is more costly than with `InstancedMesh`

Thin instances should be used when you need a lot of static instances that you know won't change often, if at all. Think of the seats in a stadium, for example.

So, regular instances may still be the way to go, depending on your scene: if you have a lot of objects scattered and only a few are visible in a frame, or if you must add/remove instances continuously, it may be better to use instances than thin instances.

<Youtube id="0DaSvI_n7Us"/>

## Creating thin instances
A thin instance is represented by a position/rotation/scaling data packed into a matrix.

The easiest way to create a thin instance is by doing:
```javascript
var matrix = BABYLON.Matrix.Translation(-2, 2, 0);
var idx = sphere.thinInstanceAdd(matrix);
```

You can also pass an array of matrices to `thinInstanceAdd` if you want to create multiple thin instances at once.

Note that `sphere` itself is not rendered. If you want to render it, use `thinInstanceAddSelf()`:
```javascript
var idx2 = sphere.thinInstanceAddSelf();
```

These methods return an index that you can use to reference the thin instance.

For example, you can update a thin instance afterwards:
```javascript
var matrix2 = BABYLON.Matrix.Translation(2, 1, 0);
sphere.thinInstanceSetMatrixAt(idx2, matrix2);
```

Example: <Playground id="#217750" title="Creating Thin Instances" description="Simple example of creating thin instances."/>

Those three methods take an additional `refresh` parameter (`true` by default) that allows you to block the buffer refresh mechanism to improve performance: if you must use those methods multiple times, pass `false` for all calls except the last one.

The bounding info of the mesh is recomputed each time you call these methods to encompass all the thin instances (except if you set `doNotSyncBoundingInfo` to `true`). You can also refresh explicitly the bounding info by calling `thinInstanceRefreshBoundingInfo`.

## Custom attributes
As for regular instances, you can add custom attributes to thin instances.

To do so, register the attribute and set the value(s) for the thin instance(s):
```typescript
sphere.thinInstanceRegisterAttribute("color", 4);

sphere.thinInstanceSetAttributeAt("color", idx, [1, 1, 0, 1]);
sphere.thinInstanceSetAttributeAt("color", idx2, [1, 0, 0, 1]);
```

As the thin instance indexes are really indexes into the underlying buffer, you can set the values for several thin instances at once:
```typescript
sphere.thinInstanceRegisterAttribute("color", 4);

sphere.thinInstanceSetAttributeAt("color", 0, [1, 1, 0, 1, 1, 0, 0, 1]);
```

Example: <Playground id="#217750#1" title="Thin Instances Custom Attributes" description="Simple example of thin instances with custom attributes."/>

You can get or set the number of thin instances to display through the `thinInstanceCount` property.

Note that you can't set a number that is higher than what the underlying buffer can handle!

Set the number to 0 to bypass the thin instance rendering and render the mesh as usual.

## Faster thin instances
To get the most out of thin instance support, you can directly pass the pre-built buffer of matrices / custom attributes:
```typescript
var matrix1 = BABYLON.Matrix.Translation(-2, 2, 0);
var matrix2 = BABYLON.Matrix.IdentityReadOnly;
var matrix3 = BABYLON.Matrix.Translation(2, 1, 0);

var bufferMatrices = new Float32Array(16 * 3);

matrix1.copyToArray(bufferMatrices, 0);
matrix2.copyToArray(bufferMatrices, 16);
matrix3.copyToArray(bufferMatrices, 32);

var bufferColors = new Float32Array(3 * 4);

bufferColors.set([1, 1, 0, 1, 1, 0, 0, 1, 0, 1, 0, 1]);

sphere.thinInstanceSetBuffer("matrix", bufferMatrices, 16);
sphere.thinInstanceSetBuffer("color", bufferColors, 4);
```

Example: <Playground id="#217750#2" title="Thin Instances Example" description="Simple example showing how to use thin instances."/>

If you have a lot of thin instances to create, this can be much faster than calling `thinInstanceAdd` / `thinInstanceSetAttributeAt`. You can also allocate a bigger buffer than what you really need at the start and use the `thinInstanceCount` property to adjust the number of instances to display during the course of your program.

Note that you don't need to call `thinInstanceRegisterAttribute` if you set a custom attribute buffer by calling `thinInstanceSetBuffer`.

If you update the buffers you passed to `thinInstanceSetBuffer`, you must call `thinInstanceBufferUpdated` for the changes to take effect.

However, for performance reasons, buffers are not updateable by default. If you plan to update a buffer later, you must make it updateable by passing **false** for the **static** flag (4th parameter of `thinInstanceSetBuffer`):

```javascript
sphere.thinInstanceSetBuffer("matrix", bufferMatrices, 16, false); // matrix buffer is updateable
sphere.thinInstanceSetBuffer("color", bufferColors, 4, true); // color buffer is not updateable
```

## Support

Thin instances are supported for collisions, picking, rendering and shadows. However, for collisions, a single bounding info encompassing all the thin instances is used to check intersection: the check is not done for each thin instance separately.

Here's an example of thin instances picking: <Playground id="#RC2IAH#115" title="Thin Instances Picking Example" description="Simple example of using picking with thin instances."/>

## Limitations

* Thin instances with mixed positive and negative determinant matrices won't be rendered correctly. If you need thin instances with both positive and negative determinants, create two meshes and add the thin instances to one or the other (don't forget to set the `sideOrientation` property properly for both mesh materials!).

For example: <Playground id="#217750#3" title="Thin Instances Wrong Rendering" description="Simple example of thin instances with wrong rendering."/>

![Wrong rendering](/img/how_to/Mesh/thinInstancesWrongSideOrientation.webp)

The green and blue cubes are not rendered correctly because they have a -1 scale for the X direction, making the determinant of their matrix negative.

To correct the problem, create another mesh, add the green/blue instances to that mesh (and remove them from the first mesh!) and set the side orientation of the material of that mesh to be **Clockwise** (by default, it is **Counter clockwise**):

PG: <Playground id="#217750#4" title="Thin Instances Correct Rendering" description="Simple example of thin instances with correct rendering."/>
![Correct rendering](/img/how_to/Mesh/thinInstancesOkSideOrientation.webp)

* If you want to create a thin instance from a cloned mesh, you have to first make sure that you call clonedMesh.makeGeometryUnique().

* When using motion blur, the engine needs to store world matrices of the previous frame to compute velocity. Usually, this part is taken care of internally, but in certain cases you may have to specify these matrices manually. You may in fact see weird blurring artifacts if you decide to change the world matrix buffer layout, like changing the number of matrices it contains, or using a different order. In that case, you will have to keep a second buffer, storing previous world matrices, and updating it by writing :

```javascript
mesh.thinInstanceSetBuffer("previousMatrix", instancedPreviousBuffer, 16);
```

Here is an example of reordering world matrices inside the buffer in each frame, using a different start offset. Previous world matrices are stored and updated, to use motion blur correctly :
<Playground id="#HJGC2G#59" title="Thin instances previous matrices motion blur" description="Updating manually previous world matrices for thin instances to work with motion blur"/>


Interactions

Interactions

Coming next

Mesh Picking

Learn how to pick meshes in Babylon.js.

Mesh Intersections

Learn all about mesh intersections in Babylon.js.