builazoo/docs/specs/passe_saisonnier.md

Passe Saisonnier

1. Définition

Système de progression temporaire (durée typique : 1 mois) offrant des récompenses exclusives (skins, thèmes, monnaie) aux joueurs qui accomplissent des tâches ou jouent régulièrement. Chaque passe est centré sur une thématique spécifique (Jungle, Tigre, Ours, Lapin, Lion, Chat, Dinosaure, Panthère, Jaguar, Crocodile 3D, etc.).

2. Fonctions

• Engagement : Incite à jouer quotidiennement pour progresser dans le passe.
• Monétisation : Peut comporter une voie gratuite et une voie payante (Premium) offrant plus de récompenses.
• Distribution de Contenu : Moyen principal d'obtenir les nouveaux thèmes et skins.

3. Icone

• Représentation : Ticket doré ou Calendrier avec une étoile.
• Couleur dominante : Or et Rouge.

4. Interactions

• Consultation : Bouton dédié sur l'écran principal affichant la barre de progression du passe.
• Réclamation : Clic sur les paliers débloqués pour récupérer les récompenses.
• Achat : Bouton pour acheter la version Premium du passe.

5. Annexes Techniques

Données (JSON)

{
  "pass_id": "pass_season_05",
  "theme_name": "Tigre",
  "duration_days": 30,
  "start_date": "2026-05-01",
  "end_date": "2026-05-31",
  "levels": [
    {
      "level": 1,
      "xp_required": 100,
      "reward_free": "coins_100",
      "reward_premium": "skin_tiger_hat"
    },
    {
      "level": 30,
      "xp_required": 3000,
      "reward_free": "skin_tiger_statue",
      "reward_premium": "theme_tiger_full"
    }
  ]
}

Règles Métier

• Les récompenses cosmétiques (thèmes) sont temporaires pour les joueurs non-VIP (liées à la durée du passe).
• Les joueurs VIP débloquent la conservation permanente des thèmes acquis via le passe.
• La progression se fait via l'XP gagnée en jeu ou des quêtes spécifiques au passe.

6. Annexes UX/UI

• Barre de Progression : Visuel clair de l'avancement (jauge remplie).
• Paliers : Icônes des récompenses cliquables pour détails.
• Mise en avant : Pop-up à la connexion annonçant le nouveau passe ou les récompenses non réclamées.

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	Passe de progression temporaire (ex. 30 jours) avec paliers + récompenses.
Thématique	Une saison = une thématique (Jungle/Tigre/Ours/Lapin/Lion/Chat/Dinosaure/Panthère/Jaguar/Crocodile 3D…).
Accès	Voie gratuite + voie premium (achat).
Conservation	Non-VIP : accès thèmes/packs du passe pendant la durée du passe. VIP : accès conservé tant que VIP actif (cf. vip.md).

Fonctions (tableau détaillé)

Fonction	Déclencheur	Entrées	Sorties	Règles	Observabilité
Accumuler XP passe	actions/quetes	événements jeu	pass_xp +	Sources XP listées, caps journaliers	Event PASS_XP_GAINED
Déverrouiller palier	XP atteint	xp total	niveau débloqué	Déverrouillage monotone	Event PASS_LEVEL_UNLOCKED
Réclamer récompense	clic palier	type voie	item ajouté	Doit être idempotent	Event PASS_REWARD_CLAIMED
Acheter premium	achat	paiement	premium actif	Upgrade voie ; rétroactif sur paliers	Event PASS_PREMIUM_PURCHASED
Fin de saison	date fin	now	close	Non-VIP : gating thèmes ; VIP : gating par VIP	Event PASS_ENDED

Icone de base

Élément	Spécification
Représentation	Ticket / calendrier étoilé
Couleur dominante	Or / rouge
Variantes	icon_pass_ticket.png, icon_pass_calendar.png
États	Badge “nouveau”, “récompenses à réclamer”, “premium”

Interactions (tableau détaillé)

Interaction	Type	Préconditions	Étapes UI	Résultat	Erreurs / Messages
Ouvrir passe	Consultation	passe actif	bouton HUD	écran passe	-
Voir palier	Consultation	-	scroll paliers	détail reward	-
Réclamer	Action	palier débloqué	clic reward	item ajouté	REWARD_LOCKED, ALREADY_CLAIMED
Acheter premium	Action	non premium	clic CTA	premium actif	PAYMENT_FAILED
Aller quêtes passe	Navigation	-	bouton “Quêtes”	liste quêtes	-

Annexes Techniques

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

Donnée / État	Type	Exemple	Source	Contraintes
pass_id	string	pass_season_05	DB	unique
theme_name	string	Tigre	config	-
duration_days	int	30	config	-
start_date/end_date	date	-	config	UTC
levels[]	array	-	config	1..N
levels.level	int	1	config	monotone
levels.xp_required	int	100	config	monotone
reward_free/reward_premium	string	skin_tiger_hat	config	item ids
player_state.pass_xp	int	0..∞	DB	cumul
player_state.premium_active	bool	false	DB	-
player_state.claimed_rewards	set	-	DB	idempotence

Caractéristiques Initiales (tableau détaillé)

Caractéristique	Valeur initiale	Unité	Notes
XP passe	0	xp	départ
Premium actif	false	bool	départ
Niveaux	30	levels	exemple
Cap XP/jour	1000	xp	anti farm

Scores Initiaux (tableau détaillé)

Score	Valeur initiale	Plage	Impact
Niveaux débloqués	0	0..N	progression
Récompenses non réclamées	0	0..∞	badge UI

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

Phase	Déclencheur	Entrées	Sorties	Invariants
Apparition	début saison	config	passe actif	dates
Progression	actions	xp	unlocks	monotone
Fin	date	now	passe clos	gating

Conditions d'Apparition (tableau détaillé)

Condition	Seuil	Opérateur	Résultat
Date >= start	true	est	passe visible

Conditions de Disparition (tableau détaillé)

Condition	Seuil	Opérateur	Résultat
Date > end	true	est	passe inactif

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

Élément	Hérité	Règle
XP gagné	Oui	persiste pour historique
Récompenses	Oui	items acquis restent possédés ; accès thèmes dépend VIP

3. Impacts Environnementaux

Impact Température (tableau détaillé)

Condition	Effet	Notes
Canicule	quêtes spécifiques	“vendre glaces”

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

Biome	Effet	Notes
Jungle	quêtes liées	thème

Impact Saisons (tableau détaillé)

Saison	Effet	Notes
Saison du passe	contenu	paliers

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

Période	Effet	Notes
Reset quotidien	quêtes	distribution

4. Impacts Biologiques et Sociaux

Impact Reproduction (tableau détaillé)

Facteur	Effet	Condition
Quêtes “naissance”	XP passe +	si complétée

Impact Mort (tableau détaillé)

Cas	Effet	Condition
Mort bébé	quête/objectif	XP passe + si “résoudre incident”

Impact Nourriture (tableau détaillé)

Ressource	Effet	Condition
Quêtes nourriture	XP +	acheter/consommer

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

Action/État	Effet	Condition
Thèmes saisonniers	attractivité +	si actif

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

Action/État	Effet animaux	Condition
Skins animaux	visuel	pas de stats

Impact Valeur (tableau détaillé)

Facteur	Variation	Condition
Items rares	valeur cosmétique +	collection

5. Impacts Logistiques et Économiques

Vitesse (Camion) (tableau détaillé)

Paramètre	Effet	Condition
Quête livraison	XP +	délai

Vitesse (Nurserie) (tableau détaillé)

Paramètre	Effet	Condition
Quête naissance	XP +	baby

Vitesse (Accueil) (tableau détaillé)

Paramètre	Effet	Condition
Quête réception	XP +	nouveau animal

Vitesse (Recherche) (tableau détaillé)

Paramètre	Effet	Condition
Quête RP	XP +	collecter

Vitesse (Labo) (tableau détaillé)

Paramètre	Effet	Condition
Quête labo monde	XP +	achat rare

Vitesse (Visite) (tableau détaillé)

Paramètre	Effet	Condition
Quête visiteurs	XP +	satisfaction

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

Poste	Coût	Unité	Condition
Quête revenus	-	-	objectif

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

Poste	Coût	Unité	Condition
Achat premium	variable	monnaie	passe

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

Poste	Coût	Unité	Condition
-	0	-	-

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

Poste	Coût	Unité	Condition
Quête staff	-	-	embauche

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
Upgrade nurserie	variable	coins	objectif

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

Poste	Coût	Unité	Condition
Achat nourriture	variable	coins	objectif

Dépenses (Acceuil des animaux) (tableau détaillé)

Poste	Coût	Unité	Condition
Achat animaux	variable	coins	objectif

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

Poste	Coût	Unité	Condition
Livraison	variable	coins	objectif

Trajet Visiteurs

Trajet Visiteurs vers/depuis la ville (tableau détaillé)

Source	Destination	Déclencheur	Effet
Ville	Zoo	réputation	quêtes flux

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

Source	Destination	Déclencheur	Effet
Visiteur	Enclos	curiosité	objectifs

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

Source	Destination	Déclencheur	Effet
Visiteur	Boutique	soif/envie	objectifs

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

Source	Destination	Déclencheur	Effet
Visiteur	Sortie	fin journée	objectifs

6. Événements

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

Event	Déclencheur	Payload	Effet
PASS_STARTED	start	pass_id	visible
PASS_ENDED	end	pass_id	close

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

Event	Déclencheur	Effet
PASS_POPUP_LOGIN	login	CTA

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

Event	Déclencheur	Effet
PASS_XP_GAINED	action zoo	xp +

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

Event	Déclencheur	Effet
PASS_VISITOR_GOAL	satisfaction	xp +

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

Event	Déclencheur	Effet
PASS_PHOTO_BONUS	photo	xp +

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

Event	Déclencheur	Effet
PASS_PREMIUM_PURCHASED	achat	premium

7. Progression

Tableau des Upgrades (tableau détaillé)

Niveau passe	XP requis	Free reward	Premium reward	Notes
1	100	coins_100	skin_tiger_hat	exemple
30	3000	skin_tiger_statue	theme_tiger_full	exemple

8. Logique et Interfaces

Pseudo-code Impacts (tableau détaillé)

Fonction	Entrées	Sorties	Notes
addPassXp	action xp	pass_xp	cap/jour
unlockLevels	pass_xp	unlocked	monotone
claimReward	level, track	item	idempotent

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

ID	Niveau	Message	Condition
REWARD_LOCKED	Warning	"Palier verrouillé."	xp insuffisant
ALREADY_CLAIMED	Info	"Déjà réclamé."	idempotence

Annexes UX/UI

1. Expérience Utilisateur (UX)

Description UX (tableau détaillé)

Parcours	But	Friction	Réduction clics
Suivre progression	motivation	scroll long	raccourci “prochain reward”
Réclamer	récupérer items	oubli	badge non réclamés

Description UI (tableau détaillé)

Composant	Contenu	États
Écran passe	rail paliers	free/premium
CTA premium	prix	purchased

Emplacement (tableau détaillé)

Zone UI	Position	Notes
HUD	bouton passe	badge
Modal	plein écran	scroll

Intégration (tableau détaillé)

Intégration	Contrat	Notes
Inventaire skins	ajout items	idempotent
VIP	conservation	gating

Navigation (tableau détaillé)

Action	Chemin	Résultat
Ouvrir passe	HUD	écran
Aller boutique	CTA	achat

Événements (tableau détaillé)

Event UI	Déclencheur	Effet
OPEN_PASS	clic	écran
CLICK_CLAIM_REWARD	clic	claim

Assets Skinables

Musiques (tableau détaillé)

Asset	Usage	Durée	Notes
pass_screen_loop.mp3	écran	loop	thème saison

Sons (tableau détaillé)

Asset	Usage	Volume
reward_claim.mp3	claim	moyen
level_unlock.mp3	unlock	moyen

Graphiques (tableau détaillé)

Asset	Usage	Contraintes
pass_track_free.png	UI	-
pass_track_premium.png	UI	-

Images (tableau détaillé)

Asset	Usage
pass_badge.png	HUD
pass_reward_icons.png	paliers

Vidéos (tableau détaillé)

Asset	Usage	Durée
pass_intro.webm	popup	2.0s

Animations (tableau détaillé)

Animation	Déclencheur	Notes
jauge fill	xp gain	smooth
sparkles	claim	burst

Couleurs (tableau détaillé)

Token	Valeur	Usage
pass_gold	#D4AF37	premium
pass_red	#C0392B	accent

Textes (tableau détaillé)

Clé	FR	EN
pass.claim	Réclamer	Claim
pass.buy_premium	Acheter Premium	Buy Premium

Formes (tableau détaillé)

Élément	Forme	Notes
Cartes reward	rectangles arrondis	-
Jauge	barre	-