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) plus unlock bindings (GeneratorUnlockGoalData) and runtime evaluator (generator_unlock_system.gd).
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).

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-unlock-goals/generator_unlock_goal_data.gd
4. core/generator-unlock-goals/generator_unlock_system.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. Unlock system evaluates goals on currency change and generator state changes.
4. If a goal is met and target generator is resolvable, it sets both unlocked = true and available = true.

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.
5. Runtime GeneratorUnlockSystem node with configured unlock goals.

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.

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.
3. generator_unlock_knowledge.tres: maps magic_total_30 to generator Knowledge.
4. generator_unlock_wood.tres: maps magic_total_1300 to generator Wood.

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, GeneratorUnlockSystem._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, GeneratorUnlockSystem._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(goal_id, target_generator_id)	core/generator-unlock-goals/generator_unlock_system.gd	GeneratorUnlockSystem._evaluate_goal	Unlock goal transitions target 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 unlock evaluator, evaluator sets generator unlocked/available, emits goal_achieved(goal_id, target_generator_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_wood.tres targets generator ID Wood, but no generator with that ID appears in current runtime scene/content, so this goal is currently non-functional.
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.