Skip to Content
defold-typescript libraries
Insality

Insality/defold-token/token

The Defold Token module. Used to manage all countable items in the game.

  • GitHub: Insality/defold-token — pinned to 9
    1. 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 — to game.project under [project] dependencies, then Fetch Libraries in the Defold editor.
    2. Run bunx @defold-typescript/cli resolve to materialize its types.
    3. Import it under a namespace alias of your choice:
      import * as token from "token"

Functions

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 container
  • config_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 data
  • config_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_data
  • amount: number
  • reason?: string | undefined
  • visual_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_data
  • amount: number
  • reason?: string | undefined
  • visual_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: string
  • amount: number
  • reason?: string | undefined
  • visual_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: string
  • amount: 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> | undefined
  • reason?: string | undefined
  • visual_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> | undefined
  • reason?: string | undefined
  • visual_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 | undefined
  • visual_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: string
  • amount: 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 id
  • reason?: string | undefined — Optional reason for tracking
  • visual_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 id
  • reason?: string | undefined — Optional reason for tracking
  • visual_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 id
  • reason?: string | undefined — Optional reason for tracking
  • visual_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 value
  • reason?: string | undefined — Optional reason for tracking
  • visual_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 add
  • reason?: string | undefined — Optional reason for tracking
  • visual_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 pay
  • reason?: string | undefined — Optional reason for tracking
  • visual_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

On this page

Functionsreset_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()Variableson_token_change: token_event_on_token_changeon_token_visual_change: token_event_on_token_visual_changeon_token_restore_change: token_event_on_token_restore_changeTypestoken_configtoken_config.tokens: LuaTable<string, LuaTable<string, token_token_config_data>> | undefinedtoken_config.groups: LuaTable<string, LuaTable<string, number>> | undefinedtoken_config.lots: LuaTable<string, token_lot> | undefinedtoken_token_config_datatoken_token_config_data.id: string | undefinedtoken_token_config_data.default: number | undefinedtoken_token_config_data.min: number | undefinedtoken_token_config_data.max: number | undefinedtoken_lottoken_lot.price: stringtoken_lot.reward: stringtoken_containertoken_container.set_config_group(config_group: string)token_container.token(token_id: string | token_token_config_data): token_valuetoken_container.get_state_data(): token_container_datatoken_container.add(token_id: string | token_token_config_data, amount: number, reason?: string | undefined, visual_later?: boolean | undefined): numbertoken_container.set(token_id: string | token_token_config_data, amount: number, reason?: string | undefined, visual_later?: boolean | undefined): numbertoken_container.get(token_id: string | token_token_config_data): numbertoken_container.pay(token_id: string, amount: number, reason?: string | undefined, visual_later?: boolean | undefined): booleantoken_container.is_enough(token_id: string, amount: number): booleantoken_container.is_empty(token_id: string): booleantoken_container.is_max(token_id: string): booleantoken_container.add_many(tokens?: LuaMap<string, number> | Record<string, number> | undefined, reason?: string | undefined, visual_later?: boolean | undefined)token_container.set_many(tokens?: LuaMap<string, number> | Record<string, number> | undefined, reason?: string | undefined, visual_later?: boolean | undefined)token_container.pay_many(tokens: LuaMap<string, number> | Record<string, number>, reason?: string | undefined, visual_later?: boolean | undefined): booleantoken_container.is_enough_many(tokens?: LuaMap<string, number> | Record<string, number> | undefined): booleantoken_container.get_many(): LuaTable<string, number>token_container.sync_visual(token_id: string): numbertoken_container.add_visual(token_id: string, amount: number): numbertoken_container.get_visual(token_id: string): numbertoken_container.get_total_sum(token_id: string): numbertoken_container.get_token_config(token_id: string): token_token_config_datatoken_container.add_group(group_id: string, reason?: string | undefined, visual_later?: boolean | undefined)token_container.set_group(group_id: string, reason?: string | undefined, visual_later?: boolean | undefined)token_container.pay_group(group_id: string, reason?: string | undefined, visual_later?: boolean | undefined): booleantoken_container.is_enough_group(group_id: string): booleantoken_container.id: stringtoken_container.config_group: string | undefinedtoken_container._state_data: token_container_datatoken_container._tokens: LuaTable<string, token_value>token_container.on_token_change: token_container_event_on_token_changetoken_container.on_token_visual_change: token_container_event_on_token_visual_changetoken_container.on_token_restore_change: eventtoken_loggertoken_logger.trace: (_: unknown, msg: string, data: unknown) => voidtoken_logger.debug: (_: unknown, msg: string, data: unknown) => voidtoken_logger.info: (_: unknown, msg: string, data: unknown) => voidtoken_logger.warn: (_: unknown, msg: string, data: unknown) => voidtoken_logger.error: (_: unknown, msg: string, data: unknown) => voidtoken_token_restore_configtoken_token_restore_config.is_enabled: booleantoken_token_restore_config.last_restore_time: numbertoken_token_restore_config.disabled_time: number | undefinedtoken_token_restore_config.timer: numbertoken_token_restore_config.value: numbertoken_token_restore_config.max: number | undefinedtoken_token_restore_config.was_at_restore_max: boolean | undefinedtoken_token_restore_paramtoken_token_restore_param.timer: numbertoken_token_restore_param.value: number | undefinedtoken_token_restore_param.max: number | undefinedtoken_statetoken_state.containers: LuaTable<string, token_container_data>token_container_datatoken_container_data.tokens: LuaTable<string, number>token_container_data.history: LuaTable<string, number> | undefinedtoken_container_data.restore_config: LuaTable<string, token_token_restore_config> | undefinedtoken_container_data.infinity_timers: LuaTable<string, number> | undefinedtoken_container_data.config_group: string | undefinedtoken_valuetoken_value.set(value: number, reason?: string | undefined, visual_later?: boolean | undefined): numbertoken_value.get(): numbertoken_value.add(value: number, reason?: string | undefined, visual_later?: boolean | undefined): numbertoken_value.check(value: number): booleantoken_value.pay(value: number, reason?: string | undefined, visual_later?: boolean | undefined): booleantoken_value.sync_visual(): numbertoken_value.add_visual(value: number): numbertoken_value.get_visual(): numbertoken_value.get_total_sum(): numbertoken_value.set_max()token_value.on_change(callback: (token: token_value, delta: number, reason: string | undefined) => void)token_value.on_visual_change(callback: (token: token_value, delta: number) => void)token_value.get_token_id(): string | undefinedtoken_value.amount: numbertoken_value.total_sum: numbertoken_value.visual_credit: numbertoken_value.config: token_token_config_datatoken_value._on_change_callbacks: ((...args: any[]) => unknown)[] | undefinedtoken_value._on_visual_change_callbacks: ((...args: any[]) => unknown)[] | undefined