builazoo/docs/specs/carte_monde.md

# Spécifications : Carte du Monde

## Définition
La carte du monde est l'espace multijoueur où sont situés les zoos des joueurs, des bots, les villes et les laboratoires.

## Structure
- **Grille** : Fixe, avec des positions définies pour chaque entité.
- **Fond** : Reprend les biomes de la carte du zoo (Prairie/Océan/Montagne) en fond.
- **Zoom** : Niveau de zoom dépendant de l'upgrade "Agrandir la carte". Pas de pan manuel.

## Contenu Initial (Lancement)
- 1 Case Agrandissement de la carte (Payable en unités de recherche)
- 1 Compteur de bébés à vendre
- 1 Compteur d'animaux à vendre
- 1 Compteur de laboratoires
- 1 Compteur de zoos
- 1 Compteur de villes
- 1 Case Accueil nouveaux animaux (Haut gauche)
- 1 Case Nourriture générale (Haut gauche)
- 1 Case Camion (Haut gauche)
- 24 Cases de terrain (3 couleurs différentes)

## Entités Visibles
- **Zoos Joueurs** : Nom, icône, indicateurs.
- **Zoos Bots** : Identiques aux joueurs.
- **Villes** : Sources de visiteurs.
- **Laboratoires** : Sources d'œufs/bébés rares.
- **Camions** : En transit entre les entités.

## Mécaniques
- **Navigation** : Vue d'ensemble du marché.
- **Interactions** : Achat d'œufs/animaux via le camion.

# Annexes Techniques

## 1. Données et États
### Modèle de Données (JSON)
```json
{
  "id": "world_map",
  "width": "integer (très grand)",
  "height": "integer",
  "sites": [ { "id": "uuid", "type": "zoo|city|lab", "pos": { "x": "int", "y": "int" } } ],
  "trucks": [ { "id": "uuid", "owner_id": "uuid", "pos": { "x": "float", "y": "float" }, "target": "uuid" } ],
  "iso_x": "integer",
  "iso_y": "integer",
  "z_index": "integer"
}
```

### Caractéristiques Initiales
| Caractéristique | Valeur Initiale |
| :--- | :--- |
| Rayon Visible | 500km (simulé) |
| Nb Villes | 10 (dans rayon départ) |
| Nb Labos | 2 (dans rayon départ) |

### Scores Initiaux
**Score Exploration** : 0% (Carte dévoilée).

## 2. Cycles de Vie et Apparition
### Conditions d'Apparition
Unique (Singleton serveur).

### Conditions de Disparition
Jamais.

### Hérédité
**Cartographie** : Les zones découvertes restent visibles après un reset (Connaissance acquise).

## 3. Impacts Environnementaux
### Impact Température
**Météo Globale** : Nuages, Pluie ou Neige visibles sur la carte (Effet visuel + Gameplay).

### Impact Milieu (Biome)
**Diversité** : Les biomes influencent le type de zoo bot (ex: Zoo Polaire au Nord, Zoo Tropical à l'Équateur).

### Impact Saisons
**Visuel** : La carte change de teinte (Blanc en Hiver, Orange en Automne, Vert vif au Printemps).

### Impact Heure / Jour-Nuit
**Cycle Jour/Nuit** : Assombrissement global. Les villes et zoos s'allument (Pixel Art lumineux).

## 4. Impacts Biologiques et Sociaux
### Impact Reproduction
**Migration** : En saison des amours, des troupeaux sauvages (décoratifs) migrent sur la carte.

### Impact Mort
**Cimetière des Éléphants** : Lieu légendaire caché (Easter Egg) donnant un bonus si découvert.

### Impact Nourriture
**Ressources** : Les villes produisent de la nourriture (Champs autour des villes).

### Impact Attractivité (Visiteurs/Animaux)
**Rayonnement** : Un zoo très attractif (> 10k visiteurs) émet un halo doré visible de loin.

### Impact Valeur
**Économie** : Les prix du marché fluctuent selon l'offre globale (Loi de l'offre et la demande simulée).

## 5. Impacts Logistiques et Économiques
### Vitesse (Camion/Nurserie/Accueil/Recherche/Labo/Visite)
**Voyage Rapide** : Coût en pièces pour téléportation instantanée (si module "Héliport" débloqué).

### Dépenses (Boutiques/Visiteurs)
**Péages** : Taxe de passage sur certaines routes commerciales (1% valeur cargaison).

### Trajet Visiteurs
Calcul des distances Ville -> Zoo pour l'attractivité. Les visiteurs prennent le chemin le plus court.

## 6. Événements
### Événements du Jeu / Carte / Zoo / Ville / Visiteur
*   **Spawn Bot** : Apparition nouveau zoo bot.
*   **Spawn Truck** : Camion visible.
*   **Embouteillage** : Ralentissement sur les routes principales.

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

## 8. Logique et Interfaces
### Pseudo-code Impacts
```javascript
function updateWorldMap(map, deltaTime):
  for truck in map.trucks:
    moveTruck(truck, deltaTime)
    if hasArrived(truck):
      processTransaction(truck)

  updateWeather(map)
  updateDayNightCycle(map)
```

### Messages d'Infos / Alerte
| ID | Niveau | Message |
| :--- | :--- | :--- |
| `MAP_EVENT` | Info | "Un événement météo touche la région Nord." |

# 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)
### Vue Globale (Passif)
**Description UX** : Le joueur voit les autres acteurs et les flux économiques.
**Description UI** : Carte style "Google Maps" simplifiée ou grille hexagonale. Icônes (Maisons, Gratte-ciels, Fioles). **Flux** : Petites particules (voitures/points) voyageant entre les villes et les zoos attractifs.
**Emplacement** : Écran Carte Monde.
**Intégration** : Plein écran.
**Navigation** : Bouton Retour Zoo.
**Événements** : `OPEN_WORLD_MAP`.

#### Assets
- **Musiques** : Thème Aventure/Voyage.
- **Sons** : Vent, Bruit lointain trafic.
- **Graphiques** : Fond carte (Biomes flous).
- **Images** : Icônes Sites.
- **Vidéos** : Nuages dynamiques (shader).
- **Animations** : Camions qui bougent.
- **Couleurs** : Desaturées (pour faire ressortir les icônes).
- **Textes** : Noms des villes/zoos.
- **Formes** : Pins/Marqueurs.

### Brouillard de Guerre (Passif)
**Description UX** : Les zones inexplorées sont cachées.
**Description UI** : Nuages ou zone sombre en périphérie.
**Emplacement** : Bords Carte.
**Intégration** : Mask.
**Navigation** : Zoom-out via upgrade carte ; au clic sur une zone masquée, afficher un tooltip “Zone non explorée”.
**Événements** : `FOG_HOVER`, `FOG_CLICK_BLOCKED`

#### Assets
- **Musiques** : `ambience_fog_soft.mp3` (optionnel, très discret).
- **Sons** : `fog_whoosh.mp3` (au reveal), `ui_denied.mp3` (clic zone bloquée).
- **Graphiques** : Texture Nuages.
- **Images** : Masque alpha (bords flous).
- **Vidéos** : Effet de brume (particules).
- **Animations** : Nuages qui dérivent lentement.
- **Couleurs** : Blanc/Gris.
- **Textes** : "Zone Inexplorée".
- **Formes** : Zone non cliquable.

## Définition

| Champ | Valeur |
|---|---|
| Concept | “Carte du monde” : vue multijoueur/économie, affichant sites (zoos, villes, labos) et camions en transit. |
| Rôle | Permettre l’achat/vente via transport, visualiser la dynamique (flux, météo, jour/nuit) et l’exploration (brouillard). |
| Portée | Singleton logique (serveur), rendu client par zooms et marqueurs, sans pan manuel si règle active. |
| Contrainte | Pas de cache/mémorisation des flux : distances/choix calculés à la volée ; pas d’alternative HTTP/analytics ; interaction zone masquée => blocage explicite. |

## Fonctions (tableau détaillé)

| Fonction | Déclencheur | Entrées | Sorties | Règles | Observabilité |
|---|---|---|---|---|---|
| Ouvrir carte monde | bouton UI | player | écran monde | charge sites visibles | Event `OPEN_WORLD_MAP` |
| Résoudre visibilité | upgrade zoom | rayon | sites visibles | dépend upgrade carte | Event `WORLD_VISIBILITY_UPDATED` |
| Afficher sites | rendu | sites | markers | z_index stable | Event `WORLD_SITES_RENDERED` |
| Suivre camions | tick lazy | dt | pos camions | interpolation | Event `WORLD_TRUCKS_UPDATED` |
| Bloquer zone inexplorée | clic | coord | tooltip | pas de reveal gratuit | Event `FOG_CLICK_BLOCKED` |
| Délivrer cargo | camion arrive | cargo | dépôt zoo | adultes→accueil, œufs/bébés→nurserie | Event `DELIVERY_COMPLETE` |

## Icone de base

| Élément | Spécification |
|---|---|
| Représentation | Globe + pins |
| Couleur dominante | Désaturé (fond) + accents (pins) |
| Variantes | `icon_world_map.png`, `icon_pin_site.png` |
| États | normal, fogged, event_weather |

## Interactions (tableau détaillé)

| Interaction | Type | Préconditions | Étapes UI | Résultat | Erreurs / Messages |
|---|---|---|---|---|---|
| Clic site | Consultation | visible | clic marker | panneau site | `ZONE_NOT_EXPLORED` |
| Achat offre | Action | fonds + camion idle | drag offre→camion | mission | `TRUCK_BUSY`, `NOT_ENOUGH_COINS` |
| Zoom-out | Navigation | upgrade ok | bouton/gesture | rayon ↑ | `UPGRADE_REQUIRED` |

## Personnages contextuels (événements & interaction)
La carte du monde affiche des personnages contextuels selon le type de site sélectionné et les événements globaux.

### Sites et personnages
- **Ville** : maire (`maire.md`) — événements de ville, flux visiteurs, relation/jumelage.
- **Laboratoire** : laborantin (`laborantin.md`) — offres rares, services, alertes.
- **Zoo joueur** : joueur/portrait (`joueur.md`, `avatar_joueur.md`) — identité, indicateurs, interactions sociales.
- **Zoo bot** : bot (`bot.md`) — profil de stratégie et indicateurs.

### Déclencheurs (exemples)
| Event / Action | Condition | Personnage | Effet UI |
|---|---|---|---|
| `OPEN_WORLD_MAP` | ouverture écran | (contexte) | personnage de contexte selon dernier site sélectionné |
| clic site `city` | sélection ville | maire | panneau ville + événements |
| clic site `lab` | sélection labo | laborantin | panneau labo + offres/services |
| clic site `zoo` (autre joueur) | sélection zoo | joueur | panneau identité + actions permises |
| `ZONE_NOT_EXPLORED` | fog | (contexte) | message explicite (gating) |

### Skins & thèmes
Les portraits/mascottes suivent `theme.md`. Les mini-avatars des joueurs suivent leurs skins (si le profil est accessible) via les règles de `avatar_joueur.md` et `inventaire_skins.md`.

## Annexes Techniques

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

| Donnée / État | Type | Exemple | Source | Contraintes |
|---|---|---|---|---|
| `id` | string | `world_map` | DB | singleton |
| `width` | int | 200 | DB | très grand |
| `height` | int | 200 | DB | - |
| `sites[].id` | uuid_v4 | `uuid_v4` | DB | - |
| `sites[].type` | enum | `city` | DB | `zoo/city/lab` |
| `sites[].pos.x` | int | 40 | DB | grid |
| `sites[].pos.y` | int | 70 | DB | grid |
| `trucks[].id` | uuid_v4 | `uuid_v4` | DB | - |
| `trucks[].owner_id` | uuid_v4 | `uuid_v4` | DB | - |
| `trucks[].pos.x` | float | 40.2 | calcul | monde |
| `trucks[].pos.y` | float | 69.8 | calcul | monde |
| `trucks[].target` | uuid_v4 | `uuid_v4` | DB | site |
| `fog.revealed_radius` | float | 500 | config | km simulé |
| `weather.global` | enum | `rain` | calcul | rendu |

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

| Caractéristique | Valeur initiale | Unité | Notes |
|---|---:|---|---|
| Rayon visible | 500 | km | simulé |
| Nb villes | 10 | count | départ |
| Nb labos | 2 | count | départ |

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

| Score | Valeur initiale | Plage | Impact |
|---|---:|---|---|
| Exploration | 0 | 0..100 | fog |
| Trafic camions | 0 | 0..∞ | routes visibles |

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

| Phase | Déclencheur | Entrées | Sorties | Invariants |
|---|---|---|---|---|
| Création | serveur | seed | sites init | singleton |
| Exploration | upgrade | zoom | reveal | blocage zones |
| Événements | météo | saison | overlays | observables |

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

| Condition | Seuil | Opérateur | Résultat |
|---|---:|---|---|
| Démarrage | true | est | carte disponible |

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

| Condition | Seuil | Opérateur | Résultat |
|---|---:|---|---|
| - | - | - | jamais |

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

| Élément | Hérité | Règle |
|---|---|---|
| Cartographie | Oui | zones découvertes persistent |
| Routes “usuelles” | Oui | visibles si trafic haut |

### 3. Impacts Environnementaux

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

| Condition | Effet | Notes |
|---|---|---|
| Météo globale | visuel + mod vitesse | pluie/neige |

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

| Biome | Effet | Notes |
|---|---|---|
| Montagne | coût traversée + | camions |

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

| Saison | Effet | Notes |
|---|---|---|
| Hiver | teinte blanche | visuel |

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

| Période | Effet | Notes |
|---|---|---|
| Nuit | lumières villes/zoos | rendu |

### 4. Impacts Biologiques et Sociaux

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

| Facteur | Effet sur taux | Condition |
|---|---|---|
| Migration (décor) | 0 | purement visuel |

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

| Cas | Effet | Condition |
|---|---|---|
| Easter egg | bonus | découverte |

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

| Ressource | Effet | Condition |
|---|---|---|
| Villes produisent | stock + | marchés |

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

| Action/État | Gain | Rayon | Notes |
|---|---:|---:|---|
| Halo zoo attractif | visuel | monde | signal |

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

| Action/État | Effet animaux | Condition |
|---|---|---|
| - | neutre | - |

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

| Facteur | Variation | Condition |
|---|---:|---|
| Marché global | prix ± | offre/demande |

### 5. Impacts Logistiques et Économiques

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

| Paramètre | Effet | Condition |
|---|---|---|
| Embouteillage | vitesse - | event |

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

| Paramètre | Effet | Condition |
|---|---|---|
| Offres bébés | compteur + | listings |

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

| Paramètre | Effet | Condition |
|---|---|---|
| Offres animaux | compteur + | listings |

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

| Paramètre | Effet | Condition |
|---|---|---|
| Zoom upgrade | visibilité + | agrandissement carte |

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

| Paramètre | Effet | Condition |
|---|---|---|
| Refresh offers | TTL 24h | remplacement |

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

| Paramètre | Effet | Condition |
|---|---|---|
| Flux ville→zoo | distance | calcul |

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

| Poste | Coût | Unité | Condition |
|---|---:|---|---|
| Péages | 1% cargaison | coins | routes |

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

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

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

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

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

| Poste | Coût | Unité | Condition |
|---|---:|---|---|
| - | 1 | coins | 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 |
|---|---:|---|---|
| - | 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 |
|---|---:|---|---|
| Voyage rapide | 100 | coins | si héliport |

#### 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 |
|---|---|---|---|
| Zoo | Enclos | visite | path |

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

| Source | Destination | Déclencheur | Effet |
|---|---|---|---|
| Zoo | Boutique | besoins | achats |

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

| Source | Destination | Déclencheur | Effet |
|---|---|---|---|
| Billeterie | Sortie | fin | despawn |

### 6. Événements

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

| Event | Déclencheur | Payload | Effet |
|---|---|---|---|
| `OPEN_WORLD_MAP` | UI | - | écran |
| `MAP_EVENT` | météo | region | overlay |

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

| Event | Déclencheur | Effet |
|---|---|---|
| `FOG_HOVER` | hover | tooltip |

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

| Event | Déclencheur | Effet |
|---|---|---|
| `WORLD_TRUCKS_UPDATED` | tick | positions |

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

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

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

| Event | Déclencheur | Effet |
|---|---|---|
| `ZONE_NOT_EXPLORED` | clic | denied |

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

| Event | Déclencheur | Effet |
|---|---|---|
| `WORLD_VISIBILITY_UPDATED` | upgrade | reveal |

### 7. Progression

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

| Niveau | Coût | Effet | Débloque |
|---|---:|---|---|
| 1 | 1000 | zoom + | rayon |

### 8. Logique et Interfaces 

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

| Fonction | Entrées | Sorties | Notes |
|---|---|---|---|
| `updateWorldMap` | map, dt | map | move trucks |
| `canReveal` | upgrade | bool | fog |

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

| ID | Niveau | Message | Condition |
|---|---|---|---|
| `ZONE_NOT_EXPLORED` | Warning | "Zone non explorée." | fog |
| `UPGRADE_REQUIRED` | Warning | "Amélioration requise." | zoom |

## Annexes UX/UI 

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

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

| Parcours | But | Friction | Réduction clics |
|---|---|---|---|
| Lire le marché | choisir offres | densité | compteurs + filtres |
| Acheter | déclencher camion | drag | drag direct vers camion |

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

| Composant | Contenu | États |
|---|---|---|
| Pins sites | zoo/city/lab | hover/selected |
| Fog mask | nuages | revealed/hidden |
| Compteurs | offres | live |

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

| Zone UI | Position | Notes |
|---|---|---|
| Plein écran | centre | carte monde |

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

| Intégration | Contrat | Notes |
|---|---|---|
| `camion.md` | transport | missions |
| `ville.md` | flux | visiteurs |

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

| Action | Chemin | Résultat |
|---|---|---|
| Ouvrir | bouton carte monde | écran |
| Retour | bouton zoo | ferme |

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

| Event UI | Déclencheur | Effet |
|---|---|---|
| `OPEN_WORLD_MAP` | clic | open |
| `FOG_CLICK_BLOCKED` | clic fog | tooltip |

#### Assets Skinables

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

| Asset | Usage | Durée | Notes |
|---|---|---:|---|
| `world_map_travel_loop.mp3` | carte monde | loop | aventure |

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

| Asset | Usage | Volume |
|---|---|---|
| `fog_whoosh.mp3` | reveal | bas |
| `ui_denied.mp3` | blocked | moyen |

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

| Asset | Usage | Contraintes |
|---|---|---|
| `world_pins_atlas.png` | pins | lisible |
| `fog_clouds.png` | fog | alpha |

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

| Asset | Usage |
|---|---|
| `world_biomes_blur.png` | fond |

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

| Asset | Usage | Durée |
|---|---|---:|
| `clouds_shader.webm` | fond | loop |

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

| Animation | Déclencheur | Notes |
|---|---|---|
| déplacement camions | tick | continu |

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

| Token | Valeur | Usage |
|---|---|---|
| `world_desat` | #8A8A8A | fond |
| `world_pin_gold` | #D4AF37 | halo |

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

| Clé | FR | EN |
|---|---|---|
| `world.fog` | Zone inexplorée | Unexplored zone |
| `world.back` | Retour zoo | Back to zoo |

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

| Élément | Forme | Notes |
|---|---|---|
| Pin | goutte | site |