# 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) |