Idles - Systems Architecture Report

Scope Covered

This report covers all tracked files in the repository (62 total at time of analysis), including:

1. Project configuration.
2. Core runtime scripts.
3. Gameplay/economy systems.
4. Goal/unlock systems.
5. UI adapter scripts and scenes.
6. Data resources (.tres).
7. Technical docs and metadata/import files.

The focus below is on behavior-bearing files and how they interact.

Architecture Summary

1. Global startup and singleton wiring is defined in project.godot.
2. Two autoload services power the runtime: CurrencyDatabase and GameState.
3. BigNumber is the numeric backbone used by currency amounts, costs, goals, production, and persistence.
4. Generator behavior is runtime-driven by CurrencyGenerator, parameterized by CurrencyGeneratorData and GeneratorBuffData resources.
5. Goal-based progression uses reusable goal primitives (GoalData, GoalRequirementData) directly on generator data (CurrencyGeneratorData.unlock_goal).
6. UI scripts are thin adapters listening to GameState signals.

Core Systems

1) Numeric System (BigNumber)

File: core/big_number.gd

BigNumber stores values as mantissa + exponent (scientific notation style), normalizes them, and provides:

1. Arithmetic operations (add, subtract, multiply, divide).
2. In-place fast accumulation (add_in_place) for frame-loop performance.
3. Safe comparisons (compare_to, is_greater_than, etc.).
4. Ratio conversion for progress UI (get_ratio).
5. Display formatting (to_string_sci, to_string_suffix).
6. JSON-friendly serialization/deserialization.

This class is used everywhere currency values move.

2) Currency Catalog System

Files: core/currency/currency.gd, core/currency_database.gd, idles/currencies/*.tres

CurrencyDatabase scans res://idles/currencies, loads typed Currency resources, normalizes IDs, and resolves names/icons.

Current data assets:

1. idles/currencies/magic.tres (id = magic).
2. idles/currencies/knowledge.tres (id = knowledge).

This creates a data-driven currency catalog that GameState, goals, and UI can query consistently.

3) Global State + Persistence (GameState)

File: core/game_state.gd

GameState is the central state authority and signal bus.

It owns:

1. Current currency map by currency ID.
2. Total acquired currency map by currency ID.
3. Generator states (owned, purchased_count, unlocked, available).
4. Generator buff levels.
5. Generator buff unlocked flags.
6. last_save_time.

Important signals:

1. currency_changed.
2. generator_state_changed.
3. generator_buff_level_changed.
4. generator_buff_unlocked_changed.

Persistence:

1. Save path: user://idle_save.json.
2. Save payload includes currencies, generator states, buff levels, buff unlocked map, and timestamp.
3. Load path includes defensive sanitization and backward-compatible defaulting.

4) Generator Economy Runtime

Files: core/generator/currency_generator.gd, core/generator/currency_generator_data.gd, core/generator/currency_generator.tscn

CurrencyGenerator implements active gameplay behavior:

1. Auto production cycles (_process, cycle accumulation).
2. Click/hover grants with cooldown.
3. Buy-one and buy-max generator purchases.
4. Buff purchase logic and buff effect application.
5. State registration and lookup through GameState.

CurrencyGeneratorData provides formulas and tuning knobs:

1. Exponential cost growth.
2. Bulk-buy geometric cost.
3. Max-affordable estimate.
4. Milestone multipliers.
5. Purchased-count multiplier.
6. Production/cycle and production/second helpers.
7. ROI-like helpers (payback_seconds, income_to_cost_ratio).
8. Optional generator unlock goal (unlock_goal).

5) Buff System

Files: core/generator/generator_buff_data.gd, idles/buffs/*.tres

Buff kinds:

1. Auto production multiplier.
2. Manual click multiplier.
3. Resource purchase (instant grant on buff buy).

Each buff resource defines:

1. Unlock rules (unlocked and optional unlock_goal).
2. Effect scaling (base_effect, effect_increment).
3. Cost scaling (base_cost, cost_multiplier).
4. Optional target currency and resource grant scaling.

6) Goals and Unlock Progression

Files:

1. core/goals/goal_requirement_data.gd
2. core/goals/goal_data.gd
3. core/generator/currency_generator_data.gd
4. core/generator/currency_generator.gd
5. idles/goals/*.tres

Key behavior:

1. Goal requirements validate currency + target amount.
2. Requirement completion checks total acquired currency, not current wallet.
3. Each CurrencyGenerator evaluates its own data.unlock_goal on startup and on currency_changed.
4. If the goal is met, it sets both unlocked = true and available = true, then emits goal_achieved(generator_id, goal_id).

7) UI Adapter Layer

Files:

1. generator_container.gd + generator_container.tscn.
2. generator_buff_tile.gd + generator_buff_tile.tscn.
3. currency_label.gd + currency_tile.tscn.
4. big_number_progress_bar.gd + big_number_progress_bar.tscn.
5. core/generator-unlock-goals/goals_debug_ui.gd + .tscn.

These scripts primarily:

1. Subscribe to GameState and generator signals.
2. Convert runtime values to UI strings/states.
3. Trigger user actions (buy generator, buy buff, debug unlock).

The architecture is mostly event-driven and avoids polling for state refresh.

Scene Composition

Active Gameplay Prototype

File: docs/museums/generator_museum.tscn

It composes:

1. MagicGenerator instance.
2. KnowledgeGenerator instance (initially hidden and starts locked via data).
3. Currency tiles for magic and knowledge.
4. Goals debug UI panel.

Legacy/Secondary Museum

Files: docs/museums/big_number_museum.tscn, docs/museums/big_number_museum.gd

This appears to be an older/placeholder scene and not the current gameplay focus.

Data-Driven Content Snapshot

Generators

1. primary_generator.tres: Magic Orb, active from start, includes 3 buffs.
2. secondary_generator.tres: Library, starts locked/unavailable and unlocks via magic_total_30 goal.

Buffs (Magic)

1. magic_auto_flux.tres: auto-production buff, unlocked by default.
2. magic_click_focus.tres: manual-click buff.
3. magic_supply_cache.tres: resource-purchase buff.

Goals

1. magic_total_30.tres: reach total magic 30.
2. magic_total_1300.tres: reach total magic 1300.

End-to-End Runtime Flow

1. project.godot autoloads CurrencyDatabase and GameState.
2. CurrencyDatabase builds currency catalog from idles/currencies.
3. GameState initializes per-currency maps and loads save data.
4. Scene nodes initialize and connect to GameState and local gameplay signals.
5. Generators produce currency automatically and via click/hover paths.
6. Currency updates emit currency_changed and drive UI refresh + unlock checks.
7. Goal unlock evaluator may transition generator state to unlocked/available.
8. Generator and buff purchases route all balance/state mutations through GameState.

Signal Guide (Emitters and Listeners)

Custom Gameplay Signals

Signal	Declared In	Emitted By	Emitted When	Listeners
currency_changed(currency_id, new_amount)	core/game_state.gd	GameState.add_currency_by_id, GameState.spend_currency_by_id	Any currency balance increases/decreases	CurrencyGenerator._on_currency_changed, GeneratorPanel._on_currency_changed, CurrencyTile._on_currency_changed, BigNumberProgressBar._on_currency_changed, GoalsDebugUI._on_currency_changed
generator_state_changed(generator_id, state)	core/game_state.gd	GameState.register_generator, GameState._set_generator_state	Generator state created or changed (owned, purchased_count, unlocked, available)	CurrencyGenerator._on_generated_state_changed, GeneratorPanel._on_generator_state_changed, GoalsDebugUI._on_generator_state_changed
generator_buff_level_changed(generator_id, buff_id, new_level)	core/game_state.gd	GameState.register_generator_buff, GameState.set_generator_buff_level	Buff level created/sanitized/updated	GeneratorPanel._on_generator_buff_level_changed
generator_buff_unlocked_changed(generator_id, buff_id, unlocked)	core/game_state.gd	GameState.register_generator_buff_unlocked, GameState.set_generator_buff_unlocked	Buff unlock state created/sanitized/updated	GeneratorPanel._on_generator_buff_unlocked_changed
purchase_completed(amount, total_owned, total_purchased, total_cost)	core/generator/currency_generator.gd	CurrencyGenerator.buy	Generator purchase succeeds	GeneratorPanel._on_generator_updated
purchase_failed(requested_amount, required_cost, available_currency)	core/generator/currency_generator.gd	CurrencyGenerator.buy	Generator purchase fails for insufficient funds	GeneratorPanel._on_generator_updated
production_tick(amount, cycle_count, total_owned)	core/generator/currency_generator.gd	CurrencyGenerator._grant_cycle_income	One or more automatic production cycles complete	GeneratorPanel._on_generator_updated
buff_purchased(buff_id, new_level, cost, cost_currency_id)	core/generator/currency_generator.gd	CurrencyGenerator.buy_buff	Buff purchase succeeds	GeneratorPanel._on_generator_updated
buff_purchase_failed(buff_id, required_cost, cost_currency_id)	core/generator/currency_generator.gd	CurrencyGenerator.buy_buff	Buff purchase fails for insufficient funds	GeneratorPanel._on_generator_updated
goal_achieved(generator_id, goal_id)	core/generator/currency_generator.gd	CurrencyGenerator._evaluate_generator_unlock_goal	Generator unlock goal transitions that generator to unlocked+available	None currently (available for gameplay/UI hooks)
buy_pressed(buff_id)	generator_buff_tile.gd	GeneratorBuffTile._on_buy_button_pressed	User presses buff buy button in a buff row	GeneratorPanel._on_buy_buff_pressed

Built-In Godot Signals Wired In This Project

Source Signal	Connected In	Listener Method	Purpose
Area2D.mouse_entered	core/generator/currency_generator.tscn	CurrencyGenerator._on_area_2d_mouse_entered	Enter generator hover zone; mark hover true and show generator panel
Area2D.mouse_exited	core/generator/currency_generator.tscn	CurrencyGenerator._on_area_2d_mouse_exited	Exit generator hover zone; mark hover false and hide generator panel
BuyOneButton.pressed	generator_container.tscn	GeneratorPanel._on_buy_pressed	Buy one generator
BuyMaxButton.pressed	generator_container.tscn	GeneratorPanel._on_buy_max_pressed	Buy max affordable generators
GeneratorContainer.mouse_entered	generator_container.tscn	GeneratorPanel._on_mouse_entered	Intended hover hook on panel container (method currently missing)
GeneratorContainer.mouse_exited	generator_container.tscn	GeneratorPanel._on_mouse_exited	Intended hover hook on panel container (method currently missing)
BuyButton.pressed	generator_buff_tile.tscn	GeneratorBuffTile._on_buy_button_pressed	Emit tile-level buy_pressed custom signal
DebugIncomeButton.pressed	currency_tile.tscn	CurrencyTile._on_debug_income_button_pressed	Add debug income to the tile currency
Button.pressed (runtime-created unlock button)	core/generator-unlock-goals/goals_debug_ui.gd	GoalsDebugUI._on_unlock_pressed (bound with goal id)	Manual debug unlock when a goal is ready

Common Signal Chains

1. Currency gain/spend chain: generator or debug action mutates GameState currency, GameState emits currency_changed, UI widgets and unlock systems recompute and redraw.
2. Generator purchase chain: panel button triggers CurrencyGenerator.buy, generator updates GameState state, generator emits purchase signal, panel refreshes stats and buttons.
3. Buff purchase chain: buff tile emits buy_pressed, panel calls CurrencyGenerator.buy_buff, generator updates buff level/unlock and optionally grants currency, GameState emits buff/currency/state signals, panel and other listeners refresh.
4. Goal unlock chain: currency_changed triggers generator-local unlock evaluator, evaluator sets generator unlocked/available, emits goal_achieved(generator_id, goal_id), GameState emits generator_state_changed, generator and UI become interactable/visible.

Key Findings and Risks

1. project.godot has no explicit run/main_scene entry, so startup scene is not pinned in tracked config.
2. Save/load is only partially wired: load_game() runs at startup, but save_game() is not invoked anywhere else in the repository.
3. currency_label.gd and big_number_progress_bar.gd reference GameState.GOLD_CURRENCY_ID, but that constant does not exist in core/game_state.gd.
4. generator_container.tscn connects mouse_entered/mouse_exited to methods that do not exist in generator_container.gd.
5. Generator unlock goals now assume the target generator exists in-scene and owns its own unlock_goal.
6. KnowledgeGenerator visibility logic may be inconsistent because currency_generator.gd sets visible = true whenever its generator state changes.
7. Two buffs are configured locked with no unlock-goal path, so they remain permanently inaccessible under current logic.
8. core/generator-unlock-goals/TECH_SPEC.md contains some outdated assumptions relative to current .tres-based implementation.

Additional Notes

1. .uid files are identity metadata used by Godot and contain no runtime logic.
2. icon.svg and icon.svg.import are standard icon/import metadata.
3. Root config files (.editorconfig, .gitattributes, .gitignore) are minimal and conventional.