builazoo/docs/specs/skin.md

# Skin

## 1. Définition
Élément cosmétique permettant de modifier l'apparence de l'avatar du joueur ou de certains éléments du zoo (bâtiments, animaux). Les skins sont purement esthétiques et n'influencent pas les statistiques de gameplay (sauf mention contraire rare). Ils s'obtiennent via la boutique, les passes saisonniers ou des événements spéciaux.

## 2. Fonctions
*   **Personnalisation :** Permet au joueur de se différencier.
*   **Collection :** Incite à la progression et à l'achat (monétisation).
*   **Thématisation :** Renforce l'immersion lors des saisons (ex: skin Noël, Halloween).

## 3. Icone
*   **Représentation :** T-shirt plié ou Masque de carnaval.
*   **Couleur dominante :** Violet (souvent associé à la cosmétique/rare).

## 4. Interactions
*   **Achat :** Via le menu boutique ou menu skins.
*   **Équipement :** Via l'inventaire de skins (drag & drop ou clic).
*   **Visualisation :** Prévisualisation sur l'avatar ou l'objet avant validation.

## 5. Annexes Techniques

### Données (JSON)
```json
{
  "skin_id": "skin_hat_pirate",
  "name": "Chapeau de Pirate",
  "type": "avatar_head", // "avatar_body", "zoo_building", "animal_texture"
  "rarity": "rare",
  "source": "shop", // "pass", "event", "achievement"
  "price": {
    "amount": 500,
    "currency": "coins"
  },
  "asset_path": "assets/skins/avatar/head/pirate_hat.png",
  "iso_x": "integer",
  "iso_y": "integer",
  "z_index": "integer"
}
```

### Règles Métier
*   Un skin acheté est acquis définitivement (sauf skins liés à un passe temporaire expiré pour les non-VIP).
*   Certains skins sont exclusifs à un genre d'avatar ou un type de bâtiment.

## 6. Annexes UX/UI
*   **Inventaire :** Grille d'icônes représentant les skins possédés.
*   **Rareté :** Bordure de couleur autour de l'icône (Gris=Commun, Vert=Atypique, Bleu=Rare, Violet=Épique, Or=Légendaire).
*   **Notification :** "Nouveau skin débloqué !" avec animation de coffre ou d'éclat.


# 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 |
|---|---|
| Concept | Skin = item cosmétique (avatar/zoo/animal/building/path). |
| Rôle | Modifier l’apparence sans modifier les stats (sauf si explicitement listé et validé). |
| Acquisition | Boutique, passe, événement, achievement. |
| Gating | Skins pass/thèmes : selon règles `passe_saisonnier.md` + `vip.md`. |

## Fonctions (tableau détaillé)

| Fonction | Déclencheur | Entrées | Sorties | Règles | Observabilité |
|---|---|---|---|---|---|
| Afficher catalogue | UI open | filtres | liste skins | Tri par rareté/type, sans cache applicatif | Event `SKIN_CATALOG_OPEN` |
| Acheter | clic achat | coins, prix | item acquis | Transaction atomique ; idempotence sur retry | Event `SKIN_PURCHASED` |
| Équiper | clic equip | inventaire | `equipped` | Un seul par slot ; compatibilité type | Event `SKIN_EQUIPPED` |
| Prévisualiser | hover/clic | skin_id | preview render | Ne modifie pas l’état tant que non validé | Event `SKIN_PREVIEW` |
| Appliquer au zoo | apply | theme/skin | rendu map | Mise à jour rendu sans fallback silencieux | Event `ZOO_SKIN_APPLIED` |

## Icone de base

| Élément | Spécification |
|---|---|
| Représentation | T-shirt / masque |
| Couleur dominante | Violet (cosmétique) |
| Variantes | `icon_skin_shirt.png`, `icon_skin_mask.png` |
| États | Bordure rareté, lock, “new” |

## Interactions (tableau détaillé)

| Interaction | Type | Préconditions | Étapes UI | Résultat | Erreurs / Messages |
|---|---|---|---|---|---|
| Ouvrir inventaire | Consultation | - | Profil → Skins | grille | - |
| Filtrer | Action | - | catégories/rareté | liste filtrée | - |
| Prévisualiser | Consultation | item visible | clic item | preview | - |
| Équiper | Action | possédé | “Équiper” | slot update | `SKIN_LOCKED`, `INCOMPATIBLE_SKIN` |
| Acheter | Action | coins suffisants | “Acheter” | possédé | `INSUFFICIENT_FUNDS` |

## Annexes Techniques

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

| Donnée / État | Type | Exemple | Source | Contraintes |
|---|---|---|---|---|
| `skin_id` | string | `skin_hat_pirate` | config | unique |
| `name` | string | `Chapeau de Pirate` | i18n | affichage |
| `type` | enum | `avatar_head|avatar_body|zoo_building|animal_texture|path_texture|banner_material` | config | whitelist |
| `rarity` | enum | `common|uncommon|rare|epic|legendary` | config | bordures |
| `source` | enum | `shop|pass|event|achievement` | config | gating |
| `price.amount` | int | 500 | config | coins |
| `asset_path` | string | - | build | pas de remote |
| `compatibility` | object | - | config | slot/gender/type |
| `lifecycle.available_from/to` | date|null | - | config | gating saison |
| `timestamps.created_at/updated_at` | timestamp | - | DB | audit |

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

| Caractéristique | Valeur initiale | Unité | Notes |
|---|---:|---|---|
| Slots avatar | 3 | slots | head/body/accessory |
| Skins zoo | 0 | count | départ |
| Prix base rare | 500 | coins | exemple |

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

| Score | Valeur initiale | Plage | Impact |
|---|---:|---|---|
| Skins possédés | 0 | 0..∞ | collection |
| Rareté max | common | enum | gating UI |

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

| Phase | Déclencheur | Entrées | Sorties | Invariants |
|---|---|---|---|---|
| Apparition | config | pass/event/shop | item visible | depends dates |
| Acquisition | achat/gain | coins/xp | possédé | idempotent |
| Équipement | action | skin_id | slot update | 1 per slot |
| Gating | VIP/pass | vip/pass state | allow/deny | suspension vs perte |

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

| Condition | Seuil | Opérateur | Résultat |
|---|---:|---|---|
| Disponible | date in window | vrai | visible |

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

| Condition | Seuil | Opérateur | Résultat |
|---|---:|---|---|
| Retrait shop | date > to | vrai | non achetable (reste possédé si acquis) |

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

| Élément | Hérité | Règle |
|---|---|---|
| Skin acheté | Oui | persiste |
| Skin pass | Oui | persiste mais accès peut être gated si non VIP |

### 3. Impacts Environnementaux

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

| Condition | Effet | Notes |
|---|---|---|
| - | visuel uniquement | - |

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

| Biome | Effet | Notes |
|---|---|---|
| Jungle | skins adaptés | thématique |

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

| Saison | Effet | Notes |
|---|---|---|
| Noël | skins saison | dates |

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

| Période | Effet | Notes |
|---|---|---|
| Nuit | skins néon visibles | rendu |

### 4. Impacts Biologiques et Sociaux

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

| Facteur | Effet | Condition |
|---|---|---|
| - | aucun | cosmétiques |

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

| Cas | Effet | Condition |
|---|---|---|
| - | aucun | - |

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

| Ressource | Effet | Condition |
|---|---|---|
| - | aucun | - |

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

| Action/État | Effet | Condition |
|---|---|---|
| Skins zoo | attractivité + | esthétique |

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

| Action/État | Effet animaux | Condition |
|---|---|---|
| Texture animal | visuel | pas de stats |

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

| Facteur | Variation | Condition |
|---|---:|---|
| Collection rare | + | prestige |

### 5. Impacts Logistiques et Économiques

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

| Paramètre | Effet | Condition |
|---|---|---|
| - | aucun | - |

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

| Paramètre | Effet | Condition |
|---|---|---|
| - | aucun | - |

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

| Paramètre | Effet | Condition |
|---|---|---|
| - | aucun | - |

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

| Paramètre | Effet | Condition |
|---|---|---|
| Déblocage skins | visible | via RP/achievements |

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

| Paramètre | Effet | Condition |
|---|---|---|
| - | aucun | - |

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

| Paramètre | Effet | Condition |
|---|---|---|
| Temps visite | + | attractivité via skins |

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

| Poste | Coût | Unité | Condition |
|---|---:|---|---|
| - | 0 | - | - |

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

| Poste | Coût | Unité | Condition |
|---|---:|---|---|
| Achat skin | prix | coins | shop |

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

| Poste | Coût | Unité | Condition |
|---|---:|---|---|
| - | 0 | - | - |

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

| Poste | Coût | Unité | Condition |
|---|---:|---|---|
| - | 0 | - | - |

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

| Poste | Coût | Unité | Condition |
|---|---:|---|---|
| Section dupliquée | 0 | - | 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 |
|---|---:|---|---|
| - | 0 | - | - |

#### 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 | esthétique | skins indirect |

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

| Source | Destination | Déclencheur | Effet |
|---|---|---|---|
| - | - | - | - |

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

| Source | Destination | Déclencheur | Effet |
|---|---|---|---|
| Visiteur | Boutique | envie souvenir | achat |

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

| Source | Destination | Déclencheur | Effet |
|---|---|---|---|
| - | - | - | - |

### 6. Événements

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

| Event | Déclencheur | Payload | Effet |
|---|---|---|---|
| `SKIN_PURCHASED` | achat | skin_id | possédé |

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

| Event | Déclencheur | Effet |
|---|---|---|
| `SKIN_PREVIEW` | preview | render |

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

| Event | Déclencheur | Effet |
|---|---|---|
| `ZOO_SKIN_APPLIED` | apply | update visuel |

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

| Event | Déclencheur | Effet |
|---|---|---|
| - | - | - |

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

| Event | Déclencheur | Effet |
|---|---|---|---|
| - | - | - |

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

| Event | Déclencheur | Effet |
|---|---|---|---|
| `SKIN_EQUIPPED` | equip | slot update |

### 7. Progression

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

| Niveau | Coût | Effet | Débloque |
|---|---:|---|---|
| 1 | 0 | inventaire skins | equip |

### 8. Logique et Interfaces 

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

| Fonction | Entrées | Sorties | Notes |
|---|---|---|---|
| `equipSkin` | skin_id, slot | ok/err | compat |
| `applyRarityBorder` | rarity | css/token | UI |

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

| ID | Niveau | Message | Condition |
|---|---|---|---|
| `SKIN_LOCKED` | Warning | "Skin verrouillé." | non possédé |
| `INCOMPATIBLE_SKIN` | Warning | "Skin incompatible." | slot/type |
| `INSUFFICIENT_FUNDS` | Warning | "Pièces insuffisantes." | achat |

## Annexes UX/UI 

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

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

| Parcours | But | Friction | Réduction clics |
|---|---|---|---|
| Equiper | custom avatar | navigation | accès direct depuis avatar HUD |

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

| Composant | Contenu | États |
|---|---|---|
| Grille skins | items | owned/locked |
| Preview | paper doll | slots |

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

| Zone UI | Position | Notes |
|---|---|---|
| Profil | onglet skins | - |

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

| Intégration | Contrat | Notes |
|---|---|---|
| Inventaire | items possédés | pas de cache |

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

| Action | Chemin | Résultat |
|---|---|---|
| Ouvrir | profil | grille |

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

| Event UI | Déclencheur | Effet |
|---|---|---|
| `OPEN_SKIN_INVENTORY` | clic | modal |

#### Assets Skinables

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

| Asset | Usage | Durée | Notes |
|---|---|---:|---|
| `skins_loop.mp3` | screen | loop | - |

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

| Asset | Usage | Volume |
|---|---|---|
| `equip_click.mp3` | equip | faible |

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

| Asset | Usage | Contraintes |
|---|---|---|
| `rarity_border.png` | UI | 5 couleurs |

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

| Asset | Usage |
|---|---|
| `skin_thumb.png` | item |

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

| Asset | Usage | Durée |
|---|---|---:|
| `skin_unlock.webm` | unlock | 1.0s |

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

| Animation | Déclencheur | Notes |
|---|---|---|
| glow | unlock | 0.8s |

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

| Token | Valeur | Usage |
|---|---|---|
| `rarity_common` | #B0B0B0 | border |
| `rarity_legendary` | #D4AF37 | border |

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

| Clé | FR | EN |
|---|---|---|
| `skin.equip` | Équiper | Equip |
| `skin.buy` | Acheter | Buy |

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

| Élément | Forme | Notes |
|---|---|---|
| Carte skin | carré arrondi | grid |