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_catalogue.gd	Catalog system for all in-game currencies
LevelGameState	core/level_game_state.gd	Central state authority (currencies, generators, buffs, persistence, research)
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
Research	core/research/	XP-based progression with production multipliers

Key Nodes

Node	Script	Description
LevelGameState	core/level_game_state.gd	Central state management, save/load
CurrencyCatalogue	core/currency_catalogue.gd	Currency catalog resource
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 5 (current):

{
  "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": { ... },
  "buff_levels": { "farm_flux": 5 },
  "buff_unlocked": { "farm_flux": true },
  "buff_active": { "farm_flux": true },
  "goals": { "completed": ["goal_id"] },
  "research_xp": { "<research_id>": {"m": float, "e": int} },
  "research_levels": { "<research_id>": int },
  "last_save_time": 1234567890
}

Note: Save format version 5 includes research XP as BigNumber serialization.

Development

Adding New Content

New Currency:

1. Create res://sandbox/currencies/<name>.tres (Currency resource)
2. Set id, display_name, icon
3. Add to CurrencyCatalogue resource

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. Add to BuffCatalogue resource

New Research:

1. Create res://sandbox/research/<name>.tres (ResearchData)
2. Link to generator via generator_id
3. Configure XP and multiplier parameters
4. Add to ResearchCatalogue resource

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)
• GeneratorPanel has missing mouse_entered/mouse_exited handlers
• Some buffs configured locked with no unlock path
• No automated test suite

Current Status

Research system fully implemented with:

• XP-based progression tied to production
• Auto-leveling with BigNumber support
• Buff multipliers for XP gain
• Save format version 5 with research persistence

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