
## 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, which is floating point number, and should also loop. It is critical to declare the type for the animation because the animation has no concept of what it is animating. In this case, the animation is simply moving the box's position along the X axis. While the animation will know its target - the box - it has no understanding of what it means to animate its position along the X axis. To combat this, we need to define the type for the animation as a floating point animation with `BABYLON.ANIMATION.ANIMATIONTYPE_FLOAT` and define the property which will accept the input as `position.x`. With these definitions, the animation has a roadmap of how to apply its keyframe data to the target resulting in a very flexible and powerful system that can animate almost anything. In code, this declaration looks like

```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."/>

## The Animation Curve Editor (ACE)

Now that you're starting to understand the basics of animations in Babylon and how to create them, you'll also want to consider taking a look at the Animation Curve Editor (ACE). This super easy-to-use tool allows you to create full animations in a matter of seconds without writing any code!

[Check it out!](/toolsAndResources/inspector/animationCurveEditor)

<img src="/img/tools/ACE/overview.jpg" title="Babylon.js Animation Curve Editor"/>



# 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 `light.intensity`.

- _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.
  BABYLON.Animation.ANIMATIONLOOPMODE_RELATIVE_FROM_CURRENT - Relative loop mode (add to current value of animated object, unlike ANIMATIONLOOPMODE_RELATIVE)
  BABYLON.Animation.ANIMATIONLOOPMODE_YOYO - The animation will reverse its direction when it reaches the end instead of restarting from the beginning

## Set Key Frames

The key frames of an animation are held in an array of objects, each containing the following two properties:

- _frame_ - the frame number
- _value_ - for the property being changed

This array will contain one object for each key frame and can contain as many key frames as needed for the desired animation.

```javascript
const myKeys = [
  {
    frame: 0,
    value: 0.5,
  },
  {
    frame: 60,
    value: 1.0,
  },
];
```

Once the key frames array is constructed, in this case an array named _myKeys_, it is added to the animation by setting the keys.

```javascript
myAnim.setKeys(myKeys);
```

## Beginning The Animation

There are several ways to manage the play state of animations. One of the simplest is to add an animation to the _animations_ array property of an object. Objects like Mesh, Material, Light, or Camera have an _animations_ array property defined by default which holds animations which target that specific object.

```javascript
myMaterial.animations.push(myAnim);
```

Additionally, animations can be added to any object that the engine can reach, even if it does not already have an _animations_ array property. Due to the malleable nature of Javascript, simply declaring a new array property for an object will enable us to store animations on target objects. For example, if we want to target the weight property of an animation with another animation, we can add an _animations_ array property to the animation by declaring it.

```javascript
myAnimation.animations = [];
myAnimation.animations.push(weightAnimation);
```

Remember, above we said that anything that the engine can reach can be animated with our animation system. This also applies to content outside of the canvas. For example, since we can reach any DOM object with Javascript, we can apply an animation to it. If we wanted to, we could use an animation to drive the border-radius of a `<div>` object.

### beginAnimation

Now that we have pushed an animation to a target object, starting the animation is a simple case of telling the scene to begin the animations stored with the target object. Note that when `beginAnimation` is called, every animation stored in the `target.animations` array will start.

```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

If a looping animation is desired, set the fourth parameter to true.

```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"/>

There are a number of further optional parameters that you can find in the _scene_ API.

### beginDirectAnimation

If it is preferable to not store animations with a target object, one or more animations can be applied 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 the animation

Be aware that animations applied with `scene.beginDirectAnimation` do not belong to any object or the scene so the scene is not aware of these animations and they do not register in `scene.animations`. However, this method is extremely useful for applying a one-time animation to an object or for animating an object that does not have an _animations_ array property if it is desirable not to alter the target object. Further optional parameters are available and can be found in the _scene_ API. If `scene.beginDirectAnimation` is the preferable method, but additionally having a reference to the animation that can be used in the future is required, an _Animatable_ is exactly what is needed.

<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 `scene.beginAnimation` and `scene.beginDirectAnimation` return an _Animatable_ object that can be referenced when needed to change the state of the animation. Simply capture the return from one of the methods above to store the reference.

```javascript
const myAnimatable = myscene.beginAnimation(target, from, to, true);
```

Once the animatable is stored, any of the following methods can be called to change the state of the animation as needed.

- _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"/>



## An Introduction to Animation

However animation is achieved it has to take into account the action wanted, timing, the number of frames needed to produce the required fluidity and key points within the sequence. This introduction should help to understand how Babylon.js goes about animations and how they are achieved.

Animations are produced by a sequence of images, _frames_, which are displayed one after the other. This sequence of _frames_ can be individual drawings or for, stop motion animation, photographs of models that are moved slightly frame by frame

![Horse - Frames](/img/features/animation/horse_frames.jpg)

<img src="https://upload.wikimedia.org/wikipedia/commons/9/99/Horse_gif_slow.gif" title="Horse Animation" caption="from Wikimedia Commons (https://commons.wikimedia.org/wiki/File:Horse_gif_slow.gif)"/>

During the design stage the creator will need to consider how long a sequence should take and how smooth it needs to be. The smoother the movement the more frames are required. Once the number of frames is known the animation frames per second can be inferred. Also knowing the object's start position and end position and how many frames are required will determine the object's movement per frame.

In Babylon.js, as in stop motion animation, individual objects have to be moved one by. Whereas we might talk about the overall finished piece as an animation in Babylon.js an _Animation_ is also a specific object that details a transformation, timing and looping that can then be applied to any mesh, camera or light. To this data is added values at key frames from which Babylon.js calculates the transformations to take place for the in between frames.

## Terminology Used in the Animation Documentation

The following terms will have the given meaning within the How_To about animating.

- _Performer_ an item that can be animated, could be a mesh, a light or camera for example. Performers can, however, be more than just a node in the scene. The performer can also be a value like a color property on a shader, the intensity property of a light, or even the weight property on another animation.

- _Frame_ - an animation frame not a rendered frame of the scene.

- _Animation_ - similar to a play or film script but applies to just one property of a performer. It consists of

  - the property to be changed, for example, position, intensity or rotation
  - the rate of change of the property in frames per second,
  - the type of the property being changed, for example vector, floating point number or matrix,
  - looping conditions,
  - key values of the property at key frames.

- _Scripted Performer_ - The performer plus all the animations to be undertaken by the performer.

- _Performance_ - The scripted performer and the actions done by the performer following the script. In Babylon.js this is the _animatable_ object.

- _Clip_ - The viewable result of a performance. In practice there are two types of _clip_ a
  _game clip_ and a _movie clip_. In a _movie clip_ the user has no control over the camera and the _clip_ is viewed according to the _animation_ of the camera as set by the creator of the _clip_. In a _game clip_ the user is able to move the camera as determined by the type of camera used in the scene. Unless it is likely to cause any confusion just the term _clip_ will be used throughout the documentation when writing about animating.

- _Cartoon_ - A series of _clips_ played at timed intervals.
