
# The Animation Method

## Creating the animation
```javascript
const myAnim = new BABYLON.Animation(name, property, frames per second, property type, loop mode)
```
-   _name_ - _string_, name of animation

-   _property_ - _string_, a property of the object that the animation will be applied to. For example a Vector3 property such as position or a floating number property such as position.x

-   _frames per second_ - _number_, the number of animation frames per second (independent of the scene rendering frames per second)

-   _property type_ - _number_, the property type of the _property_ parameter. This can be set using the following constants

    BABYLON.Animation.ANIMATIONTYPE_COLOR3  
    BABYLON.Animation.ANIMATIONTYPE_FLOAT  
    BABYLON.Animation.ANIMATIONTYPE_MATRIX  
    BABYLON.Animation.ANIMATIONTYPE_QUATERNION  
    BABYLON.Animation.ANIMATIONTYPE_VECTOR2  
    BABYLON.Animation.ANIMATIONTYPE_VECTOR3

-   _loop mode_ - _number optional_, This can be set using the following Parameters

    BABYLON.Animation.ANIMATIONLOOPMODE_CYCLE - Restart the animation from initial value  
    BABYLON.Animation.ANIMATIONLOOPMODE_CONSTANT - Pause the animation at the final value  
    BABYLON.Animation.ANIMATIONLOOPMODE_RELATIVE - Repeat the animation incrementing using key value gradients. In this way, for example, a \_clip* showing a character's legs in a walking motion can be looped to show the character progressing across the scene.

## Set Key Frames
This is an array, *myKeys* of objects. Each object having the two properties 

- _frame_ - the frame number
- _value_ - for the property being changed

Once constructed this is added to the animation

```javascript
myAnim.setKeys(myKeys);
```

## Beginning The Animation

To run the animation it is pushed onto the *animations* array property of the mesh

```javascript
mesh.animations.push(myAnim)
```

and started with these required parameters
```javascript
scene.beginAnimation(target, from, to);
```

-   _target_ - _BabylonJS Object_, theBabylon.js object to be animated
-   _from_ - _number_, the frame at which to start the animation
-   _to_ - _number_, the frame at which to end the animation


When you want the animation to loop you and true as the fourth parameter
```javascript
scene.beginAnimation(target, from, to, true)
```

<Playground id="#7V0Y1I" title="Basic Sliding Box Animation" description="An example of basic animation by sliding a box." image="/img/playgroundsAndNMEs/divingDeeperAnimationDesign1.jpg"/>

The are a number of further optional parameters than you can find in the *scene* API

You can apply several animations to a target using
```javascript
scene.beginDirectAnimation(target, animations, from, to, loop)
```

-   _target_ - _BabylonJS Object_, theBabylon.js object to be animated

-   _animations_ - _array_, of all the animations to apply to the target

-   _from_ - _number_, the frame at which to start the animation

-   _to_ - _number_, the frame at which to end the animation

-   _loop_ - _boolean_, optional, default *false*, when *true* repeats thee animation

Further optional parameters are available and can be found at the *scene* API

<Playground id="#7V0Y1I#1" title="Sliding Box Direct Animation" description="An example of sliding a box with direct animation." image="/img/playgroundsAndNMEs/divingDeeperAnimationDesign1.jpg" isMain={true} category="Animation"/> 

## Animatable

Both methods of starting an animation return an *Animatable* object 

```javascript
const myAnimatable = myscene.beginAnimation(target, from, to, true)
```

which supports the following methods

- _pause()_
- _restart()_
- _stop()_
- _reset()_

<Playground id="#7V0Y1I#2" title="Box animation stop after 5 secs" description="An example of stopping an animation after specific amount of time." image="/img/playgroundsAndNMEs/divingDeeperAnimationDesign1.jpg" isMain={true} category="Animation"/>  



One straight forward method of combining a number of clips to form a cartoon is to give start times to each animation clip.

## Design

### Overview

The camera shows a building with a door. The camera moves closer to the door and stops. The door swings open and the camera enters the room. As the camera enters the room
lights come on in the room. The door closes and the camera sweeps around the room.

Since the aim is to show how the movie clip is made the room and door will be simply made with meshes with no textures.

### Performers

Camera - Universal  
Door - Hinged on right hand side, opening inwards  
Spot Lights - with spheres to show position

### Sequence Timetable

![Time Table](/img/how_to/Animations/seq1.jpg)

For each performer you create an animation with key points for each timed event.

### Animations

_For the Camera_  
Moving the camera changes the position (a vector3) of the camera. Sweeping the camera around is a rotation around the y axis (a float).

Since an animation can only change one property two animations are needed for the camera.

Moving the camera the key points will be at time 0 the camera will start away from the building and move towards and down until it is just outside the door at time 3 seconds.  
The camera will hold its position for 2 seconds as the door opens then at time 5 seconds will move forward into the room at an angle away from the door, stopping at time 8 seconds.

There will be no rotation of the camera for 9 seconds then camera will take until time 14 seconds to rotate 180 degrees to face the door.

Key values for the camera will be its positions at frames 0, 3, 5 and 8 seconds and its rotation at 0, 9 and 14 seconds.

```javascript
//for camera move forward
var movein = new BABYLON.Animation(
  "movein",
  "position",
  frameRate,
  BABYLON.Animation.ANIMATIONTYPE_VECTOR3,
  BABYLON.Animation.ANIMATIONLOOPMODE_CONSTANT
);

var movein_keys = [];

movein_keys.push({
  frame: 0,
  value: new BABYLON.Vector3(0, 5, -30)
});

movein_keys.push({
  frame: 3 * frameRate,
  value: new BABYLON.Vector3(0, 2, -10)
});

movein_keys.push({
  frame: 5 * frameRate,
  value: new BABYLON.Vector3(0, 2, -10)
});

movein_keys.push({
  frame: 8 * frameRate,
  value: new BABYLON.Vector3(-2, 2, 3)
});

movein.setKeys(movein_keys);

//for camera to sweep round
var rotate = new BABYLON.Animation(
  "rotate",
  "rotation.y",
  frameRate,
  BABYLON.Animation.ANIMATIONTYPE_FLOAT,
  BABYLON.Animation.ANIMATIONLOOPMODE_CONSTANT
);

var rotate_keys = [];

rotate_keys.push({
  frame: 0,
  value: 0
});

rotate_keys.push({
  frame: 9 * frameRate,
  value: 0
});

rotate_keys.push({
  frame: 14 * frameRate,
  value: Math.PI
});

rotate.setKeys(rotate_keys);
```

_For the door_  
The door will sweep around a hinge about the y axis a floatin point rotation. The opening and closing rotations will each take 2 seconds.

Key points will be a times 0, 3, 5, and 13 and 15 seconds.

Key values for the sweep will be its rotation about the y axis at frames.

```javascript
//for door to open and close
var sweep = new BABYLON.Animation(
  "sweep",
  "rotation.y",
  frameRate,
  BABYLON.Animation.ANIMATIONTYPE_FLOAT,
  BABYLON.Animation.ANIMATIONLOOPMODE_CONSTANT
);

var sweep_keys = [];

sweep_keys.push({
  frame: 0,
  value: 0
});

sweep_keys.push({
  frame: 3 * frameRate,
  value: 0
});

sweep_keys.push({
  frame: 5 * frameRate,
  value: Math.PI / 3
});

sweep_keys.push({
  frame: 13 * frameRate,
  value: Math.PI / 3
});

sweep_keys.push({
  frame: 15 * frameRate,
  value: 0
});

sweep.setKeys(sweep_keys);
```

_For Lights_
The lights will vary in intensity (float). These will be an array of spot lights.

Key points for lights are remaining off for 7 seconds, coming to full intensity at 10 seconds which stays until going off at 14 seconds.

```javascript
//for light to brighten and dim
var lightDimmer = new BABYLON.Animation(
  "dimmer",
  "intensity",
  frameRate,
  BABYLON.Animation.ANIMATIONTYPE_FLOAT,
  BABYLON.Animation.ANIMATIONLOOPMODE_CONSTANT
);

var light_keys = [];

light_keys.push({
  frame: 0,
  value: 0
});

light_keys.push({
  frame: 7 * frameRate,
  value: 0
});

light_keys.push({
  frame: 10 * frameRate,
  value: 1
});

light_keys.push({
  frame: 14 * frameRate,
  value: 1
});

light_keys.push({
  frame: 15 * frameRate,
  value: 0
});

lightDimmer.setKeys(light_keys);
```

## Cartoon

Now just run all the clips simulaneously

```javascript
scene.beginDirectAnimation(camera, [movein, rotate], 0, 25 * frameRate, false);
scene.beginDirectAnimation(hinge, [sweep], 0, 25 * frameRate, false);
scene.beginDirectAnimation(
  spotLights[0],
  [lightDimmer],
  0,
  25 * frameRate,
  false
);
scene.beginDirectAnimation(
  spotLights[1],
  [lightDimmer.clone()],
  0,
  25 * frameRate,
  false
);
```

<Playground id="#2L26P1#8" title="Finished Animation Sequence Example" description="An example of sequencing animations one after another." image="/img/playgroundsAndNMEs/divingDeeperAnimationSequence.jpg"/>


## Designing a Clip

The first step is to decide what you want to see in a _clip_, that is what is the _performance_ to be. This gives the performer and its animation.

In this _game clip_ a box, the _performer_, is to slide between two places once every second. The box will be able to be viewed from any angle.

The first stage design is to sketch what is needed at key time points, a little like an animated gif design.

![key frames](/img/features/animation/ani1.jpg)

After one second the box should be in its new position and one second later in its start position. This sequence is then continually repeated.

In Babylon.js the _Animation_ is changing the position of the box along the x axis and its x position is a floating point number and

the _animation_ should loop. In code the animation which slides an item in the x direction becomes

```javascript
const frameRate = 10;

const xSlide = new BABYLON.Animation("xSlide", "position.x", frameRate, BABYLON.Animation.ANIMATIONTYPE_FLOAT, BABYLON.Animation.ANIMATIONLOOPMODE_CYCLE);
```

The key frames are at 0, 1 and 2 seconds. To find the frame number after t seconds multiply the time by the frame rate, i.e. t x frameRate.  
In this case the key frames are at frame numbers, 0, 1 x frameRate and 2 x frame Rate.

Starting the box at x = 2 and sliding it to x = -2, gives the x positional values of the box after 0, 1 and 2 seconds as 2, -2 and 2 respectively.

The key frames are set into an array of JavaScript objects with properties for frame (number) and value and added to the animation, as in

```javascript
const keyFrames = [];

keyFrames.push({
    frame: 0,
    value: 2,
});

keyFrames.push({
    frame: frameRate,
    value: -2,
});

keyFrames.push({
    frame: 2 * frameRate,
    value: 2,
});

xSlide.setKeys(keyFrames);
```

The animation is now fully made and can be applied to the box 

```javascript
box.animations.push(xSlide);
```
The _performance_ (*Animatable*) is started with

```javascript
scene.beginAnimation(box, 0, 2 * frameRate, true);
```

You can see the result here  
<Playground id="#7V0Y1I" title="Basic Sliding Box Animation" description="An example of basic animation by sliding a box." image="/img/playgroundsAndNMEs/divingDeeperAnimationDesign1.jpg" isMain={true} category="Animation"/>

## Reversing an Animation

Fun tip, the second and third arguments for the beginAnimation method are a starting frame and ending frame from your keyFrames list. If you reverse those two values, the animation will play in reverse!

```javascript
const startFrame = 0;
const endFrame = 10;
const frameRate = 10;

const xSlide = new BABYLON.Animation("xSlide", "position.x", frameRate, BABYLON.Animation.ANIMATIONTYPE_FLOAT, BABYLON.Animation.ANIMATIONLOOPMODE_CYCLE);

const keyFrames = []; 

keyFrames.push({
    frame: startFrame,
    value: 2
});

keyFrames.push({
    frame: endFrame,
    value: -2
});


xSlide.setKeys(keyFrames);

box.animations.push(xSlide);

//backwards animation
scene.beginAnimation(box, endFrame, startFrame, false);
```

Check it out here: 
<Playground id="#7V0Y1I#940" title="Playing an Animation in Reverse" description="An example of playing an animation forwards and backwards."/>
