Release v5

.gitignore

@@ -9,4 +9,5 @@ deployer_version_settings.txt
 
 .deployer_cache
 dist
-deployer_build_stats.csv
+deployer_build_stats.csv
+/.editor_settings

.vscode/settings.json

@@ -12,4 +12,4 @@
 		"gui",
 		"vmath"
 	]
-}
+}

README.md

@@ -15,20 +15,20 @@
 
 - **Tweening**: Create tweens for any action your want.
 - **Easing Functions**: Provides a set of easing functions for different types of easings.
-- **Custom Update Frequency**: Option to define update frequency for the tween.
 - **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](https://www.defold.com/manuals/libraries/)
 
 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/4.zip)**
+**[Tweener](https://github.com/Insality/defold-tweener/archive/refs/tags/5.zip)**
 
 ```
-https://github.com/Insality/defold-tweener/archive/refs/tags/4.zip
+https://github.com/Insality/defold-tweener/archive/refs/tags/5.zip
 ```
 
 ### Library Size
@@ -41,10 +41,12 @@ https://github.com/Insality/defold-tweener/archive/refs/tags/4.zip
 | Desktop / Mobile | **6.21 KB**  |
 
 
-### Global Update Frequency
+### 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:
 
 ```ini
@@ -60,9 +62,13 @@ update_frequency = 60
 -- 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}
 
-tweener.ease(tween_function, from, to, time, time_elapsed)
-tweener.tween(tween_function, from, to, time, callback, [dt]) -- Returns tween_id
-tweener.cancel(tween_id)
+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
@@ -94,7 +100,7 @@ This function initiates a tween operation immediately. Here's how to use it:
   - `dt` (optional): The time interval for updating the tween, in seconds.
 
 - **Return Value:**
-  - `tweener_id`: A tweener id from `timer.delay` if you wish to cancel the tween.
+  - `tween`: A tween object. You can use it to cancel the tween, check if it still running, or pause it.
 
 - **Usage Example:**
 
@@ -107,12 +113,12 @@ tweener.tween(go.EASING_OUTSINE, 0, 100, 1.5, function(value, is_final_call)
 	print("Tween value: " .. value)
 end)
 
-local tween_id = tweener.tween({0, 0.2, 0.4, 0.8, 0.9, 1}, 0, 100, 1.5, function(value, is_final_call)
+local tween = tweener.tween({0, 0.2, 0.4, 0.8, 0.9, 1}, 0, 100, 1.5, function(value, is_final_call)
 	print("Tween value: " .. value)
 end)
 
 -- You can cancel the tween by calling tweener.cancel
-tweener.cancel(tween_id)
+tweener.cancel(tween)
 ```
 
 
@@ -148,29 +154,95 @@ print("The tween value at halfway point is: ", value)
 **tweener.cancel**
 ---
 ```lua
-tweener.cancel(tweener_id)
+tweener.cancel(tween)
 ```
 
-This function cancels the tween with the given `tweener_id`. This calls `timer.cancel` internally.
+This function cancels the tween with the given `tween` object.
 
 - **Parameters:**
-  - `tweener_id`: The id of the tween to cancel.
+  - `tween`: The tween object to cancel.
 
 - **Return Value:**
   - `true` if the tween was successfully canceled, `false` otherwise.
 
 - **Usage Example:**
 
 ```lua
-local tween_id = tweener.tween(tweener.linear, 0, 100, 1.5, function(value, is_final_call)
+local tween = tweener.tween(tweener.linear, 0, 100, 1.5, function(value, is_final_call)
 	print("Tween value: " .. value)
 end)
 
-tweener.cancel(tween_id)
+tweener.cancel(tween)
+```
+
+
+**tweener.is_paused**
+---
+```lua
+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**
+---
+```lua
+tweener.set_pause(tween, is_paused)
 ```
 
-These functions provide a flexible and powerful way to add animations and transitions to your projects, making them feel more dynamic and engaging. Enjoy animating with the **Tweener** module! *(Thanks, Mister ChatGPT)* 🙃
+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:**
+
+```lua
+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**
+---
+```lua
+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:**
+
+```lua
+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
 
@@ -285,6 +357,12 @@ If you have any issues, questions or suggestions please [create an issue](https:
 - 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.is_paused` function to check if a tween is paused
+- Added `tweener.is_active` function to check if a tween is active
+
+
 </details>
 
 

example/example.gui_script

@@ -3,7 +3,7 @@ local tweener = require("tweener.tweener")
 function init(self)
 	local text_score = gui.get_node("text_score")
 
-	tweener.tween(gui.EASING_OUTCIRC, 0, 9999, 2.4, function(value, is_final_call)
+	local tween_text = 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
@@ -23,19 +23,25 @@ function init(self)
 
 	local current_time = socket.gettime()
 	local custom_easing = {0, 0.4, 0.5, 0.6, 0.5, 0.4, 0.5, 0.6, 1}
-	tweener.tween(custom_easing, 75, 885, 2.4, function(value, is_final_call)
+	local tween_box = tweener.tween(custom_easing, 75, 885, 2.4, function(value, is_final_call)
 		box_pos.x = value
 		gui.set_position(box, box_pos)
 
 		if is_final_call then
 			print("Tween took", socket.gettime() - current_time)
+			gui.set_scale(box, vmath.vector3(1.25, 1.25, 1))
+			gui.animate(box, "scale", vmath.vector3(1, 1, 1), gui.EASING_OUTBOUNCE, 0.5)
 		end
 	end)
 
-	timer.delay(2.4, false, function()
-		gui.set_scale(box, vmath.vector3(1.25, 1.25, 1))
-		gui.animate(box, "scale", vmath.vector3(1, 1, 1), gui.EASING_OUTBOUNCE, 0.5)
+	timer.delay(1, false, function()
+		tweener.set_pause(tween_box, true)
+		tweener.set_pause(tween_text, true)
 
-		print("Timer took", socket.gettime() - current_time)
+	end)
+
+	timer.delay(2, false, function()
+		tweener.set_pause(tween_box, false)
+		tweener.set_pause(tween_text, false)
 	end)
 end

test/test_tweener.lua

@@ -83,7 +83,36 @@ return function()
 			assert(tweener.ease(go.EASING_OUTQUART, 0, 1, 1, 0) < epsilon)
 			assert(tweener.ease(go.EASING_OUTQUINT, 0, 1, 1, 0) < epsilon)
 			assert(tweener.ease(go.EASING_OUTSINE, 0, 1, 1, 0) < epsilon)
+		end)
+
+		it("Tween can be cancelled", function()
+			local tween = tweener.tween(go.EASING_LINEAR, 0, 100, 1, function() end)
+			assert(tweener.is_active(tween))
+			tweener.cancel(tween)
+			assert(not tweener.is_active(tween))
+		end)
+
+		it("Tween can be paused", function()
+			local tween = tweener.tween(go.EASING_LINEAR, 0, 100, 1, function() end)
+			assert(tweener.is_active(tween))
+			tweener.set_pause(tween, true)
+			assert(tweener.is_paused(tween))
+		end)
+
+		it("Tween can be resumed", function()
+			local tween = tweener.tween(go.EASING_LINEAR, 0, 100, 1, function() end)
+			assert(tweener.is_active(tween))
+			tweener.set_pause(tween, true)
+			assert(tweener.is_paused(tween))
+			tweener.set_pause(tween, false)
+			assert(not tweener.is_paused(tween))
+		end)
 
+		it("Tween can be checked if it is active", function()
+			local tween = tweener.tween(go.EASING_LINEAR, 0, 100, 1, function() end)
+			assert(tweener.is_active(tween))
+			tweener.cancel(tween)
+			assert(not tweener.is_active(tween))
 		end)
 	end)
 end