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 — mantissa + exponent beyond float INF
2. generator.gd — exponential cost / rate units
3. scientific_notation_formatter.gd — K/M/B/T + scientific display
4. offline_progress_calculator.gd — UNIX offline catch-up (not ticks_msec)

Original Expert Patterns

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

Modular Components

• offline_progress_calculator.gd - Real-world delta tracking using UNIX timestamps.
• functional_income_reducer.gd - Fast income summation patterns.
• threaded_catchup_simulator.gd - WorkerThreadPool background catch-up.
• precision_cost_validator.gd - Cost curve / affordability checks.
• scientific_notation_math.gd - Shared mantissa helpers for formatters.
• idle_performance_setup.gd - low_processor_usage_mode + signal-throttled UI.
• decoupled_economy_signal_bus.gd - Throttled economy→UI signals.
• lightweight_upgrade_resource.gd - Upgrade .tres pattern.
• big_int_save_parser.gd - Persist big numbers safely.
• 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
Labels / abbreviations	MANDATORY scientific_notation_formatter.gd
Cost curve ~1.15^n	generator.gd + precision_cost_validator.gd

Offline & perf

Need	Action
Offline catch-up	MANDATORY offline_progress_calculator.gd (UNIX time)
Long catch-up	threaded_catchup_simulator.gd
Battery / idle CPU	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 — restored baseline pedagogy (architecture, WHY, implementation depth)
• big_real.gd
• offline_progression_manager.gd
• 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.