
# How To Add Your Own Physics Engine

## Define your plugin
You can create your own plugin by creating a class that provides the interface defined in this TypeScript file : https://github.com/BabylonJS/Babylon.js/blob/master/packages/dev/core/src/Physics/IPhysicsEngine.ts

For implementation details, you can refer to cannon.js plugin: https://github.com/BabylonJS/Babylon.js/tree/master/packages/dev/core/src/Physics/Plugins/cannonJSPlugin.ts

## Using your plugin
When you launch the physics simulation, you can add a new parameter to ```enablePhysics``` function to indicate which plugin to use:

```javascript
scene.enablePhysics(null, new BABYLON.CannonJSPlugin()),
```

The first parameter can be used to define gravity (which is (0, -9.807, 0) by default).


# How To Use Advanced Physics Features

## The Heightmap

One of the best way of interacting with a ground object is the Heightmap impostor (supported currently only with the CannonJS plugin).

A heightmap is not a mesh impostor. It is possible that objects coming from the side will not collide with it. The heightmap impostor takes the height Y value at a certain point in a mesh and sets a collision point. To understand what a heightmap impostor is, think of a regular house with a triangle roof. If we set the heightmap impostor to the house, the only part that will have collision detection is the roof. Anything below the roof will be ignored, including the walls.

On the positive side, a heightmap can collide with most other objects, as opposed to the mesh impostor which only collides against spheres. Performance is also much better with a heightmap than with a mesh impostor.

There are certain conditions in which a heightmap can be initialized:

* It must be square (x === z). The most important values are the y values in each point of the heightmap.
* It cannot contain holes or missing textures
* It is recommended that the heightmap be generated from a GroundMesh, generated from a heightmap image

To create a ground from an image-based ground mesh:

```javascript
var ground = BABYLON.Mesh.CreateGroundFromHeightMap("ground", "textures/worldHeightMap.jpg", 200, 200, 50, 0, 30, scene, false, function () {
    ground.physicsImpostor = new BABYLON.PhysicsImpostor(ground, BABYLON.PhysicsImpostor.HeightmapImpostor, { mass: 0 });
});
```

To create a heightmap from a square ribbon:

```javascript
var exponentialPath = function (p) {
    var path = [];
    for (var i = -50; i <= 50; i++) {
        path.push(new BABYLON.Vector3(p-50, (Math.sin(p / 3) * 10 * Math.exp((i - p) / 100) + i / 3), i));
    }
    return path;
};
// let's populate arrayOfPaths with all these different paths
var arrayOfPaths = [];
for (var p = 0; p <= 100; p++) {
    arrayOfPaths[p] = exponentialPath(p);

}

var mesh = BABYLON.Mesh.CreateRibbon("ribbon", arrayOfPaths, false, false, 0, scene);
mesh.physicsImpostor = new BABYLON.PhysicsImpostor(mesh, BABYLON.PhysicsImpostor.HeightmapImpostor, { mass: 0, friction:1, restitution: 0.5 });
```

A demo for both of these examples can be found here - 
<Playground id="#D3LQD#7" title="Creating Ground From An Image-Based Ground Mesh" description="Simple example of creating ground from an image based ground mesh."/>
<Playground id="#EXL6K#9" title="Creating A Heightmap From A Square Ribbon" description="Simple example of creating a heightmap from a square ribbon."/>

## Mesh Impostor

A mesh impostor wraps a complex mesh with a physics body, allowing exact collision detection with the object. As opposed to the heightmap impostor, a mesh impostor has the entire mesh covered.

A mesh impostor is only available with cannon.js, and only collides against spheres.

Regarding performance - you will notice that the mesh impostor doesn't influence performance too much, until an object collides against it. Then the calculations are rather complex and can lower your FPS significantly, depending on the mesh's complexity.

A simple example of the mesh impostor can be found here - <Playground id="#3B3135#1" title="Mesh Imposter Example" description="Simple example of a mesh imposter."/>

To generate a mesh impostor, simply set the MeshImpostor type when creating the physics impostor of the mesh:

```javascript
mesh.physicsImpostor = new BABYLON.PhysicsImpostor(mesh, BABYLON.PhysicsImpostor.MeshImpostor, {mass: 0});
```

The rest will be done by Babylon and the physics engine.

A wonderful example of the abilities of the mesh impostor can be found here - https://ajna4taiga.tk/PerplexusShadowOpen/Home.html

## Motors

Certain joint types like the wheel (hinge) joint have the ability to run a motor that will move the impostor connecting to the joint in the direction set by the user.

Motors can be used to move a wheel of a car, to simulate an elevator or create a gear system. The motor is responsible to enable the circular movement of those simulations.

A simple example can be seen here - <Playground id="#5W5B6W#1" title="Simple Motor Example" description="Simple example of a motor joint."/>

Motor.enabled joints are using the `IMotorEnabledJoint` :

```javascript
interface IMotorEnabledJoint {
    physicsJoint: any; //the native physics joint object. Coming from the selected engine.
    setMotor(force?: number, maxForce?: number, motorIndex?: number): void; // provide force to the motor
    setLimit(upperLimit: number, lowerLimit?: number, motorIndex?: number): void; // set limits to the motor
}
```

Setting a motor on a hinge joint (assuming impostors are already set):

```javascript
var joint1 = new BABYLON.HingeJoint({
    mainPivot: new BABYLON.Vector3(0, 0, 0), // Pivot on the main mesh
    connectedPivot: new BABYLON.Vector3(0, 0, 0), // pivot (connecting point) on the connected pivot
    mainAxis: new BABYLON.Vector3(0, 0, -1), // the hinge will turn on the Z axis
    connectedAxis: new BABYLON.Vector3(0, 0, -1) // Same as above - Z axis on the connected mesh
});
holder.physicsImpostor.addJoint(wheel.physicsImpostor, joint1); // attach holder (main) and wheel using the defined hinge joint

joint1.setMotor(3, 20); // start turning!
```

## Compounds and Babylon's parenting system

Babylon.js supports creating physics compounds. A compound is a collection of physics bodies that are connected together to create a single physics body with the joint geometry of all of the meshes connected.

To create a compound, use babylon's parenting system. A single object should be the parent of the rest of the compound shapes:

```javascript
// Create a 2-sphere compound
 var sphere = BABYLON.Mesh.CreateSphere("sphere1", 16, 2, scene);
sphere.position.y = 10;

var sphere2 = BABYLON.Mesh.CreateSphere("sphere2", 16, 2, scene);
sphere2.position.x = 2;
sphere.position.y = 1;
sphere2.parent = sphere;
```

After creating the meshes, we need to initialize the impostors. It is important to first initialize the child impostors and initialize the parent impostor at the end:

```javascript
sphere2.physicsImpostor = new BABYLON.PhysicsImpostor(sphere2, BABYLON.PhysicsImpostor.SphereImpostor, {mass: 2, restitution: 0.8});
sphere.physicsImpostor = new BABYLON.PhysicsImpostor(sphere, BABYLON.PhysicsImpostor.SphereImpostor, {mass: 2, restitution: 0.8});
```

The mass will be accumulated. So this single physics body's mass will be 4. `sphere2`'s physics impostor will be "disabled" and will be joined to `sphere`'s impostor, which is the main impostor. To apply impulses, set the liner velocity etc', use `sphere.physicsImpostor`.

<Playground id="#PRHF00#6" title="Advanced Physics Compounds Example 1" description="Advanced example of physics compounds."/>

An advanced example of compounds can be seen here - <Playground id="#5W5B6W#3" title="Advanced Physics Compounds Example 2" description="Advanced example of physics compounds."/>. The boxes connected to the disc are connected using Babylon's parenting system.

### ignoreParent

You can disable the compound behavior of babylon by setting the ignoreParent flag when creating the impostor.
It is important to note that this will only work if your parent has no impostor attached to it. Otherwise the results can vary from weird physics calculations to missing collisions.

To create an impostor for a child mesh using the ignoreParent flag:

```javascript
sphere2.physicsImpostor = new BABYLON.PhysicsImpostor(sphere2, BABYLON.PhysicsImpostor.SphereImpostor, {ignoreParent: true, mass: 2, restitution: 0.8});
```

A simple example can be found here - <Playground id="#PRHF00#4" title="Ignore Parent Example" description="Simple example of ignoring a physics parent."/>

## Substeps

It's possible to run the physics ticks at a different frequency than the framerate while keeping consistent display.
This means it's possible to display at 60 frames per seconds while updating the physics 1000 times a second.
With substeps, the physics will look like it's running at 60 frames per second but will perform smaller steps.
This is useful when the physics update needs more precision. For example, simulating a bullet against a wall or more accurate physics for a car.
The substeps can also be used to reduce the physics update. For example, doing an update every 2 frames.
In the following example, the physics is computed 10 times a second instead of 60. 

```javascript
var physicsEngine = scene.getPhysicsEngine();
physicsEngine.setSubTimeStep(100);
```

<Playground id="#YUNAST#21" title="Substeps Example" description="Simple example of using substeps."/>

## Cloth simulation

Raanan Weber wrote an article about cloth simulation in his blog: [https://blog.raananweber.com/2016/04/03/cloth-physics-simulation-for-babylon-js/](https://blog.raananweber.com/2016/04/03/cloth-physics-simulation-for-babylon-js/)

## An Oimo Demo

* Oimo car demo - <Playground id="#SFELK#3" title="Oimo Car Demo" description="Oimo Car Demo"/>


## The Skull as a Compound Body

![Skull](/img/how_to/physics/skull.jpg)
The skull is an interesting shape to try to compound and you can see it in all its magnificence here: <Playground id="#UKNERM#0" title="Skull As A Compound Body" description="Simple example of the skull as a compound body."/>

It is roughly composed of a sphere for most of it with a box around the jaw area, with a bit of work involved to position the sphere and box as best as possible. The skull is compounded to these two covering meshes.

![Compound Skull](/img/how_to/physics/greenSkull.jpg)

**Note** Center of mass is at the origin of the compound object.

## Compound to Empty Mesh

1. Create an empty mesh to be used as a parent for the compound body;
2. Create a range of appropriately shaped standard meshes to fit over the irregular mesh;
3. Parent the standard meshes and the irregular mesh to the empty mesh;
4. Calculate or estimate the mass for each standard mesh;
5. Create physics imposters for each standard mesh with zero mass;
6. Create a physics imposter for the empty mesh, using the NoImposter property, with the total mass of all the standard meshes.

**Note** Step 3 MUST come before step 4 and step 5 before step 6.

<Playground id="#492ZK0#7" title="Skull As A Compound Body 1" description="Simple example of a skull as a compound body."/>

## Compound Covering Meshes to The Complex Mesh 

1. Create a range of appropriately shaped standard meshes to fit over the irregular mesh;
2. Parent the standard meshes to the irregular mesh;
3. Calculate or estimate the mass for each standard mesh;
4. Create physics imposters for each standard mesh with zero mass;
5. Create a physics imposter for the irregular mesh, using the NoImposter property, with the total mass of all the standard meshes.

**Note** Steps 2, 4 and 5 must be in that order.

<Playground id="#492ZK0#12" title="Skull As A Compound Body 2" description="Simple example of a skull as a compound body."/>


## Compound to One of the Covering Meshes

1. Create a range of appropriately shaped standard meshes to fit over the irregular mesh;
2. Choose one standard mesh and parent the other standard meshes and the irregular mesh to this mesh;
3. Calculate or estimate the mass for each standard mesh;
4. Create physics imposters for each standard mesh with the assumed mass;

**Note** Step 2 MUST come before step 4.

<Playground id="#492ZK0#8" title="Skull As A Compound Body 3" description="Simple example of a skull as a compound body."/>


## How To Use Forces

This section gives some terminology needed to discuss the use of forces in the three physics' engines 

1. Cannon.js;
2. Oimo.js;
3. Ammo.js

as well as playground examples to check out the coding. In the playgrounds the physics' engine used can be changed by selecting which ones to comment out.

See [How to Use The Physics' Engines](/features/featuresDeepDive/physics/usingPhysicsEngine) for an overall view of setting up and using the three plugins.



## Body

Solids in physics are often referred to as `bodies`. In the simulation bodies are made up of two parts, the rendered object and the physics object. The rendered object is a mesh and the physics object, which holds the data about the body, is called a physics imposter. 

**Note:** a box imposter is often preferable when the body is a plane.

## Mass

This is the amount of matter in the body and is set when the imposter is formed. Static bodies should have a mass of zero.

```javascript
new BABYLON.PhysicsImpostor(mesh, BABYLON.PhysicsImpostor.BoxImpostor, { mass: 2 }, scene);
```

## Forces

These are gravity, impulses, friction and applied forces.

### Gravity 

In the simulations gravity is a universal force applied throughout the time of the simulation producing a gravitational acceleration. Setting a Vector3 for gravity is in fact setting the gravitational acceleration. The default value being `(0, -9.807, 0)`. Since it is a universal force it is set in the physics' engine either when it is enabled or later. 

```javascript
/*When physics is enabled use default gravity*/ 
scene.enablePhysics(null, new BABYLON.CannonJSPlugin());
scene.enablePhysics(null, new BABYLON.OimoJSPlugin());

await Ammo();
scene.enablePhysics(null, new BABYLON.AmmoJSPlugin());

//set gravity
scene.enablePhysics(new BABYLON.Vector3(0, -5, 0), new BABYLON.CannonJSPlugin());
scene.enablePhysics(new BABYLON.Vector3(0, -5, 0), new BABYLON.OimoJSPlugin());
scene.enablePhysics(new BABYLON.Vector3(0, -5, 0), new BABYLON.AmmoJSPlugin());

/*Get and set gravity*/
var physicsEngine = scene.enablePhysics(null, new BABYLON.CannonJSPlugin());
var physicsEngine = scene.enablePhysics(null, new BABYLON.OimoJSPlugin());

await Ammo();
var physicsEngine = scene.enablePhysics(null, new BABYLON.AmmoJSPlugin());

//Get gravity
var gravity = physicsEngine.gravity;

//Set gravity
physicsEngine.setGravity(new BABYLON.Vector3(0, -5, 0))
```

<Playground id="#YUNAST#3" title="Gravity Example" description="Simple example of using gravity in a phyics engine."/>

### Impulses

An impulse is a force applied to a body in an instance which will change the current linear velocity and/or the angular velocity of the body. Impulses acting at the center of mass of the body will not change the angular velocity.  Unless other forces act on it the body will continue with the new velocities.

An impulse is applied to a body's physics imposter.

Applying an impulse requires a vector giving the magnitude and direction of the impulse and the position vector of the contact point of the impulse. The contact point of the impulse is given in world coordinates. 

```javascript
imposter.applyImpulse(impluse_vector, contact_vector)

let localRefPoint = new BABYLON.Vector3(x, y, z);

imposter.applyImpulse(ImpulseVector, mesh.getAbsolutePosition()); //impulse at center of mass

imposter.applyImpulse(ImpulseVector, mesh.getAbsolutePosition().add(localRefPoint)); //impulse at a local point
```

The following playground is initially set up to apply an impulse at the center of mass vertically against gravity which eventually return the box to earth. Leaving the friction as 0 and applying horizontal impulses shows the continuity of movement.

<Playground id="#RHBQY9#12" title="Impulses Example 1" description="Simple example of adding impulses to objects." isMain={true} category="Physics"/>

### Friction

Friction is a property of a body and is set in the imposter and provides a continuous force between two bodies while they are in contact. You can set friction when creating an imposter and also get and set it later.

```javascript
new BABYLON.PhysicsImpostor(mesh, BABYLON.PhysicsImpostor.BoxImpostor, { mass: 2, friction: 0.4}, scene); //on creation

var friction = imposter.friction; // get friction;
imposter.friction = 0.1; //set friction.
```

Since friction occurs at the boundary of a body, applying an impulse at the center of mass will produce an angular velocity as well as a linear velocity.

Re-visiting the following playground and setting friction on **both** bodies and applying horizontal impulses will show the angular velocity effect.

<Playground id="#RHBQY9#12" title="Impulses Example 2" description="Simple example of adding impulses to objects."/>

### Applied Forces

An applied force will only affect the body over the time period that it is applied which is the duration of the frame interval. For zero friction a sufficiently large force (to overcome inertia) applied in the first frame interval will set the body in motion. While `Cannon.js` and `Ammo.js` have a native apply force method `Oimo.js` does not and so an applying force is replaced (internally in Babylon.js) with the apply impulse method so a smaller value has a greater effect. 


```javascript
//Force Settings
var forceDirection = new BABYLON.Vector3(1, 0, 0);
var forceMagnitude = 50;
var contactLocalRefPoint = BABYLON.Vector3.Zero();

impostor.applyForce(forceDirection.scale(forceMagnitude), mesh.getAbsolutePosition().add(contactLocalRefPoint));
```

The following playground initially set up with zero friction and to apply an impulse at the center of mass horizontally in the X direction.

<Playground id="#RHBQY9#1" title="Applying Forces" description="Simple example of applying forces to objects." isMain={true} category="Physics"/>


# Joints

A joint in a physics engine is a constraining feature between two bodies. This area has the largest differences between the physics engine both in the joints available and the names used. Not all native joints are available in some plugins.

Playgrounds are available to check out the coding. In the playgrounds the physics' engine used can be changed by selecting which ones to comment out.

See [How to Use The Physics' Engines](/features/featuresDeepDive/physics/usingPhysicsEngine) for an overall view of setting up and using the three plugins.

## Physical Joint Types

| Number | Joint                                                   | Name            | Notes                                                                           |
| ------ | ------------------------------------------------------- | --------------- | ------------------------------------------------------------------------------- |
| 1      | ![Hinge](/img/how_to/physics/hinge.jpg)                 | Hinge           | Single Axis Rotation                                                            |
| 2      | ![Ball and Socket](/img/how_to/physics/ballnsocket.jpg) | Ball and Socket | Multi Axis Rotation                                                             |
| 3      | ![Cone Twist](/img/how_to/physics/conetwist.jpg)        | Cone Twist      | Unrestricted rotation (Twist) on One Axis, Limited Rotation (in Cone) On Others |
| 4      | ![Wheel](/img/how_to/physics/wheel.jpg)                 | Wheel           | Two Axes Rotation                                                               |
| 5      | ![Slider](/img/how_to/physics/slider.jpg)               | Slider          | Single Axis Translation and Rotation                                            |
| 6      | ![Prismatic](/img/how_to/physics/prismatic.jpg)         | Prismatic       | Single Axis Translation Only                                                    |
| 7      | ![Distance](/img/how_to/physics/distance.jpg)           | Distance        | Set Bodies a Fixed Distance Apart                                               |
| 8      | ![Locked](/img/how_to/physics/locked.jpg)               | Locked          | Bodies Act As One Body                                                          |

## Babylon.js Joints

The following table lists those joints within Babylon.js and where available their equivalence to each other and their link to the native joints

| Babylon.js Joint   | Cannon Joint           | Oimo Joint         | Ammo Joint                                   | Helper Class     |
| ------------------ | ---------------------- | ------------------ | -------------------------------------------- | ---------------- |
| HingeJoint         | HingeConstraint        | HingJoint          | HingeConstraint                              | Yes              |
| BallAndSocketJoint | PointToPointConstraint | BallAndSocketJoint | Point2PointConstraint                        | no               |
| WheelJoint         | ----                   | WheelJoint         | Point2PointConstraint                        | Hinge2Joint Only |
| SliderJoint        | ----                   | SliderJoint        | SliderConstraint                             | No               |
| PrismaticJoint     | ----                   | PrismaticJoint     | ----                                         | No               |
| DistanceJoint      | DistanceConstraint     | DistanceJoint      | Point2PointConstraint with Added Constraints | Yes              |
| LockJoint          | LockConstraint         | ----               | FixedConstraint                              | No               |
| SpringJoint        | Spring                 | ----               | ----                                         | No               |

The method to form a joint and connect one body (main) to a second body (connected) is

```javascript
var joint = new BABYLON.PhysicsJoint(
  BABYLON.PhysicsJoint.TYPE_OF_JOINT,
  jointData
);

mainImpostor.addJoint(connectedImpostor, joint);
```

where the `jointData` object contains the properties for the joint.

### Hinge Joint

For a hinge the only component of any force that produces movement is one perpendicular to the axis of the hinge. It is possible however that a large impulse in another direction can produce a reaction between the two bodies that does produce an impulse component in the perpendicular direction.

The `jointData` object for a hinge contains the following properties

- mainAxis: Vector3; the axis for the main body.
- connectedAxis: Vector3; the axis for the connected body, usually the same as the main axis.
- mainPivot: Vector3; the pivot point for the main body.
- connectedPivot: vector3; the pivot point for the connected body, the negative of the connected body's position.

A hinge joint can also be created with a helper class

```javascript
var joint1 = new BABYLON.HingeJoint(jointData);
```

**_PhysicsJoint Playground_**

- <Playground id="#UFVU18#32" title="Hinge As A Sphere 1" description="Simple example of using a hinge as a sphere with PhysicsJoint."/>

**_Helper Class Playground_**

- <Playground id="#F15U0G#55" title="Hinge As A Sphere 2" description="Simple example of using a hinge as a sphere with the helper class."/>

Since a hinge gives movement about only one axis it would seem to make sense to replace the representation of the hinge with a cylinder. Doing this, reshaping the box and keeping the sphere mesh imposter as a sphere does produce changes.

In this case, for all the physics' engines whatever the direction of impulse set it is applied in a direction perpendicular to the hinge axis.

**_PhysicsJoint Playground_**

- <Playground id="#UFVU18#33" title="Hinge As A Cylinder 1" description="Simple example of using a hinge as a cylinder with PhysicsJoint."/>

**_Helper Class Playground_**

- <Playground id="#F15U0G#56" title="Hinge As A Cylinder 2" description="Simple example of using a hinge as a cylinder with the helper class."/>

You can, of course, use a cylinder impostor for the cylinder mesh

**_PhysicsJoint Playground_**

- <Playground id="#RHBQY9#13" title="Hinge As A Cylinder 3 (box and cylinder)" description="Simple example of using a hinge as a cylinder with PhysicsJoint."/>

**_Helper Class Playground_**

- <Playground id="#RHBQY9#14" title="Hinge As A Cylinder 4 (box and cylinder)" description="Simple example of using a hinge as a cylinder with the helper class."/>

### Ball And Socket Joint

For a ball and socket joint a force can produce rotation about all three axes.

The positioning of the connected body is determined by the connected pivot. The `jointData` object for a ball and socket contains the following properties

- mainPivot: Vector3; the pivot point for the main body.
- connectedPivot: vector3; the pivot point for the connected body, the negative of the connected body's position.

**_PhysicsJoint Playground_**

- <Playground id="#RHBQY9#15" title="Ball and Socket" description="Simple example of a ball and socket joint with box and sphere imposters."/>

### Wheel Joint

For a wheel the a force produces rotation about two axes.

The `jointData` object for a hinge contains the following properties

- mainAxis: Vector3; the first axis.
- connectedAxis: Vector3; the second axis.
- mainPivot: Vector3; the pivot point for the main body.
- connectedPivot: vector3; the pivot point for the connected body, the negative of the connected body's position.

**Note** In the `Oimo.js` playgrounds changing the contact point of the force will not produce a spin around the axis perpendicular to the sphere's surface.

**_PhysicsJoint Playground_**

- <Playground id="#UFVU18#7" title="Oimo.js Wheel Joint Example" description="Simple example of creating a wheel joint in Oimo with box and sphere imposters."/>

The `PhysicsJoint` called `Hinge2Joint` can be used as an alternative. Note however that there is no helper call `WheelJoint` and the helper must be

```javascript
var joint1 = new BABYLON.Hinge2Joint(jointData);
```

When this helper class is used with `Ammo.js` it forms a `BallAndSocketJoint` not a `WheelJoint`. So a change of contact point can produce a spin around the axis perpendicular to the sphere's surface when using `Ammo.js`.

**_Helper Class Playgrounds_**

- <Playground id="#F15U0G#26" title="Oimo.js Hinge2" description="Simple Oimo.js example of a hinge2 with box and sphere imposters."/>
- <Playground id="#F15U0G#64" title="Ammo.js Hinge2" description="Simple Ammo.js example of a hinge2 with box and sphere imposters."/>

### Slider Joint

Currently `Oimo.js` only. Any component of force in the direction of the slider axis will move the body along this axis. Any component of force perpendicular to the slider axis will rotate the body around the axis.

The `jointData` object for a slider contains the following properties

- mainAxis:Vector3, slider and rotational axis
- collision: Boolean, true if the main and connected bodies react at collision.

**_PhysicsJoint Playgrounds_**

- <Playground id="#UFVU18#17" title="Oimo.js Slier Example" description="Simple Oimo.js example of a slider with box and sphere imposters."/>

### Prismatic Joint

Currently `Oimo.js` only. Only the component of force in the direction of the axis will move the body and the movement will be a translation only along this axis.

The `jointData` object for a slider contains the following properties

- mainAxis:Vector3, prismatic axis
- collision: Boolean, true if the main and connected bodies react at collision.

**_PhysicsJoint Playgrounds_**

- <Playground id="#UFVU18#18" title="Oimo.js Prismatic Joint" description="Simple Oimo.js example of a prismatic Joint with box and sphere imposters."/>

### Distance Joint

The `jointData` object for a distance joint contains the following properties

- maxDistance: number.

**_PhysicsJoint Playgrounds_**

- <Playground id="#UFVU18#34" title="Distance Joint 1" description="Simple example of a distance joint with box and sphere imposters."/>

**_Helper Class Playgrounds_**

- <Playground id="#F15U0G#57" title="Distance Joint 2" description="Simple example of a distance joint with box and sphere imposters, created with the helper class."/>

### LockJoint

`Cannon.js` only. The two connected bodies act as one body.

**_PhysicsJoint Playgrounds_**

- <Playground id="#UFVU18#19" title="Cannon.js Lock Joint Example" description="Simple Cannon.js example of a lock joint using box imposters."/>

### Spring

`Cannon,js` Only. The `jointData` object for a spring contains the following properties

- length: number.
- stiffness: number.
- damping: number.

**_PhysicsJoint Playgrounds_**

- <Playground id="#UFVU18#36" title="Cannon.js Spring Joint Example" description="Simple Cannon.js example of a spring joint with box imposters."/>

## Motors

A motor requires a target speed (angular velocity) and the maximum force (torque) that can be applied by the motor. It is possible to set a torque that is insufficient for it to reach the target speed. Depending on the shape and mass of the body the torque has to overcome the moment of inertia of the body. A too low value for the torque will make the body struggle and stutter to reach the target speed. Even attempting to simulate a virtual motor in zero gravity with no friction and a zero mass for the axel joint turning a cylinder can make determining an appropriate value for the torque difficult. Since moment of inertia, which determines torque, also depends on the volume of the body it is a good idea to keep linear dimensions around 10 or less though it is probably worth experimenting to get obtain what you need. Adding gravity, friction and further bodies, that the motored body has to move, makes it even more difficult. Sometimes in your project all you will want is for the motor to turn. This can be achieved by just setting the target speed (the motor will be over torqued by default), as in

```javascript
joint.setMotor(speed);
```

At other times it will be important to set a value for the torque that limits the motor operation, you can do this with

```javascript
joint.setMotor(speed, force);
```

The table below shows the joints that a motor can be added to.

| Babylon.js Joint                 | Cannon Motor | Oimo Motor | Ammo Motor |
| -------------------------------- | ------------ | ---------- | ---------- |
| BABYLON.PhysicsJoint.HingeJoint  | Yes          | Yes        | Yes        |
| BABYLON.PhysicsJoint.WheelJoint  | No           | Yes        | No         |
| BABYLON.PhysicsJoint.Hinge2Joint | No           | Yes        | No         |
| BABYLON.PhysicsJoint.SliderJoint | No           | Yes        | No         |

To add a motor to one of these joints simply replace `PhysicsJoint` with `MotorEnabledJoint` and set the motor on the joint.

```javascript
var joint = new BABYLON.PhysicsJoint(
  BABYLON.PhysicsJoint.TYPE_OF_JOINT,
  jointData
);

mainImpostor.addJoint(connectedImpostor, joint);
```

becomes

```javascript
var joint = new BABYLON.MotorEnabledJoint(BABYLON.PhysicsJoint.TYPE_OF_JOINT, jointData);

mainImpostor.addJoint(connectedImpostor, joint);

joint.setMotor(target speed, maximum torque)
```

The helper classes for `HingeJoint` and `Hinge2Joint` are already motorised and only `setMotor` is needed.

## Playground Examples

### Hinge Motor Speed Only

**_MotorEnabledJoint Playground_**

- <Playground id="#UFVU18#35" title="Hinge Motor 1" description="Simple example of a hinge motor."/>

**_Helper Class Playground_**

- <Playground id="#F15U0G#58" title="Hinge Motor 2" description="Simple example of a hinge motor, created with the helper class."/>

### Hinge Motor Speed and Torque (Force)

Different engines use differing scales for the torque and a little trial and error is often necessary to determine the required effect.

- For Cannon.js try starting with torque values between 1/100 to 1/10 of the total mass value;
- For Ammo.js try starting with torque values between 1/100 and 1/10 of total mass value;
- For Oimo.js try starting with torque values about 1 to 10 times the total mass value.

In the hinge motor playgrounds below there are two wheels you can try out different torque values for each wheel to see how they vary. Note that they are in zero gravity, with zero friction and the axel has zero mass. In other situations torque values may need a larger factor than those given above.

**_MotorEnabledJoint Playground_**

- <Playground id="#WWNQ10#19" title="Hinge Motor 3" description="Simple example of a hinge motor (play with torque values)."/>

**_Helper Class Playground_**

- <Playground id="#WWNQ10#20" title="Hinge Motor 4" description="Simple example of a hinge motor created with the helper class (play with torque values)."/>

### Wheel (Hinge2) Motor

**_MotorEnabledJoint Playgrounds_**

- <Playground id="#UFVU18#28" title="Oimo.js Wheel Z Axis" description="Simple Oimo.js example of a wheel (hinge2) along the Z axis."/>
- <Playground id="#UFVU18#29" title="Oimo.js Wheel Y Axis" description="Simple Oimo.js example of a wheel (hinge2) along the Y axis."/>
- <Playground id="#UFVU18#30" title="Oimo.js Wheel X Axis" description="Simple Oimo.js example of a wheel (hinge2) along the X axis."/>

### Slider Motor

The motor rotates the body around the slider axis.

**_MotorEnabledJoint Playground_**

- <Playground id="#UFVU18#31" title="Oimo.js Slider X Axis" description="Simple Oimo.js example of a slider along the X axis."/>


# Pivots and Axes

Through the use of playgrounds this section considers how the pivot and axis parameters of the hinge joint effect the behaviour of the joint in the three physics engines 

1. Cannon.js;
2. Oimo.js;
3. Ammo.js

See [How to Use The Physics' Engines](/features/featuresDeepDive/physics/usingPhysicsEngine) for an overall view of setting up and using the three plugins.

The examples on this page a hinge joint and a main body are added to a connected axle using

```javascript
connectedAxle.physicsImpostor.addJoint(mainBody.physicsImpostor, joint);
```
the following parameters need to be set

* mainPivot: main body pivot;
* mainAxis: main body axis ;
* connectedPivot: connected axle pivot;
* connectedAxis: connected axle axis.

In all the following playgrounds the X axis is red, the Y axis green and the Z axis blue and unless clearly stated otherwise the gravity is zero. 

The main body is a purple box and the connected axle is a yellow box. Local axes are shown for both.

The purple sphere marks the position of the main pivot and is the center of rotation for the main body around the local axis of the main body. The yellow sphere marks the position of the connected pivot which is the negative of the set value for the connected pivot. 

The initial position of the main body is set by the values of the main pivot and the connected pivot and is may be shown by the slightly larger black sphere. The radius of rotation for the main body around the main pivot is determined by the value of the connected pivot.

The main body is orientated so that the connected axis and the main axis align but can be in the opposite directions.

When the position and orientation of the bodies' imposters set by their pivots do not match the position of the bodies' meshes then, at the start, movement of the bodies can occur as the meshes re-position to that given by the pivots. 

**Note** In some instances pivot and axes in `Cannon.js` can result in the an axis or movement of the body in the opposite direction to those of `Oimo.js` and `Ammo.js`.

The first and second set of playgrounds show examples when the mass of the connected axle is zero. In the first set the connected axle is positioned at the origin with no rotation. In the second the connected axle one or both of position or rotation can be non-zero. In the third set of examples both the body and the axle have a non-zero mass.

## Playground Examples  - Connected Axle Has Zero Mass and is at the Origin with No Rotation

(A) Parameter Settings
```javascript
mainPivot: new BABYLON.Vector3(0, 0, 0),  
connectedPivot: new BABYLON.Vector3(0, 0, 0), 
mainAxis: new BABYLON.Vector3(0, 1, 0), //
connectedAxis: new BABYLON.Vector3(0, 1, 0)
```

<Playground id="#8RQJ1R#2" title="Pivots and Axes (A Parameters)" description="Simple example of pivots and axes with A parameters."/>

----

(B) Parameter Settings
```javascript
mainPivot: new BABYLON.Vector3(0, 5, 0), //set main body position
connectedPivot: new BABYLON.Vector3(0, 0, 0),
mainAxis: new BABYLON.Vector3(0, 1, 0),
connectedAxis: new BABYLON.Vector3(0, 1, 0)
```
<Playground id="#8RQJ1R#3" title="Pivots and Axes (B Parameters)" description="Simple example of pivots and axes with B parameters."/>

----

(C) Parameter Settings
```javascript
mainPivot: new BABYLON.Vector3(0, 0, 0),
connectedPivot: new BABYLON.Vector3(5, 0, 0), //adjust main body position and radius of rotation
mainAxis: new BABYLON.Vector3(0, 1, 0),
connectedAxis: new BABYLON.Vector3(0, 1, 0)
```

* <Playground id="#8RQJ1R#4" title="Pivots and Axes (C Parameters)" description="Simple example of pivots and axes with C parameters."/>

----

(D) Parameter Settings
```javascript
mainPivot: new BABYLON.Vector3(10, 0, 0),
connectedPivot: new BABYLON.Vector3(0, 5, 0),
mainAxis: new BABYLON.Vector3(1, 0, 0), //different axes will orientate main body to align axes.
connectedAxis: new BABYLON.Vector3(0, 1, 0)
```
<Playground id="#8RQJ1R#5" title="Pivots and Axes (D Parameters)" description="Simple example of pivots and axes with D parameters."/>

----

(E) Parameter Settings
```javascript
mainPivot: new BABYLON.Vector3(0, 0, 0), //set main body position
connectedPivot: new BABYLON.Vector3(0, 0, 0), //adjust main body position and radius of rotation
mainAxis: new BABYLON.Vector3(0, 0, 1), //different axes will orientate main body to align axes.
connectedAxis: new BABYLON.Vector3(1, 0, 0)
```
<Playground id="#8RQJ1R#6" title="Pivots and Axes (E Parameters)" description="Simple example of pivots and axes with E parameters."/>

## Playground Examples  - Connected Axle Has Zero Mass and Position or Rotation Non-Zero

Any translation or rotation of the connected axle results in the same transformation being applied to the whole hinge joint system.

(F) Parameter Settings
```javascript
mainPivot: new BABYLON.Vector3(0, 0, 0),  
connectedPivot: new BABYLON.Vector3(0, 0, 0), 
mainAxis: new BABYLON.Vector3(0, 1, 0), //
connectedAxis: new BABYLON.Vector3(0, 1, 0)
```

* <Playground id="#8RQJ1R#7" title="Pivots and Axes (F Parameters)" description="Simple example of pivots and axes with F parameters."/>

----

(G) Parameter Settings
```javascript
mainPivot: new BABYLON.Vector3(0, 0, 0),
connectedPivot: new BABYLON.Vector3(0, 0, 0),
mainAxis: new BABYLON.Vector3(0, 1, 0),
connectedAxis: new BABYLON.Vector3(0, 1, 0)
```
<Playground id="#8RQJ1R#8" title="Pivots and Axes (G Parameters)" description="Simple example of pivots and axes with G parameters."/>

----

(H) Parameter Settings
```javascript
mainPivot: new BABYLON.Vector3(5, 0, 0),
connectedPivot: new BABYLON.Vector3(0, 0, 0), 
mainAxis: new BABYLON.Vector3(0, 1, 0),
connectedAxis: new BABYLON.Vector3(0, 1, 0)
``` 
<Playground id="#8RQJ1R#9" title="Pivots and Axes (H Parameters)" description="Simple example of pivots and axes with H parameters."/>

----

(J) Parameter Settings
```javascript
mainPivot: new BABYLON.Vector3(10, 0, 0),
connectedPivot: new BABYLON.Vector3(0, 5, 0), //adjust main body position and radius of rotation
mainAxis: new BABYLON.Vector3(0, 1, 0), 
connectedAxis: new BABYLON.Vector3(0, 1, 0)
```
<Playground id="#8RQJ1R#10" title="Pivots and Axes (J Parameters)" description="Simple example of pivots and axes with J parameters."/>

----

(K) Parameter Settings
```javascript
mainPivot: new BABYLON.Vector3(10, 0, 0), //set main body position
connectedPivot: new BABYLON.Vector3(0, 5, 0), //adjust main body position and radius of rotation
mainAxis: new BABYLON.Vector3(0, 0, 1), //different axes will rotate main body so stated axes align.
connectedAxis: new BABYLON.Vector3(1, 0, 0)
```
<Playground id="#8RQJ1R#11" title="Pivots and Axes (K Parameters)" description="Simple example of pivots and axes with K parameters."/>

## Playground Examples  - Connected Axle Has Non-Zero Mass and is at the Origin with No Rotation

When the position of the main body mesh is not the same as the position imposed on the impostors by the pivots or axes the body the physics will move the body from its mesh position to the position determined by the pivots and axes. This movement acts in the physics' world and so will set the hinge joint system in motion. 

In the following example the parameter setting will be applied in four situations, the last two just for fun.

  i. No Motor - main body mesh position and rotation made to be equal to that determined by pivots and axes;  
 ii. No Motor - main body mesh position and rotation different to that determined by pivots and axes;  
iii. Motor Applied - as ii.;  
 iv. Motor Applied in Non-Zero gravity - as ii.

(L) Parameter Settings
```javascript
mainPivot: new BABYLON.Vector3(0, 0, 0),  
connectedPivot: new BABYLON.Vector3(0, 0, 0), 
mainAxis: new BABYLON.Vector3(0, 1, 0),
connectedAxis: new BABYLON.Vector3(0, 1, 0)
```

<Playground id="#8RQJ1R#13" title="Pivots and Axes (L(i) Parameters)" description="Simple example of pivots and axes with L(i) parameters."/>
<Playground id="#8RQJ1R#14" title="Pivots and Axes (L(ii) Parameters)" description="Simple example of pivots and axes with L(ii) parameters."/>
<Playground id="#8RQJ1R#15" title="Pivots and Axes (L(iii) Parameters)" description="Simple example of pivots and axes with L(iii) parameters."/>
<Playground id="#8RQJ1R#16" title="Pivots and Axes (L(iv) Parameters)" description="Simple example of pivots and axes with L(iv) parameters."/>


# Soft Bodies
In terms of physics' engines a soft body is a body that can have its shape deformed by interactions with other bodies or forces within the physics world. Out of the three plugins available with Babylon.js soft bodies are only available using Ammo.js. There are three soft bodies you can create, the three dimensional `softbody`, the two dimensional `cloth` and the one dimensional rope. First a number of limitations need to be considered, followed by some aspects particular to soft bodies and then some examples.

See [How to Use The Physics' Engines](/features/featuresDeepDive/physics/usingPhysicsEngine) for an overall view of setting up and using the three plugins.

## Limitations
A deformation of a body can only be shown if there are sufficient vertices to produce the deformation. The number of vertices used and the need to check their positions and velocities each time step means that the number of soft bodies can be restricted to one, two or possibly three. 

Any triangular facet belonging to a mesh used as the basis for a soft body must share its vertices with any adjacent facet. If not the soft body will rip apart along unshared vertices. As an example look at the triangular facets in the diagram below

![Shared Facets](/img/how_to/physics/share.jpg)

In Mesh A the positions have new indices for each of the facets 0, 1, 2 and 3, 4, 5. This happens, for instance, in a sphere and also when a mesh is converted to a flat shaded mesh. In this case a soft body would tear along the lines 0,2 and 3,4.

In Mesh B the positions share indices for each of the facets 0, 1, 2 and 0, 2, 3. The soft body will then hold together.

To force a mesh to share vertices use

```javascript
mesh.forceSharedVertices();
```
One benefit of this is to reduce the number of vertices in the mesh. Of course there may not be enough vertices in the mesh to make a properly functioning soft body, in this case use

```javascript
mesh.increaseVertices(n);
```
where n is the number of extra vertices to be added to each side of a triangular facet. The number of facets is increased by a factor (n + 1)<sup>2</sup>. This method forces repeated vertex positions to share indices. The order to use the above two methods is always share then increase.

```javascript
mesh.forceSharedVertices();
mesh.increaseVertices(4);
```

**Note**
1. The position and rotation of the mesh must be set **before** its soft impostor is created.
2. A mesh used for a soft body cannot be a parent or child of another mesh.
3. Soft bodies cannot have forces and impulses applied to it.

## Options for Soft Bodies

As well as the usual optional parameters of mass, friction and restitution that can be set when creating a physics impostor there are a number peculiar to soft bodies. These come in two sets. 

Those that can be set during or after the impostor creation

* velocityIterations, positive integer, the maximum iterations used when solving for vertex velocities, default 20; 
* positionIterations, positive integer, the maximum iterations used when solving for vertex positions, default 20;
* stiffness, a float from 0 to 1, 0 very elastic, the distance between vertices is not constrained; 1 in-elastic, the distance between vertices is invariant, default 1;
* pressure, softbody only, a positive number; the higher it is the less likely the softbody will collapse onto itself, default 200; cloth and rope pressure is maintained at 0; 

and those that can only be set during creation

* margin, the collision margin around the soft body, set it around about 1/100 of the lengths of the body when needed, useful particularly to stop a cloth passing through a body, default 0;
* damping, slows down the changes in vertex positions, useful if it looks like parts of the body are vibrating, start from around 0.01;
* fixedPoints, cloth only, can be 0, 1, 2, 4, 8 or sums of these; 0 no fixed points, 1 back left corner fixed, 2, back right corner, 4 front left corner, 8 front right corner and sum to fix more than one corner, default 0.

You may have to do a trial and error on the above parameters to get the effect you want.

## The Softbody Soft Body

A softbody is a 3D soft body. To ensure that the body is not pulled apart the mesh used has to have [shared vertices](/toolsAndResources/utilities/Minimise_Vertices). This is achieved using

```javascript
mesh.forceSharedVertices()
```

It also has to have sufficient vertices to simulate the body. Where the mesh used cannot [increase the number of vertices](/toolsAndResources/utilities/Increasing_Facets) in its construction, a box for example, you use 

```javascript
mesh.increaseVertices(n);
```
 where n is the extra number of vertices to add to one side of a triangular facet. The number of facets is increased by a factor of (n + 1)<sup>2</sup>

A softbody is constructed using

```javascript
var options = {
    mass: 15,
    friction: 0.2,
    restitution: 0.3,
    pressure: 3500,
    velocityIterations: 10, 
    positionIterations: 10,
    stiffness: 1,
    margin: 0.1;
    damping: 0.05
}

new BABYLON.PhysicsImpostor(mesh, BABYLON.PhysicsImpostor.SoftbodyImpostor, options, scene);
```

or possibly

```javascript
mesh.physicsImpostor =  new BABYLON.PhysicsImpostor(mesh, BABYLON.PhysicsImpostor.SoftbodyImpostor, { mass: 1, friction: 0.1}, scene);
mesh.physicsImpostor.velocityIterations = 10; 
mesh.physicsImpostor.positionIterations = 10;
mesh.physicsImpostor.stiffness = 0.9;
```
### Examples
<Playground id="#480ZBN#1" title="Softbody Example" description="Simple example of a softbody."/>
<Playground id="#480ZBN#2" title="Softbody and Rigid Sphere" description="Simple example of a soft body and a rigid sphere."/>


## The Cloth Soft Body

A 2D soft body. All cloth soft bodies are created from a [ground mesh](/features/featuresDeepDive/mesh/creation/set/ground) as this is already two dimensional, has shared vertices and the number of vertices can be increased by setting the subdivisions used. The usual [options](/features/featuresDeepDive/physics/softBodies#options-for-soft-bodies) are available.

The clothImpostor is created by, for example,

```javascript
cloth.physicsImpostor =  new BABYLON.PhysicsImpostor(ground, BABYLON.PhysicsImpostor.ClothImpostor, {margin: 0.25, damping: 0.01}, scene);
cloth.physicsImpostor.velocityIterations = 10; 
cloth.physicsImpostor.positionIterations = 10;
cloth.physicsImpostor.stiffness = 1;
```

**Note** Using the `increaseVertices` method on a plane mesh will not provide a suitable mesh for a clothImpostor as the algorithm used to increase the vertices does not place them in the correct row by row order.

To see both sides of a cloth set `backFaceCulling = false` on the material to be applied to the ground mesh.

### Examples

<Playground id="#480ZBN#3" title="Cloth Over a Softbody" description="Simple example of a cloth over a softbody."/>
<Playground id="#480ZBN#4" title="Cloth Over a Rigid Box" description="Simple example of a cloth over a rigid box."/>
<Playground id="#480ZBN#5" title="Cloth Over Rigid Box With Fixed Corners" description="Simple example of a cloth over a rigid box with fixed corners." isMain={true} category="Physics"/>

### Fixed Points

![Cloth Points](/img/how_to/physics/cloth.jpg)

To fix corner points of the cloth so that those points do not move use the numbers (or their sum) as shown in the diagram above.

Set the fixedPoints parameter during the construction of the cloth.

```javascript
cloth.physicsImpostor =  new BABYLON.PhysicsImpostor(ground, BABYLON.PhysicsImpostor.ClothImpostor, {margin, 0.2, fixedPoints: 3}, scene);
cloth.physicsImpostor.velocityIterations = 10; 
cloth.physicsImpostor.positionIterations = 10;
cloth.physicsImpostor.stiffness = 1;
```

<Playground id="#480ZBN#6" title="Fixed Points Example" description="Simple example of a cloth over rigid box fixed at 1 + 2 = 3."/>

### Anchors

As well as being able to fix the corners of a cloth in space it is also possible to anchor points on a cloth to a rigid body.

![Horizontal Cloth](/img/how_to/physics/cloth2.jpg)

Anchor points are given as a fraction across the width and height of the ground forming the cloth as shown in the diagram above.

Rotating the cloth mesh to a vertical position using

```javascript
cloth.rotate.x = -Math.PI /2
```

will place (0, 0) as the bottom left corner and (1, 1) as the top right corner.

Using 

```javascript
cloth.rotate.x = Math.PI /2
```

will place (0, 1) as the bottom left corner and (1, 0) as the top right corner.

Setting an anchor needs three required parameter plus two optional ones, as in

```
clothImpostor.addAnchor(rigidImpostor, fraction of width, fraction of height, influence, noCollisionBetweenLinkedBodies);
```

* rigidImpostor, to which the anchor points are attached. The attachments are calculated automatically by Ammo.js and depend on the position of the softImpostor and the anchor points used.
* fraction of width, from 0 to 1, fraction across width of ground mesh
* fraction of height, from 0 to 1, fraction up height of ground mesh
* influence, from 0 to 1, defaults to 1. A value of 1 fixes the distance of the anchor from the rigid body, the closer to 0 the more elastic the distance
* noCollisionBetweenLinkedBodies, default false. When true the soft body and the rigid body, it is attached to, will not detect collisions to each other.

The width and height fraction coordinates are used to determine the closest vertex within the ground mesh to those fractional coordinates.

You are able to add multiple anchors, for example 

```javascript
cloth.physicsImpostor.addAnchor(box.physicsImpostor, 0, 1);
cloth.physicsImpostor.addAnchor(box.physicsImpostor, 1, 1, 0.8);
```

<Playground id="#480ZBN#8" title="Anchoring A Cloth" description="Simple example of anchoring a cloth."/>

## The Rope Soft Body

A rope is a 1D soft body. This can be constructed using a [lines mesh](/features/featuresDeepDive/mesh/creation/param/lines) or an [extruded shape](/features/featuresDeepDive/mesh/creation/param/extrude_shape) mesh. The usual [options](/features/featuresDeepDive/physics/softBodies#options-for-soft-bodies) available for both, however the use of an extruded shape requires extra parameters in the options.

### Using Lines

A lines mesh should be constructed in a straight line and an imposter constructed in the same way as for a softbody or a cloth.

```javascript
var rope = BABYLON.MeshBuilder.CreateLines("lines", {points: myPoints}, scene); 
rope.color = BABYLON.Color3.Black();
    
rope.physicsImpostor = new BABYLON.PhysicsImpostor(rope, BABYLON.PhysicsImpostor.RopeImpostor, {mass: 2}, scene);
rope.physicsImpostor.velocityIterations = 20; 
rope.physicsImpostor.positionIterations = 20;
rope.physicsImpostor.stiffness = 0.8;
```

<Playground id="#8WC6ZN" title="Rope With Fixed Ends" description="Simple example of a rope with fixed ends."/>

In the following playground note the use of the margin for the rope impostor to prevent the rope cutting into the soft box.
<Playground id="#8WC6ZN#1" title="Rope With Fixed Ends Over Soft Box" description="Simple example of a rope with fixed ends over a soft box."/>

### Using an Extruded Shape

The path for the extruded shape should be in a straight line and the shape and path parameters used in constructing the shape should be copied and pasted into the options for the impostor. Currently shape and path are the only two parameters that can be used when an extruded shape is used to construct a rope.

```javascript
var rope = BABYLON.MeshBuilder.ExtrudeShape("ext", {shape: myShape, path: myPoints}, scene);
rope.material = ropeMat;
    
rope.physicsImpostor = new BABYLON.PhysicsImpostor(rope, BABYLON.PhysicsImpostor.RopeImpostor, {mass: 2, shape: myShape, path: myPoints}, scene);
rope.physicsImpostor.velocityIterations = 20; 
rope.physicsImpostor.positionIterations = 20;
rope.physicsImpostor.stiffness = 1;
```
<Playground id="#8WC6ZN#122" title="Extruded Rope With Fixed Ends" description="Simple example of an extruded rope with fixed ends."/>

In the following playground remember that the extruded shape does not have an impostor, that it lies on the surface of the box is because the margin for the rope is set to the radius of the extruded shape.
<Playground id="#8WC6ZN#3" title="Extruded Rope With Fixed Ends Over Soft Box" description="Simple example of an extruded rope with fixed ends over a soft box."/>

### Fixed Points
Fixing the end points for a rope is the same whichever of the two meshes are used and must be set during construction. A 1 fixes the starting point of the rope, a 2 fixes the end point of the rope and 3 fixes both.

### Hooks

A hook can be added anywhere along the length of the rope using a number from 0 (start) to 1 (end) and is attached to a rigid body using

```
ropeImpostor.addHook(rigidImpostor, fraction of length, influence, noCollisionBetweenLinkedBodies);
```

where

* rigidImpostor, to which hook attached. The attachments are calculated automatically by Ammo.js and depend on the position of the ropeImpostor and the hook used.
* fraction of length, from 0 to 1, fraction across length of rope
* influence, from 0 to 1, defaults to 1. A value of 1 fixes the distance of the hook from the rigid body, the closer to 0 the more elastic the distance
* noCollisionBetweenLinkedBodies, default false. When true the rope and the rigid body, it is attached to, will not detect collisions to each other.

For example attaching a ball to the end of a rope and an crossbar to the start of a rope with influence 1,

```javascript
rope.physicsImpostor.addHook(crossbar.physicsImpostor, 0, 1);
rope.physicsImpostor.addHook(ball.physicsImpostor, 1, 1);
```

<Playground id="#8WC6ZN#4" title="Winging Ball (Lines Mesh)" description="Simple example of a swinging ball using a lines mesh."/>

<Playground id="#8WC6ZN#121" title="Swinging Ball (Extruded Mesh)" description="Simple example of a swinging ball using an extruded shape mesh."/>



# Support for Physics Engines

Physics engines are third party external programs that can be plugged into Babylon.js. They, depending on their features, emulate "real-life" interactions between objects, which can be meshes, solid particles from the solid particle system or some cameras. One feature of a Physics Engine is the addition of gravity to a scene.

There are plugins for 3 physics engines:

1. Cannon.js - a wonderful physics engine written entirely in JavaScript
2. Oimo.js - a JS port of the lightweight Oimo physics engine
3. Ammo.js - a JS post of the bullet physics engine

All need to be enabled before use.

Interactions between objects are achieved by imposters, simple objects that are attached to any complex objects with a scene. The imposter can be assigned physical attributes such as mass, friction, a coefficient of restitution, impulse, and linear and angular 

Two imposters can be connected using joints such as a hinge or ball and socket.

Ammo also allows the creation of soft bodies.


## Particle Properties

Once the PCS mesh is built, unless immutable, it can respond to changes in the properties of each particle. Existing properties are shown in the table below.

| Property | Type | Default |
| ---- | ---- | ----|
| position | Vector3 | (0, 0, 0) |
| rotation | Vector3 | (0, 0, 0) |
| rotationQuaternion | Vector3 | undefined |
| velocity | Vector3 | (0, 0, 0) |
| color | Vector4 | (1, 1, 1, 1) |
| pivot | Vector3  | (0, 0, 0) |
| uvs | Vector2  | (0,0) |
| translateFromPivot | boolean |false |
| parentId | integer | null |
| idx | integer (read only) | index of particle |
| groupId | integer (read only) | group number for a particle |


If you set a particle rotation quaternion, its rotation property will then be ignored.

New properties can be initialised.

**Note:** Since point particles **_always_** face the camera setting the rotation of a particle only has any effect in two cases:

1. The rotation of a particle parent will rotate its children about itself;
2. A pivot is set for the particle.



### Initialising Particles

Using `addPoints` particle properties can be set in the passed function. The `addSurfacePoints` and `addVolumePoints` methods obviously set the position and color properties  of the particles but you may still want to set the initial values of other particle properties.

This can be done using `initParticles`. With this you must iterate over all the particles by using the `nbParticles` property and follow a call to this function with a call to `setParticles`. For example

```javascript
pcs.initParticles = function() {
   for (var p = 0; p < pcs.nbParticles; p++) {
       pcs.particles[p].velocity = BABYLON.Vector3.Zero();
       pcs.particles[p].acceleration = pcs.particles[p].position.scale(0.01);
   }
}

pcs.addSurfacePoints(model, 10000, BABYLON.PointColor.Color);
pcs.buildMeshAsync().then(() => {
  model.dispose()
  pcs.initParticles();
  pcs.setParticles();
});
```

### Updating Particles

When any appropriate particle properties are initiated the `updateParticles` method can be used. Unlike `initParticles` the function is called by `setParticles` and already passes a particle as an argument.  The method `setParticles` will only execute after the PCS mesh has been built and so may safely be placed inside a render loop to produce an animation. For example

```javascript
pcs.updateParticle = function(particle) {
  particle.velocity.addInPlace(particle.acceleration);
  particle.position.addInPlace(particle.velocity);
}

scene.registerBeforeRender(() => {
  pcs.setParticles();
});
```

**Note:** All particle positions are expressed in the *local space* of the PCS mesh. 

The particle `pivot` vector is also in *local space* of the PCS mesh. By default rotations around a pivot are calculated by translating the particle to the pivot point, then rotating it and then the inverse translation applied. By setting the particle method `translateFromPivot` to `true` (default `false`) rotations will only be calculated using the initial translation followed by the rotation leaving the particle at the translated location.  

<Playground id="#UI95UC#12" title="Simple Animation" description="Simple example of animating a point cloud system."/>

In the following playground the particle pivots in the top PCS are set relative to the particle position and in the lower one are set in the same place.
<Playground id="#UI95UC#14" title="Pivot Animation Example 1" description="Simple example of animating the pivot point of a point cloud system."/>

In this playground the only difference is that the lower PCS has `translateFromPivot` set to `true`.
<Playground id="#UI95UC#15" title="Pivot Animation Example 2" description="Simple example of animating the pivot point of a point cloud system."/>

This playground animates the mesh not the particles.
<Playground id="#UI95UC#16" title="Immutable Animation" description="Simple example of point cloud system immutable animation."/>

This playground loads meshes from a file, converts to particles and animates
<Playground id="#UI95UC#17" title="Loaded Mesh Animation" description="Simple example of point cloud system animation based on loaded mesh animation."/>

### UVs

While setting and changing particle colors is straightforward doing this for UVs is a little more complex. Using `BABYLON.PointColor.UV` as a parameter within `addSurfacepoints` or `addVolumePoints` will set the UVs automatically for you based on the passed mesh.

You can also set the uv value for each particle using the passed function for `addPoints`. To make sense of the texture as the image used the uv values should relate in some way to the positional values for each particle. To then apply the texture with these uvs both the emissiveColor and emissiveTexture for the PCS mesh material must be set after the mesh is built.

**Note:** Only use emissive.

For example

```javascript
var myfunc = function(particle) { 
    var x = Math.random();
    var y = Math.random();
    var z = 0;
    particle.position = new BABYLON.Vector3(x, y, z);
    //Relate uv values to positional values
    particle.uv.x = x;
    particle.uv.y = y; 
    }
    pcs.addPoints(5000, myfunc);

    pcs.buildMeshAsync().then(() => {
      pcs.mesh.material.emissiveColor = new BABYLON.Color3(0, 0, 0);
      pcs.mesh.material.emissiveTexture = myTexture;
    });
```

It is possible to use a texture atlas but you need to customize and calculate the more complex relationship between positional and uv values.

<Playground id="#UI95UC#23" title="UV With Added Points" description="Simple example of updating the UVs and adding points of a point cloud system."/>
<Playground id="#UI95UC#24" title="UV With Texture Atlas" description="Simple example of updating the UVs of a point cloud system with textured atlas."/>

### Recycling Particles

You can write your own code to recycle particles using `recycleParticle` which can be called from within `updateParticle`. For example,

```javascript
pcs.recycleParticle = function(particle) {
    particle.position = BABYLON.Vector3.Zero();
    particle.velocity = BABYLON.Vector3.Zero();
    particle.heightLim = 4 + 0.5 * Math.random();
}

pcs.updateParticle = function(particle) {
    if (particle.position.y > particle.heightLim) {
      this.recycleParticle(particle);
    }
    particle.velocity.addInPlace(particle.acceleration);
    particle.position.addInPlace(particle.velocity);
}
```

<Playground id="#UI95UC#19" title="Recycling Animations" description="Simple example of recycling animations of a point cloud system."/>

### Particle Parenting  

Each particle can be given another particle as a parent.  
The parent must be created before the child particle. This means the parent has to have a lower index Id (`particle.idx`) than the current particle. So the first particle in the pool (`idx = 0`) can't have a parent. To give a parent to a particle, just set its property `parentId` to the parent index Id value. 

```javascript
if (particle.idx > 0) {
    particle.parentId = particle.idx - 1; // the previous particle becomes the parent of the current one
}
```
To un-parent a particle, just set `.parentId` back to `null` which is the default value.  

When a particle has got a parent, its position and rotation are then expressed in its parent local space.  
```javascript
if (particle.idx > 0) {
    particle.parentId = particle.idx - 1; // the previous particle becomes the parent of the current one
    // the particle position and rotation are expressed in the previous particle space, this one being already 
    // rotated and translated from the yet previous particle. Etc.
    particle.rotation.z = 0.01;
    particle.position.x = 1.0;
}
```
 <Playground id="#UI95UC#18" title="Parent Animation" description="Simple example of animating a point cloud system parent."/>

### Particle Intersections
     
The PCS provides a simple way to deal with intersections between a particle and other meshes. As this feature consumes more memory and CPU do not include it unless necessary.

To use it call the method `intersectsMesh(target)` (target is a mesh) for any particle to check if this particle intersects the _target_.  
It just will return true or false depending whether the particle intersects the target or not.    
  
```javascript
if (particle.intersectsMesh(anyMesh)) { 
  // change properties of particle
}
```
By default the check is carried out on the (AABB) bounding box of the mesh. When you wish to use the bounding sphere of the mesh add the parameter true.
```javascript
if (particle.intersectsMesh(mesh, true) {
    // change properties of particle
}; 
```

<Playground id="#UI95UC#20" title="Recycling Particle Collisions" description="Simple example of recycling particle collisions of a point cloud system."/>
<Playground id="#UI95UC#21" title="Mesh Colliding With Point Cloud" description="Simple example of a mesh colliding with a point cloud."/>


Physics

Coming next

Using A Physics Engine

Learn how to use one of the available physics engines in Babylon.js.

Forces

Learn all about applying physical forces in Babylon.js.

Joints

Learn all about using joints in physics engines within Babylon.js.

Pivots and Axes

Learn all about physics pivots and axes in Babylon.js.

Compound Bodies

Learn all about physics compound bodies in Babylon.js.

Soft Bodies

Learn all about physics soft bodies in Babylon.js.

Advanced Physics Features

Unlock the full potential of physics with advanced physics features in Babylon.js.

Add Your Own Physics Engine

Learn how to add your own physics engine to Babylon.js.