Michele Rossi
81a4058b04
Decouples core systems from centralized globals in favor of catalogue-based architecture and data-driven content. Key changes: - Prestige: node-based buff tech tree, graph panel, progress bar - Research: multi-worker system, per-generator research, xp generation - Ascension: meta-currency layer via multi-currency prestige resets - Buffs: refactored as generator-independent via catalogues - UI: currency panel, edge-scrolling camera + zoom, current-goal panel - Alchemy Tower: crafting building with recipe/cost system - Testing: 7 test suites (ascension, prestige, research, goals) - Content: migrated from hardcoded idles/ to gym format (tiny_sword)
112 lines
3.0 KiB
Markdown
112 lines
3.0 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
|
|
|
|
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
|