167 lines
5.2 KiB
Markdown
167 lines
5.2 KiB
Markdown
|
|
# Tween
|
|
|
|
The tween object is a table that contain informations and callbacks about an interpolation animation that can be started or stopped with the tween itself.
|
|
|
|
BeTweenApi.tween(interpolation: function, movement: Movement, time: float, loop: bool, callbacks: TweenEvents) : Tween
|
|
|
|
This method will create a new Tween object.
|
|
|
|
- *interpolation* is the interpolation function to use, see [BeTweenApi.interpolation](interpolation.md) for functions to use.
|
|
You can define a custom function here too, make sure it ask for 3 argouments.
|
|
|
|
- *movement* movement data from the initial position to the end, see [Movement](#Movement)
|
|
|
|
- *time* is the time in seconds of how much this tween must run.
|
|
|
|
- *loop* set if the tween should loop his interpolation when he finish it, if is true the tween will loop forever, if is a number the tween will loop for the specified amount.
|
|
|
|
- *callbacks* contain all functions to execute on specific events of the tween, see [TweenEvents](#TweenEvents)
|
|
|
|
|
|
# Movement
|
|
|
|
This data contain initial and final position of the interpolation, every property with a default value does not require to be set.
|
|
|
|
| Property | Default | Description |
|
|
| -------- | ----------- | ------- |
|
|
| start: number | | is the initial position of the interpolation. |
|
|
| finish: number | | is the final position of the interpolation. |
|
|
| mirror: boolean | false | if enabled will make the interpolation move twince faster and use half of the time to repeat the animation in reverse. |
|
|
|
|
|
|
```lua
|
|
{ start = 0, finish = 64 } --- from 0 to 64 in time.
|
|
{ start = 0, finish = 64, mirror = true } --- same as before but also repeat in reverse.
|
|
{ 0, 64 } --- you can write it like this too.
|
|
{ 0, 64, true } --- same as second line.
|
|
```
|
|
|
|
|
|
# TweenEvents
|
|
|
|
These are all functions called on specific events, you give this table to a tween to make it execute your own code.
|
|
|
|
Each function receive the tween itself as first argoument, you can call any tween method from there.
|
|
|
|
| Callback | Description |
|
|
| - | - |
|
|
| on_start(tween: Tween) | Called when the Tween:start() is executed and the Tween will soon start to run his steps. |
|
|
| on_end(tween: Tween) | Called when the Tween:stop() is executed or when the tween has finished to run. |
|
|
| on_loop(tween: Tween) | Called every time the tween is looping, only called if loop is used.. |
|
|
| on_step(tween: Tween, value: number) | Called each step of the interpolation in the defined time, value is the result value. |
|
|
|
|
```lua
|
|
{
|
|
on_start = function (tween)
|
|
minetest.log("Hello Tween!")
|
|
end,
|
|
on_end = function (tween)
|
|
minetest.log("Goodbye Tween!")
|
|
end,
|
|
on_loop = function (tween)
|
|
minetest.log("Boom, 360 loop!")
|
|
end,
|
|
on_step = function (tween, value)
|
|
--- do something with value.
|
|
end,
|
|
}
|
|
```
|
|
|
|
______
|
|
|
|
|
|
# Functions and methods
|
|
|
|
|
|
Tween:start()
|
|
|
|
This method will start the tween by adding it in the *active_tweens* list, the global step will handle the process of time in the tween.
|
|
|
|
To make sure the Tween use the 100% of the assigned interpolation function it will make sure to process step 0.0 and 1.0 (the absolute end and start of the animation).
|
|
|
|
Everything in between of the interpolation time is handled by the server time using global steps.
|
|
|
|
After adding in the list the Tween is seen as "running", if the Tween is started while is already running a message log will be printed instead.
|
|
|
|
After adding to the list the **Tween:on_start()** callback is called.
|
|
|
|
Tween:stop(reset: bool = false)
|
|
|
|
This method will stop the tween by removing it from the *active_tweens* list.
|
|
|
|
If *reset* is true the current position in time of the Tween is resetted to 0, if is false the Tween is just paused.
|
|
|
|
Tween:is_running(): bool
|
|
|
|
Check if the current Tween is running inside the list, return true if it is or false if not.
|
|
|
|
Tween:index(): int | nil
|
|
|
|
Get the index position of the Tween inside the list, if the Tween isn't running *nil* is returned.
|
|
|
|
______
|
|
|
|
|
|
# Examples
|
|
|
|
|
|
```lua
|
|
|
|
--- store the tween in a variable.
|
|
local tween = InterpolationApi.tween(
|
|
InterpolationApi.interpolation.quadratic_in,
|
|
{ 0, 64, false },
|
|
8.0, false,
|
|
{
|
|
on_start = function (tween)
|
|
minetest.log("Interpolation start!")
|
|
end,
|
|
on_step = function (tween, value)
|
|
minetest.log(tostring(value))
|
|
end
|
|
}
|
|
)
|
|
|
|
--- start the tween.
|
|
tween:start()
|
|
```
|
|
|
|
|
|
```lua
|
|
InterpolationApi.tween(
|
|
InterpolationApi.interpolation.linear, --- linear movement
|
|
{ start = 0, finish = 64 }, --- from 0 to 64, don't mirror
|
|
4.0, --- in 4 seconds
|
|
true, --- repeat after the time
|
|
{
|
|
--- execute this method each step in time.
|
|
on_step = function (tween, value)
|
|
local item = player:hud_get(icon)
|
|
player:hud_change(icon, "offset", { x = value, y = 32 })
|
|
end
|
|
}
|
|
):start() --- you can also start the tween without creating a variable.
|
|
```
|
|
|
|
|
|
______
|
|
|
|
|
|
# Extra
|
|
|
|
Extra informations about the Tween.
|
|
|
|
>## Tween loop
|
|
>
|
|
>The tween execute his loop using the server global steps, so his execution is synced to each player, but that's mean it will slow down when the server is lagging.
|
|
|
|
>## Tween list
|
|
>
|
|
>When a tween is running, by executing his :start() method) will insert itself in the *active_tweens* list inside the api.
|
|
>
|
|
>When the tween is stopped, paused, or has finished his interpolation job he will remove itself from the list.
|
|
>
|
|
>Tween in the list are only tween that **are** running.
|
|
|