# 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):

GameState.register_generator_buff(generator_id, buff_id, level)
GameState.get_generator_buff_level(generator_id, buff_id)

New API (global buff state):

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):

{
  "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:

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

New Generator:

Create res://sandbox/generators/<name>.tres (CurrencyGeneratorData)
Configure production stats, costs, purchase currency
Optionally add unlock_goal
Add CurrencyGenerator node to scene

New Buff:

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

Testing

# 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