
## What is Raycast

In a collision detection scenario, a raycast can be used to determine whether a line of sight exists between two objects or whether a collision is imminent. By casting a ray from one object to another, the physics engine can determine whether the ray intersects with any other objects in its path, allowing the game to determine whether the two objects can "see" each other or whether a collision has occurred.

## How to use it

Here is an example of raycast:

```javascript
var raycastResult = new BABYLON.PhysicsRaycastResult();
var start = new BABYLON.Vector3(1, 20, 2);
var end = new BABYLON.Vector3(1, -20, 2);
physicsEngine.raycastToRef(start, end, raycastResult);
if (raycastResult.hasHit) {
    console.log("Collision at ", raycastResult.hitPointWorld);
}
```

The important thing to note here is the `raycastResult` that can (and should!) be reused between calls. This is the major difference with Physics V1 raycasting.

The result object has some information about the properties of the intersection, such as the intersection point, the body that was hit, and the index of the triangle hit in case it hit a Mesh Shape. You can find all the fields in the [PhysicsRaycastResult](/api/classes/BABYLON.PhysicsRaycastResult) class.

<Playground id="#I6AR8X" title="RayPicking Vs Raycast" description="Compare Raypicking with raycast feature of the Physics Engine" isMain={true} category="Physics"/>

## Raycast queries

You can use raycast queries to make the raycast test for specific objects only. The test utilizes the `membership` and `collideWith` fields, as follows:

```javascript
bool doesCollide = (ray.membership & shape.collideWith) && (shape.membership & ray.collideWith)
```

Where `&` represents the [bitwise AND](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Expressions_and_operators#bitwise_operators) operation and `&&` the [logical AND](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Expressions_and_operators#logical_operators). By default, if not specified, the values for both the `membership` and `collideWith` fields are `0xffffffff`, which is the identity for the bitwise operation.

```javascript
var shapeA = new PhysicsShape(...);
var shapeB = new PhysicsShape(...);

shapeA.filterMembershipMask = 1; // 01 in binary
shapeB.filterMembershipMask = 2; // 10 in binary

/**
 *  EXAMPLE 1: will test only for shape A 
 */
physicsEngine.raycastToRef(start, end, raycastResult, {collideWith: 1});

/**
 *  EXAMPLE 2: will test only for shape B 
 */
physicsEngine.raycastToRef(start, end, raycastResult, {collideWith: 2});

/**
 *  EXAMPLE 3: will test for shape A AND shape B (as 3 is 11 in binary)
 */
physicsEngine.raycastToRef(start, end, raycastResult, {collideWith: 3});
```

Here's a diagram of the operation for the second example's test on shapeA (which does not collide with the ray):

![Diagram of the ray collision test](/img/features/physics/raycast_diagram.png)

<Playground id="#PY59V9#7" title="Raycast Filtering Example" description="Example of the raycast filtering feature" isMain={true} category="Physics" />



# Migrate from Physics V1

Babylon 6.0 brought a new physics architecture, which aims to provide closer functionality to what most of the existing physic engines provide. However, it also includes some extra classes to make this migration easier. Here we show two ways of migrating your existing V1 scene to V2:

## Option 1: Using Aggregates

[Aggregates](/features/featuresDeepDive/physics/aggregates) work very similarly to the V1 Physics Impostors, creating all necessary objects automatically based on the parameters. So, if you have this code in V1:

```javascript
const sphere = BABYLON.MeshBuilder.CreateSphere("sphere", { diameter: 2, segments: 32 }, scene);
const impostor = new BABYLON.PhysicsImpostor(sphere, BABYLON.PhysicsImpostor.SphereImpostor, { mass: 1, friction: 0.2, restitution: 0.3 }, scene);
```

You will just need to change it to:

```javascript
const sphere = BABYLON.MeshBuilder.CreateSphere("sphere", { diameter: 2, segments: 32 }, scene);
const aggregate = new BABYLON.PhysicsAggregate(sphere, BABYLON.PhysicsShapeType.SPHERE, { mass: 1, friction: 0.2, restitution: 0.3 }, scene);
```

Note we switched the constructor from `PhysicsImpostor` to `PhysicsAggregate`, and the second parameter (the type of the physical shape) from `BABYLON.PhysicsImpostor.SphereImpostor` to `BABYLON.PhysicsShapeType.SPHERE`. [Here are the available types of shapes](/features/featuresDeepDive/physics/rigidBodies#shape).

## Option 2: No Aggregates

One of the most important new features in the new architecture is the ability to fine-tune the collision shapes and reuse them, improving memory usage and customizability. So it is also possible to separately create bodies and shapes:

```javascript
const sphere = BABYLON.MeshBuilder.CreateSphere("sphere", { diameter: 2, segments: 32 }, scene);
const impostor = new BABYLON.PhysicsImpostor(sphere, BABYLON.PhysicsImpostor.SphereImpostor, { mass: 1, friction: 0.2, restitution: 0.3 }, scene);
```

Would become:

```javascript
const sphere = BABYLON.MeshBuilder.CreateSphere("sphere", { diameter: 2, segments: 32 }, scene);
const sphereShape = new BABYLON.PhysicsShapeSphere(new BABYLON.Vector3(0, 0, 0), 1, scene);
const sphereBody = new BABYLON.PhysicsBody(sphere, BABYLON.PhysicsMotionType.DYNAMIC, false, scene);
sphereShape.material = { friction: 0.2, restitution: 0.3 };
sphereBody.shape = sphereShape;
sphereBody.setMassProperties({ mass: 1 });
```

The advantage of this approach is that, if you have another mesh you want to use with the same collider shape and material, you can reuse the shape:

```javascript
const complexModel = await BABYLON.ImportMeshAsync(...);
const body = new BABYLON.PhysicsBody(complexModel, BABYLON.PhysicsMotionType.DYNAMIC, false, scene);
body.shape = sphereShape;
body.setMassProperties({mass: complexModelMass});
```

<Playground id="#Q6TJRN#7" title="Shapes test" description="Use all available shapes with or without aggregates."/>



## What is it

A constraint represents a *connection* between two bodies. This connection can apply restrictions on the relative movement of the bodies, and allows us to model all sorts of physical connections between bodies such as ropes, doors, character joints, and more.

Because the two bodies are still simulated independently, A constraint (`PhysicsConstraint`) definition includes transforms from the local space of each body to the pivot position/orientation of the constraint on that body. Together these are known as the "constraint space". During simulation, constraints will act on the two bodies to maintain the pivot position/orientation across the two constrained bodies. For example, a ball-and-socket constraint will apply forces to the bodies so that the pivots point positions (defined respectively to each body's local space) will coincide. Likewise, a hinge constraint will also maintain the common rotation axis.

![Constraint Space](/img/how_to/physics/constraintbasics.png)

In rigid body dynamics, each body has 6 degrees of freedom: 3 translational degrees of freedom, and 3 rotational degrees of freedom. A constraint definition includes limitations on one or more of these degrees of freedom for its constrained bodies. Different types of constraints are generally defined by the number and type of these limitations. For example, in a ball-and-socket constraint, the constrained objects have no linear freedom relative to each other in any direction as they are attached together at the point, but are completely free to rotate around the constraint pivot point. In a hinge constraint, the objects no linear freedom and also have restricted relative orientation. In addition, limits can be provided for each degree of freedom. For example, limiting the distance rotation of a hinge constraint allows you for example to create a door that will not rotate beyond a given angle.

![Constraint Linear Limits](/img/how_to/physics/constraintlimitslinear.png)

![Constraint Angular Limits](/img/how_to/physics/constraintlimitsangular.png)

## Constraint Types

Babylon supports several constraint types; the most generic of which is the "6 DoF," which allows control over each degree of freedom individually. In addition to the 6 DoF, Babylon also provides several helper types for common constraints. Many of these constraints are specializations of the 6 DoF, but they don't require you to specify the full constraint space, which can make initialization easier in those cases.

| Enum | Name | Notes |
| --- | --- | --- |
| LOCK | Lock | ![Locked](/img/how_to/physics/locked.jpg) A locked joint attempts to keep the two constraint spaces completely lined up, allowing no relative movement. |
| BALL_AND_SOCKET  | Ball and socket| ![Ball and Socket](/img/how_to/physics/ballnsocket.jpg) A ball and socket joint attempts to line up the pivot *positions* but puts no restrictions on the relative rotation of the two bodies. |
| DISTANCE | Distance | ![Distance](/img/how_to/physics/distance.jpg) A distance joint attempts to keep the positions of the constraint spaces within a specified distance and provides no restriction on relative rotation. |
| HINGE | Hinge | ![Hinge](/img/how_to/physics/hinge.jpg) A hinge will keep the positions of the constraint spaces aligned as well as two of the angular axes, only allowing relative rotation around one axis. |
| PRISMATIC | Prismatic | ![Prismatic](/img/how_to/physics/prismatic.jpg) A prismatic joint allows the constraint spaces to translate along one axis and allows no relative rotation of the two spaces. |
| SLIDER | Slider | ![Slider](/img/how_to/physics/slider.jpg) Similar to the prismatic joint, but also allows the bodies to rotate around the translation axis. |
| SIX_DOF | 6 Degrees Of Freedom | <figure> <img src="/img/features/physics/6DOF.svg" alt="Image representing 6 Degrees of Freedom"/> <figcaption>6 degrees of freedom: three translational and three rotational axes. By GregorDS - Own work, CC BY-SA 4.0, https://commons.wikimedia.org/w/index.php?curid=38429678</figcaption> </figure> The most generic type. Does not provide any restrictions by default, so the limits can be applied as you choose. |

## How to use it

```javascript
const bodyA = new BABYLON.PhysicsBody(objectA, BABYLON.PhysicsMotionType.DYNAMIC, scene);
const bodyB = new BABYLON.PhysicsBody(objectB, BABYLON.PhysicsMotionType.DYNAMIC, scene);

const constraint = new BABYLON.DistanceConstraint(
  10, // max distance between the two bodies
  scene
);

bodyA.addConstraint(bodyB, constraint);
```

If one or both bodies are instanced, you need to specify the instance to which the constraint applies:

```javascript
// This will add a constraint between the instance in index 3 of body A, and the instance in index 2 of body B
bodyA.addConstraint(bodyB, constraint, 3, 2);
// The constraint can also be between two instances in the same body
bodyA.addConstraint(bodyA, constraint, 4, 7); 
```

For the 6DOF (6 Degrees of Freedom) constraint, you should pass an array with entries specifying the translational and rotational axis that have min and max limits:

```javascript
// This will constraint the bodies to mantain a distance of at least 1 and at most 2, and to rotate at most 1.58 rad along the perpendicular axis
let constraint = new BABYLON.Physics6DoFConstraint({
    pivotA: new BABYLON.Vector3(0, -0.5, 0),
    pivotB: new BABYLON.Vector3(0, 0.5, 0),
    perpAxisA: new BABYLON.Vector3(1, 0, 0),
    perpAxisB: new BABYLON.Vector3(1, 0, 0),
}, [
    {axis: BABYLON.PhysicsConstraintAxis.LINEAR_DISTANCE, minLimit: 1, maxLimit: 2},
    {axis: BABYLON.PhysicsConstraintAxis.ANGULAR_Y, minLimit: 0, maxLimit: 1.58}
], scene);
```
## Debug visualization

Physics viewer allows to display angular and linear limits of constraints.
Following example adds and immediately removes a constraint from debug visualization.

```javascript
physicsViewer = new BABYLON.Debug.PhysicsViewer(scene, visualizationSizeFactor);
let joint = new BABYLON.HingeConstraint(
    new BABYLON.Vector3(0, 0, -0.5),
    new BABYLON.Vector3(0, 0, 0.5),
    undefined,
    undefined,
    scene
);
agg1.body.addConstraint(agg2.body, joint);
  
physicsViewer.showConstraint(joint);
physicsViewer.hideConstraint(joint);
```

Because of performance, limit debug mesh is not recreated when constraints change. User is responsible for removing and adding the constraint if any limit is changed.

<Playground id="#RMF5CJ#38" title="Constraint Debug view" description="Edit angular and linear limits of a constraint" isMain={true} category="Physics"/>
<Playground id="#7DMWP8#693" title="Constraints limits" description="View limits for different type of constraints" isMain={true} category="Physics"/>

## Best practices

A problem that's very noticeable to users of your application is when a third body comes between the constraint spaces of a pair of constrained bodies, resulting in visual penetration, as seen in the picture below.

![Ragdoll bone gap](/img/how_to/physics/ragdollbonegap.jpg)

This can look very unnatural and, in addition, cause jitter between the constrained bodies, as the collision detection will "fight" against the constraint. Overlapping the constrained bodies greatly helps to avoid situations like this.

![Ragdoll with overlapping bones](/img/how_to/physics/ragdolloverlappedbones.jpg)

Even when the constraint is not attempting to force the bodies into an overlapping position, most use-cases for constraints still attempt to position the bodies very close to each other. To avoid the collision detection from "fighting" the constraint resolution, by default, we disable collisions between each pair of constrained bodies. If you *do* want the bodies to collide, however, this can be controlled by `PhysicsConstraint.isCollisionsEnabled`.

When simulating a long chain of constrained bodies, not all of the constraints might be solved perfectly by the physics engine, which can result in stretching or misalignment of the constraint - this is more likely to happen if the mass ratio between two constrained bodies is very high. A common approach to mitigate this is to tweak the mass ratios of the constrained bodies - increase the mass and inertia of bodies which are closer to the "root" of the chain and decrease as the bodies are further from the root. e.g. if you have a ragdoll, ensure that the torso has the most mass and decrease the mass as you move down the limbs of the ragdoll.


## Examples

<Playground id="#7DMWP8" title="Constraints" description="Shows all the different constraints available" isMain={true} category="Physics"/>

<Playground id="#NAMYYQ#2" title="Swinging pendulums" description="Example of using the Distance Constraint to model a pendulum" isMain={true} category="Physics"/>

<Playground id="#RMF5CJ" title="6 DoF Joint Tool" description="Simple tool for experimenting with commonly used Physics6DoFConstraint parameters" isMain={true} category="Physics"/>

<Playground id="#5KKGOT#1" title="Motor Constraints" description="Example of Motor Constraints targeting velocity and position" isMain={true} category="Physics"/>