Insality/defold-token/token
The Defold Token module. Used to manage all countable items in the game.
- GitHub: Insality/defold-token — pinned to
9- This repo publishes no stable release. Pick a tag from Insality/defold-token tags and add its Source code (zip) URL — for the pinned tag,
https://github.com/Insality/defold-token/archive/refs/tags/9.zip— togame.projectunder[project]dependencies, then Fetch Libraries in the Defold editor. - Run
bunx @defold-typescript/cli resolveto materialize its types. - Import it under a namespace alias of your choice:
import * as token from "token"
- This repo publishes no stable release. Pick a tag from Insality/defold-token tags and add its Source code (zip) URL — for the pinned tag,
Functions
reset_state()get_state():token_stateset_state(new_state:token_state)set_logger(logger_instance?:token_logger| LuaTable | undefined)container(container_id: string, config_group?: string | undefined):token_containerdelete_container(container_id: string)clear_container(container_id: string)is_container_exist(container_id: string): booleanregister_tokens(tokens: LuaMap<string,token_token_config_data> | Record<string,token_token_config_data> | string, config_group?: string | undefined)register_token_groups(groups: LuaMap<string, LuaMap<string, number> | Record<string, number>> | Record<string, LuaMap<string, number> | Record<string, number>> | string)register_lots(lots_data: LuaMap<string,token_lot> | Record<string,token_lot> | string)get_token_group(token_group_id: string): LuaTable<string, number> | undefinedget_lot_reward(lot_id: string): LuaTable<string, number> | undefinedget_lot_price(lot_id: string): LuaTable<string, number> | undefinedget_token_config(token_id: string):token_token_config_data| undefinedinit(tokens_config_or_path?: LuaMap<string,token_token_config_data> | Record<string,token_token_config_data> | string | undefined, config_group?: string | undefined)update()
reset_state()
Active container instances Timer handle for update loop Call this to reset state to default
get_state(): token_state
Get the current state for serialization
Returns
token_state
set_state(new_state: token_state)
Set the state (for deserialization)
Parameters
new_state:token_state
set_logger(logger_instance?: token_logger | LuaTable | undefined)
Customize the logging mechanism used by Token Module. You can use Defold Log library or provide a custom logger.
Parameters
logger_instance?:token_logger | LuaTable | undefined
container(container_id: string, config_group?: string | undefined): token_container
Get container instance, create if it doesn't exist.
If config_group is passed, it overrides the stored group on that container.
Parameters
container_id:string— Unique identifier for the containerconfig_group?:string | undefined— Optional configuration group
Returns
token_container— Container instance
delete_container(container_id: string)
Delete a container and all its tokens
Parameters
container_id:string— Unique identifier for the container
clear_container(container_id: string)
Clear all tokens from a container but keep the container
Parameters
container_id:string— Unique identifier for the container
is_container_exist(container_id: string): boolean
Check if container exists
Parameters
container_id:string
Returns
boolean
register_tokens(tokens: LuaMap<string, token_token_config_data> | Record<string, token_token_config_data> | string, config_group?: string | undefined)
Register tokens in the token system
Call this before token.init() when using a named config group.
Saved containers restore with the config_group stored on their state.
Parameters
tokens:LuaMap<string, token_token_config_data> | Record<string, token_token_config_data> | string— Table mapping token IDs to token config dataconfig_group?:string | undefined— Optional config group (defaults to "default")
register_token_groups(groups: LuaMap<string, LuaMap<string, number> | Record<string, number>> | Record<string, LuaMap<string, number> | Record<string, number>> | string)
Register token groups in the token system
Parameters
groups:LuaMap<string, LuaMap<string, number> | Record<string, number>> | Record<string, LuaMap<string, number> | Record<string, number>> | string— Table mapping group IDs to token IDs and amounts
register_lots(lots_data: LuaMap<string, token_lot> | Record<string, token_lot> | string)
Register lots in the token system
Parameters
lots_data:LuaMap<string, token_lot> | Record<string, token_lot> | string— Table mapping lot IDs to lot config
get_token_group(token_group_id: string): LuaTable<string, number> | undefined
Get a token group by its identifier
Parameters
token_group_id:string— The unique identifier for the token group
Returns
LuaTable<string, number> | undefined— Table mapping token IDs to amounts, or nil if group doesn't exist
get_lot_reward(lot_id: string): LuaTable<string, number> | undefined
Get the reward tokens for a specific lot
Parameters
lot_id:string— Lot id
Returns
LuaTable<string, number> | undefined
get_lot_price(lot_id: string): LuaTable<string, number> | undefined
Get the price tokens for a specific lot
Parameters
lot_id:string— Lot id
Returns
LuaTable<string, number> | undefined
get_token_config(token_id: string): token_token_config_data | undefined
Get token configuration
Parameters
token_id:string— The unique identifier for the token
Returns
token_token_config_data | undefined— The token config, or nil if the token doesn't exist
init(tokens_config_or_path?: LuaMap<string, token_token_config_data> | Record<string, token_token_config_data> | string | undefined, config_group?: string | undefined)
Initialize the token system with token configuration (optional)
Register named config groups with register_tokens(tokens, config_group) before calling init.
Saved containers are restored with the config_group stored on their state; otherwise "default".
Parameters
tokens_config_or_path?:LuaMap<string, token_token_config_data> | Record<string, token_token_config_data> | string | undefined— Lua table with tokens or path to JSON config. Example: "/resources/tokens.json"config_group?:string | undefined— Optional config group (defaults to "default")
update()
Update the token system
Variables
on_token_change: token_event_on_token_change
Triggers when token amount was changed. amount is the new total, delta is the applied change
Callback is fun(container_id: string, token_id: string, amount: number, reason: string|nil, delta: number)
on_token_visual_change: token_event_on_token_visual_change
Triggers when token visual amount was changed. amount is the new visual total, delta is the applied visual change
Callback is fun(container_id: string, token_id: string, amount: number, delta: number)
on_token_restore_change: token_event_on_token_restore_change
Triggers when token restore config was changed Callback is fun(container_id: string, token_id: string, config: token.token_restore_config)
Types
token_config
token_config.tokens: LuaTable<string, LuaTable<string, token_token_config_data>> | undefined
token_config.groups: LuaTable<string, LuaTable<string, number>> | undefined
token_config.lots: LuaTable<string, token_lot> | undefined
token_token_config_data
token_token_config_data.id: string | undefined
Token id, Autofill
token_token_config_data.default: number | undefined
Default: 0
token_token_config_data.min: number | undefined
Default: -math.huge
token_token_config_data.max: number | undefined
Default: math.huge
token_lot
token_lot.price: string
Group id
token_lot.reward: string
Group id
token_container
token_container.set_config_group(config_group: string)
Switch config group on an existing container. Amounts stay; min/max/default come from the new group.
Parameters
config_group:string
token_container.token(token_id: string | token_token_config_data): token_value
Get token instance
Parameters
token_id:string | token_token_config_data
Returns
token_value
token_container.get_state_data(): token_container_data
Get container state data For internal use only by token module plugins (restore/infinity)
Returns
token_container_data
token_container.add(token_id: string | token_token_config_data, amount: number, reason?: string | undefined, visual_later?: boolean | undefined): number
Add tokens to the container
Parameters
token_id:string | token_token_config_dataamount:numberreason?:string | undefinedvisual_later?:boolean | undefined
Returns
number— New token amount
token_container.set(token_id: string | token_token_config_data, amount: number, reason?: string | undefined, visual_later?: boolean | undefined): number
Set token amount in the container
Parameters
token_id:string | token_token_config_dataamount:numberreason?:string | undefinedvisual_later?:boolean | undefined
Returns
number— New token amount
token_container.get(token_id: string | token_token_config_data): number
Get token amount from the container
Parameters
token_id:string | token_token_config_data
Returns
number
token_container.pay(token_id: string, amount: number, reason?: string | undefined, visual_later?: boolean | undefined): boolean
Pay (subtract) tokens from the container
Parameters
token_id:stringamount:numberreason?:string | undefinedvisual_later?:boolean | undefined
Returns
boolean— True if payment was successful
token_container.is_enough(token_id: string, amount: number): boolean
Check if container has enough tokens
Parameters
token_id:stringamount:number
Returns
boolean
token_container.is_empty(token_id: string): boolean
Check if token is empty (zero)
Parameters
token_id:string
Returns
boolean
token_container.is_max(token_id: string): boolean
Check if token is at maximum value
Parameters
token_id:string
Returns
boolean
token_container.add_many(tokens?: LuaMap<string, number> | Record<string, number> | undefined, reason?: string | undefined, visual_later?: boolean | undefined)
Add multiple tokens to the container
Parameters
tokens?:LuaMap<string, number> | Record<string, number> | undefinedreason?:string | undefinedvisual_later?:boolean | undefined
token_container.set_many(tokens?: LuaMap<string, number> | Record<string, number> | undefined, reason?: string | undefined, visual_later?: boolean | undefined)
Set multiple tokens in the container
Parameters
tokens?:LuaMap<string, number> | Record<string, number> | undefinedreason?:string | undefinedvisual_later?:boolean | undefined
token_container.pay_many(tokens: LuaMap<string, number> | Record<string, number>, reason?: string | undefined, visual_later?: boolean | undefined): boolean
Pay multiple tokens from the container
Parameters
tokens:LuaMap<string, number> | Record<string, number>reason?:string | undefinedvisual_later?:boolean | undefined
Returns
boolean— True if all payments were successful
token_container.is_enough_many(tokens?: LuaMap<string, number> | Record<string, number> | undefined): boolean
Check if container has enough of multiple tokens
Parameters
tokens?:LuaMap<string, number> | Record<string, number> | undefined
Returns
boolean
token_container.get_many(): LuaTable<string, number>
Get all tokens from the container
Returns
LuaTable<string, number>
token_container.sync_visual(token_id: string): number
Sync visual debt for a token
Parameters
token_id:string
Returns
number— The visual debt that was synced
token_container.add_visual(token_id: string, amount: number): number
Add visual debt to a token
Parameters
token_id:stringamount:number
Returns
number— The new visual value
token_container.get_visual(token_id: string): number
Get visual value of a token
Parameters
token_id:string
Returns
number
token_container.get_total_sum(token_id: string): number
Get total sum for a token
Parameters
token_id:string
Returns
number
token_container.get_token_config(token_id: string): token_token_config_data
Get token configuration
Parameters
token_id:string
Returns
token_token_config_data
token_container.add_group(group_id: string, reason?: string | undefined, visual_later?: boolean | undefined)
Add tokens from a token group to container
Parameters
group_id:string— Token group idreason?:string | undefined— Optional reason for trackingvisual_later?:boolean | undefined— If true, visual update will be delayed
token_container.set_group(group_id: string, reason?: string | undefined, visual_later?: boolean | undefined)
Set tokens in container to match a token group
Parameters
group_id:string— Token group idreason?:string | undefined— Optional reason for trackingvisual_later?:boolean | undefined— If true, visual update will be delayed
token_container.pay_group(group_id: string, reason?: string | undefined, visual_later?: boolean | undefined): boolean
Pay tokens from container using a token group as cost
Parameters
group_id:string— Token group idreason?:string | undefined— Optional reason for trackingvisual_later?:boolean | undefined— If true, visual update will be delayed
Returns
boolean— True if payment was successful, false otherwise
token_container.is_enough_group(group_id: string): boolean
Check if container has enough tokens to pay for a token group
Parameters
group_id:string— Token group id
Returns
boolean— True if enough tokens are available, false otherwise
token_container.id: string
Container unique identifier
token_container.config_group: string | undefined
Configuration group name
token_container._state_data: token_container_data
Reference to state data
token_container._tokens: LuaTable<string, token_value>
Runtime token instances
token_container.on_token_change: token_container_event_on_token_change
Per-container change event. Callback: fun(token_id: string, amount: number, reason: string|nil, delta: number)
token_container.on_token_visual_change: token_container_event_on_token_visual_change
Per-container visual change event. Callback: fun(token_id: string, amount: number, delta: number)
token_container.on_token_restore_change: event
Per-container restore change event
token_logger
token_logger.trace: (_: unknown, msg: string, data: unknown) => void
token_logger.debug: (_: unknown, msg: string, data: unknown) => void
token_logger.info: (_: unknown, msg: string, data: unknown) => void
token_logger.warn: (_: unknown, msg: string, data: unknown) => void
token_logger.error: (_: unknown, msg: string, data: unknown) => void
token_token_restore_config
token_token_restore_config.is_enabled: boolean
token_token_restore_config.last_restore_time: number
Last restore time in seconds since epoch
token_token_restore_config.disabled_time: number | undefined
token_token_restore_config.timer: number
Timer in seconds for restore
token_token_restore_config.value: number
Value for restore per timer
token_token_restore_config.max: number | undefined
Cap on total value (restore never exceeds this) and max gain per offline batch. Nil means no limit
token_token_restore_config.was_at_restore_max: boolean | undefined
Internal: true when last update saw value >= max (used to reset timer when dropping below max)
token_token_restore_param
token_token_restore_param.timer: number
Timer in seconds for restore
token_token_restore_param.value: number | undefined
Value for restore per timer. Default is 1
token_token_restore_param.max: number | undefined
Cap on total value and max gain per offline batch. Nil means no limit
token_state
token_state.containers: LuaTable<string, token_container_data>
token_container_data
token_container_data.tokens: LuaTable<string, number>
Table of token amounts
token_container_data.history: LuaTable<string, number> | undefined
Table of token total sums
token_container_data.restore_config: LuaTable<string, token_token_restore_config> | undefined
Restore config
token_container_data.infinity_timers: LuaTable<string, number> | undefined
token_container_data.config_group: string | undefined
Configuration group used by this container
token_value
token_value.set(value: number, reason?: string | undefined, visual_later?: boolean | undefined): number
Set token value
Parameters
value:number— New valuereason?:string | undefined— Optional reason for trackingvisual_later?:boolean | undefined— If true, visual update will be delayed
Returns
number— The new value after applying min/max constraints
token_value.get(): number
Get current token value
Returns
number
token_value.add(value: number, reason?: string | undefined, visual_later?: boolean | undefined): number
Add to token value
Parameters
value:number— Amount to addreason?:string | undefined— Optional reason for trackingvisual_later?:boolean | undefined— If true, visual update will be delayed
Returns
number— The new value
token_value.check(value: number): boolean
Check if token has enough value
Parameters
value:number— Amount to check
Returns
boolean
token_value.pay(value: number, reason?: string | undefined, visual_later?: boolean | undefined): boolean
Pay (subtract) value from token
Parameters
value:number— Amount to payreason?:string | undefined— Optional reason for trackingvisual_later?:boolean | undefined— If true, visual update will be delayed
Returns
boolean— True if payment was successful, false otherwise
token_value.sync_visual(): number
Sync visual debt with actual value
Returns
number— The visual debt that was synced
token_value.add_visual(value: number): number
Add visual debt to token
Parameters
value:number— Amount to add (positive shows more, negative shows less)
Returns
number— The new visual value
token_value.get_visual(): number
Get visual value (actual value - visual debt)
Returns
number
token_value.get_total_sum(): number
Get total sum (all tokens ever accumulated)
Returns
number
token_value.set_max()
Set token to maximum value
token_value.on_change(callback: (token: token_value, delta: number, reason: string | undefined) => void)
Register callback for value changes
Parameters
callback:(token: token_value, delta: number, reason: string | undefined) => void
token_value.on_visual_change(callback: (token: token_value, delta: number) => void)
Register callback for visual changes
Parameters
callback:(token: token_value, delta: number) => void
token_value.get_token_id(): string | undefined
Get token id from config
Returns
string | undefined
token_value.amount: number
Current token amount
token_value.total_sum: number
Total accumulated amount (never decreases)
token_value.visual_credit: number
Visual debt amount
token_value.config: token_token_config_data
Token configuration
token_value._on_change_callbacks: ((...args: any[]) => unknown)[] | undefined
Callbacks for value changes
token_value._on_visual_change_callbacks: ((...args: any[]) => unknown)[] | undefined
Callbacks for visual changes