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)

{
  "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
rarity	enum	`common	uncommon	rare
source	enum	`shop	pass	event
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
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