85 lines
2.1 KiB
Markdown
85 lines
2.1 KiB
Markdown
# 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
|
|
|
|
```gdscript
|
|
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
|
|
|
|
```gdscript
|
|
# Get all known currencies
|
|
var currencies: Array[Currency] = CurrencyDatabase.get_known_currencies()
|
|
|
|
# Get currency by ID
|
|
var gold: Currency = CurrencyDatabase.get_currency_resource(&"gold")
|
|
|
|
# Check if currency exists
|
|
var is_valid: bool = CurrencyDatabase.is_known_currency_id(&"gems")
|
|
|
|
# Get display name
|
|
var name: String = CurrencyDatabase.get_currency_name(&"gold")
|
|
```
|
|
|
|
## Integration with GameState
|
|
|
|
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)
|
|
|
|
```gdscript
|
|
# Add currency
|
|
GameState.add_currency(gold_resource, BigNumber.new(100.0, 0))
|
|
|
|
# Get balance
|
|
var balance: BigNumber = GameState.get_currency_amount_by_id(&"gold")
|
|
|
|
# Spend currency (returns false if insufficient)
|
|
var success: bool = GameState.spend_currency_by_id(&"gold", BigNumber.new(50.0, 0))
|
|
```
|
|
|
|
## Auto-Discovery
|
|
|
|
`CurrencyDatabase` automatically scans `res://sandbox/currencies/` for `.tres` and `.res` files on startup.
|
|
|
|
## See Also
|
|
|
|
- `core/game_state.gd` - Currency state management
|
|
- `core/big_number.gd` - Large number handling
|
|
- `generator/currency_generator_data.gd` - Generator purchase currency
|