Add docs

core/currency/README.md

@@ -0,0 +1,84 @@
+# 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