
## Clone
This simply creates a deep copy of the original mesh and saves memory by sharing the geometry. Each clone can have its own material and transformation.

## Examples
Shows shared geometry by scaling one geometry by 2: <Playground id="#QMFPPE" title="Cloning Example 1" description="Simple example showing shared geometry by scaling one geometry by 2." image=""/> 
Shows transformation by scaling of 2 only changes one mesh: <Playground id="#QMFPPE#1" title="Cloning Example 2" description="Simple example showing transformation by scaling of 2 only changes one mesh." image=""/>
Different materials:  <Playground id="#QMFPPE#1" title="Cloning Example 3" description="Simple example of clones with different materials." image=""/>


## How to use Instances
Instances are an excellent way to use hardware accelerated rendering to draw a huge number of identical meshes (let's imagine a forest or an army).

Instances are built from a mesh with the following code:

```javascript
// In this case we're loading our mesh from an external source.
BABYLON.SceneLoader.ImportMesh("", "//www.babylonjs.com/assets/Tree/", "tree.babylon", scene, function (newMeshes) {
    var mesh = newMeshes[0];
    // Make the "root" mesh not visible. The instanced versions of it that we
    // create below will be visible.
    mesh.isVisible = false;
    for (var index = 0; index < 100; index++) {
        var newInstance = mesh.createInstance("i" + index);
        // Here you could change the properties of your individual instance,
        // for example to form a diagonal line of instances:
        //  newInstance.position.x = index;
        //  newInstance.position.z = index;
        // See below for more details on what can be changed.
    }
});
```
A mesh can have as many instances as you want.

Each instance has the same material as the root mesh. They can vary on the following properties:
* ```position```
* ```rotation```
* ```rotationQuaternion```
* ```setPivotMatrix```
* ```scaling```

Note: related are **thin instances**, if you want yet more performances but with less control on each instance. See the [dedicated page](/divingDeeper/mesh/copies/thinInstances) for further information.

## Instancing a glTF object

When you instanciate a glTF object, you need to make sure that the new instance will be under the same parent or you need to remove the parent from the source object.

This is because every gltf file comes from a right handed world. To get it into Babylon.js left handed world, we are adding an arbitrary parent that is adding a negative scale on z.

So when instancing a glTF object you have to (either):
- Call `source.setParent(null)`
- Or call `newInstance.setParent(source.parent)`

## Custom buffers

You also have the opportunity to specify per instance values for any attribute. For instance (no pun intended), if you want to have a specific color per instance, you only need to provide a vertex buffer flagged as "instanceable" and fill it with a color per instance:

```javascript
let instanceCount = 1000;
let colorData = new Float32Array(4 * instanceCount);

for (var index = 0; index < instanceCount; index++) {
    colorData[index * 4] = Math.random();
    colorData[index * 4 + 1] = Math.random();
    colorData[index * 4 + 2] = Math.random();
    colorData[index * 4 + 3] = 1.0;
}

var buffer = new BABYLON.VertexBuffer(engine, colorData, BABYLON.VertexBuffer.ColorKind, false, false, 4, true);
box.setVerticesBuffer(buffer);
```

The last parameter of the VertexBuffer constructor is the one to set to true to flag it as instanceable.

Example: <Playground id="#8L50Q3#1" title="Custom Buffers Example 1" description="Simple example of custom buffers." image=""/>

The other way is to register a custom buffer with `registerInstancedBuffer`:
```javascript
mesh.registerInstancedBuffer("color", 4); // 4 is the stride size eg. 4 floats here
```

Using this API, you can specify a new buffer that will be instancied. This means that each instance will have its own value. You can specify this value on the root mesh and on every single instance:

```javascript
box.instancedBuffers.color = new BABYLON.Color4(Math.random(), Math.random(), Math.random(), 1);
let instance = box.createInstance("box1");
instance.instancedBuffers.color = new BABYLON.Color4(Math.random(), Math.random(), Math.random(), 1);
```

The system will take care of updating the internal vertex buffer.

Example: <Playground id="#YPABS1" title="Custom Buffers Example 2" description="Simple example of custom buffers." image=""/>

## Advanced control

You can decide to control the world matrix instanced buffer the same way you control the custom buffers.

To do so, just run the following code:
```javascript
mesh.manualUpdateOfWorldMatrixInstancedBuffer = true;
```

When this mode is activated, you can update the world matrix instanced buffer with this code:
```javascript
mesh.worldMatrixInstancedBuffer.set(mat, offset); // mat is the matrix you want to store at the given offset
offset += 16; (a matrix is composed of 16 floats
```

It is recommended to freeze the active meshes when controling the world matrix instanced buffer to avoid having a discrepancy between the values you store and the number of active instances:
```javascript
scene.freezeActiveMeshes(true);
```

You can find a complete example here: <Playground id="#HJGC2G" title="Instancing Advanced Control" description="Simple example of instancing advanced controls." image=""/>

## Support

Instances are supported for collisions, picking, rendering and shadows. Even if the current hardware does not support hardware accelerated instances, babylon.js will be able to optimize rendering to take instances into account.

## Using 3D modeler to create instances

## Blender

Using Blender, you can create instances of a mesh by just creating a linked object:

![](/img/how_to/use-instance/blender-linked-object.jpg)

## 3DS Max

Using 3DS Max, you can create instances of a mesh by just creating a clone instance object with clic right on the object:

![](/img/how_to/use-instance/3ds-linked-object.jpg)

## Limitations

* You can use instances with LOD but one limitation will apply in this case: You will have to hide the root objects.
Here is an example where LODs reuse instances:
<Playground id="#0720FC#10" title="Instances and LODs" description="Simple example of instancing and LODs." image=""/>

* If you want to create an instance from a cloned mesh, you have to first make sure that you call clonedMesh.makeGeometryUnique().

* Instances with a world matrix where determinant is different than root mesh world matrix will be rendered separately (like a regular mesh). This mostly happens when the sign of the scaling vector is different between an instance and the root mesh.

## Demos
- Trees: <Playground id="#YB006J#75" title="Instancing Trees Example" description="Simple example of instancing with trees." image=""/>
- 10,000 Icospheres: <Playground id="#c2ynt9#12" title="10,000 Icospheres" description="Simple example of instancing with 10,000 icospheres." image=""/>


## Using the Solid Particle System to Copy Meshes
There is more to the Solid Particle System (SPS) than just producing multiple copies of a mesh and these are considered in full in the Particles section. The SPS places multiple copies of a mesh all together into just one mesh. This means that instead of multiple draw calls there is just one draw call for the single mesh.

The SPS is a single updatable mesh with the same properties as any other Babylon.js  mesh.

In order to produce multiple copies of a mesh you follow this script

Example :
```javascript
SPS = new BABYLON.SolidParticleSystem("SPS", scene);  //create the SPS
const tetra = BABYLON.MeshBuilder.CreatePolyhedron("tetra", {}); //create the mesh
SPS.addShape(tetra, 1500);      // add as many copies as you want to the SPS
tetra.dispose(); //ddispose of the original mesh
const spsMesh = SPS.buildMesh();  //builds the SPS mesh

//Set the function to intialise the particle properties
SPS.initParticles = () => {
    for (let p = 0; p < SPS.nbParticles; p++) {
        const particle = SPS.particles[p]  
        particle.position.x = BABYLON.Scalar.RandomRange(-50, 50);
        particle.position.y = BABYLON.Scalar.RandomRange(-50, 50);
        particle.position.z = BABYLON.Scalar.RandomRange(-50, 50);
    
        const scale = BABYLON.Scalar.RandomRange(0.5, 1.5);;
        particle.scale.x = scale;
        particle.scale.y = scale;
        particle.scale.z = scale;

	        particle.rotation.x = BABYLON.Scalar.RandomRange(0, Math.PI);
	        particle.rotation.y = BABYLON.Scalar.RandomRange(0, Math.PI);
	        particle.rotation.z = BABYLON.Scalar.RandomRange(0, Math.PI);
    }
} ;


SPS.initParticles(); //call the initialising function
SPS.setParticles(); //apply the properties and display the mesh
```

## Example
Copying a tetrahedron: <Playground id="#GKUCQP" title="Copying a Tetrahedron" description="Simple example of copying a tetrahdedron." image="/img/playgroundsAndNMEs/PGNMEProceduralTexture.jpg"/>


## 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." image=""/>

As explained in [How To Use Instances](/divingDeeper/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.

## 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." image=""/>

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." image=""/>

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." image=""/>

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 and picking, a single bounding info encompassing all the thin instances is used to check intersection: the check is not done for each thin instance separately.

## 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." image=""/>

![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." image=""/>
![Correct rendering](/img/how_to/Mesh/thinInstancesOkSideOrientation.png)


## How To Rotate Around an Axis About a Point

Rotation needs two things specifying, they are an axis and a center of rotation with the axis passing through the center of rotation. An axis is defined by a direction vector and the center of rotation a position vector. In Babylon.js when a mesh is created the center of rotation defaults to the the local origin of the mesh which is the mesh's position. Using [rotation](/divingDeeper/mesh/transforms#rotation) the axis is specified through the Euler angles alpha, beta, gamma, and using [rotationQuaternion](/divingDeeper/mesh/transforms) and [rotate](/divingDeeper/mesh/transforms#rotate) it is specified explicitly.

There are three ways to change a center of rotation different to the local origin, these are using a [TransformNode](/divingDeeper/mesh/transforms/parent_pivot/transform_node), a parent and [setting a pivot](/divingDeeper/mesh/transforms/parent_pivot/pivots).

Together an axis and a center of rotation define a straight line in space and in the following animated playgrounds this line is shown in white. The asymmetric pilot mesh is used to demonstrate the rotation.

![The Pilot](/img/how_to/Mesh/pilot.jpg)
The Pilot

In each of the following examples there is

-   a center of rotation at CoR_At;
-   a marker mesh for the center of rotation, a small sphere positioned at CoR_At;
-   an axis to rotate around
-   the pilot mesh at a starting position relative to the center of rotation, pilotStart.

## How to Use TransformNode as a Center of Rotation

A TransformNode is an object that is not rendered but can be used as a center of rotation (in fact the centre of any transformation). This can decrease memory usage and increase rendering speed.

The TransformNode is used as a pivot point by parenting it to the pilot and rotating it.

```javascript
var pivot = new BABYLON.TransformNode("root");
pivot.position = CoR_At;

pilot.parent = pivot;
pilot.position = pilotStart;

pivot.rotate(axis, angle, BABYLON.Space.WORLD);
```

In these playgrounds a sphere is created only to show the position of the TransformNode.

<Playground id="#1JLGFP#36" title="Rotating TransformNode" description="Simple example of a Rotating TransformNode." image=""/>
<Playground id="#C12LH3#3" title="Rotating Mesh Moving TransformNode along Axis" description="Simple example of a rotating mesh moving TransformNode along axis." image=""/>
<Playground id="#C12LH3#4" title="Rotating Mesh Moving TransformNode" description="Simple example of a rotating mesh moving TransformNode." image=""/>

## How To Use a Parent as Center of Rotation

The sphere is parented to the pilot, the pilot positioned and the sphere rotated.

```javascript
sphere.position = CoR_At;

pilot.parent = sphere;
pilot.position = pilotStart;

sphere.rotate(axis, angle, BABYLON.Space.WORLD);
```

**Note:** Any movement of the sphere will result in the pilot being moved.

<Playground id="#1JLGFP#31" title="Rotating Parent" description="Simple example of a rotating parent." image=""/>

## How To Use a Pivot as a Center of Rotation

```javascript
var CoR_At = new BABYLON.Vector3(1, 3, 2);
var pilotStart = new BABYLON.Vector3(3, 6, 6);

pilot.position = pilotStart;

var pivotTranslate = pilotStart.subtract(CoR_At);
pilot.setPivotMatrix(BABYLON.Matrix.Translation(pivotTranslate.x, pivotTranslate.y, pivotTranslate.z));
```

```javascript
/*-------------------Rotation Animation--------------------*/
var angle = 0.025;
scene.registerAfterRender(function () {
    pilot.rotate(axis, angle, BABYLON.Space.LOCAL);
});
```

<Playground id="#C12LH3#7" title="Rotating Mesh with Pivot" description="Simple example of a rotating mesh with pivot." image=""/>
<Playground id="#C12LH3#8" title="Rotating Mesh Moving Pivot along Axis" description="Simple example of a rotating mesh moving pivot along axis." image=""/>

Notice that as the pivot is moved the axis line moves with the pivot, though the axis direction remains the same.  
<Playground id="#C12LH3#9" title="Rotating Mesh Moving Pivot" description="Simple example of a rotating mesh moving pivot." image=""/>

## How to Use a Pivot as a Parent

Perhaps you would like to think about achieving the positioning of the pivot by changing the pivots position rather than the pilots position. This can be done with parenting as shown in the following example.

The sphere, representing the pivot at the center of rotation, is placed at the pivot position (CoR_At), the sphere is then made the parent of the pilot the pilot position relative to the pivot is set by matrix and the pilot rotated.

```javascript
sphere.position = CoR_At;

pilot.parent = sphere;
pilot.setPivotMatrix(BABYLON.Matrix.Translation(pilotTranslate.x, pilotTranslate.y, pilotTranslate.z));

pilot.rotate(axis, angle, BABYLON.Space.WORLD);
```

<Playground id="#1JLGFP#77" title="Rotating Mesh as Pivot's Child" description="Simple example of a rotating mesh as pivot's child." image=""/>

Done this way any movement of the pivot is done by moving the parent mesh representing the pivot.  
<Playground id="#1JLGFP#78" title="Rotating Mesh Moving Pivot's Parent along Axis" description="Simple example of a rotating mesh moving pivot's parent along axis." image=""/>
<Playground id="#1JLGFP#80" title="Rotating Mesh Moving Pivot's Parent" description="Simple example of a rotating mesh moving pivot's parent." image=""/>


Copies, Clones, and Instancing

Copies, Clones and Instances

Coming next

Clones

Learn clones and cloning in Babylon.js.

Cloning With the Solid Particle System

Learn how to clone using the solid particle system in Babylon.js.

Instances

Learn all about the instancing system in Babylon.js.

Thin Instances

Learn how to leverage thin instances in your Babylon.js scenes.