builazoo/docs/plan-implementation-rappel-grandes-regles.md

Plan d'implémentation – Rappel des grandes règles (cahier des charges 174-324)

Plan pour implémenter l’intégralité du bloc « Rappel des grandes règles » sans exception. Les phases sont ordonnées par dépendances ; chaque phase livre un ensemble cohérent et testable.

---

0. Modèle de données et configuration

Objectif : Fondations pour tout le reste (cases avec couleur + température, bâtiments, bébés vs animaux, ventes).

Livrables :

• Cases : chaque case a une couleur (milieu : eau douce, eau salée, montagne, prairie, forêt, etc.) et une température (nombre ou plage). Transitions douces = formules d’interpolation entre cases voisines (calcul côté moteur).
• Animaux multi-cases : définition des types d’animaux qui occupent N×M cases (shape), et stockage dans grid.cells (référence à une entité « animal » multi-case ou marquage des cases).
• Types de bâtiments (remplacement / extension des kinds actuels) :
  • research (Centre de recherche), 7 niveaux
  • billeterie, 7 niveaux
  • boutique (déjà présent en souvenirShop → renommer/aligner), 7 niveaux
  • nursery, 7 niveaux (au lieu de 5)
  • food (Nourriture), 7 niveaux
  • reception (Accueil nouveaux animaux), 7 niveaux
  • truck (camion : actuellement métadonnée d’état, pas une case – à trancher : case dédiée ou zone comme aujourd’hui)
  • biomeChangeColor (changement de milieu couleur), 7 niveaux
  • biomeChangeTemp (changement de milieu température), 7 niveaux
• Entités déplaçables : baby (bébé, en nurserie ou en vente), animal (adulte, sur carte ou en accueil ou en vente). Plus d’œufs comme objet principal : les zoos exposent des bébés et des animaux à l’achat/vente.
• Config : GameConfig étendu (niveaux max à 7 pour les bâtiments listés, coûts, capacités : recherche 10 zoos/unité, billeterie 20 visiteurs/unité, boutique 5 visiteurs/unité, nurserie 1 bébé/unité, nourriture 5 animaux/unité, accueil 1 animal/unité, camion 1/unité).

Fichiers impactés : web/js/types.js, web/js/config.js, web/js/state.js, server/schema.sql (si extension game_state), web/js/loot-tables.js (animaux avec cellsWide, cellsHigh, température idéale, score reproduction/survie par milieu).

Dépendances : aucune.

---

1. Cartes : couleurs et températures des cases

Objectif : Les cases ont une couleur (milieu) et une température ; les transitions sont douces entre cases.

Livrables :

• Couleurs : élargir les biomes au-delà de prairie/océan/montagne (eau douce, eau salée, montagne, prairie, forêt, etc.) ; chaque case a un biome (couleur/milieu) et un temperature (valeur ou min/max).
• Transitions douces : calcul de la couleur et de la température affichées par interpolation avec les cases voisines (ou gradient par position). Export d’une fonction du type getDisplayColor(x, y, grid), getDisplayTemperature(x, y, grid).
• Rendu : CSS/Canvas ou styles dynamiques pour fond de case selon couleur et température (dégradés entre cases).
• Grille : les cases forment le cadrillage des cartes (zoo et monde) ; pas de changement de structure, seulement sémantique couleur/température.

Fichiers impactés : web/js/biome-rules.js (ou nouveau cell-environment.js), web/js/grid-utils.js, web/css/main.css, web/js/ui.js (rendu grille).

Dépendances : Phase 0.

---

2. Animaux multi-cases

Objectif : Certains animaux prennent plusieurs cases.

Livrables :

• Définition : dans les données animaux (loot-tables ou équivalent), champs cellsWide, cellsHigh (ex. 1×1, 2×2). Placement valide si toutes les cases cibles sont vides et dans les limites.
• Stockage : soit une entité « animal » avec originKey (case coin) + animalId + width, height, soit marquage de chaque case avec référence à la même entité. Suppression/mouvement : toute la surface est libérée ou déplacée.
• Règles : cohérence animal/milieu et température (phase 1) appliquée sur la zone couverte (ex. toutes les cases dans la plage de température idéale ou au moins la case d’origine).
• UI : affichage d’un sprite ou emprise sur plusieurs cases ; glisser-déposer d’un animal multi-case déplace tout le bloc.

Fichiers impactés : web/js/loot-tables.js, web/js/placement.js, web/js/grid-utils.js, web/js/ui.js, web/js/state.js (structure cells).

Dépendances : Phase 0, 1.

---

3. Bâtiments zoo (types et niveaux)

Objectif : Implémenter tous les types de cases « achetables » avec 7 niveaux et leurs effets.

Livrables :

• Centre de recherche (research) : 7 niveaux. Produit des unités de recherche par tick (formule par niveau). Stock dans le game_state (ex. researchPoints). 1 unité = 10 zoos max couverts (par proximité sur la carte du monde) ; ces zoos débloquent des niveaux d’animaux/bébés. Coût d’upgrade par palier.
• Billeterie : 7 niveaux. Cap visiteurs en simultané = 20 × niveau (ou 20 par unité comme dans le rappel). Entrée des visiteurs uniquement via la billeterie (voir phase 8). Coût par palier.
• Boutique : passer à 7 niveaux. 1 unité = 5 visiteurs simultanés max (effet sur revenus quand un visiteur « passe » par une boutique). Coût par palier.
• Nurserie : 7 niveaux. 1 unité = 1 bébé max en croissance. Effet « plus rapide » et « meilleurs reproducteurs » (à lier à la reproduction, phase 7). Coût par palier.
• Nourriture : 7 niveaux. 1 unité = 5 animaux max nourris (voir phase 4). Coût par palier.
• Accueil nouveaux animaux : 7 niveaux. 1 unité = 1 animal en acclimatation. Durée d’acclimatation selon niveau ; à la fin, état « animal prêt » déplaçable sur une case ou sur le camion. Coût par palier.
• Camion : 7 niveaux. Représentation : soit une case dédiée « camion », soit une zone comme aujourd’hui ; 1 unité = 1 camion. Effets : plus rapide (durée trajet), dégrade moins le score de reproduction avec la durée du transport (à lier aux ventes et au score de reproduction).
• Changement de milieu (couleur) : 7 niveaux, payant. Permet de modifier la couleur/milieu d’une case (ou d’une zone selon niveau). Effets : plage de température plus précise, améliore reproduction, diminue besoin nourriture, allonge temps avant mort.
• Changement de milieu (température) : 7 niveaux, payant. Même idée pour la température des cases.

Grille au lancement (à appliquer en phase 11) : 1 Agrandissement zoo, 1 Recherche, 1 Billeterie, 1 Nurserie, 1 Accueil, 1 Nourriture, 1 Camion, 24 cases (3 couleurs). Pas de « changement de milieu » au lancement.

Fichiers impactés : web/js/config.js, web/js/state.js, web/js/economy.js, web/js/placement.js, web/js/zoo.js, web/js/ui.js, server/ si game_state étendu.

Dépendances : Phase 0.

---

4. Bébés et flux nurserie / accueil (remplacement œufs)

Objectif : Ce ne sont plus des œufs qui apparaissent dans les zoos mais des bébés ; flux nurserie → bébé mature, achat/accueil → animal prêt.

Livrables :

• Suppression du modèle « œuf » comme objet acheté sur la carte du monde. Les zoos (et le labo) proposent des bébés ou des animaux adultes à l’achat.
• Nurserie : un bébé est « en croissance » dans une case nurserie (1 bébé par unité de capacité). À la fin de la durée : état bébé mature. Déplacement possible : vers une case vide du zoo (devient animal) ou vers le camion (mise en vente, voir phase 9).
• Accueil nouveaux animaux : un animal acheté (ou reçu) est d’abord en accueil (1 animal par unité). À la fin de l’acclimatation : animal prêt. Déplacement possible : vers une case vide du zoo ou vers le camion (mise en vente).
• Carte du zoo : on peut acheter (occupe la case) : recherche, billeterie, boutique, nurserie, nourriture, accueil, camion, changement de milieu (couleur), changement de milieu (température). On peut déplacer dessus (occupe la case) : bébé mature, animal prêt.
• État : pendingBabies / receptionAnimals avec readyAt, babyId / animalId, lien vers case nurserie/accueil. Quand now >= readyAt, l’entité est déplaçable (bébé mature / animal prêt).

Fichiers impactés : web/js/state.js, web/js/zoo.js, web/js/placement.js, web/js/hatching.js (remplacer par croissance bébé + acclimatation), web/js/conveyor.js (offres = bébés/animaux, pas œufs), web/js/ui.js, web/js/world-map.js, API offres.

Dépendances : Phase 0, 3.

---

5. Nourriture, consommation et morts

Objectif : Chaque animal a une consommation / unité de temps ; sinon il meurt. Toutes les causes de mort listées.

Livrables :

• Nourriture : par tick, calcul de la consommation totale des animaux du zoo. Les bâtiments « nourriture » ont une capacité (5 animaux × niveau ou 5 par unité). Répartition : nourrir jusqu’à la capacité ; les animaux non nourris accumulent un déficit (ou un timer « sans nourriture »).
• Mort si pas nourri : au-delà d’un seuil (temps ou déficit), l’animal meurt (retiré de la grille, enregistré pour pénalités attractivité / naissances).
• Autres causes de mort (toutes à implémenter) :
  • Seul : à définir (ex. animal seul sur l’île sans voisin après un délai).
  • Pas visité : déjà en place (MaxSecondsWithoutVisit).
  • Manque de nourriture : ci-dessus.
  • Tué par un autre animal d’un autre zoo : règle métier (ex. événement rare ou mécanique croisée entre zoos).
  • Niveau de recherche trop inférieur : si niveau du centre de recherche du zoo < seuil requis pour le type d’animal, après un délai l’animal meurt.
  • Bébé non vendu dans les délais : si un bébé en vente n’est pas vendu avant une date limite, il meurt (voir phase 9).
  • Bébé de nurserie prêt non placé dans les délais : si bébé mature n’est pas déplacé (case ou camion) avant un délai, il meurt.
  • Animal d’accueil prêt non placé sur la carte après un délai : idem.
  • Animal non placé sur la carte dans les délais (vente échouée) : si une vente est annulée ou expire sans que l’animal soit récupéré, mort.
  • Température trop en écart : si la température de la case (ou de la zone) n’est pas dans la plage acceptable pour l’animal, après un délai mort.
  • Milieu (couleur) trop en écart : idem pour le biome.
• Historique des morts : stockage (compteur ou liste récente) pour calcul d’attractivité et de naissances (phases 8 et 7).

Fichiers impactés : web/js/config.js, web/js/state.js, nouveau web/js/food.js (ou dans income.js), web/js/game-loop.js, web/js/animal-visits.js (étendre pour morts), web/js/loot-tables.js (température idéale, plages par animal).

Dépendances : Phase 0, 1, 3, 4.

---

6. Reproduction

Objectif : Après un délai, en proximité d’un autre animal de même type mais issu d’un zoo différent, naissance d’un bébé (nurserie ou vente). Score de reproduction du zoo et adéquation température/milieu influencent.

Livrables :

• Proximité : deux animaux de même type (même animalId ou même « type ») sur des cases adjacentes (ou à distance N). Un des deux doit avoir une origine « autre zoo » (vendue achetée) pour permettre la reproduction.
• Délai : timer par paire ou par animal ; à l’échéance, génération d’un bébé. Le bébé va en nurserie si une place est libre, sinon directement en vente (case de vente sur la carte du monde).
• Score de reproduction du zoo (voir phase 7) : utilisé pour accélérer l’arrivée du bébé (réduction du délai).
• Température et milieu : « très bonne adéquation » avec la température/milieu de l’animal réduit le délai ou augmente la chance de reproduction.
• Score de reproduction par milieux (couleurs) et score de survie par milieux (couleurs) : définis dans les données animaux ; utilisés dans les formules de reproduction et de mort.
• Température idéale : par type d’animal (déjà prévu en phase 5 pour les morts) ; utilisée aussi pour la reproduction.

Fichiers impactés : web/js/loot-tables.js, nouveau web/js/reproduction.js, web/js/state.js, web/js/game-loop.js.

Dépendances : Phase 0, 1, 4, 5.

---

7. Score de reproduction du zoo

Objectif : Nombre de naissances, taux d’alimentation, et score « vendu » attaché aux animaux.

Livrables :

• Nombre de naissances : compteur dans le game_state (incrémenté à chaque bébé né en reproduction).
• Taux d’alimentation : ratio (animaux nourris / animaux total) sur une fenêtre ou instantané ; stocké ou dérivé pour l’affichage et les formules.
• Score de reproduction (valeur agrégée du zoo) : formule combinant naissances, taux d’alimentation, et éventuellement autres facteurs. Exposé pour l’UI (carte du monde : case « score de reproduction » sous le nom du zoo).
• Animal vendu : quand un animal quitte le zoo (vente), il garde en mémoire le score de reproduction du zoo au moment de la vente (pour accélérer l’arrivée d’un bébé dans le zoo acheteur, phase 6).

Fichiers impactés : web/js/state.js, web/js/income.js ou web/js/food.js, web/js/reproduction.js, web/js/trade.js, web/js/world-map.js (affichage score).

Dépendances : Phase 5, 6.

---

8. Attractivité et visiteurs (billeterie, 1 journée, boutiques)

Objectif : Visiteurs entrent par la billeterie, restent max 1 journée, plus longtemps avec boutiques et nombre d’animaux différents. Attractivité du zoo avec toutes les composantes et pénalités.

Livrables :

• Billeterie : seule entrée des visiteurs dans le zoo. Capacité simultanée = 20 × niveau billeterie (ou 20 par unité). Le nombre de visiteurs présents est plafonné par cette capacité.
• Durée max 1 journée : chaque visiteur a une « arrivée » ; il repart au plus tard après 1 journée (temps de jeu). Il repart par la billeterie.
• Temps passé : les visiteurs restent plus longtemps dans la journée s’il y a des boutiques et plus d’animaux différents (formule à définir).
• Déplacement : les visiteurs se déplacent en étant attirés (déjà partiellement en place ; conserver et adapter si besoin).
• Attractivité du zoo (formule globale) :
  • proportionnelle à la valeur cumulée des animaux du zoo
  • proportionnelle au nombre d’animaux différents
  • proportionnelle à la rareté (niveau) des animaux
  • proportionnelle au taux de remplissage en animaux
  • Pénalités : les morts pénalisent l’attractivité auprès des visiteurs à venir (depuis les villes) ; les morts pénalisent l’apparition de naissances dans le zoo.
  • Bonus : les naissances augmentent l’attractivité auprès des visiteurs à venir ; les naissances augmentent l’apparition d’autres naissances dans le zoo.
• Villes : nombre de visiteurs maximum vers les zoos (voir phase 10). L’attractivité du zoo détermine combien de ces visiteurs sont « alloués » au zoo.
• Affichage : sur la carte du monde, sous le nom du zoo : une case « score d’attractivité » (et une « score de reproduction », phase 7).

Fichiers impactés : web/js/income.js, web/js/visitor-attraction.js, web/js/config.js, web/js/state.js, web/js/ui.js, web/js/world-map.js.

Dépendances : Phase 3, 5, 7.

---

9. Carte du monde : agrandissement en unités de recherche et compteurs

Objectif : Agrandissement de la carte payé en unités de recherche ; affichage des compteurs et des cases zoo (attractivité, reproduction, vente).

Livrables :

• Agrandissement de la carte : plus payé en pièces mais en unités de recherche produites par les centres de recherche des zoos du joueur. Coût en unités par palier (plus cher par palier, même nombre de cases ajoutées). Si pas assez d’unités, bouton/zone grisé.
• Compteurs (sur la carte du monde ou dans une barre dédiée) :
  • Compteur de bébés à vendre (total ou par zoo)
  • Compteur d’animaux à vendre
  • Compteur de laboratoires
  • Compteur de zoos
  • Compteur de villes
• Cases monde au lancement : 1 Agrandissement carte, 1 Compteur bébés à vendre, 1 Compteur animaux à vendre, 1 Compteur laboratoires, 1 Compteur zoos, 1 Compteur villes, 1 Accueil, 1 Nourriture, 1 Camion, 24 cases 3 couleurs.
• Case du zoo (joueur et autres) : 1 case nom du zoo, juste en dessous 1 case score d’attractivité, juste en dessous 1 case score de reproduction, juste en dessous 1 case de vente (voir phase 10). Possibilité d’acheter sur les cases voisines d’autres cases de vente (achats multi-slots).
• Même principe pour zoos des autres joueurs et zoos bots.

Fichiers impactés : web/js/state.js, web/js/economy.js, web/js/world-map.js, web/js/ui.js, web/js/config.js.

Dépendances : Phase 3, 7, 8.

---

10. Ventes et enchères (bébés et animaux adultes)

Objectif : Bébés et animaux en vente sur la carte du monde ; enchères joueurs/bots ; vendeur valide ou non ; bébé invendu meurt.

Livrables :

• Cases de vente : sur la carte du monde, sous le nom de chaque zoo, une (ou plusieurs) case(s) de vente affichant un bébé ou un animal à vendre, avec le dernier montant d’enchère.
• Mise en vente : depuis la carte du zoo, déplacer un animal ou un bébé mature sur le camion → l’entité sort du zoo et apparaît en vente sur la carte du monde (case de vente du joueur).
• Enchères : joueurs et bots peuvent enchérir. Montant initial décidé par le vendeur (ou dérivé d’un prix de base). Après un temps, le vendeur choisit de valider ou non la vente (acceptation de la meilleure enchère ou refus).
• Si vente validée : l’acheteur reçoit le bébé ou l’animal (en accueil dans son zoo, ou en nurserie si bébé). Le score de reproduction du zoo vendeur au moment de la vente est attaché à l’entité (pour accélérer bébé en phase 6).
• Si bébé invendu (délai dépassé sans vente validée) : le bébé meurt (supprimé, pénalités éventuelles).
• Animaux adultes : les zoos vendent aussi des animaux adultes (pas seulement des bébés) ; même flux : mise sur le camion → case de vente → enchères → validation ou refus.

Fichiers impactés : web/js/state.js, web/js/trade.js, web/js/world-map.js, web/js/ui.js, server/routes/zoos.js ou nouveau server/routes/trades.js (enchères temps réel ou polling), server/db.js (table ou champs pour offres de vente / enchères).

Dépendances : Phase 4, 6, 7, 9.

---

11. Villes

Objectif : Cases des villes avec nom et nombre de visiteurs maximum vers les zoos.

Livrables :

• Cases des villes : sur la carte du monde, chaque ville a 1 case nom et 1 case « nombre de visiteurs maximum vers les zoos » (capacité totale ou par zoo à définir).
• Règle : ce nombre limite ou répartit les visiteurs qui peuvent aller vers les zoos (déjà partiellement en place avec CityAttractionScale ; adapter pour un plafond « max visiteurs vers zoos » par ville).

Fichiers impactés : web/js/config.js, web/js/world-map.js, web/js/income.js ou web/js/visitor-attraction.js, web/js/ui.js.

Dépendances : Phase 8.

---

12. UI et grille au lancement

Objectif : Grille zoo et monde conformes au rappel ; transitions douces visibles ; tous les types de cases et actions.

Livrables :

• Carte du zoo au lancement : 1 Agrandissement du zoo (+1 case, payant), 1 Recherche (en haut à gauche), 1 Billeterie, 1 Nurserie, 1 Accueil nouveaux animaux, 1 Nourriture, 1 Camion, 24 cases de 3 couleurs différentes. Positions exactes (ex. 1_1 = Recherche, 2_1 = Billeterie, …) à fixer dans defaultState() et config.
• Carte du monde au lancement : 1 Agrandissement de la carte (payé en unités de recherche), compteurs (bébés, animaux, labos, zoos, villes), 1 Accueil, 1 Nourriture, 1 Camion, 24 cases de 3 couleurs. Layout à définir (même zone que la grille zoo ou zone dédiée).
• Transitions douces : rendu des couleurs et températures avec interpolation (phase 1) visible sur les deux cartes.
• Actions : achat sur case vide (recherche, billeterie, boutique, nurserie, nourriture, accueil, camion, changement de milieu couleur, changement de milieu température) ; déplacement sur case vide (bébé mature, animal prêt). Messages d’erreur et feedback clairs.
• Accessibilité : ARIA, clavier, contraste (règles projet).

Fichiers impactés : web/js/state.js, web/js/ui.js, web/js/world-map.js, web/css/main.css.

Dépendances : Toutes les phases précédentes.

---

13. Migration et compatibilité

Objectif : Anciennes sauvegardes (modèle œufs/école actuel) restent jouables ou migration propre.

Livrables :

• Détection de version : game_state.version ou game_state.specVersion pour distinguer « ancien » (œufs, école, 5 niveaux) et « nouveau » (bébés, recherche, 7 niveaux, etc.).
• Migration : script ou logique au chargement : si ancienne version, soit conversion (œufs → bébés en nurserie, école → centre de recherche niveau 1, etc.), soit message « sauvegarde incompatible, recommencer ».
• API et BDD : extension de game_state (JSONB) pour tous les nouveaux champs ; pas de perte de données existantes si migration choisie.

Fichiers impactés : web/js/state.js (loadState, defaultState), server/routes/zoos.js, éventuellement script de migration côté serveur.

Dépendances : Toutes les phases 0–12.

---

Synthèse des dépendances

0 (modèle) ─┬─ 1 (couleurs/temp) ─┬─ 2 (multi-cases)
            │                     └─ 5 (nourriture/morts)
            ├─ 3 (bâtiments)
            └─ 4 (bébés/flux)
                    │
                    ├─ 5 (nourriture/morts) ─ 7 (score repro)
                    ├─ 6 (reproduction) ──── 7
                    ├─ 8 (attractivité/visiteurs)
                    ├─ 9 (carte monde recherche/compteurs)
                    └─ 10 (ventes/enchères) ─ 11 (villes)
                            │
                            └─ 12 (UI / grilles lancement) ─ 13 (migration)

Ordre recommandé d’implémentation : 0 → 1 → 3 → 4 → 2 → 5 → 6 → 7 → 8 → 9 → 10 → 11 → 12 → 13.

---

Checklist exhaustive (référence 174-324)

• Cases : couleur (milieu) + température ; transitions douces
• Animaux multi-cases
• Centre de recherche : 7 niv., unités de recherche, 10 zoos/unité, déblocage niveaux animaux/bébés
• Billeterie : 7 niv., 20 visiteurs/unité, entrée/sortie visiteurs
• Boutique : 7 niv., 5 visiteurs simultanés/unité
• Nurserie : 7 niv., 1 bébé/unité, bébé mature → case ou camion
• Nourriture : 7 niv., consommation/animal, mort si pas nourri, 5 animaux/unité, reproduction
• Accueil nouveaux animaux : 7 niv., 1 animal/unité, animal prêt → case ou camion
• Camion : 7 niv., bébé/animal sur camion → vente carte monde, 1 camion/unité
• Changement de milieu (couleur) : 7 niv., payant
• Changement de milieu (température) : 7 niv., payant
• Bébés animaux (plus d’œufs) ; zoos vendent bébés et animaux adultes
• Morts : seuls, pas visités, nourriture, tué autre zoo, recherche trop basse, bébé non vendu à temps, bébé mature non placé à temps, animal accueil non placé à temps, vente échouée, température/milieu en écart
• Reproduction : délai, proximité même type autre zoo, score repro, température/milieu adéquats ; score repro/survie par milieu ; température idéale
• Score de reproduction du zoo : naissances, taux alimentation, score vendu sur l’animal
• Attractivité : valeur cumulée, nombre d’animaux différents, rareté, taux remplissage ; pénalités morts ; bonus naissances
• Visiteurs : entrée billeterie, max 1 journée, plus longtemps avec boutiques et diversité animaux, déplacement attiré
• Carte du monde : agrandissement en unités de recherche ; compteurs bébés, animaux, labos, zoos, villes ; cases zoo (nom, attractivité, reproduction, vente) ; villes (nom, max visiteurs vers zoos)
• Ventes : cases de vente sous les zoos ; enchères joueurs/bots ; vendeur valide ou non ; bébé invendu meurt
• Grille zoo au lancement : 1 agrandissement, 1 recherche, 1 billeterie, 1 nurserie, 1 accueil, 1 nourriture, 1 camion, 24 cases 3 couleurs
• Grille monde au lancement : 1 agrandissement carte (recherche), compteurs, 1 accueil, 1 nourriture, 1 camion, 24 cases 3 couleurs
• Migration anciennes sauvegardes / compatibilité