ok

docs/specs/artiste.md

@@ -76,3 +76,484 @@ def update_artist(artist, visitors_nearby):
 *   **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.
+
+
+## Définition
+
+| Champ | Valeur |
+|---|---|
+| Entité | Employé “Artiste” |
+| Rôle | Divertir les visiteurs pour augmenter satisfaction, temps de séjour et micro-revenus (pourboires). |
+| Position | Se déplace sur chemins / points d’intérêt (scène) avec un rayon d’effet local. |
+| Vue | Isométrique 2.5D, sprite 4 directions, hitbox base-sprite. |
+
+## Fonctions (tableau détaillé)
+
+| Fonction | Déclencheur | Entrées | Sorties | Règles | Observabilité |
+|---|---|---|---|---|---|
+| Divertissement de zone | Tick IA / début performance | `radius`, visiteurs proches | `+happiness`, `+stay_duration` | Effet décroissant si performance continue sans pause ; nécessite cases walkable | Event `ARTIST_PERF_TICK`, compteur visiteurs affectés |
+| Show spécial | Action joueur | cooldown, coût optionnel | Bonus temporaire fort | Cooldown strict ; annule si artiste en pause forcée | Event `ARTIST_SPECIAL_SHOW_START/END` |
+| Pourboires | Aléatoire pendant performance | RNG, densité foule | `+coins` | Plafond par minute ; augmente avec `charisma` | Event `ARTIST_TIP`, cumul `tips_collected` |
+| Gestion fatigue | Temps passé en perf | durée | état `BREAK` | Pause obligatoire ; réduit efficacité avant pause | Event `ARTIST_BREAK_START/END` |
+
+## Icone de base
+
+| Élément | Spécification |
+|---|---|
+| Représentation | Masque de théâtre / notes de musique |
+| Couleur dominante | Rose / Violet |
+| Variantes | `icon_artist_mask.png`, `icon_artist_music.png`, `icon_artist_paint.png` |
+| États | Badge “cooldown” (horloge), “en pause” (Zzz) |
+
+## Interactions (tableau détaillé)
+
+| Interaction | Type | Préconditions | Étapes UI | Résultat | Erreurs / Messages |
+|---|---|---|---|---|---|
+| Recruter | Action | Coins ≥ `hire_cost`, slot employé dispo | Menu Employés → Artiste → Confirmer | Artiste créé/assignable | `INSUFFICIENT_FUNDS`, `EMPLOYEE_CAP_REACHED` |
+| Assigner à une scène | Action | Scène/POI existant, path possible | Sélection artiste → “Assigner” → clic scène | Itinéraire fixé + zone perf | `NO_PATH`, `SCENE_BUSY` |
+| Déplacer manuellement | Action | Pas en show spécial verrouillé | Drag & drop / tap-to-move | Nouvelle position, recalcul foule | `INVALID_TILE` |
+| Lancer show spécial | Action | Cooldown fini | Bouton “Show spécial” | Buff + FX + foule | `COOLDOWN_ACTIVE` |
+| Inspecter stats | Consultation | - | Sélection artiste | Panel stats (charisma, tips) | - |
+
+## Annexes Techniques
+
+### 1. Données et États (tableau détaillé)
+
+| Donnée / État | Type | Exemple | Source | Contraintes |
+|---|---|---|---|---|
+| `employee_id` | string | `artist_03` | DB | Unique |
+| `type` | enum | `artiste` | DB | Constante |
+| `subtype` | enum | `musician|clown|painter|juggler` | DB | 1 parmi n |
+| `salary` | int | 45 | config | Paiement journalier |
+| `hire_cost` | int | 450 | config | Paiement à l’embauche |
+| `state` | enum | `IDLE|PERFORMING|BREAK` | runtime | Transitions contrôlées |
+| `performance_cooldown_end` | timestamp | - | runtime | Non nul après show |
+| `stats.charisma` | int | 15 | DB | [1..100] |
+| `stats.radius` | int | 3 | DB | [1..8] |
+| `stats.tips_collected` | int | 0 | runtime | Cumul session/jour |
+| `grid` | object | `{x,y}` | runtime | Coord grille |
+| `iso_x/iso_y` | int | - | rendu | Proj iso |
+| `z_index` | int | - | rendu | Tri profondeur |
+| `hitbox` | enum | `base_sprite` | rendu | Click sur base |
+
+#### Caractéristiques Initiales (tableau détaillé)
+
+| Caractéristique | Valeur initiale | Unité | Notes |
+|---|---:|---|---|
+| Rayon effet | 3 | cases | `radius` |
+| Chance pourboire | 5% | / tick perf | modulée par `charisma` |
+| Bonus happiness | +0.1 × `charisma` | / tick | clamp max par visiteur |
+| Pause requise | 10 | min in-game | après perf continue |
+| Cooldown show spécial | 30 | min in-game | après activation |
+
+#### Scores Initiaux (tableau détaillé)
+
+| Score | Valeur initiale | Plage | Impact |
+|---|---:|---|---|
+| Satisfaction locale | 0 | -100..+100 | S’ajoute au calcul visiteur |
+| Densité foule | 0 | 0..∞ | Conditionne bouchons |
+| Revenu tips/jour | 0 | 0..∞ | Finance zoo |
+
+### 2. Cycles de Vie et Apparition (tableau détaillé)
+
+| Phase | Déclencheur | Entrées | Sorties | Invariants |
+|---|---|---|---|---|
+| Apparition | Embauche | coins, config | entité artiste | créé en `IDLE` |
+| Activité | Tick | position, visiteurs | effets | pas de perf si `BREAK` |
+| Disparition | Licenciement (si prévu) | - | suppression | pas de suppression si en show (attendre fin) |
+
+#### Conditions d'Apparition (tableau détaillé)
+
+| Condition | Seuil | Opérateur | Résultat |
+|---|---:|---|---|
+| Achat employé | coins ≥ `hire_cost` | vrai | création |
+| Cap employé | slots > employés actifs | vrai | autorisé |
+
+#### Conditions de Disparition (tableau détaillé)
+
+| Condition | Seuil | Opérateur | Résultat |
+|---|---:|---|---|
+| Licenciement | action joueur | vrai | suppression + arrêt effets |
+| Zoo supprimé | - | vrai | suppression |
+
+#### Hérédité (tableau détaillé)
+
+| Élément | Hérité | Règle |
+|---|---|---|
+| `subtype` | Oui | reste identique |
+| Stats (charisma/radius) | Oui | persistées |
+| Tips collectés | Non | remis à 0 par jour |
+
+### 3. Impacts Environnementaux
+
+#### Impact Température (tableau détaillé)
+
+| Température | Effet sur artiste | Effet sur visiteurs | Condition |
+|---|---|---|---|
+| < 0°C | perf -20% | satisfaction - | si pas d’abris proches |
+| 15–25°C | neutre | neutre | - |
+| > 35°C | perf -10% (fatigue) | incidents “soif” + | canicule |
+
+#### Impact Milieu (Biome) (tableau détaillé)
+
+| Biome | Effet | Notes |
+|---|---|---|
+| Chemin pavé | foule + | visitors préfèrent rester sur chemins |
+| Boue / marécage | perf - | gêne visuelle + saleté |
+| Pont | neutre | éviter attroupement sur pont étroit |
+
+#### Impact Saisons (tableau détaillé)
+
+| Saison | Effet | Modificateur |
+|---|---|---|
+| Été | demande shows + | tips +10% |
+| Hiver | shows indoor | perf -10% si extérieur |
+
+#### Impact Heure / Jour-Nuit (tableau détaillé)
+
+| Période | Effet | Règle |
+|---|---|---|
+| 10h–16h | affluence max | perf prioritaire |
+| 18h–20h | sortie visiteurs | show spécial conseillé |
+| Nuit | zoo fermé | artiste `IDLE` |
+
+### 4. Impacts Biologiques et Sociaux
+
+#### Impact Reproduction (tableau détaillé)
+
+| Facteur | Effet sur taux | Condition |
+|---|---|---|
+| Foule bruyante | -5% | si densité > seuil près d’enclos |
+| Show doux (musician) | +2% | si proche enclos et calme |
+
+#### Impact Mort (tableau détaillé)
+
+| Cas | Effet | Condition |
+|---|---|---|
+| Accident foule | incident | si bouchon + chemins étroits |
+| Animal mort visible | choc | artiste stop perf, foule se disperse |
+
+#### Impact Nourriture (tableau détaillé)
+
+| Ressource | Effet | Condition |
+|---|---|---|
+| Boisson visiteur | ventes + | show près boutique boisson |
+| Nourriture artiste | coût | si mécanique employé nourrit (option) |
+
+#### Impact Attractivité(Visiteurs (tableau détaillé)
+
+| Action/État | Gain attractivité | Rayon | Notes |
+|---|---:|---:|---|
+| Performance active | +5 | 3 cases | cumul limité par zone |
+| Show spécial | +20 | 5 cases | déclenche attroupement |
+
+#### Impact Attractivité Animaux) (tableau détaillé)
+
+| Action/État | Effet animaux | Condition |
+|---|---|---|
+| Bruit clown | stress + | espèces sensibles |
+| Musique douce | stress - | espèces calmes |
+
+#### Impact Valeur (tableau détaillé)
+
+| Facteur | Variation | Condition |
+|---|---:|---|
+| Tips collectés | +coins | par tick perf |
+| Réputation zoo | + | si artistes actifs sans incidents |
+
+### 5. Impacts Logistiques et Économiques
+
+#### Vitesse (Camion) (tableau détaillé)
+
+| Paramètre | Effet | Condition |
+|---|---|---|
+| Livraison employés | neutre | pas d’impact direct |
+
+#### Vitesse (Nurserie) (tableau détaillé)
+
+| Paramètre | Effet | Condition |
+|---|---|---|
+| - | aucun | artiste n’affecte pas nurserie |
+
+#### Vitesse (Accueil) (tableau détaillé)
+
+| Paramètre | Effet | Condition |
+|---|---|---|
+| File entrée | + lente | foule show proche billeterie |
+
+#### Vitesse (Recherche) (tableau détaillé)
+
+| Paramètre | Effet | Condition |
+|---|---|---|
+| - | aucun | - |
+
+#### Vitesse (Labo) (tableau détaillé)
+
+| Paramètre | Effet | Condition |
+|---|---|---|
+| - | aucun | - |
+
+#### Vitesse (Visite) (tableau détaillé)
+
+| Paramètre | Effet | Condition |
+|---|---|---|
+| Temps de séjour | + | performance active |
+| Déplacement | - | si attroupement crée bouchon |
+
+#### Dépenses (Billeterie) (tableau détaillé)
+
+| Poste | Coût | Unité | Condition |
+|---|---:|---|---|
+| Gestion file | 0 | - | - |
+
+#### Dépenses (Boutiques) (tableau détaillé)
+
+| Poste | Coût | Unité | Condition |
+|---|---:|---|---|
+| Stock goodies show | variable | coins | si boutique vend souvenirs |
+
+#### Dépenses (Visiteurs) (tableau détaillé)
+
+| Poste | Coût | Unité | Condition |
+|---|---:|---|---|
+| Pourboires | +revenu (pas dépense) | coins | tips |
+
+#### Dépenses (Employés) (tableau détaillé)
+
+| Poste | Coût | Unité | Condition |
+|---|---:|---|---|
+| Salaire artiste | `salary` | coins/jour | employé actif |
+| Embauche | `hire_cost` | coins | à l’achat |
+
+#### Dépenses (Boutiques) (tableau détaillé)
+
+| Poste | Coût | Unité | Condition |
+|---|---:|---|---|
+| Cross-sell | - | - | section dupliquée conservée |
+
+#### Dépenses (Nurseries) (tableau détaillé)
+
+| Poste | Coût | Unité | Condition |
+|---|---:|---|---|
+| - | 0 | - | - |
+
+#### Dépenses (Nourriture) (tableau détaillé)
+
+| Poste | Coût | Unité | Condition |
+|---|---:|---|---|
+| Snacks show | 10 | coins | option “stand temporaire” |
+
+#### Dépenses (Acceuil des animaux) (tableau détaillé)
+
+| Poste | Coût | Unité | Condition |
+|---|---:|---|---|
+| - | 0 | - | - |
+
+#### Dépenses (Camion) (tableau détaillé)
+
+| Poste | Coût | Unité | Condition |
+|---|---:|---|---|
+| - | 0 | - | - |
+
+#### Trajet Visiteurs
+
+##### Trajet Visiteurs vers/depuis la ville (tableau détaillé)
+
+| Source | Destination | Déclencheur | Effet |
+|---|---|---|---|
+| Ville | Zoo | réputation/attractivité | l’artiste n’affecte pas le flux initial |
+
+##### Trajet Visiteurs vers/depuis les animaux (tableau détaillé)
+
+| Source | Destination | Déclencheur | Effet |
+|---|---|---|---|
+| Show | Enclos proche | curiosité | détour possible, congestion |
+
+##### Trajet Visiteurs vers/depuis les boutiques (tableau détaillé)
+
+| Source | Destination | Déclencheur | Effet |
+|---|---|---|---|
+| Show | Boutique | soif/envie souvenir | augmente dépenses |
+
+##### Trajet Visiteurs vers/depuis la billeterie (entrées/sorties du zoo) (tableau détaillé)
+
+| Source | Destination | Déclencheur | Effet |
+|---|---|---|---|
+| Billeterie | Show proche | densité | risque file lente |
+
+### 6. Événements
+
+#### Événements du Jeu  (tableau détaillé)
+
+| Event | Déclencheur | Payload | Effet |
+|---|---|---|---|
+| `EMPLOYEE_HIRED` | embauche | type, id | ajoute entité |
+| `EMPLOYEE_SALARY_PAID` | fin jour | id, amount | dépense |
+
+#### Événements du Carte (tableau détaillé)
+
+| Event | Déclencheur | Effet |
+|---|---|---|
+| `CROWD_CONGESTION` | densité > seuil | ralentit pathing local |
+
+#### Événements du Zoo (tableau détaillé)
+
+| Event | Déclencheur | Effet |
+|---|---|---|
+| `ARTIST_SPECIAL_SHOW_START` | clic show | buff + FX |
+| `ARTIST_BREAK_START` | fatigue | stop perf |
+
+#### Événements du Ville / Visiteur (tableau détaillé)
+
+| Event | Déclencheur | Effet |
+|---|---|---|
+| `VISITOR_DONATION` | tip | coins + |
+
+#### Événements du Visiteur (tableau détaillé)
+
+| Event | Déclencheur | Effet |
+|---|---|---|
+| `VISITOR_HAPPINESS_GAIN` | tick perf | happiness + |
+
+#### Événements du Joueur (tableau détaillé)
+
+| Event | Déclencheur | Effet |
+|---|---|---|
+| `PLAYER_TRIGGER_SHOW` | bouton | démarre cooldown |
+
+### 7. Progression
+
+#### Tableau des Upgrades (tableau détaillé)
+
+| Niveau | Coût | Effet | Débloque |
+|---|---:|---|---|
+| 1 | 0 | artiste basic | subtype 1 |
+| 2 | 1000 | `radius` +1 | meilleur crowd control |
+| 3 | 2500 | tips +10% | bonus revenu |
+| 4 | 5000 | show spécial + | FX + durée |
+
+### 8. Logique et Interfaces
+
+#### Pseudo-code Impacts (tableau détaillé)
+
+| Fonction | Entrées | Sorties | Notes |
+|---|---|---|---|
+| `update_artist` | artiste, visiteurs proches | happiness/tips | cf. algo existant |
+| `trigger_special_show` | artiste | buff | cooldown |
+
+#### Messages d'Infos / Alerte (tableau détaillé)
+
+| ID | Niveau | Message | Condition |
+|---|---|---|---|
+| `ARTIST_ASSIGNED` | Info | "Artiste assigné." | assign ok |
+| `ARTIST_COOLDOWN` | Warning | "Show spécial en recharge." | cooldown actif |
+| `CROWD_BLOCKING` | Alerte | "Bouchon détecté près du show." | densité > seuil |
+
+## Annexes UX/UI
+
+### 1. Expérience Utilisateur (UX)
+
+#### Description UX (tableau détaillé)
+
+| Parcours | But | Friction | Réduction clics |
+|---|---|---|---|
+| Recruter artiste | augmenter attractivité | coûts/slots | achat direct depuis panneau Employés |
+| Lancer show | booster momentané | cooldown | bouton direct sur panneau artiste |
+
+#### Description UI (tableau détaillé)
+
+| Composant | Contenu | États |
+|---|---|---|
+| Panneau employé | salaire, rayon, subtype | IDLE/PERF/BREAK |
+| Bouton show spécial | cooldown + tooltip | enabled/disabled |
+
+#### Emplacement (tableau détaillé)
+
+| Zone UI | Position | Notes |
+|---|---|---|
+| HUD | menu Employés | accès rapide |
+| Carte | sprite artiste | sélection base |
+
+#### Intégration (tableau détaillé)
+
+| Intégration | Contrat | Notes |
+|---|---|---|
+| Pathfinding visiteurs | densité/obstacles | éviter ponts étroits |
+| Système incidents | foule/bouchons | événements dédiés |
+
+#### Navigation (tableau détaillé)
+
+| Action | Chemin | Résultat |
+|---|---|---|
+| Ouvrir panneau | clic artiste | panel visible |
+| Recruter | menu → confirmer | entité créée |
+
+#### Événements (tableau détaillé)
+
+| Event UI | Déclencheur | Effet |
+|---|---|---|
+| `OPEN_EMPLOYEE_PANEL` | clic artiste | ouvre panel |
+| `CLICK_SPECIAL_SHOW` | clic bouton | démarre show |
+
+#### Assets Skinables
+
+##### Musiques (tableau détaillé)
+
+| Asset | Usage | Durée | Notes |
+|---|---|---:|---|
+| `artist_theme_loop.mp3` | zone perf | loop | mix selon subtype |
+
+##### Sons (tableau détaillé)
+
+| Asset | Usage | Volume |
+|---|---|---|
+| `crowd_cheer.mp3` | show spécial | moyen |
+| `coin_tip.mp3` | tip | faible |
+
+##### Graphiques (tableau détaillé)
+
+| Asset | Usage | Contraintes |
+|---|---|---|
+| `artist_sprite_[subtype]_[dir].png` | sprite | 4 directions |
+| `fx_music_notes.png` | FX | overlay |
+
+##### Images (tableau détaillé)
+
+| Asset | Usage |
+|---|---|
+| `portrait_artist.png` | panel |
+| `icon_artist_mask.png` | liste employés |
+
+##### Vidéos (tableau détaillé)
+
+| Asset | Usage | Durée |
+|---|---|---:|
+| `artist_special_show.webm` | popup show | 1.2s |
+
+##### Animations (tableau détaillé)
+
+| Animation | Déclencheur | Notes |
+|---|---|---|
+| notes flottantes | perf active | cadence 1/s |
+| confetti | show spécial | burst |
+
+##### Couleurs (tableau détaillé)
+
+| Token | Valeur | Usage |
+|---|---|---|
+| `artist_primary` | #C86DD7 | UI |
+| `artist_accent` | #FF77AA | FX |
+
+##### Textes (tableau détaillé)
+
+| Clé | FR | EN |
+|---|---|---|
+| `artist.hire` | Recruter | Hire |
+| `artist.special_show` | Show spécial | Special show |
+
+##### Formes (tableau détaillé)
+
+| Élément | Forme | Notes |
+|---|---|---|
+| Badge cooldown | pill arrondi | lisible |
+| Zone radius | cercle iso-projeté | overlay |