# 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

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

```gdscript
# 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)

```gdscript
# 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

```gdscript
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

</content>
<parameter=filePath>
/home/mikymod/work/jmp/idle/core/currency/README.md