132 lines
4.2 KiB
Markdown
132 lines
4.2 KiB
Markdown
# Core Module Documentation
|
|
|
|
## Overview
|
|
|
|
The `core/` directory contains the fundamental systems for the idle game. It provides:
|
|
|
|
- **Numeric Foundation**: `BigNumber` for handling huge idle game values
|
|
- **Game State Management**: `LevelGameState` for all persistent state
|
|
- **Currency System**: `CurrencyCatalogue` and tracking for multiple currency types
|
|
- **Generator System**: Automated resource production with scaling costs
|
|
- **Buff System**: Upgrades that modify generator behavior
|
|
- **Goal System**: Achievement tracking and unlock triggers
|
|
- **Prestige System**: Rebirth mechanics with permanent multipliers
|
|
- **Research System**: XP-based progression with production multipliers
|
|
|
|
## Architecture
|
|
|
|
```
|
|
core/
|
|
├── big_number.gd # Core numeric API
|
|
├── level_game_state.gd # Main state management (Node)
|
|
├── currency/ # Currency data structures + CurrencyCatalogue
|
|
├── currency_catalogue.gd # Currency catalogue resource
|
|
├── buff_catalogue.gd # Buff catalogue resource
|
|
├── goal_catalogue.gd # Goal catalogue resource
|
|
├── generator/ # Generator logic and data
|
|
├── goals/ # Goal/achievement system
|
|
├── prestige/ # Prestige/rebirth system
|
|
└── research/ # Research XP and progression
|
|
```
|
|
|
|
## Data Flow
|
|
|
|
1. **Game Start**: `LevelGameState._ready()` initializes currencies, loads save
|
|
2. **Player Action**: Generator bought → `LevelGameState` updated → signals emitted
|
|
3. **UI Reaction**: Listeners respond to signals → update display
|
|
4. **Goal Check**: Currency changed → goals evaluated → buffs unlocked
|
|
5. **Save**: `LevelGameState.save_game()` → JSON to `user://level_save.json`
|
|
|
|
## Save Format
|
|
|
|
**Version**: 5
|
|
|
|
```json
|
|
{
|
|
"save_format_version": 5,
|
|
"currencies": {
|
|
"<currency_id>": {
|
|
"current": {"m": float, "e": int},
|
|
"total": {"m": float, "e": int},
|
|
"all_time": {"m": float, "e": int}
|
|
}
|
|
},
|
|
"generator_states": {
|
|
"<generator_id>": {
|
|
"owned": int,
|
|
"purchased_count": int,
|
|
"unlocked": bool,
|
|
"available": bool
|
|
}
|
|
},
|
|
"buff_levels": {
|
|
"<buff_id>": int
|
|
},
|
|
"buff_unlocked": {
|
|
"<buff_id>": true
|
|
},
|
|
"buff_active": {
|
|
"<buff_id>": true
|
|
},
|
|
"goals": {
|
|
"completed": ["<goal_id>", ...]
|
|
},
|
|
"research_xp": {
|
|
"<research_id>": {"m": float, "e": int}
|
|
},
|
|
"research_levels": {
|
|
"<research_id>": int
|
|
},
|
|
"last_save_time": unix_timestamp
|
|
}
|
|
```
|
|
|
|
## Key Signals
|
|
|
|
| Signal | Emitted When |
|
|
|--------|--------------|
|
|
| `currency_changed(currency_id, new_amount)` | Any currency balance changes |
|
|
| `generator_state_changed(generator_id, state)` | Generator owned/unlocked changes |
|
|
| `generator_buff_level_changed(gen_id, buff_id, level)` | Buff level increased |
|
|
| `buff_unlocked_changed(buff_id, unlocked)` | Buff unlock state changed |
|
|
| `goal_completed(goal_id)` | Goal criteria met |
|
|
|
|
## BigNumber Serialization
|
|
|
|
All large numbers use scientific notation internally:
|
|
```gdscript
|
|
# Value = mantissa * 10^exponent
|
|
var num = BigNumber.new(1.5, 24) # 1.5e24
|
|
var dict = num.serialize() # {"m": 1.5, "e": 24}
|
|
var restored = BigNumber.deserialize(dict)
|
|
```
|
|
|
|
## Extending the Core
|
|
|
|
### Adding a New Currency
|
|
1. Create `res://sandbox/currencies/<name>.tres` extending `Currency`
|
|
2. Set `id`, `display_name`, and `icon`
|
|
3. Add to `CurrencyCatalogue` resource assigned to `LevelGameState`
|
|
|
|
### Adding a New Generator
|
|
1. Create `res://sandbox/generators/<name>.tres` extending `CurrencyGeneratorData`
|
|
2. Configure costs, production, and unlock goals
|
|
3. Instance `CurrencyGenerator` scene with this data
|
|
|
|
### Adding a New Buff
|
|
1. Create `res://sandbox/buffs/<name>.tres` extending `GeneratorBuffData`
|
|
2. Set `target_ids`, `kind`, `effect_increment`, and `cost`
|
|
3. Add to `BuffCatalogue` resource assigned to `LevelGameState`
|
|
|
|
### Adding New Research
|
|
1. Create `res://sandbox/research/<name>.tres` extending `ResearchData`
|
|
2. Link to a generator via `generator_id`
|
|
3. Add to `ResearchCatalogue` resource assigned to `LevelGameState`
|
|
|
|
## See Also
|
|
|
|
- `currency/` - Currency data structures
|
|
- `generator/` - Generator production system
|
|
- `goals/` - Achievement system
|
|
- `prestige/` - Rebirth mechanics
|