
## 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 is going to show you two ways of collision detection: the first one is to raise a collision event when two meshes are in contact, the other one is detecting contact between a mesh and a single point.

We are going to talk about the scene above. The first and second sphere (balloon) will collide on the rotated ground, the last one will be in collision only on 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 calculation by checking many details on a mesh, Babylon engine creates a bounding box around the object, and tests for intersection 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’s a more costly calculation. Be aware that this type of bounding box is especially useful when your mesh is rotated to an angle.

![Collisions](/img/how_to/Collisions%20Intersect/10-2.png)

So think about the collisions details you need before to choose.

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, wherever on the balloon, then the event is raised 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 ray from any point and in any direction.
For example in a shooting game at 3rd person view: 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.jpg)

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)_.
A ray requires when its created: 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 good directional 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 multiplicating 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 do what we want with the picking info like getting the mesh name, the position of the point etc...
Here we change its size because it's funnier!

---

**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.jpg)

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 avoid box.
We avoid also 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 fine like if box2 was transparent for 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 that 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.jpg)

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!

---

An other method is to use directly the **Ray class**.

To change the ray to a local space :

```javascript
Ray.Transform(ray, matrix) → Ray
```

Checking intersection:

```javascript
Ray.intersectsMesh(mesh, fastCheck) → PickingInfo
```

---

## 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" title="Picking Ray Example" description="Simple example of using a picking ray."/>

<Youtube id="dgsWKpa7RcY"/>

---

An other method is to use directly the **Ray class**.

To change the ray to a local space :

```javascript
Ray.Transform(ray, matrix) → Ray
```

Checking intersection:

```javascript
Ray.intersectsMesh(mesh, fastCheck) → PickingInfo
```

---

## Debugging

It could be tough to understand where a ray starts and is its direction. To help you debug you can then 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 detailled 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."/>


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


## How to use Thin Instances
Starting with Babylon.js v4.2, thin intances are a new 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 make a number of processing (visibility check, 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:
* all thin instances are always all drawn (if the mesh is deemed visible) or none. 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 / at all. Think of the seats of a stadium, for eg.

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 3 methods take an additional `refresh` parameter (`true` by default) that allows you to block the buffer refresh mechanism to save performances: if you must use those methods multiple times, pass `false` for all calls except for 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 explicitely 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 of the 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, it could be a lot faster than calling `thinInstanceAdd` / `thinInstanceSetAttributeAt`. Also, you can allocate a bigger buffer than what you really need at start and play with 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.

To gain some performances, you can flag the buffers as **static**, meaning you won't change them later on. This way, the system can apply some optimizations to your buffers.

To do so, pass `true` for the 4th parameter of `thinInstanceSetBuffer`:
```javascript
sphere.thinInstanceSetBuffer("matrix", bufferMatrices, 16, true);
sphere.thinInstanceSetBuffer("color", bufferColors, 4, true);
```

## 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#1" 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 eg: <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.png)

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.png)

* 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 Intersections

Learn all about mesh intersections in Babylon.js.

Mesh Picking

Learn how to pick meshes in Babylon.js.