# 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