Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/whiteboxdev/library-defold-timer
Defold Timer provides a visual timer widget in a Defold game engine project.
https://github.com/whiteboxdev/library-defold-timer
defold defold-library
Last synced: about 2 months ago
JSON representation
Defold Timer provides a visual timer widget in a Defold game engine project.
- Host: GitHub
- URL: https://github.com/whiteboxdev/library-defold-timer
- Owner: whiteboxdev
- License: zlib
- Created: 2022-02-09T21:56:46.000Z (almost 3 years ago)
- Default Branch: main
- Last Pushed: 2024-05-24T16:20:46.000Z (7 months ago)
- Last Synced: 2024-10-25T10:04:34.228Z (about 2 months ago)
- Topics: defold, defold-library
- Language: Lua
- Homepage:
- Size: 232 KB
- Stars: 15
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
- awesome-defold - Timer
README
# Defold Timer
Defold Timer provides a visual timer widget in a Defold game engine project.
Please click the ☆ button on GitHub if this repository is useful or interesting. Thank you!
## Installation
Add the latest version to your project's dependencies:
https://github.com/whiteboxdev/library-defold-timer/archive/main.zip
## Configuration
Import the dtimer Lua module into your relevant gui scripts:
`local dtimer = require "dtimer.dtimer"`
In many games, there exists some kind of on-screen timer counting up or down to track the player's rate of progression through a level or scenario. The elapsed time can then be used for various purposes, for example saving the player's fastest attempt at a level or restarting a level when time runs out.
This library only handles timer logic and setting the text of a gui node with `gui.set_text()`. The user retains all styling authority over their gui nodes. These philosophies allow for simplicity, robustness, and separation of concerns.
Timers used in `dtimer` hold four components: hours, minutes, seconds, and centiseconds. The user can specify which of these components to display in their gui nodes. Leading zeros are displayed appropriately.
See the following code for a basic usage scenario:
```
local dtimer = require "dtimer.dtimer"
-- Hash of gui node id.
local node_timer = hash("node_timer")
function init(self)
msg.url(msg.url(), hash("acquire_input_focus"))
dtimer.set_url(msg.url())
-- Count up to 1 hour and display all timestamp components.
dtimer.add_node(node_timer, true, { hours = true, minutes = true, seconds = true, centiseconds = true }, 3600)
dtimer.start(node_timer)
end
function update(self, dt)
dtimer.update(dt)
end
function on_message(self, message_id, message, sender)
if message_id == dtimer.messages.start then
-- If timer starts, turn node green.
gui.set_color(gui.get_node(message.node_id), vmath.vector4(0, 1, 0, 1))
elseif message_id == dtimer.messages.stop then
-- If timer stops and limit is reached, turn node red.
-- If timer stops and limit is not reached or no limit exists, turn node yellow.
gui.set_color(gui.get_node(message.node_id), message.complete and vmath.vector4(1, 0, 0, 1) or vmath.vector4(1, 1, 0, 1))
end
end
```
## API: Properties
### dtimer.messages
Table of hashes which are sent to the `on_message()` function of the corresponding gui script:
```
dtimer.messages
{
start = hash("dtimer_start"),
stop = hash("dtimer_stop")
}
```
`start`: Sent when a timer starts. The `message` table contains the following:
```
{
node_id = ,
elapsed = -- Starting value of the timer in seconds.
}
```
`stop`: Sent when a timer stops. The `message` table contains the following:
```
{
node_id = ,
elapsed = , -- Stopping value of the timer in seconds.
complete = -- If the timer reached its `duration` limit.
}
```
## API: Functions
### dtimer.add_node(node_id, increasing, [format], [duration])
Adds a gui node to the timer system. Timers begin in the stopped state.
#### Parameters
1. `node_id`: Hashed id of a gui node.
2. `increasing`: `bool` if timer should count up or down.
3. `[format]`: Table that specifies which timestamp components to display:
```
{
hours = false,
minutes = true,
seconds = true,
centiseconds = false
}
```
If `format` is `nil`, then the above default will be used.
4. `[duration]`: Maximum elapsed seconds counting up from zero or start time counting down to zero. This argument is required if `increasing` is `false`.
---
### dtimer.remove_node(node_id)
Removes a node from the timer system.
#### Parameters
1. `node_id`: Hashed id of a gui node.
---
### dtimer.start(node_id, [reset])
Starts the timer attached to a node. If the timer is already started and `reset` is `true`, then its elapsed time will reset and continue counting without stopping.
#### Parameters
1. `node_id`: Hashed id of a gui node.
2. `[reset]`: `bool` if the timer should reset to zero.
---
### dtimer.stop(node_id, [reset])
Stops the timer attached to a node.
#### Parameters
1. `node_id`: Hashed id of a gui node.
2. `[reset]`: `bool` if the timer should reset to zero.
---
### dtimer.toggle(node_id, [reset])
Toggles the timer attached to a node.
#### Parameters
1. `node_id`: Hashed id of a gui node.
2. `[reset]`: `bool` if the timer should reset to zero.
---
### dtimer.update(dt)
Updates all timers and displays. Should be called in the `update(self, dt)` function of your gui script.
#### Parameters
1. `dt`: Time elapsed since last frame.
---
### dtimer.set_url(url)
Sets the url of the gui script to receive `dtimer` messages.
#### Parameters
1. `url`: Url of the gui script to receive `dtimer` messages.
---
### dtimer.set_format(node_id, format)
Sets the format of a node.
#### Parameters
1. `node_id`: Hashed id of a gui node.
2. `format`: Table that specifies which timestamp components to display:
```
{
hours = false,
minutes = true,
seconds = true,
centiseconds = false
}
```
---
### dtimer.set_timestamp(node_id, format, seconds)
Applies a timestamp to a node that is not registered with `dtimer`. This is useful when a node should not be tracked by `dtimer.add_node()`, but should display a formatted timestamp.
#### Parameters
1. `node_id`: Hashed id of a gui node.
2. `format`: Table that specifies which timestamp components to display:
```
{
hours = false,
minutes = true,
seconds = true,
centiseconds = false
}
```
3. `seconds`: Seconds to format into a timestamp.
---
### dtimer.get_elapsed(node_id)
Gets the elapsed time of a node in seconds.
#### Parameters
1. `node_id`: Hashed id of a gui node.
#### Returns
Return a `number`.
---
### dtimer.get_timestamp(node_id)
Gets a verbose timestamp of a node.
#### Parameters
1. `node_id`: Hashed id of a gui node.
#### Returns
Return a table in the following format:
```
{
hours = ,
minutes = ,
seconds = ,
centiseconds =
}
```
---
### dtimer.is_enabled(node_id)
Checks if the timer attached to a node is running.
#### Parameters
1. `node_id`: Hashed id of a gui node.
#### Returns
Returns `true` or `false`.