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

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

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

# 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