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

## Définition
Entité active dans le jeu, qu'elle soit contrôlée par un humain, une IA ou un script.

## Types
- **Joueur** : Utilisateur humain gérant son zoo.
- **Bot** : IA gérant un zoo concurrent.
- **Visiteur** : PNJ se promenant dans le zoo.
- **Animal** : Entité biologique gérée par le joueur.
- **Staff (Employé / PNJ de service)** : Personnage de service (accueil, guichet, boutique, recherche, soin, sécurité, nurserie, laboratoire).

## Skins, thèmes et personnalisation
Les personnages (joueur, visiteurs, bots, staff) sont rendus avec une combinaison :
- **Thème global** : voir `theme.md` (palette, ambiance UI, décor, uniformes).
- **Skins** : voir `skin.md` et l’équipement/possession via `inventaire_skins.md`.

### Règles de rendu (contrat)
- Un personnage peut avoir des **variantes visuelles** (uniforme, accessoires, palette) déterminées par le thème et les skins équipés.
- Les personnages affichés dans une UI (portrait, badge, “paper doll”, bulle) doivent rester **cohérents** avec l’avatar/skin courant.
- Un même rôle (ex. “vendeur”) peut avoir plusieurs skins, mais **un skin actif** doit être explicite (pas d’auto-déduction silencieuse).

## Personnage contextuel de module (UI)
Certains modules affichent un **personnage contextuel** quand le module est actionné ou lorsqu’un événement lié au module survient.

### Objectifs
- **Ancrage** : associer un module à un rôle (ex. Nurserie → Nurse).
- **Interaction** : proposer des actions directes (1 clic) et des explications factuelles (état, cause, prochaine action).
- **Cohérence cosmétique** : appliquer thème + skins sur le personnage.

### Déclencheurs (génériques)
- **Ouverture / activation** : ouverture d’un panneau, sélection d’un bâtiment, entrée dans un mode (build, gestion).
- **Événement module** : arrivée, incident, succès d’une action, blocage explicite (fonds insuffisants, capacité pleine, gating réputation).
- **État critique** : un statut “critique” du module est actif (ex. nurserie pleine, alerte quarantaine, alerte sécurité).

### Interactions (génériques)
- **Clic** : ouvre l’écran/action la plus pertinente du module (deep-link).
- **Survol / tap** : affiche une fiche courte (rôle + état + action possible).
- **Dialogue/bulle** : messages informatifs liés à un événement (sans “best effort”, sans masquage d’erreur).

### Index des rôles (spécifications associées)
- **Visiteurs homme/femme** : `visiteur.md`
- **Joueur actif (avatar + pseudo + skins + profil)** : `joueur.md`, `avatar_joueur.md`, `inventaire_skins.md`
- **Autres joueurs** : `joueur.md` (représentation externe) + `avatar_joueur.md` (portrait partagé)
- **Bots** : `bot.md`
- **Chercheur** : `chercheur.md`
- **Nourisseur** : `nourisseur.md`
- **Soigneur** : `soigneur.md`
- **Agent de sécurité** : `agent_securite.md`
- **Nurse (nurserie)** : `nurse.md`
- **Personnel d’accueil (nouveaux animaux)** : `personnel_accueil.md`
- **Guichetière (billetterie)** : `guichetiere.md`
- **Vendeur (boutique)** : `vendeur.md`
- **Vendeur “achat en pièces” (menu achats / conversion monnaies)** : `vendeur_pieces.md`
- **Laborantin (site laboratoire carte monde)** : `laborantin.md`
- **Maire (ville / carte monde)** : `maire.md`

# Annexes Techniques

## 1. Données et États
### Modèle de Données (JSON)
Classe abstraite ou interface commune.
```json
{
  "id": "uuid",
  "type": "enum('player','bot','visitor','animal','staff')",
  "created_at": "timestamp",
  "updated_at": "timestamp",
  "position": { "x": "int", "y": "int" },
  "active": "boolean",
  "status_flags": ["enum('selected','moving','interacting','hidden','dead','sleeping','busy')"],
  "hitbox": "enum('tile','base_sprite','custom_polygon')",
  "iso_x": "integer",
  "iso_y": "integer",
  "z_index": "integer"
}
```

### Caractéristiques Initiales
| Caractéristique | Valeur Initiale | Type | Description |
|---|---|---|---|
| active | true | bool | L’entité est simulée/rendue si active. |
| hitbox | base_sprite | enum | Sélection via base sprite (isométrique). |
| status_flags | [] | enum[] | Liste vide au spawn, enrichie par le comportement. |

### Scores Initiaux
| Score | Valeur Initiale | Plage (Min-Max) | Impact |
|---|---:|---|---|
| visibilité | 100 | 0-100 | Probabilité d’être rendu/affiché (ex. foule dense). |
| priorité interaction | 50 | 0-100 | Arbitre quel élément capte le clic en cas de chevauchement. |

## 2. Cycles de Vie et Apparition
### Conditions d'Apparition
| Condition | Seuil | Opérateur | Résultat |
|---|---:|---|---|
| Spawn système | true | Est | Création de l’entité (par règle métier). |
| Ressources dispo | selon type | >= | Autorise création (ex. staff payé). |

### Conditions de Disparition
| Condition | Seuil | Opérateur | Résultat |
|---|---:|---|---|
| active | false | Est | Retrait du rendu/simulation. |
| status_flags contient dead | true | Est | Retrait ou état “cadavre” selon design. |

### Hérédité
| Parent | Trait Transmis | Probabilité | Mutation Possible |
|---|---|---:|---|
| Classe dérivée | Champs spécifiques | 100% | Non |
| Skins | Palette/cosmétiques | 100% | Non |

## 3. Impacts Environnementaux
### Impact Température
| Plage Température | Effet sur l’entité | Bonus/Malus |
|---|---|---|
| < 0°C | Animations “froid” (si entité sensible) | vitesse -10% (visiteurs) |
| > 30°C | Animations “chaud” | soif +20% (visiteurs) |

### Impact Milieu (Biome)
| Biome | Compatibilité | Bonus/Malus |
|---|---:|---|
| Chemin | 100% | coût de mouvement 1.0 |
| Herbe | 100% | coût de mouvement 1.2 |
| Boue | 60% | coût de mouvement 1.5 |

### Impact Saisons
| Saison | Effet | Modificateur |
|---|---|---|
| Été | foule + | visiteurs + |
| Hiver | foule - | visiteurs - |

### Impact Heure / Jour-Nuit
| Période | Activité | Visibilité |
|---|---|---|
| Jour | simulation normale | haute |
| Nuit | entités “dorment” selon type | moyenne/basse |

## 4. Impacts Biologiques et Sociaux
### Impact Reproduction
| Facteur | Effet sur Taux | Condition |
|---|---|---|
| Proximité | augmente | si entité = animal |

### Impact Mort
| Cause | Conséquence | Durée |
|---|---|---|
| État critique | passage dead | selon règles type |

### Impact Nourriture
| Type Nourriture | Gain Santé | Coût | Préférence |
|---|---:|---:|---:|
| selon type | variable | variable | 1–5 |

### Impact Attractivité (Visiteurs/Animaux)
| Action/État | Gain Attractivité | Rayon d'action |
|---|---:|---:|
| entité rare visible | + | 8 cases |

### Impact Valeur
| Facteur | Variation Prix | Condition |
|---|---:|---|
| rareté cosmétique | + | si skin rare |

## 5. Impacts Logistiques et Économiques
### Vitesse (Camion/Nurserie/Accueil/Recherche/Labo/Visite)
| Domaine | Paramètre | Valeur | Unité |
|---|---|---:|---|
| Déplacement | coût de mouvement | >= 1.0 | multiplicateur |

### Dépenses (Boutiques/Visiteurs)
| Poste | Coût | Unité | Condition |
|---|---:|---|---|
| maintenance entité | variable | /jour | si staff/bâtiment associé |

### Trajet Visiteurs
| Trajet | Règle | Priorité | Notes |
|---|---|---:|---|
| vers POI | A* pondéré | 50 | chemins préférés |

## 6. Événements
### Événements du Jeu / Carte / Zoo / Ville / Visiteur
| Event | Déclencheur | Effet | Durée |
|---|---|---|---|
| `ENTITY_SPAWN` | création | rendu + simulation | instant |
| `ENTITY_DESPAWN` | suppression | retrait | instant |

## 7. Progression
### Tableau des Upgrades
| Niveau | Coût | Prérequis | Bonus Débloqué |
|---|---:|---|---|
| 1 | 0 | - | comportement de base |

## 8. Logique et Interfaces
### Pseudo-code Impacts
```text
computeZIndex(x, y):
  return y * 1000 + x

hitTest(click):
  candidates = entities.sortedBy(z_index desc)
  return first(entity where click inside entity.hitbox)
```

### Messages d'Infos / Alerte
| Type | Message | Condition | Priorité |
|---|---|---|---:|
| Info | "Entité sélectionnée." | clic valide | 2 |
| Warn | "Interaction impossible." | état busy/dead | 4 |

# 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)
### Identification (Passif)
**Description UX** : Reconnaître le type de personnage au premier coup d'œil.
**Description UI** : Silhouette distincte, Code couleur, Badge/Nom au survol.
**Emplacement** : Grille.
**Intégration** : Tooltip.
**Navigation** : Survol souris / Tap.
**Événements** : `HOVER_CHARACTER`.

#### Assets
- **Musiques** : `ui_hover_soft.mp3` (jingle court, optionnel).
- **Sons** : `ui_hover.mp3`, `ui_select.mp3`.
- **Graphiques** : Silhouettes archétypales.
- **Images** : `badge_player.png`, `badge_bot.png`, `badge_visitor.png`, `badge_animal.png`.
- **Vidéos** : `hover_glow.webm` (0.6s loop, optionnel).
- **Animations** : Glow pulse (hover), pop (select).
- **Couleurs** : Joueur (Bleu), Bot (Rouge/Gris), Visiteur (Multicolore), Animal (Naturel).
- **Textes** : Nom, Rôle.
- **Formes** : Badge rond + tooltip rect arrondi.