chindit/Ransom-s-wake

0 Fork 0

Files

T

chindit 9d4a89f355 Define vertical slice technical plan

2026-08-07 15:44:33 +02:00

21 KiB

Raw Blame History

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.

Consulter un message de contrat et une fiche de secteur.
Accepter la mission avec un équipement imposé ou très limité.
Déployer le mini-sous-marin à proximité de la zone probable.
Suivre le relief tout en surveillant oxygène, propulsion et coque.
Utiliser manuellement le sonar bathymétrique pour trouver un accès masqué.
Découvrir l'épave sans marqueur posé directement sur elle.
Observer deux indices permettant de confirmer son identité.
Dégager ou ouvrir un accès avec une interaction contextuelle simple.
Récupérer une caisse ou un journal lié à la piste du U-Boot.
Calculer la marge de retour et remonter au bateau.
Consulter le débriefing, conserver la preuve et vendre un objet secondaire.
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.

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

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

InputAdapter
  → VehicleCommand
  → PilotUseCase
  → SubmarineActor
  → VehicleTelemetry
  → TickDive
  → DiveSnapshot
  → cockpit et alarmes

Scan sonar

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

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

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

Succès nominal avec deux preuves et retour.
Retour sans preuve principale : mission non terminée.
Abandon volontaire : perte appliquée, campagne encore jouable.
Batterie vide : pas de mort instantanée, oxygène continue.
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 :

le renderer de production de la verticale ;
les contrats VehicleTelemetry, DiveSnapshot et SonarScan ;
la sauvegarde V1 et sa stratégie atomique ;
l'absence initiale d'autoload de gameplay ;
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 :

DiveSession pur avec horloge injectée ;
VehicleTelemetry minimal fourni par un faux adaptateur ;
DiveSnapshot affiché dans une scène de diagnostic ;
tests de consommation, profondeur et état terminal ;
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.

21 KiB Raw Blame History