idle/README.md

# Idles - Godot 4.6 Idle Game

A modular idle/incremental game prototype featuring a decoupled buff system, multi-target buffs with wildcard support, and goal-based progression.

## Quick Start

```bash
# Run the project
"$GODOT_BIN" --path .

# Headless mode (lint/smoke test)
"$GODOT_BIN" --headless --path . --quit

# Check single script syntax
"$GODOT_BIN" --headless --check-only --script res://core/big_number.gd
```

## Architecture Overview

### Core Systems

| System | Location | Purpose |
|--------|----------|---------|
| **BigNumber** | `core/big_number.gd` | Handles huge numbers (mantissa + exponent) for idle game math |
| **Currency** | `core/currency/`, `core/currency_database.gd` | Catalog system for all in-game currencies |
| **GameState** | `core/game_state.gd` | Central state authority (currencies, generators, buffs, persistence) |
| **Generators** | `core/generator/` | Production mechanics (auto cycles, clicks, purchases) |
| **Buffs** | `core/generator/generator_buff_data.gd` | Global multipliers with multi-target support |
| **Goals** | `core/goals/` | Unlock conditions for generators and buffs |
| **Prestige** | `core/prestige/` | Reset-with-bonus mechanics |

### Autoload Singletons

| Autoload | Script | Description |
|----------|--------|-------------|
| `GameState` | `core/game_state.gd` | Central state management, save/load |
| `CurrencyDatabase` | `core/currency_database.gd` | Currency catalog discovery |
| `PrestigeManager` | `core/prestige/prestige_manager.gd` | Prestige system |

### Data Directory Structure

```
sandbox/
├── currencies/    # Currency resources (gold, food, wood, worker, etc.)
├── generators/    # Generator configuration (.tres files)
├── buffs/         # Buff definitions with target_ids
├── goals/         # Unlock goal definitions
└── prestige/      # Prestige configuration
```

## Current Architecture (Post-Refactoring)

### Decoupled Buff System

Buffs are now **globally registered** and **multi-target capable**:

- **Global Levels**: Buff levels are shared across all targets
- **Multi-Target**: A single buff resource can affect multiple generators
- **Wildcards**: `target_ids: ["*"]` applies to all current + future generators
- **Auto-Discovery**: Buffs loaded from `res://sandbox/buffs/` at runtime
- **Goal-Based Activation**: Buffs unlock automatically when goals are met

### Key Design Decisions

| Feature | Implementation |
|---------|----------------|
| **Buff Levels** | Global (shared across all targets) |
| **Buff Registry** | Auto-discovered from `res://sandbox/buffs/` |
| **Wildcards** | `["*"]` matches all current AND future generators |
| **Default State** | Inactive until goal met |
| **Persistence** | Buff definitions serialized to save |
| **Prestige** | All buff levels reset to 0 |
| **Activation** | Automatic via goals, no manual toggle |

### API Changes

**Old API (per-generator state):**
```gdscript
GameState.register_generator_buff(generator_id, buff_id, level)
GameState.get_generator_buff_level(generator_id, buff_id)
```

**New API (global buff state):**
```gdscript
GameState.register_buff(buff: GeneratorBuffData)
GameState.get_buff(buff_id) -> GeneratorBuffData
GameState.get_buffs_for_generator(generator_id) -> Array[GeneratorBuffData]
GameState.get_effective_multiplier(generator_id, kind) -> float
```

## Save Format

**Version 2 (current):**
```json
{
  "save_format_version": 2,
  "currencies": { ... },
  "generator_states": { ... },
  "buff_definitions": { ... },
  "buff_levels": { "farm_flux": 5 },
  "buff_unlocked": { "farm_flux": true },
  "buff_active": { "farm_flux": true },
  "last_save_time": 1234567890
}
```

**Note**: Breaking change from v1 - old saves are incompatible.

## Development

### Adding New Content

**New Currency:**
1. Create `res://sandbox/currencies/<name>.tres` (Currency resource)
2. Set `id`, `display_name`, `icon`
3. Auto-discovered at runtime

**New Generator:**
1. Create `res://sandbox/generators/<name>.tres` (CurrencyGeneratorData)
2. Configure production stats, costs, purchase currency
3. Optionally add `unlock_goal`
4. Add `CurrencyGenerator` node to scene

**New Buff:**
1. Create `res://sandbox/buffs/<name>.tres` (GeneratorBuffData)
2. Set `target_ids` (e.g., `["farm", "forestry"]` or `["*"]`)
3. Configure effect, cost, unlock goal
4. Auto-registered at runtime

### Testing

```bash
# Run project and test manually
"$GODOT_BIN" --path .

# No automated test framework committed yet
# (GUT not included in repository)
```

## Known Issues / TODOs

- [ ] Manual save triggers not implemented (auto-save needed)
- [ ] `CurrencyTile` references `GameState.GOLD_CURRENCY_ID` (constant missing)
- [ ] `GeneratorPanel` has missing `mouse_entered`/`mouse_exited` handlers
- [ ] Some buffs configured locked with no unlock path
- [ ] No automated test suite

## Refactoring Status

See `REFACTORING.md` for:
- Complete refactoring plan (8 phases)
- Implementation timeline (15-23 hours estimated)
- Testing checklist
- Rollback procedures

### Completed Phases
- Phase 1: GeneratorBuffData with target_ids support

### Pending Phases
- Phase 2-8: GameState extension, save format update, data migration

## Technical Details

### BigNumber System
- **Representation**: Mantissa (float) + Exponent (int)
- **Range**: Handles values up to ~10^308 (float precision limit)
- **Operations**: Add, subtract, multiply, divide, compare
- **Optimization**: `add_in_place()` for performance-critical loops

### Production Formulas
```
Cost for N items: base * ratio^k * ((ratio^n - 1) / (ratio - 1))
Max affordable: log((currency*(ratio-1)/(base*ratio^k)) + 1) / log(ratio)
Production: base_productivity * owned * run_mult * milestone_mult * purchased_mult
```

### Buff Multiplier Stacking
Multiple buffs of the same kind stack **multiplicatively**:
```
total_multiplier = buff1_effect * buff2_effect * buff3_effect * ...
```

## License

Internal prototype - no external license applied.

---

*Last updated: Refactoring plan documented*
*Godot version: 4.6*