The aim of this series of tutorials is to consider how a collision system can be built using justBabylon.js code (ie no physics engines). Some of the issues involved in developing such a system are described. The ideas in this tutorial can be used to build a collision system of complex shapes. 

In this case a complex shape is one constructed from spheres of the same size in such a way that any one sphere 
is always in contact with at least one other sphere in the shape. A complex shape is likely to have concave sections. 
An example of colliding complex shapes is given below. It has been constructed using the Solid Particle System because of the speed and flexibility when using many repeated shapes.

![Complex Shape](/img/samples/collide1.jpg)

PG: <Playground id="#WLYB9" title="Complex Shapes Colliding" description="An example of complex shapes in collision."/>

To begin with the frame rate will be taken as constant throughout the animation and speed for any shape will be in units per frame.

## Checking for an Intersect

One way to check inBabylon.js whether two meshes are colliding is to use the _intersectsMesh_ method. So for Fig 1 

```javascript
sphere.intersectsMesh(wall)
```
would give the result *true*

![Fig 1](/img/samples/collide4.jpg) 
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Fig 1

You may think that where the sphere in Fig 2 is travelling towards the wall that you could use

```javascript
if(sphere.intersectsMesh(wall)) {
 //bounce sphere off wall
}
else {
 //move sphere left
}
```

![Fig 2](/img/samples/collide2.jpg) 
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Fig 2

However consider the sphere as having unit diameter and is moving towards the ball with a speed of 5 units per frame. The check for collision has to be 
considered for each frame. The first frame is as in Fig 3 and the next frame as in Fig 4

![Fig 3](/img/samples/collide2.jpg) 
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Fig 3

The sphere will have gone past the wall and is not intersecting it and so no collision will be detected

![Fig 4](/img/samples/collide3.jpg) 
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Fig 4

## Size and Speed Matter.

Consider a sphere of radius r travelling towards a wall with speed v, at a position just out of contact with the wall. To be able definitely to use of the _intersectsMesh_ method the sphere must be in contact with the wall during the next frame. The maximum distance the sphere can travel between frames must be less than twice the radius, as in Fig 5. 

![Fig 5](/img/samples/collide5.jpg) 
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Fig 5

So for the sphere to start in any random position and travel directly towards the wall and for an intersection with the wall definitely to take place during a frame v &lt;= 2r

Now consider two spheres travelling towards each other, each sphere having a speed v. The relative velocity is 2v. Take one sphere as stationary and the other moving with speed v at a position just out of contact with each other. To be able to use the _intersectsMesh_ method the spheres must be in contact with each other during the next frame. The maximum distance the moving sphere can travel between frames must be less than four times the radius, as in Fig 6. 

![Fig 6](/img/samples/collide6.jpg) 
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Fig 6

So for two spheres to start in any random positions and travel directly towards each other and for an intersection with the wall definitely to take place during a frame 2v &lt;= 4r, which is again v &lt;= 2r.

To generalise , should one sphere have radius r1 and speed v1 and the other radius r2 and speed v2 
intersections from random positions will definitely take place 
when v1 + v2 < 2(r1 + r2)

What is the situation when v > 2r?

Consider that the front of the sphere is a distance d from the wall in a frame, F, and in the next frame, N, the sphere intersects the wall or has moved passed it, then 0 &lt;= d &lt;= v. If d &gt; v then d - v &gt; 0 and so in the next frame the sphere is still a distance d - v &gt; 0 from the wall. In fact when the sphere is any distance p away from the wall, p &gt; 0, then for frame F, d = p modulo v. Fig 7 shows that for the sphere to intersect the wall v - 2r &lt; d V v.

![Fig 7](/img/samples/collide7.jpg) 
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Fig 7

The sphere just touches the wall when d = 0 and so for a display where the sphere does not penetrate the wall p modulo v is 0.
 
Expressing this in quotient and remainder form p = qv, q &gt;= 0 

Since p is the distance from the front of the wall the centre of the sphere will be at qv + r.

## Playground Example

In the following playground the three spheres are positioned so that for sphere1, d &lt; v - r and so will pass through the wall; for sphere2 
d = 0 and for sphere3 v - 2r &lt; d &lt; v. The radius and speed for each sphere have been set at the same values but can be changed easily should you wish to.
Sphere1 is at the top, sphere2 the middle and sphere3 at the bottom.

PG: <Playground id="#1LOEWK#1" title="Spheres Collide With Walls" description="Shows the effect of speed on colliions."/>

## Hypotheses

Given a multitude of equally sized spheres, all initially inside a box and given random velocities and using Newtonian physics to inform the results of collisions 

1. By setting the initial speed of each sphere to be twice the radius and contraining their initial positions to be within a grid system of cubes with size matching the diameter of the spheres then it is possible to create a system whereby all collisions and rebounds between a sphere and a wall and between two spheres take place when they just touch.

2. By setting the initial speed of each sphere to below twice the radius of a sphere then it is possible to form a system whereby all collisions and rebounds between a sphere and a wall and between two spheres can be detected by checking if the meshes intersect.

Both hypotheses turn out to be false. This can be seen by reading the following

1. [Simple Particle Collisions on a Grid](/guidedLearning/workshop/Grid_Moves) 
2. [Slow Particles](/guidedLearning/workshop/Slow_Collide)

This being the case we turn to issues arising when the speed of a sphere is greater than twice the radius.

## Stroboscopic Issues

What happens when the speed of a sphere is greater than twice the radius and you need to calculate its position following what should be a collision with the wall?

In Fig 8 the red arrow shows the movement of the sphere, between two frames, when the collision with the wall is not detected and the green arrow the required movement. The required position is a reflection, with the wall as reflector, of the through position.

![Fig 8](/img/samples/collide15.jpg) 
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Fig 8.

As usual r is the radius of the sphere.

Should a sphere be moving at right angles to a wall a distance 8r units from the wall and the speed of the sphere be 16r units then its reflected position will be its start position and the sphere will apper not to have moved. This is the stroboscopic effect.

The following Playground shows spheres all starting from a distance of 8r units from two walls, all moving at right angles to the walls with speeds ranging from 20r to 12r units.

PG: <Playground id="#1LOEWK#2" title="Strobing Effect" description="Shows the effect of position, radius and speed."/>

## Conclusion

Depending on the effect required it is probably better to start with speeds 2r or below per frame but even so it is not sufficient to use intersection of meshes to check for collisions and mathematical techniques will be needed. These techniques will both determine if collisions take place and the repositioning of the spheres.

This page explains the design behind the 'createTrack' function which you use to [build tracks](/guidedLearning/workshop/Track) that provide data for a carriage to follow. A track is built for an array of points (Vector3s) which is split into sections. Each section uses the designated lean, _the rotation of the carriage about the track direction_ and turn, _the rotation of the carriage about its local Y axis_, of the carriage following the track to produce arrays of matrices for each point on the track path. The direction of a rail is given by the tilt (-&pi;/2 to &pi;/2) of the rail about the z axis and its swivel ( to to 2&pi;) about the y axis.

## Rotation Matrices

Matrices are used since they are the fundamental operations needed to combine rotations in a given order. To produce the final rotation of a carriage at any point all the following rotations: tilt; swivel; lean; turn; need to be combined.

![tilt and swivel track](/img/snippets/rail1.jpg) track tilt (yellow angle) and swivel (purple angle)

![lean and turn carriage](/img/snippets/rail2.jpg) carriage lean and turn

## Obtaining the Track Data

The track data produce by `createTrack` are the arrays

- directions: directions of travel;
- rotations: a combination of the lean and turn rotations;
- carriageRotations: lean rotations;
- passengerRotations: turn rotations.

The [parameters](/guidedLearning/workshop/Track#parameters) needed for each section are

- start index;

then the options

- lean;
- leanTwists;
- leanWaves;
- leanWaveAngle;
- turn;
- turnTwists;
- turnWaves;
- turnWaveAngle.

are used with

```javascript
var section = new sectionData(startAt, options);
```

The code for which is

```javascript
var sectionData = function (startAt, options) {
 this.start = startAt;
 this.options = options;
};
```

This data for each section is passed as an array to 'createTrack' along with the points for the track as

```javascript
var createTrack = function(points, sections) {
```

Internally 'createTrack' uses a 'createSection' function to construct the data to return.

## Section Build

The 'createSection' takes three parameters, points, the full points array for the track, the startSection which contains the information to be used in creating the section and endSection which just provides the lean and turn values at the end of the current section.

The term rail is used to indicate a segment of track from points[i] to points[i + 1]

```javascript
function createSection(points, startSection, endSection) {
 /***** Calculate the number of rails for the section *****/
 var railsFrom = startSection.start; //index of start of section
 var railsTo = endSection.start; //index of end of section
 if (endSection.start === 0) {
 railsTo = points.length;
 }

 var nbRails = railsTo - railsFrom;

 /***** Set the defaults for the section *****/
 var initialLean = startSection.options.lean === void 0 ? 0 : startSection.options.lean; //lean of carriage about direction axis at start, a phi variable
 var initialTurn = startSection.options.turn === void 0 ? 0 : startSection.options.turn; // turn of carriage around upright at start, a theta variable
 var leanTwists = startSection.options.leanTwists === void 0 ? 0 : startSection.options.leanTwists; //number of lean twists (+ve counter clockwise, -ve clockwise)
 var leanWaves = startSection.options.leanWaves === void 0 ? 0 : startSection.options.leanWaves; //number of lean waves
 var leanWaveAngle = startSection.options.leanWaveAngle === void 0 ? 0 : startSection.options.leanWaveAngle; //angle for lean wave
 var turnTwists = startSection.options.turnTwists === void 0 ? 0 : startSection.options.turnTwists; //number of turn twists (+ve counter clockwise, -ve clockwise)
 var turnWaves = startSection.options.turnWaves === void 0 ? 0 : startSection.options.turnWaves; //number of turn waves
 var turnWaveAngle = startSection.options.turnWaveAngle === void 0 ? 0 : startSection.options.turnWaveAngle; //angle for turn wave

 var finalLean = endSection.options.lean === void 0 ? 0 : endSection.options.lean;
 var finalTurn = endSection.options.turn === void 0 ? 0 : endSection.options.turn;

 /***** Check if both waves and twists are used and ignore twists when so *****/
 //lean waves supersede lean twists unless leanWaveAngle = 0
 if (leanWaves > 0 && Math.abs(leanTwists) > 0) {
 if (leanWaveAngle == 0) {
 leanWaves = 0;
 } else {
 leanTwists = 0;
 }
 }

 //turn waves supersede turn twists unless turnWaveAngle = 0
 if (turnWaves > 0 && Math.abs(turnTwists) > 0) {
 if (turnWaveAngle == 0) {
 turnWaves = 0;
 } else {
 turnTwists = 0;
 }
 }

 /***** Initiate the variables and their types *****/
 //rail transformation matrices for swivel and tilt rotations
 var rotationMatrixY = BABYLON.Matrix.Identity();
 var rotationMatrixZ = BABYLON.Matrix.Identity();
 var rotationMatrix = BABYLON.Matrix.Identity();

 var m = BABYLON.Matrix.Identity();
 var initialRailDirection = BABYLON.Axis.X;
 var initialUprightDirection = BABYLON.Axis.Y;
 var initialLevelDirection = BABYLON.Axis.Z;
 var railDirection = BABYLON.Vector3.Zero();
 var uprightDirection = BABYLON.Vector3.Zero(); //contains vector normal to rail direction after tilt
 var levelDirection = BABYLON.Vector3.Zero(); //contains vector normal to rail direction after swivel
 var leanDirection = BABYLON.Vector3.Zero(); // contains vector normal to rail direction after tilt, swivel and lean
 var turnDirection = BABYLON.Vector3.Zero();
 var carriageNormal = BABYLON.Vector3.Zero();
 var rotationMatrixLean = BABYLON.Matrix.Identity();
 var rotationMatrixTurn = BABYLON.Matrix.Identity();
 var rotationMatrixPassenger = BABYLON.Matrix.Identity();
 var initialPosition = BABYLON.Vector3.Zero();
 var rotation = BABYLON.Matrix.Identity(); //Overall rotation after tilt, swivel, lean and turn

 var tilt = 0; //tilt angle of rail after rotation about (0, 0, 1)
 var swivel = 0; //swivel angle of rail after rotation around (0, 1, 0)

 var railCount = 0; // determines how many rails along a section, used to control wave values

 //Set calculated values for variables
 var phi = initialLean;
 var theta = initialTurn;

 var gradLean = (finalLean - initialLean) / (nbRails - 1); // lean gradient
 var gradTurn = (finalTurn - initialTurn) / (nbRails - 1); // turn gradient

 var deltaPhi = (finalLean + 2 * leanTwists * Math.PI - initialLean) / nbRails; //increase in phi per rail for lean twist
 var deltaTheta = (finalTurn + 2 * turnTwists * Math.PI - initialTurn) / nbRails; //increase in theta per rail for lean twist

 /***** Loop over rails in section*****/

 for (var i = railsFrom; i < railsTo; i++) {
 points[(i + 1) % points.length].subtractToRef(points[i], railDirection); //direction of each rail
 railDirection.normalize();
 swivel = -Math.atan2(railDirection.z, railDirection.x); //swivel angle rail makes in xz plane
 tilt = Math.atan2(Math.abs(railDirection.y), Math.abs(railDirection.x)); // tilt angle rail makes in first quadrant of xy plane
 tilt *= Math.sign(railDirection.y); //tilt angle of rail in xy plane from -pi/2 to pi/2
 BABYLON.Matrix.RotationAxisToRef(BABYLON.Axis.Y, swivel, rotationMatrixY); //swivel angle to matrix rotation
 BABYLON.Matrix.RotationAxisToRef(BABYLON.Axis.Z, tilt, rotationMatrixZ); //tilt angle to matrix rotation
 rotationMatrixZ.multiplyToRef(rotationMatrixY, rotationMatrix); // form combined swivel and tilt matrix
 BABYLON.Vector3.TransformNormalToRef(initialUprightDirection, rotationMatrix, uprightDirection); //swivel, tilt act on carriage upright
 BABYLON.Vector3.TransformNormalToRef(initialLevelDirection, rotationMatrix, levelDirection); //swivel, tilt act on carriage level
 uprightDirection.normalize();
 levelDirection.normalize();

 if (leanWaves > 0) {
 phi = initialLean + railCount * gradLean + leanWaveAngle * Math.sin((railCount * leanWaves * Math.PI) / (nbRails - 1));
 } else {
 phi += deltaPhi;
 }
 if (turnWaves > 0) {
 theta = initialTurn + railCount * gradTurn + turnWaveAngle * Math.sin((railCount * turnWaves * Math.PI) / (nbRails - 1));
 } else {
 theta += deltaTheta;
 }
 railCount++;
 BABYLON.Matrix.RotationAxisToRef(railDirection, phi, rotationMatrixLean); // lean matrix
 BABYLON.Vector3.TransformNormalToRef(uprightDirection, rotationMatrixLean, carriageNormal); // lean applied to upright
 BABYLON.Matrix.RotationAxisToRef(carriageNormal, theta, rotationMatrixTurn); // turn applied to upright after lean

 BABYLON.Matrix.RotationAxisToRef(initialUprightDirection, theta, rotationMatrixPassenger); //just turn applied to upright
 passengerRotations.push(rotationMatrixPassenger.clone());

 rotationMatrix.multiplyToRef(rotationMatrixLean, rotation); //rotation from swivel, tilt, and lean only
 carriageRotations.push(rotation.clone());
 rotation.multiplyToRef(rotationMatrixTurn, rotation); //complete rotation from swivel, tilt, lean and turn
 rotations.push(rotation.clone());

 directions.push(railDirection.clone());
 }
}
```

## Create Track from Sections

The createTrack function requires the points for the path of the track and an array of sections. Checking is carried out on the order of sections.

```javascript
var createTrack = function (points, sections) {
 //Data arrays
 var directions = [];
 var rotations = [];
 var carriageRotations = [];
 var passengerRotations = [];

 var nbSections = sections.length;

 var looped = sections[nbSections - 1].start === 0;
 for (var i = 1; i < nbSections - looped; i++) {
 if (sections[i - 1].start > sections[i].start) {
 console.log("sections not in order");
 return;
 }
 }
 if (0 < sections[nbSections - 1].start && sections[nbSections - 2].start > sections[nbSections - 1].start) {
 console.log("last section not in order");
 return;
 }
 var section = sections[0];
 if (section.start > 0) {
 startSection = new sectionData(0, {});
 sections.unshift(startSection);
 nbSections = sections.length;
 }

 if (0 < sections[nbSections - 1].start && sections[nbSections - 1].start < points.length - 1) {
 //assume need to close loop
 var endSection = new sectionData(0, sections[0].options);
 sections.push(endSection);
 }

 //Store track data per section
 for (var i = 0; i < sections.length - 1; i++) {
 createSection(points, sections[i], sections[i + 1]);
 }

 return { directions: directions, rotations: rotations, carriageRotations: carriageRotations, passengerRotations: passengerRotations };

 /****** createSection function goes here *******/
};
```

## Playground Example

PG: <Playground id="#HSMDF2#10" title="Set Carriage Variables" description="Shows how the carriage behaves on varying its parameters."/>

Introduction to Developing a System For Collisions