Token - library designed for the Defold game engine to manage countable items such as money, lives, and other numeric values. This library provides a robust and flexible system for handling various token-related operations, including creation, management, and restoration of token values.
- Token Management - Create, delete, and manage tokens within containers.
- Container Management - Create, delete, and manage token containers.
- Visual Management - Control the displayed amount separately from the actual value for smooth UI animations.
- Callbacks - Customizable callbacks for token changes.
- Token Groups - Support for grouped token operations.
- Token Restoration - Configurable restoration mechanics for tokens.
- Infinity Tokens - Manage tokens with infinite time usage.
Can be installed from the Asset Store extension to skip this step.
Open your game.project file and add the following line to the dependencies field under the project section:
https://github.com/Insality/defold-event/archive/refs/tags/14.zip
https://github.com/Insality/defold-token/archive/refs/tags/5.zip
After that, select Project ▸ Fetch Libraries to update library dependencies. This happens automatically whenever you open a project so you will only need to do this if the dependencies change without re-opening the project.
Note: The library size is calculated based on the build report per platform
| Platform | Library Size |
|---|---|
| HTML5 | 7.16 KB |
| Desktop / Mobile | 13.84 KB |
- Token: A countable item such as money, lives, or other numeric values.
- Container: A collection of tokens.
- Token Group: A group of tokens that can be managed together and have a group id.
- Token Lot: A data with a price group id and reward group id. Can be used for shop items, for example.
In Token library, you create a container which contains tokens.
local token = require("token.token")
token.init({
["money"] = { default = 100, min = 0, max = 10000 },
["exp"] = {},
["level"] = { default = 1, min = 1, max = 100 },
})
local state = token.get_state() -- get the current state for save/load
token.set_state(state) -- set the state for save/load
token.container("wallet"):add("exp", 100) -- Will be 100, due the default value is 0
token.container("wallet"):add("level", 1) -- Will be 2, due the default value is 1
token.container("wallet"):pay("money", 100) -- Will be 0, due the default value is 100
token.container("wallet"):add("gems", 20) -- Token configs is not required to operate with tokens
-- Configs is not required to operate with tokens
token.container("skill"):add("damage", 100) -- Return token instance
token.container("skill"):get("damage") -- Return 100
token.container("skill"):set("crit_chance", 0.1) -- Set crit chance to 10%local token = require("token.token")
-- Initialize the token system
token.init([tokens_config_or_path], [config_group])
token.get_state()
token.set_state(new_state)
token.reset_state()
-- Containers
token.container(container_id, [config_group])
token.delete_container(container_id)
token.clear_container(container_id)
token.is_container_exist(container_id)
-- Data management
token.register_tokens(tokens, [config_group])
token.register_token_groups(groups)
token.register_lots(lots_data)
token.get_token_group(token_group_id)
token.get_lot_reward(lot_id)
token.get_lot_price(lot_id)
token.get_token_config(token_id)
-- System
token.set_logger([logger_instance])
-- Events
token.on_token_change -- (container_id, token_id, amount, reason)
token.on_token_visual_change -- (container_id, token_id, amount)
token.on_token_restore_change -- (container_id, token_id, restore_config)local container = token.container("wallet")
-- Single Token
container:add(token_id, amount, [reason], [visual_later])
container:set(token_id, amount, [reason], [visual_later])
container:get(token_id)
container:pay(token_id, amount, [reason], [visual_later])
container:is_enough(token_id, amount)
container:is_empty(token_id)
container:is_max(token_id)
-- Multiple Tokens
container:add_many([tokens], [reason], [visual_later])
container:set_many([tokens], [reason], [visual_later])
container:pay_many(tokens, [reason], [visual_later])
container:is_enough_many([tokens])
container:get_many()
-- Token Groups
container:add_group(group_id, [reason], [visual_later])
container:set_group(group_id, [reason], [visual_later])
container:pay_group(group_id, [reason], [visual_later])
container:is_enough_group(group_id)
-- Visual Management
container:sync_visual(token_id)
container:add_visual(token_id, amount)
container:get_visual(token_id)
-- Info
container:get_total_sum(token_id)
container:get_token_config(token_id)
-- Restore Config
container:set_restore_config(token_id, config)
container:get_restore_config(token_id)
container:set_restore_config_enabled(token_id, is_enabled)
container:is_restore_config_enabled(token_id)
container:remove_restore_config(token_id)
container:reset_restore_timer(token_id)
container:get_time_to_restore(token_id)
-- Infinity Config
container:add_infinity_time(token_id, seconds)
container:is_infinity(token_id)
container:get_infinity_time(token_id)
container:set_infinity_time(token_id, time)
-- Events
container.on_token_change -- (token_id, amount, reason)
container.on_token_visual_change -- (token_id, amount)
container.on_token_restore_change -- (token_id, restore_config)Read the API Reference:
Read the Use Cases file to see several examples of how to use the this module in your Defold game development projects.
This project is licensed under the MIT License - see the LICENSE file for details.
For any issues, questions, or suggestions, please create an issue.
Details
- Initial Release
- Tests, refactor, docs, annotations
- Refactor containers and token API
- Update docs
- Restore config
max: now acts as both cap on total value (restore never exceeds it) and max gain per offline batch. No restore when current >= max - When token value drops below restore max (e.g. after spend), restore timer starts from that moment
- Fix token total sum history tracking
Your donation helps me stay engaged in creating valuable projects for Defold. If you appreciate what I'm doing, please consider supporting me!
