GianptDev
/
between-api-minetest
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

first commit

master
GianptDev 2022-08-14 10:40:14 +02:00
commit b0970911a5
11 changed files with 652 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

21
LICENSE Normal file
View File

@ -0,0 +1,21 @@
MIT License
Copyright (c) 2022 _gianpy_
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.

24
docs/debug.md Normal file
View File

@ -0,0 +1,24 @@
# Debug tools
This is a table that contain debug visual stuff.
| Property | Description |
| -------- | ----------- |
| player_huds | List of all players that uses debug visuals, each item uses as a key the player name and as a value the title id of the hud and the tweens used for debug.
## debug:show(player_name: string)
Display all defined interpolations functions on screen with some animated images and the interpolation name.
*player_name* is the player wich will see the hud.
If the player has already the hud visible a log message will be printed instead.
## debug:hid(player_name: string)
Do the opposite of **debug:show**, will hide the hud visual.
*player_name* is the player wich the hud will be removed.
If the player has already the hud disabled a log message will be printed instead.

23
docs/interpolation.md Normal file
View File

@ -0,0 +1,23 @@
# Interpolation Functions
**BeTweenApi.interpolation** is a table that contain interpolation functions, here are listed all of the and what their porpuse is for.
| Function | Description |
| -------- | ----------- |
| linear | straight increment from x to y in time. |
| ease_in | straight increment from x to y in time. |
| ease_out | movement increment slower from x to y in time. |
| ease_in_out | movement is faster between x to y but slow down on begin and end in time. |
| spike_linear | movement moves like linear, but reach his destination in half the time, the rest of the time is used to come back to the starting point. |
| spike_ease_in | movement moves like ease in, but reach his destination in half the time, the rest of the time is used to come back to the starting point. |
| spike_ease_out | movement moves like ease out, but reach his destination in half the time, the rest of the time is used to come back to the starting point. |
| spike_ease_in_out | movement moves like ease in out, but reach his destination in half the time, the rest of the time is used to come back to the starting point. |
______
Usage example:
BeTweenApi.interpolation.linear(0, 4, 0.5) -- 2
BeTweenApi.interpolation.ease_in(0, 8, 0.5) -- 2
BeTweenApi.interpolation.ease_out(0, 8, 0.5) -- 4.5

24
docs/readme.md Normal file
View File

@ -0,0 +1,24 @@
# BeTween Api
This api implements a simple table called *BeTweenApi*, this table contains everything implemented in this library.
| Property | Description |
| ------------- | ----------- |
| *active_tweens* | This is a list of all running tweens, when a tween has started is inserted in this list until is stopped. |
| [interpolation](interpolation.md) | This is a table that contain a set of interpolation functions that can be used by tweens or directly. |
| [debug](debug.md) | This is a table that contain debug related stuff.
## Objects
| Name | Description |
| ---- | ----------- |
| [Tween](tween.md) | This is the tween itself, contain all the stuff you need for time interpolation. |
## Commands
| Name | Description |
| ---- | ----------- |
| /between | Show a debug hud to display all defined tween animations, require no privileges and the hud is displayed only from the calling player. |

82
docs/tween.md Normal file
View File

@ -0,0 +1,82 @@
# 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.
| Property | Description |
| ------------- | ----------- |
| *method*: function | The method the Tween is using. |
| *value_start*: number | The start value of the interpolation. |
| *value_end*: number | The final value of the interpolation. |
| *time_end*: float | The time of the interpolation in seconds. |
| *timer*: float | Current time of the interpolation. |
| *loop*: bool | If the Tween should loop.
BeTweenApi.tween(method: function, from: number, to: number, time: float, loop: bool, callbacks: table)
This method will create a new Tween object.
- *method* 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.
- *from* is the initial value of the interpolation.
- *to* is the final value of the interpolation.
- *time* is the time in seconds of how much this tween must run.
- *loop* set if the Tween must automatically restart when it finish it, this will make the Tween run forever until manually stopped.
- *callbacks* is a list of methods called on Tween events, each callback give the tween itself.
| 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 and the Tween has stopped to run. |
| on_step(value: number, tween: Tween) | Called each step of the interpolation in the defined time, value is the result value. |
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.
______
Usage example:
local tween = InterpolationApi.tween(
InterpolationApi.interpolation.linear, -- linear movement
0, -- from 0
64, -- to 64
4.0, -- in 4 seconds
true, -- repeat after the time
{
on_step = function (step, tween)
local item = player:hud_get(icon)
player:hud_change(icon, "offset", { x = step, y = 32 })
end
}
)
tween:start() -- make sure to start the tween.

376
init.lua Normal file
View File

@ -0,0 +1,376 @@
-- BeTween Api 1.0
-- made by GianptDev (_gianpy_)
-- this table contain interpolation methods and the logic to make tween works.
BeTweenApi = {
-- This is a list of all active tween that are processed in the server.
active_tweens = {},
-- contain debug related content.
debug = {
-- list of all players that are using the debug hud.
player_huds = {},
-- show the debug hud to this specific player.
show_functions = function (_, player_name)
if (_.player_huds[player_name] ~= nil) then
minetest.log("action", string.format("BeTween: The player '%s' has already the debug hud enabled.", player_name))
return
end
local player = minetest.get_player_by_name(player_name)
local index = 0
local start, finish = 32, 400
local scale = { x = 2, y = 2}
local visual = {
tweens = {},
}
_.player_huds[player_name] = visual
visual.title = player:hud_add({
hud_elem_type = "text",
text = "BeTween Api Debug : interpolation list",
position = { x = 0, y = 0 },
offset = { x = start, y = 32 },
alignment = { x = 1, y = 0 },
number = 0xFFFFFF,
style = 1,
})
for _, interpolation in pairs(BeTweenApi.interpolation) do
local y = 64 + (24 * index)
local start_icon = player:hud_add({
hud_elem_type = "image",
text = "heart.png^[colorize:#0000FF",
scale = scale,
offset = { x = start, y = y },
position = { x = 0, y = 0 },
alignment = { x = 0, y = 0 },
})
local stop_icon = player:hud_add({
hud_elem_type = "image",
text = "heart.png^[colorize:#0000FF",
scale = scale,
offset = { x = finish, y = y },
position = { x = 0, y = 0 },
alignment = { x = 0, y = 0 },
})
local icon = player:hud_add({
hud_elem_type = "image",
text = "heart.png",
scale = scale,
offset = { x = 32, y = y },
position = { x = 0, y = 0 },
alignment = { x = 0, y = 0 },
})
local title = player:hud_add({
hud_elem_type = "text",
text = tostring(_),
position = { x = 0, y = 0 },
offset = { x = 460, y = y },
alignment = { x = 1, y = 0 },
number = 0xFFFFFF,
style = 1,
})
visual.tweens[_] = BeTweenApi.tween(
interpolation,
start,
finish,
4.0,
true,
{
on_step = function (step, tween)
local item = player:hud_get(icon)
player:hud_change(icon, "offset", { x = step, y = item.offset.y })
end,
on_stop = function (tween)
player:hud_remove(start_icon)
player:hud_remove(stop_icon)
player:hud_remove(icon)
player:hud_remove(title)
end,
}
)
index = index + 1
end
for _, tween in pairs(visual.tweens) do
tween:start()
end
end,
-- hide the debug hud from this specific player.
hide_functions = function (_, player_name)
if (_.player_huds[player_name] == nil) then
minetest.log("action", string.format("BeTween: The player '%s' has already the debug hud disabled.", player_name))
return
end
local player = minetest.get_player_by_name(player_name)
player:hud_remove(_.player_huds[player_name].title)
for _, tween in pairs(_.player_huds[player_name].tweens) do
tween:stop()
end
_.player_huds[player_name] = nil
end,
},
--[[
contain a list of interpolation functions,
each method require a start value, end value
and the position in time from start to end of the interpolation (0.0 to 1.0).
interpolation.linear(0, 8, 0.5) -- 4
interpolation.ease_in(0, 8, 0.5) -- 2
interpolation.ease_out(0, 8, 0.5) -- 4.5
]]
interpolation = {
-- straight increment from x to y in time.
linear = function (x, y, t)
return x + t * (y - x)
end,
-- movement increment faster from x to y in time.
ease_in = function (x, y, t)
return x + ((t * t) / 1.0) * (y - x)
end,
-- movement increment slower from x to y in time.
ease_out = function (x, y, t)
t = 1 - ((1 - t) ^ 2)
return BeTweenApi.interpolation.ease_in(x, y, t)
end,
-- movement is faster between x to y but slow down on begin and end in time.
ease_in_out = function (x, y, t)
x = BeTweenApi.interpolation.ease_in(x, y, t)
y = BeTweenApi.interpolation.ease_out(x, y, t)
return BeTweenApi.interpolation.linear(x, y , t)
end,
-- movement moves like linear, but reach his destination in half the time, the rest of the time is used to come back to the starting point.
spike_linear = function (x, y, t)
if (t <= 0.5) then
return BeTweenApi.interpolation.linear(x, y, t / 0.5)
end
return BeTweenApi.interpolation.linear(x, y, (1 - t) / 0.5)
end,
-- movement moves like ease in, but reach his destination in half the time, the rest of the time is used to come back to the starting point.
spike_ease_in = function (x, y, t)
if (t <= 0.5) then
return BeTweenApi.interpolation.ease_in(x, y, t / 0.5)
end
return BeTweenApi.interpolation.ease_in(x, y, (1 - t) / 0.5)
end,
-- movement moves like ease out, but reach his destination in half the time, the rest of the time is used to come back to the starting point.
spike_ease_out = function (x, y, t)
if (t <= 0.5) then
return BeTweenApi.interpolation.ease_out(x, y, t / 0.5)
end
return BeTweenApi.interpolation.ease_out(x, y, (1 - t) / 0.5)
end,
-- movement moves like ease in out, but reach his destination in half the time, the rest of the time is used to come back to the starting point.
spike_ease_in_out = function (x, y, t)
if (t <= 0.5) then
return BeTweenApi.interpolation.ease_in_out(x, y, t / 0.5)
end
return BeTweenApi.interpolation.ease_in_out(x, y, (1 - t) / 0.5)
end
},
--[[
create a new tween and retturn it, you can choose the interpolation method to use,
the initial and final value, the time it require to reach the end, if it must loop
(by default false) and callbacks on 3 events, each event give as an argoument the tween.
on_start(tween) -- executed the start method.
on_end(tween) -- executed the stop method or the tween has ended.
on_step(value, tween) -- called every time step of the function.
]]
tween = function (method, from, to, time, loop, callbacks)
if (callbacks == nil) then
callbacks = {}
end
local tween = {
method = method,
value_start = from,
value_end = to,
time_end = time,
timer = 0.0,
loop = loop,
on_start = callbacks.on_start,
on_stop = callbacks.on_stop,
on_step = callbacks.on_step,
-- start the tween to work by adding it from the active list.
start = function (_)
if (_:is_running() == true) then
minetest.log("action", "Tried to start tween twince!")
return
end
table.insert(BeTweenApi.active_tweens, _)
if (_.on_start ~= nil) then
_.on_start(_)
end
end,
-- stop the tween to work by removing it from the active list.
--
-- params:
-- reset = false, if true it will restart the tween timer.
stop = function (_, reset)
local index = _:index()
if (reset == nil) then
reset = false
end
if (index == nil) then
minetest.log("action", "Tried to stop tween when already stopped.")
return
end
if (reset == true) then
_.timer = 0
end
table.remove(BeTweenApi.active_tweens, index)
if (_.on_stop ~= nil) then
_.on_stop(_)
end
end,
-- check if the tween is currently running.
is_running = function (_)
for i, tween in pairs(BeTweenApi.active_tweens) do
if (tween == _) then
return true
end
end
return false
end,
-- get the running index of the tween, if the tween isn't running nil is returned.
index = function (_)
local index = 1
for i, tween in pairs(BeTweenApi.active_tweens) do
if (tween == _) then
return index
end
index = index + 1
end
return nil
end,
}
return tween
end
}
-- register the global step that will handle all running tweens.
minetest.register_globalstep(
function(dtime)
for _, tween in pairs(BeTweenApi.active_tweens) do
-- calculate the position in time from the current to the target,
-- make sure to clamp the range.
local t = tween.timer / tween.time_end
if (t > 1.0) then
t = 1.0
end
-- calculate the interpolated value.
local value = tween.method(
tween.value_start,
tween.value_end,
t
)
-- call the step of the tween.
if (tween.on_step ~= nil) then
tween.on_step(value, tween)
end
-- action to execute when the tween has finished his job.
if (t == 1.0) then
-- some extra millisecons may be inside the timer, this will remove them.
tween.timer = tween.time_end
-- if loop is disabled, stop the timer and reset it,
-- if enabled, simply restart the timer.
if (tween.loop == false) then
tween:stop(true)
else
tween.timer = 0
end
-- if the job isn't finished, continue to run the timer.
else
-- merge the current timer with all the time has passed from the previus step.
tween.timer = tween.timer + dtime
end
end
end
)
-- register simple debug command.
minetest.register_chatcommand(
"between",
{
description = "Toggle the debug hud of this api to the calling player.",
func = function (name, _)
if (BeTweenApi.debug.player_huds[name] == nil) then
BeTweenApi.debug:show_functions(name)
else
BeTweenApi.debug:hide_functions(name)
end
return true
end
}
)

4
mod.conf Normal file
View File

@ -0,0 +1,4 @@
name = api_between
title = BeTween Api
description = Interpolation functions and a Tween object to make smooth interpolations in huds or anything else you need.
author = GianptDev (_gianpy_)

24
readme.md Normal file
View File

@ -0,0 +1,24 @@
<p align=center>
<img src=resources/screenshot.svg width=320>
</p>
# BeTween Api
This is a mod that implements interpolation functions and tween for animation in the game [minetest](https://www.minetest.net/).
This mod can be used by other mods for animations, currently tested for huds.
![showcase](resources/showcase.gif)
## Installation
Just put this mod in your mod folder or in your custom mod.
## Wiki
Documentation about using the features of the api is written in the [docs](/docs) folder.
## Contribute
If you want to add more easing functions or want to ask about a specific feature, ask in the [Issues](https://github.com/GianptDev/between-api-minetest/issues) panel.

74
resources/screenshot.svg Normal file
View File

@ -0,0 +1,74 @@
<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<!-- Created with Inkscape (http://www.inkscape.org/) -->
<svg
width="320"
height="200"
viewBox="0 0 320 200"
version="1.1"
id="svg5"
inkscape:version="1.2 (dc2aedaf03, 2022-05-15)"
sodipodi:docname="screenshot.svg"
inkscape:export-filename="../screenshot.png"
inkscape:export-xdpi="96"
inkscape:export-ydpi="96"
xmlns:inkscape="http://www.inkscape.org/namespaces/inkscape"
xmlns:sodipodi="http://sodipodi.sourceforge.net/DTD/sodipodi-0.dtd"
xmlns="http://www.w3.org/2000/svg"
xmlns:svg="http://www.w3.org/2000/svg">
<sodipodi:namedview
id="namedview7"
pagecolor="#505050"
bordercolor="#eeeeee"
borderopacity="1"
inkscape:showpageshadow="0"
inkscape:pageopacity="0"
inkscape:pagecheckerboard="0"
inkscape:deskcolor="#505050"
inkscape:document-units="px"
showgrid="false"
inkscape:zoom="1.3037281"
inkscape:cx="193.29183"
inkscape:cy="144.96887"
inkscape:window-width="1304"
inkscape:window-height="745"
inkscape:window-x="54"
inkscape:window-y="-8"
inkscape:window-maximized="1"
inkscape:current-layer="layer1" />
<defs
id="defs2" />
<g
inkscape:label="Layer 1"
inkscape:groupmode="layer"
id="layer1">
<rect
style="fill:#a8cbfe;stroke:none;stroke-width:1;stroke-miterlimit:0;stroke-dasharray:none"
id="rect1886"
width="320"
height="200"
x="0"
y="0"
ry="4.4408921e-16" />
<path
id="path1738"
style="fill:#5a9cfe;stroke:none;stroke-width:1.24555;stroke-miterlimit:0;stroke-dasharray:none"
d="M 171.32753,25.350841 A 56.186156,99.177807 53.032143 0 0 53.688342,99.99878 56.186156,99.177807 53.032143 0 0 85.343631,174.64915 56.186156,99.177807 53.032143 0 0 202.98422,99.99878 56.186156,99.177807 53.032143 0 0 171.32753,25.350841 Z m -10.57211,17.457181 c 1.92543,-0.01676 3.8014,0.05576 5.60671,0.233541 0.81819,0.07345 1.83748,0.208538 2.47514,0.306523 3.81424,0.577395 7.30107,1.610727 10.38189,3.072522 10.49202,4.894108 15.92825,15.002839 15.02676,27.655134 -0.61357,10.672477 -5.94528,23.129223 -14.66826,34.977608 -10.74993,14.73026 -26.99882,28.34335 -44.07966,37.10625 -17.07743,8.87602 -35.35584,12.77174 -48.807297,10.29769 -12.021051,-2.09972 -20.378472,-9.06404 -23.1974,-19.25497 -0.31857,-1.09616 -0.577744,-2.39402 -0.741712,-3.46419 -1.875396,-11.45103 2.771302,-26.18401 12.581341,-40.317418 0.571769,-0.83504 1.343871,-1.905142 1.827757,-2.573815 5.043665,-6.850513 11.254193,-13.484302 18.187289,-19.486069 2.84661,-2.469871 6.018842,-4.991561 9.207252,-7.298153 18.09248,-13.175356 39.30551,-21.151995 56.20019,-21.254653 z" />
<text
xml:space="preserve"
style="font-style:normal;font-variant:normal;font-weight:bold;font-stretch:normal;font-size:42px;line-height:1.25;font-family:'Fira Code';-inkscape-font-specification:'Fira Code Bold';fill:#0d6efd;fill-opacity:1;stroke:none;stroke-width:1.43189;stroke-dasharray:none"
x="102.82876"
y="88.01162"
id="text186"><tspan
sodipodi:role="line"
id="tspan184"
x="102.82876"
y="88.01162"
style="font-style:normal;font-variant:normal;font-weight:bold;font-stretch:normal;font-size:42px;font-family:sans-serif;-inkscape-font-specification:'sans-serif Bold';fill:#0d6efd;stroke:none;stroke-width:1.43189;stroke-dasharray:none">BeTween</tspan><tspan
sodipodi:role="line"
x="102.82876"
y="141.97638"
id="tspan188"
style="font-style:normal;font-variant:normal;font-weight:bold;font-stretch:normal;font-size:42px;font-family:sans-serif;-inkscape-font-specification:'sans-serif Bold';fill:#0d6efd;stroke:none;stroke-width:1.43189;stroke-dasharray:none">API</tspan></text>
</g>
</svg>
Side by Side

After

Width:  |  Height:  |  Size: 3.8 KiB

BIN
resources/showcase.gif Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 136 KiB

BIN
screenshot.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 9.4 KiB