godot-genre-idle-clicker

NEVER Do (Expert Anti-Patterns)

Economics & Math

• NEVER use standard floats for currency; strictly implement a BigNumber (Mantissa/Exponent) system (e.g., 1.5e300) to prevent INF crashes at 1e308.
• NEVER use Timer nodes for revenue generation; strictly use a manual accumulator in _process(delta) to prevent drift during frame fluctuations.
• NEVER hardcode generator costs or growth; strictly use an exponential formula: Cost = BasePrice * pow(GrowthFactor, OwnedCount) (industry standard 1.15x).
• NEVER evaluate exact float equality (==); strictly use is_equal_approx() or >= to prevent "stuck" progress due to precision loss.
• NEVER parse scientific notation strings with to_int(); strictly use to_float() or a dedicated BigNumber parser.

Performance & Optimization

• NEVER update all UI labels every frame; strictly use Signals to update labels ONLY when values change, or throttle updates to 10 FPS.
• NEVER ignore Low Processor Usage Mode for mobile; strictly enable OS.low_processor_usage_mode = true to preserve battery life.
• NEVER instantiate/delete hundreds of text nodes per second; strictly use Object Pooling or MultiMeshInstance for click-feedback.
• NEVER update massive logs by modifying the text property; strictly use append_text() to prevent main thread blocking.

Player Experience & Persistence

• NEVER ignore Offline Progress; strictly calculate seconds_offline * total_revenue using system UNIX timestamps (Time.get_unix_time_from_system()).
• NEVER make the "Prestige" reset feel like a loss; strictly provide a global multiplier that makes the next run significantly faster (2-5x).
• NEVER calculate offline time using Time.get_ticks_msec(); strictly use Persistent UNIX timestamps as ticks reset on app restart.
• NEVER use Node hierarchies for raw data; strictly use RefCounted or Resource objects for lightweight, serializable logic.

---

🛠 Expert Components (scripts/)

> MANDATORY reads before implementing the matching system:

> 1. [big_number.gd](scripts/big_number.gd) — mantissa + exponent beyond float INF

> 2. [generator.gd](scripts/generator.gd) — exponential cost / rate units

> 3. [scientific_notation_formatter.gd](scripts/scientific_notation_formatter.gd) — K/M/B/T + scientific display

> 4. [offline_progress_calculator.gd](scripts/offline_progress_calculator.gd) — UNIX offline catch-up (not ticks_msec)

Original Expert Patterns

• [big_number.gd](scripts/big_number.gd) - Mantissa + Exponent math for e308+ scales.
• [generator.gd](scripts/generator.gd) - Exponential cost units and production rate calculation.
• [scientific_notation_formatter.gd](scripts/scientific_notation_formatter.gd) - Readable K/M/B/T and scientific suffixes.

Modular Components

• [offline_progress_calculator.gd](scripts/offline_progress_calculator.gd) - Real-world delta tracking using UNIX timestamps.
• [functional_income_reducer.gd](scripts/functional_income_reducer.gd) - Fast income summation patterns.
• [threaded_catchup_simulator.gd](scripts/threaded_catchup_simulator.gd) - WorkerThreadPool background catch-up.
• [precision_cost_validator.gd](scripts/precision_cost_validator.gd) - Cost curve / affordability checks.
• [scientific_notation_math.gd](scripts/scientific_notation_math.gd) - Shared mantissa helpers for formatters.
• [idle_performance_setup.gd](scripts/idle_performance_setup.gd) - low_processor_usage_mode + signal-throttled UI.
• [decoupled_economy_signal_bus.gd](scripts/decoupled_economy_signal_bus.gd) - Throttled economy→UI signals.
• [lightweight_upgrade_resource.gd](scripts/lightweight_upgrade_resource.gd) - Upgrade .tres pattern.
• [big_int_save_parser.gd](scripts/big_int_save_parser.gd) - Persist big numbers safely.
• [thread_safe_ui_updater.gd](scripts/thread_safe_ui_updater.gd) - Deferred UI after threaded catch-up.

---

Core Loop

1. Click → 2. Buy generators → 3. Idle income → 4. Upgrade → 5. Prestige

Decision Trees

Numbers & display

| Need | Action |

|------|--------|

| Values past ~1e308 | MANDATORY [big_number.gd](scripts/big_number.gd) |

| Labels / abbreviations | MANDATORY [scientific_notation_formatter.gd](scripts/scientific_notation_formatter.gd) |

| Cost curve ~1.15^n | [generator.gd](scripts/generator.gd) + [precision_cost_validator.gd](scripts/precision_cost_validator.gd) |

Offline & perf

| Need | Action |

|------|--------|

| Offline catch-up | MANDATORY [offline_progress_calculator.gd](scripts/offline_progress_calculator.gd) (UNIX time) |

| Long catch-up | [threaded_catchup_simulator.gd](scripts/threaded_catchup_simulator.gd) |

| Battery / idle CPU | [idle_performance_setup.gd](scripts/idle_performance_setup.gd) |

Do not re-inline BigNumber/Offline tutorials in the skill body — load the scripts above.

Skill Chain

| Phase | Skills | Purpose |

|-------|--------|---------|

| 1. Math | godot-gdscript-mastery | Big-number arithmetic |

| 2. UI | godot-ui-containers, labels | Scientific / suffix labels |

| 3. Data | godot-save-load-systems | Offline timestamps + prestige |

| 4. Logic | signals | Throttled economy UI |

| 5. Balance | godot-monte-carlo-balancer | Minutes-to-milestone bands |

Common Pitfalls

| Pitfall | Solution |

|---------|----------|

| Wrong Expert Component hrefs | Links above point at canonical big_number / generator / formatter |

| Time.get_ticks_msec offline | Use UNIX via offline calculator |

| UI every frame | Signal-throttle via economy bus / performance setup |

Expert knowledge (on demand)

> LLM-ignorance rule: If a general agent would not know it before reading, load the reference — never delete expert deltas.

• [expert-idle-clicker-patterns.md](references/expert-idle-clicker-patterns.md) — restored baseline pedagogy (architecture, WHY, implementation depth)
• [big_real.gd](scripts/big_real.gd)
• [offline_progression_manager.gd](scripts/offline_progression_manager.gd)
• [click_juice_manager.gd](scripts/click_juice_manager.gd)

Reference

> Progressive disclosure: open Official Documentation links only when researching a specific API; load Related Skills when routing to a peer domain — do not preload the whole lattice.

Official Documentation

• Idle and physics processing — Revenue must accumulate in _process(delta) (or a fixed sim tick), not drifting Timer nodes, so generators stay frame-rate independent.
• Time — Offline catch-up uses Time.get_unix_time_from_system(); never get_ticks_msec(), which resets when the app restarts.
• Saving games — Persist currency, generator counts, prestige multipliers, and last-save UNIX timestamps so welcome-back earnings survive restarts.
• Data paths — Keep save blobs under user:// so offline timestamps and big-number strings remain writable across platforms.
• Resources — Generators, upgrades, and prestige curves belong as .tres Resources so designers retune cost_growth_factor without code changes.
• GDScript exports — @export base costs, revenue rates, and growth factors so balance sheets stay Inspector-driven.
• Using signals — Emit currency_updated only when balances change so HUD labels do not rewrite every frame.
• OS — Enable OS.low_processor_usage_mode (and sleep usec) for mobile idle sessions that spend most time waiting on generators.
• Using multiple threads — Long offline catch-up sims belong on WorkerThreadPool; UI must not block while thousands of ticks replay.
• Thread-safe APIs — Marshaling sim results to Labels requires call_deferred / main-thread rules from this page.
• Formatting strings — K/M/B suffixes and %.2fe%d scientific display depend on correct format strings (and String.num_scientific when appropriate).
• RefCounted — BigNumber and upgrade payloads should be lightweight RefCounted/Resource data, not Node trees.

Related Skills

Prerequisites

• godot-gdscript-mastery — Mantissa/exponent classes, pow growth, and precision-safe compares (is_equal_approx) are core GDScript patterns before building idle economies.
• godot-resource-data-patterns — Generator and upgrade definitions should be Resource-first so balance curves stay data-driven .tres assets.
• godot-signal-architecture — Decoupled currency buses must signal up to UI and never let Labels mutate the simulation wallet.
• godot-save-load-systems — Offline progress and prestige state need versioned save handlers that store UNIX timestamps and big-number strings safely.

Complements

• godot-economy-system — Soft-currency wallets, sinks, and transaction APIs compose with idle generators when the game grows shops or prestige shops.
• godot-ui-containers — Generator lists and upgrade grids are GridContainer/VBoxContainer layouts bound to throttle-friendly labels.
• godot-ui-rich-text — Scientific notation, suffix strings, and append-only logs belong in Label/RichTextLabel patterns rather than rebuilding huge text blobs.
• godot-performance-optimization — Low-processor mode, UI throttling, and pooled click-juice keep idle loops battery-friendly on mobile.
• godot-autoload-architecture — Simulation managers and economy buses that survive scene reloads should follow Autoload ownership rules.
• godot-particles — Click-feedback bursts should use batched GPUParticles2D.emit_particle rather than spawning Label nodes per tap.

Downstream / consumers

• godot-monte-carlo-balancer — After cost curves and prestige multipliers are Resource-driven, Monte Carlo career sims prove minutes-to-milestone bands (not win%) before shipping growth factors.
• godot-platform-mobile — Shipping idle on phones consumes low-processor mode, background resume, and offline catch-up patterns from this genre skill.

Master

• godot-master — Library router and mirrored module entry; use when discovering peer skills or syncing shared script mirrors after Domain Skill edits.