Have you ever wondered how physics can bring a virtual bowling game to life? Well, you're in for a treat! In this tutorial, we'll explore using the Havok Physics engine to create a simple bowling scene which simulates bowling ball movement and pin interactions. If you’re new to using physics with Babylon.js, then this tutorial is for you! We’ll create the scene in the Babylon.js Playground and use assets available in the Asset Librarian. So, let's lace up our virtual bowling shoes and get started!

## Create the Scene

Let’s first create a new playground. We can get rid of the sphere and ground within the scene since we later add our own assets. Before moving onto the next step, be sure that your code doesn’t include the sphere or ground.

```javascript
var createScene = function () {
 // This creates a basic Babylon Scene object (non-mesh)
 var scene = new BABYLON.Scene(engine);

 // This creates and positions a free camera (non-mesh)
 var camera = new BABYLON.FreeCamera("camera1", new BABYLON.Vector3(0, 5, -10), scene);

 // This targets the camera to scene origin
 camera.setTarget(BABYLON.Vector3.Zero());

 // This attaches the camera to the canvas
 camera.attachControl(canvas, true);

 // This creates a light, aiming 0,1,0 - to the sky (non-mesh)
 var light = new BABYLON.HemisphericLight("light", new BABYLON.Vector3(0, 1, 0), scene);

 // Default intensity is 1. Let's dim the light a small amount
 light.intensity = 0.7;

 return scene;
};
```

Since we’re creating the scene in the Playground, save the scene and copy the URL so that you can save incremental updates throughout the tutorial.

## Enable Physics

To bring our scene to life with realistic physics, Babylon.js provides a powerful function called `enablePhysics`. This essential function serves as the gateway to integrating physics into our scene. By invoking `enablePhysics`, we enable dynamic physics simulation for our objects, allowing them to respond to forces and collisions realistically. This function is necessary for creating a scene with physics because it sets the stage for objects to interact with each other in a lifelike manner. From simulating the movement of a bowling ball as it rolls down the lane to accurately calculating the collision response between the ball and the pins, `enablePhysics` is the key that unlocks the potential for immersive and interactive experiences.

Let’s enable the physics engine just below the code for light intensity. The `enablePhysics` function takes two parameters: `gravity` and `plugin`. We create a variable for each parameter and pass them each into the function. For `gravity`, we use the vector `(0, -9.81,0)` which reflects real Earth gravity. As for the `plugin`, we assign the `HavokPlugin`.

```javascript
var gravityVector = new BABYLON.Vector3(0, -9.81, 0);
var physicsPlugin = new BABYLON.HavokPlugin();
scene.enablePhysics(gravityVector, physicsPlugin);
```

Now that physics is enabled, let’s create our bowling lane!

## Create Bowling Lane

The bowling lane is considered the ground in our scene. We want to provide a thin long platform for both the pins to sit and the bowling ball to roll. Using `MeshBuilder`, we create the lane and assign the width and height parameters, 6 and 20 respectively.

```javascript
const lane = BABYLON.MeshBuilder.CreateGround("lane", { width: 6, height: 20 }, scene);
```

We also position the lane further ahead on the z-axis by `4` to provide a more full view of the lane without moving the camera.

```javascript
lane.position = new BABYLON.Vector3(0, 0, 4);
```

Now that we have a bowling lane, we add physics to the lane since both the ball and pins need to collide with the surface. By not adding physics to the lane, our ball and pins would fall through the ground! To add physics, we create an aggregate. The Physics Aggregate is a helper that allows creating all the objects necessary to physicalize the scene in just one call.

```javascript
const laneAggregate = new BABYLON.PhysicsAggregate(lane, BABYLON.PhysicsShapeType.BOX, { mass: 0 }, scene);
```

The aggregate contains both a body and a shape. Since we’re adding physics to the lane, the lane is the body. As for the shape, we need to ensure that the shape matches the body. Given the lane closely resembles the shape of a box, we use the BOX shape. We also make use of the PhysicsAggregate Parameter – Mass. Since the lane lies flat against the virtual ground, we assign no mass (or 0). Otherwise, the lane would fall into the abyss of the scene!

![Bowling lane](/img/samples/lane.png)

## Create Bowling Pins

With our bowling lane created and configured with physics, we add pins to sit on top of its surface. A standard bowling lane consists of 10 bowling pins. Rather than write the same code 10 times to create each bowling pin, we create a function `createPins` which uses the `InstancedMesh` method to create an instance of 10 pins. The `InstancedMesh` method allows for efficient rendering of multiple instances of the same mesh with varying positions or properties. This is quite the function so let’s break it down!

We first start by loading the bowling pin from the Asset Librarian. Once loaded, we set the scaling of the pin to a size that’ll fit well within our lane dimension but also accommodate 10 pins. Given the lane dimensions, we scale the bowling pin `0.3`.

```javascript
async function createPins(scene) {
 const result = await BABYLON.ImportMeshAsync(Assets.meshes.bowlingPinpin_glb.rootUrl + Assets.meshes.bowlingPinpin_glb.filename, scene);
 const bowlingPin = result.meshes[1];
 bowlingPin.scaling = new BABYLON.Vector3(0.3, 0.3, 0.3);
}

createPins(scene);
```

![Single bowling pin](/img/samples/single-pin.png)

Because we’re creating instances of the loaded bowling pin mesh, we disable the initial pin which hides the pin from view.

```javascript
bowlingPin.setEnabled(false);
```

Since we can change the position for each instanced pin, we need a way to both store and later reference all positions. To do so, we create an array `pinPositions` to store all pin positions. The position is based on the scale of the pin. Therefore, if you choose a scale different than `0.3``, adjust the x and z values of the pins accordingly.

```javascript
pinPositions = [
 new BABYLON.Vector3(0, 0, 5),
 new BABYLON.Vector3(0.5, 0, 6),
 new BABYLON.Vector3(-0.5, 0, 6),
 new BABYLON.Vector3(0, 0, 7),
 new BABYLON.Vector3(1, 0, 7),
 new BABYLON.Vector3(-1, 0, 7),
 new BABYLON.Vector3(-1.5, 0, 8),
 new BABYLON.Vector3(-0.5, 0, 8),
 new BABYLON.Vector3(0.5, 0, 8),
 new BABYLON.Vector3(1.5, 0, 8),
];
```

We now iterate over the `pinPositions` array using the `map()` method. For each position in `pinPositions`, a new `bowlingPin` instance is created. Each new pin’s name is given the prefix `pin` followed by the corresponding index. The instanced pin’s position is then assigned based on the corresponding position value from the `pinPositions` array.

```javascript
return pinPositions.map(function (positionInSpace, idx) {
 const pin = new BABYLON.InstancedMesh("pin-" + idx, bowlingPin);
 pin.position = positionInSpace;
 return pin;
});
```

Before we return the instanced pin, we need to add physics to the pin. Like adding physics for the bowling lane, we create an aggregate for the pin. However, this time we use the `CONVEX_HULL` shape which matches the visual geometry as good as possible. We assign a mass of `1` to the pin so that there’s just a bit of weight but not too much that the pin can’t be knocked down. In addition, we use the `restitution` parameter which refers to how bouncy or springy an object is when it collides with another object. Bowling pins are made of wood and therefore when a pin collides with another object, the pin should “bounce” just a tad but not so much as though the pin is made of rubber. Therefore, a `restitution` of `.25` will suffice!

```javascript
const pinAggregate = new BABYLON.PhysicsAggregate(pin, BABYLON.PhysicsShapeType.CONVEX_HULL, { mass: 1, restitution: 0.25 }, scene);
```

With the pin instanced and then returned, we call the `createPins()` function passing the scene into the function call. At this point, we have 10 pins instanced in the shape of a triangle!

![Bowling pins and lane](/img/samples/ten-pins.png)

## Create a Bowling Ball

With our bowling lane created and our pins perfectly placed, we’re ready to create the bowling ball! We load the bowling ball from the Asset Librarian and scale to `.2`. In addition, we position the ball at `(0, 0.5, -5)` which centers the ball at the opposite end of the bowling lane.

```javascript
async function createBall(scene) {
 const result = await BABYLON.ImportMeshAsync(Assets.meshes.bowlingBall_glb.rootUrl + Assets.meshes.bowlingBall_glb.filename, scene);
 const bowlingBall = result.meshes[1];
 bowlingBall.scaling.scaleInPlace(0.2);
 bowlingBall.position = new BABYLON.Vector3(0, 0.5, -5);
}

createBall(scene);
```

![Bowling pins and lane](/img/samples/full-bowling-scene.png)

Now that our bowling ball is in place, we add physics to the ball. However, this time we choose the `SPHERE` shape given the balls rounded shape.

```javascript
const ballAggregate = new BABYLON.PhysicsAggregate(bowlingBall, BABYLON.PhysicsShapeType.SPHERE, { mass: 1, restitution: 0.25 }, scene);
```

We’re going to simulate aiming and rolling the ball down the lane later by adding keyboard input. Since both forms of movement are manually initiated by key input, we need to modify default behavior that Babylon.js performs for physics objects.

Before an actual physics simulation takes place, Babylon.js performs a pre-step computation which handle various tasks such as updating the object’s position and velocity based on external forces, applying constraints, and resolving collisions. These calculations help ensure accurate and stable physics simulations.

However, we want to manually control the bowling ball’s motion – whereas the bowling ball only moves when a key is pressed. Therefore, we set `disablePreStep` to `false`. In doing so, Babylon.js skips the pre-step computation for the bowling ball which allows us to directly manipulate its position and velocity without interference from the built-in calculations.

```javascript
ballAggregate.body.disablePreStep = false;
```

## Add and Configure Keyboard Input

The final step in our tutorial is to add keyboard input to both move the position of the bowling ball for optimal aim and roll the ball down the lane - hopefully for a strike! We add this functionality within the function callback for the bowling ball. Using the `onKeyboardObservable` method, we check for a `KEYDOWN` event. Essentially, when the appropriate key is down, an action occurs. Let’s first start with moving the bowling ball’s position left and right.

```javascript
scene.onKeyboardObservable.add((kbInfo) => {
 switch (kbInfo.type) {
 case BABYLON.KeyboardEventTypes.KEYDOWN:
 switch (kbInfo.event.key.toLowerCase()) {
 }
 }
});
```

For typical keyboard game play, the A and D keys are used for left and right movement, respectively. Since we’re only moving the bowling ball to the left and right, we change the ball’s `x` position when the key is pressed. We don’t want to change the position too much per key press, therefore, we decrement and increment `0.1` on the x-axis.

```javascript
case "a":
 bowlingBall.position.x += 0.1;
 break
case "d":
 bowlingBall.position.x -= 0.1;
 break
```

As for rolling the bowling ball down the lane, we need to apply an impulse to the ball in the direction of the bowling pins. To do so, we use `applyImpulse` on the body for the ball aggregate that was created when we added physics to the bowling ball. When applying an impulse, we need to provide an impulse vector (or the direction of the impulse) and the location of the impulse. The direction of impulse is going to be in the direction of the bowling pins – which are in a positive direction on the Z axis. As for the location of the impulse, we use the absolute position of the bowling ball. Like our sentiment about typical keyboard game play, we assign the W key for rolling the ball forward down the lane.

```javascript
case "w":
 ballAggregate.body.applyImpulse(new BABYLON.Vector3(0, 0, 20), bowlingBall.getAbsolutePosition());
 break;
```

## Summary

Let’s get rolling! Now that we have our bowling lane, pins and bowling ball setup, we can play our game. Use the A and D keys to move the bowling ball to the left or right and press the W key to send the ball rolling down the lane. Did you get a strike? We hope so!

Here's the complete playground: <Playground id="#FSMQBW#1" title="Bowling" description="Simple bowling scene with Havok Physics Plugin." image=""/>

Although this is a simplified version of a bowling game, we encourage you to let your imagination run wild and build upon this sample. If you’re in need of inspiration, consider adding some of the following features:

- Reset the ball to the start position after the initial roll
- Keep score of how many pins fall
- Add advanced manipulations to the ball such as spins
- Reset the pins after rolling the ball
- Swap out the existing assets for your own custom designs

## Further Reading

- [Havok Physics Plugin](content/features/featuresDeepDive/physics/v2/usingHavok)
- [Aggregates](content/features/featuresDeepDive/physics/v2/aggregates)

This is to show a practical use of translate, rotate and using a parent.

## The Design

The car will be designed in the same way as for the [Simple Car](/guidedLearning/workshop/Car_Path). In this case the car will be flatter and the view will be from behind
the car and this will be fixed as the camera will not be attached to the canvas. The front wheels will be further away from the side of the body
to allow them to turn, each will have its own pivot. The car will be driven forward using the space bar as an accelerator up to a maximum speed.
The front wheels will be steered with A and D. The rotation of the wheels will be matched with the speed of the car.

The car will be created with the origin in the middle of the centres of the two rear wheels.

The ground will be covered in random boxes to give the illusion of movement. For simplicity it will be possible to drive off the ground with
no consequences other than perhaps the loss of the sense of motion.

## Steering

The steering will be based on a simplified Ackerman steering system. In the true Ackerman system when turning
the rotation of the left and right front wheels will be different. For the purposes of this simulation they will
be taken to be the same.

![Ackerman Steering](/img/samples/ackerman.jpg)

The front wheel pivots and the rear wheel supports form a rectangle with a distance L between the front and rear and a distance A
between the two front wheels. When the front inside wheel is turned through an angle of theta the centre of rotation is where the
line through the pivot point normal to the wheel meets the line through the two real wheel supports.
The distance R of the centre of rotation from the inside rear wheel support can be found using R = L/tan(theta) and from the middle
of the to rear wheels it is A/2 + L/tan(theta).

## Mathematics of Rotation for Car

When theBabylon.js engine is running at F frames per second the time for one frame is 1/F seconds.

When the speed of the car is D units per second the distance travelled by the car is D/F units.

When the car is driven forward (ie theta =0) at a speed of D units per second the distance travelled by the car in one frame is D/F units.

Let the radius of each wheel be r units. In one frame a wheel travels a distance of D/F units and turns through an angle of psi radians
where r * psi = D/F and so psi = D/Fr.


When the car is turning each wheel will rotate at different rates as they travel different distances in the same time. For simplicity the following
conditions are imposed for the mathematical calculations:

1. The wheel pivots and supports will be taken as the centre of the wheels.
2. The rear inside wheel travels a distance D.
3. The angle of rotation turned by the car for one frame is phi radians.

The rear inside wheel travels a distance R * phi = D/F ands so phi = D/RF.
For one frame let this wheel rotate through an angle of psi0 then
r * psiRI = D/F and so psiRI = D/rF

The rear outside wheel travels a distance (R + A) * phi .
For one frame let this wheel rotate through an angle of psi1 then
r * psiRO = D\*(R + A)/F and so psiRO = D*(R + A)/Fr

The front inside wheel travels a distance sqrt(R\*R + L\*L) * phi .
For one frame let this wheel rotate through an angle of psi2 then
r * psiFI = D\*sqrt(R\*R + L\*L)/F and so psiFI = D*sqrt(R\*R + L\*L)/rF

The front outside wheel travels a distance sqrt((R + A)\*(R + A) + L\*L) * phi .
For one frame let this wheel rotate through an angle of psi3 then
r * psiFO = D\*sqrt((R + A)\*(R + A) + L\*L) and so psiFO = D\*sqrt((R + A)\*(R + A) + L\*L)/rF

At any point when the front wheels are turned the centre of rotation and the turning radius R need to be recalculated.
The following diagram indicates the procedure.

![Centre of Rotation](/img/samples/car3.jpg)

## Applying the Calculations

The centre of rotation will be an empty mesh, the pivot, which will be the parent of the car. The pivot's position
will depend on the angle theta of the front wheels. The car has been created with its front pointing towards the negative x axis.
When the pivot rotates to turn the car its local negative x axis will always be the direction of travel and the centre of rotation
will always be along its local positive z axis.
R will be given an initial value and the pivot set at R along the local positive z axis. When theta = 0 any movement will be linear and the pivot will
be translated a distance of D/F along the local negative x axis per frame.

When theta changes a new value NR for the radius of the circle of rotation will be calculated and the centre of rotation translated a distance
R - NR along the local positive z axis and the car translated NR - R along the local positive z axis. This results in the car not changing position
and the centre of rotation being a distance NR from the car. R is then set to NR.

### Turning the Front wheels

An action manager is used to register a key up and a key down event. There are three keys used A, D and Space (with or without caps lock).
As acceleration and turning can take place at the same time multiple key presses are required. Whenever a key down event occurs the key is added to
an associative array formed from a map object and the array value is set to true. It is reset to false on key up.

```javascript
 var map ={}; //object for multiple key presses
 scene.actionManager = new BABYLON.ActionManager(scene);

 scene.actionManager.registerAction(new BABYLON.ExecuteCodeAction(BABYLON.ActionManager.OnKeyDownTrigger, function (evt) {
 map[evt.sourceEvent.key] = evt.sourceEvent.type == "keydown";
 }));

 scene.actionManager.registerAction(new BABYLON.ExecuteCodeAction(BABYLON.ActionManager.OnKeyUpTrigger, function (evt) {
 map[evt.sourceEvent.key] = evt.sourceEvent.type == "keydown";
 }));
```

In the animation loop whenever A or D is pressed the front wheels are turned by a small amount. Since theta the angle made by the front wheels
is changed the centre of rotation is repositioned. The example below is for turning left.

```javascript
if((map["a"] || map["A"]) && -Math.PI/6 < theta) {
	deltaTheta = -Math.PI/252;
	theta += deltaTheta;
	pivotFI.rotate(BABYLON.Axis.Y, deltaTheta, BABYLON.Space.LOCAL); //turn front wheels
	pivotFO.rotate(BABYLON.Axis.Y, deltaTheta, BABYLON.Space.LOCAL);
	if(Math.abs(theta) > 0.00000001) { //when not near to 0 calculate new radius of rotation
		NR = A/2 +L/Math.tan(theta);
	}
	else { //when theta near 0 make it 0 and give NR some value
		theta = 0;
		NR = 0;
	}
	pivot.translate(BABYLON.Axis.Z, NR - R, BABYLON.Space.LOCAL); // translate pivot to centre of rotation from current position
	carBody.translate(BABYLON.Axis.Z, R - NR, BABYLON.Space.LOCAL); //as this translation will move the car translate it back to where it was
	R = NR;
};
```

### Moving the Car

When the speed is greater than zero and theta is not zero rotate the pivot and rotate each wheel depending on its position. Otherwise translate the pivot in the local negative x direction
and rotate the wheels by the same amount.

```javascript
if(D > 0) {
	phi = D/(R * F);
	if(Math.abs(theta)>0) {
	 	pivot.rotate(BABYLON.Axis.Y, phi, BABYLON.Space.WORLD);
		psiRI = D/(r * F);
		psiRO = D * (R + A)/(r * F);
		psiFI = D * Math.sqrt(R* R + L * L)/(r * F);
		psiFO = D * Math.sqrt((R + A) * (R + A) + L * L)/(r * F);

		wheelFI.rotate(BABYLON.Axis.Y, psiFI, BABYLON.Space.LOCAL);
		wheelFO.rotate(BABYLON.Axis.Y, psiFO, BABYLON.Space.LOCAL);
		wheelRI.rotate(BABYLON.Axis.Y, psiRI, BABYLON.Space.LOCAL);
		wheelRO.rotate(BABYLON.Axis.Y, psiRO, BABYLON.Space.LOCAL);
 	}
 	else {
	 	pivot.translate(BABYLON.Axis.X, -distance, BABYLON.Space.LOCAL);
		wheelFI.rotate(BABYLON.Axis.Y, psi, BABYLON.Space.LOCAL);
		wheelFO.rotate(BABYLON.Axis.Y, psi, BABYLON.Space.LOCAL);
		wheelRI.rotate(BABYLON.Axis.Y, psi, BABYLON.Space.LOCAL);
		wheelRO.rotate(BABYLON.Axis.Y, psi, BABYLON.Space.LOCAL);
 	}
}
```

## Playground Examples

The first playground is the example as described above.

NOTE: To use the keys with the playground you MUST click on the car after it loads or you have used RUN.

PG: <Playground id="#102TBD#31" title="Driven Car" description="View behind the car."/>

The second playground is similar. The pivot has been made into a sphere so you can see it and the camera position changed to give
an overview. The camera is now attached to the canvas so you can change viewing angles. This may help give more insight into
the workings of the code.

PG: <Playground id="#102TBD#33" title="Driven Car Overview" description="Visible pivot and flexible camera view"/>

This is to show the practical use of rotate.

## The Design

The car will consist of a trapezoid for the body, four cylinders for wheels. The car will be animated to follow a path and will remain parallel to it.
The wheels will rotate and be given a texture to show that they are rotating. For simplicity all wheels will remain parallel to the car and
their rotation will not be matched to the forward speed of the car. The car will move forward by following a sequence of points on the path.
The path will be a curved line with large turning radius and will be shown in the scene.

![Basic Car](/img/samples/car1.jpg)

### Car body

The car body will be an extrusion of the trapezium formed from the trapezium given by the points (-4, 2), (4, 2), (5, -2), (-7, -2)
in the direction of the positive x axis from (0, 0, 0) to (0, 0, 4)

```javascript
var bodyMaterial = new BABYLON.StandardMaterial("body_mat", scene);
bodyMaterial.diffuseColor = new BABYLON.Color3(1.0, 0.25, 0.25);
bodyMaterial.backFaceCulling = false;

var side = [new BABYLON.Vector3(-4, 2, -2), new BABYLON.Vector3(4, 2, -2), new BABYLON.Vector3(5, -2, -2), new BABYLON.Vector3(-7, -2, -2)];

side.push(side[0]); //close trapezium

var extrudePath = [new BABYLON.Vector3(0, 0, 0), new BABYLON.Vector3(0, 0, 4)];

var carBody = BABYLON.MeshBuilder.ExtrudeShape("body", { shape: side, path: extrudePath, cap: BABYLON.Mesh.CAP_ALL }, scene);
carBody.material = bodyMaterial;
```

PG: <Playground id="#1YD970#8" title="Car Body" description="Constructing the car body."/>

### Wheel

The wheel is made from a cylinder using MeshBuilder as this allows different textures and colors to be applied
to the flat and curved surfaces of the cylinder.

```javascript
var wheelMaterial = new BABYLON.StandardMaterial("wheel_mat", scene);
var wheelTexture = new BABYLON.Texture("https://i.imgur.com/ZUWbT6L.png", scene);
wheelMaterial.diffuseTexture = wheelTexture;

//Set color for wheel tread as black
var faceColors = [];
faceColors[1] = new BABYLON.Color3(0, 0, 0);

//set texture for flat face of wheel
var faceUV = [];
faceUV[0] = new BABYLON.Vector4(0, 0, 1, 1);
faceUV[2] = new BABYLON.Vector4(0, 0, 1, 1);

var wheel = BABYLON.MeshBuilder.CreateCylinder("wheel", { diameter: 3, height: 1, tessellation: 24, faceColors: faceColors, faceUV: faceUV }, scene);
wheel.material = wheelMaterial;

//rotate wheel so tread in xz plane
wheel.rotation.x = Math.PI / 2;
```

PG: <Playground id="#1YD970#541" title="Wheels" description="Constructing the wheels"/>

### Attaching the Wheels to the Car

As the car moves forward so will the wheels, this can be achieved by making the car the parent of the wheels.

As the wheels need to first rotate around the x axis to orientate the cylinder correctly and then rotate about another axis
the rotate method will be used instead of rotation.

```javascript
var wheelFI = BABYLON.MeshBuilder.CreateCylinder("wheelFI", { diameter: 3, height: 1, tessellation: 24, faceColors: faceColors, faceUV: faceUV }, scene);
wheelFI.material = wheelMaterial;

wheelFI.rotate(BABYLON.Axis.X, Math.PI / 2, BABYLON.Space.WORLD);
wheelFI.parent = carBody;

var wheelFO = wheelFI.createInstance("FO");
wheelFO.parent = carBody;
wheelFO.position = new BABYLON.Vector3(-4.5, -2, 2.8);

var wheelRI = wheelFI.createInstance("RI");
wheelRI.parent = carBody;
wheelRI.position = new BABYLON.Vector3(2.5, -2, -2.8);

var wheelRO = wheelFI.createInstance("RO");
wheelRO.parent = carBody;
wheelRO.position = new BABYLON.Vector3(2.5, -2, 2.8);

wheelFI.position = new BABYLON.Vector3(-4.5, -2, -2.8);
```

PG: <Playground id="#1YD970#542" title="Attach Wheels" description=" Attaching the wheels."/>

### Rotate Wheels

The animation is achieved using scene.registerAfterRender and small rotations within the render loop.

_Note:_ when using rotate and translate scene.register*After*Render is preferable to scene.register*Before*Render as
the calculations will take place after the world matrix has been computed for each mesh.

```javascript
scene.registerAfterRender(function () {
 wheelFI.rotate(BABYLON.Axis.Z, Math.PI / 64, BABYLON.Space.WORLD);
 wheelFO.rotate(BABYLON.Axis.Z, Math.PI / 64, BABYLON.Space.WORLD);
 wheelRI.rotate(BABYLON.Axis.Z, Math.PI / 64, BABYLON.Space.WORLD);
 wheelRO.rotate(BABYLON.Axis.Z, Math.PI / 64, BABYLON.Space.WORLD);
});
```

PG: <Playground id="#1YD970#543" title="Rotate Wheels" description="Adding a method to rotate the wheels."/>

### Path

To draw a path a sequence of points are needed. Starting with a circle of radius r in the xz plane with centre (0, 0, 0) calculate points around the
circle and vary r slightly and smoothly on the way round to give a less regular path. This is achieved by adding to the radius, at each angle, a fraction of r
times the sine of a multiple of the angle turned. In addition a ground is added.

Since on creation the side of the car is perpendicuar to the z axis the base circle will start with theta = 0 and x = r _ sin(theta) and z = r _ cos(theta).
This means that when the car can be positioned tangental to the circle by setting z = r.

Since the circle has been given a perturbation some small rotation of the car will be necessary for it to be truly tangential.

```javascript
var points = [];
var n = 50; // number of points - more points the slower the car
var r = 50; //radius
for (let i = 0; i < n + 1; i++) {
 points.push(new BABYLON.Vector3((r + (r / 5) * Math.sin((8 * i * Math.PI) / n)) * Math.cos((2 * i * Math.PI) / n), 0, (r + (r / 10) * Math.sin((6 * i * Math.PI) / n)) * Math.sin((2 * i * Math.PI) / n)));
}

var track = BABYLON.MeshBuilder.CreateLines("track", { points: points }, scene);
track.color = new BABYLON.Color3(0, 0, 0);

var ground = BABYLON.MeshBuilder.CreateGround("ground", { width: 3 * r, height: 3 * r }, scene);
```

PG: <Playground id="#172C5E#2" title="The Path" description="The path that the car will follow."/>

### Following the Path

The car will be moved forward using the sequence of points calculated for the path. As it moves round the path the car side should remain tangential to the path and the wheels should rotate about an axis that is normal to the path.
Since the normals to the path need to be calculated for the wheel axes it will be the normals that will be used to rotate the car.
The angle to be rotated at any point can be found from the angle between the previous normal and the current one. This angle can be found
by using the dot product of the two normal vectors. However the dot product only gives the amount of rotation not the direction.

Determining the normals at any point is achieved by forming the Path3D object from the array of points defining the path and extracting
the normals which are unit vectors.

```javascript
var path3d = new BABYLON.Path3D(points);
var normals = path3d.getNormals();
```

As can be seen from the diagram below the direction that the normal changes varies from clockwise to anti-clockwise depending whether the
path is a convex or concave curve.

![Rotation of Normal](/img/samples/car2.jpg)

Both normals lie in the xz plane and so the cross product of the two normals will lie in the y axis and so the direction of turn can be
determined from the sign of the y component of the cross product.

```javascript
theta = Math.acos(BABYLON.Vector3.Dot(normals[i], normals[i + 1])); //amount of turn
var dir = BABYLON.Vector3.Cross(normals[i], normals[i + 1]).y; //enables direction of turn to be found depending if +ve or -ve
var dir = dir / Math.abs(dir); //dir takes value 1 or -1
carBody.rotate(BABYLON.Axis.Y, dir * theta, BABYLON.Space.WORLD);
```

### Placing the Car

To stand on the ground the car will need to be lifted. To be set on the path it will be moved to the point (0, r, 4). Its current normal is
along the z axis so determine the turn necessary from

```javascript
var theta = Math.acos(BABYLON.Vector3.Dot(BABYLON.Axis.Z, normals[0]));
carBody.rotate(BABYLON.Axis.Y, theta, BABYLON.Space.WORLD);
```

### Animating the Car

The animation is achieved using scene.registerAfterRender. Within this render loop:
the car is moved forward from point to point;
it is rotated tangential to the path at the current point;
the wheels are now rotated a small amount about the _normal_ at the current point.

```javascript
var i = 0;
scene.registerAfterRender(function () {
 carBody.position.x = points[i].x;
 carBody.position.z = points[i].z;
 wheelFI.rotate(normals[i], Math.PI / 32, BABYLON.Space.WORLD);
 wheelFO.rotate(normals[i], Math.PI / 32, BABYLON.Space.WORLD);
 wheelRI.rotate(normals[i], Math.PI / 32, BABYLON.Space.WORLD);
 wheelRO.rotate(normals[i], Math.PI / 32, BABYLON.Space.WORLD);

 theta = Math.acos(BABYLON.Vector3.Dot(normals[i], normals[i + 1]));
 var dir = BABYLON.Vector3.Cross(normals[i], normals[i + 1]).y;
 var dir = dir / Math.abs(dir);
 carBody.rotate(BABYLON.Axis.Y, dir * theta, BABYLON.Space.WORLD);

 i = (i + 1) % (n - 1); //continuous looping
});
```

PG: <Playground id="#1YD970#582" title="Car Travels The Path" description="First prototype of car following a path"/>

## Correction

After allowing the finalised playground of the car to run for a while it can be seen that the rotating of the car becomes askew.
This is due to rounding errors in the floating point (probably).

The initial rotation quaternion is stored in _startRotation_ and is now applied to the car whenever it starts a new loop.

```javascript
if (i == 0) {
 carBody.rotationQuaternion = startRotation;
}
```

PG: <Playground id="#1YD970#583" title="Car Following a Path" description="Removed rotation errors for car path following ."/>

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#5" 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.

After considering the [issues](/guidedLearning/workshop/Issues) involved and slow [slow particles](/guidedLearning/workshop/Slow_Collide) we are now ready to consider **free particles**, ones that move with no restriction to their start position or velocity.

The velocity of a particle is its displacement per frame.


## Colliding with a Wall

Given a particle of radius r, at position p and velocity v in *frame n*, the particle will collide with a wall when it is travelling towards the wall in *frame n* and in *frame n+1* the centre of the particle, at p + v, is within a distance r from the wall or is moving away from the wall.

For example consider a left hand wall, with plane parallel to the YZ plane, and a particle travelling towards it with velocity (dx, dy, dz), dx &lt; 0.

In *frame n*, the position of the particle is (x, y, z) and during the time between *frame n* and *frame n+1* it overlapped the wall. At *frame n+1*, the particle may still be overlapping the wall and its centre may be to the right or left of the wall or, the particle may have gone beyond the wall completely. The 2D diagrams show the latter case but the calculations apply in all cases. Fig 16 indicates the particle passing through the wall.

![Fig 16](/img/samples/collide18.jpg) 
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Fig 16. 

The particle at *frame n+1*, is at position (x + dx, y + dy, z + dz)

Sometime between *frame n* and *frame n+1* the particle would just touch the wall as in Fig 17.

![Fig 17](/img/samples/collide19.jpg) 
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Fig 17. 

At this position let the displacement of the particle from its position in *frame n* be (dx1, dy1, dz1) and its displacement from this position to its position in *frame n+1* be (dx2, dy2, dz2). It follows that (dx, dy, dz) = (dx1, dy1, dz1) + (dx2, dy2, dz2), see Fig 18.

![Fig 18](/img/samples/collide20.jpg) 
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Fig 18. 

At the point of contact with this wall the component of velocity in the x direction would reverse and so the remaining x axis displacement before *frame n+1* would be -dx2, see Fig 19.

![Fig 19](/img/samples/collide21.jpg) 
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Fig 19. 

The particle velocity, after the collision is now (-dx, dy, dz). For *frame n+1*, we need the position of the particle to be at (x + dx1 - dx2 , y + dy, z + dz). Since before *frame n+1*, is displayed the velocity (-dx, dy, dz) will be added and so we need it position before this is done to be (x + dx1 - dx2 , y + dy, z + dz) - (-dx, dy, dz), see Fig 20.

![Fig 20](/img/samples/collide22.jpg) 
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Fig 20.

(x + dx1 - dx2 , y + dy, z + dz) - (-dx, dy, dz)

= (x + dx1 - dx2 + dx, y, z)

= (x + dx1 - dx2 + dx1 + dx2, y, z) 

= (x + 2dx1, y, z)

Which is the reflection of the particle at *frame n* in the plane parallel to the YZ plane through the centre of the particle, see Fig 21.

![Fig 21](/img/samples/collide23.jpg) 
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Fig 21.

This means after *frame n* is displayed the particle's position has to be reset as indicated.

## Colliding Particles

Given two particles P and Q of radius r, at positions p and q with velocities v and u respectively travelling towards each other in *frame n*. In *frame n+1* the centres of the particle are at p + v and q + u. Between *frame n* and frame n+1* the two particles would collide when there is a time t &lt;= 1 when the distance between the positions of the particles is 2r. See Fig 22.

![Fig 22](/img/samples/collide25.jpg) 
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Fig 22.

At time t, P is at p + vt and Q is at p + ut and P an Q will collide if there is a solution for t to the equation 

(p + vt - (q + ut)).(p + vt - (q + ut)) = 4r2

with 0 &lt; t &lt;= 1

This equation is a quadratic equation in t of the form at2 + bt + c = 0

(p + vt - (q + ut)).(p + vt - (q + ut)) = 4r2

(p - q +(v - u)t).(p - q +(v - u)t) = 4r2

(p - q).(p - q) + 2(p - q).(v - u)t + (v -u).(v - u)t2 = 4r2

(v -u).(v - u)t2 + 2(p - q).(v - u)t + (p - q).(p - q) - 4r2

so a = (v -u).(v - u), b = 2(p - q).(v - u), c = (p - q).(p - q) - 4r2

There will be a collision between *frame n* and *frame n+1* provided b2 - 4ac &gt; 0. In this case there will be two solutions for t the smallest value being where the particles first touch and the other at the end of the overlap.

Based on the above the following Playground shows two spheres and their paths. Should they collide their positions at first touch are shown. Their start positions and velocities may be set at lines 35 to 38.

PG: <Playground id="#A4HZTV" title="First Contact" description="Two moving spheres showing their paths and their positions at first contact."/>

### Reaction

Since only the velocities along the line joining the centres of the particles are affected during the collision we need to consider axes along this radial line and a tangential line. The particles are at first contact at time t, with P at p + vt and Q at q + ut

Let m = p + vt - (q + ut) and n = m/|m| a unit vector.

Then vr = (v.n)n is the component of v along n, and ur = (u.n)n the component of u along n and after collision these components are swapped. The tangential components for P and Q before collision are vt = v - (v.n)n and ut = u - (u.n)n respectively. 
After collision the velocity of 
P is va = ur + vt = (u.n)n + v - (v.n)n = v + ((u - v).n)n and that of 
Q is ua = vr + ut = (v.n)n + u - (u.n)n = u + ((v - u).n)n

Given that the particles collide between *frame n* and *frame n+1* what will the positions of P and Q be during *frame n+1*?

In *frame n*, the position of particle P is (px, py, pz) and the position of Q is (qx, qy, qz). For some time t &lt;= 1 the particles will make first contact. Fig 23 shows the positions of P and Q for *frame n*, their positions at time t, and their positions for *frame n+1* when the collision is not detected. The radial and tangential components of their displacements (= velocities) are also shown upto and after first contact.

![Fig 23](/img/samples/collide16.jpg) 
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Fig 23.

The displacement v can be split in vt and v(1 - t) and u can be split into u and u(1 - t) which take the particles to the point of contact and after the first contact. During the frame transition it is at the point of contact the displacements along the line of centres are exchanged.

Fig 24 shows the rearrangement of the component displacements and positions of the spheres when the collision is detected and component velocities along the line joining the centres are exchanged. Just before *frame n+1* this gives

particle P at p + vrt + vtt + ur(1 - t) + vt(1 - t) = p + vrt + ur(1 - t) + vt
and particle Q at q + urt + utt + vr(1 - t) + ut(1 - t) = q + urt + vr(1 - t) + ut 
as in Fig 24

![Fig 24](/img/samples/collide17.jpg) 
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Fig 24.

However, since before *frame n+1*, is displayed the velocities of P and Q will be added to the positions of P and Q and so we need these positions to have their velocities subtracted so that the correct positions are displayed during *frame n+1*. See Fig 25 

![Fig 25](/img/samples/collide24.jpg) 
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Fig 25.

P 
p + vrt + ur(1 - t) + vt - (ur + vt)

= p + vrt + ur(1 - t) - ur

= p + vrt + ur(1 - t) - urt - ur(1 - t)

= p + vrt - urt

= p + (vr - ur)t


Q 
q + urt + vr(1 - t) + ut - (vr + ut)

= q + urt + vr(1 - t) - vr

= q + urt + vr(1 - t) - vrt - vr(1 - t)

= q + urt - vrt

= q + (ur - vr)t


After a collision these values are used to recalculate the positions of particles before *frame n+1*.

The following Playground shows the first contact position of two particles and their paths before and after collision. Start position and velocities may be set on lines 36 to 39.

PG: <Playground id="#A4HZTV#1" title="Contact and Rebound" description="Shows the first contact position of two particles and their paths before and after collision."/>

This Playground fires particles randomly towards each other to see the effect when they collide.

PG: <Playground id="#A4HZTV#2" title="Random Collisions" description="Particles are fired randomly towards each other to see the effect when they collide."/>

## A Multitude of Particles

Combining all of the above the following Playgrounds put many particles inside a box and have them collide with the box and each other.

PG: <Playground id="#HIM0WS" title="Slow Moving Particles" description="Particles inside a box, collide with the box and each other."/>

PG: <Playground id="#HIM0WS#1" title="Fast Moving Particles" description="."/>

Maximum speeds, for both, can be changed on lines 21 to 23.

## Further Reading

[Slow Particles](/guidedLearning/workshop/Slow_Collide)

In this case an attempt is made to produce a box that will contain many particles, each a sphere of the same diameter and mass. The idea is for the particles to move around colliding with each other and the walls of the box, with the speed for each particle along its x axis, along its y axis and along its z axis being equal to the diameter of the particle or zero and for collisions to only take place if particles just touch the walls or each other.

It turns out that such a system is not possible when the particles are to obey the Newtonian physical laws for colliding spheres.

Other systems are produced, fitting the above conditions except for the rules for colliding.

## The Grid

Take a grid of cubes with the **origin cube** having its centre at the world origin. Each cube will have a side width of 2r, where r is the radius of each
particle. The position of any particle will be the centre of the cube it is occupying. The conditions for the speed of the particles means they each will lie wholly within a cube.

## The Collisions

When a particle hits the wall then its velocity perpendicular to the wall will be reversed.

When two particles collide in a perfectly elastic collision the Newtonian laws of physics give that their velocities along the line joining their centres are exchanged and they retain their velocities tangential to this line.

## The Walls

For a particle to just touch a wall the wall position must be of the form (2p + 1)r, p an integer.

![Fig 9](/img/samples/collide8.jpg) 
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Fig 9

## The Particles

Now having constrained the positions of the walls to ensure that the particles rebound on just touching them can the same be done for the particles themselves?

If the particles have an odd number of cubes between them they will meet only when overlapping completely. To ensure they meet
in a touching position they need to have an even number of cubes between them, as in Fig 10.

![Fig 10](/img/samples/collide9.jpg) 
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Fig 10

Take two particles a distance 4 cubes apart in the x direction and 2 in the y direction, one travelling upwards and the other to the left, as in Fig 11.

![Fig 11](/img/samples/collide10.jpg) 
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Fig 11

After two frames it is clear that the two particles would collide. The first issue is that they do not actually touch or intersect. There are two ways to overcome this. One way is to make the diameter of the particle equal to the length of a diagonal across the cube. The second is to state that a collision takes place when the distance between the positions of two particles is less than or equal to the length of a diagonal of the cube.

The second issue is more subtle and relates to the velocities of the particles after the collision. Fig 12 shows the velocities and positions
before and after a collision.

![Fig 12](/img/samples/collide11.jpg) 
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Fig 12

Consider a situation when two particles collide and obey the Newtonian rules.

The green arrows show the velocities before and after the collision and the blue arrows the components along and at right angles to the line of collision.

Note that after the collision the speeds no longer obey the initial rules of one cube distance along the x, y or z axes per frame and keep inside the cubes. So any attempt to maintain collisions only when the particles touch is fruitless. Also note that the vertical speed of the top particle has increased. The maximum possible vertical speed (or horizontal speeds) is 2&radic;3 r, the diagonal speed of a particle. At this speed and with no control over positioning a particle can escape the box.

Systems where the Newtonian laws of physics are obeyed is considered [TBA]. This page now considers other physics.

## Other Physics

Two simple physics could be:

1. Colliding particles swap velocities.
2. Colliding particles reverse velocities.

These at least ensure that speeds in the x, y and z directions are maintained and so particles cannot escape the box.

What about collisions between particles in these cases? To ensure contact, by just touching alone, then we have already seen that there must be an even number of cubes between them. Placing particles in the box so this conditions exists is not straightforward so simplify this to - every particle has two cubes between them. This means that placing a particle at the cube origin and counting cube positions from this point every cube with position of the form (3m, 3n, 3p), and only these cube positions, has a particle in it. Should one particle be missing then there will be two particles with an odd number of cubes between them which could meet by overlapping, as in Fig 13.

![Fig 13](/img/samples/collide12.jpg) 
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Fig 13

However setting random velocities to such particles could lead to a situation such as in Fig 14 which would again lead to particles totally overlapping.

![Fig 14](/img/samples/collide13.jpg) 
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Fig 14

Keeping the speed restrictions in the x, y and z directions to 2r and dropping the condition that particles can only make contact by touch and letting them fully overlap allows us to place the particles in any random cube. Movement is still within the grid cubes and particles will touch but not overlap the walls of the box.

## Collision Conditions

One condition already stated above is that the distance between the positions of two particles is less than or equal to the length of a diagonal of the cube which is 2&radic;3 r.

A second condition is that the particles must be travelling towards each other. By considering relative velocities one particle can be considered as still.
The component of velocity for the moving particle along the line joining their centres will be positive or negative depending weather it is moving away from or towards the other. The magnitude of the component velocity is found by using the dot product of their relative positions and relative velocities.

## Creating The Examples

The walls of the box are positioned using (2p + 1)r, for an integer p. Two parallel walls will be positioned at (-2p + 1)r and (2p + 1), p &gt; 0.

Particles can be positioned 2jr, where j is an integer with -p &lt;= j &lt;= p

To generate j randomly, use floor(1 - 2 \* random)

In the Playground code spaceMultiplier is used as the p.

The speed of all particles in the x, y and z directions is 2r or 0. For the particle velocity in each direction the speed will therefore be multiplied by -1, 0 or 1. The numbers -1, 0, and 1 can be generated by using floor(2.99 \* random - 1).

## Playground Examples

In both these examples on particle is colored red to aid focus on one particle if needed. Also by removing the comment markers, lines 140 and 144, in the swap example and lines137 and 141, in the reverse example you can see the path trace of the red particle.

Which one do you think gives the most random type movement?

PG: <Playground id="#CGSXR" title="Particles Swap Velocities" description="Colliding particles swap their velocities."/> 
PG: <Playground id="#CGSXR#1" title="Particles Reverse velocity" description="Colliding particles reverse their velocity."/>

Starting with a polygon as the footprint, a house is built by giving the footprint thickness (ply), extruding and adding door and window spaces at given positions.

**Please note that some functions used in this project uses Earcut, so, in non playground projects, you will have to add a reference to their [cdn](https://unpkg.com/earcut@2.1.1/dist/earcut.min.js) or download their [npm package](https://github.com/mapbox/earcut#install)**

## Data Structure

### Walls

**A footprint** is a sequence of consecutive corners in counter-clockwise order. Each **corner** is a Vector3 in the form (x, 0, z). This footprint forms the inner walls of the house, see Fig 1. The inner walls do not have to be set at right angles to each other.

![Footprint](/img/samples/house1.jpg)
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Fig 1

This footprint is then copied and extended by **ply** (the thickness of the walls) to form the base of the walls for the house.

The number of walls will be the number of corners in the footprint, with wall w extending from corner w. The position of each new corner is determined using trigonometry on half the angle formed at the corners.

If the number of walls is nbWalls the new corners are numbered by adding nbWalls to the corresponding inner corners. Then the base for wall w, consists of corners numbered, w, (w + 1) % nbWalls, w + nbWalls, (w + 1) % nbWalls + nbWalls. See Fig 2.

![Base of Walls](/img/samples/house2.jpg)
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Fig 2

The top of wall is formed by adding the **height** of the walls to the base corners to form the top corners, having the form of a Vector3 (x, height, z). The new corners are numbered by adding 2 \_ nbWalls to the corresponding base corners. The top of wall w will consist of corners numbered , w + 2 \_ nbWalls, (w + 1) % nbWalls + 2 \_ nbWalls, w + nbWalls + 2 \_ nbWalls, (w + 1) % nbWalls + nbWalls + 2 \* nbWalls. See Fig 3.

![Top of Walls](/img/samples/house3.jpg)
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Fig 3

## Walls Mesh

The table of positions for the vertexData buffer looks like this

| corner | position | |
| ---------------- | ------------------------------------------------------------- | -------------------------------- |
| 0 | x0, 0, z0 | &nbsp;&nbsp;&nbsp;&nbsp;&#x2B9D; |
| 1 | x1, 0, z1 | &nbsp;&nbsp;&nbsp;&nbsp;&#x2503; |
| 2 | x2, 0, z1 | **inner base** |
| .. | ..., ..., ... | &nbsp;&nbsp;&nbsp;&nbsp;&#x2503; |
| .. | ..., ..., ... | &nbsp;&nbsp;&nbsp;&nbsp;&#x2503; |
| nbWalls - 1 | xnbWalls - 1, 0, znbWalls - 1 | &nbsp;&nbsp;&nbsp;&nbsp;&#x2B9F; |
| nbWalls | xnbWalls, 0, znbWalls | &nbsp;&nbsp;&nbsp;&nbsp;&#x2B9D; |
| nbWalls + 1 | xnbWalls + 1, 0, znbWalls + 1 | &nbsp;&nbsp;&nbsp;&nbsp;&#x2503; |
| nbWalls + 2 | xnbWalls + 2, 0, znbWalls + 2 | **outer base** |
| .. | ..., ..., ... | &nbsp;&nbsp;&nbsp;&nbsp;&#x2503; |
| .. | ..., ..., ... | &nbsp;&nbsp;&nbsp;&nbsp;&#x2503; |
| 2 \* nbWalls - 1 | x2 \_ nbWalls - 1, 0, z2 \_ nbWalls - 1 | &nbsp;&nbsp;&nbsp;&nbsp;&#x2B9F; |
| 2 \* nbWalls | x2 \_ nbWalls, 0, z2 \_ nbWalls | &nbsp;&nbsp;&nbsp;&nbsp;&#x2B9D; |
| 2 \* nbWalls + 1 | x2 \_ nbWalls + 1, 0, z2 \_ nbWalls + 1 | &nbsp;&nbsp;&nbsp;&nbsp;&#x2503; |
| 2 \* nbWalls + 2 | x2 \_ nbWalls + 2, 0, z2 \_ nbWalls + 2 | **inner top** |
| .. | ..., ..., ... | &nbsp;&nbsp;&nbsp;&nbsp;&#x2503; |
| .. | ..., ..., ... | &nbsp;&nbsp;&nbsp;&nbsp;&#x2503; |
| 3 \* nbWalls - 1 | x3 \_ nbWalls - 1, 0, z3 \_ nbWalls - 1 | &nbsp;&nbsp;&nbsp;&nbsp;&#x2B9F; |
| 3 \* nbWalls | x3 \_ nbWalls, 0, z3 \_ nbWalls | &nbsp;&nbsp;&nbsp;&nbsp;&#x2B9D; |
| 3 \* nbWalls + 1 | x3 \_ nbWalls + 1, 0, z3 \_ nbWalls + 1 | &nbsp;&nbsp;&nbsp;&nbsp;&#x2503; |
| 3 \* nbWalls + 2 | x3 \_ nbWalls + 2, 0, z3 \_ nbWalls + 2 | **outer top** |
| .. | ..., ..., ... | &nbsp;&nbsp;&nbsp;&nbsp;&#x2503; |
| .. | ..., ..., ... | &nbsp;&nbsp;&nbsp;&nbsp;&#x2503; |
| 4 \* nbWalls - 1 | x4 \_ nbWalls - 1, 0, z4 \_ nbWalls - 1 | &nbsp;&nbsp;&nbsp;&nbsp;&#x2B9F; |

To form the mesh, the base, top, inner wall and outer wall have to be split into triangular facets by grouping sets of three corners for each and pushing these into the indices array. To form the normals in the correct direction the order of corners is important. For the base and the inner wall this is clockwise and for the top and outer wall this is counter-clockwise.

Fig 4 shows the corner numbers for a completed wall. For simplification this is without taking into account that for the final wall the far corners will be the starting corners so in any code each w + 1 must be calculated using modulo nbWalls.

![Wall w](/img/samples/house4.jpg)
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Fig 4

By corner number
base facets : w, w + 1, w + 1 + nbWalls, w, w + 1 + nbWalls, w + nbWalls

inner wall facets : w, w + 2nbWalls, w + 1 + 2nbWalls, w, w + 1 + 2nbWalls, w + 1

top facets : w + 1 + 3nbWalls, w + 1 + 2nbWalls, w + 2nbWalls, w + 3nbWalls, w + 1 + nbWalls, w + 2nbWalls

outer facets : w + 1 + 3nbWalls, w + 3nbWalls, w + nbWalls, w + 1 + nbWalls, w + 1 + 3nbWalls, w + nbWalls

PG: <Playground id="#4GBWI5" title="Blank House Walls" description="Walls with no doors or windows"/>

So far fairly straight forward, now to add door and window spaces.

## Door and Window Spaces.

For this project doors and windows must be rectangular and are just defined by their width and height. However a door space is assumed to be a space cut from the base and upwards, whereas a window space can be cut anywhere in the wall. Both types of spaces are cut at right angles to the wall they belong in.

The placement of door and window spaces must be checked by the user. They must not overlap and must be contained wholly within a wall. These conditions are not checked by the code.

A door has two properties, width and height. A doorspace has two properties - a door and left, which, when it is part of wall w, is its horizontal distance from the inner corner w.

A window has two properties, width and height. A windowspace has three properties - a window, left and top, which, when it is part of wall w, are its horizontal distance from the inner corner w and the vertical distance from the top of the wall to the top of the window. Top must be greater than zero and less than wall height - window height.

![Doors and Windows](/img/samples/house5.jpg)
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Fig 5

## Walls with Doors and Windows

To include the doors and walls the positions of their corners have to be added to the positions array.

So far the positions array has this form

[ inner corners base, outer corners base, inner corners top, outer corners top]

and each group of corners has 3 \* nbWalls entries.

Once the inner corner positions for the doors and windows are added then their outer corner positions are easily calculated.

Adding in the door positions will turn the wall from a rectangle to a concave polygon. Then the placement of the window positions will add holes to the polygon. Luckily there is already a method of triangulating a polygon using PolygonMeshBuilder. This will be used to triangulate the wall polygons and a new method wallBuild (based on the existing build method) can be created that will correctly correlate indices to vertices to form the necessary 3D mesh.

Whereas the top surface between the inner and outer walls will not be changed the base surface will now have to accommodate vertical sections to form the gaps for the doors. Also for each window, surfaces will have to be created at right angles to the inner and outer walls at the edges of the window.

Since for polygonMeshBuilder corners have to be in counter-clockwise consecutive order, all doorspaces for each wall will have to be sorted in increasing order of their left value.

At this stage code was written to add in the doors using existing positions. However as you can see in the following playground sharing vertices and normals made the triangular facets stand out.

PG: <Playground id="#4GBWI5#266" title="Using Shared Vertices" description="Show lighting effect on walls with shared vertices"/>

To stop this effect a flat shaded mesh is necessary and rather than just converting the existing mesh to a flat shaded one it was decided to re-code for a flat shaded mesh from the start. This simplified the procedures for adding in the edges to doors and windows. Also because the interior and exterior walls were now separate it gave the possibility of applying different materials and colors to these walls.

It was decided that edges to doors and windows would be exterior.

## Inner and Outer Walls with Doors and Windows Mesh

A flat shaded mesh will be created so the normals for all surfaces will be at right angles to the surface.

Consider inner wall w with one door and one window added as in Fig 6 showing corner labels.

Let Vlabel be the position of a corner with the given label in the form of the triple x, y, z.

![Polygon with Holes](/img/samples/house6.jpg)
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Fig 6

Using polygonMeshBuilder would create an interior wall positions array with

[Vw, Vdw0, Vdw1, Vdw2, Vdw3, Vw+1, Vw+1 + 2nbWalls, Vw + 2nbWalls, Vww0, Vww1, Vww2, Vwww3]

with indices 0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11

Where nbIndices is the current number of indices. These wall positions can be added to the house positions array and their indices incremented by nbIndices.

### General Case

More generally w+1 must be calculated using modulo nbWalls to complete the final wall of the house.

When d doors and ww windows have been calculated using PolygonMeshBuilder then the form of the positions for interior wall w is

[
position of base inner left wall corner,
4 door inner positions * number of doors,
position of base inner right,
position of top inner right wall corner,
position of top inner left wall corrner,
4 window inner positions * number of windows
]

These can be pushed to the house positions array and their wall indices to the house indices array, with a suitable increment to their value.
Add entries to the uvs array and colors array.

Also since this is the only interior wall for wall w record the end position of the house positions array so that later all other vertices can be linked to the exterior color.

The doors occupy positions with indices 1 to 4d and windows occupy positions with from index 1 + 4d. So the data for doors and windows can be extracted from the array.

Having done so incrementing their positions values by ply along their normals will give their positions on the exterior wall.

Data for each door and window giving inner and outer corners is saved.

Using this data the vertices for the exterior wall corresponding to wall w can be found.

[
position of base outer left wall corner,
4 door outer positions * number of doors,
position of base outer right,
position of top outer right wall corner,
position of top outer left wall corner,
4 window outer positions * number of windows
]

The these can be pushed to the house positions array. Since the wall indices array for these still apply but the order must be reversed, so that any normals formed will be in the correct direction, and appropriate increments added. Add appropriate values to the uv array.

## Top, Base and Edge Side for Walls, Doors and Windows.

All that is left now is to consider each base sections between doors, the side and top edges for the doors and base, top and side edges for the windows for wall w.

Since the data for all corners for each of these has now been saved it is fairly straight forward to form the correct triangular facets and uv values for each

Once all positions are in the house positions array and knowing that the first block only relates to the interior wall it is easy to link the remaining vertices to the exterior color.

## The Function and How to Use It.

The function **buildFromPlan** has five parameters and returns a mesh

_walls_ : an array of wall objects
_ply_ : thickness of each wall
_height_ : height of each wall
_options_ : an object containing 4 optional parameters
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;interiorUV: a Vector4(bottom left u, bottom left v, top right u, top right v)
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;exteriorUV: a Vector4(bottom left u, bottom left v, top right u, top right v)
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;interiorColor: a Color4(r, g, b, a)
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;exteriorColor: a Color4(r, g, b, a)
_scene_ : the scene

Examples

```javascript
buildFromPlan(walls, 0.3, 2, {}, scene);
buildFromPlan(walls, 1, 10, { interiorColor: new BABYLON.Color4(1, 0, 0, 1), exteriorColor: new BABYLON.Color4(0, 0.5, 1, 1) }, scene);
buildFromPlan(walls, 0.87, 6.21, { interiorUV: new BABYLON.Vector4(0, 0, 0.5, 1), exteriorUV: new BABYLON.Color4(0.5, 1, 1, 1) }, scene);
```

Each wall object has one two or three parameters

_corners_: an array of corner objects - required
_doorSpaces_ : an array of doorSpace objects - optional
_windowSpaces_ an array of windowSpace objects - optional

Each corner object has two parameters giving its position in 2D , example new corner(-3, 2)

Each doorSpace object has two parameters
_door_ : door object
_left_ : distance from left hand edge of wall

Each door object has two parameters, example new door(2, 1)
_width_ : width of door
_height_ : height of door

Each windowSpace object has three parameters
_window_ : window object
_left_ : distance from left hand edge of wall
_top_ : distance from top of wall

Each window object has two parameters, example new window(1, 2)
_width_ : width of window
_height_ : height of window

Using the plan in fig 7 we can construct a house.

![House floorplan](/img/samples/house7.jpg)
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Fig 7

Inner base corner coordinates

(-3, -2), (-1, -4), (1, -4), (3, -2), (5, -2), (5, 1), (2, 1), (2, 3), (-3, 3)

window 0 width 1.2, height 2.4

window 1 width 2, height 2,4

wall 0 - windowSpace window 0, left 0.814, top 0.4
wall 1 - windowSpace window 0, left 0.4 top 0.4
wall 2 - windowSpace window 0, left 0.814, top 0.4
wall 7 - windowSpace window 1, left 1.5, top 0.4
wall 8 - windowSpace window 1, left 1.5, top 0.4

door width 1 height 1.8

wall 6 - doorSpace door, left 1

Applying the plan leads to

PG: <Playground id="#4GBWI5#2144" title="House Built from a FloorPlan" description="A basic house built from a floorplan."/>

## Checking for an Intersect

One way to check in Babylon.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.

In the [issues](/guidedLearning/workshop/Issues) we found that it is necessary to keep the speed, the distance moved per frame, of particles to below, twice the radius of a particle, to ensure they intersect with walls or each other. Slow particles are those where the initial speed meets this restriction. 
When the resultant velocities after the collision are based on Newtonian physics for perfectly elastic particles then there are situations when the speeds of particles can increase to infinity.

## The Collisions

For Newtonian physics - 

When a particle hits the wall then its velocity perpendicular to the wall will be reversed.

When two particles collide their velocities along the line joining their centres are exchanged and they retain their velocities tangential to this line.

Under the right circumstances it is possible for the speed of a number of particles to all be given additively to one particle.

In Fig 14 the positions of the four pink particles are shown as at frame 1. Each with a radius r and speed v, their velocities shown by the blue arrows. Their positions at frame 2 are shown in grey. At frame 3 the dark grey particles have moved to the red positions, each now having a speed of 2&radic;v. By frame 4 the darker red particle has moved to the position shown in purple now with a speed of 2v. So if the particles had started with a velocity of 0.6r by the fourth frame the vertical speed of one of the particles will be 2.4r, fast enough to avoid intersection with a wall or another sphere.

Given that the dark red particles reaches position (x, y, 0) when its speed reaches twice the velocity of the pink particles then the necessary positions for their start are shown in Fig 15.

![Fig 15](/img/samples/collide14.jpg)
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Fig 15

The following Playgrounds use four such sets of particles, to produce four particles that combine to give one particle a speed four times that of the original particles. In each case the higher two groups are set in the XY plane and the lower two groups are in the YZ plane. 

PG: <Playground id="#1DJ7RH" title="Collision Increases Speed" description="Shows how collsions increase speed."/> 
PG: <Playground id="#1DJ7RH#1" title="Increases Speed with Trails" description="Shows how collsions increase speed with trail markers for path."/> 
PG: <Playground id="#1DJ7RH#2" title="Increases Speed with More Spacing" description="Shows the effect of spacing"/> 

## Escaping Particles

In the above examples the four fold increase in speed depended on setting the particles in particular positions. In the case of randomly positioning particles, with random velocities, in a box then it is less likely that this will happen but it is possible.

In the Playground below, there are occasions when particles escape the box even though there initial speeds are set to below 2r. You may need to run the code more than once to see the effect.

PG: <Playground id="#MYGV6#3" title="Escaping Particles" description="Shows how increase speed allows particles to leave the box"/> 

The maximum speed of the particles can be changed on lines 21 to 23. Lowering the values for the speed decreases the probability of escape. 

A single red particle is included so that its reaction can be followed.

## Stopping the Escapes

The easiest way to stop the particles escaping is to rebound from a wall if the displacement of a particle is less than the radius. Any particle that is close enough to the wall will rebound, as will any particle that passes through the wall since its displacement from the wall will be negative and so must be less than the radius.

Making no changes to the intersection between particles means there can be times that particles will pass through each other. A high number of particles means that this is not noticeable.

The following Playground is an example that uses the above method to stop particles escaping. One downside is that particles can be seen breaching the walls.

PG: <Playground id="#MYGV6#4" title="Particles Stopped from Escaping" description="Reverse velocity if displacement from wall is negative."/>

The maximum speed of the particles can be changed on lines 21 to 23. 

A single red particle is included so that its reaction can be followed.

## Conclusion

To produce a system of collisions using Newtonian physics the path of a particle between frames must be determined.

![lean and turn](/img/snippets/roller.png)

In the first image the carriage leans and turns as it follows the track. In the second image the carriage leans and it is the people inside that turn to look around. The 'createTrack' function can be used to simulate either of these two events.

A carriage can be a mesh (with children if wanted), camera or even a point light. A track is a sequence of points in 3D space and for each point rotational data that determines the orientation of the mesh following it, and where necessary any children of the mesh. This rotational data is built by specifying parameters along sections of the track. The default starting position for a carriage is, as you would expect, is with its local x, y and z axis in the directions of the world axes.

A **track** is created using

```javascript
var track = createTrack(points, sections);
```

where points is an array of Vector3s and sections is an array of sections. A section is constructed by giving its starting point (an index of the points array) and an options object (which may be empty), as in

```javascript
var section0 = new sectionData(0, options0);
var section1 = new sectionData(100, {});
var section2 = new sectionData(120, options2);
var section3 = new sectionData(220, { lean: 0, leanTwists: 0, leanWaves: 0, leanWaveAngle: 0 });
var section4 = new sectionData(240, { turn: 0, turnTwists: 0, turnWaves: 0, turnWaveAngle: 0 });
```

Sections added to the sections array must be in increasing index order. The rotations in any one section are built from the options given in that section and some options from the following section. The following playground allows you to play with these options and others.

PG: <Playground id="#HSMDF2#6" title="Short Track Example" description="."/>

## Section Options

There are two types of rotation 'a lean' and a 'turn' and both may be applied to any section of track. Some illustrative examples are used better understand these. The lean at each point is shown in red and the turn in green, defaults for both are 0. Twists (defaults 0) force complete rotations, waves, with a wave angle, force a rotation to the maximum set by the wave angle followed by a rotation in the reverse direction.

In these examples the track is simply a straight line formed from 100 points and two sections, section0 includes all points from 0 to 99. The second section is an empty section of track but is needed as a device to specify the lean and turn at the track end.

### Leaning

The initial lean comes from section0 and the final lean from section 1.

A lean is the rotation of the carriage about the track direction.

![lean zero track](/img/snippets/track1.jpg) initial lean is 0, final lean is zero

![lean at end track](/img/snippets/track2.jpg) initial lean is 0, final lean is &pi; / 2

![lean at start track](/img/snippets/track3.jpg) initial lean is &pi; / 2, final lean is 0

The value of leanTwists (positive integer, default 0) gives the number of complete rotations about the track over that section of track.

![lean twists track](/img/snippets/track4.jpg) initial lean is 0, final lean is 0, leanTwists is 2

The value of waveTwists (positive integer, default 0) gives the number of leans to one side of the track followed by a lean to the other side depending on the lean wave angle over that section of track.

![lean waves track](/img/snippets/track5.jpg) initial lean is 0, final lean is 0, leanWaves is 2, leanWaveAngle is &pi; / 2

When both the values of leanWaves and leanWaveAngle or non zero they will override any value given to leanTwists.

### Turning

The initial turn comes from section0 and the final turn from section 1.

A turn is the rotation of the carriage about its local Y axis. (It can alternatively be the rotation of the children of the carriage mesh)

![turn zero track](/img/snippets/track6.jpg) initial turn is 0, final turn is zero

![turn at end track](/img/snippets/track7.jpg) initial turn is 0, final turn is &pi; / 2

![turn at start track](/img/snippets/track8.jpg)
initial turn is &pi; / 2, final turn is 0

The value of turnTwists (positive integer, default 0) gives the number of complete rotations about the track over that section of track.

![turn twists track](/img/snippets/track9.jpg) initial turn is 0, final turn is 0, turnTwists is 2

The value of waveTwists (positive integer, default 0) gives the number of turns to one side of the track followed by a turn to the other side depending on the turn wave angle over that section of track.

![turn waves track](/img/snippets/track10.jpg) initial turn is 0, final turn is 0, turnWaves is 2, turnWaveAngle is &pi; / 2

When both the values of turnWaves and turnWaveAngle or non zero they will override any value given to turnTwists.

### Leaning and Turning

It is possible to use both the lean and turn parameters

![lean and turn track](/img/snippets/track11.jpg) both lean and turn are used

### Parameters

The options parameters in a section are

- lean: angle of lean about direction of travel at start of section;
- leanTwists: number of twists against direction of travel over the section;
- leanWaves: number of waves against direction of travel over the section;
- leanWaveAngle: additional angle of lean applied during a wave;
- turn: angle of turn about local carriage y axis at start of section;
- turnTwists: number of twists about local carriage y axis over the section;
- turnWaves: number of waves about local carriage y axis over the section;
- turnWaveAngle: additional angle of turn applied during a wave.

## Data Returned for Track Object

Using

```javascript
var track = createTrack(points, sections);
```

gives you a set of arrays of matrices, where each element with index **i** is the data for the points array at **i**.

- track.directions: each element is the direction of travel;
- track.rotations: each element is a combination of the lean and turn rotations;
- track.carriageRotations: each element is the lean rotation;
- track.passengerRotations: each element is the turn rotation.

## Closed Tracks

As an example of a closed path take a circle formed from 500 points

```javascript
var points = [];
var n = 400; // number of points
var r = 20; //radius
for (let i = 0; i < n; i++) {
 points.push(new BABYLON.Vector3(r * Math.cos((i * 2 * Math.PI) / n), 0, r * Math.sin((i * 2 * Math.PI) / n)));
}
```

When drawing a line to represent the path of the track it is necessary to push points[0] to the end to draw a closed path. However once the line is drawn this must be removed using pop before creating a track.

```javascript
points.push(points[0]); // push to close path
var lines = BABYLON.MeshBuilder.CreateLines("lines", { points: points }, scene); //draw path of track
points.pop(); // remove before track creation
```

Also before creating the track the sections needed must be determined. In this case split into four equal sections. Section0 from 0 to 124, section1 from 125 to 249, section2 from 250 to 374 and section 3 from 375 to 0.

```javascript
var section0 = new sectionData(0, options0);
var section1 = new sectionData(125, options1);
var section2 = new sectionData(250, options2);
var section3 = new sectionData(375, options3);

var sections = [section0, section1, section2, section3];

var track = createTrack(points, sections);
```

PG: <Playground id="#HSMDF2#7" title="Closed Track Example" description="."/>

## Open Tracks

As an example of a open path take three quarters of a circle formed from 375 points

```javascript
var points = [];
var n = 375; // number of points
var r = 20; //radius
for (let i = 0; i < n; i++) {
 points.push(new BABYLON.Vector3(r * Math.cos((i * 3 * Math.PI) / (2 * n)), 0, r * Math.sin((i * 3 * Math.PI) / (2 * n))));
}
```

Drawing a line to represent the path of the track may be done directly.

```javascript
var lines = BABYLON.MeshBuilder.CreateLines("lines", { points: points }, scene); //draw path of track
```

Before creating the track the sections needed must be determined. In this case split into three equal sections. Section0 from 0 to 124, section1 from 125 to 249 and section2 from 250 to 374. A fourth dummy section, section3, is needed to provide the data on the final lean and turn at the end of the track. The starting index for the dummy section, at the end, should always be the number of points in the open path, in this case 375.

```javascript
var section0 = new sectionData(0, options0);
var section1 = new sectionData(125, options1);
var section2 = new sectionData(250, options2);
var section3 = new sectionData(375, options3); //Dummy section

var sections = [section0, section1, section2, section3];

var track = createTrack(points, sections);
```

PG: <Playground id="#HSMDF2#8" title="Open Track Example" description="."/>

## Using the Built Track

Data from the track can be used to produce quaternions to rotate a mesh or to produce lines showing the direction of rotations or even rails parallel to the track path. Initially just animation around the track is considered.

## From Matrices to Animation

In these examples `scene.registerAfterRender` is used to create the animation. One aspect that governs the speed of the animation is the distance between the points, so always take this into consideration when designing you path for the track. Of course, depending on how your path is built, you can vary the number of points per length of section. Note that for curved paths it is unlikely a constant speed is obtainable as the distance between points will vary. Often this is not noticeable. You can also produce variations in speed when you construct the quaternions to rotate the carriage and or passengers.

Take a carriage and its contents, forged together by

```javascript
contents.parent = carriage;
```

At any point, index **i** on the track position is from

```javascript
carriage.position = points[i];
```

Firstly take the contents as freight, i.e. it moves with the carriage. At any point, index **i** rotation of both is given by

```javascript
carriage.rotationQuaternion = BABYLON.Quaternion.FromRotationMatrix(track.rotations[i]);
```

When you take the contents as a passenger, i.e. somebody who can turn to look around the carriage and passenger rotation are separated

```javascript
carriage.rotationQuaternion = BABYLON.Quaternion.FromRotationMatrix(track.carriageRotations[i]);
contents.rotationQuaternion = BABYLON.Quaternion.FromRotationMatrix(track.passengerRotations[i]);
```

These can be built from a simple loop.

Now throw a speed variable into the loop. When the speed is 1 or more, an integer **s** say, then jump from **i** to **i + s**. When **s** is not an integer round it to the nearest integer. When **s** is less than 1 you need to interpolate between points. When **s** is 0.25, for example you need 3 extra points between **i** and **i + 1**, that is including the point at **i** 4 points, which is found from 1 / s.

Just considering the x coordinates

![drag](/img/snippets/drag.jpg)

between index **i** and **i + 1** the distance to be covered each frame is deltaX = (xi + 1 - xi) / 4 .

The multiplier for deltaX moving along the interpolated points is 0, 1, 2, 3, 0, 1, 2, 3, 0 etc., which is an increasing integer sequence modulo 4.

More generally calling this multiplier the **drag** on the speed, then **drag** = Math.round( 1 / speed), to ensure an integer and the multiplier for deltaX is an increasing sequence modulo **drag**.

Use

```javascript
var deltaI = 0;

deltaI = (deltaI + 1) % drag;
```

to obtain the multiplier sequence.

Taking into account speed and whether the contents are freight or passenger you can generate a sequence of positions and rotations from

```javascript
var nbPoints = points.length;
var i = 0;
var deltaI = 0;
var pace = Math.round(speed);
var drag = Math.round(1 / speed);

var carriagePositions = [];
var carriageRotations = [];
var contentsRotations = [];

var carPosition = BABYLON.Vector3.Zero();

while (i < nbPoints) {
 if (speed >= 1) {
 carriagePositions.push(points[i]);
 if (isFreight) {
 carriageRotations.push(BABYLON.Quaternion.FromRotationMatrix(track.rotations[i]));
 } else {
 carriageRotations.push(BABYLON.Quaternion.FromRotationMatrix(track.carriageRotations[i]));
 contentsRotations.push(BABYLON.Quaternion.FromRotationMatrix(track.passengerRotations[i]));
 }
 i += pace;
 } else {
 tempPosition.x = points[i].x + (deltaI * (points[(i + 1) % nbPoints].x - points[i].x)) / drag;
 tempPosition.y = points[i].y + (deltaI * (points[(i + 1) % nbPoints].y - points[i].y)) / drag;
 tempPosition.z = points[i].z + (deltaI * (points[(i + 1) % nbPoints].z - points[i].z)) / drag;

 carriagePositions.push(tempPosition.clone());

 if (isFreight) {
 carriageRotations.push(BABYLON.Quaternion.FromRotationMatrix(track.rotations[i]));
 } else {
 carriageRotations.push(BABYLON.Quaternion.FromRotationMatrix(track.carriageRotations[i]));
 contentsRotations.push(BABYLON.Quaternion.FromRotationMatrix(track.passengerRotations[i]));
 }
 i = Math.floor(i + (deltaI + 1) / drag);
 deltaI = (deltaI + 1) % drag;
 }
}
```

### Animation

The animation uses the above in

```javascript
i = 0;
var nbSteps = carriagePositions.length;
var animate = true;
scene.registerAfterRender(function () {
 carrriage.position = carriagePositions[i];
 carrriage.rotationQuaternion = carriageRotations[i];
 if (!isFreight) {
 contents.rotationQuaternion = passengerRotations[i];
 }

 i += 1;
 i %= nbSteps;
});
```

## Showing Axes

The data returned by 'createTrack' can be used to produce the lines showing the intended directions of the local axes 0f the carriage at any of the points (as seen in the images and playgrounds above). These are the required tangents, normals and binormals of the path for the carriage to follow. Initially these are tangent = (1, 0, 0), normal = (0, 1, 0) and binormal = (0, 0, 1).

The following function will produce arrays or tangents, normals and binormals

```javascript
var tangents = [];
var normals = [];
var binormals = [];
var buildVectors = function() {
 normals = [];
 binormals = [];
 for(let i = 0; i < nbPoints; i++) {
 tangents.push(BABYLON.Vector3.TransformNormal(BABYLON.Axis.X, track.railDirections[i]));
 if (isFreight) {
 normals.push(BABYLON.Vector3.TransformNormal(BABYLON.Axis.Y, track.rotations[i]));
 binormals.push(BABYLON.Vector3.TransformNormalToRef(BABYLON.Axis.Z, track.rotations[i]);
 }
 else {
 normals.push(BABYLON.Vector3.TransformNormal(BABYLON.Axis.Y, track.carriageRotations[i]);
 binormals.push(BABYLON.Vector3.TransformNormal(BABYLON.Axis.Z, track.carriageRotations[i]);
 }
 }
 }
```

The following function will produce a lineSystem drawing vectors from a series of points and so will draw tangents, normals and binormals.

```javascript
function drawVectors(vectors, positions, size, color) {
 color = color || BABYLON.Color3.White();
 size = size || 1;

 var lines = [];
 for (let i = 0; i < vectors.length - 1; i++) {
 var v1 = positions[i];
 var v2 = v1.add(vectors[i].scale(size));
 lines.push([v1, v2]);
 }
 var vectorLines = BABYLON.MeshBuilder.CreateLineSystem("vectorLines", { lines: lines }, sc);
 vectorLines.color = color;
 return vectorLines;
}
```

## Illustrating the Path

### Using a Ribbon to Create a Simple Velodrome

In this next playground a simple velodrome track is built from a ribbon.

PG: <Playground id="#HSMDF2#9" title="Velodrome Example" description="."/>

The normals and binormals of the track are used to create two paths for the ribbon, with a given offset and height. So that the velodrome track sits beneath the wheels a radial vector (from the origin to a point on the track) is used to extend the track outwards.

To produce a smooth velodrome track not all points are necessary. In this example only one in five are used.

```javascript
for (let i = 0; i < points.length; i += 5) {
 radials[i] = points[i].clone().normalize();
 upperPoints.push(points[i].add(binormals[i].scale(offset)).add(normals[i].scale(height)).add(radials[i].scale(extend)));
 lowerPoints.push(points[i].subtract(binormals[i].scale(offset)).subtract(normals[i].scale(height)).add(radials[i].scale(extend)));
}

upperPoints.push(upperPoints[0]); //close path
lowerPoints.push(lowerPoints[0]); //close path

var ribbon = BABYLON.MeshBuilder.CreateRibbon("ribbon", { pathArray: [upperPoints, lowerPoints], sideOrientation: BABYLON.Mesh.DOUBLESIDE }, scene);
```

Also note that since cylinders are created with their faces horizontal, the wheels are rotated by &pi; / 2 radians and this transformation is baked into the vertices. This ensures that the wheels maintain their intended orientation as the track rotation data is applied.

### Using Tubes and Instances to Create a Roller Coaster

For this roller coaster only the lean angle is used for the carriage and the passenger rotation used to turn the passenger to look out at the start of the run.
In this playground paths created either side of the track are used to build tubes and the same track carriage rotational data used to place sleepers underneath the rails.

PG: <Playground id="#SQFG0Q#5" title="Roller Coaster Overview" description="."/>
PG: <Playground id="#SQFG0Q#6" title="Roller Coaster Passenger View" description="Passenger View From Roller Coaster"/>

```javascript
for (let i = 0; i < points.length; i += 5) {
 BABYLON.Vector3.TransformNormalToRef(BABYLON.Axis.Y, track.carriageRotations[i], normal);
 BABYLON.Vector3.TransformNormalToRef(BABYLON.Axis.Z, track.carriageRotations[i], binormal);
 plusPoints.push(points[i].add(binormal.scale(offset)).add(normal.scale(height)));
 negPoints.push(points[i].subtract(binormal.scale(offset)).add(normal.scale(height)));

 var nsleeper = sleeper.createInstance("");

 nsleeper.position.x = points[i].x;
 nsleeper.position.y = points[i].y;
 nsleeper.position.z = points[i].z;

 nsleeper.rotationQuaternion = BABYLON.Quaternion.FromRotationMatrix(track.carriageRotations[i]);
 nsleeper.position.subtractInPlace(normal.scale(0.5));
}

plusPoints.push(plusPoints[0]);
negPoints.push(negPoints[0]);

var plusTube = BABYLON.MeshBuilder.CreateTube("tube", { path: plusPoints, radius: 0.1, tessellation: 4 }, scene);
var negTube = BABYLON.MeshBuilder.CreateTube("tube", { path: negPoints, radius: 0.1, tessellation: 4 }, scene);
```

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 (0 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 (let 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 (let 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 (let 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."/>

## Vertical Wave with Vertex Shader

As with any code it is important to have a firm idea of what you want to achieve, what is possible to code and 
a design. 

## Requirements
The requirements are a row of many boxes that move vertically in a wave motion. The motion will be achieved by 
changing the apparent positions of all vertices within a Vertex Shader. To be clear the positions of the boxes within 
the scene model will not be altered. What will be changed through the Vertex Shader is their projection onto the screen.

## First Stage Design
The boxes will be generated using the Solid Particle System as this deals with a multitude of repeated boxes efficiently. 
The vertical height of a box at any time will depend on the time and its position along the x axis using the sin function.

## First Challenge
Generally coding this project in Javascript, for example, would give access to the position of a box and so
```Javascript
box.position.y = Math.sin(box.position.x + time)
```
could be used.

However the data passed to a Vertex Shader Code is the attributes of the vertices of a mesh or is through using uniforms. Also the 
Vertex Shader Code applies to a single vertex with no access to any other vertices. 
Since the x coordinate of vertices on the left hand side of the box will differ by the size of the box to those on the right hand side. 
So sin(xLeft + time) with differ from sin(xRight + time) distorting the box. 

What is needed is a method of obtaining the same number h, from the numbers xLeft and xRight. 

## Second Stage Design

The boxes are cubes arranged equally spaced with the following parameters, *size* of box, *gap* between boxes and *spacing* = *size* + *gap*

![spaced boxes](/img/how_to/Shaders/wave1.jpg)

The number of boxes n will be odd, numbered from the left starting with 0. 

The box i will be at position (i - floor(n/2)) \* *spacing* + *size*/2

For example when n = 5, floor(n/2) = 2 and the left hand edges of the boxes 0 to 4 will have positions

-2 \* *spacing*, -1 \* *spacing*, 0, 1 \* *spacing*, 2 \* *spacing* respectively. Adding size to these gives their hand edges.

![spaced boxes positions](/img/how_to/Shaders/wave2.jpg)

Dividing these left and right hand edge positions by *spacing* gives a pair of numbers for each box of

-2, -2 + (*size*/*spacing*), &nbsp;&nbsp;&nbsp;-1, -1 + (*size*/*spacing*), &nbsp;&nbsp;&nbsp;0, (*size*/*spacing*), &nbsp;&nbsp;&nbsp;1, 1 + (*size*/*spacing*), &nbsp;&nbsp;&nbsp;2, 2 + (*size*/*spacing*).

Since *spacing* = *size* + *gap* *spacing* &gt; *size* and so (*size*/*spacing*) &lt; 1 and it follows that applying the 
function floor to each of these numbers gives 

-2, -2, &nbsp;&nbsp;&nbsp;-1, -1, &nbsp;&nbsp;&nbsp; &nbsp;&nbsp;&nbsp;0, 0, &nbsp;&nbsp;&nbsp;1, 1, &nbsp;&nbsp;&nbsp;2,2.

Hence obtaining a number h that is the same from the numbers xLeft and xRight. 
For a box the x coordinate of any vertex will either be on a left hand or a right hand edge and so for each box *x/spacing* 
will give a unique number. 

## Third Stage Design

Within the Vertex Shader Main function 

```
vec3 p = position;
float bn = floor(position.x / box_spacing);
p.y = p.y + sin(time + bn/4.0);
gl_Position = worldViewProjection * vec4(p, 1.0);
```

where time and box_spacing are uniforms.

## SPS Code

```
//Create SPS of Boxes
var boxes = 101; //odd number
var box_size = 0.25; // must be float
var box_gap = box_size/2;
var box_spacing = box_size + box_gap;
var box = BABYLON.MeshBuilder.CreateBox("box", {size:box_size}, scene);

var boxes_SPS = new BABYLON.SolidParticleSystem("boxesSPS", scene, {updatable: false});
 
//function to position boxes
var set_boxes = function(particle, i, s) { 
 var mid_point = Math.floor(boxes/2);
 particle.position.x = (i - mid_point) * box_spacing + box_size/2;
}

boxes_SPS.addShape(box, boxes, {positionFunction:set_boxes}); 
var boxes = boxes_SPS.buildMesh(); // mesh of leaves
box.dispose();
```

## Shader Material Code

### Vertex Shader

```
// Attributes
attribute vec3 position;
attribute vec3 normal;
attribute vec2 uv;

// Uniforms
uniform mat4 worldViewProjection;
uniform float box_spacing;
uniform float time;

// Normal
varying vec2 vUV;

void main(void) {
 vec3 p = position;
 float bn = floor(position.x / box_spacing);
 p.y = p.y + sin(time + bn/4.0);
 gl_Position = worldViewProjection * vec4(p, 1.0);

 vUV = uv;
}
```
### Fragment Shader

```
varying vec2 vUV;

uniform sampler2D textureSampler;

void main(void) {
 gl_FragColor = texture2D(textureSampler, vUV);
}
```

### Set Material

```javascript
var shaderMaterial = new BABYLON.ShaderMaterial("shader", scene, {
		vertexElement: "vertexShaderCode",
		fragmentElement: "fragmentShaderCode",
	},
	{
		attributes: ["position", "normal", "uv"],
		uniforms: ["world", "worldView", "worldViewProjection", "view", "projection"]
	});


var mainTexture = new BABYLON.Texture("amiga.jpg", scene);

shaderMaterial.setTexture("textureSampler", mainTexture);
```

### Animation Loop

```javascript
var time = 0;
scene.registerBeforeRender(function() {
 boxes.material.setFloat("time", time);
 time +=0.1;
});
```

## Shader Builder Code

### Shader Code

```javascript
BABYLONX.ShaderBuilder.InitializeEngine();
		
var shaderMaterial = new BABYLONX.ShaderBuilder() 
	.Solid({ b: 1 })
	.SetUniform('box_spacing', 'float')
 .Map({path:'amiga.jpg' }) 
	.VertexShader(
 ' float bn = pos.x/box_spacing;\
 result = vec4( pos.x, pos.y + sin(time + bn/4.0), pos.z ,1.);')
	.BuildMaterial(scene);
```

### Set Material

```javascript
boxes.material = shaderMaterial;
boxes.material.setFloat("box_spacing", box_spacing)
```

### Animation Loop

```javascript
var time = 0;
scene.registerBeforeRender(function () {

	time += 0.1;

 new BABYLONX.ShaderMaterialHelper().SetUniforms(
 scene.meshes,
 camera.position,
 camera.target,
 { x: 0, y: 0 },
 { x: 100, y: 100 },
 time);
	 
});
```

## Vertical Wave

[External Example - Shader Material](http://babylonjsguide.github.io/examples/bouncecode.html)

PG: <Playground id="#1OH09K#3" title="Vertical Wave" description="Built from Shader Material."/>

[External Example - Shader Builder](http://babylonjsguide.github.io/examples/bouncecodeSB.html)

PG: <Playground id="#1NXPC3#4" title="Vertical Wave" description="Built from Shader Builder."/>

As with any code it is important to have a firm idea of what you want to achieve, what is possible to code and
a design.

## Requirements

The requirements are for a collection of colored facets to bursts out from a central position so that each fragment lies on the surface of an expanding sphere.
All fragments should be equally spaced on the sphere and should change color during the expansion, fading over time.

## First Stage Design

A sphere created in Babylon.js is made up of facets where vertices of adjoining facets share normals to ensure a smooth surface.
Converting the sphere to a flat shaded mesh will give each facet its own set of normals which will be the mathematical normals for the plane of the facet.
To make a facet travel outwards from the centre over time its position at any time will be _start position + normal \* function of time_

The sphere is flat shaded and the normals for the three vertices of each facet will be the same. The original position of each vertex and its normal
are accessible to the shader as attributes passing time as a uniform will be enough.

To obtain an initially fast expansion the slowing down a logarithmic function of time will be used.

## Second Stage Design

The color and transparency of all the facets will be the same at the same time and so a change to each component of the color of a vertex
can be applied as a function of time.

## Third Stage Design

After the first coding of the shaders adjustments were made to the functions of time, manually, to obtain a satisfactory appearance to the burst of facets.

## Shader Material Code

### Vertex Shader Main Function

```
void main(void) {
 vec3 p = position;
 vec3 j = vec3(0., -1.0, 0.);
 p = p + normal * log2(1. + time) * 25.0;
 gl_Position = worldViewProjection * vec4(p, 1.0);
}
```

### Fragment Shader Main Function

```
void main(void) {
 gl_FragColor = vec4(1. - log2(1. + time)/100., 1. * log2(1. + time), 0., 1. - log2(1. + time/2.)/log2(1. + 3.95));
}
```

### Sphere

```javascript
var sphere = BABYLON.MeshBuilder.CreateSphere("sphere", { diameter: 10 }, scene);
sphere.convertToFlatShadedMesh();

sphere.material = shaderMaterial;
```

### Animation Loop

```javascript
var t = 0;
var time = 0;
scene.registerBeforeRender(function () {
 if (time < 8) {
 sphere.material.setFloat("time", time);
 time += 0.1;
 } else {
 sphere.dispose();
 }
});
```

## Fireworks

[External Example - Shader Material](http://babylonjsguide.github.io/examples/fireworkcode.html) 
PG: <Playground id="#1OH09K#1672" title="Fireworks" description="Build from Shader Material." image="/img/playgroundsAndNMEs/pg-1OH09K-4.png"/>

For any house there is a range of different types of roof that can be added and so there is no automatic way to use the footprint of a house to build a roof directly. However with a little bit of manual design there are methods that can complete the build. Here we present two ways to design and create a hip roof. The example used is based on the [design](/guidedLearning/workshop/House) and [coding](/guidedLearning/workshop/House_Use) of this [house](https://www.babylonjs-playground.com/#4GBWI5#265).

**Please note that some functions used in this project uses Earcut, so, in non playground projects, you will have to add a reference to their [CDN](https://unpkg.com/earcut@2.1.1/dist/earcut.min.js) or download their [npm package](https://github.com/mapbox/earcut#install)**

## Design Whole Roof

In this case the **rise**, or roof height, is the same for all sections of the roof.

The **footprint** for the house defines the inner walls of the house, from which the data for the outer walls is calculated. A roof overhangs the outer walls. The footprint of the roof, or **roofprint**, defines the corners of this overhang. In _Fig 1_ the black area shows the thickness, or **ply** of the house walls and the red the **overhang** of the roofprint.

![overhang](/img/samples/roof1.jpg)
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Fig 1

Since in creating the house the _ply_, house _height_ and the footprint _corners_ have already been created they are used to create the roofprint, as in

```javascript
var overhang = 0.2;
var overlap = ply + overhang;
var wholeRoofprint = roofprint(corners, overlap, height);
```

The function **roofprint** returns a list of Vector3 representing the corners of the roof floor in counter clockwise order.

Using the roofprint the floor of the roof (or top ceiling) can be added as a mesh.

PG: <Playground id="#1Z71FW#41" title="Example Roof Floor" description="."/>

## Plan of Roof

Though it is possibly more accurate to use the roofprint as a guide to a plan for the roof it is probably easier (in terms of coordinates) to use the original footprint. All you need to do is draw, in a plan diagram, the planes of the roof. An **apex** is a highest point on the roof where planes meet. The plan diagram in _Fig 2_ shows the floorprint corners numbered C0, C1, C2 etc and the apexes numbered in sequence using A0, A1 etc. _Fig 2_ is drawn to scale based on the original base data. 

![roof plan](/img/samples/roof2.jpg)
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Fig 2

```javascript
var baseData = [-3, -2, -1, -4, 1, -4, 3, -2, 5, -2, 5, 1, 2, 1, 2, 3, -3, 3];
```
The red dash lines showing the axes.

From the diagram the roof apex data can be read off and the coordinate pairs placed in the array in sequence order. First pair is from A0, the second from A1 etc.

```javascript
var roofApexData = [0, -2, 0, -0.5, 0, 2, 4.5, -0.5];
```

This data the needs to be turned into an array, **apexes** for example, of Vector2 which will be used as the second parameter of the **roof** function.

```javascript
var apexes = [];
	
for(let i = 0; i < roofApexData.length / 2; i++) {
	apexes.push(new BABYLON.Vector2(roofApexData[2 * i], roofApexData[2 * i + 1]))
}
```
Each roof plane can be described using the corner and apex labels. The planes should be draw so that they are described with either 3 or 4 labels. Each plane is set as an array using the labels in a counter clockwise order with corner labels coming first. Remember that the corner labels are already in counter clockwise order. An array of planes is then formed containing all the plane data arrays.

```javascript
var planes = [
	["C0", "C1", "A0"],
	["C1", "C2", "A0"],
	["C2", "C3", "A0"],
	["C3", "A1", "A0"],
	["C3", "C4", "A3", "A1"],
	["C4", "C5", "A3"],
	["C5", "C6", "A1", "A3"],
	["C6", "C7", "A2", "A1"],
	["C7", "C8", "A2"],
	["C8", "C0", "A0", "A2"]
]
```

The roof function can then be applied to produce the sections or planes of the roof. 

This takes the parameters as shown

```javascript
roof(roofprint, apexes, planes, rise, height, uvbase)
```

The **rise** is the distance from the roof floor to an apex, the height is the height of the house.

The roof function creates uv values for each plane based on the size of the plane. So a plane that is twice as big as another will have double the uv values. For this to work the parameter _uvbase_ has to larger than the maximum width and height of all the planes. As a rule of thumb use a value about the width (horizontal) of the largest plane.

The roof function creates the mesh of the roof.

In the example the roof mesh is built using

```javascript
var roofSection = roof(wholeRoofprint, apexes, planes, 2, height, 5.6);
```

PG: <Playground id="#1Z71FW#42" title="Simple Roof Plan Example" description="."/>

## Design Roof In Sections

When you want different parts of the roof to have different heights then although it is possible to choose suitable apexes and planes it is much more difficult to determine the apex where a low roof meets the plane of a higher roof. For example in _Fig 3_ it is possible to calculate the x coordinate of apex A using 3D vector geometry.

![roof planes meet](/img/samples/roof3.jpg)
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Fig 3

The simplest solution however is to use values that extend the small roof into the large roof.

Following this method and using the original floor plan the plan for the lower roof section will cover the red area as in _Fig 4_

![overlap 1](/img/samples/roof4.jpg)
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Fig 4

The help prevent Z fighting the plan for the higher roof will be reduced so that parts of it will fall inside the lower roof.

The plan drawing for the main roof is now as in _Fig 5_ and for the smaller roof as in _Fig 6_

![main roof](/img/samples/roof5.jpg)
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Fig 5

![smaller roof](/img/samples/roof6.jpg)
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Fig 6

Specific corners to be used by the _roofprint_ function have to be created for the main and the small roof. The original corners are used to create the whole roofprint in order to construct the roof floor.

```javascript
var wholeRoofprint = roofprint(corners, overlap, height);
var mainRoofprint = roofprint(mainCorners, overlap, height);
var smallRoofprint = roofprint(smallCorners, overlap, height);
	
var ceiling = roofFloor(wholeRoofprint);
```
Apex arrays has to be formed for both the main and small roof

```javascript
var apexes = [];
	
for(let i = 0; i < roofApexData.length / 2; i++) {
	apexes.push(new BABYLON.Vector2(roofApexData[2 * i], roofApexData[2 * i + 1]))
}

var smallApexes = [];

for(let i = 0; i < smallRoofApexData.length / 2; i++) {
	smallApexes.push(new BABYLON.Vector2(smallRoofApexData[2 * i], smallRoofApexData[2 * i + 1]))
}
```

In the same way two plane arrays are needed, on for each roof

```javascript
var planes = [
		["C0", "C1", "A0"],
		["C1", "C2", "A0"],
		["C2", "C3", "A0"],
		["C3", "C4", "A1", "A0"],
		["C4", "C5", "A1"],
		["C5", "C0", "A0", "A1"]
	]
	
	var smallPlanes = [
		["C0", "C1", "A1", "A0"],
		["C1", "C2", "A1"],
		["C2", "C3", "A0", "A1"]
	]
```

Then ,finally, both roof sections can be created

```javascript
var roofSection = roof(mainRoofprint, apexes, planes, 2, height, 5.1);
var smallRoofSection = roof(smallRoofprint, smallApexes, smallPlanes, 2, height - 1, 5.1);
```

PG: <Playground id="#1Z71FW#43" title="Roof Added" description="Building and adding a roof"/>

WebVR is deprecated and was removed from most (if not all) modern browsers. **it is strongly recommended that projects use the [WebXR experience helper](/features/featuresDeepDive/webXR/webXRExperienceHelpers) instead of WebVR**. For more information, check out our [introduction to WebXR](/features/featuresDeepDive/webXR/introToWebXR).

We leave this information since the code, apart from the direct interface to WebVR, can be used in other projects.

A simple WebVR gamelet to show how to implement key VR features.

## The Design

![Basic WebVR](https://i.gyazo.com/dc1ad24a692ada3e5d00c206a366519c.gif)

### Overview

The scene is very simple. The pickable object is steadily rotating around you. When clicked, it'll make a spatial sound effect and your score will increase. There is a reticle in the middle of the screen that changes color when something can be picked.

This scene shows:

- Creating a [simple reticle](#reticle)
- [Dynamic GUI](#dynamic-gui)
- [VR Camera](#vr-cameras)
- [Spatial Sound](#spatial-sound)

### Reticle

There are a number of different ways to create VR reticles. An ideal reticle would have animations that would give the user feedback on their environment and the different actions they can perform. For this gamelet, we kept it simple and used a sphere mesh that changed color to indicate something pickable.

The sphere reticle starts red, and changes to green when pickable. We don't want our reticle to be pickable since we're not interacting with it directly.

```javascript
/*Sphere reticle*/
var reticle = BABYLON.MeshBuilder.CreateSphere("reticle", { segments: 10, diameter: 0.03 }, scene);
var retmat = new BABYLON.StandardMaterial("reticalmaterial", scene);
retmat.emissiveColor = BABYLON.Color3.Red();
retmat.specularColor = BABYLON.Color3.Black();
reticle.material = retmat;
reticle.isPickable = false;
reticle.position.z = 2;
```

The secret behind creating a reticle is [Raycasting](/features/featuresDeepDive/mesh/interactions/picking_collisions). A Ray is a straight line that'll tell us when it intersects with an object. We want to create a Ray from the middle of our camera facing forward, and change the color of the reticle to green when we can interact with the mesh.

We put the function in registerBeforeRender() so that it gets continually updated every frame.

```javascript
/*The function that runs to determine the behavior of the reticle.*/
function castRay() {
 var ray = camera.getForwardRay();

 var hit = scene.pickWithRay(ray);

 if (hit.pickedMesh) {
 reticle.material.emissiveColor = BABYLON.Color3.Green();
 } else {
 reticle.material.emissiveColor = BABYLON.Color3.Red();
 }
}

scene.registerBeforeRender(function () {
 castRay();
});
```

In order for the reticle to move with the VR Camera as well as the Web camera, we have to change the reticle's parent whenever we enter VR mode.

```javascript
VRHelper.onEnteringVR = function () {
 console.log(VRHelper.currentVRCamera);
 reticle.parent = VRHelper.currentVRCamera;
};
VRHelper.onExitingVR = function () {
 reticle.parent = camera;
};
```

#### Ways To Improve

You could improve this reticle a number of ways. As mentioned previously, providing better feedback to the user with interactable options is one of the key factors in making an effective reticle. Additionally, a 2D reticle that rotates with the surface of what the user is looking at gives a more concrete picture of where the user is looking in 3D space.

### Dynamic GUI

In the context of our game, our GUI consists of a Score variable that increases every time the user clicks the rotating box. To do this, we have a scoreVar object with a 'score' attribute that gets incremented with the action below. Follow these guides for more about [GUI](/features/featuresDeepDive/gui/gui) and [Actions](/features/featuresDeepDive/events/actions).

```javascript
/*Object keeping track of score. It's an object and not an int because of the available actions. */
var scoreVar = { score: 0 };

/*GUI*/
var advancedTexture = BABYLON.GUI.AdvancedDynamicTexture.CreateFullscreenUI("UI");

var scoreText = new BABYLON.GUI.TextBlock();
scoreText.text = "Score: " + scoreVar.score.toString();
scoreText.color = "black";
scoreText.fontSize = 30;
scoreText.paddingTop = 10;
scoreText.paddingLeft = 10;

advancedTexture.addControl(scoreText);

scoreText.textHorizontalAlignment = BABYLON.GUI.Control.HORIZONTAL_ALIGNMENT_LEFT;
scoreText.textVerticalAlignment = BABYLON.GUI.Control.VERTICAL_ALIGNMENT_TOP;

/*Actions that'll happen when clicking (or "picking")*/
blubox.actionManager.registerAction(new BABYLON.IncrementValueAction(BABYLON.ActionManager.OnPickTrigger, scoreVar, "score", 1));
```

### VR Cameras

Babylon.js makes it very easy to use VR camera. Our scene has two options. The default implemented is the `WebVRFreeCamera`, the documentation, including browser/device limitations and motion controls, can be found [here](/features/featuresDeepDive/cameras/webVRCamera).

```javascript
var camera = new BABYLON.WebVRFreeCamera("Camera", new BABYLON.Vector3(0, 1, 0), scene);
camera.attachControl(canvas, true);
```

Alternatively, you can include `scene.createDefaultVRExperience();` to toggle between VR capable scenes. In the playground code, comment out the lines that use the `camera` var and uncomment the lines that have `//to use with createDefaultVRExperience()`.

### Spatial Sound

Spatializing a sound in Babylon.js can be as simple as marking the BABYLON.Sound `spatialSound` attribute as 'true'. However, there are a number of other options you can specify, including linear, inverse, or exponential distance, max distance, and the panning model. 
A more in depth guide can be found [here](/features/featuresDeepDive/audio/playingSoundsMusic#creating-a-spatial-3d-sound).

Afterwards, we make sure to attach the sound to our moving box, and register the sound to play when the box is clicked.

> Note: Whenever you attach a sound to a mesh it automatically converts it into a spatial sound.

```javascript
/*Spatial Sound Effect*/
var SFX = new BABYLON.Sound("gunshot", "sounds/gunshot.wav", scene, null, { maxDistance: 50, loop: false, autoplay: false, spatialSound: true }); //no need to set spatialSound if attaching to a mesh

SFX.attachToMesh(blubox);

blubox.actionManager.registerAction(new BABYLON.PlaySoundAction(BABYLON.ActionManager.OnPickTrigger, SFX));
```

## The Finished Game

The full code, featuring the sections mentioned above and including the rest of the game scene, can be found below.

PG: <Playground id="#KJ8ZRZ#2" title="Full VR Game" description= "The game in action."/>


The workshop holds a selection of experiments and partially finished projects. They put together several aspects of Babylon.js in one place with a description of their design and construction. Some could be developed into full applications but really they are just workshop ideas which expand on the examples in the documentation.



Hello, my name is Nikos and I run a YouTube channel catering for programmers.

Have you ever wanted to build an awesome Real-Time Strategy (RTS) game using Babylon.js?
Have you ever wondered how all the units in an RTS game go about their tasks?

I invite you to come and build one and learn together with me as we build a unique RTS game called Density Wars!
The game will involve you having to strategically position the units to beat your opponents. The units can link up their firepower when closer together, but you will have to balance local fire power against the overall progression of the battle.

The RTS Game Development series consists of these episodes:

1. [Lets build an online RTS game together](https://www.youtube.com/watch?v=i7tdJpf6Pnc)
2. [The RTS game project structure](https://www.youtube.com/watch?v=nbmYIcwZEys)
3. [Rectangular Unit selection](https://www.youtube.com/watch?v=NO820DfNAew)

You will benefit greatly in this series as we learn together how to make a full RTS realtime game, including server side code.

All code is open source and contained here: https://github.com/QuantumInformation/Density-Wars
