# Animation

Animating values and objects using tweens

[Reference](index.md)

<a id="section-Guides"></a>

## Guides

<a id="Animating-Values"></a>

### Animating Values

A tween changes a value over time. Use one to slide a menu into place, fade a
label, or move an object to a destination.

## Starting a tween

Keep the values in a table or object, then give the tween its destination and
duration. An easing curve changes how it speeds up or slows down.

Start a tween once, such as when a button is pressed. Starting it again in
`draw()` would reset it every frame. Keep the returned tween if you want to
pause or cancel it later.

Use a completion callback to run code when it finishes, or a sequence to run
several tweens in order. See [Tweening](#Animating-with-Tweens) for examples and commands.

<a id="section-Tweening"></a>

## Tweening

<a id="Animating-with-Tweens"></a>

### Animating with Tweens

A tween changes values over time. Use it to move an object, fade a color, or animate a menu.

**Tweening a value**

```lua
function setup()
   p = vec2(0, HEIGHT/2)
   tween(p):to{x = WIDTH}:time(5)
end

function draw()
   background(40, 40, 50)

   strokeWidth(5)
   ellipse(p, 50)
end
```

<a id="tween"></a>

### tween

```lua
tween
```

tween a value or values to a given target

<a id="tween-2"></a>

### tween(target)

```lua
tween(target)
```

Create a tween for a table or object. Call `to{}` with the values you want to reach, then chain commands to set the duration, easing, or looping.

Each `to{}` adds a new part to the animation. Keep the tween to pause, resume, restart, or cancel it.

tween a value or values to a given target

#### Parameters

- **target** (table | usertype): The target to tween

#### Returns

- **tween**: 

<a id="tween.duration"></a>

### tween.duration

```lua
tween.duration
```

The total duration of the tween in seconds

get the duration of this tween

<a id="tween.progress"></a>

### tween.progress

```lua
tween.progress
```

The current progress of the tween in seconds

get the progress of this tween

<a id="tween.target"></a>

### tween.target

```lua
tween.target
```

The target object being tweened

get the target object of this tween

<a id="tween:to"></a>

### tween:to(keyValuePairs)

```lua
tween:to(keyValuePairs)
```

Creates a new tweening segement, each key is animated to the corresponding value

Multiple tweening segments can be created one after another, but the same set of keys and values should be used for all of them

add a tweening segment with target values

#### Parameters

- **keyValuePairs** (table): The key value pairs to be tweened

<a id="tween:time"></a>

### tween:time(duration)

```lua
tween:time(duration)
```

Sets The duration of the current tweening segment (created via `to{}`)

set the duration of the current tween segment

#### Parameters

- **duration** (number): The amount of time to take in seconds

<a id="tween:ease"></a>

### tween:ease(easeType)

```lua
tween:ease(easeType)
```

Sets the easing type for the current tweening segment (created via `to{}`)

set the easing function for the current tween segment

#### Parameters

- **easeType** (constant): The easing function to use

<a id="tween:loop"></a>

### tween:loop(count)

```lua
tween:loop(count)
```

Sets the loop count for the current tweening segment (created via `to{}`). Using nil for the count will result in an infinite number of loops

set the loop count for the current tween segment

#### Parameters

- **count** (integer): The number of times to loop

<a id="tween:pingpong"></a>

### tween:pingpong(count)

```lua
tween:pingpong(count)
```

Sets the current tweening segment (created via `to{}`) to ping-pong. Using nil for the count will result in an infinite number of ping-pongs

set the current tween segment to ping-pong

#### Parameters

- **count** (integer): The number of times to ping-pong

<a id="tween:relative"></a>

### tween:relative()

```lua
tween:relative()
```

Sets the current tweening segment (created via `to{}`) to be relative

Relative tweens will apply values additively from their initial state

set the current tween segment to use relative values

<a id="tween:unscaled"></a>

### tween:unscaled()

```lua
tween:unscaled()
```

Sets the current tweening segment (created via `to{}`) to used unscaled time

Unscaled tweens will not be effected by `time.scale`

set the current tween segment to use unscaled time

<a id="tween:onStep"></a>

### tween:onStep(callback)

```lua
tween:onStep(callback)
```

Sets a callback for each time the tween is stepped (advanced once per frame)

set a callback for each tween step

#### Parameters

- **callback** (function): The callback function

<a id="tween:onSeek"></a>

### tween:onSeek(callback)

```lua
tween:onSeek(callback)
```

Sets a callback for each time the tween seeks

set a callback for each tween seek

#### Parameters

- **callback** (function): The callback function

<a id="tween:onComplete"></a>

### tween:onComplete(callback)

```lua
tween:onComplete(callback)
```

Sets a callback for each time the tween completes

set a callback for when the tween completes

#### Parameters

- **callback** (function): The callback function

<a id="tween:seek"></a>

### tween:seek(percent)

```lua
tween:seek(percent)
```

Seeks the tween to a specific normalized time (percentage of duration)

seek the tween to a normalized time

#### Parameters

- **percent** (number): The normalized time in the tween to seek to

<a id="tween:pause"></a>

### tween:pause()

```lua
tween:pause()
```

Pauses the tween

pause the tween

<a id="tween:play"></a>

### tween:play()

```lua
tween:play()
```

Plays/resumes the tween

play or resume the tween

<a id="tween:restart"></a>

### tween:restart()

```lua
tween:restart()
```

Restarts the tween from the beginning

restart the tween from the beginning

<a id="tween:cancel"></a>

### tween:cancel()

```lua
tween:cancel()
```

Cancels and destroys the tween (this still counts as the tween completing)

cancel and destroy the tween

<a id="tween:dontDestroy"></a>

### tween:dontDestroy()

```lua
tween:dontDestroy()
```

Prevent the tween from being automatically destroyed when complete

This is useful if you plan to reuse the tween using `restart()`

prevent the tween from being destroyed when complete

<a id="Easing-Functions"></a>

### Easing Functions

Here is a list of all easing functions

#### Easing Functions

| Name |
| --- |
| backIn |
| backOut |
| backInOut |
| bounceIn |
| bounceOut |
| bounceInOut |
| circularIn |
| circularOut |
| circularInOut |
| cubicIn |
| cubicOut |
| cubicInOut |
| quarticIn |
| quarticOut |
| quarticInOut |
| quinticIn |
| quinticOut |
| quinticInOut |
| sinusoidalIn |
| sinusoidalOut |
| sinusoidalInOut |
| elasticIn |
| elasticOut |
| elasticInOut |
| punch |