# Spécifications : Case de Zoo (Générique)

## Définition
Case spécifique à la grille du zoo, pouvant accueillir les éléments de gestion.

## Types de Contenu Possibles
- **Bâtiments** : Billeterie, Nurserie, Boutique, Centre de Recherche, École, Accueil Animaux.
- **Animaux** : Bébés matures, Animaux adultes.
- **Éléments Mobiles** : Visiteurs, Camion (sur sa zone dédiée).
- **Vide** : Terrain libre pour construction ou placement.

## Propriétés Spécifiques
- **Occupation** : Une case ne peut contenir qu'un seul élément principal (bâtiment/animal) à la fois.
- **Visite** : Enregistre la date de dernier passage d'un visiteur (pour la règle de disparition).
- **Qualité** : Indicateur visuel d'adéquation avec l'animal posé dessus (Jaunissement, Givre).

## Liste des Cases Spéciales (cf. Carte Zoo)
- Agrandissement
- Recherche
- Billeterie
- Nurserie
- Accueil
- Nourriture
- Camion

# Annexes Techniques

## 1. Données et États
### Modèle de Données (JSON)
Hérite de `Case (Générique)`.
```json
{
  "last_visit_time": "timestamp | null",
  "visit_count_total": "integer",
  "visit_count_day": "integer",
  "heatmap_score": "float (0-100)",
  "quality_score": "float (0-100)",
  "pathing": {
    "walkable": "boolean",
    "movement_cost": "float (>= 1.0)",
    "preferred": "boolean (true for path tiles)"
  },
  "zoo_specific_flags": [
    "enum('premium_spot','near_entry','near_shop','near_enclosure','staff_only')"
  ]
}
```

### Contraintes (Invariants)
*   **Walkable** : une case avec `content_type` bâtiment/animal est généralement `walkable=false` pour les visiteurs (sauf exceptions design).
*   **last_visit_time** : mis à jour uniquement quand un visiteur “observe” réellement (pas juste traverse) si la mécanique de “visite” est distincte.
*   **movement_cost** : > 1.0 sur herbe/boue, = 1.0 sur chemins, < 1.0 interdit (évite vitesse infinie).

### Caractéristiques Initiales
| Caractéristique | Valeur Initiale |
| :--- | :--- |
| Dernière Visite | Création du zoo |
| Qualité | 100 |

### Scores Initiaux
**Passages** : 0 (Heatmap de fréquentation).
**Propreté** : 100 (aucun déchet).
**Coût de marche** : 1.2 (herbe) par défaut, 1.0 (chemin) si la case est convertie.

## 2. Cycles de Vie et Apparition
### Conditions d'Apparition
Génération zoo.

### Conditions de Disparition
**Jamais** : Une case ne disparaît pas, elle change juste de contenu.

### Hérédité
**Qualité du Sol** : Un sol bien entretenu (fertilisé) garde ses bonus après un reset partiel.

## 3. Impacts Environnementaux
### Impact Température
Voir `case_generique.md`.

### Impact Milieu (Biome)
Voir `case_generique.md`.

### Impact Saisons
**Neige** : La case devient blanche en hiver (si T° < 0).

### Impact Heure / Jour-Nuit
**Ombres** : Les ombres des objets sur la case tournent avec le soleil.

## 4. Impacts Biologiques et Sociaux
### Impact Reproduction
**Lieu de rencontre** : Les cases "Buissons" favorisent les rencontres.

### Impact Mort
**Lieu de décès** : Une case où un animal est mort garde une "odeur" (malus stress) pendant 24h.

### Impact Nourriture
**Pâturage** : Une case herbeuse peut être broutée (devient terreuse).

### Impact Attractivité (Visiteurs/Animaux)
**Vue** : Une case "Point de Vue" (hauteur) augmente l'attractivité des animaux alentour.

### Impact Valeur
**Emplacement** : Une case proche de l'entrée vaut plus cher (emplacement premium pour boutiques).

## 5. Impacts Logistiques et Économiques
### Vitesse (Camion/Nurserie/Accueil/Recherche/Labo/Visite)
**Revêtement** : Herbe (Lent), Terre (Moyen), Pavés (Rapide).

### Dépenses (Boutiques/Visiteurs)
**Nettoyage** : Coût si la case est sale (déchets visiteurs).

### Trajet Visiteurs
**Obstacle** : Une case occupée par un bâtiment ou de l'eau est infranchissable (sauf pont).

## 6. Événements
### Événements du Jeu / Carte / Zoo / Ville / Visiteur
*   **Passage Visiteur** : Met à jour `last_visit_time`.
*   **Salissure** : Apparition d'un déchet.

## 7. Progression
### Tableau des Upgrades
Voir `achat_upgrade_case.md`.

## 8. Logique et Interfaces
### Pseudo-code Impacts
```
function checkAnimalDisappearance(case):
  if currentTime - case.last_visit_time > MAX_TIME_WITHOUT_VISIT:
    removeAnimal(case.content)
```

### Messages d'Infos / Alerte
| ID | Niveau | Message |
| :--- | :--- | :--- |
| `CASE_DIRTY` | Info | "Une case est sale." |
| `PATH_BLOCKED` | Warning | "Chemin bloqué : les visiteurs recalculent leur trajet." |
| `ANIMAL_NOT_VISITED` | Warning | "Un animal n'a pas été observé depuis longtemps." |

# 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)
### Sélection (Action)
**Description UX** : Clic sur une case zoo.
**Description UI** : Highlight + Menu contextuel adapté au contenu (Animal -> Stats, Bâtiment -> Upgrade, Vide -> Construire).
**Emplacement** : Grille.
**Intégration** : Standard.
**Navigation** : Clic.
**Événements** : `SELECT_ZOO_CASE`.

#### Assets
- **Musiques** : Son "Click".
- **Sons** : `select_soft.mp3`.
- **Graphiques** : Cadre sélection.
- **Images** : Icône Menu Contextuel.
- **Vidéos** : Effet de sélection (contour brillant).
- **Animations** : Rebondissement léger du contenu.
- **Couleurs** : Blanc.
- **Textes** : "Case [X,Y]".
- **Formes** : Carré.

## Définition

| Champ | Valeur |
|---|---|
| Concept | Case “zoo” : spécialisation de `case_generique` avec contraintes d’occupation, métriques de visite, et signaux qualité/propreté. |
| Rôle | Supporter le gameplay de placement (animal/bâtiment), le pathfinding (walkable/cost), et la logique “animal observé” (last_visit_time). |
| Portée | Une tuile de la carte du zoo, identifiée par coordonnées, rendue en isométrie. |
| Contrainte | Mesures dérivées (heatmap, quality_score) calculées à la volée ; pas de fallback : si `content_type` incohérent => log + erreur. |

## Fonctions (tableau détaillé)

| Fonction | Déclencheur | Entrées | Sorties | Règles | Observabilité |
|---|---|---|---|---|---|
| Sélectionner case | clic | x,y | menu contexte | actions selon contenu | Event `SELECT_ZOO_CASE` |
| Résoudre walkable | update terrain | content_type | `pathing.walkable` | bâtiment/animal => false (sauf exceptions) | Event `PATHING_UPDATED` |
| Mettre à jour last_visit_time | visiteur observe | visitor_id | timestamp | observe != traverse | Event `CASE_VISITED` |
| Accumuler heatmap | passage | dt | heatmap_score | 0..100 | Event `HEATMAP_UPDATED` |
| Dégrader propreté | déchets | visitor behavior | cleanliness ↓ | clamp 0..100 | Event `CASE_DIRTY` |
| Mettre à jour qualité | compat animal/terrain | biome/temp | quality_score | signaux visuels | Event `CASE_QUALITY_UPDATED` |

## Icone de base

| Élément | Spécification |
|---|---|
| Représentation | Tuile losange + marqueur |
| Couleur dominante | dépend biome/terrain |
| Variantes | `icon_tile.png`, `icon_tile_dirty.png` |
| États | `dirty`, `fertilized`, `frozen`, `muddy` |

## Interactions (tableau détaillé)

| Interaction | Type | Préconditions | Étapes UI | Résultat | Erreurs / Messages |
|---|---|---|---|---|---|
| Construire ici | Action | case vide | menu → item → place | occupancy building | `CELL_OCCUPIED` |
| Placer animal | Action | enclos compatible | drag/drop | occupancy animal | `BIOME_INCOMPATIBLE` |
| Nettoyer | Action | sale | outil nettoyage | cleanliness ↑ | `NO_STAFF` |

## Personnage contextuel (événements & interaction)
La case est actionnée via la sélection sur la carte du zoo. Le personnage contextuel attendu est le **joueur actif** (avatar) : voir `avatar_joueur.md`.

### Déclencheurs (exemples)
| Event / Message | Condition | Effet UI personnage |
|---|---|---|
| `SELECT_ZOO_CASE` | clic case | avatar présent dans le panneau contexte |
| `CELL_OCCUPIED` / `BIOME_INCOMPATIBLE` | action refusée | avatar affiche la cause et l’action suivante possible |
| `CASE_DIRTY` | case sale | avatar propose CTA “Nettoyer” (si action permise) |

### Skins & thèmes
Le rendu du portrait/overlay suit `theme.md` et `inventaire_skins.md`.

## Annexes Techniques

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

| Donnée / État | Type | Exemple | Source | Contraintes |
|---|---|---|---|---|
| `last_visit_time` | timestamp \| null | - | DB | UTC |
| `visit_count_total` | int | 120 | DB | cumul |
| `visit_count_day` | int | 12 | DB | reset day |
| `heatmap_score` | float | 35.5 | calcul | 0..100 |
| `quality_score` | float | 92.0 | calcul | 0..100 |
| `pathing.walkable` | boolean | true | calcul | dépend contenu |
| `pathing.movement_cost` | float | 1.2 | config | >=1.0 |
| `zoo_specific_flags[]` | enum[] | `near_entry` | DB | - |

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

| Caractéristique | Valeur initiale | Unité | Notes |
|---|---:|---|---|
| Propreté | 100 | pts | init |
| Fertilité | 0 | pts | init |
| Coût marche herbe | 1.2 | coef | default |

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

| Score | Valeur initiale | Plage | Impact |
|---|---:|---|---|
| Passages | 0 | 0..∞ | heatmap |
| Qualité | 100 | 0..100 | rendu |

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

| Phase | Déclencheur | Entrées | Sorties | Invariants |
|---|---|---|---|---|
| Création | génération map | biome | case | existe toujours |
| Occupation | placement | entity | occupancy | un principal |
| Nettoyage | action | outil | propreté ↑ | clamp |

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

| Condition | Seuil | Opérateur | Résultat |
|---|---:|---|---|
| Génération zoo | true | est | case créée |

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

| Condition | Seuil | Opérateur | Résultat |
|---|---:|---|---|
| - | - | - | case persiste |

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

| Élément | Hérité | Règle |
|---|---|---|
| Sol fertilisé | Oui | garde bonus soft reset |
| Heatmap | Non | recalcul |

### 3. Impacts Environnementaux

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

| Condition | Effet case | Notes |
|---|---|---|
| < 0°C | flag `frozen` | givre |

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

| Biome | Effet | Notes |
|---|---|---|
| prairie | herbe repousse | nourriture |

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

| Saison | Effet | Notes |
|---|---|---|
| hiver | `snowy` | visuel |

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

| Période | Effet | Notes |
|---|---|---|
| nuit | ombres tournent | rendu |

### 4. Impacts Biologiques et Sociaux

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

| Facteur | Effet sur taux | Condition |
|---|---|---|
| buissons | +5% | proximité enclos |

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

| Cas | Effet | Condition |
|---|---|---|
| odeur | stress + | 24h in-game |

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

| Ressource | Effet | Condition |
|---|---|---|
| pâturage | herbe→terre | animal broute |

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

| Action/État | Gain | Rayon | Notes |
|---|---:|---:|---|
| point de vue | + | 4 cases | hauteur |

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

| Action/État | Effet animaux | Condition |
|---|---|---|
| foule | stress + | densité |

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

| Facteur | Variation | Condition |
|---|---:|---|
| near_entry | + | premium spot |

### 5. Impacts Logistiques et Économiques

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

| Paramètre | Effet | Condition |
|---|---|---|
| revêtement | vitesse ± | chemin/pavés |

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

| Paramètre | Effet | Condition |
|---|---|---|
| placement mode | overlay | sortie bébé |

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

| Paramètre | Effet | Condition |
|---|---|---|
| placement mode | overlay | sortie animal |

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

| Paramètre | Effet | Condition |
|---|---|---|
| - | neutre | - |

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

| Paramètre | Effet | Condition |
|---|---|---|
| - | neutre | - |

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

| Paramètre | Effet | Condition |
|---|---|---|
| cost | route | A* |

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

| Poste | Coût | Unité | Condition |
|---|---:|---|---|
| nettoyage | 5 | coins | si sale |

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

| Poste | Coût | Unité | Condition |
|---|---:|---|---|
| maintenance sol | 1 | coin/case | option |

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

| Poste | Coût | Unité | Condition |
|---|---:|---|---|
| déchets | temps | min | propreté |

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

| Poste | Coût | Unité | Condition |
|---|---:|---|---|
| passage staff | temps | min | path |

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

| Poste | Coût | Unité | Condition |
|---|---:|---|---|
| section dupliquée | 1 | coin | conservée |

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

| Poste | Coût | Unité | Condition |
|---|---:|---|---|
| hygiène | 1 | coin | lore |

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

| Poste | Coût | Unité | Condition |
|---|---:|---|---|
| pâturage | 0 | - | herbe |

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

| Poste | Coût | Unité | Condition |
|---|---:|---|---|
| quarantaine | 1 | coin | lore |

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

| Poste | Coût | Unité | Condition |
|---|---:|---|---|
| usure | 1 | coin | lore |

#### Trajet Visiteurs

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

| Source | Destination | Déclencheur | Effet |
|---|---|---|---|
| entrée | allées | ticket | spawn |

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

| Source | Destination | Déclencheur | Effet |
|---|---|---|---|
| allée | enclos | curiosité | observe |

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

| Source | Destination | Déclencheur | Effet |
|---|---|---|---|
| enclos | boutique | faim | achat |

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

| Source | Destination | Déclencheur | Effet |
|---|---|---|---|
| allées | sortie | budget 0 | despawn |

### 6. Événements

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

| Event | Déclencheur | Payload | Effet |
|---|---|---|---|
| `CASE_DIRTY` | déchet | coord | flag |
| `PATH_BLOCKED` | obstacle | coord | reroute |

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

| Event | Déclencheur | Effet |
|---|---|---|
| `PATHING_UPDATED` | terrain | coûts |

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

| Event | Déclencheur | Effet |
|---|---|---|
| `CASE_QUALITY_UPDATED` | compat | rendu |

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

| Event | Déclencheur | Effet |
|---|---|---|
| `CASE_VISITED` | observe | last_visit_time |

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

| Event | Déclencheur | Effet |
|---|---|---|
| `VISITOR_REROUTE` | blocage | route |

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

| Event | Déclencheur | Effet |
|---|---|---|
| `PLAYER_CLEANS_TILE` | outil | propreté + |

### 7. Progression

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

| Niveau | Coût | Effet | Débloque |
|---|---:|---|---|
| Pavés | 250 | cost marche 1.0 | route |

### 8. Logique et Interfaces 

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

| Fonction | Entrées | Sorties | Notes |
|---|---|---|---|
| `checkAnimalDisappearance` | case, now | bool | visite |
| `computeMovementCost` | terrain | float | >=1.0 |

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

| ID | Niveau | Message | Condition |
|---|---|---|---|
| `CASE_DIRTY` | Info | "Une case est sale." | déchet |
| `PATH_BLOCKED` | Warning | "Chemin bloqué." | reroute |
| `ANIMAL_NOT_VISITED` | Warning | "Animal non observé." | timeout |

## Annexes UX/UI 

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

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

| Parcours | But | Friction | Réduction clics |
|---|---|---|---|
| Ouvrir menu case | agir vite | contexte | menu auto-adapté |
| Nettoyer | propreté | outil | raccourci dans menu |

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

| Composant | Contenu | États |
|---|---|---|
| Menu contextuel | actions | selon contenu |
| Highlight | outline | hover/selected |

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

| Zone UI | Position | Notes |
|---|---|---|
| Tuile | monde | iso |

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

| Intégration | Contrat | Notes |
|---|---|---|
| `carte_zoo.md` | sélection | panneau |

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

| Action | Chemin | Résultat |
|---|---|---|
| Sélection | clic | menu |

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

| Event UI | Déclencheur | Effet |
|---|---|---|
| `SELECT_ZOO_CASE` | clic | open |

#### Assets Skinables

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

| Asset | Usage | Durée | Notes |
|---|---|---:|---|
| `select_tile_click.mp3` | sélection | 0.2s | discret |

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

| Asset | Usage | Volume |
|---|---|---|
| `select_soft.mp3` | clic | bas |

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

| Asset | Usage | Contraintes |
|---|---|---|
| `tile_outline.png` | highlight | overlay |

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

| Asset | Usage |
|---|---|
| `context_menu_icon.png` | menu |

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

| Asset | Usage | Durée |
|---|---|---:|
| `tile_select.webm` | feedback | 0.5s |

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

| Animation | Déclencheur | Notes |
|---|---|---|
| bounce contenu | sélection | léger |

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

| Token | Valeur | Usage |
|---|---|---|
| `tile_white` | #FFFFFF | outline |

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

| Clé | FR | EN |
|---|---|---|
| `tile.coords` | Case {x},{y} | Tile {x},{y} |

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

| Élément | Forme | Notes |
|---|---|---|
| Tuile | losange | iso |