Files
builazoo/docs/specs/case_zoo.md
2026-03-05 04:01:29 +01:00

619 lines
18 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# Spécifications : Case de Zoo (Générique)
## Définition
Case spécifique à la grille du zoo, pouvant accueillir les éléments de gestion.
## Types de Contenu Possibles
- **Bâtiments** : Billeterie, Nurserie, Boutique, Centre de Recherche, École, Accueil Animaux.
- **Animaux** : Bébés matures, Animaux adultes.
- **Éléments Mobiles** : Visiteurs, Camion (sur sa zone dédiée).
- **Vide** : Terrain libre pour construction ou placement.
## Propriétés Spécifiques
- **Occupation** : Une case ne peut contenir qu'un seul élément principal (bâtiment/animal) à la fois.
- **Visite** : Enregistre la date de dernier passage d'un visiteur (pour la règle de disparition).
- **Qualité** : Indicateur visuel d'adéquation avec l'animal posé dessus (Jaunissement, Givre).
## Liste des Cases Spéciales (cf. Carte Zoo)
- Agrandissement
- Recherche
- Billeterie
- Nurserie
- Accueil
- Nourriture
- Camion
# Annexes Techniques
## 1. Données et États
### Modèle de Données (JSON)
Hérite de `Case (Générique)`.
```json
{
"last_visit_time": "timestamp | null",
"visit_count_total": "integer",
"visit_count_day": "integer",
"heatmap_score": "float (0-100)",
"quality_score": "float (0-100)",
"pathing": {
"walkable": "boolean",
"movement_cost": "float (>= 1.0)",
"preferred": "boolean (true for path tiles)"
},
"zoo_specific_flags": [
"enum('premium_spot','near_entry','near_shop','near_enclosure','staff_only')"
]
}
```
### Contraintes (Invariants)
* **Walkable** : une case avec `content_type` bâtiment/animal est généralement `walkable=false` pour les visiteurs (sauf exceptions design).
* **last_visit_time** : mis à jour uniquement quand un visiteur “observe” réellement (pas juste traverse) si la mécanique de “visite” est distincte.
* **movement_cost** : > 1.0 sur herbe/boue, = 1.0 sur chemins, < 1.0 interdit (évite vitesse infinie).
### Caractéristiques Initiales
| Caractéristique | Valeur Initiale |
| :--- | :--- |
| Dernière Visite | Création du zoo |
| Qualité | 100 |
### Scores Initiaux
**Passages** : 0 (Heatmap de fréquentation).
**Propreté** : 100 (aucun déchet).
**Coût de marche** : 1.2 (herbe) par défaut, 1.0 (chemin) si la case est convertie.
## 2. Cycles de Vie et Apparition
### Conditions d'Apparition
Génération zoo.
### Conditions de Disparition
**Jamais** : Une case ne disparaît pas, elle change juste de contenu.
### Hérédité
**Qualité du Sol** : Un sol bien entretenu (fertilisé) garde ses bonus après un reset partiel.
## 3. Impacts Environnementaux
### Impact Température
Voir `case_generique.md`.
### Impact Milieu (Biome)
Voir `case_generique.md`.
### Impact Saisons
**Neige** : La case devient blanche en hiver (si T° < 0).
### Impact Heure / Jour-Nuit
**Ombres** : Les ombres des objets sur la case tournent avec le soleil.
## 4. Impacts Biologiques et Sociaux
### Impact Reproduction
**Lieu de rencontre** : Les cases "Buissons" favorisent les rencontres.
### Impact Mort
**Lieu de décès** : Une case où un animal est mort garde une "odeur" (malus stress) pendant 24h.
### Impact Nourriture
**Pâturage** : Une case herbeuse peut être broutée (devient terreuse).
### Impact Attractivité (Visiteurs/Animaux)
**Vue** : Une case "Point de Vue" (hauteur) augmente l'attractivité des animaux alentour.
### Impact Valeur
**Emplacement** : Une case proche de l'entrée vaut plus cher (emplacement premium pour boutiques).
## 5. Impacts Logistiques et Économiques
### Vitesse (Camion/Nurserie/Accueil/Recherche/Labo/Visite)
**Revêtement** : Herbe (Lent), Terre (Moyen), Pavés (Rapide).
### Dépenses (Boutiques/Visiteurs)
**Nettoyage** : Coût si la case est sale (déchets visiteurs).
### Trajet Visiteurs
**Obstacle** : Une case occupée par un bâtiment ou de l'eau est infranchissable (sauf pont).
## 6. Événements
### Événements du Jeu / Carte / Zoo / Ville / Visiteur
* **Passage Visiteur** : Met à jour `last_visit_time`.
* **Salissure** : Apparition d'un déchet.
## 7. Progression
### Tableau des Upgrades
Voir `achat_upgrade_case.md`.
## 8. Logique et Interfaces
### Pseudo-code Impacts
```
function checkAnimalDisappearance(case):
if currentTime - case.last_visit_time > MAX_TIME_WITHOUT_VISIT:
removeAnimal(case.content)
```
### Messages d'Infos / Alerte
| ID | Niveau | Message |
| :--- | :--- | :--- |
| `CASE_DIRTY` | Info | "Une case est sale." |
| `PATH_BLOCKED` | Warning | "Chemin bloqué : les visiteurs recalculent leur trajet." |
| `ANIMAL_NOT_VISITED` | Warning | "Un animal n'a pas été observé depuis longtemps." |
# 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.
## 1. Expérience Utilisateur (UX)
### Sélection (Action)
**Description UX** : Clic sur une case zoo.
**Description UI** : Highlight + Menu contextuel adapté au contenu (Animal -> Stats, Bâtiment -> Upgrade, Vide -> Construire).
**Emplacement** : Grille.
**Intégration** : Standard.
**Navigation** : Clic.
**Événements** : `SELECT_ZOO_CASE`.
#### Assets
- **Musiques** : Son "Click".
- **Sons** : `select_soft.mp3`.
- **Graphiques** : Cadre sélection.
- **Images** : Icône Menu Contextuel.
- **Vidéos** : Effet de sélection (contour brillant).
- **Animations** : Rebondissement léger du contenu.
- **Couleurs** : Blanc.
- **Textes** : "Case [X,Y]".
- **Formes** : Carré.
## Définition
| Champ | Valeur |
|---|---|
| Concept | Case “zoo” : spécialisation de `case_generique` avec contraintes doccupation, métriques de visite, et signaux qualité/propreté. |
| Rôle | Supporter le gameplay de placement (animal/bâtiment), le pathfinding (walkable/cost), et la logique “animal observé” (last_visit_time). |
| Portée | Une tuile de la carte du zoo, identifiée par coordonnées, rendue en isométrie. |
| Contrainte | Mesures dérivées (heatmap, quality_score) calculées à la volée ; pas de fallback : si `content_type` incohérent => log + erreur. |
## Fonctions (tableau détaillé)
| Fonction | Déclencheur | Entrées | Sorties | Règles | Observabilité |
|---|---|---|---|---|---|
| Sélectionner case | clic | x,y | menu contexte | actions selon contenu | Event `SELECT_ZOO_CASE` |
| Résoudre walkable | update terrain | content_type | `pathing.walkable` | bâtiment/animal => false (sauf exceptions) | Event `PATHING_UPDATED` |
| Mettre à jour last_visit_time | visiteur observe | visitor_id | timestamp | observe != traverse | Event `CASE_VISITED` |
| Accumuler heatmap | passage | dt | heatmap_score | 0..100 | Event `HEATMAP_UPDATED` |
| Dégrader propreté | déchets | visitor behavior | cleanliness ↓ | clamp 0..100 | Event `CASE_DIRTY` |
| Mettre à jour qualité | compat animal/terrain | biome/temp | quality_score | signaux visuels | Event `CASE_QUALITY_UPDATED` |
## Icone de base
| Élément | Spécification |
|---|---|
| Représentation | Tuile losange + marqueur |
| Couleur dominante | dépend biome/terrain |
| Variantes | `icon_tile.png`, `icon_tile_dirty.png` |
| États | `dirty`, `fertilized`, `frozen`, `muddy` |
## Interactions (tableau détaillé)
| Interaction | Type | Préconditions | Étapes UI | Résultat | Erreurs / Messages |
|---|---|---|---|---|---|
| Construire ici | Action | case vide | menu → item → place | occupancy building | `CELL_OCCUPIED` |
| Placer animal | Action | enclos compatible | drag/drop | occupancy animal | `BIOME_INCOMPATIBLE` |
| Nettoyer | Action | sale | outil nettoyage | cleanliness ↑ | `NO_STAFF` |
## Personnage contextuel (événements & interaction)
La case est actionnée via la sélection sur la carte du zoo. Le personnage contextuel attendu est le **joueur actif** (avatar) : voir `avatar_joueur.md`.
### Déclencheurs (exemples)
| Event / Message | Condition | Effet UI personnage |
|---|---|---|
| `SELECT_ZOO_CASE` | clic case | avatar présent dans le panneau contexte |
| `CELL_OCCUPIED` / `BIOME_INCOMPATIBLE` | action refusée | avatar affiche la cause et laction suivante possible |
| `CASE_DIRTY` | case sale | avatar propose CTA “Nettoyer” (si action permise) |
### Skins & thèmes
Le rendu du portrait/overlay suit `theme.md` et `inventaire_skins.md`.
## Annexes Techniques
### 1. Données et États (tableau détaillé)
| Donnée / État | Type | Exemple | Source | Contraintes |
|---|---|---|---|---|
| `last_visit_time` | timestamp \| null | - | DB | UTC |
| `visit_count_total` | int | 120 | DB | cumul |
| `visit_count_day` | int | 12 | DB | reset day |
| `heatmap_score` | float | 35.5 | calcul | 0..100 |
| `quality_score` | float | 92.0 | calcul | 0..100 |
| `pathing.walkable` | boolean | true | calcul | dépend contenu |
| `pathing.movement_cost` | float | 1.2 | config | >=1.0 |
| `zoo_specific_flags[]` | enum[] | `near_entry` | DB | - |
#### Caractéristiques Initiales (tableau détaillé)
| Caractéristique | Valeur initiale | Unité | Notes |
|---|---:|---|---|
| Propreté | 100 | pts | init |
| Fertilité | 0 | pts | init |
| Coût marche herbe | 1.2 | coef | default |
#### Scores Initiaux (tableau détaillé)
| Score | Valeur initiale | Plage | Impact |
|---|---:|---|---|
| Passages | 0 | 0..∞ | heatmap |
| Qualité | 100 | 0..100 | rendu |
### 2. Cycles de Vie et Apparition (tableau détaillé)
| Phase | Déclencheur | Entrées | Sorties | Invariants |
|---|---|---|---|---|
| Création | génération map | biome | case | existe toujours |
| Occupation | placement | entity | occupancy | un principal |
| Nettoyage | action | outil | propreté ↑ | clamp |
#### Conditions d'Apparition (tableau détaillé)
| Condition | Seuil | Opérateur | Résultat |
|---|---:|---|---|
| Génération zoo | true | est | case créée |
#### Conditions de Disparition (tableau détaillé)
| Condition | Seuil | Opérateur | Résultat |
|---|---:|---|---|
| - | - | - | case persiste |
#### Hérédité (tableau détaillé)
| Élément | Hérité | Règle |
|---|---|---|
| Sol fertilisé | Oui | garde bonus soft reset |
| Heatmap | Non | recalcul |
### 3. Impacts Environnementaux
#### Impact Température (tableau détaillé)
| Condition | Effet case | Notes |
|---|---|---|
| < 0°C | flag `frozen` | givre |
#### Impact Milieu (Biome) (tableau détaillé)
| Biome | Effet | Notes |
|---|---|---|
| prairie | herbe repousse | nourriture |
#### Impact Saisons (tableau détaillé)
| Saison | Effet | Notes |
|---|---|---|
| hiver | `snowy` | visuel |
#### Impact Heure / Jour-Nuit (tableau détaillé)
| Période | Effet | Notes |
|---|---|---|
| nuit | ombres tournent | rendu |
### 4. Impacts Biologiques et Sociaux
#### Impact Reproduction (tableau détaillé)
| Facteur | Effet sur taux | Condition |
|---|---|---|
| buissons | +5% | proximité enclos |
#### Impact Mort (tableau détaillé)
| Cas | Effet | Condition |
|---|---|---|
| odeur | stress + | 24h in-game |
#### Impact Nourriture (tableau détaillé)
| Ressource | Effet | Condition |
|---|---|---|
| pâturage | herbe→terre | animal broute |
#### Impact Attractivité(Visiteurs (tableau détaillé)
| Action/État | Gain | Rayon | Notes |
|---|---:|---:|---|
| point de vue | + | 4 cases | hauteur |
#### Impact Attractivité Animaux) (tableau détaillé)
| Action/État | Effet animaux | Condition |
|---|---|---|
| foule | stress + | densité |
#### Impact Valeur (tableau détaillé)
| Facteur | Variation | Condition |
|---|---:|---|
| near_entry | + | premium spot |
### 5. Impacts Logistiques et Économiques
#### Vitesse (Camion) (tableau détaillé)
| Paramètre | Effet | Condition |
|---|---|---|
| revêtement | vitesse ± | chemin/pavés |
#### Vitesse (Nurserie) (tableau détaillé)
| Paramètre | Effet | Condition |
|---|---|---|
| placement mode | overlay | sortie bébé |
#### Vitesse (Accueil) (tableau détaillé)
| Paramètre | Effet | Condition |
|---|---|---|
| placement mode | overlay | sortie animal |
#### Vitesse (Recherche) (tableau détaillé)
| Paramètre | Effet | Condition |
|---|---|---|
| - | neutre | - |
#### Vitesse (Labo) (tableau détaillé)
| Paramètre | Effet | Condition |
|---|---|---|
| - | neutre | - |
#### Vitesse (Visite) (tableau détaillé)
| Paramètre | Effet | Condition |
|---|---|---|
| cost | route | A* |
#### Dépenses (Billeterie) (tableau détaillé)
| Poste | Coût | Unité | Condition |
|---|---:|---|---|
| nettoyage | 5 | coins | si sale |
#### Dépenses (Boutiques) (tableau détaillé)
| Poste | Coût | Unité | Condition |
|---|---:|---|---|
| maintenance sol | 1 | coin/case | option |
#### Dépenses (Visiteurs) (tableau détaillé)
| Poste | Coût | Unité | Condition |
|---|---:|---|---|
| déchets | temps | min | propreté |
#### Dépenses (Employés) (tableau détaillé)
| Poste | Coût | Unité | Condition |
|---|---:|---|---|
| passage staff | temps | min | path |
#### Dépenses (Boutiques) (tableau détaillé)
| Poste | Coût | Unité | Condition |
|---|---:|---|---|
| section dupliquée | 1 | coin | conservée |
#### Dépenses (Nurseries) (tableau détaillé)
| Poste | Coût | Unité | Condition |
|---|---:|---|---|
| hygiène | 1 | coin | lore |
#### Dépenses (Nourriture) (tableau détaillé)
| Poste | Coût | Unité | Condition |
|---|---:|---|---|
| pâturage | 0 | - | herbe |
#### Dépenses (Acceuil des animaux) (tableau détaillé)
| Poste | Coût | Unité | Condition |
|---|---:|---|---|
| quarantaine | 1 | coin | lore |
#### Dépenses (Camion) (tableau détaillé)
| Poste | Coût | Unité | Condition |
|---|---:|---|---|
| usure | 1 | coin | lore |
#### Trajet Visiteurs
##### Trajet Visiteurs vers/depuis la ville (tableau détaillé)
| Source | Destination | Déclencheur | Effet |
|---|---|---|---|
| entrée | allées | ticket | spawn |
##### Trajet Visiteurs vers/depuis les animaux (tableau détaillé)
| Source | Destination | Déclencheur | Effet |
|---|---|---|---|
| allée | enclos | curiosité | observe |
##### Trajet Visiteurs vers/depuis les boutiques (tableau détaillé)
| Source | Destination | Déclencheur | Effet |
|---|---|---|---|
| enclos | boutique | faim | achat |
##### Trajet Visiteurs vers/depuis la billeterie (entrées/sorties du zoo) (tableau détaillé)
| Source | Destination | Déclencheur | Effet |
|---|---|---|---|
| allées | sortie | budget 0 | despawn |
### 6. Événements
#### Événements du Jeu (tableau détaillé)
| Event | Déclencheur | Payload | Effet |
|---|---|---|---|
| `CASE_DIRTY` | déchet | coord | flag |
| `PATH_BLOCKED` | obstacle | coord | reroute |
#### Événements du Carte (tableau détaillé)
| Event | Déclencheur | Effet |
|---|---|---|
| `PATHING_UPDATED` | terrain | coûts |
#### Événements du Zoo (tableau détaillé)
| Event | Déclencheur | Effet |
|---|---|---|
| `CASE_QUALITY_UPDATED` | compat | rendu |
#### Événements du Ville / Visiteur (tableau détaillé)
| Event | Déclencheur | Effet |
|---|---|---|
| `CASE_VISITED` | observe | last_visit_time |
#### Événements du Visiteur (tableau détaillé)
| Event | Déclencheur | Effet |
|---|---|---|
| `VISITOR_REROUTE` | blocage | route |
#### Événements du Joueur (tableau détaillé)
| Event | Déclencheur | Effet |
|---|---|---|
| `PLAYER_CLEANS_TILE` | outil | propreté + |
### 7. Progression
#### Tableau des Upgrades (tableau détaillé)
| Niveau | Coût | Effet | Débloque |
|---|---:|---|---|
| Pavés | 250 | cost marche 1.0 | route |
### 8. Logique et Interfaces
#### Pseudo-code Impacts (tableau détaillé)
| Fonction | Entrées | Sorties | Notes |
|---|---|---|---|
| `checkAnimalDisappearance` | case, now | bool | visite |
| `computeMovementCost` | terrain | float | >=1.0 |
#### Messages d'Infos / Alerte (tableau détaillé)
| ID | Niveau | Message | Condition |
|---|---|---|---|
| `CASE_DIRTY` | Info | "Une case est sale." | déchet |
| `PATH_BLOCKED` | Warning | "Chemin bloqué." | reroute |
| `ANIMAL_NOT_VISITED` | Warning | "Animal non observé." | timeout |
## Annexes UX/UI
### 1. Expérience Utilisateur (UX)
#### Description UX (tableau détaillé)
| Parcours | But | Friction | Réduction clics |
|---|---|---|---|
| Ouvrir menu case | agir vite | contexte | menu auto-adapté |
| Nettoyer | propreté | outil | raccourci dans menu |
#### Description UI (tableau détaillé)
| Composant | Contenu | États |
|---|---|---|
| Menu contextuel | actions | selon contenu |
| Highlight | outline | hover/selected |
#### Emplacement (tableau détaillé)
| Zone UI | Position | Notes |
|---|---|---|
| Tuile | monde | iso |
#### Intégration (tableau détaillé)
| Intégration | Contrat | Notes |
|---|---|---|
| `carte_zoo.md` | sélection | panneau |
#### Navigation (tableau détaillé)
| Action | Chemin | Résultat |
|---|---|---|
| Sélection | clic | menu |
#### Événements (tableau détaillé)
| Event UI | Déclencheur | Effet |
|---|---|---|
| `SELECT_ZOO_CASE` | clic | open |
#### Assets Skinables
##### Musiques (tableau détaillé)
| Asset | Usage | Durée | Notes |
|---|---|---:|---|
| `select_tile_click.mp3` | sélection | 0.2s | discret |
##### Sons (tableau détaillé)
| Asset | Usage | Volume |
|---|---|---|
| `select_soft.mp3` | clic | bas |
##### Graphiques (tableau détaillé)
| Asset | Usage | Contraintes |
|---|---|---|
| `tile_outline.png` | highlight | overlay |
##### Images (tableau détaillé)
| Asset | Usage |
|---|---|
| `context_menu_icon.png` | menu |
##### Vidéos (tableau détaillé)
| Asset | Usage | Durée |
|---|---|---:|
| `tile_select.webm` | feedback | 0.5s |
##### Animations (tableau détaillé)
| Animation | Déclencheur | Notes |
|---|---|---|
| bounce contenu | sélection | léger |
##### Couleurs (tableau détaillé)
| Token | Valeur | Usage |
|---|---|---|
| `tile_white` | #FFFFFF | outline |
##### Textes (tableau détaillé)
| Clé | FR | EN |
|---|---|---|
| `tile.coords` | Case {x},{y} | Tile {x},{y} |
##### Formes (tableau détaillé)
| Élément | Forme | Notes |
|---|---|---|
| Tuile | losange | iso |