builazoo/docs/specs/ville.md

# Spécifications : Ville (Site)

## Définition
Une ville est une entité sur la Carte du Monde qui génère le flux de visiteurs vers les zoos.

## Propriétés
- **Nom** : Nom de la ville.
- **Population** : Nombre de visiteurs potentiels maximum.
- **Icône** : 🏙️

## Mécanique d'Attraction
- Les visiteurs partent de la ville pour aller vers les zoos.
- **Facteur de Distance** : Plus un zoo est proche d'une ville, plus il attire de visiteurs.
- **Facteur d'Attractivité** : La valeur et la diversité du zoo influencent le choix des visiteurs.

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

### Affichage
Le maire s’affiche lorsque :
- la ville est **actionnée** (sélection/clic ville, ouverture panneau ville) ;
- un **événement** de ville survient (festival, grève, bonus économique, `CITY_EVENT`).

### Déclencheurs (exemples)
| Event | Condition | Effet UI personnage |
|---|---|---|
| sélection ville | clic icône ville | portrait + synthèse (population, richesse, flux) |
| `CITY_EVENT` | événement actif | bulle “Événement en cours” + impacts chiffrés |

### Skins & thèmes
Portrait et accessoires suivent `theme.md` ; variantes “ville” possibles via `inventaire_skins.md`.

# Annexes Techniques

## 1. Données et États
### Modèle de Données (JSON)
```json
{
  "id": "uuid",
  "type": "city",
  "name": "string",
  "population": "integer",
  "wealth_factor": "float (0.5 - 2.0)",
  "iso_x": "integer",
  "iso_y": "integer",
  "z_index": "integer"
}
```

### Caractéristiques Initiales
| Caractéristique | Valeur Moyenne |
| :--- | :--- |
| Population | 10,000 - 1,000,000 |
| Richesse | 1.0 |

### Scores Initiaux
**Niveau de Bonheur** : 50% (Influence la fréquence des visites).

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

### Conditions de Disparition
**Désastre** : Ville détruite (Event rare "Météorite" ou "Crise Éco").

### Hérédité
**Jumelage** : Bonus permanent de flux (+5%) si relation max atteinte avec une ville.

## 3. Impacts Environnementaux
### Impact Température
**Ilot de chaleur** : La ville est toujours +2°C par rapport à la campagne environnante.

### Impact Milieu (Biome)
**Architecture** : Adaptée au biome (Igloos en Toundra, Tentes en Désert, Gratte-ciels en Plaine).

### Impact Saisons
**Festivals** : Event saisonnier en ville (+Visiteurs pendant 24h).
- Été : Carnaval.
- Hiver : Marché de Noël.

### Impact Heure / Jour-Nuit
**Lumières** : La ville brille la nuit (Pollution lumineuse visible).

## 4. Impacts Biologiques et Sociaux
### Impact Reproduction
**Baby Boom** : Augmente la population de la ville (+Flux) pendant 1 semaine.

### Impact Mort
**Épidémie** : Baisse population temporaire (-Flux).

### Impact Nourriture
**Marché** : La ville vend de la nourriture au joueur (Source d'approvisionnement).

### Impact Attractivité (Visiteurs/Animaux)
Source du flux. `Flux = Pop * (AttractivitéZoo / Distance²)`.

### Impact Valeur
**PIB** : Influence le budget des visiteurs (Richesse). Une ville riche envoie des VIP.

## 5. Impacts Logistiques et Économiques
### Vitesse (Camion/Nurserie/Accueil/Recherche/Labo/Visite)
**Trafic** : Ralentit les camions traversant la ville aux heures de pointe (8h-9h, 17h-18h).

### Dépenses (Boutiques/Visiteurs)
**Facteur Richesse** : Multiplie le budget des visiteurs issus de cette ville.

### Trajet Visiteurs
Point de départ. Les visiteurs arrivent en bus/voiture depuis la ville.

## 6. Événements
### Événements du Jeu / Carte / Zoo / Ville / Visiteur
*   **Fête Nationale** : Flux x2.
*   **Grève** : Flux / 2.

## 7. Progression
### Tableau des Upgrades
*Note : Campagnes Marketing ciblées.*
| Niveau Campagne | Coût | Effet |
| :--- | :--- | :--- |
| 1 (Panneaux) | 500 | +5% Flux |
| 2 (Radio) | 1500 | +10% Flux |
| 3 (TV) | 5000 | +20% Flux |

## 8. Logique et Interfaces
### Pseudo-code Impacts
```javascript
function calculateVisitorFlow(city, zoo):
  distance = getDistance(city, zoo)
  baseFlow = city.population * (zoo.attractiveness / (distance * distance))
  
  if isPeakHour(): baseFlow *= 1.5
  if city.hasEvent(): baseFlow *= 2.0
  
  return baseFlow
```

### Messages d'Infos / Alerte
| ID | Niveau | Message |
| :--- | :--- | :--- |
| `CITY_EVENT` | Info | "C'est la fête à [NomVille] ! Attendez-vous à du monde." |

# 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)
### Visualisation Taille (Passif)
**Description UX** : Distinguer les grandes villes des petites.
**Description UI** : Taille de l'icône proportionnelle à la population. Gratte-ciels vs Maisons.
**Emplacement** : Carte Monde.
**Intégration** : Sprite.
**Navigation** : Zoom sur la carte.
**Événements** : `MAP_ZOOM`.

#### Assets
- **Musiques** : Ambiance urbaine (klaxons lointains, vent).
- **Sons** : Bruit de trafic faible.
- **Graphiques** : Sprites Ville (Petit, Moyen, Grand).
- **Images** : Silhouette Skyline.
- **Vidéos** : Lumières des fenêtres qui s'allument la nuit (Pixel Art animé).
- **Animations** : Fumée des cheminées.
- **Couleurs** : Gris/Bleu.
- **Textes** : Nom Ville.
- **Formes** : Cercle d'influence (zone de chalandise).

## Définition

| Champ | Valeur |
|---|---|
| Concept | Site “Ville” : nœud de la carte monde générant un potentiel de visiteurs et un budget moyen (wealth_factor). |
| Rôle | Alimenter le flux ville→zoo (choix par attractivité/distance) et porter des événements (festivals, grèves) modifiant la demande. |
| Portée | Une entité fixe sur carte monde, référencée par les calculs d’attractivité. |
| Contrainte | Flux calculé à la volée (pas de cache/mémorisation) ; aucun mécanisme d’analytics ; événements doivent être explicités via events/messages. |

## Fonctions (tableau détaillé)

| Fonction | Déclencheur | Entrées | Sorties | Règles | Observabilité |
|---|---|---|---|---|---|
| Calculer flux vers un zoo | tick / ouverture carte | `population`, `wealth_factor`, distance, attractivité zoo | `baseFlow` | formule \(Pop \cdot A / d^2\) + mods heure/event | Event `CITY_FLOW_DISPATCHED` |
| Déclencher événement ville | calendrier/saison | type event | mod flux/budget | durée bornée | Event `CITY_EVENT` |
| Vendre nourriture (marché) | interaction (feature) | stock, price | items | pricing selon wealth | Event `CITY_MARKET_OPENED` |
| Marquer jumelage | relation max | city_id | bonus permanent | +5% flux vers zoo jumelé | Event `CITY_TWINNED` |

## Icone de base

| Élément | Spécification |
|---|---|
| Représentation | Skyline (petite/moyenne/grande) |
| Couleur dominante | Gris/bleu + lumières jaunes |
| Variantes | `city_small.png`, `city_medium.png`, `city_large.png` |
| États | jour (clair), nuit (lumières), event (feux d’artifice) |

## Interactions (tableau détaillé)

| Interaction | Type | Préconditions | Étapes UI | Résultat | Erreurs / Messages |
|---|---|---|---|---|---|
| Ouvrir ville | Consultation | ville visible | clic marker | panneau | `ZONE_NOT_EXPLORED` |
| Voir flux | Consultation | zoo sélectionné | onglet flux | valeurs | - |
| Lancer campagne (feature) | Action | coins ok | bouton campagne | flux + | `NOT_ENOUGH_COINS` |

## 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 | `city` | DB | constant |
| `name` | string | `Rivemont` | DB | - |
| `population` | int | 250000 | DB | >0 |
| `wealth_factor` | float | 1.2 | DB | 0.5..2.0 |
| `events.active_event` | enum \| null | `NATIONAL_HOLIDAY` | DB | null si none |
| `events.ends_at` | timestamp \| null | - | DB | UTC |
| `iso_x` | int | 120 | calcul | rendu |
| `iso_y` | int | 88 | calcul | rendu |
| `z_index` | int | 12088 | calcul | profondeur |

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

| Caractéristique | Valeur initiale | Unité | Notes |
|---|---:|---|---|
| Bonheur ville | 50 | % | influe fréquence |
| Îlot chaleur | +2 | °C | vs campagne |

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

| Score | Valeur initiale | Plage | Impact |
|---|---:|---|---|
| Relation | 0 | 0..100 | jumelage |
| Flux envoyé | 0 | 0..∞ | suivi in-game |

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

| Phase | Déclencheur | Entrées | Sorties | Invariants |
|---|---|---|---|---|
| Génération | seed monde | biome | ville | fixe |
| Événement | calendrier | type | mods | durée |

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

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

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

| Condition | Seuil | Opérateur | Résultat |
|---|---:|---|---|
| Désastre rare | true | est | ville détruite (event) |

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

| Élément | Hérité | Règle |
|---|---|---|
| Jumelage | Oui | bonus permanent |
| Événements | Non | expirent |

### 3. Impacts Environnementaux

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

| Condition | Effet | Notes |
|---|---|---|
| îlot chaleur | +2°C | constant |

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

| Biome | Effet | Notes |
|---|---|---|
| toundra | architecture igloos | visuel |

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

| Saison | Effet | Notes |
|---|---|---|
| hiver | marché Noël | flux + |

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

| Période | Effet | Notes |
|---|---|---|
| nuit | lumières | pollution lumineuse |

### 4. Impacts Biologiques et Sociaux

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

| Facteur | Effet sur taux | Condition |
|---|---|---|
| baby boom | pop + | 1 semaine in-game |

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

| Cas | Effet | Condition |
|---|---|---|
| épidémie | pop - | temporaire |

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

| Ressource | Effet | Condition |
|---|---|---|
| marché | stock joueur + | achats |

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

| Action/État | Gain | Rayon | Notes |
|---|---:|---:|---|
| richesse | budget ↑ | monde | VIP |

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

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

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

| Facteur | Variation | Condition |
|---|---:|---|
| PIB | dépense moyenne ± | wealth_factor |

### 5. Impacts Logistiques et Économiques

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

| Paramètre | Effet | Condition |
|---|---|---|
| trafic pointe | vitesse - | 8-9h, 17-18h |

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

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

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

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

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

| Paramètre | Effet | Condition |
|---|---|---|
| campagne marketing | flux + | achat |

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

| Paramètre | Effet | Condition |
|---|---|---|
| conférence science | affluence + | event |

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

| Paramètre | Effet | Condition |
|---|---|---|
| distance | flux \(\downarrow\) | d^2 |

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

| Poste | Coût | Unité | Condition |
|---|---:|---|---|
| campagne 1 | 500 | coins | panneaux |

#### 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 |
|---|---:|---|---|
| budget visiteurs | wealth_factor × | $ | ville |

#### 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 |
|---|---:|---|---|
| marchés | variable | coins | achats |

#### 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 |
|---|---:|---|---|
| parking (lore) | 5 | $ | voiture |

#### Trajet Visiteurs

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

| Source | Destination | Déclencheur | Effet |
|---|---|---|---|
| Ville | Zoo | flux | entrée billeterie |

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

| Source | Destination | Déclencheur | Effet |
|---|---|---|---|
| Zoo | Enclos | visite | satisfaction |

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

| Source | Destination | Déclencheur | Effet |
|---|---|---|---|
| Zoo | Boutiques | besoins | dépenses |

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

| Source | Destination | Déclencheur | Effet |
|---|---|---|---|
| Zoo | Ville | sortie | despawn |

### 6. Événements

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

| Event | Déclencheur | Payload | Effet |
|---|---|---|---|
| `CITY_EVENT` | calendrier | type | flux mod |
| `CITY_TWINNED` | relation 100 | city_id | bonus + |

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

| Event | Déclencheur | Effet |
|---|---|---|
| `MAP_ZOOM` | zoom | taille icône |

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

| Event | Déclencheur | Effet |
|---|---|---|
| `CITY_FLOW_DISPATCHED` | calcul | spawn potentiels |

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

| Event | Déclencheur | Effet |
|---|---|---|
| `NATIONAL_HOLIDAY` | event | flux x2 |

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

| Event | Déclencheur | Effet |
|---|---|---|
| `VISITOR_SPAWNS_FROM_CITY` | flux | origine |

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

| Event | Déclencheur | Effet |
|---|---|---|
| `PLAYER_STARTS_CITY_CAMPAIGN` | action | flux + |

### 7. Progression

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

| Niveau | Coût | Effet | Débloque |
|---|---:|---|---|
| 2 | 1500 | flux +10% | radio |
| 3 | 5000 | flux +20% | TV |

### 8. Logique et Interfaces 

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

| Fonction | Entrées | Sorties | Notes |
|---|---|---|---|
| `calculateVisitorFlow` | city, zoo | float | distance |
| `isPeakHour` | now | bool | trafic |

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

| ID | Niveau | Message | Condition |
|---|---|---|---|
| `CITY_EVENT` | Info | "C'est la fête à {city}." | event |
| `CITY_STRIKE` | Warning | "Grève : flux réduit." | event |

## Annexes UX/UI 

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

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

| Parcours | But | Friction | Réduction clics |
|---|---|---|---|
| Identifier ville | choisir cible | densité | taille icône + tooltip |
| Comprendre flux | arbitrer | maths | panneau simple “flux” |

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

| Composant | Contenu | États |
|---|---|---|
| Marker ville | sprite skyline | petit/moyen/grand |
| Cercle influence | rayon | visible |
| Tooltip | nom + pop | hover |

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

| Zone UI | Position | Notes |
|---|---|---|
| Carte monde | sites | iso |

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

| Intégration | Contrat | Notes |
|---|---|---|
| `carte_monde.md` | usage | map |
| `billeterie.md` | entrées | spawn |

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

| Action | Chemin | Résultat |
|---|---|---|
| Ouvrir ville | clic marker | panneau |

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

| Event UI | Déclencheur | Effet |
|---|---|---|
| `MAP_ZOOM` | zoom | scale |

#### Assets Skinables

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

| Asset | Usage | Durée | Notes |
|---|---|---:|---|
| `city_ambience_loop.mp3` | proximité ville | loop | discret |

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

| Asset | Usage | Volume |
|---|---|---|
| `traffic_far.mp3` | ville | bas |

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

| Asset | Usage | Contraintes |
|---|---|---|
| `city_skyline_set.png` | sprites | 4 dirs |

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

| Asset | Usage |
|---|---|
| `city_influence_ring.png` | cercle |

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

| Asset | Usage | Durée |
|---|---|---:|
| `city_lights_night.webm` | nuit | 2.0s |

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

| Animation | Déclencheur | Notes |
|---|---|---|
| fumée | idle | loop |

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

| Token | Valeur | Usage |
|---|---|---|
| `city_gray` | #546E7A | bâtiments |
| `city_light_yellow` | #FFEE58 | fenêtres |

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

| Clé | FR | EN |
|---|---|---|
| `city.population` | Population | Population |
| `city.wealth` | Richesse | Wealth |

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

| Élément | Forme | Notes |
|---|---|---|
| Cercle influence | cercle | zone |