Tweener

Tweener - is a single file Lua module for the Defold game engine. It provides a way to handle manual tweening in your game.

Features

• Tweening: Create tweens for any action your want.
• Easing Functions: Provides a set of easing functions for different types of easings.
• Callbacks: Callbacks for each tween update.
• Custom Easings: Support for custom easing functions.
• Custom Update Frequency: Option to define update frequency for the tween.

Setup

Dependency

Open your game.project file and add the following line to the dependencies field under the project section:

Tweener

https://github.com/Insality/defold-tweener/archive/refs/tags/6.zip

Library Size

Note: The library size is calculated based on the build report per platform

Platform	Library Size
HTML5	3.28 KB
Desktop / Mobile	6.21 KB

Global Update Frequency [Optional]

Optionally, you can setup global default update frequency in your game.project. It's 60 by default.

This is a global settings for the tweener. You can specify the update frequence parameter in the tweener.tween function for special tween operation.

Add next tweener section to your game.project in text mode:

[tweener]
update_frequency = 60

API Reference

Quick API Reference

-- Tween function can be a string, a predefined easing function, or a custom easing function
local tween_function = "linear" or tweener.linear or go.EASING_LINEAR or gui.EASING_LINEAR or {0, 0.2, 0.4, 0.8, 0.9, 1}

local tween = tweener.tween(tween_function, from, to, time, callback, [dt])
tweener.cancel(tween)
tweener.set_pause(tween, true)
tweener.is_paused(tween)
tweener.is_active(tween)

local value = tweener.ease(tween_function, from, to, time, time_elapsed)

Importing the Module

To start using the Tweener module in your project, you first need to import it. This can be done with the following line of code:

local tweener = require("tweener.tweener")

Functions

The Tweener module provides two primary functions to work with tweens:

tweener.tween

tweener.tween(tween_function, from, to, time, callback, [dt])

This function initiates a tween operation immediately. Here's how to use it:

• Parameters:

  • tween_function: The tween function. You can use one of the predefined easing functions or provide a custom one.
  • from: The starting value of the tween.
  • to: The ending value of the tween.
  • time: The duration of the tween, in seconds.
  • callback: A function(value, is_final_call, time_elapsed, time_total) that gets called upon each update of the tween.
  • dt (optional): The time interval for updating the tween, in seconds.

• Return Value:

  • tween: A tween object. You can use it to cancel the tween, check if it still running, or pause it.

• Usage Example:

tweener.tween(tweener.linear, 0, 100, 1.5, function(value, is_final_call)
	print("Tween value: " .. value)
end)

tweener.tween(go.EASING_OUTSINE, 0, 100, 1.5, function(value, is_final_call)
	print("Tween value: " .. value)
end)

local tween = tweener.tween({0, 0.2, 0.4, 0.8, 0.9, 1}, 0, 100, 1.5, function(value, is_final_call, time_elapsed, time_total)
	print("Tween value: " .. value)
	print("Time elapsed: " .. time_elapsed .. " from " .. time_total .. " seconds")
end)

-- You can cancel the tween by calling tweener.cancel
tweener.cancel(tween)

tweener.ease

tweener.ease(tween_function, from, to, time, time_elapsed)

This function calculates the value of the tween at a specific point in time, based on the easing function provided.

• Parameters:

  • tween_function: The tween function.
  • from: The starting value of the tween.
  • to: The ending value of the tween.
  • time: The total duration of the tween, in seconds.
  • time_elapsed: The elapsed time since the start of the tween, in seconds.

• Usage Example:

local value = tweener.ease(tweener.inquad, 0, 100, 1.5, 0.75)
print("The tween value at halfway point is: ", value)

local value = tweener.ease(gui.EASING_OUTSINE, 0, 100, 1.5, 0.75)
print("The tween value at halfway point is: ", value)

local value = tweener.ease({0, 0.2, 0.4, 0.8, 0.9, 1}, 0, 100, 1.5, 0.75)
print("The tween value at halfway point is: ", value)

tweener.cancel

tweener.cancel([tween])

This function cancels the tween with the given tween object.

• Parameters:

  • tween: The tween object to cancel.

• Return Value:

  • true if the tween was successfully canceled, false otherwise.

• Usage Example:

local tween = tweener.tween(tweener.linear, 0, 100, 1.5, function(value, is_final_call)
	print("Tween value: " .. value)
end)

tweener.cancel(tween)

tweener.is_paused

tweener.is_paused(tween)

This function returns true if the tween is paused, false otherwise.

• Parameters:

  • tween: The tween object to check. It returned from tweener.tween function.

• Return Value:

  • true if the tween is paused, false otherwise.

tweener.set_pause

tweener.set_pause(tween, is_paused)

This function sets the pause state of the tween.

• Parameters:

  • tween: The tween object to set the pause state. It returned from tweener.tween function.
  • is_paused: The new pause state.

• Return Value:

  • true if the tween was successfully paused, false otherwise.

• Usage Example:

local tween = tweener.tween(tweener.linear, 0, 100, 1.5, function(value, is_final_call)
	print("Tween value: " .. value)
end)

tweener.set_pause(tween, true)
tweener.is_paused(tween) -- Returns true

tweener.is_active

tweener.is_active(tween)

This function returns true if the tween is running, false is the tween is finished.

• Parameters:

  • tween: The tween object to check. It returned from tweener.tween function.

• Return Value:

  • true if the tween is running, false is the tween is finished.

• Usage Example:

local tween = tweener.tween(tweener.linear, 0, 100, 1.5, function(value, is_final_call)
	print("Tween value: " .. value)
end)

tweener.is_active(tween) -- Returns true
-- Wait for 1.5 seconds
tweener.is_active(tween) -- Returns false

Tween Functions

Tweener Constant	Defold Constant	Easing
tweener.linear	go.EASING_LINEAR
tweener.insine	go.EASING_INSINE
tweener.inquad	go.EASING_INQUAD
tweener.incubic	go.EASING_INCUBIC
tweener.incirc	go.EASING_INCIRC
tweener.inquart	go.EASING_INQUART
tweener.inquint	go.EASING_INQUINT
tweener.inexpo	go.EASING_INEXPO
tweener.inback	go.EASING_INBACK
tweener.inelastic	go.EASING_INELASTIC
tweener.inbounce	go.EASING_INBOUNCE
tweener.outsine	go.EASING_OUTSINE
tweener.outquad	go.EASING_OUTQUAD
tweener.outcubic	go.EASING_OUTCUBIC
tweener.outcirc	go.EASING_OUTCIRC
tweener.outquart	go.EASING_OUTQUART
tweener.outquint	go.EASING_OUTQUINT
tweener.outexpo	go.EASING_OUTEXPO
tweener.outback	go.EASING_OUTBACK
tweener.outelastic	go.EASING_OUTELASTIC
tweener.outbounce	go.EASING_OUTBOUNCE
tweener.inoutsine	go.EASING_INOUTSINE
tweener.inoutquad	go.EASING_INOUTQUAD
tweener.inoutcubic	go.EASING_INOUTCUBIC
tweener.inoutcirc	go.EASING_INOUTCIRC
tweener.inoutquart	go.EASING_INOUTQUART
tweener.inoutquint	go.EASING_INOUTQUINT
tweener.inoutexpo	go.EASING_INOUTEXPO
tweener.inoutback	go.EASING_INOUTBACK
tweener.inoutelastic	go.EASING_INOUTELASTIC
tweener.inoutbounce	go.EASING_INOUTBOUNCE
tweener.outinsine	go.EASING_OUTINSINE
tweener.outinquad	go.EASING_OUTINQUAD
tweener.outincubic	go.EASING_OUTINCUBIC
tweener.outincirc	go.EASING_OUTINCIRC
tweener.outinquart	go.EASING_OUTINQUART
tweener.outinquint	go.EASING_OUTINQUINT
tweener.outinexpo	go.EASING_OUTINEXPO
tweener.outinback	go.EASING_OUTINBACK
tweener.outinelastic	go.EASING_OUTINELASTIC
tweener.outinbounce	go.EASING_OUTINBOUNCE

Usage

You can use Tweener to animate scoring text, for example:

This animation can be created using the following code:

tweener.tween(gui.EASING_OUTCIRC, 0, 9999, 2.4, function(value, is_final_call)
	gui.set_text(text_score, "Score: " .. math.floor(value))

	if is_final_call then
		gui.set_scale(text_score, vmath.vector3(1.25, 1.25, 1))
		gui.animate(text_score, "scale", vmath.vector3(1, 1, 1), gui.EASING_OUTBOUNCE, 0.5)
	end
end)

You can obtain the value of the tween at any point in time with the tweener.ease function:

tweener.ease(gui.EASING_OUTSINE, 0, 100, 1, 0)    -- Returns 0
tweener.ease(gui.EASING_OUTSINE, 0, 100, 1, 0.25) -- Returns 38.268343236509
tweener.ease(gui.EASING_OUTSINE, 0, 100, 1, 0.5)  -- Returns 70.710678118655
tweener.ease(gui.EASING_OUTSINE, 0, 100, 1, 0.75) -- Returns 92.387953251129
tweener.ease(gui.EASING_OUTSINE, 0, 100, 1, 1)    -- Returns 100

License

This project is licensed under the MIT License - see the LICENSE file for details.

Issues and suggestions

If you have any issues, questions or suggestions please create an issue.

👏 Contributors

Changelog

V1

• Initial release

V2

• Changed timer delta time to socket.gettime for more precise tweening

V3

• Added custom easings support

V4

• Fix update_frequency game.project settings typo
• Now able to use string name of easing functions (ex. "linear", "insine", "outquad", etc.)
• Add tweener.cancel function to cancel tweening instead of timer.cancel (For better API and README)
• Code cleanup and better performance
• Fix if total time is 0, then callback will be called immediately

V5

• [Breaking]: tweener.tween now returns a tween object instead of a timer id. So if you used timer.cancel to cancel the tween, you need to use tweener.cancel instead.
• Added tweener.set_pause function to pause and resume a tween
• Added tweener.is_paused function to check if a tween is paused
• Added tweener.is_active function to check if a tween is active

V6

• Add time_elapsed and time_total parameters to the tween callback function
• The tweener.cancel now can be called with a nil object to escape the additional if check

❤️ Support project ❤️

Your donation helps me stay engaged in creating valuable projects for Defold. If you appreciate what I'm doing, please consider supporting me!