# Passe Saisonnier

## 1. Définition
Système de progression temporaire (durée typique : 1 mois) offrant des récompenses exclusives (skins, thèmes, monnaie) aux joueurs qui accomplissent des tâches ou jouent régulièrement. Chaque passe est centré sur une thématique spécifique (Jungle, Tigre, Ours, Lapin, Lion, Chat, Dinosaure, Panthère, Jaguar, Crocodile 3D, etc.).

## 2. Fonctions
*   **Engagement :** Incite à jouer quotidiennement pour progresser dans le passe.
*   **Monétisation :** Peut comporter une voie gratuite et une voie payante (Premium) offrant plus de récompenses.
*   **Distribution de Contenu :** Moyen principal d'obtenir les nouveaux thèmes et skins.

## 3. Icone
*   **Représentation :** Ticket doré ou Calendrier avec une étoile.
*   **Couleur dominante :** Or et Rouge.

## 4. Interactions
*   **Consultation :** Bouton dédié sur l'écran principal affichant la barre de progression du passe.
*   **Réclamation :** Clic sur les paliers débloqués pour récupérer les récompenses.
*   **Achat :** Bouton pour acheter la version Premium du passe.

## 5. Annexes Techniques

### Données (JSON)
```json
{
  "pass_id": "pass_season_05",
  "theme_name": "Tigre",
  "duration_days": 30,
  "start_date": "2026-05-01",
  "end_date": "2026-05-31",
  "levels": [
    {
      "level": 1,
      "xp_required": 100,
      "reward_free": "coins_100",
      "reward_premium": "skin_tiger_hat"
    },
    {
      "level": 30,
      "xp_required": 3000,
      "reward_free": "skin_tiger_statue",
      "reward_premium": "theme_tiger_full"
    }
  ]
}
```

### Règles Métier
*   Les récompenses cosmétiques (thèmes) sont temporaires pour les joueurs non-VIP (liées à la durée du passe).
*   Les joueurs VIP débloquent la conservation permanente des thèmes acquis via le passe.
*   La progression se fait via l'XP gagnée en jeu ou des quêtes spécifiques au passe.

## 6. Annexes UX/UI
*   **Barre de Progression :** Visuel clair de l'avancement (jauge remplie).
*   **Paliers :** Icônes des récompenses cliquables pour détails.
*   **Mise en avant :** Pop-up à la connexion annonçant le nouveau passe ou les récompenses non réclamées.


# Annexes UX/UI

## 0. Direction Artistique & Vue
*   **Vue** : Isométrique (2.5D).
*   **Style** : Coloré, vivant, détails foisonnants (Réf: IMG_20260303_170253.jpg).
*   **Sprites** : 4 directions.
*   **Interactions** :
    *   **Sélection** : Cliquer sur la base de l'élément (ou son sprite principal) pour le sélectionner.
    *   **Feedback** : Surbrillance (outline blanc/jaune) au survol de la souris.


## Définition

| Champ | Valeur |
|---|---|
| Concept | Passe de progression **temporaire** (ex. 30 jours) avec paliers + récompenses. |
| Thématique | Une saison = une thématique (Jungle/Tigre/Ours/Lapin/Lion/Chat/Dinosaure/Panthère/Jaguar/Crocodile 3D…). |
| Accès | Voie gratuite + voie premium (achat). |
| Conservation | Non-VIP : accès thèmes/packs du passe **pendant la durée du passe**. VIP : accès conservé **tant que VIP actif** (cf. `vip.md`). |

## Fonctions (tableau détaillé)

| Fonction | Déclencheur | Entrées | Sorties | Règles | Observabilité |
|---|---|---|---|---|---|
| Accumuler XP passe | actions/quetes | événements jeu | `pass_xp +` | Sources XP listées, caps journaliers | Event `PASS_XP_GAINED` |
| Déverrouiller palier | XP atteint | xp total | niveau débloqué | Déverrouillage monotone | Event `PASS_LEVEL_UNLOCKED` |
| Réclamer récompense | clic palier | type voie | item ajouté | Doit être idempotent | Event `PASS_REWARD_CLAIMED` |
| Acheter premium | achat | paiement | premium actif | Upgrade voie ; rétroactif sur paliers | Event `PASS_PREMIUM_PURCHASED` |
| Fin de saison | date fin | now | close | Non-VIP : gating thèmes ; VIP : gating par VIP | Event `PASS_ENDED` |

## Icone de base

| Élément | Spécification |
|---|---|
| Représentation | Ticket / calendrier étoilé |
| Couleur dominante | Or / rouge |
| Variantes | `icon_pass_ticket.png`, `icon_pass_calendar.png` |
| États | Badge “nouveau”, “récompenses à réclamer”, “premium” |

## Interactions (tableau détaillé)

| Interaction | Type | Préconditions | Étapes UI | Résultat | Erreurs / Messages |
|---|---|---|---|---|---|
| Ouvrir passe | Consultation | passe actif | bouton HUD | écran passe | - |
| Voir palier | Consultation | - | scroll paliers | détail reward | - |
| Réclamer | Action | palier débloqué | clic reward | item ajouté | `REWARD_LOCKED`, `ALREADY_CLAIMED` |
| Acheter premium | Action | non premium | clic CTA | premium actif | `PAYMENT_FAILED` |
| Aller quêtes passe | Navigation | - | bouton “Quêtes” | liste quêtes | - |

## Annexes Techniques

### 1. Données et États (tableau détaillé)

| Donnée / État | Type | Exemple | Source | Contraintes |
|---|---|---|---|---|
| `pass_id` | string | `pass_season_05` | DB | unique |
| `theme_name` | string | `Tigre` | config | - |
| `duration_days` | int | 30 | config | - |
| `start_date/end_date` | date | - | config | UTC |
| `levels[]` | array | - | config | 1..N |
| `levels.level` | int | 1 | config | monotone |
| `levels.xp_required` | int | 100 | config | monotone |
| `reward_free/reward_premium` | string | `skin_tiger_hat` | config | item ids |
| `player_state.pass_xp` | int | 0..∞ | DB | cumul |
| `player_state.premium_active` | bool | false | DB | - |
| `player_state.claimed_rewards` | set | - | DB | idempotence |

#### Caractéristiques Initiales (tableau détaillé)

| Caractéristique | Valeur initiale | Unité | Notes |
|---|---:|---|---|
| XP passe | 0 | xp | départ |
| Premium actif | false | bool | départ |
| Niveaux | 30 | levels | exemple |
| Cap XP/jour | 1000 | xp | anti farm |

#### Scores Initiaux (tableau détaillé)

| Score | Valeur initiale | Plage | Impact |
|---|---:|---|---|
| Niveaux débloqués | 0 | 0..N | progression |
| Récompenses non réclamées | 0 | 0..∞ | badge UI |

### 2. Cycles de Vie et Apparition (tableau détaillé)

| Phase | Déclencheur | Entrées | Sorties | Invariants |
|---|---|---|---|---|
| Apparition | début saison | config | passe actif | dates |
| Progression | actions | xp | unlocks | monotone |
| Fin | date | now | passe clos | gating |

#### Conditions d'Apparition (tableau détaillé)

| Condition | Seuil | Opérateur | Résultat |
|---|---:|---|---|
| Date >= start | true | est | passe visible |

#### Conditions de Disparition (tableau détaillé)

| Condition | Seuil | Opérateur | Résultat |
|---|---:|---|---|
| Date > end | true | est | passe inactif |

#### Hérédité (tableau détaillé)

| Élément | Hérité | Règle |
|---|---|---|
| XP gagné | Oui | persiste pour historique |
| Récompenses | Oui | items acquis restent possédés ; accès thèmes dépend VIP |

### 3. Impacts Environnementaux

#### Impact Température (tableau détaillé)

| Condition | Effet | Notes |
|---|---|---|
| Canicule | quêtes spécifiques | “vendre glaces” |

#### Impact Milieu (Biome) (tableau détaillé)

| Biome | Effet | Notes |
|---|---|---|
| Jungle | quêtes liées | thème |

#### Impact Saisons (tableau détaillé)

| Saison | Effet | Notes |
|---|---|---|
| Saison du passe | contenu | paliers |

#### Impact Heure / Jour-Nuit (tableau détaillé)

| Période | Effet | Notes |
|---|---|---|
| Reset quotidien | quêtes | distribution |

### 4. Impacts Biologiques et Sociaux

#### Impact Reproduction (tableau détaillé)

| Facteur | Effet | Condition |
|---|---|---|
| Quêtes “naissance” | XP passe + | si complétée |

#### Impact Mort (tableau détaillé)

| Cas | Effet | Condition |
|---|---|---|
| Mort bébé | quête/objectif | XP passe + si “résoudre incident” |

#### Impact Nourriture (tableau détaillé)

| Ressource | Effet | Condition |
|---|---|---|
| Quêtes nourriture | XP + | acheter/consommer |

#### Impact Attractivité(Visiteurs (tableau détaillé)

| Action/État | Effet | Condition |
|---|---|---|
| Thèmes saisonniers | attractivité + | si actif |

#### Impact Attractivité Animaux) (tableau détaillé)

| Action/État | Effet animaux | Condition |
|---|---|---|
| Skins animaux | visuel | pas de stats |

#### Impact Valeur (tableau détaillé)

| Facteur | Variation | Condition |
|---|---:|---|
| Items rares | valeur cosmétique + | collection |

### 5. Impacts Logistiques et Économiques

#### Vitesse (Camion) (tableau détaillé)

| Paramètre | Effet | Condition |
|---|---|---|
| Quête livraison | XP + | délai |

#### Vitesse (Nurserie) (tableau détaillé)

| Paramètre | Effet | Condition |
|---|---|---|
| Quête naissance | XP + | baby |

#### Vitesse (Accueil) (tableau détaillé)

| Paramètre | Effet | Condition |
|---|---|---|
| Quête réception | XP + | nouveau animal |

#### Vitesse (Recherche) (tableau détaillé)

| Paramètre | Effet | Condition |
|---|---|---|
| Quête RP | XP + | collecter |

#### Vitesse (Labo) (tableau détaillé)

| Paramètre | Effet | Condition |
|---|---|---|
| Quête labo monde | XP + | achat rare |

#### Vitesse (Visite) (tableau détaillé)

| Paramètre | Effet | Condition |
|---|---|---|
| Quête visiteurs | XP + | satisfaction |

#### Dépenses (Billeterie) (tableau détaillé)

| Poste | Coût | Unité | Condition |
|---|---:|---|---|
| Quête revenus | - | - | objectif |

#### Dépenses (Boutiques) (tableau détaillé)

| Poste | Coût | Unité | Condition |
|---|---:|---|---|
| Achat premium | variable | monnaie | passe |

#### Dépenses (Visiteurs) (tableau détaillé)

| Poste | Coût | Unité | Condition |
|---|---:|---|---|
| - | 0 | - | - |

#### Dépenses (Employés) (tableau détaillé)

| Poste | Coût | Unité | Condition |
|---|---:|---|---|
| Quête staff | - | - | embauche |

#### Dépenses (Boutiques) (tableau détaillé)

| Poste | Coût | Unité | Condition |
|---|---:|---|---|
| Section dupliquée | 0 | - | conservée |

#### Dépenses (Nurseries) (tableau détaillé)

| Poste | Coût | Unité | Condition |
|---|---:|---|---|
| Upgrade nurserie | variable | coins | objectif |

#### Dépenses (Nourriture) (tableau détaillé)

| Poste | Coût | Unité | Condition |
|---|---:|---|---|
| Achat nourriture | variable | coins | objectif |

#### Dépenses (Acceuil des animaux) (tableau détaillé)

| Poste | Coût | Unité | Condition |
|---|---:|---|---|
| Achat animaux | variable | coins | objectif |

#### Dépenses (Camion) (tableau détaillé)

| Poste | Coût | Unité | Condition |
|---|---:|---|---|
| Livraison | variable | coins | objectif |

#### Trajet Visiteurs

##### Trajet Visiteurs vers/depuis la ville (tableau détaillé)

| Source | Destination | Déclencheur | Effet |
|---|---|---|---|
| Ville | Zoo | réputation | quêtes flux |

##### Trajet Visiteurs vers/depuis les animaux (tableau détaillé)

| Source | Destination | Déclencheur | Effet |
|---|---|---|---|
| Visiteur | Enclos | curiosité | objectifs |

##### Trajet Visiteurs vers/depuis les boutiques (tableau détaillé)

| Source | Destination | Déclencheur | Effet |
|---|---|---|---|
| Visiteur | Boutique | soif/envie | objectifs |

##### Trajet Visiteurs vers/depuis la billeterie (entrées/sorties du zoo) (tableau détaillé)

| Source | Destination | Déclencheur | Effet |
|---|---|---|---|
| Visiteur | Sortie | fin journée | objectifs |

### 6. Événements

#### Événements du Jeu  (tableau détaillé)

| Event | Déclencheur | Payload | Effet |
|---|---|---|---|
| `PASS_STARTED` | start | pass_id | visible |
| `PASS_ENDED` | end | pass_id | close |

#### Événements du Carte (tableau détaillé)

| Event | Déclencheur | Effet |
|---|---|---|
| `PASS_POPUP_LOGIN` | login | CTA |

#### Événements du Zoo (tableau détaillé)

| Event | Déclencheur | Effet |
|---|---|---|
| `PASS_XP_GAINED` | action zoo | xp + |

#### Événements du Ville / Visiteur (tableau détaillé)

| Event | Déclencheur | Effet |
|---|---|---|
| `PASS_VISITOR_GOAL` | satisfaction | xp + |

#### Événements du Visiteur (tableau détaillé)

| Event | Déclencheur | Effet |
|---|---|---|---|
| `PASS_PHOTO_BONUS` | photo | xp + |

#### Événements du Joueur (tableau détaillé)

| Event | Déclencheur | Effet |
|---|---|---|---|
| `PASS_PREMIUM_PURCHASED` | achat | premium |

### 7. Progression

#### Tableau des Upgrades (tableau détaillé)

| Niveau passe | XP requis | Free reward | Premium reward | Notes |
|---|---:|---|---|---|
| 1 | 100 | coins_100 | skin_tiger_hat | exemple |
| 30 | 3000 | skin_tiger_statue | theme_tiger_full | exemple |

### 8. Logique et Interfaces 

#### Pseudo-code Impacts (tableau détaillé)

| Fonction | Entrées | Sorties | Notes |
|---|---|---|---|
| `addPassXp` | action xp | pass_xp | cap/jour |
| `unlockLevels` | pass_xp | unlocked | monotone |
| `claimReward` | level, track | item | idempotent |

#### Messages d'Infos / Alerte (tableau détaillé)

| ID | Niveau | Message | Condition |
|---|---|---|---|
| `REWARD_LOCKED` | Warning | "Palier verrouillé." | xp insuffisant |
| `ALREADY_CLAIMED` | Info | "Déjà réclamé." | idempotence |

## Annexes UX/UI 

### 1. Expérience Utilisateur (UX)

#### Description UX (tableau détaillé)

| Parcours | But | Friction | Réduction clics |
|---|---|---|---|
| Suivre progression | motivation | scroll long | raccourci “prochain reward” |
| Réclamer | récupérer items | oubli | badge non réclamés |

#### Description UI (tableau détaillé)

| Composant | Contenu | États |
|---|---|---|
| Écran passe | rail paliers | free/premium |
| CTA premium | prix | purchased |

#### Emplacement (tableau détaillé)

| Zone UI | Position | Notes |
|---|---|---|
| HUD | bouton passe | badge |
| Modal | plein écran | scroll |

#### Intégration (tableau détaillé)

| Intégration | Contrat | Notes |
|---|---|---|
| Inventaire skins | ajout items | idempotent |
| VIP | conservation | gating |

#### Navigation (tableau détaillé)

| Action | Chemin | Résultat |
|---|---|---|
| Ouvrir passe | HUD | écran |
| Aller boutique | CTA | achat |

#### Événements (tableau détaillé)

| Event UI | Déclencheur | Effet |
|---|---|---|
| `OPEN_PASS` | clic | écran |
| `CLICK_CLAIM_REWARD` | clic | claim |

#### Assets Skinables

##### Musiques (tableau détaillé)

| Asset | Usage | Durée | Notes |
|---|---|---:|---|
| `pass_screen_loop.mp3` | écran | loop | thème saison |

##### Sons (tableau détaillé)

| Asset | Usage | Volume |
|---|---|---|
| `reward_claim.mp3` | claim | moyen |
| `level_unlock.mp3` | unlock | moyen |

##### Graphiques (tableau détaillé)

| Asset | Usage | Contraintes |
|---|---|---|
| `pass_track_free.png` | UI | - |
| `pass_track_premium.png` | UI | - |

##### Images (tableau détaillé)

| Asset | Usage |
|---|---|
| `pass_badge.png` | HUD |
| `pass_reward_icons.png` | paliers |

##### Vidéos (tableau détaillé)

| Asset | Usage | Durée |
|---|---|---:|
| `pass_intro.webm` | popup | 2.0s |

##### Animations (tableau détaillé)

| Animation | Déclencheur | Notes |
|---|---|---|
| jauge fill | xp gain | smooth |
| sparkles | claim | burst |

##### Couleurs (tableau détaillé)

| Token | Valeur | Usage |
|---|---|---|
| `pass_gold` | #D4AF37 | premium |
| `pass_red` | #C0392B | accent |

##### Textes (tableau détaillé)

| Clé | FR | EN |
|---|---|---|
| `pass.claim` | Réclamer | Claim |
| `pass.buy_premium` | Acheter Premium | Buy Premium |

##### Formes (tableau détaillé)

| Élément | Forme | Notes |
|---|---|---|
| Cartes reward | rectangles arrondis | - |
| Jauge | barre | - |
