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

## Définition
Une case est l'unité élémentaire de la grille (Zoo ou Monde).

## Propriétés
- **Coordonnées** : Position (x, y) dans la grille.
- **Couleur (Milieu)** : Définit le biome et l'environnement visuel.
- **Température** : Liée à la couleur/biome.
- **Contenu** : Peut contenir un bâtiment, un animal, un visiteur, ou être vide.
- **État** : Peut avoir des indicateurs visuels (herbe jaunie, givre, fertilité).

# Annexes Techniques

## 1. Données et États
### Modèle de Données (JSON)
```json
{
  "x": "integer",
  "y": "integer",
  "grid_id": "string (stable key: `${x}:${y}`)",
  "owner_id": "uuid | null (null = carte neutre/monde)",
  "created_at": "timestamp",
  "updated_at": "timestamp",
  "biome_id": "integer",
  "biome_type": "enum('prairie','ocean','montagne','savane','toundra','desert','jungle','marais')",
  "temperature_offset": "float (°C, additive)",
  "content_ref": "uuid | null",
  "content_type": "enum('empty','animal','building','visitor','staff','decoration','path','bridge','water','fence')",
  "fertility_level": "float (0-100)",
  "cleanliness_level": "float (0-100)",
  "state_flags": [
    "enum('frozen','dry','dirty','fertilized','muddy','snowy','flooded','trampled')"
  ],
  "render": {
    "tile_variant": "string (auto-tiling key)",
    "occluder": "boolean",
    "hitbox": "enum('tile','base_sprite','custom_polygon')"
  },
  "iso_x": "integer",
  "iso_y": "integer",
  "z_index": "integer"
}
```

### Contraintes (Invariants)
*   **Unicité** : (`x`,`y`) est unique dans une grille.
*   **Cohérence contenu** : si `content_type === 'empty'` alors `content_ref === null`.
*   **Température** : `temperature_offset` s’applique additivement à la température “biome” et aux modificateurs (saison, jour/nuit).
*   **Z-index isométrique** : `z_index` est dérivé principalement de `y` (et secondairement de `x`) pour garantir le recouvrement correct.

## 8. Logique et Interfaces
### Pseudo-code Impacts
```python
def fertilize_case(case, player):
    cost = 50
    if player.money < cost: return error("NO_MONEY")
    
    player.money -= cost
    case.fertility_level = 100
    case.state_flags.append("fertilized")
    
    # Si plante dessus, boost croissance
    if case.content and case.content.type == "plant":
        case.content.growth_rate *= 1.5
        
    return success("CASE_FERTILIZED")
```

### Messages d'Infos / Alerte
| Type | Message | Condition | Priorité |
|---|---|---|---:|
| Info | "Sol fertilisé." | `state_flags` ajoute `fertilized` | 2 |
| Warn | "Fonds insuffisants." | `player.money < cost` | 4 |
| Warn | "Case occupée : action indisponible." | `content_type` non compatible | 3 |

# 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)
### Fertilisation (Action)
**Description UX** : Le joueur améliore le sol pour que l'herbe repousse plus vite.
**Description UI** : Outil "Sac d'engrais". Clic sur la case.
**Emplacement** : Menu Outils -> Case.
**Intégration** : Curseur.
**Navigation** : Clic.
**Événements** : `FERTILIZE_SOIL`.

#### Assets
- **Musiques** : `ambience_garden_soft.mp3` (léger, discret).
- **Sons** : `scatter.mp3`.
- **Graphiques** : Particules vertes/brunes.
- **Images** : Texture terre riche (plus foncée).
- **Animations** : Poussière qui retombe.
- **Couleurs** : Marron foncé.
 - **Textes** : `TOOL_FERTILIZE` = "Engrais", `CASE_FERTILIZED` = "Sol fertilisé"
 - **Formes** : Curseur rond (outil), surbrillance tuile.

## Définition

| Champ | Valeur |
|---|---|
| Concept | Case générique : unité élémentaire \((x,y)\) d’une carte, portant biome, température, contenu, états de sol et paramètres de rendu isométrique. |
| Rôle | Supporter toutes les interactions bas niveau (occupation, états terrain, outils) et fournir un contrat unique pour les spécialisations (zoo/monde). |
| Portée | Toute grille (zoo/world) ; les entités référencent des cases via coordonnées ou `grid_id`. |
| Contrainte | Invariants stricts (content_type vs ref) ; pas de fallback silencieux ; dérivés (z_index, tile_variant) calculés à la volée. |

## Fonctions (tableau détaillé)

| Fonction | Déclencheur | Entrées | Sorties | Règles | Observabilité |
|---|---|---|---|---|---|
| Résoudre `grid_id` | création | x,y | string | format `${x}:${y}` | Event `GRID_ID_BUILT` |
| Mettre à jour contenu | placement | content_type/ref | case | cohérence obligatoire | Event `CASE_CONTENT_UPDATED` |
| Appliquer outil (fertilize) | action | player, cost | fertility=100 | fonds requis, sinon erreur | Event `FERTILIZE_SOIL` |
| Mettre à jour flags | tick | env + actions | state_flags | clamp + cohérence | Event `CASE_FLAGS_UPDATED` |
| Calculer température locale | tick | biome + offset + saison | float | additif | Event `CASE_TEMP_COMPUTED` |

## Icone de base

| Élément | Spécification |
|---|---|
| Représentation | Tuile + symbole biome |
| Couleur dominante | selon biome |
| Variantes | `icon_tile_generic.png`, `icon_tile_fertilized.png` |
| États | `dirty`, `fertilized`, `snowy`, `muddy` |

## Interactions (tableau détaillé)

| Interaction | Type | Préconditions | Étapes UI | Résultat | Erreurs / Messages |
|---|---|---|---|---|---|
| Fertiliser | Action | fonds ≥ 50 | outil → clic case | fertilité 100 | `NO_MONEY` |
| Lire état case | Consultation | - | survol | tooltip flags | - |

## Annexes Techniques

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

| Donnée / État | Type | Exemple | Source | Contraintes |
|---|---|---|---|---|
| `x` | int | 10 | DB | coord |
| `y` | int | 12 | DB | coord |
| `grid_id` | string | `10:12` | calcul | stable |
| `owner_id` | uuid_v4 \| null | `uuid_v4` | DB | null pour monde |
| `biome_type` | enum | `prairie` | DB | - |
| `temperature_offset` | float | -2.0 | DB | additif |
| `content_type` | enum | `empty` | DB | voir enum |
| `content_ref` | uuid_v4 \| null | - | DB | null si empty |
| `fertility_level` | float | 100 | DB | 0..100 |
| `cleanliness_level` | float | 80 | DB | 0..100 |
| `state_flags[]` | enum[] | `dirty` | DB | sans doublons |
| `render.tile_variant` | string | `prairie_A` | calcul | auto-tiling |
| `render.hitbox` | enum | `tile` | config | access |
| `iso_x` | int | 120 | calcul | iso |
| `iso_y` | int | 88 | calcul | iso |
| `z_index` | int | 12088 | calcul | tri |

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

| Caractéristique | Valeur initiale | Unité | Notes |
|---|---:|---|---|
| Fertilité | 0 | pts | init |
| Propreté | 100 | pts | init |
| Temp offset | 0.0 | °C | init |

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

| Score | Valeur initiale | Plage | Impact |
|---|---:|---|---|
| Occupation | 0 | 0..100 | densité |
| Dégradation | 0 | 0..100 | sol |

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

| Phase | Déclencheur | Entrées | Sorties | Invariants |
|---|---|---|---|---|
| Création | gen map | biome | case | unicité |
| Mutation | actions | outils | flags | cohérence |

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

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

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

| Condition | Seuil | Opérateur | Résultat |
|---|---:|---|---|
| Suppression compte | true | est | supprimée |

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

| Élément | Hérité | Règle |
|---|---|---|
| Coordonnées | Oui | stables |
| Flags | Oui | persistants DB |

### 3. Impacts Environnementaux

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

| Condition | Effet | Notes |
|---|---|---|
| Saison | temp \(\pm\) | global |

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

| Biome | Effet | Notes |
|---|---|---|
| jungle | humidité | visuel |

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

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

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

| Période | Effet | Notes |
|---|---|---|
| nuit | luminosité - | rendu |

### 4. Impacts Biologiques et Sociaux

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

| Facteur | Effet sur taux | Condition |
|---|---|---|
| fertilized | + | plantes |

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

| Cas | Effet | Condition |
|---|---|---|
| flooded | danger | event |

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

| Ressource | Effet | Condition |
|---|---|---|
| herbe | nourriture | prairie |

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

| Action/État | Gain | Rayon | Notes |
|---|---:|---:|---|
| propre | + | local | ambiance |

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

| Action/État | Effet animaux | Condition |
|---|---|---|
| sale | stress + | proximité |

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

| Facteur | Variation | Condition |
|---|---:|---|
| tile premium | + | flag |

### 5. Impacts Logistiques et Économiques

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

| Paramètre | Effet | Condition |
|---|---|---|
| movement_cost | vitesse - | >1 |

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

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

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

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

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

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

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

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

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

| Paramètre | Effet | Condition |
|---|---|---|
| walkable | route | bool |

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

| Poste | Coût | Unité | Condition |
|---|---:|---|---|
| fertilize | 50 | coins | outil |

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

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

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

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

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

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

#### 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 |
|---|---:|---|---|
| - | 1 | coins | lore |

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

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

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

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

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

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

#### Trajet Visiteurs

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

| Source | Destination | Déclencheur | Effet |
|---|---|---|---|
| ville | zoo | attractivité | flux |

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

| Source | Destination | Déclencheur | Effet |
|---|---|---|---|
| entrée | enclos | visite | route |

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

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

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

| Source | Destination | Déclencheur | Effet |
|---|---|---|---|
| zoo | sortie | fin | despawn |

### 6. Événements

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

| Event | Déclencheur | Payload | Effet |
|---|---|---|---|
| `CASE_FERTILIZED` | outil | grid_id | flag + |
| `CASE_CONTENT_UPDATED` | placement | content | cohérence |

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

| Event | Déclencheur | Effet |
|---|---|---|
| `CASE_TEMP_COMPUTED` | tick | temp |

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

| Event | Déclencheur | Effet |
|---|---|---|
| `CASE_FLAGS_UPDATED` | tick | flags |

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

| Event | Déclencheur | Effet |
|---|---|---|
| `GRID_ID_BUILT` | init | id |

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

| Event | Déclencheur | Effet |
|---|---|---|
| `CASE_HOVERED` | UI | tooltip |

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

| Event | Déclencheur | Effet |
|---|---|---|
| `PLAYER_FERTILIZES` | clic | sol |

### 7. Progression

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

| Niveau | Coût | Effet | Débloque |
|---|---:|---|---|
| Outil engrais | 50 | fertilité 100 | action |

### 8. Logique et Interfaces 

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

| Fonction | Entrées | Sorties | Notes |
|---|---|---|---|
| `fertilize_case` | case, player | result | fonds |
| `getLocalTemp` | case, season | float | additif |

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

| ID | Niveau | Message | Condition |
|---|---|---|---|
| `CASE_FERTILIZED` | Info | "Sol fertilisé." | succès |
| `NO_MONEY` | Warn | "Fonds insuffisants." | coût |

## Annexes UX/UI 

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

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

| Parcours | But | Friction | Réduction clics |
|---|---|---|---|
| Utiliser outil | améliorer case | menus | outil direct |

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

| Composant | Contenu | États |
|---|---|---|
| Curseur outil | sac engrais | actif |
| Feedback case | particules | succès |

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

| Zone UI | Position | Notes |
|---|---|---|
| Menu outils | HUD | accès |

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

| Intégration | Contrat | Notes |
|---|---|---|
| `case_zoo.md` | spécialisation | zoo |

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

| Action | Chemin | Résultat |
|---|---|---|
| Fertiliser | outil → clic | succès |

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

| Event UI | Déclencheur | Effet |
|---|---|---|
| `FERTILIZE_SOIL` | clic | action |

#### Assets Skinables

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

| Asset | Usage | Durée | Notes |
|---|---|---:|---|
| `ambience_garden_soft.mp3` | outil | loop | discret |

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

| Asset | Usage | Volume |
|---|---|---|
| `scatter.mp3` | engrais | bas |

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

| Asset | Usage | Contraintes |
|---|---|---|
| `fertilize_particles.png` | FX | overlay |

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

| Asset | Usage |
|---|---|
| `soil_rich.png` | tuile |

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

| Asset | Usage | Durée |
|---|---|---:|
| `fertilize_fx.webm` | feedback | 0.8s |

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

| Animation | Déclencheur | Notes |
|---|---|---|
| poussière | action | 0.6s |

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

| Token | Valeur | Usage |
|---|---|---|
| `soil_brown` | #4E342E | sol |

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

| Clé | FR | EN |
|---|---|---|
| `tool.fertilize` | Engrais | Fertilize |
| `case.fertilized` | Sol fertilisé | Soil fertilized |

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

| Élément | Forme | Notes |
|---|---|---|
| Curseur | rond | outil |