idle/core

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: LevelGameState for all persistent state
• Currency System: CurrencyCatalogue 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
• Research System: XP-based progression with production multipliers

Architecture

core/
├── big_number.gd           # Core numeric API
├── level_game_state.gd     # Main state management (Node)
├── currency/               # Currency data structures + CurrencyCatalogue
├── currency_catalogue.gd   # Currency catalogue resource
├── buff_catalogue.gd       # Buff catalogue resource
├── goal_catalogue.gd       # Goal catalogue resource
├── generator/              # Generator logic and data
├── goals/                  # Goal/achievement system
├── prestige/               # Prestige/rebirth system
└── research/               # Research XP and progression

Data Flow

1. Game Start: LevelGameState._ready() initializes currencies, loads save
2. Player Action: Generator bought → LevelGameState updated → signals emitted
3. UI Reaction: Listeners respond to signals → update display
4. Goal Check: Currency changed → goals evaluated → buffs unlocked
5. Save: LevelGameState.save_game() → JSON to user://level_save.json

Save Format

Version: 5

{
  "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": {
    "<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>", ...]
  },
  "research_xp": {
    "<research_id>": {"m": float, "e": int}
  },
  "research_levels": {
    "<research_id>": int
  },
  "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:

# 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. Add to CurrencyCatalogue resource assigned to LevelGameState

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

Adding New Research

1. Create res://sandbox/research/<name>.tres extending ResearchData
2. Link to a generator via generator_id
3. Add to ResearchCatalogue resource assigned to LevelGameState

See Also

• currency/ - Currency data structures
• generator/ - Generator production system
• goals/ - Achievement system
• prestige/ - Rebirth mechanics