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 isequalapprox() or >= to prevent "stuck" progress due to precision loss.
• NEVER parse scientific notation strings with toint(); strictly use tofloat() 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.lowprocessorusage_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 secondsoffline * totalrevenue using system UNIX timestamps (Time.getunixtimefromsystem()).
• 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.getticksmsec(); 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. [bignumber.gd](scripts/bignumber.gd) — mantissa + exponent beyond float INF
2. [generator.gd](scripts/generator.gd) — exponential cost / rate units
3. [scientificnotationformatter.gd](scripts/scientificnotationformatter.gd) — K/M/B/T + scientific display
4. [offlineprogresscalculator.gd](scripts/offlineprogresscalculator.gd) — UNIX offline catch-up (not ticks_msec)

Original Expert Patterns

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

Modular Components

• [offlineprogresscalculator.gd](scripts/offlineprogresscalculator.gd) - Real-world delta tracking using UNIX timestamps.
• [functionalincomereducer.gd](scripts/functionalincomereducer.gd) - Fast income summation patterns.
• [threadedcatchupsimulator.gd](scripts/threadedcatchupsimulator.gd) - WorkerThreadPool background catch-up.
• [precisioncostvalidator.gd](scripts/precisioncostvalidator.gd) - Cost curve / affordability checks.
• [scientificnotationmath.gd](scripts/scientificnotationmath.gd) - Shared mantissa helpers for formatters.
• [idleperformancesetup.gd](scripts/idleperformancesetup.gd) - lowprocessorusage_mode + signal-throttled UI.
• [decoupledeconomysignalbus.gd](scripts/decoupledeconomysignalbus.gd) - Throttled economy→UI signals.
• [lightweightupgraderesource.gd](scripts/lightweightupgraderesource.gd) - Upgrade .tres pattern.
• [bigintsaveparser.gd](scripts/bigintsaveparser.gd) - Persist big numbers safely.
• [threadsafeuiupdater.gd](scripts/threadsafeuiupdater.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

Offline & perf

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

Skill Chain

Common Pitfalls

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)
• [bigreal.gd](scripts/bigreal.gd)
• [offlineprogressionmanager.gd](scripts/offlineprogressionmanager.gd)
• [clickjuicemanager.gd](scripts/clickjuicemanager.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.getunixtimefromsystem(); never getticks_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 costgrowthfactor without code changes.
• GDScript exports — @export base costs, revenue rates, and growth factors so balance sheets stay Inspector-driven.
• Using signals — Emit currencyupdated only when balances change so HUD labels do not rewrite every frame.
• OS — Enable OS.lowprocessorusagemode (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 (isequalapprox) 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.