builazoo/docs/specs/avatar_joueur.md

Avatar Joueur

1. Définition

Représentation visuelle du joueur dans l'interface du jeu. L'avatar est personnalisable (genre, apparence, vêtements) et s'affiche en permanence dans un coin de l'écran (généralement en haut à gauche ou à droite, à définir selon l'UI). Il sert d'identité visuelle pour le profil du joueur et est visible par les autres joueurs lors des visites ou classements.

2. Fonctions

• Personnalisation : Permet au joueur de choisir le genre (Homme/Femme) et d'équiper des skins (chapeaux, vêtements, accessoires).
• Identité : Associé au pseudonyme du joueur et à son niveau.
• Feedback Visuel : Peut réagir aux événements du zoo (sourire si tout va bien, inquiet si problème).
• Social : S'affiche sur la carte du monde à côté du zoo du joueur.
• NPC Directeur : Une version miniature de l'avatar se promène physiquement dans le zoo pour inspecter les enclos.

3. Icone

• Représentation : Tête de l'avatar actuel dans un cadre circulaire ou carré.
• Couleur dominante : Dépend des skins équipés.

4. Interactions

• Click : Ouvre le menu de profil du joueur et l'inventaire de skins.
• Survol : Affiche le niveau actuel et le titre du joueur (ex: "Directeur Débutant").
• Level Up : Animation spéciale lorsque le joueur gagne un niveau.

5. Annexes Techniques

Données (JSON)

{
  "avatar_id": "player_12345",
  "gender": "female", // "male" | "female"
  "level": 12,
  "experience": 4500,
  "next_level_xp": 5000,
  "title": "Expert Zoologist",
  "equipped_skins": {
    "head": "skin_hat_safari",
    "body": "skin_shirt_ranger",
    "accessory": "skin_glasses_sun"
  },
  "unlocked_titles": ["Beginner", "Novice", "Expert"],
  "mood_state": "happy" // "happy" | "neutral" | "worried"
}

Règles Métier

• Le choix du genre est gratuit et modifiable.
• Les skins doivent être débloqués ou achetés avant d'être équipés.
• L'avatar est persistant entre les sessions.

6. Annexes UX/UI

• Emplacement : Coin supérieur (gauche ou droite) de l'interface principale (HUD).
• Style : Cartoon / Isométrique cohérent avec le reste du jeu.
• Feedback : Animation légère (clignement des yeux, mouvement de tête).
• Vue Isométrique : Le "Directeur" (NPC) a un pathfinding aléatoire mais priorise les zones à problèmes (animaux malades, déchets).

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é	Avatar du joueur (HUD) + “Directeur” (NPC miniature)
Rôle	Identité visuelle (pseudo/niveau/titre), personnalisation par skins, feedback d’état global du zoo.
Visibilité	Toujours visible dans le HUD ; visible sur carte monde et potentiellement en visite/classements.
Vue	Isométrique 2.5D (NPC), sprite 4 directions, hitbox base-sprite pour sélection NPC.

Fonctions (tableau détaillé)

Fonction	Déclencheur	Entrées	Sorties	Règles	Observabilité
Personnaliser	Action joueur	inventaire skins, genre	equipped_skins	Équiper uniquement skins possédés ; genre modifiable	Event AVATAR_EQUIP, AVATAR_GENDER_SET
Afficher identité	HUD render	pseudo, level, title	UI avatar	Toujours présent ; tooltip au hover	Event HUD_AVATAR_RENDER
Réagir état zoo	Tick / événements	incidents, survie, réputation	mood_state + anim	Mapping déterministe (pas de “best effort”)	Event AVATAR_MOOD_CHANGED
Level-up	XP gain	xp, seuil	level+1	Animation + textes	Event PLAYER_LEVEL_UP
NPC Directeur	Tick IA	heatmap incidents	déplacement	Priorise zones critiques, respecte chemins	Event DIRECTOR_NPC_MOVE

Icone de base

Élément	Spécification
Représentation	Portrait tête (cadre rond/carré)
Couleur dominante	Dépend skins équipés
Variantes	avatar_frame_round.png, avatar_frame_square.png
États	Badge niveau, badge humeur (🙂/😟) via icônes, pas d’emoji dans UI final (icônes).

Interactions (tableau détaillé)

Interaction	Type	Préconditions	Étapes UI	Résultat	Erreurs / Messages
Ouvrir profil	Action	-	Clic avatar HUD	ouvre panneau profil	-
Ouvrir inventaire skins	Action	-	Profil → onglet Skins	liste + preview	NO_SKIN_OWNED (info)
Équiper skin	Action	skin possédé	Clic skin → “Équiper”	update equipped_skins	SKIN_LOCKED
Changer genre	Action	-	Profil → genre	update gender	-
Inspecter NPC	Consultation	NPC visible	Clic base sprite NPC	mini panel	-

Annexes Techniques

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

Donnée / État	Type	Exemple	Source	Contraintes
avatar_id	string/uuid	player_12345	DB	unique
gender	enum	`male	female`	DB
level	int	12	DB	monotone
experience	int	4500	DB	0..∞
next_level_xp	int	5000	config	recalcul
title	string	Expert Zoologist	DB	liste débloquée
equipped_skins.head/body/accessory	string	skin_hat_safari	DB	doit être possédé
unlocked_titles	string[]	-	DB	append-only
mood_state	enum	`happy	neutral	worried`
director_npc	object	-	runtime	si feature active
grid	object	{x,y}	runtime	NPC
iso_x/iso_y	int	-	rendu	NPC
z_index	int	-	rendu	NPC
hitbox	enum	base_sprite	rendu	NPC

Caractéristiques Initiales (tableau détaillé)

Caractéristique	Valeur initiale	Unité	Notes
Genre	male/female	enum	choix initial
Niveau	1	level	départ
Mood	neutral	enum	départ
Slots skins	3	slots	head/body/accessory
NPC directeur	actif	bool	si feature

Scores Initiaux (tableau détaillé)

Score	Valeur initiale	Plage	Impact
XP	0	0..∞	progression
Prestige (titre)	0	0..∞	cosmétiques
Incidents vus (NPC)	0	0..∞	debug IA

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

Phase	Déclencheur	Entrées	Sorties	Invariants
Création	création compte	pseudo	avatar	persisté
Session	login	state	render	HUD constant
Level-up	XP seuil	xp	level+1	animation
Disparition	suppression compte	-	supprimé	-

Conditions d'Apparition (tableau détaillé)

Condition	Seuil	Opérateur	Résultat
Compte créé	true	est	avatar créé

Conditions de Disparition (tableau détaillé)

Condition	Seuil	Opérateur	Résultat
Compte supprimé	true	est	supprimé

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

Élément	Hérité	Règle
Skins équipés	Oui	persiste
Titres	Oui	persiste
Mood	Non	recalcul à l’ouverture session

3. Impacts Environnementaux

Impact Température (tableau détaillé)

Condition	Effet	Notes
Canicule	mood plus “worried”	si incidents chaleur

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

Biome	Effet	Notes
Chemins	NPC préfère	pathing

Impact Saisons (tableau détaillé)

Saison	Effet	Notes
Hiver	tenue “hiver” (si skin)	visuel option

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

Période	Effet	Notes
Nuit	NPC plus lent / rentre	zoo fermé

4. Impacts Biologiques et Sociaux

Impact Reproduction (tableau détaillé)

Facteur	Effet	Condition
Mood “happy”	aucun direct	UI seulement

Impact Mort (tableau détaillé)

Cas	Effet	Condition
Mort animal	mood worried	événement mort

Impact Nourriture (tableau détaillé)

Ressource	Effet	Condition
-	aucun	avatar ne consomme pas

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

Action/État	Effet	Condition
Avatar soigné (skins VIP)	perception +	cosmétique

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

Action/État	Effet animaux	Condition
NPC inspecte	stress +/-	si s’approche

Impact Valeur (tableau détaillé)

Facteur	Variation	Condition
Skins rares	valeur compte +	cosmétique

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

Vitesse (Labo) (tableau détaillé)

Paramètre	Effet	Condition
-	aucun	-

Vitesse (Visite) (tableau détaillé)

Paramètre	Effet	Condition
-	aucun	-

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

Poste	Coût	Unité	Condition
-	0	-	-

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

Poste	Coût	Unité	Condition
Achat skins	variable	coins	boutique

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	réputation	avatar 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
-	-	-	-

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
PLAYER_LEVEL_UP	xp seuil	level	anim

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

Event	Déclencheur	Effet
DIRECTOR_NPC_MOVE	tick	déplacement

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

Event	Déclencheur	Effet
AVATAR_MOOD_CHANGED	incidents	expression

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

Event	Déclencheur	Effet
SHOW_PLAYER_AVATAR	visite/classement	portrait

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

Event	Déclencheur	Effet
VISITOR_SEE_OWNER	proximité NPC	réaction

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

Event	Déclencheur	Effet
AVATAR_EQUIP	equip	update

7. Progression

Tableau des Upgrades (tableau détaillé)

Niveau	Coût	Effet	Débloque
1	0	avatar base	3 slots
2	0	titres	badges
3	1000	emotes	mood FX

8. Logique et Interfaces

Pseudo-code Impacts (tableau détaillé)

Fonction	Entrées	Sorties	Notes
computeMoodState	incidents/survie	mood_state	mapping
renderAvatarHud	avatar	DOM	-

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

ID	Niveau	Message	Condition
SKIN_LOCKED	Warning	"Skin non débloqué."	equip fail
PLAYER_LEVEL_UP	Info	"Niveau supérieur !"	level up

Annexes UX/UI

1. Expérience Utilisateur (UX)

Description UX (tableau détaillé)

Parcours	But	Friction	Réduction clics
Accéder skins	personnaliser	navigation	clic avatar → onglet skins direct

Description UI (tableau détaillé)

Composant	Contenu	États
HUD avatar	portrait + badge	hover
Panel skins	grille + preview	equip

Emplacement (tableau détaillé)

Zone UI	Position	Notes
HUD	coin sup	fixe

Intégration (tableau détaillé)

Intégration	Contrat	Notes
Inventaire skins	items	cf. inventaire_skins.md

Navigation (tableau détaillé)

Action	Chemin	Résultat
Ouvrir profil	clic	panel

Événements (tableau détaillé)

Event UI	Déclencheur	Effet
OPEN_PROFILE	clic avatar	panel

Assets Skinables

Musiques (tableau détaillé)

Asset	Usage	Durée	Notes
ui_profile_loop.mp3	panel	loop	discret

Sons (tableau détaillé)

Asset	Usage	Volume
ui_open.mp3	open	faible
equip_click.mp3	equip	faible

Graphiques (tableau détaillé)

Asset	Usage	Contraintes
avatar_portrait.png	HUD	-
director_sprite_[dir].png	NPC	4 dirs

Images (tableau détaillé)

Asset	Usage
icon_gender_male.png	switch
icon_gender_female.png	switch

Vidéos (tableau détaillé)

Asset	Usage	Durée
level_up.webm	level up	1.0s

Animations (tableau détaillé)

Animation	Déclencheur	Notes
blink	idle	loop
smile/frown	mood change	0.6s

Couleurs (tableau détaillé)

Token	Valeur	Usage
avatar_frame	#FFFFFF	cadre
avatar_badge	#FFD700	niveau

Textes (tableau détaillé)

Clé	FR	EN
profile.open	Profil	Profile
skins.open	Skins	Skins

Formes (tableau détaillé)

Élément	Forme	Notes
Avatar HUD	cercle	accessible
Boutons onglets	pills	lisible