idle/core/currency

Currency Module Documentation

Overview

The currency/ subfolder contains the data structure for defining in-game currencies.

Files

currency.gd

Defines the Currency class - a Resource for currency metadata.

Currency Class

class_name Currency
extends Resource

@export var id: StringName = &""          # Unique identifier (e.g., &"gold")
@export var display_name: String = ""     # UI-friendly name
@export var icon: Texture2D               # Display icon

Usage

Defining a Currency

Create a .tres resource file with:

• id: Lowercase unique key (used internally)
• display_name: What players see ("Gold", "Gems")
• icon: Texture for UI display

Example res://sandbox/currencies/gold.tres:

[gd_resource type="Resource" script_class="Currency"]
[resource]
id = &"gold"
display_name = "Gold"
icon = ExtResource("uid://...")

Accessing Currencies

Currencies are defined in a CurrencyCatalogue resource that holds an array of Currency resources.

# Get all known currency IDs from the catalogue
var ids: Array[StringName] = currency_catalogue.get_all_ids()

# Get currency resource by ID
var gold: Currency = currency_catalogue.get_currency_by_id(&"gold")

Integration with LevelGameState

Currencies are tracked in three ways:

1. current: Current balance (resets on prestige)
2. total: Total acquired this run (resets on prestige)
3. all_time: Lifetime total (never resets)

# Add currency
level_game_state.add_currency(gold_resource, BigNumber.new(100.0, 0))

# Add by ID
level_game_state.add_currency_by_id(&"gold", BigNumber.new(100.0, 0))

# Get balance
var balance: BigNumber = level_game_state.get_currency_amount_by_id(&"gold")

# Spend currency (returns false if insufficient)
var success: bool = level_game_state.spend_currency_by_id(&"gold", BigNumber.new(50.0, 0))

# Check if currency exists
var is_valid: bool = level_game_state.is_known_currency_id(&"gems")

# Get currency resource
var gold: Currency = level_game_state.get_currency_resource(&"gold")

# Get display name
var name: String = level_game_state.get_currency_name(&"gold")

CurrencyCatalogue Class

class_name CurrencyCatalogue
extends Resource

@export var currencies: Array[Currency] = []

func get_currency_by_id(id: StringName) -> Currency
func get_all_ids() -> Array[StringName]

The CurrencyCatalogue is a resource that holds all defined currencies and is assigned to LevelGameState via the currency_catalogue export variable.

Signals

LevelGameState emits currency_changed(currency_id: StringName, new_amount: BigNumber) whenever a currency balance changes.

See Also

• core/level_game_state.gd - Currency state management
• core/big_number.gd - Large number handling
• core/currency/currency_catalogue.gd - Currency catalogue resource
• core/generator/currency_generator_data.gd - Generator purchase currency

/home/mikymod/work/jmp/idle/core/currency/README.md