ClickerZ/docs/GDD.md

Clickerz — GDD (Game Design Document)

Tetard Universe — Clicker/idle hybride Dernière mise à jour : 2026-03-20 Repo : git.tetardtek.com/Tetardtek/clickerz URL : https://clickerz.tetardtek.com/

---

Identité

Clickerz — Clicker/idle hybride dans le Tetard Universe. Un marais mystérieux où des têtards naissent, évoluent, mutent et bâtissent un écosystème. Chaque prestige = une nouvelle "génération" de têtards, plus forte, plus étrange.

Archétype : hybride — clicker au départ (onboarding immédiat), idle dominant en mid-game (rétention), couche stratégique en late-game (prestige + arbre permanent).

---

Univers — Tetard Universe

Le joueur est le Gardien du Marais. Les têtards sont la ressource vivante — ils naissent, travaillent, évoluent. Le marais grandit, se diversifie, attire de nouvelles espèces.

Cross-promo naturelle avec TetaRdPG (même univers, assets partageables à terme).

Vocabulaire in-game

Concept mécanique	Nom in-game	Icône
Ressource principale	Têtards	🥚
Click	Ponte	tap/click
Générateurs tier 1	Nid	🪹
Générateurs tier 2	Mare	🌊
Générateurs tier 3	Marécage	🏞️
Générateurs tier 4	Étang Ancien	🏛️
Générateurs tier 5	Lac Mystique	✨
Prestige currency	ADN Ancestral	🧬
Prestige reset	Nouvelle Génération	🔄🐸
Arbre permanent	Arbre d'Évolution	🌳
Milestones	Mutations	🧪

---

Stack technique

Couche	Techno	Justification
Frontend	React 18 + TypeScript + Vite	Existant validé, lazy calc pattern
State	Zustand	Game loop adapté, léger
Style	Tailwind CSS (migration SCSS → Tailwind)	Productivité, cohérence
Backend	Express + MySQL	Existant avec SuperOAuth câblé
Auth	SuperOAuth (clickerz.tetardtek.com)	SSO Tetardtek ecosystem
Tests	Vitest	13 tests existants sur economy.ts

---

Mécaniques core

Ressource principale : Têtards

Sources de production :

• Ponte (clic manuel) : +1 × clickMultiplier × prestigeMultiplier
• Générateurs idle : 5 tiers, coût base × 1.15^owned, production/s cumulative

Générateurs — progression tier

Tier	Nom	Coût base	Production/s	Ratio scaling
1	Nid	10	0.1	1.15
2	Mare	100	0.5	1.15
3	Marécage	1 000	3	1.15
4	Étang Ancien	10 000	20	1.15
5	Lac Mystique	100 000	150	1.15

Formule coût : coût = base_cost × 1.15^owned Formule production : output = base_prod × owned × multipliers

Ratio 1.15 = standard éprouvé. Assez steep pour forcer la diversification, assez doux pour que chaque achat ait un impact.

---

Boucle de progression — 3 couches

┌─────────────────────────────────────────────────┐
│  BOUCLE 1 — La Run (secondes → minutes)         │
│                                                   │
│  Ponte (click) → +têtards                         │
│  Acheter Nid → +têtards/sec (idle)                │
│  Upgrades Nid → multiplicateur                    │
│  Débloquer Mare → nouveau tier, plus cher,         │
│                   plus rentable                    │
│  ...jusqu'à atteindre un plateau                  │
└──────────────────────┬──────────────────────────┘
                       │ plateau atteint
                       ▼
┌─────────────────────────────────────────────────┐
│  BOUCLE 2 — Nouvelle Génération (heures → jours) │
│                                                   │
│  Prestige → reset générateurs + têtards           │
│  Gain : ADN Ancestral (formule sur total têtards) │
│  ADN → Arbre d'Évolution (permanent)              │
│    → +% production globale                        │
│    → débloquer nouvelles mutations                │
│    → débloquer nouveaux types de générateurs      │
│  Nouvelle run = plus rapide, va plus loin          │
└──────────────────────┬──────────────────────────┘
                       │ arbre mature
                       ▼
┌─────────────────────────────────────────────────┐
│  BOUCLE 3 — Méta (semaines) [Sprint 3+]          │
│                                                   │
│  Espèces rares, événements saisonniers,           │
│  leaderboard, objectifs communautaires            │
│  (hors scope Sprint 1)                            │
└─────────────────────────────────────────────────┘

---

Prestige — Nouvelle Génération

Seuil : 1 000 000 têtards produits (total lifetime de la run) Formule ADN : adn = floor(150 × sqrt(lifetime_tadpoles / 1e9))

Ce qui reset : têtards, générateurs, upgrades de run Ce qui persiste : ADN Ancestral, Arbre d'Évolution, achievements, stats

Prestige actuel (hérité) : +0.1× multiplicateur permanent par reset Cible Sprint 1 : migrer vers ADN Ancestral + Arbre d'Évolution

---

Arbre d'Évolution (permanent — jamais reset)

Sprint 1 — linéaire (5 nœuds). Sprint 2+ → branches.

Nœud	Coût ADN	Effet
Ponte Améliorée	1	+100% click power
Instinct Grégaire	3	+50% production tous générateurs
Mémoire Génétique	10	Commence chaque run avec 100 têtards
Mutation Alpha	25	Débloquer tier 5 dès le début de la run
Symbiose	50	+1% production par achievement débloqué

---

Sauvegarde & Anti-triche

• Save côté serveur uniquement (backend Express + MySQL)
• Pas de localStorage pour les données de jeu (cache UI uniquement)
• Auto-save toutes les 30 secondes via API
• Validation snapshot : elapsed_time × max_possible_production × 1.1 >= claimed_resources
• Client considéré hostile — toute donnée validée côté serveur

---

Monétisation

Cosmétiques only — pas de pay-to-win

• Thèmes visuels (couleurs, icônes marais)
• Titres / badges de génération
• Effets de ponte (particules)
• Raison : 0 compliance fiscale, 0 déséquilibre économie, communauté saine

---

Sprint 2 — Offline, Branches & Cosmétiques

Brief technique : docs/SPRINT2.md

Feature	Design
Offline gains	Courbe inversée 100%→0% sur 2h, cap 25% prod idle, écran résumé au retour
Arbre 3 voies	Ponte (click) / Marais (production) / Adaptation (utility), ~15 nœuds, reset gratuit
Cosmétiques V1	5 slots SVG overlay, récompenses achievements + prestige tiers, inventaire

Hors scope Sprint 2

• Boucle 3 (méta, events, leaderboard)
• Monétisation effective (boutique cosmétique payante)
• Sound / musique
• Mobile responsive (session dédiée)
• Migration Express → Fastify
• Intégration Twitch
• Multijoueur
• Coût reset arbre (gratuit Sprint 2, payant plus tard)

---

Sprint 3 — Prestige Loop (endless)

Brief technique : docs/SPRINT3.md

Feature	Design
Migration saves	Pattern saveVersion + migrateSave() — backward compat Sprint 2, lazy au chargement
Prestige Experience	Écran redesigné (preview ADN, stats run, comparaison), animation reset, hooks audio-ready
Arbre V2 endless	~30 nœuds (3 branches approfondies), capstones game-changers, post-capstone repeatable (scaling par tranche ×1.5/×1.8/×2.0), cross-branche
Milestones prestige	8 paliers (1→100 prestiges), cosmétiques exclusifs + bonus gameplay légers
Reset arbre	1 gratuit par prestige, payant linéaire au-delà (5 ADN × n). Build exportable (fondation Sprint 4 sharing)
Formule ADN rebalancée	max(1, floor(50 × log10(t/1e6) × (1 + min(0.05×p, 3.0)))) — clamp + cap bonus ×4

Capstones par branche

Branche	Capstone	Effet
Ponte (click)	Ponte Automatique	Auto-click 1/sec, scale avec upgrades ponte
Marais (production)	Symbiose Totale	Chaque générateur booste les autres (+2% par type possédé)
Adaptation (utility)	Mémoire du Marais	Offline cap 25%→75%, durée 2h→8h

Profils joueurs émergents

• Joueur Ponte : joue activement, optimise les clics, capstone = auto-click idle
• Joueur Marais : optimise les achats générateurs, capstone = boucle multiplicative
• Joueur Adaptation : joue casual 2-3×/jour, capstone = idle puissant

Hors scope Sprint 3

• Boucle 3 (méta, events, leaderboard, cross-promo TetaRdPG)
• Son / musique (prévu Sprint 4+ — hooks audio posés dans prestige)
• Mobile responsive / client natif Godot (projet séparé envisagé)
• Monétisation effective (boutique cosmétique payante)
• Analytics joueur (event log backend — Sprint 4)

---

Changelog

Date	Changement
2026-03-17	GDD initial — sprint1-step1, stack React+TS+Vite, mécaniques core
2026-03-20	Refonte game-designer — Tetard Universe, Arbre d'Évolution, anti-triche backend, SuperOAuth, stack confirmée Express
2026-03-28	Sprint 1 livré (6/6). Sprint 2 briefé — offline gains courbe inversée, arbre 3 voies, cosmétiques récompenses
2026-03-28	Sprint 2 livré (3/3). Sprint 3 briefé — prestige loop endless, arbre V2 30 nœuds, capstones, milestones, formule ADN rebalancée
2026-03-28	Sprint 3 brainstorm — 5 décisions : saveVersion migration, formule ADN clamp+cap, scaling post-capstone par tranche, reset 1 gratuit/prestige + vision build-sharing, Convergence évolutif (Alpha→Omega, nœud unique à tiers)