Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/rxi/flux

A fast, lightweight tweening library for Lua
https://github.com/rxi/flux

Last synced: 6 days ago
JSON representation

A fast, lightweight tweening library for Lua

Awesome Lists containing this project

README 

        
# flux

A fast, lightweight tweening library for Lua.



## Installation

The [flux.lua](flux.lua?raw=1) file should be dropped into an existing project

and required by it.

```lua

flux = require "flux"

``` 

The `flux.update()` function should be called at the start of each frame. As

its only argument It should be given the time in seconds that has passed since

the last call.

```lua

flux.update(deltatime)

```



## Usage

Any number of numerical values in a table can be tweened simultaneously. Tweens

are started by using the `flux.to()` function. This function requires 3

arguments:

* `obj` The object which contains the variables to tween

* `time` The amount of time the tween should take to complete

* `vars` A table where the keys correspond to the keys in `obj` which should be

  tweened, and their values correspond to the destination

```lua

-- Moves the ball object to the position 200, 300 over 4 seconds

flux.to(ball, 4, { x = 200, y = 300 })

```

If you try to tween a variable which is already being tweened, the original

tween stops tweening the variable and the new tween begins from the current

value.



### Additional options

Additional options when creating a tween can be set through the use of chained

functions provided by the tween object which `flux.to()` returns.

```lua

flux.to(t, 4, { x = 10 }):ease("linear"):delay(1)

```



#### :ease(type)

The easing type which should be used by the tween; `type` should be a string

containing the name of the easing to be used. The library provides the

following easing types:



  `linear`

  `quadin`       `quadout`       `quadinout`

  `cubicin`      `cubicout`      `cubicinout`

  `quartin`      `quartout`      `quartinout`

  `quintin`      `quintout`      `quintinout`

  `expoin`       `expoout`       `expoinout`

  `sinein`       `sineout`       `sineinout`

  `circin`       `circout`       `circinout`

  `backin`       `backout`       `backinout`

  `elasticin`    `elasticout`    `elasticinout`



The default easing type is `quadout`. Examples of the different easing types

can be [found here](http://easings.net/).



#### :delay(time)

The amount of time flux should wait before starting the tween; `time` should be

a number of seconds. The default delay time is `0`.



#### :onstart(fn)

Sets the function `fn` to be called when the tween starts (once the delay has

finished). `:onstart()` can be called multiple times to add more than one

function.



#### :onupdate(fn)

Sets the function `fn` to be called each frame the tween updates a value.

`onupdate()` can be called multiple times to add more than one function.



#### :oncomplete(fn)

Sets the function `fn` to be called once the tween has finished and reached its

destination values. `oncomplete()` can be called multiple times to add more

than one function.



#### :after([obj,] time, vars)

Creates a new tween and chains it to the end of the existing tween; the chained

tween will be called after the original one has finished. Any additional

chained function used after `:after()` will effect the chained tween. There is

no limit to how many times `:after()` can be used in a chain, allowing the

creation of long tween sequences. If `obj` is not specified the `obj` argument

from the original tween is used.

```lua

-- Tweens t.x to 10 over 2 seconds, then to 20 over 1 second

flux.to(t, 2, { x = 10 }):after(t, 1, { x = 20 })

```



### Stopping a tween

If you want the ability to stop a tween before it has finished, the tween

should be assigned to a variable when it is created.

```lua

local tween = flux.to(x, 2, { y = 20 }):delay(1)

```

The tween can then be stopped at any point by calling its `:stop()` method.

```lua

tween:stop()

```

This will cause the tween to immediatly be removed from its parent group and

will leave its tweened variables at their current values. The tween's

`oncomplete()` callback is not called.



### Groups

flux provides the ability to create tween groups; these are objects

which can have tweens added to them, and who are in charge of updating and

handling their contained tweens. A group is created by calling the

`flux.group()` function.

```lua

group = flux.group()

```

Once a group is created it acts independently of the `flux` object, and must

be updated each frame using its own update method.

```lua

group:update(deltatime)

```

To add a tween to a group, the group's `to()` method should be used.

```lua

group:to(t, 3, { x = 10, y = 20 })

```

A good example of where groups are useful is for games where you may have a set

of tweens which effect objects in the game world and which you want to pause

when the game is paused.  A group's tweens can be paused by simply neglecting

to call its `update()` method; when a group is destroyed its tweens are also

destroyed.



## License

This library is free software; you can redistribute it and/or modify it under

the terms of the MIT license. See [LICENSE](LICENSE) for details.