builazoo/docs/specs/billeterie.md

# Spécifications : Billeterie

## Définition
Bâtiment d'entrée du zoo. Point d'apparition et de départ des visiteurs.

## Fonctionnalités
- **Entrée/Sortie** : Génère le flux de visiteurs.
- **Vente de tickets** : Génère des revenus par visiteur entrant.
- **Capacité** : Limite le nombre de visiteurs simultanés dans le zoo.

## Niveaux d'Amélioration (7 niveaux)
- **Coût** : Progressif par palier.
- **Effet** : Augmente le prix du ticket et la capacité maximale de visiteurs simultanés.
- **Ratio** : 1 unité couvre 20 visiteurs simultanés max.

# Annexes Techniques

## 1. Données et États
### Modèle de Données (JSON)
```json
{
  "id": "uuid",
  "type": "ticket_booth",
  "level": "integer (1-7)",
  "position": { "x": "int", "y": "int" },
  "stats": {
    "total_entries": "integer",
    "daily_revenue": "integer",
    "current_queue_length": "integer"
  },
  "entry_log": [
    { "timestamp": "timestamp", "visitor_count": 5, "revenue": 50 }
  ],
  "iso_x": "integer",
  "iso_y": "integer",
  "z_index": "integer"
}
```

### Caractéristiques Initiales
| Caractéristique | Valeur Initiale (Niv 1) |
| :--- | :--- |
| Prix Ticket | 10 pièces |
| Capacité Max | 20 visiteurs |

## 7. Progression
### Tableau des Upgrades
| Niveau | Coût (Pièces) | Prix Ticket | Capacité Max | Temps Construction |
| :--- | :--- | :--- | :--- | :--- |
| 1 | 0 (Base) | 10 | 20 | 0s |
| 2 | 200 | 12 | 40 | 0s |
| 3 | 400 | 15 | 70 | 0s |
| 4 | 800 | 18 | 110 | 0s |
| 5 | 1600 | 22 | 160 | 0s |
| 6 | 3200 | 28 | 220 | 0s |
| 7 | 6400 | 35 | 300 | 0s |

## 8. Logique et Interfaces
### Pseudo-code Impacts
```python
def process_entry(zoo):
    potential_visitors = calculate_attraction_flow(zoo)
    
    # Gestion de la file d'attente
    zoo.billeterie.current_queue_length += potential_visitors
    
    # Traitement des entrées (limité par la vitesse du guichet)
    entries_per_tick = get_entry_speed(zoo.billeterie.level)
    actual_entries = min(zoo.billeterie.current_queue_length, entries_per_tick)
    
    # Vérification capacité zoo
    if zoo.current_visitors + actual_entries > zoo.billeterie.capacity:
        actual_entries = zoo.billeterie.capacity - zoo.current_visitors
        emit_event("ZOO_FULL")
    
    zoo.billeterie.current_queue_length -= actual_entries
    
    for _ in range(actual_entries):
        spawn_visitor()
        player.add_coins(zoo.billeterie.ticket_price)
```

### Messages d'Infos / Alerte
| ID | Niveau | Message |
| :--- | :--- | :--- |
| `ZOO_FULL` | Alerte | "Le zoo est complet ! Agrandissez la billeterie." |
| `VIP_BUS` | Info | "Un bus de touristes arrive !" |
| `QUEUE_LONG` | Warning | "La file d'attente est trop longue, des visiteurs partent !" |

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


## 1. Expérience Utilisateur (UX)
### Consultation
**Description UX** : Le joueur clique sur la billeterie pour voir ses statistiques et son niveau.
**Description UI** : **Bottom Sheet** ou Panneau Latéral affichant le niveau actuel, la capacité, le prix du ticket et les revenus du jour.
**Emplacement** : Case Billeterie sur la grille du zoo.
**Intégration** : Bâtiment fixe.
**Navigation** : Clic -> Ouverture Panneau -> Fermeture.
**Événements** : `CLICK_BILLETERIE`.

#### Assets
- **Musiques** : Ambiance "Hall de Gare" (brouhaha léger).
- **Sons** : `ui_open.mp3`
- **Graphiques** : Pixel Art, style guichet.
- **Images** : `billeterie_lvl[1-7].png`
- **Vidéos** : Flux vidéo surveillance (fictif, décoratif).
- **Animations** : Légère surbrillance au survol.
- **Couleurs** : Palette UI standard.
- **Textes** : "Billeterie", "Niveau X", "Revenus : Y".
- **Formes** : Carré (case).

### Vue Isométrique
- **File d'attente** : Afficher physiquement les sprites des visiteurs qui attendent devant le guichet.
- **Portiques** : Animation d'ouverture/fermeture des barrières.

## Personnage contextuel (événements & interaction)
Voir `guichetiere.md`.

### Affichage
La guichetière s’affiche lorsque :
- la billetterie est **actionnée** (clic panneau, upgrade, consultation stats) ;
- un **événement** d’entrée survient (saturation, file longue, arrivée VIP).

### Déclencheurs (exemples)
| Event | Condition | Effet UI personnage |
|---|---|---|
| `CLICK_BILLETERIE` | clic bâtiment | portrait + synthèse (prix, capacité, file) |
| `ZOO_FULL` | capacité atteinte | bulle “Zoo complet” + CTA “Améliorer billetterie” |
| `QUEUE_LONG` | file > seuil | bulle “File longue” + CTA “Voir billetterie” |
| `VIP_BUS` | arrivée VIP | bulle “Bus VIP” + CTA “Voir entrée” |

### Skins & thèmes
Uniforme et guichet suivent `theme.md` ; variantes éventuelles via `inventaire_skins.md`.

## Définition

| Champ | Valeur |
|---|---|
| Concept | Bâtiment “billeterie” : point unique d’entrée/sortie des visiteurs et point de monétisation “tickets”. |
| Rôle | Transformer l’attractivité (ville → zoo) en entrées contrôlées (capacité/queue) et en revenus (prix ticket), avec signaux visibles (file, portiques, saturation). |
| Portée | Une instance fixe sur la carte zoo, connectée au réseau de chemins, agissant comme spawn/despawn visiteurs. |
| Contrainte | Aucun tracking externe/analytics ; flux et revenus calculés à la volée (lazy update), sans cache/mémorisation ; saturation doit produire message + event (pas silencieux). |

## Fonctions (tableau détaillé)

| Fonction | Déclencheur | Entrées | Sorties | Règles | Observabilité |
|---|---|---|---|---|---|
| Ouvrir panneau billeterie | clic bâtiment | `ticket_booth_id` | UI stats | montre prix/capacité/queue/revenus jour | Event `CLICK_BILLETERIE` |
| Calculer demandes d’entrée | tick logique | attractivité, villes, saison | `potential_visitors` | dépend distance ville + attractivité zoo | Event `VISITOR_DEMAND_COMPUTED` |
| Alimenter file | tick logique | `potential_visitors` | `current_queue_length` | clamp ≥ 0 | Event `QUEUE_UPDATED` |
| Convertir file en entrées | tick logique | level, queue | `actual_entries` | limité par vitesse guichet et capacité zoo | Event `VISITOR_ENTERED` |
| Encaisser ticket | entrée | ticket_price | coins + | atomicité par visiteur entré | Event `TICKET_SOLD` |
| Bloquer si zoo complet | capacité atteinte | `current_visitors` | entrée 0 | déclenche alerte + évaporation file (visiteurs partent) | Event `ZOO_FULL` |
| Gérer bus VIP | event | multiplicateur | pic entrées | bus si condition (réputation/ville riche) | Event `VIP_BUS` |
| Mesurer impatience | queue longue | temps attente | départs | si attente > seuil, départs + malus réputation léger | Event `QUEUE_LONG` |

## Icone de base

| Élément | Spécification |
|---|---|
| Représentation | Guichet + ticket + portique |
| Couleur dominante | Bleu/rouge (signalétique), or (coins) |
| Variantes | `billeterie_lvl_{1..7}_dir_{N,E,S,W}.png`, `icon_ticket_booth.png` |
| États | `open`, `busy` (queue), `full` (zoo complet), `vip_bus` (arrivée) |

## Interactions (tableau détaillé)

| Interaction | Type | Préconditions | Étapes UI | Résultat | Erreurs / Messages |
|---|---|---|---|---|---|
| Consulter stats | Consultation | - | clic billeterie | panneau stats | - |
| Upgrader | Action | coins ok | panneau → “Améliorer” | level +1 | `NOT_ENOUGH_COINS` |
| Voir file | Consultation | file > 0 | survol bâtiment | tooltip “X en attente” | - |
| Aller à la saturation | Navigation | `ZOO_FULL` | clic notif | focus billeterie | - |
| Forcer fermeture | Action (option future) | mode maintenance | toggle | entrées stoppées | `MAINTENANCE_REQUIRED` |

## Annexes Techniques

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

| Donnée / État | Type | Exemple | Source | Contraintes |
|---|---|---|---|---|
| `id` | uuid_v4 | `uuid_v4` | DB | - |
| `type` | string | `ticket_booth` | DB | constant |
| `level` | int | 3 | DB | 1..7 |
| `position.x` | int | 1 | DB | grid |
| `position.y` | int | 1 | DB | grid |
| `stats.total_entries` | int | 1280 | DB | cumul |
| `stats.daily_revenue` | int | 420 | DB | reset journalier in-game |
| `stats.current_queue_length` | int | 18 | DB/calcul | clamp ≥ 0 |
| `entry_log[].timestamp` | timestamp | - | DB | UTC |
| `entry_log[].visitor_count` | int | 5 | DB | batch |
| `entry_log[].revenue` | int | 50 | DB | batch |
| `iso_x` | int | 120 | DB/calcul | rendu |
| `iso_y` | int | 88 | DB/calcul | rendu |
| `z_index` | int | 12088 | calcul | profondeur |

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

| Caractéristique | Valeur initiale | Unité | Notes |
|---|---:|---|---|
| Prix ticket (lvl1) | 10 | coins | base |
| Capacité max (lvl1) | 20 | visiteurs | base |
| Vitesse guichet (lvl1) | 2 | visiteurs/tick | file |
| Seuil queue longue | 25 | visiteurs | message + départs |

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

| Score | Valeur initiale | Plage | Impact |
|---|---:|---|---|
| Satisfaction d’entrée | 50 | 0..100 | queue longue la baisse |
| Taux départ file | 0% | 0..100% | impatience |

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

| Phase | Déclencheur | Entrées | Sorties | Invariants |
|---|---|---|---|---|
| Apparition | création zoo | - | bâtiment présent | fixe |
| Fonctionnement | zoo ouvert | attractivité | entrées | capacité respectée |
| Saturation | zoo plein | - | entrées stoppées | alerte obligatoire |
| Upgrade | action joueur | coins | level ↑ | monotone |

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

| Condition | Seuil | Opérateur | Résultat |
|---|---:|---|---|
| Zoo créé | true | est | billeterie placée |

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

| Condition | Seuil | Opérateur | Résultat |
|---|---:|---|---|
| - | - | - | bâtiment persistant |

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

| Élément | Hérité | Règle |
|---|---|---|
| Niveau | Oui | persiste |
| Statistiques | Oui | logs conservés, pas d’analytics |

### 3. Impacts Environnementaux

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

| Condition | Effet billeterie | Notes |
|---|---|---|
| Canicule | flux -10% | visiteurs évitent attente au soleil |
| Froid extrême | flux -15% | sortie plus rapide |

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

| Biome | Effet | Notes |
|---|---|---|
| Proche océan (frais) | impatience - | queue tolérée |
| Boue autour entrée | impatience + | pénalise |

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

| Saison | Effet | Notes |
|---|---|---|
| Été | demande +20% | vacances |
| Hiver | demande -30% | froid |

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

| Période | Effet | Notes |
|---|---|---|
| Matin | pics d’entrée | 9h-12h |
| Soir | pics de sortie | 17h-19h |

### 4. Impacts Biologiques et Sociaux

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

| Facteur | Effet sur taux | Condition |
|---|---|---|
| Bébés visibles | satisfaction entrée +5 | marketing “naissances” |

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

| Cas | Effet | Condition |
|---|---|---|
| Incident visible à l’entrée | flux -40% | pendant 1 jour in-game |

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

| Ressource | Effet | Condition |
|---|---|---|
| Stand boisson proche | impatience - | file longue |

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

| Action/État | Gain | Rayon | Notes |
|---|---:|---:|---|
| Entrée fluide | +5 | 8 cases | file courte |
| File longue | -10 | 8 cases | visiteurs partent |

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

| Action/État | Effet animaux | Condition |
|---|---|---|
| Foule bruyante | stress + | enclos proche entrée |

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

| Facteur | Variation | Condition |
|---|---:|---|
| Upgrade billeterie | + | valeur zoo | capacité |

### 5. Impacts Logistiques et Économiques

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

| Paramètre | Effet | Condition |
|---|---|---|
| Bus VIP | entrées batch | event `VIP_BUS` |

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

| Paramètre | Effet | Condition |
|---|---|---|
| Naissances annoncées | demande + | saison |

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

| Paramètre | Effet | Condition |
|---|---|---|
| Nouveaux animaux placés près entrée | intérêt + | visiteurs |

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

| Paramètre | Effet | Condition |
|---|---|---|
| Marketing recherche | demande + | upgrade futur |

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

| Paramètre | Effet | Condition |
|---|---|---|
| Offre rare | pics | annonce |

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

| Paramètre | Effet | Condition |
|---|---|---|
| Portiques auto | entrées/tick + | level élevé |

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

| Poste | Coût | Unité | Condition |
|---|---:|---|---|
| Impression tickets | 100 | $/semaine | lore |
| Maintenance portiques | 20 | coins/semaine | level ≥ 3 |

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

| Poste | Coût | Unité | Condition |
|---|---:|---|---|
| Signalétique | 10 | coins/semaine | esthétique |

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

| Poste | Coût | Unité | Condition |
|---|---:|---|---|
| Perte opportunité | ticket non vendu | coins | queue trop longue |

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

| Poste | Coût | Unité | Condition |
|---|---:|---|---|
| Agent accueil | 1500 | $/mois | lore |

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

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

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

| Poste | Coût | Unité | Condition |
|---|---:|---|---|
| Vitrine bébés | 50 | coins/semaine | option |

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

| Poste | Coût | Unité | Condition |
|---|---:|---|---|
| Eau file d’attente | 5 | coins/jour | été |

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

| Poste | Coût | Unité | Condition |
|---|---:|---|---|
| Signal “nouvel animal” | 5 | coins | panneau |

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

| Poste | Coût | Unité | Condition |
|---|---:|---|---|
| Bus touristes | 25 | coins/event | `VIP_BUS` |

#### Trajet Visiteurs

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

| Source | Destination | Déclencheur | Effet |
|---|---|---|---|
| Ville | Billeterie | demande calculée | spawn file |

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

| Source | Destination | Déclencheur | Effet |
|---|---|---|---|
| Billeterie | Enclos | plan visite | route via chemins |

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

| Source | Destination | Déclencheur | Effet |
|---|---|---|---|
| Enclos | Boutique | faim/soif | détour |

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

| Source | Destination | Déclencheur | Effet |
|---|---|---|---|
| Zoo | Billeterie | fin visite | sortie |

### 6. Événements

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

| Event | Déclencheur | Payload | Effet |
|---|---|---|---|
| `TICKET_SOLD` | entrée | price | coins + |
| `ZOO_FULL` | capacité | current/max | stop entrées |
| `QUEUE_LONG` | queue > seuil | length | départs + |
| `VIP_BUS` | event | count | entrées batch |

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

| Event | Déclencheur | Effet |
|---|---|---|
| `FOCUS_TICKET_BOOTH` | clic notif | caméra |

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

| Event | Déclencheur | Effet |
|---|---|---|
| `VISITOR_SPAWNED_AT_ENTRY` | entrée | spawn point |

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

| Event | Déclencheur | Effet |
|---|---|---|
| `CITY_FLOW_DISPATCHED` | calcul | demande |

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

| Event | Déclencheur | Effet |
|---|---|---|
| `VISITOR_LEAVES_QUEUE` | impatience | départ |

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

| Event | Déclencheur | Effet |
|---|---|---|
| `PLAYER_UPGRADES_TICKET_BOOTH` | UI | stats maj |

### 7. Progression

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

| Niveau | Coût | Effet | Débloque |
|---|---:|---|---|
| 3 | 400 | portiques visibles + vitesse guichet | anim porte |
| 5 | 1600 | file plus courte (vitesse) | satisfaction + |
| 7 | 6400 | capacité 300 + prix 35 | “grand hall” |

### 8. Logique et Interfaces 

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

| Fonction | Entrées | Sorties | Notes |
|---|---|---|---|
| `getEntrySpeed` | level | int | visiteurs/tick |
| `computePotentialVisitors` | zoo, villes, saison | int | à la volée |
| `processEntry` | zoo, booth | int | encaisse + spawn |

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

| ID | Niveau | Message | Condition |
|---|---|---|---|
| `ZOO_FULL` | Alerte | "Le zoo est complet." | capacité atteinte |
| `QUEUE_LONG` | Warning | "La file d'attente est trop longue." | queue > seuil |
| `VIP_BUS` | Info | "Un bus de touristes arrive." | event |

## Annexes UX/UI 

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

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

| Parcours | But | Friction | Réduction clics |
|---|---|---|---|
| Voir revenus | décider upgrade | stats dispersées | panneau unique billeterie |
| Réagir à saturation | éviter pertes | notif | clic notif → focus |

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

| Composant | Contenu | États |
|---|---|---|
| Panneau billeterie | prix/capacité/revenus | normal/full |
| File visuelle | sprites visiteurs | courte/longue |
| Badge bus VIP | icône bus | visible |

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

| Zone UI | Position | Notes |
|---|---|---|
| Carte zoo | entrée | file visible |
| HUD | compteur coins | feedback pièces |

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

| Intégration | Contrat | Notes |
|---|---|---|
| `visiteur.md` | spawn/despawn | flux |
| `ville.md` | demande | distance |

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

| Action | Chemin | Résultat |
|---|---|---|
| Ouvrir stats | clic bâtiment | panneau |
| Upgrader | panneau → bouton | level ↑ |
| Focus | clic notif | caméra |

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

| Event UI | Déclencheur | Effet |
|---|---|---|
| `CLICK_BILLETERIE` | clic | ouvre |
| `CLICK_UPGRADE_TICKET_BOOTH` | bouton | upgrade |

#### Assets Skinables

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

| Asset | Usage | Durée | Notes |
|---|---|---:|---|
| `ticket_booth_crowd_loop.mp3` | proximité entrée | loop | discret |

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

| Asset | Usage | Volume |
|---|---|---|
| `gate_open.mp3` | portiques | bas |
| `coin_jingle.mp3` | ticket vendu | bas |
| `ui_denied.mp3` | zoo plein | moyen |

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

| Asset | Usage | Contraintes |
|---|---|---|
| `ticket_booth_ui_panel.png` | panneau | scalable |
| `queue_indicator.png` | badge | lisible |
| `vip_bus_icon.png` | bus | contraste |

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

| Asset | Usage |
|---|---|
| `billeterie_lvl1.png` | bâtiment |
| `billeterie_lvl7.png` | bâtiment |

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

| Asset | Usage | Durée |
|---|---|---:|
| `ticket_gate_cycle.webm` | portiques | 1.0s |

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

| Animation | Déclencheur | Notes |
|---|---|---|
| pièces qui volent | ticket vendu | 0.6s |
| bounce badge | queue longue | 0.4s |

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

| Token | Valeur | Usage |
|---|---|---|
| `ticket_blue` | #1976D2 | signalétique |
| `ticket_gold` | #D4AF37 | revenus |
| `ticket_alert_red` | #D32F2F | saturation |

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

| Clé | FR | EN |
|---|---|---|
| `ticket_booth.title` | Billeterie | Ticket booth |
| `ticket_booth.capacity` | Capacité | Capacity |
| `ticket_booth.queue_long` | File trop longue. | Queue too long. |

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

| Élément | Forme | Notes |
|---|---|---|
| Panneau | rectangle arrondi | lisible |
| Badge | rond | constant |