ClickerZ/docs/SPRINT3.md

SPRINT3.md — Prestige Loop

Brief technique — Sprint 3 Date : 2026-03-28 Réf GDD : docs/GDD.md Dépend : Sprint 2 livré (3/3) Agents : game-designer (design) → build (implémentation)

---

Objectif

Transformer le prestige d'une mécanique de reset en une boucle de progression motivante et endless. Le joueur doit sentir l'accélération à chaque génération, faire des choix de build durables, et viser des paliers qui récompensent la spécialisation.

---

Pré-requis technique — Migration saves

À traiter en amont de Step 1 — pas un step visible, mais bloquant.

Pattern saveVersion + migrateSave() (décision session 2026-03-28)

Le GameState est stocké en JSON unique dans MySQL. Ajouter/modifier des champs sans migration = undefined silencieux → NaN → bugs fantômes.

Mécanisme :

• Ajouter saveVersion: number au GameState
  • Saves Sprint 2 existantes = version absente → traitées comme v1
  • Sprint 3 = v2
• Fonction migrateSave(state: unknown): GameState appliquée au chargement (frontend useSaveSync + backend saveControllers)
  • v1 → v2 : injecter defaults (runStats vide, treeResetCount: 0, freeResetAvailable: true, repeatableNodes: {}, nouveaux nœuds arbre)
  • Les 18 nœuds Sprint 2 conservent leur id — les nouveaux s'ajoutent
  • Champ critique manquant → log warning + default safe (jamais de crash)
• Chaque sprint futur ajoute un step de migration (v2 → v3, etc.)

Schéma DB

• ALTER TABLE game_saves ADD COLUMN save_version INT DEFAULT 1
• Pas de migration du JSON existant en DB — la migration est lazy (au chargement)

Validation

• Charger une save Sprint 2 brute sur le nouveau code → migrateSave injecte v2
• Pas de perte de données, pas de reset forcé
• Les nœuds arbre existants (18) gardent leur position et état unlocked

---

Steps

Step 1 — Prestige Experience

Scope : Rendre le moment du prestige satisfaisant et informatif.

Design :

• Écran de prestige redesigné :
  • Preview ADN gagné (avant de confirmer)
  • Comparaison : "Run actuelle vs meilleure run" (durée, têtards, ADN)
  • Compteur de générations (nombre total de prestiges)
• Statistiques de run persistées :
  • Durée de la run
  • Têtards produits (lifetime cette run)
  • Vitesse de progression vs run précédente (% plus rapide / plus lent)
  • Branche d'arbre principale utilisée
• Animation de reset : transition visuelle (le marais "renaît")
• Hooks audio-ready : prévoir les points d'ancrage pour le son (Sprint futur)

Technique :

• PrestigeScreen.tsx : composant modal fullscreen (pas un simple bouton)
• RunStats dans le GameState :

  interface RunStats {
    startedAt: number;
    tadpolesProduced: number;
    prestigeCount: number;
    bestRun: {
      duration: number;
      tadpoles: number;
      adn: number;
    };
  }
  

• Backend : persister runStats dans la save (même pattern save serveur)
• Rebalancer la formule prestige pour l'endless (voir section Formules)

Critère done : le joueur clique Prestige → voit un écran avec preview ADN + stats comparées → confirme → animation → nouvelle run. Les stats de la meilleure run sont persistées.

---

Step 2 — Arbre d'Évolution V2 — Profondeur endless

Scope : Étendre l'arbre à ~30 nœuds avec capstones game-changers et scaling post-capstone infini.

Design — Structure par branche :

Branche Ponte (click) — 8-10 nœuds :

• Tier 1 : Ponte Améliorée (+100% click) — 1 ADN
• Tier 2 : Click Critique (5% chance ×10) — 5 ADN
• Tier 3 : Frénésie (click power +1% par click dans les 10 dernières sec, cap +50%) — 15 ADN
• Tier 3 alt (exclusif) : Concentration (+200% click, -25% idle) — 15 ADN
• Capstone : Ponte Automatique — auto-click 1/sec, scale avec upgrades ponte — 200 ADN
• Post-capstone (repeatable) : +5% auto-click speed, coût ×2 — départ 500 ADN

Branche Marais (production) — 8-10 nœuds :

• Tier 1 : Instinct Grégaire (+50% production tous générateurs) — 3 ADN
• Tier 2 : Spécialisation (un générateur au choix ×3) — 8 ADN
• Tier 3 : Écosystème (+10% prod par type de générateur possédé) — 25 ADN
• Tier 3 alt (exclusif) : Monoculture (un seul type ×5, les autres ×0.5) — 25 ADN
• Capstone : Symbiose Totale — chaque générateur booste les autres (+2% par type possédé) — 300 ADN
• Post-capstone (repeatable) : +1% symbiose, coût ×2 — départ 600 ADN

Branche Adaptation (utility) — 8-10 nœuds :

• Tier 1 : Mémoire Génétique (commence chaque run avec 100 têtards) — 2 ADN
• Tier 2 : Métabolisme Rapide (+25% offline cap) — 10 ADN
• Tier 3 : Héritage (conserve 5% des générateurs tier 1 entre prestiges) — 30 ADN
• Tier 3 alt (exclusif) : Mutation ADN (+25% ADN gagné au prestige) — 30 ADN
• Capstone : Mémoire du Marais — offline cap 25% → 75%, durée 2h → 8h — 250 ADN
• Post-capstone (repeatable) : +2% offline cap (au-delà de 75%), coût ×2 — départ 500 ADN

Nœud cross-branche — Convergence (évolutif, décision session 2026-03-28) :

Un seul nœud qui évolue quand le joueur atteint de nouveaux paliers de diversification. Pattern tier sur le nœud — fondation pour d'autres nœuds évolutifs futurs.

Convergence Alpha (tier 1)
  Condition : 1 capstone + tier 3 d'une 2e branche (~prestige 12-15)
  Coût : 500 ADN
  Effet : +10% à tous les effets de l'arbre

Convergence Omega (tier 2 — même nœud, upgrade auto)
  Condition : 2 capstones atteintes
  Coût : 500 ADN supplémentaires (total investi : 1000)
  Effet : +10% tous effets + -20% coût post-capstones

Technique — champ tier sur EvolutionNode :

tier?: number;              // 1 = Alpha, 2 = Omega (current level)
maxTier?: number;           // 2
tierUpgradeCost?: number;   // 500
tierUpgradeCondition?: string; // "2_capstones"

UX : notification "Convergence a évolué !" quand la condition tier 2 est remplie. Le joueur voit sa récompense grandir — pas un 2e nœud à acheter séparément.

Technique :

• DEFAULT_EVOLUTION_TREE : ~30 nœuds (tree data structure, pas array)
• Ajouter tier: number et repeatable: boolean aux EvolutionNode
• repeatableCount: number dans le state pour les nœuds post-capstone
• UI : garder le layout 3 colonnes, ajouter scroll vertical par branche
• Capstones visuellement distincts (bordure dorée, icône spéciale)
• Cross-branche : section basse, verrouillée visuellement jusqu'aux conditions
• Convergence : badge évolutif (Alpha → Omega), indicateur de progression vers le prochain tier

Reset arbre — 1 gratuit par prestige (décision session 2026-03-28) :

Chaque prestige offre 1 reset gratuit (nouvelle génération = nouvelle chance de build). Resets supplémentaires dans la même génération = payants.

freeResetAvailable: boolean  // true après chaque prestige, false après usage
resetCostInGeneration: number = 5 × extraResetsUsed  // linéaire, pas exponentiel

Reset# (dans la même génération)	Coût ADN
1er	Gratuit (offert par prestige)
2e	5
3e	10
4e	15

Pas punitif, encourage l'expérimentation, mais décourage le spam.

Fondation build-sharing (Sprint 4+ vision) : Le build de l'arbre est exportable en string compacte (nœuds unlocked encodés). Permet le partage de builds entre joueurs et les "runs prestige" communautaires. → Structurer l'arbre state pour faciliter l'export dès Sprint 3 : buildCode: string = nœuds unlocked encodés base36 ou similaire.

Critère done : l'arbre affiche ~30 nœuds sur 3 branches + cross-branche, les capstones changent le gameplay de manière perceptible, les post-capstones sont achetables en boucle.

---

Step 3 — Milestones de Prestige

Scope : Récompenser la persévérance avec des paliers de prestige qui débloquent cosmétiques exclusifs et bonus légers.

Design :

Palier	Récompense	Type
1 prestige	Badge "Première Génération" + ruban queue	cosmétique
3 prestiges	Titre "Gardien Récurrent"	cosmétique
5 prestiges	Start avec 1 Nid gratuit	gameplay léger
10 prestiges	Skin "Têtard Ancestral" (body prestige) + couronne dorée	cosmétique
15 prestiges	+5% offline cap permanent	gameplay léger
25 prestiges	Cape d'algues ancestrales + aura prestige	cosmétique
50 prestiges	Titre "Légende du Marais" + particules dorées permanentes	cosmétique
100 prestiges	Skin "Têtard Primordial" (full set)	cosmétique

• Les bonus gameplay sont légers — jamais assez pour casser l'économie
• Les cosmétiques prestige-only ne sont pas obtenables autrement (exclusivité = motivation)
• Écran milestones accessible depuis le menu prestige (progress bar vers le prochain palier)

Technique :

• PrestigeMilestone type :

  interface PrestigeMilestone {
    id: string;
    threshold: number;        // nombre de prestiges requis
    reward: MilestoneReward;
    claimed: boolean;
  }
  
  type MilestoneReward =
    | { type: "cosmetic"; cosmeticId: string }
    | { type: "bonus"; effect: EffectType; value: number }
    | { type: "title"; title: string };
  

• Intégrer avec le système cosmétiques V1 existant — ajouter source: "prestige_milestone" aux cosmétiques
• UI : MilestonesPanel.tsx — liste verticale avec progress bar, claim button, preview reward
• Backend : valider les claims (le joueur ne peut pas claim un milestone sans le nombre de prestiges)

Critère done : atteindre 5 prestiges → notification milestone → claim → Nid gratuit actif + cosmétique dans l'inventaire.

---

Formules — Rebalancing endless (décisions session 2026-03-28)

Formule ADN (remplace l'actuelle)

Actuelle : adn = floor(150 × sqrt(lifetime_tadpoles / 1e9)) — s'aplatit trop vite.

Nouvelle :

adn = max(1, floor(base × log10(tadpoles / threshold) × (1 + bonus)))

  base      = 50
  threshold = 1e6 (1M têtards — seuil minimum pour prestige)
  bonus     = min(0.05 × prestigeCount, 3.0)  // cap ×4 max à 80 prestiges
  clamp     = minimum 1 ADN si tadpoles >= threshold

Run	Tadpoles	Prestige#	Bonus	ADN gagné
1	1M (seuil)	0	×1.0	1 (clamp)
1	10M	0	×1.0	50
5	100M	4	×1.20	120
15	1B	14	×1.70	255
30	10B	29	×2.45	430
80+	100B	80	×4.00	800 (cap bonus atteint)

La courbe log scale bien : récompense toujours plus, oblige à aller exponentiellement plus loin. Le cap du bonus évite que l'endgame trivialise l'arbre.

Courbe coût post-capstones — paliers par tranche

Le ×2 brut crée un mur après ~8 achats. Scaling par tranche :

Achats 1-5   : cost = base × 1.5^n
Achats 6-10  : cost = base × 1.5^5 × 1.8^(n-5)
Achats 11+   : cost = base × 1.5^5 × 1.8^5 × 2.0^(n-10)

Achat#	Coût (base 500)	~Runs nécessaires (400 ADN/run)
1	750	~2
5	3 797	~10
10	68 890	~172
15	2.2M	endgame long

Chaque achat reste "quelques sessions" en mid-game, puis ralentit en endgame sans frapper un mur infranchissable.

Courbe coût nœuds standards

Définis manuellement par nœud (1, 3, 5, 8, 10, 15, 25, 30, 200, 250, 300, 500, 1000 ADN).

Vérification d'équilibre

• Premier capstone : entre le 8e et 12e prestige (spécialisation une branche)
• Arbre "complet" (hors post-capstone) : ~15-20 prestiges
• Post-capstones : progression infinie, chaque achat = investissement plus lourd mais gain marginal
• Cross-branche : joueur dédié à 25+ prestiges

Niveau de confiance : moyen — les chiffres sont calibrés sur les formules mais devront être playtestés. Toutes les constantes centralisées dans balance.ts pour ajustement rapide.

---

Résumé séquentiel

Migration saves → Step 1 (prestige experience) → Step 2 (arbre V2 endless) → Step 3 (milestones)

Step 1 = le moment. Step 2 = la profondeur. Step 3 = la motivation long terme.

---

Risques identifiés

Risque	Mitigation	Statut
Formule ADN mal calibrée	Constantes dans balance.ts. Clamp min 1 + cap bonus ×4. Playtest après Step 1	✅ adressé
Capstones trop puissants (Ponte Auto trivialise)	Tester chaque capstone isolément. Auto-click = 1/sec de base	à tester
Post-capstone wall en late-game	Scaling par tranche (×1.5/×1.8/×2.0) au lieu de ×2 brut	✅ adressé
Migration saves casse les joueurs existants	Pattern saveVersion + migrateSave() lazy. Saves Sprint 2 = v1, migrées automatiquement	✅ adressé
Reset arbre frustrant	1 gratuit par prestige + linéaire au-delà. Pas d'exponentiel	✅ adressé
Arbre V2 complexe visuellement	Progressive disclosure : griser les nœuds non débloquables, tooltip clair	à tester
Build-sharing string : encodage fragile	Valider le décodage côté client. Nœud inconnu dans le code = ignoré (forward compat)	Sprint 4