# 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