idle/core/prestige/TECH_SPEC.md

Prestige System - Technical Specification

Document Status

1. Version: 1.0
2. Date: 2026-03-21
3. Scope: Add a configurable prestige reset loop with editor-authored curve math and permanent run multipliers.

Problem Statement

The prototype currently has growth, buffs, and unlock goals, but no reset loop that converts late-run progress into long-term power. Without prestige, the economy has no designed "ladder climb" cycle and balancing eventually relies only on direct cost/production tuning.

Design Goals

1. Support a prestige reset that grants a permanent currency based on player progress.
2. Keep prestige math data-driven and editable in the Godot inspector for balancing iteration.
3. Support both major prestige archetypes from Kongregate's analysis:
   • Lifetime or max-stat based curves (diminishing gains when resetting at the same point repeatedly).
   • Since-reset/run-only curves (same run depth gives similar rewards each reset).
4. Integrate with existing systems (GameState, BigNumber, generator/buff runtime) without hardcoding one formula.
5. Persist all prestige state in user://idle_save.json alongside existing runtime data.

Non-Goals (For First Iteration)

1. Multiple prestige currencies.
2. Prestige skill tree/shop UI.
3. Offline simulation changes beyond applying the resulting permanent multiplier.

Kongregate-Informed Curve Model

From "The Math of Idle Games, Part III", prestige formulas can be modeled as transformed progress stats with fractional exponents.

Core variables:

1. delta_p: prestige currency gained on reset.
2. p: total prestige currency owned.
3. c_L: lifetime currency earned.
4. c_M: max currency reached in a run.
5. c_R: currency earned since last reset.

Supported formula families for this system:

1. Power curve (generic): f(x) = scale * (x / threshold)^exponent.
2. Triangular inverse sqrt (Realm Grinder style): solve x = threshold * p(p+1)/2 for p.
3. Log-like compression (future option, disabled by default).

Behavior groups:

1. Cumulative-stat formulas (c_L, c_M) compute target total prestige then grant target_total - current_total.
2. Run-only formulas (c_R) compute direct gain per run.

Proposed Runtime Architecture

1. Add PrestigeManager autoload (core/prestige/prestige_manager.gd) as the single authority for prestige state and reset flow.
2. Add PrestigeConfig resource (core/prestige/prestige_config.gd) authored in inspector and loaded from data assets.
3. GameState remains owner of currencies/generator state; PrestigeManager orchestrates reset and applies permanent multiplier.
4. Generators read the active prestige multiplier through one accessor (PrestigeManager.get_total_multiplier()), then multiply existing run_multiplier behavior.

Data Model

PrestigeConfig (Resource)

Editor-authored resource fields (all exported):

1. id: StringName.
2. display_name: String.
3. prestige_currency_id: StringName (logical id, not regular wallet currency).
4. source_currency_id: StringName (which gameplay currency powers prestige calculation).
5. basis: BasisType enum:
   • LIFETIME_TOTAL
   • RUN_TOTAL
   • RUN_MAX
6. formula: FormulaType enum:
   • POWER
   • TRIANGULAR_INVERSE
7. threshold_mantissa: float and threshold_exponent: int (BigNumber-like threshold).
8. scale: float.
9. exponent: float (used by POWER).
10. flat_bonus: float.
11. minimum_gain: int.
12. rounding_mode: RoundingMode enum (FLOOR, ROUND, CEIL).
13. allow_prestige_without_gain: bool.
14. Multiplier tuning:

• multiplier_mode: MultiplierMode enum (ADDITIVE, MULTIPLICATIVE_POWER).
• base_multiplier: float.
• multiplier_per_prestige: float.
• multiplier_exponent: float.

Prestige Runtime State

Persisted by PrestigeManager:

1. total_prestige_earned: BigNumber.
2. current_prestige_unspent: BigNumber.
3. prestige_resets_count: int.
4. run_start_total_source_currency: BigNumber.
5. run_peak_source_currency: BigNumber.
6. last_reset_time: int.

Formula Specification

1) Basis Value Extraction

Given configured source_currency_id:

1. LIFETIME_TOTAL: basis_value = GameState.get_total_currency_acquired_by_id(source_currency_id).
2. RUN_TOTAL: basis_value = lifetime_now - run_start_total_source_currency.
3. RUN_MAX: basis_value = run_peak_source_currency.

2) Raw Gain

1. POWER: raw = scale * pow(basis_value / threshold, exponent) + flat_bonus.
2. TRIANGULAR_INVERSE:
   • k = basis_value / threshold
   • target = (sqrt(1 + 8k) - 1) / 2
   • if basis is cumulative (LIFETIME_TOTAL, RUN_MAX interpreted as cumulative target), raw = target - total_prestige_earned
   • if basis is run-only, raw = target

3) Post-Processing

1. Clamp negative to zero.
2. Apply configured rounding.
3. Enforce minimum_gain when basis passed threshold and gain > 0.

4) Multiplier Application

get_total_multiplier() returns one of:

1. Additive mode: base_multiplier + total_prestige_earned * multiplier_per_prestige.
2. Multiplicative power mode: base_multiplier * pow(1 + multiplier_per_prestige, pow(total_prestige_earned, multiplier_exponent)).

Implementation note: compute large-number powers via log10 transforms against BigNumber to avoid float overflow.

Reset Flow

1. Player presses prestige button.
2. PrestigeManager.calculate_pending_gain() computes gain from configured curve.
3. If gain is zero and allow_prestige_without_gain is false, block reset.
4. On confirm:
   • Add gain to total_prestige_earned and current_prestige_unspent.
   • Increment prestige_resets_count.
   • Reset runtime progression (GameState currencies, generator owned counts, generator availability that should restart locked).
   • Preserve permanent unlocks only if explicitly marked as persistent in future extensions.
   • Reinitialize run-tracking values (run_start_total_source_currency, run_peak_source_currency).
   • Emit prestige_performed(gain, total_prestige) signal.

GameState Integration

1. Add APIs for reset-safe state initialization (single call from PrestigeManager instead of duplicating clear logic).
2. Keep total-acquired currency behavior explicit:
   • Option A (recommended): reset current currencies and generator ownership, keep lifetime totals for LIFETIME_TOTAL basis.
   • Option B: clear totals too and rely on dedicated lifetime accumulator in prestige state.
3. Ensure generator/buff registrations are idempotent after reset (_ensure_registered paths already support this pattern).

Editor Authoring And Balancing Workflow

1. Create idles/prestige/primary_prestige.tres using PrestigeConfig.
2. Designers tune only exported fields in inspector (no code edits).
3. Provide presets matching Kongregate article examples:
   • Realm Grinder-like: basis=RUN_MAX, formula=TRIANGULAR_INVERSE, threshold=1e12.
   • AdCap-like: basis=LIFETIME_TOTAL, formula=POWER, scale=150, threshold=1e15, exponent=0.5.
   • Cookie Clicker-like: basis=LIFETIME_TOTAL, formula=POWER, threshold=1e12, exponent=0.333333.
   • Egg Inc-like: basis=RUN_TOTAL, formula=POWER, threshold=1e6, exponent=0.14.
4. Balance target guidance:
   • For sqrt-like curves, doubling prestige generally needs roughly 3x-4x deeper runs.
   • For cube-root curves, doubling prestige tends toward ~8x deeper runs.
   • For ~1/7 exponent run curves, doubling prestige needs ~128x deeper runs.

UI Requirements

1. Prestige panel must display:
   • current prestige total
   • pending gain (delta_p)
   • resulting multiplier after reset
   • basis stat currently used (c_L, c_R, or c_M equivalent)
2. Reset CTA disabled when pending gain is zero and config disallows zero-gain resets.
3. Confirmation dialog explicitly lists what resets and what is kept.

Persistence

1. Extend save payload with prestige_state object.
2. Serialize all BigNumber values with existing BigNumber.serialize() pattern.
3. During load, validate dictionaries and apply defaults if fields are missing.
4. Maintain backward compatibility with pre-prestige saves by creating default prestige state when absent.

Validation Plan

1. Headless parse: "$GODOT_BIN" --headless --path . --quit.
2. Script checks once implemented:
   • "$GODOT_BIN" --headless --check-only --script res://core/prestige/prestige_manager.gd
   • "$GODOT_BIN" --headless --check-only --script res://core/prestige/prestige_config.gd
3. Manual smoke cases:
   • same reset point in cumulative mode yields reduced/zero incremental gain.
   • same reset point in run-only mode yields roughly same gain.
   • multiplier updates production immediately after reset.
   • prestige state survives save/load.

Implementation Milestones

1. Introduce data classes (PrestigeConfig) and one authored .tres profile.
2. Implement PrestigeManager with gain math + persistence.
3. Add reset integration entrypoint in GameState.
4. Wire generator production multiplier to prestige.
5. Add initial prestige UI panel and confirmation flow.