diff --git a/README.md b/README.md index 8dafb3d..a092999 100644 --- a/README.md +++ b/README.md @@ -85,4 +85,5 @@ Test d'intégration du POC B : - Objectifs et protocole du POC B : docs/POC_B.md - Bilan technique du POC B : docs/POC_B_TECHNICAL_BASELINE.md - Barrières techniques de production : docs/ENGINEERING_GUARDRAILS.md +- Cadrage technique de la verticale : docs/VERTICAL_SLICE_TECHNICAL_PLAN.md - Décisions d'architecture : docs/adr/ diff --git a/docs/GAME_DESIGN_PLAN.md b/docs/GAME_DESIGN_PLAN.md index 3bbaed4..0a569a2 100644 --- a/docs/GAME_DESIGN_PLAN.md +++ b/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 diff --git a/docs/VERTICAL_SLICE_TECHNICAL_PLAN.md b/docs/VERTICAL_SLICE_TECHNICAL_PLAN.md new file mode 100644 index 0000000..aed8add --- /dev/null +++ b/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.