5.2 KiB
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 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
-
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
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. |
{ 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. |
{
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
--- 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()
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.