Define vertical slice technical plan

docs/GAME_DESIGN_PLAN.md

@@ -6,13 +6,15 @@
 
 - Nature : plan directeur de conception et de production
 - Version : 0.3
-- État : POC A et POC B validés ; cadrage de la verticale à préparer
+- État : POC A et POC B validés ; cadrage technique de la verticale proposé
 - Titre : titre de travail, à valider juridiquement avant toute annonce publique
 - Prix commercial : volontairement non défini à ce stade
 
 Les baselines techniques consolidées sont conservées dans
 [POC_A_TECHNICAL_BASELINE.md](POC_A_TECHNICAL_BASELINE.md) et
 [POC_B_TECHNICAL_BASELINE.md](POC_B_TECHNICAL_BASELINE.md).
+Le périmètre et l'architecture proposés pour le prochain jalon sont décrits dans
+[VERTICAL_SLICE_TECHNICAL_PLAN.md](VERTICAL_SLICE_TECHNICAL_PLAN.md).
 
 ## Pitch
 

docs/VERTICAL_SLICE_TECHNICAL_PLAN.md

@@ -0,0 +1,596 @@
+# Verticale jouable — Cadrage technique proposé
+
+## Statut
+
+- Date : 7 août 2026.
+- État : proposition à valider avant le premier code de production.
+- Jalon : verticale jouable, après validation des POC A et B.
+- Durée directrice du plan général : quatre à six mois.
+- Moteur figé pour le jalon : Godot 4.7.1.
+- Références : baselines techniques des POC A et B.
+
+Ce document définit ce que la verticale doit prouver, les frontières de son
+implémentation et l'ordre de construction. Il ne remplace ni le game design
+général ni les baselines des prototypes.
+
+## 1. Question à valider
+
+La verticale doit répondre à une seule question principale :
+
+> Piloter, chercher une épave réellement cachée, l'identifier, récupérer une
+> preuve et revenir sous contrainte forme-t-il une boucle claire et assez
+> satisfaisante pour porter une campagne ?
+
+Les POC ont validé séparément le véhicule et le langage du sonar. La verticale
+doit vérifier leur combinaison dans une mission complète avec préparation,
+objectif, conséquence et progression.
+
+## 2. Parcours joueur retenu
+
+La verticale utilise le premier navire de la campagne : le bâtiment de
+prospection contemporain du précédent opérateur.
+
+1. Consulter un message de contrat et une fiche de secteur.
+2. Accepter la mission avec un équipement imposé ou très limité.
+3. Déployer le mini-sous-marin à proximité de la zone probable.
+4. Suivre le relief tout en surveillant oxygène, propulsion et coque.
+5. Utiliser manuellement le sonar bathymétrique pour trouver un accès masqué.
+6. Découvrir l'épave sans marqueur posé directement sur elle.
+7. Observer deux indices permettant de confirmer son identité.
+8. Dégager ou ouvrir un accès avec une interaction contextuelle simple.
+9. Récupérer une caisse ou un journal lié à la piste du U-Boot.
+10. Calculer la marge de retour et remonter au bateau.
+11. Consulter le débriefing, conserver la preuve et vendre un objet secondaire.
+12. Acheter une première amélioration dont l'effet est vérifiable en replongeant.
+
+Durée cible initiale : 15 à 25 minutes pour une première réussite, hors reprise
+après échec. Ce nombre sera corrigé par playtest.
+
+## 3. Périmètre obligatoire
+
+### Plongée
+
+- POV intérieur et hublot circulaire.
+- Pilotage inertiel avec retour immédiat des commandes.
+- Oxygène, batterie de propulsion, profondeur et intégrité.
+- Alarmes texte, couleur et son.
+- Estimation de retour compréhensible.
+- Sonar manuel progressif, compact et agrandissable.
+- Un terrain conçu à la main avec une route sûre et une route plus risquée.
+- Une épave identifiable et une anomalie secondaire optionnelle.
+- Une interaction d'ouverture et une récupération.
+- Retour réussi, abandon volontaire et perte du véhicule.
+
+### Métajeu minimal
+
+- Un écran de contrat.
+- Une fiche historique courte.
+- Un écran de préparation limité.
+- Un débriefing.
+- Une vente ou restitution.
+- Une amélioration achetable.
+- Une sauvegarde locale versionnée.
+
+### Qualité minimale
+
+- Clavier-souris remappable.
+- Textes français structurés pour une future localisation anglaise.
+- Taille du texte et réduction des mouvements accessibles depuis les réglages.
+- Chargement, sauvegarde et reprise d'une session sans état incohérent.
+- Barrière qualité reproductible sur macOS, puis Windows et Linux avant la fin
+  du jalon.
+
+## 4. Hors périmètre ferme
+
+- Deuxième grande épave.
+- Carte maritime complète et pilotage de surface.
+- Trois ports ou marchés dynamiques.
+- Relations de personnages complètes.
+- Dialogue à embranchements complexe.
+- Plusieurs classes de coque.
+- Plusieurs outils de salvage simulés.
+- Intérieur complet de l'épave.
+- Véritable grotte à plusieurs niveaux ou surplomb complexe.
+- Génération procédurale de site majeur.
+- Corruption surnaturelle avancée.
+- Doublage, cinématique ou art final.
+- Manette certifiée, succès, cloud ou intégration de boutique.
+- Import d'une sauvegarde de démo.
+
+Une idée hors périmètre peut être inscrite dans le backlog. Elle ne peut entrer
+dans la verticale sans retirer un élément de coût comparable et mettre à jour ce
+document.
+
+## 5. Critères de réussite
+
+### Compréhension humaine
+
+- Au moins 8 testeurs sur 10 trouvent l'accès à l'épave en 5 à 10 minutes après
+  l'arrivée dans la zone de recherche, sans aide orale.
+- Au moins 8 sur 10 comprennent le rapport entre bleu, vert, jaune et hauteur.
+- Au moins 8 sur 10 identifient la caisse ou l'anomalie sur le sonar.
+- Aucun testeur ne confond oxygène et batterie après le tutoriel.
+- Les alarmes sont comprises avant la première perte.
+- Au moins 4 testeurs sur 5 souhaitent essayer une seconde mission.
+
+### Boucle de jeu
+
+- Une enquête attentive réduit la recherche locale à moins de dix minutes.
+- Le joueur peut expliquer les deux indices ayant confirmé l'épave.
+- Le retour est une décision anticipable et non une surprise punitive.
+- Une première erreur ne rend jamais la mission principale impossible.
+- L'amélioration achetée produit un changement visible lors d'une seconde sortie.
+
+### Technique
+
+- La barrière qualité reste verte à chaque tranche.
+- Aucun code de production ne dépend des dossiers des POC.
+- Une seule source de vérité existe pour chaque ressource et progression.
+- Une sauvegarde V1 peut être chargée après redémarrage du jeu.
+- Les références de contenu invalides sont refusées par des tests de contrat.
+- Le jeu tient 60 FPS à 1080p sur la machine macOS ARM64 disponible, avec mesure
+  séparée du coût du sonar.
+- Aucun `ERROR`, `SCRIPT ERROR`, avertissement ou objet Godot fuité n'est accepté
+  dans les parcours automatisés.
+
+## 6. Architecture de production
+
+La verticale suit `docs/ENGINEERING_GUARDRAILS.md` et les ADR acceptés.
+
+```text
+game/
+  domain/
+    dive/
+    sonar/
+    mission/
+    inventory/
+    economy/
+    upgrades/
+  application/
+    dive/
+    sonar/
+    mission/
+    port/
+    interfaces/
+  world/
+    submarine/
+    sonar/
+    sites/
+    interactions/
+  presentation/
+    cockpit/
+    sonar/
+    briefing/
+    debriefing/
+    settings/
+  infrastructure/
+    input/
+    save/
+    audio/
+    localization/
+  composition/
+    vertical_slice/
+
+content/
+  wrecks/
+  contracts/
+  evidence/
+  items/
+  upgrades/
+  sites/
+  localization/
+```
+
+Le dossier `application/interfaces/` contient les contrats abstraits vers les
+adaptateurs externes. Le dossier `application/port/` orchestre les écrans et cas
+d'usage du port maritime.
+
+## 7. Propriétaires des états
+
+| État | Propriétaire unique | Lecteurs principaux |
+|---|---|---|
+| Oxygène, batterie, coque, profondeur autorisée | `DiveSession` du domaine | HUD, alarmes, débriefing, sauvegarde |
+| Transform, vitesses et collisions | `SubmarineActor` dans `world` | télémétrie, caméra, capteur |
+| Commande de propulsion | cas d'usage de pilotage | adaptateur physique |
+| Scan courant et précédent | service applicatif sonar | renderer, HUD, sauvegarde si retenue |
+| Échantillons physiques bruts | adaptateur sonar du monde | service applicatif sonar |
+| Objectifs et preuves observées | `MissionProgress` du domaine | HUD, fiche, débriefing |
+| Cargaison du panier | `DiveInventory` du domaine | HUD, récupération, débriefing |
+| Argent et améliorations | `CampaignState` du domaine | port, préparation, sauvegarde |
+| Écran ouvert et sélection locale | présentation concernée | aucune règle de gameplay |
+| Réglages joueur | service de réglages | input, caméra, audio, présentation |
+
+La profondeur affichée est calculée à partir de la position physique, puis
+transmise à `DiveSession` par un échantillon de télémétrie. Le HUD ne la recalcule
+jamais depuis un nœud 3D.
+
+## 8. Premiers contrats typés
+
+Les noms ci-dessous sont des responsabilités proposées. Leur API exacte sera
+validée par tests avant toute scène complète.
+
+### `VehicleCommand`
+
+- poussée longitudinale normalisée ;
+- gouvernail normalisé ;
+- commande verticale normalisée ;
+- forte poussée active ou non ;
+- tick ou instant logique.
+
+Produit par l'infrastructure d'entrée, validé par l'application et consommé par
+l'acteur physique.
+
+### `VehicleTelemetry`
+
+- position et orientation mondiales ;
+- vitesse linéaire et angulaire ;
+- profondeur en mètres ;
+- effort de propulsion normalisé ;
+- intensité de la dernière collision ;
+- tick logique.
+
+Snapshot immuable produit par le monde. Aucune référence de nœud n'en sort.
+
+### `DiveSnapshot`
+
+- identifiant de session ;
+- oxygène restant ;
+- batterie restante ;
+- intégrité ;
+- profondeur nominale et critique ;
+- coût de retour estimé ;
+- niveau d'alarme ;
+- état terminal éventuel.
+
+Produit par le domaine après application d'un tick et d'une télémétrie.
+
+### `SonarSample`
+
+- ligne et colonne ;
+- position et normale dans un repère déclaré ;
+- distance en mètres ;
+- intensité normalisée ;
+- catégorie de matériau ;
+- élévation ou profondeur ;
+- temps de révélation ;
+- statut observé ou inconnu.
+
+Il remplace les dictionnaires implicites du POC B.
+
+### `SonarScan`
+
+- identifiant unique ;
+- transform du capteur à l'émission ;
+- portée et ouvertures ;
+- durée ;
+- dimensions de grille ;
+- collection typée de `SonarSample` ;
+- état : demandé, actif, terminé ou remplacé.
+
+Le résultat stocke le repère de capture. La présentation peut ainsi orienter la
+carte sans relire un acteur mutable.
+
+### `MissionProgress`
+
+- contrat actif ;
+- objectifs connus ;
+- preuves observées ;
+- identité proposée ou confirmée ;
+- interaction d'accès ;
+- objet principal récupéré ;
+- résultat de mission.
+
+### Définitions de contenu
+
+- `WreckDefinition` : identité, époque, dimensions, preuves et références.
+- `ContractDefinition` : donneur, site, objectifs, paiement et prérequis.
+- `EvidenceDefinition` : type d'observation, cible et texte de fiche.
+- `ItemDefinition` : volume, catégorie, valeur et caractère essentiel.
+- `UpgradeDefinition` : coût, prérequis et effet typé.
+- `DiveSiteDefinition` : scène, profondeur, limites et contenu autorisé.
+
+Chaque définition possède un ID stable et ne référence jamais une ressource par
+un texte libre destiné au joueur.
+
+## 9. Flux principaux
+
+### Démarrage de mission
+
+```text
+Briefing UI
+  → AcceptContract
+  → CampaignState valide les prérequis
+  → StartDive crée DiveSession et MissionProgress
+  → Composition charge le DiveSite
+  → World reçoit uniquement les paramètres nécessaires
+```
+
+### Pilotage
+
+```text
+InputAdapter
+  → VehicleCommand
+  → PilotUseCase
+  → SubmarineActor
+  → VehicleTelemetry
+  → TickDive
+  → DiveSnapshot
+  → cockpit et alarmes
+```
+
+### Scan sonar
+
+```text
+Action F
+  → RequestSonarScan
+  → validation état/cooldown
+  → WorldSonarAdapter capture les retours
+  → SonarScanService structure le scan
+  → progression déterministe
+  → SonarPresentationSnapshot
+  → renderer compact et agrandi
+```
+
+La petite et la grande vue consomment la même sortie du renderer. Elles ne
+maintiennent jamais deux reconstructions indépendantes.
+
+### Observation et récupération
+
+```text
+Interaction monde
+  → ObserveEvidence ou RecoverItem
+  → MissionProgress / DiveInventory
+  → résultat explicite
+  → snapshot UI et sauvegarde éventuelle
+```
+
+L'acteur d'épave ne décide pas qu'une mission est terminée. Il décrit le contact
+observé ; le domaine applique les règles du contrat.
+
+### Retour et débriefing
+
+```text
+Zone de retour atteinte
+  → CompleteDive
+  → résultat immuable
+  → transfert autorisé de cargaison
+  → calcul économique
+  → sauvegarde atomique
+  → Debriefing UI
+```
+
+## 10. Scènes de production minimales
+
+| Scène | Responsabilité |
+|---|---|
+| `vertical_slice_root.tscn` | composition et transitions du parcours |
+| `dive_site_survey_wreck.tscn` | environnement, limites et points d'injection |
+| `submarine_actor.tscn` | physique et adaptateurs du véhicule |
+| `survey_wreck.tscn` | géométrie, collisions et points observables |
+| `cockpit_hud.tscn` | télémétrie et alertes |
+| `sonar_display.tscn` | affichage compact et agrandi partagé |
+| `briefing_screen.tscn` | contrat, fiche et départ |
+| `debriefing_screen.tscn` | résultat, cargaison et progression |
+| `workshop_screen.tscn` | une amélioration et son installation |
+
+Ces scènes reçoivent leurs dépendances depuis la composition. Aucun autoload de
+gameplay n'est introduit pour éviter cette injection.
+
+## 11. Sauvegarde V1 minimale
+
+La sauvegarde existe avant le métajeu complet afin d'empêcher une architecture
+reposant sur des nœuds sérialisés.
+
+Contenu V1 :
+
+- version du format ;
+- ID de campagne et date technique non utilisée par le gameplay ;
+- contrat actif ou terminé ;
+- argent ;
+- améliorations acquises et installées ;
+- preuves principales sécurisées ;
+- dernier résultat de plongée ;
+- réglages joueur séparés de la campagne.
+
+La position arbitraire du sous-marin, les particules, les collisions et le
+maillage sonar dynamique ne sont pas sauvegardés dans cette verticale.
+
+Procédure : sérialiser dans un fichier temporaire, relire et valider, puis
+remplacer atomiquement la sauvegarde précédente. Conserver une fixture V1 et un
+test de round-trip dès la première implémentation.
+
+## 12. Stratégie de tests
+
+### Unitaires
+
+- consommation des trois ressources ;
+- seuils de profondeur et dégâts ;
+- estimation du retour ;
+- transitions terminales ;
+- validation et progression temporelle d'un scan ;
+- remplacement d'un seul scan précédent ;
+- classification des matériaux ;
+- ajout idempotent d'une preuve ;
+- conditions d'identification ;
+- capacité de cargaison ;
+- résultat de mission ;
+- vente, restitution et achat d'amélioration.
+
+### Contrats
+
+- IDs de contenu uniques ;
+- références résolues ;
+- contrat principal terminable ;
+- deux preuves valides pour l'épave ;
+- objet principal invendable ou récupérable selon la règle ;
+- effet d'amélioration reconnu ;
+- sauvegarde V1 aller-retour ;
+- rejet d'une version inconnue ;
+- textes visibles munis d'une clé de localisation.
+
+### Intégration
+
+- entrée abstraite vers mouvement et télémétrie ;
+- collision vers dégâts uniques ;
+- sonar monde vers `SonarScan` puis maillage ;
+- rotation du véhicule vers orientation de la carte ;
+- vue compacte et agrandie partageant la même texture ;
+- observation monde vers progression de mission ;
+- récupération vers inventaire ;
+- retour vers débriefing et sauvegarde ;
+- chargement d'une sauvegarde vers écran correct.
+
+### Parcours automatisés
+
+1. Succès nominal avec deux preuves et retour.
+2. Retour sans preuve principale : mission non terminée.
+3. Abandon volontaire : perte appliquée, campagne encore jouable.
+4. Batterie vide : pas de mort instantanée, oxygène continue.
+5. Sauvegarde après débriefing puis redémarrage.
+
+Les parcours utilisent des adaptateurs déterministes, pas une simulation de
+plusieurs minutes en temps réel.
+
+### Tests humains
+
+- compréhension du pilotage sans aide orale ;
+- lecture du relief dans les deux tailles sonar ;
+- découverte de l'accès ;
+- compréhension des indices ;
+- anticipation du retour ;
+- désir de relancer une mission.
+
+Chaque session note les interventions verbales du testeur. Une réussite obtenue
+après explication ne satisfait pas le critère d'autonomie.
+
+## 13. Budgets techniques initiaux
+
+| Budget | Cible de départ |
+|---|---:|
+| Framerate de validation locale | 60 FPS à 1080p |
+| Budget total par frame | 16,7 ms |
+| Sonar, coût CPU moyen pendant scan | ≤ 3 ms |
+| Sonar, pic CPU exceptionnel | ≤ 8 ms sur une frame |
+| Durée de chargement du site sur SSD | ≤ 3 s |
+| Écriture de sauvegarde | ≤ 100 ms hors blocage visible prolongé |
+| Barrière qualité locale | ≤ 60 s avant croissance du contenu |
+| Erreurs ou avertissements Godot acceptés | 0 |
+
+Ces budgets sont des alarmes, pas des promesses commerciales. Une mesure doit
+indiquer la machine, le renderer, la résolution, le build et la scène.
+
+Le renderer Forward+ reste la cible de production. Son adoption pour la
+verticale nécessite un ADR et un test immédiat sur les machines disponibles ;
+elle ne doit pas attendre la phase de finition graphique.
+
+## 14. Tranches d'implémentation
+
+### Tranche 0 — fondations exécutables
+
+- Créer les sous-dossiers nécessaires, sans architecture vide exhaustive.
+- Définir horloge, IDs et premiers types de résultat.
+- Porter `DiveSession` comme règle pure avec tests.
+- Créer une composition minimale et un écran de diagnostic.
+
+Sortie : état de plongée déterministe, testable sans scène, affiché par une scène
+de production qui ne dépend pas des POC.
+
+### Tranche 1 — véhicule de production
+
+- Réécrire le contrôleur derrière `VehicleCommand` et `VehicleTelemetry`.
+- Reproduire les sensations validées du POC A à partir de sa baseline.
+- Intégrer caméra intérieure et hublot.
+- Ajouter les tests de mouvement et de dégâts prioritaires.
+
+Sortie : parcours de pilotage court avec ressources et retour immédiat lisible.
+
+### Tranche 2 — sonar de production
+
+- Définir `SonarSample` et `SonarScan`.
+- Séparer acquisition, reconstruction et présentation.
+- Reproduire la bathymétrie validée sans importer le POC B.
+- Mesurer le coût et passer à une mise à jour incrémentale.
+
+Sortie : relief inconnu révélé manuellement, lisible dans les deux vues, avec
+rotation et remplacement d'un relevé.
+
+### Tranche 3 — site et découverte
+
+- Construire le terrain graybox et l'épave contemporaine.
+- Ajouter une entrée masquée simple, sans surplomb complexe.
+- Définir deux preuves et une anomalie secondaire.
+- Organiser le premier playtest de recherche.
+
+Sortie : 8 testeurs sur 10 trouvent l'épave dans la fenêtre cible ou une porte de
+décision est déclenchée.
+
+### Tranche 4 — interaction et retour
+
+- Ajouter une interaction d'ouverture bornée.
+- Ajouter la caisse, le panier et l'objet principal.
+- Ajouter zone de retour, succès, abandon et perte.
+- Automatiser les parcours nominaux et d'échec.
+
+Sortie : boucle de plongée complète sans métajeu.
+
+### Tranche 5 — contrat, économie et sauvegarde
+
+- Ajouter briefing, fiche, débriefing et atelier.
+- Ajouter une vente/restitution et une amélioration.
+- Écrire Save V1 et ses tests de contrat.
+
+Sortie : boucle verticale complète et rejouable après redémarrage.
+
+### Tranche 6 — présentation et validation
+
+- Remplacer les éléments graybox nécessaires à la compréhension.
+- Ajouter audio moteur, sonar, alarmes et ambiance.
+- Ajouter réglages d'accessibilité retenus.
+- Profiler, tester sur trois OS et conduire le playtest final.
+
+Sortie : décision documentée de poursuivre, corriger ou réduire le projet.
+
+## 15. Risques et portes de décision
+
+| Risque | Détection précoce | Réponse prévue |
+|---|---|---|
+| Sensations perdues pendant la réécriture | test véhicule dès tranche 1 | comparer aux mesures POC A, ajuster avant sonar |
+| Sonar lisible seul mais confus en mission | playtest tranche 3 | réduire relief parasite ou resserrer la zone probable |
+| Ouverture impossible à représenter | site graybox dédié | ajouter surfaces locales ; ne pas revenir aux voxels globaux |
+| États dupliqués entre monde et HUD | tests de propriétaire et snapshots | supprimer la copie, rétablir un flux unidirectionnel |
+| Scènes fortement couplées | contrôle d'architecture | déplacer l'assemblage vers `composition` |
+| Sauvegarde conçue trop tard | Save V1 tranche 5 au plus tard | bloquer le métajeu tant que le round-trip échoue |
+| Contenu lent à produire | mesure sur l'épave contemporaine | réduire preuves et interactions avant d'ajouter une épave |
+| Performance du maillage sonar | profil tranche 2 | buffers incrémentaux, fréquence bornée ou travail distribué |
+| Palette inaccessible | tests contraste/daltonisme | palette alternative et indices de forme |
+| Portée verticale excessive | revue à chaque tranche | retirer une fonctionnalité de coût comparable |
+
+Une porte de décision produit une conclusion écrite. Elle ne devient pas une
+suite indéfinie de corrections sans critère de sortie.
+
+## 16. Décisions à formaliser après validation de ce cadrage
+
+Une fois ce document approuvé, créer des ADR séparés pour :
+
+1. le renderer de production de la verticale ;
+2. les contrats `VehicleTelemetry`, `DiveSnapshot` et `SonarScan` ;
+3. la sauvegarde V1 et sa stratégie atomique ;
+4. l'absence initiale d'autoload de gameplay ;
+5. le modèle hybride retenu si le site exige une surface non bathymétrique.
+
+Les noms de classes peuvent évoluer pendant la tranche 0. Les responsabilités,
+les propriétaires et les directions de dépendance ne changent qu'avec un ADR.
+
+## 17. Première action après approbation
+
+La première implémentation ne sera ni le sous-marin ni le sonar. Elle créera une
+tranche verticale minuscule :
+
+1. `DiveSession` pur avec horloge injectée ;
+2. `VehicleTelemetry` minimal fourni par un faux adaptateur ;
+3. `DiveSnapshot` affiché dans une scène de diagnostic ;
+4. tests de consommation, profondeur et état terminal ;
+5. ajout de cette suite à `scripts/quality_gate.sh`.
+
+Cette tranche prouvera le chemin complet domaine → application → présentation
+et la discipline de tests avant de porter un comportement complexe.