builazoo/docs/specs/artiste.md

# Artiste

## 1. Définition
Employé dédié au divertissement des visiteurs. Il réalise des spectacles de rue, joue de la musique ou peint, augmentant ainsi le bonheur des visiteurs et leur temps de séjour dans le zoo. Achetable avec des pièces.

## 2. Fonctions
*   **Divertissement :** Crée une zone d'attractivité temporaire autour de lui.
*   **Bonheur :** Augmente la jauge de bonheur des visiteurs à proximité.
*   **Dons :** Peut générer de petits revenus supplémentaires (pourboires).

## 3. Icone
*   **Représentation :** Masque de théâtre ou Notes de musique.
*   **Couleur dominante :** Rose et Violet.

## 4. Interactions
*   **Recrutement :** Menu "Employés", coût en pièces.
*   **Placement :** Peut être assigné à une "scène" ou un point de passage stratégique.
*   **Performance :** Le joueur peut déclencher un "Show Spécial" (cooldown) pour un gros boost.

## 5. Annexes Techniques

### Données (JSON)
```json
{
  "employee_id": "artist_03",
  "type": "artiste",
  "subtype": "musician", // "clown", "painter", "juggler"
  "name": "Melody",
  "salary": 45,
  "hire_cost": 450,
  "state": "enum (IDLE, PERFORMING, BREAK)",
  "performance_cooldown_end": "timestamp",
  "stats": {
    "charisma": 15,
    "radius": 3, // Rayon d'effet
    "tips_collected": 0
  },
  "iso_x": "integer",
  "iso_y": "integer",
  "z_index": "integer"
}
```

### Règles Métier
*   L'efficacité diminue si l'artiste reste trop longtemps au même endroit (besoin de rotation ou de pause).
*   Attire les foules, ce qui peut créer des bouchons (à gérer avec les chemins).

### Algorithme de Performance
```python
def update_artist(artist, visitors_nearby):
    if artist.state == "PERFORMING":
        for visitor in visitors_nearby:
            visitor.happiness += artist.stats.charisma * 0.1
            visitor.stay_duration += 5 # minutes

            # Chance de pourboire
            if random() < 0.05:
                tip = random(1, 5)
                artist.tips_collected += tip
                add_coins(tip)
```

## 6. Annexes UX/UI
*   **Visuel Carte :** Personnage coloré, jonglant ou jouant d'un instrument.
*   **Effet :** Notes de musique ou étoiles flottant autour de lui.
*   **Son :** Musique d'ambiance locale quand on zoome dessus.
*   **Vue Isométrique :** Animation de jonglage ou de jeu d'instrument en boucle.


# 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.


## 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 |