builazoo/docs/specs/menu_achats.md

Menu Achats

1. Définition

Interface centralisée dédiée aux transactions utilisant la monnaie premium (pièces du zoo) ou standard, regroupant les employés, la nourriture spéciale, les skins et les améliorations. C'est le "hub" économique du joueur.

2. Fonctions

• Catalogue : Présente tous les articles achetables de manière organisée.
• Transaction : Gère la validation des achats et le débit des ressources.
• Offres : Peut afficher des promotions ou des packs (bundles).

3. Icone

• Représentation : Caisse enregistreuse ou Panier d'achat.
• Couleur dominante : Vert (billet) et Or (pièce).

4. Interactions

• Accès : Bouton principal dans la barre d'interface (HUD).
• Navigation : Onglets par catégorie (Animaux, Enclos, Employés, Déco, Spécial).
• Achat Rapide : Possibilité d'acheter en quantité (x1, x10).

5. Annexes Techniques

Données (JSON)

{
  "shop_categories": [
    {
      "id": "employees",
      "label": "Personnel",
      "items": ["healer_01", "feeder_01", "security_01"]
    },
    {
      "id": "consumables",
      "label": "Nourriture Spéciale",
      "items": ["food_boost_lion", "food_boost_monkey"]
    }
  ],
  "currency_balance": {
    "coins": 1500,
    "gems": 50
  },
  "iso_x": "integer",
  "iso_y": "integer",
  "z_index": "integer"
}

Règles Métier

• Déblocage : Certains articles ne sont visibles qu'à partir d'un certain niveau de zoo.
• Stock : Certains items peuvent être en quantité limitée (ex: offres du jour).

6. Annexes UX/UI

• Design : Fenêtre modale propre, avec de grandes icônes et des prix clairs.
• Feedback Achat : Animation de pièces qui volent vers le compteur total lors de la dépense.
• Confirmation : Pop-up de confirmation pour les achats coûteux (> 1000 pièces).

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	Menu “Achats” : hub UI des transactions (employés, consommables, cosmétiques, upgrades).
Rôle	Réduire les clics d’achat via catégories/onglets, et garantir des transactions atomiques (débit + attribution).
Portée	UI globale (HUD) ; impacte inventaires, bâtiments, personnel, monnaies.
Contrainte	Aucun tracking/analytics ; pas de cache/mémorisation côté app : catalogue et soldes sont lus comme état courant à l’ouverture.

Fonctions (tableau détaillé)

Fonction	Déclencheur	Entrées	Sorties	Règles	Observabilité
Ouvrir menu achats	clic HUD	player_id	modal hub	focus dernière catégorie (état UI local)	Event OPEN_SHOP_HUB
Charger catalogue	ouverture	shop_version	catégories + items	filtrer par niveau, conditions	Event SHOP_CATALOG_LOADED
Filtrer catégorie	clic onglet	category_id	liste items	tri stable, recherche	Event SHOP_CATEGORY_SELECTED
Prévisualiser item	clic item	item_id	panneau détail	affiche prix, effets, prérequis	Event SHOP_ITEM_PREVIEWED
Acheter item	clic “Acheter”	item_id, quantité	débit + attribution	transaction atomique ; pas d’achat si fonds insuffisants	Event SHOP_PURCHASED
Confirmer achat coûteux	seuil	price	modal confirm	requis si > 1000 coins	Event SHOP_CONFIRM_SHOWN
Achat en quantité	clic x1/x10	quantité	panier/achat	clamp par stock/solde	Event SHOP_QUANTITY_CHANGED

Icone de base

Élément	Spécification
Représentation	Caisse / panier
Couleur dominante	Vert + or
Variantes	icon_shop_cash.png, icon_shop_cart.png
États	normal, hover, disabled (fonds)

Interactions (tableau détaillé)

Interaction	Type	Préconditions	Étapes UI	Résultat	Erreurs / Messages
Accès hub	Navigation	-	clic HUD	ouvre hub	-
Changer onglet	Navigation	-	clic onglet	liste update	-
Achat simple	Action	fonds ok	clic acheter	item attribué	NOT_ENOUGH_COINS
Achat coûteux	Action	fonds ok	acheter → confirm	item attribué	CANCELLED
Achat x10	Action	fonds/stock ok	select x10 → acheter	10 items	LIMIT_REACHED

Personnage contextuel (événements & interaction)

Deux personnages contextuels peuvent être affichés selon la section :

• Vendeur “achat en pièces” : voir vendeur_pieces.md (section “Pièces”, conversion/pack).
• Vendeur (boutique) : voir vendeur.md (prévisualisation/achat d’items boutique/cosmétiques si le hub les expose).

Déclencheurs (exemples)

Section	Event / Action	Effet UI personnage
Hub	OPEN_SHOP_HUB	personnage visible dans l’en-tête du hub (thématisé)
Hub	SHOP_ITEM_PREVIEWED	bulle “Détails item” + CTA “Acheter”
Hub	SHOP_CONFIRM_SHOWN	confirmation contextualisée (prix, quantité)
Pièces	ouverture section	vendeur pièces présente les packs + limites
Pièces	achat pack	reçu + solde mis à jour ; erreur explicite si paiement impossible

Skins & thèmes

Le rendu suit theme.md et les skins de la UI/boutique si disponibles via inventaire_skins.md.

Annexes Techniques

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

Donnée / État	Type	Exemple	Source	Contraintes
shop_categories[].id	string	employees	config/DB	stable
shop_categories[].label_key	string	shop.cat.employees	i18n	FR/EN
shop_categories[].items[]	string[]	["healer_01"]	config/DB	ids
items[item_id].price.coins	int	250	config	>=0
items[item_id].price.gems	int	0	config	>=0
items[item_id].requires.zoo_level	int	3	config	gating
items[item_id].stock_daily	int | null	10	config	null = illimité
currency_balance.coins	int	1500	DB	source de vérité
currency_balance.gems	int	50	DB	source de vérité
ui.last_category_id	string	employees	client	état UI

Caractéristiques Initiales (tableau détaillé)

Caractéristique	Valeur initiale	Unité	Notes
Seuil confirmation	1000	coins	règle existante
Quantités rapides	1,10	unités	boutons
Catégorie par défaut	employees	id	configurable

Scores Initiaux (tableau détaillé)

Score	Valeur initiale	Plage	Impact
Achats du jour	0	0..∞	historique local, pas d’analytics
Dépenses du jour	0	0..∞	transparence UI

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

Phase	Déclencheur	Entrées	Sorties	Invariants
Apparition	jeu lancé	config	hub dispo	bouton HUD
Navigation	clic onglets	category_id	liste	tri stable
Transaction	achat	item+prix	débit+attribution	atomicité

Conditions d'Apparition (tableau détaillé)

Condition	Seuil	Opérateur	Résultat
Compte créé	true	est	hub visible

Conditions de Disparition (tableau détaillé)

Condition	Seuil	Opérateur	Résultat
Mode tutorial verrou	true	est	hub masqué temporairement

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

Élément	Hérité	Règle
Soldes	Oui	persistants DB
Achats	Oui	items attribués

3. Impacts Environnementaux

Impact Température (tableau détaillé)

Condition	Effet shop	Notes
-	aucun	UI

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

Biome	Effet shop	Notes
-	aucun	UI

Impact Saisons (tableau détaillé)

Saison	Effet shop	Notes
Saison active	items saisonniers visibles	gating explicite

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

Période	Effet shop	Notes
-	aucun	-

4. Impacts Biologiques et Sociaux

Impact Reproduction (tableau détaillé)

Facteur	Effet sur taux	Condition
-	aucun	shop n’impacte pas directement

Impact Mort (tableau détaillé)

Cas	Effet	Condition
-	aucun	-

Impact Nourriture (tableau détaillé)

Ressource	Effet	Condition
Achat nourriture spéciale	stock +	transaction ok

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

Action/État	Gain	Rayon	Notes
-	0	0	UI

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

Action/État	Effet animaux	Condition
-	-	-

Impact Valeur (tableau détaillé)

Facteur	Variation	Condition
Skins/thèmes achetés	+	valeur perçue

5. Impacts Logistiques et Économiques

Vitesse (Camion) (tableau détaillé)

Paramètre	Effet	Condition
-	-	-

Vitesse (Nurserie) (tableau détaillé)

Paramètre	Effet	Condition
Achat upgrade nurserie	level ↑	transaction ok

Vitesse (Accueil) (tableau détaillé)

Paramètre	Effet	Condition
Achat accueil	capacité ↑	transaction ok

Vitesse (Recherche) (tableau détaillé)

Paramètre	Effet	Condition
Achat recherche	vitesse ↑	transaction ok

Vitesse (Labo) (tableau détaillé)

Paramètre	Effet	Condition
Achat labo	capacité ↑	transaction ok

Vitesse (Visite) (tableau détaillé)

Paramètre	Effet	Condition
Achat décor	attractivité ↑	transaction ok

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

Poste	Coût	Unité	Condition
-	0	-	-

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

Poste	Coût	Unité	Condition
-	0	-	-

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

Poste	Coût	Unité	Condition
-	0	-	-

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

Poste	Coût	Unité	Condition
Recrutement	variable	coins	item employé

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	variable	coins	achat

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

Poste	Coût	Unité	Condition
Consommables	variable	coins	achat

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

Poste	Coût	Unité	Condition
Achat capacité	variable	coins	achat

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

Poste	Coût	Unité	Condition
Achat upgrade	variable	coins	achat

Trajet Visiteurs

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

Source	Destination	Déclencheur	Effet
-	-	-	-

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
OPEN_SHOP_HUB	clic	-	ouvre
SHOP_CATALOG_LOADED	open	version	liste
SHOP_PURCHASED	achat	item_id, qty	attribue

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

Event	Déclencheur	Effet
-	-	-

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

Event	Déclencheur	Effet
-	-	-

É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
SHOP_CATEGORY_SELECTED	onglet	UI

7. Progression

Tableau des Upgrades (tableau détaillé)

Niveau	Coût	Effet	Débloque
Hub 1	0	catégories base	-

8. Logique et Interfaces

Pseudo-code Impacts (tableau détaillé)

Fonction	Entrées	Sorties	Notes
canPurchase	balance, price	bool	fonds + gating
purchaseItem	item_id, qty	receipt	atomique

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

ID	Niveau	Message	Condition
NOT_ENOUGH_COINS	Warning	"Fonds insuffisants."	achat
SHOP_PURCHASED	Info	"Achat effectué."	succès

Annexes UX/UI

1. Expérience Utilisateur (UX)

Description UX (tableau détaillé)

Parcours	But	Friction	Réduction clics
Acheter employé	renforcer zoo	navigation	hub + onglet + CTA
Acheter consommable	soigner/booster	quantité	x1/x10 direct

Description UI (tableau détaillé)

Composant	Contenu	États
Onglets	catégories	actif/inactif
Carte item	icône, prix, CTA	disabled si fonds
Modal confirm	item + prix	ok/cancel

Emplacement (tableau détaillé)

Zone UI	Position	Notes
HUD	bouton	accès direct
Modal	centre	hub

Intégration (tableau détaillé)

Intégration	Contrat	Notes
boutique.md	boutique interne	cohérence
inventaire_skins.md	cosmétiques	attribution

Navigation (tableau détaillé)

Action	Chemin	Résultat
Ouvrir	HUD → menu	hub
Acheter	item → CTA	attribution

Événements (tableau détaillé)

Event UI	Déclencheur	Effet
OPEN_SHOP_HUB	clic	modal
CLICK_BUY_ITEM	CTA	achat

Assets Skinables

Musiques (tableau détaillé)

Asset	Usage	Durée	Notes
shop_hub_loop.mp3	menu achats	loop	neutre

Sons (tableau détaillé)

Asset	Usage	Volume
ui_purchase_success.mp3	succès	moyen
ui_purchase_fail.mp3	échec	moyen

Graphiques (tableau détaillé)

Asset	Usage	Contraintes
shop_item_card.png	carte item	scalable
shop_coin_fly_fx.png	feedback achat	overlay

Images (tableau détaillé)

Asset	Usage
shop_banner.png	header

Vidéos (tableau détaillé)

Asset	Usage	Durée
coin_fly.webm	feedback	0.8s

Animations (tableau détaillé)

Animation	Déclencheur	Notes
pièces qui volent	achat	0.8s

Couleurs (tableau détaillé)

Token	Valeur	Usage
shop_green	#2E7D32	CTA
shop_gold	#D4AF37	prix

Textes (tableau détaillé)

Clé	FR	EN
shop.title	Achats	Shop
shop.buy	Acheter	Buy

Formes (tableau détaillé)

Élément	Forme	Notes
Cartes	rectangles arrondis	lisible