{"id":15723208,"url":"https://github.com/whiteboxdev/library-defold-timer","last_synced_at":"2025-09-04T19:49:19.879Z","repository":{"id":74948341,"uuid":"457541766","full_name":"whiteboxdev/library-defold-timer","owner":"whiteboxdev","description":"Defold Timer provides a visual timer widget in a Defold game engine project.","archived":false,"fork":false,"pushed_at":"2024-05-24T16:20:46.000Z","size":238,"stargazers_count":16,"open_issues_count":2,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-05-02T23:08:40.876Z","etag":null,"topics":["defold","defold-library"],"latest_commit_sha":null,"homepage":"","language":"Lua","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"zlib","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/whiteboxdev.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2022-02-09T21:56:46.000Z","updated_at":"2025-04-09T10:20:39.000Z","dependencies_parsed_at":"2024-04-19T22:33:57.224Z","dependency_job_id":"0cab0aeb-d62b-475f-89b1-1522a99fddfc","html_url":"https://github.com/whiteboxdev/library-defold-timer","commit_stats":null,"previous_names":["whiteboxdev/library-defold-timer"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/whiteboxdev%2Flibrary-defold-timer","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/whiteboxdev%2Flibrary-defold-timer/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/whiteboxdev%2Flibrary-defold-timer/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/whiteboxdev%2Flibrary-defold-timer/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/whiteboxdev","download_url":"https://codeload.github.com/whiteboxdev/library-defold-timer/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":252798762,"owners_count":21805879,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["defold","defold-library"],"created_at":"2024-10-03T22:10:41.483Z","updated_at":"2025-05-07T01:45:20.211Z","avatar_url":"https://github.com/whiteboxdev.png","language":"Lua","funding_links":[],"categories":["Libraries"],"sub_categories":["Programming Language"],"readme":"# Defold Timer\n\nDefold Timer provides a visual timer widget in a Defold game engine project.\n\nPlease click the ☆ button on GitHub if this repository is useful or interesting. Thank you!\n\n![alt text](https://github.com/whiteboxdev/library-defold-timer/blob/main/assets/thumbnail.png?raw=true)\n\n## Installation\n\nAdd the latest version to your project's dependencies:  \nhttps://github.com/whiteboxdev/library-defold-timer/archive/main.zip\n\n## Configuration\n\nImport the dtimer Lua module into your relevant gui scripts:  \n`local dtimer = require \"dtimer.dtimer\"`\n\nIn 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.\n\nThis 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.\n\nTimers 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.\n\nSee the following code for a basic usage scenario:\n\n```\nlocal dtimer = require \"dtimer.dtimer\"\n\n-- Hash of gui node id.\nlocal node_timer = hash(\"node_timer\")\n\nfunction init(self)\n    msg.url(msg.url(), hash(\"acquire_input_focus\"))\n    dtimer.set_url(msg.url())\n    -- Count up to 1 hour and display all timestamp components.\n    dtimer.add_node(node_timer, true, { hours = true, minutes = true, seconds = true, centiseconds = true }, 3600)\n    dtimer.start(node_timer)\nend\n\nfunction update(self, dt)\n    dtimer.update(dt)\nend\n\nfunction on_message(self, message_id, message, sender)\n    if message_id == dtimer.messages.start then\n        -- If timer starts, turn node green.\n        gui.set_color(gui.get_node(message.node_id), vmath.vector4(0, 1, 0, 1))\n    elseif message_id == dtimer.messages.stop then\n        -- If timer stops and limit is reached, turn node red.\n        -- If timer stops and limit is not reached or no limit exists, turn node yellow.\n        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))\n    end\nend\n```\n\n## API: Properties\n\n### dtimer.messages\n\nTable of hashes which are sent to the `on_message()` function of the corresponding gui script:\n\n```\ndtimer.messages\n{\n    start = hash(\"dtimer_start\"),\n    stop = hash(\"dtimer_stop\")\n}\n```\n\n`start`: Sent when a timer starts. The `message` table contains the following:\n\n```\n{\n    node_id = \u003chash\u003e,\n    elapsed = \u003cnumber\u003e -- Starting value of the timer in seconds.\n}\n```\n\n`stop`: Sent when a timer stops. The `message` table contains the following:\n\n```\n{\n    node_id = \u003chash\u003e,\n    elapsed = \u003cnumber\u003e, -- Stopping value of the timer in seconds.\n    complete = \u003cbool\u003e -- If the timer reached its `duration` limit.\n}\n```\n\n## API: Functions\n\n### dtimer.add_node(node_id, increasing, [format], [duration])\n\nAdds a gui node to the timer system. Timers begin in the stopped state.\n\n#### Parameters\n1. `node_id`: Hashed id of a gui node.\n2. `increasing`: `bool` if timer should count up or down.\n3. `[format]`: Table that specifies which timestamp components to display:\n\n```\n{\n    hours = false,\n    minutes = true,\n    seconds = true,\n    centiseconds = false\n}\n```\n\nIf `format` is `nil`, then the above default will be used.\n\n4. `[duration]`: Maximum elapsed seconds counting up from zero or start time counting down to zero. This argument is required if `increasing` is `false`.\n\n---\n\n### dtimer.remove_node(node_id)\n\nRemoves a node from the timer system.\n\n#### Parameters\n1. `node_id`: Hashed id of a gui node.\n\n---\n\n### dtimer.start(node_id, [reset])\n\nStarts 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.\n\n#### Parameters\n1. `node_id`: Hashed id of a gui node.\n2. `[reset]`: `bool` if the timer should reset to zero.\n\n---\n\n### dtimer.stop(node_id, [reset])\n\nStops the timer attached to a node.\n\n#### Parameters\n1. `node_id`: Hashed id of a gui node.\n2. `[reset]`: `bool` if the timer should reset to zero.\n\n---\n\n### dtimer.toggle(node_id, [reset])\n\nToggles the timer attached to a node.\n\n#### Parameters\n1. `node_id`: Hashed id of a gui node.\n2. `[reset]`: `bool` if the timer should reset to zero.\n\n---\n\n### dtimer.update(dt)\n\nUpdates all timers and displays. Should be called in the `update(self, dt)` function of your gui script.\n\n#### Parameters\n1. `dt`: Time elapsed since last frame.\n\n---\n\n### dtimer.set_url(url)\n\nSets the url of the gui script to receive `dtimer` messages.\n\n#### Parameters\n1. `url`: Url of the gui script to receive `dtimer` messages.\n\n---\n\n### dtimer.set_format(node_id, format)\n\nSets the format of a node.\n\n#### Parameters\n1. `node_id`: Hashed id of a gui node.\n2. `format`: Table that specifies which timestamp components to display:\n\n```\n{\n    hours = false,\n    minutes = true,\n    seconds = true,\n    centiseconds = false\n}\n```\n\n---\n\n### dtimer.set_timestamp(node_id, format, seconds)\n\nApplies 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.\n\n#### Parameters\n1. `node_id`: Hashed id of a gui node.\n2. `format`: Table that specifies which timestamp components to display:\n\n```\n{\n    hours = false,\n    minutes = true,\n    seconds = true,\n    centiseconds = false\n}\n```\n\n3. `seconds`: Seconds to format into a timestamp.\n\n---\n\n### dtimer.get_elapsed(node_id)\n\nGets the elapsed time of a node in seconds.\n\n#### Parameters\n1. `node_id`: Hashed id of a gui node.\n\n#### Returns\nReturn a `number`.\n\n---\n\n### dtimer.get_timestamp(node_id)\n\nGets a verbose timestamp of a node.\n\n#### Parameters\n1. `node_id`: Hashed id of a gui node.\n\n#### Returns\nReturn a table in the following format:\n\n```\n{\n    hours = \u003cnumber\u003e,\n    minutes = \u003cnumber\u003e,\n    seconds = \u003cnumber\u003e,\n    centiseconds = \u003cnumber\u003e\n}\n```\n\n---\n\n### dtimer.is_enabled(node_id)\n\nChecks if the timer attached to a node is running.\n\n#### Parameters\n1. `node_id`: Hashed id of a gui node.\n\n#### Returns\n\nReturns `true` or `false`.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwhiteboxdev%2Flibrary-defold-timer","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fwhiteboxdev%2Flibrary-defold-timer","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwhiteboxdev%2Flibrary-defold-timer/lists"}