Add docs

2026-04-04 16:04:51 +02:00
parent eaa8f18a4a
commit cd23125739
9 changed files with 870 additions and 7 deletions
--- a/core/README.md
+++ b/core/README.md
@@ -0,0 +1,117 @@
+# 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**: `GameState` autoload for all persistent state
+- **Currency System**: Database 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
+
+## Architecture
+
+```
+core/
+├── big_number.gd           # Core numeric API
+├── game_state.gd           # Main state management autoload
+├── buff_database.gd        # Buff registration system
+├── currency_database.gd    # Currency registration system
+├── currency/               # Currency data structures
+├── generator/              # Generator logic and data
+├── goals/                  # Goal/achievement system
+└── prestige/               # Prestige/rebirth system
+```
+
+## Data Flow
+
+1. **Game Start**: `GameState._ready()` initializes currencies, loads save
+2. **Player Action**: Generator bought → `GameState` updated → signals emitted
+3. **UI Reaction**: Listeners respond to signals → update display
+4. **Goal Check**: Currency changed → goals evaluated → buffs unlocked
+5. **Save**: `GameState.save_game()` → JSON to `user://idle_save.json`
+
+## Save Format
+
+**Version**: 3
+
+```json
+{
+  "save_format_version": 3,
+  "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>", ...]
+  },
+  "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. Auto-discovered by `CurrencyDatabase`
+
+### 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. Auto-discovered by `BuffDatabase`
+
+## See Also
+
+- `currency/` - Currency data structures
+- `generator/` - Generator production system
+- `goals/` - Achievement system
+- `prestige/` - Rebirth mechanics