builazoo/docs/specs/accueil_animaux.md

# Spécifications : Accueil des Animaux

## Définition
Zone tampon pour les nouveaux animaux arrivant dans le zoo (achats adultes ou transferts). C'est le point d'entrée unique pour tout animal avant son placement en enclos.

## Fonctionnalités
- **Acclimatation** : Période obligatoire avant de pouvoir placer l'animal sur la grille active.
- **Stockage temporaire** : Évite de devoir placer immédiatement un animal acheté si le terrain n'est pas prêt.
- **Inspection** : Permet au joueur de voir les stats de l'animal avant placement.

## Niveaux d'Amélioration (7 niveaux)
- **Coût** : Progressif par palier.
- **Effet** : Réduit le temps d'acclimatation. Améliore le potentiel reproducteur de l'animal entrant.
- **Ratio** : 1 unité couvre 1 animal en cours d'accueil.

# Annexes Techniques

## 1. Données et États
### Modèle de Données (JSON)
```json
{
  "id": "uuid",
  "type": "building_reception",
  "created_at": "timestamp",
  "updated_at": "timestamp",
  "level": "integer (1-7)",
  "position": { "x": "integer", "y": "integer" },
  "slots": [
    {
      "slot_id": "integer (0-index)",
      "animal_id": "uuid (nullable)",
      "status": "enum (EMPTY, OCCUPIED, READY)",
      "arrival_time": "timestamp",
      "acclimatization_end_time": "timestamp",
      "bonus_applied": "boolean"
    }
  ],
  "iso_x": "integer",
  "iso_y": "integer",
  "z_index": "integer"
}
```

### Caractéristiques Initiales
| Caractéristique | Valeur Initiale (Niv 1) | Valeur Max (Niv 7) |
| :--- | :--- | :--- |
| Temps Acclimatation | 600 secondes (10 min) | 0 secondes (Instantané) |
| Capacité | 1 animal | 7 animaux |

### Scores Initiaux
| Score | Valeur Initiale | Plage (Min-Max) | Impact |
| :--- | :--- | :--- | :--- |
| Confort Quarantaine | 60 | 0-100 | Modifie le stress initial de l’animal lors du placement (\(-\)stress = +confort). |
| Risque Contamination | 2% | 0-25% | Probabilité d’incident sanitaire (quarantaine prolongée, coût supplémentaire) par animal accueilli. |
| Traçabilité | 80 | 0-100 | Qualité des infos affichées au joueur (traits révélés, historique). |

## 2. Cycles de Vie et Apparition
### Conditions d'Apparition
Présent au démarrage du jeu (Tutorial ou Nouvelle Partie). Position fixe généralement près de l'entrée.

### Conditions de Disparition
Indestructible. Ne peut pas être vendu ni déplacé (sauf si feature de réaménagement global).

### Hérédité
| Parent | Trait Transmis | Probabilité | Mutation Possible |
|---|---|---|---|
| Accueil Niv 4+ | Trait temporaire “Calme” (+5 Satisfaction Visiteurs à proximité après placement) | 100% | Non (effet temporaire, non génétique) |
| Accueil Niv 7 | Trait temporaire “Confiant” (stress \(-15\) au placement) | 100% | Non |

## 3. Impacts Environnementaux
### Impact Température
Zone neutre (T° idéale simulée). Les animaux ne subissent pas de dégâts de température ici.

### Impact Milieu (Biome)
Zone neutre. Compatible avec tous les biomes d'animaux.

### Impact Saisons
Protégé des intempéries.

### Impact Heure / Jour-Nuit
Fonctionne 24/7. Pas de pénalité la nuit.

## 4. Impacts Biologiques et Sociaux
### Impact Reproduction
**Bonus Repro** : Un animal passant par un accueil de haut niveau gagne un bonus temporaire de fertilité.
- Niv 1-3 : +0%
- Niv 4-6 : +10% fertilité (durée 2 jours in-game)
- Niv 7 : +25% fertilité (durée 5 jours in-game)

### Impact Mort
Pas de mort possible en zone d'accueil (Stase). Les jauges de faim/soif/santé sont gelées.

### Impact Nourriture
Nourri automatiquement (coût nul ou inclus dans les frais de gestion globaux).

### Impact Attractivité (Visiteurs/Animaux)
| Action/État | Gain Attractivité | Rayon d'action |
|---|---:|---:|
| Façade entretenue (Propreté > 80) | +5 | 6 cases |
| File d’attente visible (Capacité saturée) | -10 | 8 cases |
| Livraison spectaculaire (animal rare) | +20 | 10 cases |

### Impact Valeur
| Facteur | Variation Prix | Condition |
|---|---:|---|
| Niveau Accueil | +5% / niveau | Appliqué à la valeur du zoo (bâtiment clé non revendable). |
| Historique sans incident | +10% | Si aucun événement `QUARANTINE_ALERT` sur 7 jours in-game. |

## 5. Impacts Logistiques et Économiques
### Vitesse (Camion/Nurserie/Accueil/Recherche/Labo/Visite)
**Réduction Temps Acclimatation** :
| Niveau | Temps Base | Réduction % |
| :--- | :--- | :--- |
| 1 | 10 min | 0% |
| 2 | 8 min | 20% |
| 3 | 6 min | 40% |
| 4 | 4 min | 60% |
| 5 | 2 min | 80% |
| 6 | 1 min | 90% |
| 7 | Instantané | 100% |

### Dépenses (Boutiques/Visiteurs)
| Poste | Coût Hebdo | Maintenance |
|---|---:|---:|
| Consommables quarantaine | 50 pièces | 10 pièces |
| Nettoyage & désinfection | 30 pièces | 5 pièces |
| Contrôle vétérinaire | 80 pièces | 0 pièce (service périodique) |

### Trajet Visiteurs
| Trajet | Condition | Effet | Détails |
|---|---|---|---|
| Visiteurs passent devant | Chemin adjacent | Attraction faible | Le bâtiment n’est pas une attraction nominale, mais une façade visible peut influer sur l’ambiance. |
| Visiteurs évitent la zone | `QUARANTINE_ALERT` actif | Déviation | Les visiteurs recalculent leur chemin pour éviter un rayon de 6 cases autour. |

## 6. Événements
### Événements du Jeu / Carte / Zoo / Ville / Visiteur
*   **Arrivée (`ANIMAL_ARRIVAL`)** : Animal livré par camion, entre dans un slot libre.
*   **Prêt (`ANIMAL_READY`)** : Le temps d'acclimatation est écoulé.
*   **Placement (`ANIMAL_PLACED`)** : Le joueur sort l'animal de l'accueil vers un enclos.

## 7. Progression
### Tableau des Upgrades
| Niveau | Coût (Pièces) | Capacité | Temps Acclimatation | Temps Construction |
| :--- | :--- | :--- | :--- | :--- |
| 1 | 100 | 1 | 10 min | 0s |
| 2 | 200 | 2 | 8 min | 10s |
| 3 | 400 | 3 | 6 min | 30s |
| 4 | 800 | 4 | 4 min | 1m |
| 5 | 1600 | 5 | 2 min | 2m |
| 6 | 3200 | 6 | 1 min | 5m |
| 7 | 6400 | 7 | 0 min | 10m |

## 8. Logique et Interfaces
### Pseudo-code Impacts
```python
def update_reception(reception_center, current_time):
    # Vérification de l'intégrité
    if not reception_center or not reception_center.slots:
        return error("Invalid reception center")

    for slot in reception_center.slots:
        if slot.status == "OCCUPIED":
            # Vérifier si le temps est écoulé
            if current_time >= slot.acclimatization_end_time:
                slot.status = "READY"
                trigger_event("ANIMAL_READY", {"animal_id": slot.animal_id})
                
def add_animal_to_reception(reception_center, animal):
    # Trouver un slot vide
    empty_slot = find_first_empty_slot(reception_center.slots)
    
    if not empty_slot:
        return error("RECEPTION_FULL")
        
    # Calcul du temps selon le niveau
    duration = get_acclimatization_duration(reception_center.level)
    
    empty_slot.animal_id = animal.id
    empty_slot.arrival_time = now()
    empty_slot.acclimatization_end_time = now() + duration
    empty_slot.status = "OCCUPIED"
    
    return success()
```

### Messages d'Infos / Alerte
| ID | Niveau | Message | Condition |
| :--- | :--- | :--- | :--- |
| `ANIMAL_READY` | Info | "Un nouvel animal est prêt à rejoindre le zoo !" | `slot.status` passe à `READY` |
| `RECEPTION_FULL` | Warning | "Accueil saturé, impossible d'acheter." | Tentative d'achat sans slot libre |
| `PLACEMENT_ERROR` | Error | "Impossible de placer ici (Enclos plein / Biome incompatible)." | Drag & Drop invalide |

# 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)
### Arrivée Animal (Passif)
**Description UX** : Le camion décharge un animal. Il apparaît dans l'Accueil en mode "Attente".
**Description UI** : Notification "Livraison effectuée". L'icône de l'Accueil change (ex: porte fermée -> porte avec caisse devant).
**Notification Push** : "Votre [Animal] est arrivé à l'accueil !" envoyée si le joueur est hors ligne.
**Emplacement** : Case Accueil.
**Intégration** : Suite de l'action Camion.
**Navigation** : Clic sur Accueil → Bottom Sheet “Accueil” (liste slots) → action “Placer” ouvre le mode placement sur la carte du zoo.
**Événements** : `DELIVERY_COMPLETE`.

#### Assets
- **Musiques** : `ambience_stable_soft.mp3` (léger, discret, pas intrusif).
- **Sons** : `truck_door.mp3`, `crate_drop.mp3`.
- **Graphiques** : Sprite Caisse en bois.
- **Images** : `reception_building.png` (bâtiment), `reception_icon.png` (icône), `badge_quarantine.png` (badge).
- **Vidéos** : `delivery_short.webm` (2s, loop optionnel sur notif).
- **Animations** : Camion qui repart.
- **Couleurs** : Marron (Caisse).
- **Textes** : `RECEPTION_DELIVERY_DONE` = "Livraison effectuée", `RECEPTION_ANIMAL_ARRIVED` = "Votre {animalName} est arrivé à l'accueil !"
- **Formes** : Bulle (notif), badge rond (état).

### Consultation & Acclimatation (Consultation)
**Description UX** : Le joueur vérifie le temps restant avant de pouvoir placer l'animal.
**Description UI** : **Bottom Sheet** listant les animaux en transit. Barre de progression "Acclimatation" pour chacun.
**Emplacement** : Modal Accueil.
**Intégration** : Liste verticale.
**Navigation** : Clic Accueil -> Modal.
**Événements** : `OPEN_RECEPTION`.

#### Assets
- **Musiques** : `ui_modal_soft.mp3` (jingle court).
- **Sons** : `ui_open.mp3`
- **Graphiques** : Style "Quarantaine" ou "Étable propre".
- **Images** : Portrait animal.
- **Vidéos** : `progress_fill.webm` (0.8s loop) pour la barre d’acclimatation (optionnel).
- **Animations** : Barre de progression qui avance.
- **Couleurs** : Orange (En cours), Vert (Prêt).
- **Textes** : "Prêt dans X min".
- **Formes** : Barres arrondies.

### Transfert vers Zoo (Action)
**Description UX** : L'animal est prêt. Le joueur le glisse vers le zoo.
**Description UI** : Bouton "Placer" ou Drag & Drop depuis la liste.
**Alternative** : Tap to Select -> Tap to Place.
**Emplacement** : Modal Accueil -> Carte Zoo.
**Intégration** : Mode placement (comme Nurserie).
**Navigation** : Drag -> Drop.
**Événements** : `PLACE_ANIMAL`.

#### Assets
- **Musiques** : `ui_confirm_place.mp3` (jingle court de confirmation).
- **Sons** : `animal_happy.mp3` (cri de l'animal).
- **Graphiques** : Sprite Animal.
- **Images** : `placement_ghost_ok.png`, `placement_ghost_ko.png` (surbrillance vert/rouge).
- **Vidéos** : `placement_glow.webm` (1.2s, non loop).
- **Animations** : Animal qui saute de joie au placement.
- **Couleurs** : Vert (#2ECC71) placement valide, Rouge (#E74C3C) placement invalide, Ambre (#F39C12) état “en acclimatation”.
- **Textes** : `BTN_PLACE` = "Placer", `RECEPTION_READY` = "Prêt"
- **Formes** : Badge “!” (prêt), sablier (en cours).

### Vue Isométrique
- **Sprite Bâtiment** : 4 directions isométriques (Nord-Est, Sud-Est, Sud-Ouest, Nord-Ouest) pour s'aligner avec les chemins.
- **Occlusion** : Le bâtiment doit être semi-transparent si le joueur passe la souris derrière (pour voir les objets cachés).
- **Indicateur d'état** : Une icône flottante (bulle) au-dessus du bâtiment indique si un animal est prêt (point d'exclamation vert) ou en cours (sablier).
- **Z-Index** : Doit être trié correctement par rapport aux visiteurs passant devant.