Validate POC A and POC B foundations
This commit is contained in:
chindit committed
1 parent
44fd4b4b43
commit
c38e09a663
47 files changed
+4990
-35
No files matched your search
@@ -0,0 +1,273 @@
|
||||
# Barrières techniques avant la verticale
|
||||
|
||||
## Objectif
|
||||
|
||||
Cette politique protège la verticale contre trois dérives principales :
|
||||
|
||||
1. transformer silencieusement les POC en code de production ;
|
||||
2. dupliquer une règle dans plusieurs scènes ou interfaces ;
|
||||
3. découvrir tardivement des erreurs de dépendance, de chargement ou de
|
||||
régression.
|
||||
|
||||
Les contraintes ci-dessous sont volontairement plus strictes que nécessaire
|
||||
pour un petit prototype. Une verticale engage plusieurs mois de travail ; une
|
||||
frontière légèrement contraignante maintenant coûte moins cher qu'une
|
||||
réécriture au milieu de la production.
|
||||
|
||||
## 1. Séparation physique entre prototypes et production
|
||||
|
||||
```text
|
||||
src/ POC A et B jetables
|
||||
scenes/ scènes des POC
|
||||
game/ futur code de production
|
||||
domain/ règles pures et données typées
|
||||
application/ cas d'usage et contrats
|
||||
world/ acteurs, physique et monde Godot
|
||||
presentation/ HUD, écrans et rendu
|
||||
infrastructure/ sauvegarde, audio, plateforme et entrées
|
||||
composition/ assemblage des scènes et dépendances
|
||||
content/ définitions de contenu, sans logique dupliquée
|
||||
tests/
|
||||
unit/ règles sans scène
|
||||
integration/ assemblage de nœuds et services
|
||||
contract/ ressources, sauvegardes et compatibilité
|
||||
docs/adr/ décisions d'architecture immuables
|
||||
scripts/ barrières qualité reproductibles
|
||||
```
|
||||
|
||||
Les dossiers `game/` et `content/` seront créés avec la première tranche de la
|
||||
verticale. Ils ne contiendront aucune copie directe des scripts des POC.
|
||||
|
||||
## 2. Direction unique des dépendances
|
||||
|
||||
```text
|
||||
domain <── application <── world
|
||||
▲ ▲ │
|
||||
└──────────────┼── presentation
|
||||
└── infrastructure
|
||||
|
||||
composition peut assembler toutes les branches.
|
||||
```
|
||||
|
||||
### Domain
|
||||
|
||||
Contient les règles qui doivent rester vraies quel que soit l'écran ou la scène :
|
||||
ressources, dégâts, intensité sonar, coût d'une amélioration, identification,
|
||||
inventaire et transitions d'état.
|
||||
|
||||
- Classes `RefCounted` ou `Resource` typées.
|
||||
- Aucun `Node`, `Input`, signal de scène, audio, fichier ou rendu.
|
||||
- Aucun accès à une horloge ou à un générateur aléatoire global.
|
||||
- Tests synchrones et déterministes.
|
||||
|
||||
### Application
|
||||
|
||||
Exprime ce que le joueur ou le jeu peut demander : démarrer un scan, équiper un
|
||||
module, enregistrer une preuve, terminer une plongée ou vendre un objet.
|
||||
|
||||
- Dépend uniquement du domaine.
|
||||
- Définit des ports abstraits pour sauvegarde, audio, temps ou plateforme.
|
||||
- Retourne des résultats explicites ; aucune dépendance à un HUD ou un acteur.
|
||||
|
||||
### World
|
||||
|
||||
Adapte Godot aux cas d'usage : véhicule, collisions, capteurs, épaves et outils.
|
||||
|
||||
- Ne possède pas les règles économiques ou de campagne.
|
||||
- Convertit les événements physiques en commandes d'application.
|
||||
- Ne référence aucun HUD concret.
|
||||
|
||||
### Presentation
|
||||
|
||||
Affiche des snapshots et transforme une interaction en commande.
|
||||
|
||||
- Ne calcule pas la consommation, les dégâts, la valeur ou la réussite.
|
||||
- Ne modifie pas directement un acteur ou une ressource de domaine.
|
||||
- Les shaders et renderers traduisent les données ; ils ne les inventent pas.
|
||||
|
||||
### Infrastructure
|
||||
|
||||
Implémente les ports externes : sauvegardes, fichiers, audio, entrées, builds et
|
||||
services de plateforme.
|
||||
|
||||
- Ne contient aucune règle de gameplay.
|
||||
- Les erreurs d'I/O deviennent des résultats contrôlés et testables.
|
||||
|
||||
### Composition
|
||||
|
||||
Seule couche autorisée à connaître les implémentations concrètes de toutes les
|
||||
autres. Elle instancie, injecte et connecte. Une scène de composition ne doit pas
|
||||
devenir un second système de gameplay.
|
||||
|
||||
## 3. Une seule source de vérité
|
||||
|
||||
Chaque information mutable possède un propriétaire unique.
|
||||
|
||||
| Concept | Propriétaire attendu | Consommateurs |
|
||||
|---|---|---|
|
||||
| Oxygène, batterie, coque | état de plongée du domaine | HUD, alarmes, sauvegarde |
|
||||
| Mouvement physique | acteur sous-marin du monde | caméra, télémétrie, sonar |
|
||||
| Relevé sonar | service/cartographie sonar | renderer, sauvegarde éventuelle |
|
||||
| Inventaire | agrégat de campagne | HUD, vente, sauvegarde |
|
||||
| Contrat actif | service de contrats | objectifs, port, sauvegarde |
|
||||
| Paramètres d'accessibilité | service de réglages | UI, caméra, audio, sonar |
|
||||
|
||||
Un consommateur reçoit un snapshot immuable ou un événement. Il ne maintient
|
||||
pas une copie concurrente de l'état. Un cache doit être explicitement nommé,
|
||||
invalidé par son propriétaire et vérifié par test.
|
||||
|
||||
## 4. Politique anti-duplication
|
||||
|
||||
Avant d'ajouter une fonction, rechercher le concept et ses synonymes avec `rg`.
|
||||
|
||||
Une similitude ne justifie pas toujours une abstraction. Extraire lorsque deux
|
||||
implémentations portent la même règle métier ou doivent évoluer ensemble. Garder
|
||||
deux présentations séparées lorsqu'elles partagent seulement quelques lignes de
|
||||
mise en page.
|
||||
|
||||
Interdictions :
|
||||
|
||||
- copier un calcul du domaine dans un HUD ;
|
||||
- dupliquer des seuils dans plusieurs scripts ;
|
||||
- créer un dossier générique `utils`, `helpers`, `common` ou `shared` ;
|
||||
- coder une variante par difficulté avec un second système complet ;
|
||||
- dupliquer les identifiants d'actions ou les chemins de sauvegarde ;
|
||||
- faire du prototype une dépendance de production.
|
||||
|
||||
Les constantes de réglage deviennent des ressources de configuration validées.
|
||||
Les identifiants stables deviennent des types ou constantes centralisés dans
|
||||
leur domaine propriétaire.
|
||||
|
||||
## 5. Contrats de données
|
||||
|
||||
Les dictionnaires anonymes sont tolérés dans les POC mais interdits aux
|
||||
frontières de production. Un contrat doit préciser :
|
||||
|
||||
- le type de chaque champ ;
|
||||
- son unité (`m`, `s`, `%`, radians) ;
|
||||
- le repère spatial utilisé ;
|
||||
- sa mutabilité ;
|
||||
- son propriétaire ;
|
||||
- sa stratégie de version si elle est sauvegardée.
|
||||
|
||||
Exemples attendus : `SonarSample`, `SonarScan`, `DiveSnapshot`,
|
||||
`TelemetrySnapshot`, `WreckDefinition` et `SaveGameVersion`.
|
||||
|
||||
Les conversions entre coordonnées monde, véhicule et carte sonar se font dans
|
||||
un adaptateur nommé et couvert par des tests. Aucune convention implicite de
|
||||
signe ou d'axe ne doit traverser plusieurs fichiers.
|
||||
|
||||
## 6. Tests obligatoires
|
||||
|
||||
### Pyramide
|
||||
|
||||
1. **Unitaires** : majorité des tests ; domaine pur, rapides et déterministes.
|
||||
2. **Contrats** : ressources, sérialisation, migrations, configurations et
|
||||
invariants de contenu.
|
||||
3. **Intégration** : scènes minimales, signaux, physique et assemblage.
|
||||
4. **Parcours** : peu nombreux ; une boucle complète avec critères observables.
|
||||
5. **Visuels et humains** : lisibilité, contraste, mouvement et compréhension.
|
||||
|
||||
### Règles
|
||||
|
||||
- Tout bug corrigé commence par un test qui échoue lorsque c'est raisonnable.
|
||||
- Aucun test ne dépend du réseau, de l'heure réelle ou d'un ordre aléatoire.
|
||||
- Les attentes temporelles utilisent une horloge injectée ou un nombre de ticks
|
||||
borné, jamais un sommeil arbitraire.
|
||||
- Une scène d'intégration construit le minimum requis pour le comportement.
|
||||
- Les tests vérifient des résultats, pas la structure interne d'une méthode.
|
||||
- Une migration de sauvegarde garde un échantillon de chaque version supportée.
|
||||
- Le contenu principal reçoit des tests de validation : ID uniques, références
|
||||
résolues, profondeur possible et absence de blocage narratif.
|
||||
|
||||
### Barrière actuelle
|
||||
|
||||
`bash scripts/quality_gate.sh` exécute dans cet ordre :
|
||||
|
||||
1. règles d'architecture ;
|
||||
2. chargement de tous les scripts et scènes ;
|
||||
3. tests unitaires existants ;
|
||||
4. tests d'intégration du POC B.
|
||||
|
||||
La verticale ajoutera ses suites à cette commande unique. Une fonctionnalité ne
|
||||
peut pas être déclarée terminée si la barrière échoue.
|
||||
|
||||
La commande locale est la barrière active dans le dépôt actuel. Avant la
|
||||
première fusion de code de production sur un dépôt distant, elle devra devenir
|
||||
un contrôle CI obligatoire avec protection de branche. La CI appellera ce même
|
||||
script ; elle ne maintiendra pas une seconde liste de tests.
|
||||
|
||||
## 7. Taille et responsabilités
|
||||
|
||||
Seuils de revue, non objectifs mécaniques :
|
||||
|
||||
- au-delà de 350 lignes par fichier, vérifier si plusieurs responsabilités sont
|
||||
mêlées ;
|
||||
- au-delà de 40 lignes par fonction, vérifier si des étapes nommées manquent ;
|
||||
- au-delà de cinq dépendances injectées, vérifier si le composant orchestre trop
|
||||
de domaines ;
|
||||
- une scène ne doit avoir qu'une racine de composition identifiable ;
|
||||
- un signal doit décrire un fait passé, une commande une intention.
|
||||
|
||||
Une exception justifiée vaut mieux qu'un découpage artificiel. Une exception
|
||||
durable doit être documentée dans un ADR.
|
||||
|
||||
## 8. Gestion des erreurs et observabilité
|
||||
|
||||
- Toute erreur récupérable produit un résultat explicite et un message utile.
|
||||
- Les erreurs de sauvegarde ne doivent jamais écraser la dernière sauvegarde
|
||||
valide.
|
||||
- Les ressources invalides échouent au chargement ou au test de contrat.
|
||||
- Les logs n'enregistrent aucune donnée personnelle ou secret.
|
||||
- Les événements importants portent un contexte : mission, site, scan ou version.
|
||||
- Les fuites de nœuds, avertissements et erreurs Godot sont triés avant fusion.
|
||||
|
||||
## 9. Sauvegardes et migrations
|
||||
|
||||
- Format versionné dès le premier prototype de verticale sauvegardé.
|
||||
- Écriture dans un fichier temporaire, validation, puis remplacement atomique.
|
||||
- Jamais de sérialisation arbitraire de nœuds ou de physique.
|
||||
- IDs stables plutôt que chemins de scène comme identité métier.
|
||||
- Migration explicite d'une version à la suivante.
|
||||
- Sauvegardes de référence anonymes conservées sous `tests/fixtures/`.
|
||||
|
||||
## 10. Entrées, accessibilité et localisation
|
||||
|
||||
- Le gameplay dépend d'actions abstraites, jamais de touches codées en dur.
|
||||
- Une seule infrastructure traduit les périphériques en commandes.
|
||||
- Toute nouvelle action est remappable et documentée.
|
||||
- Les textes visibles sont identifiables pour la localisation ; aucun texte
|
||||
métier n'est construit par concaténation fragile.
|
||||
- Les informations critiques combinent texte, forme, son ou animation avec la
|
||||
couleur.
|
||||
- Les options réduisant mouvement, flash et contraste sont consultées par la
|
||||
présentation, pas recodées dans chaque effet.
|
||||
|
||||
## 11. Décisions d'architecture
|
||||
|
||||
Un ADR est requis avant :
|
||||
|
||||
- un nouvel autoload ;
|
||||
- une dépendance qui inverse le graphe défini ici ;
|
||||
- un format de sauvegarde ou une migration ;
|
||||
- une technologie externe ou un plugin ;
|
||||
- une exception durable à une barrière automatique ;
|
||||
- un changement de renderer ou de version Godot pendant un jalon.
|
||||
|
||||
Un ADR décrit le contexte, la décision, ses conséquences et les alternatives
|
||||
rejetées. Il ne doit pas être réécrit pour masquer une ancienne décision ; un
|
||||
nouvel ADR le remplace explicitement.
|
||||
|
||||
## 12. Ordre de mise en production
|
||||
|
||||
Avant le premier gameplay de la verticale :
|
||||
|
||||
1. créer les couches vides et leur test d'architecture ;
|
||||
2. définir les premiers contrats typés ;
|
||||
3. porter une règle pure avec ses tests ;
|
||||
4. créer une seule scène de composition ;
|
||||
5. intégrer le véhicule puis le sonar par adaptateurs ;
|
||||
6. ajouter un parcours end-to-end minimal ;
|
||||
7. seulement ensuite ajouter contenu, port et économie.
|
||||
|
||||
Chaque tranche doit rester jouable et laisser la barrière qualité verte.
|
||||
+52
-35
@@ -5,16 +5,20 @@
|
||||
## Statut du document
|
||||
|
||||
- Nature : plan directeur de conception et de production
|
||||
- Version : 0.1
|
||||
- État : préproduction, aucun code commencé
|
||||
- Version : 0.3
|
||||
- État : POC A et POC B validés ; cadrage de la verticale à préparer
|
||||
- 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).
|
||||
|
||||
## Pitch
|
||||
|
||||
Trace a cursed Inca ransom backward through five centuries of Caribbean shipwrecks. Read the sonar, survive the descent, and decide what the deep should return.
|
||||
|
||||
Ransom’s Wake est un jeu solo d’exploration sous-marine en 3D stylisée, vu à la troisième personne. Le joueur incarne un ancien technicien offshore devenu récupérateur indépendant dans un archipel caribéen fictif.
|
||||
Ransom’s Wake est un jeu solo d’exploration sous-marine en 3D stylisée, vu depuis l'habitacle du mini-sous-marin à travers un large hublot circulaire. Le joueur incarne un ancien technicien offshore devenu récupérateur indépendant dans un archipel caribéen fictif.
|
||||
|
||||
Chaque dossier consiste à obtenir une piste, préparer un mini-sous-marin, rejoindre un secteur probable, lire le relief et le sonar pour localiser une épave, l’identifier, récupérer ou documenter son contenu, puis remonter avant l’épuisement des ressources. Les bénéfices financent l’accès à de nouvelles profondeurs et à des instruments plus performants.
|
||||
|
||||
@@ -29,7 +33,7 @@ Une mission récente apparemment banale révèle progressivement une chaîne de
|
||||
La singularité du jeu repose sur trois éléments combinés :
|
||||
|
||||
1. La recherche locale d’une épave réellement cachée par le relief.
|
||||
2. Un sonar 2D reconstruisant progressivement une carte 3D incomplète.
|
||||
2. Un sonar manuel reconstruisant progressivement une carte bathymétrique 3D.
|
||||
3. Des dossiers historiques couvrant cinq siècles, reliés par une enquête surnaturelle.
|
||||
|
||||
Le jeu ne doit pas être présenté comme un simple cycle « trouver du loot, vendre, améliorer ». La découverte et l’identification de l’épave constituent le cœur du plaisir. L’extraction, le commerce et les améliorations servent à mettre cette recherche sous tension et à renouveler ses possibilités.
|
||||
@@ -146,30 +150,37 @@ La première version ne comprend pas :
|
||||
|
||||
Le mini-sous-marin utilise un contrôleur cinématique. Il simule accélération, inertie et courants sans reposer sur une simulation complète de flottabilité.
|
||||
|
||||
Le POC A a validé une réponse volontairement lente : les commandes donnent un
|
||||
retour audiovisuel immédiat, tandis que la vitesse linéaire, la rotation de la
|
||||
coque et la dérive évoluent progressivement.
|
||||
|
||||
Fonctions d’assistance :
|
||||
|
||||
- maintien automatique de l’assiette ;
|
||||
- maintien de profondeur sans commande verticale ;
|
||||
- arrêt stable lorsque le joueur relâche les commandes ;
|
||||
- limitation du roulis ;
|
||||
- caméra anticollision ;
|
||||
- rapprochement automatique de la caméra dans les cavités ;
|
||||
- transparence temporaire des obstacles qui masquent le véhicule.
|
||||
- caméra fixée à un point intérieur de la cabine ;
|
||||
- regard vertical limité par le champ utile du hublot ;
|
||||
- réduction indépendante du roulis et des mouvements de caméra pour l'accessibilité.
|
||||
|
||||
### 3.2 Contrôles clavier-souris par défaut
|
||||
|
||||
- WASD : propulsion avant/arrière et translation latérale.
|
||||
- Souris : caméra et direction de déplacement.
|
||||
- W/S : propulsion avant et arrière.
|
||||
- A/D : gouvernail gauche et droite.
|
||||
- Souris horizontale : consigne de cap.
|
||||
- Souris verticale : regard limité dans le hublot.
|
||||
- Espace/Ctrl : monter et descendre.
|
||||
- Maj : forte poussée, plus rapide mais moins efficace.
|
||||
- Alt : regard libre.
|
||||
- F : impulsion sonar.
|
||||
- E : interaction contextuelle.
|
||||
- 1 à 4 : sélection des modules.
|
||||
- Tab : carte sonar 3D.
|
||||
- Tab : agrandir ou fermer l'écran sonar.
|
||||
- Commande d’éjection maintenue trois secondes : abandon volontaire.
|
||||
|
||||
Toutes les actions doivent pouvoir être remappées. Aucun mode première personne n’est prévu.
|
||||
Toutes les actions doivent pouvoir être remappées. Le POV depuis l'habitacle est
|
||||
le seul point de vue de pilotage prévu ; aucune caméra extérieure jouable n'est
|
||||
nécessaire à la production.
|
||||
|
||||
---
|
||||
|
||||
@@ -298,13 +309,14 @@ Les sauvegardes de port protègent contre les bugs, pas contre les conséquences
|
||||
|
||||
Le sonar est le principal risque technique et doit être validé avant la production de la campagne.
|
||||
|
||||
1. Le joueur envoie une impulsion orientée.
|
||||
2. L’écran 2D affiche distance, angle, intensité et continuité des échos.
|
||||
3. Plusieurs angles sont nécessaires pour comprendre la forme.
|
||||
4. Chaque impact observé ajoute un point à une carte 3D.
|
||||
5. Les points sont dédupliqués et persistent entre les plongées.
|
||||
6. Les matériaux influencent la réponse.
|
||||
7. La carte ne révèle jamais un volume non observé.
|
||||
1. Le joueur envoie une impulsion orientée sous le nez du sous-marin.
|
||||
2. Le relief est révélé du proche vers le lointain pendant 2,5 secondes.
|
||||
3. Les retours voisins forment une maquette bathymétrique 3D continue locale.
|
||||
4. Les ruptures de profondeur restent visibles comme des ouvertures possibles.
|
||||
5. Un seul scan antérieur subsiste pendant le remplacement par le suivant.
|
||||
6. Le petit écran et la vue agrandie montrent exactement le même relief.
|
||||
7. Les matériaux influencent la couleur et l'intensité de la réponse.
|
||||
8. Aucune géométrie non observée n'est inventée.
|
||||
|
||||
### 7.2 Matériaux sonar
|
||||
|
||||
@@ -318,9 +330,9 @@ Le sonar est le principal risque technique et doit être validé avant la produc
|
||||
|
||||
### 7.3 Progression sonar
|
||||
|
||||
- Sonar I : courte portée, contours grossiers.
|
||||
- Sonar II : portée et densité supérieures, meilleure détection des cavités.
|
||||
- Sonar III : reconstruction stable et détails plus fins.
|
||||
- Sonar I : courte portée, relief grossier et impulsions manuelles.
|
||||
- Sonar II : portée et densité supérieures, remplacement plus rapide.
|
||||
- Sonar III : balayage automatique et reconstruction plus stable.
|
||||
|
||||
Modules de capteur :
|
||||
|
||||
@@ -779,9 +791,9 @@ Aucun personnage 3D marchable.
|
||||
|
||||
### 20.1 Pile
|
||||
|
||||
- Godot 4.6 stable.
|
||||
- Godot 4.7.1 stable.
|
||||
- GDScript.
|
||||
- Renderer Forward+.
|
||||
- Renderer Forward+ visé pour la production ; GL Compatibility utilisé par le POC A pour faciliter les premiers tests multiplateformes.
|
||||
- Blender.
|
||||
- Export glTF 2.0.
|
||||
- Git.
|
||||
@@ -814,13 +826,17 @@ La version mineure du moteur est figée pendant chaque jalon. Toute mise à jour
|
||||
|
||||
### 20.4 Sonar technique
|
||||
|
||||
- Impulsions via faisceaux de rayons physiques bornés.
|
||||
- Matériaux annotés avec réflectivité, rugosité et catégorie.
|
||||
- Bruit déterministe selon distance, angle, sonar et difficulté.
|
||||
- Affichage 2D distance/azimut.
|
||||
- Carte 3D par points dédupliqués dans une grille spatiale.
|
||||
- Sauvegarde compacte des points.
|
||||
- Aucun scan GPU ou reconstruction dynamique de mesh pour la première version.
|
||||
- Grille bathymétrique structurée par ligne et colonne, avec position, normale,
|
||||
intensité, matériau et élévation normalisée.
|
||||
- Surface continue par `ArrayMesh` indexé, normales lissées et palette d'altitude.
|
||||
- Caméra sonar oblique et fixe, cap vers le haut.
|
||||
- Un scan courant et un scan précédent en fondu au maximum.
|
||||
- Une texture de rendu partagée entre l'écran compact et la vue agrandie.
|
||||
- Passe frontale complémentaire pour les anomalies matérielles.
|
||||
- Représentation hybride à concevoir pour les grottes et surplombs, qu'une carte
|
||||
à hauteur unique ne peut pas décrire seule.
|
||||
- Bruit déterministe selon distance, angle, sonar et difficulté après validation
|
||||
de la lecture fondamentale.
|
||||
|
||||
### 20.5 Persistance
|
||||
|
||||
@@ -906,7 +922,7 @@ La version mineure du moteur est figée pendant chaque jalon. Toute mise à jour
|
||||
|---|---:|---|
|
||||
| Préparation | 2 à 4 semaines | Outils, dépôt, builds vides sur trois OS |
|
||||
| POC A jetable | 6 à 8 semaines | Pilotage, caméra, jauges, profondeur, éjection |
|
||||
| POC B jetable | 8 à 12 semaines | Sonar hybride, grotte whitebox, carte 3D |
|
||||
| POC B jetable | 8 à 12 semaines | Sonar de relief, lecture d'ouverture, anomalie |
|
||||
| Verticale | 4 à 6 mois | Une épave, port, contrat, vente, amélioration |
|
||||
| Acte I | 7 à 10 mois | Quatre épaves, économie, difficulté, bilingue |
|
||||
| Démo et préparation EA | 2 à 3 mois | Démo 30 à 45 minutes, QA Windows/Linux |
|
||||
@@ -921,7 +937,8 @@ Total attendu : 36 à 48 mois à environ 15 heures par semaine.
|
||||
|
||||
## 24. Portes de décision
|
||||
|
||||
- Si le sonar n’est pas amusant après le POC B, tester une reconstruction plus automatique.
|
||||
- Si les grottes restent illisibles dans la verticale, tester une reconstruction
|
||||
locale hybride sans abandonner la bathymétrie extérieure validée par le POC B.
|
||||
- Si la recherche reste incompréhensible, réduire l’incertitude des coordonnées.
|
||||
- Si la seconde épave dépasse huit semaines, réduire le jeu à huit épaves et deux zones.
|
||||
- Si le multiplateforme consomme plus de 20 % du temps, repousser la QA Mac.
|
||||
@@ -973,5 +990,5 @@ Total attendu : 36 à 48 mois à environ 15 heures par semaine.
|
||||
- Accès à 5 à 10 testeurs.
|
||||
- Deux POC jetables avant la verticale de production.
|
||||
- Décisions de réduction prises aux jalons.
|
||||
- Aucun code ne doit être commencé avant validation de ce plan comme base de travail.
|
||||
|
||||
- Aucun code de verticale ne doit être commencé avant validation de son cadrage
|
||||
technique et de ses contrats de données.
|
||||
+106
@@ -0,0 +1,106 @@
|
||||
# POC A — Pilotage et survie
|
||||
|
||||
**État : validé.** Le principe du pilotage sous contrainte justifie la poursuite
|
||||
du projet. Les réglages de réactivité et le rendu des projecteurs restent à
|
||||
reprendre pendant la verticale de production.
|
||||
|
||||
## Question à valider
|
||||
|
||||
Piloter le mini-sous-marin sous contrainte est-il agréable, lisible et suffisamment tendu pour justifier la suite du projet ?
|
||||
|
||||
## Ce que le prototype teste
|
||||
|
||||
- Compréhension immédiate des déplacements.
|
||||
- Lisibilité du POV derrière un hublot circulaire.
|
||||
- Différence entre oxygène et batterie de propulsion.
|
||||
- Lecture de la profondeur nominale et critique.
|
||||
- Réaction aux alarmes.
|
||||
- Capacité à conserver une marge de retour.
|
||||
- Acceptation de l’éjection et de la perte du véhicule.
|
||||
|
||||
## Parcours
|
||||
|
||||
1. Rejoindre une balise à faible profondeur.
|
||||
2. Descendre vers une balise placée à 66 m, au-delà de la profondeur nominale de 60 m.
|
||||
3. Choisir combien de temps rester dans la zone dangereuse.
|
||||
4. Revenir au point de récupération.
|
||||
|
||||
Le raccourci F9 place oxygène, batterie et coque près de leurs seuils critiques pour tester rapidement les alarmes et l’éjection.
|
||||
|
||||
## Protocole de playtest
|
||||
|
||||
Chaque session est observée sans expliquer les commandes au-delà de ce qui est affiché.
|
||||
|
||||
Après la session, demander :
|
||||
|
||||
1. Qu’est-ce qui consommait la batterie ?
|
||||
2. À quel moment as-tu compris que la profondeur devenait dangereuse ?
|
||||
3. Savais-tu combien coûterait le retour ?
|
||||
4. La caméra t’a-t-elle gêné ?
|
||||
5. As-tu eu l’impression de contrôler un véhicule ou une caméra volante ?
|
||||
6. Les alarmes étaient-elles lisibles sans être agaçantes ?
|
||||
7. Voudrais-tu effectuer une seconde plongée ?
|
||||
|
||||
## Test ciblé — navigation depuis le hublot
|
||||
|
||||
Cette itération teste la lecture du déplacement dans une zone plus dense, sans
|
||||
ajouter de sonar ni d'indicateur de direction.
|
||||
|
||||
1. Rejoindre la première balise en passant entre les formations proches.
|
||||
2. S'arrêter avant la balise, effectuer un demi-tour, puis la retrouver.
|
||||
3. Descendre vers la seconde balise en utilisant le relief et les particules pour estimer la vitesse.
|
||||
4. Déclencher l'état critique avec F9 et amorcer le retour sans collision.
|
||||
|
||||
Pendant la session, relever :
|
||||
|
||||
- le premier moment où le joueur anticipe correctement sa distance d'arrêt ;
|
||||
- le nombre de collisions dans le premier couloir ;
|
||||
- le temps nécessaire pour retrouver la balise après le demi-tour ;
|
||||
- les moments où le joueur dit ne plus connaître son orientation ;
|
||||
- les obstacles découverts trop tard malgré les phares.
|
||||
|
||||
Le test est concluant si le joueur retrouve la balise en moins de 15 secondes,
|
||||
termine le premier couloir sans aide et sait expliquer quels indices lui ont
|
||||
permis d'estimer sa vitesse et sa profondeur.
|
||||
|
||||
## Critères de passage
|
||||
|
||||
- 80 % des testeurs terminent le parcours sans aide orale.
|
||||
- Aucun testeur ne confond oxygène et batterie après la session.
|
||||
- Les trois seuils d’alarme sont perçus.
|
||||
- La caméra n’est pas citée comme obstacle majeur par plus de 20 % des testeurs.
|
||||
- Au moins quatre testeurs sur cinq souhaitent effectuer une autre plongée.
|
||||
- Aucun bug bloquant sur Windows, Linux ou macOS.
|
||||
|
||||
## Critères de reprise
|
||||
|
||||
- Si le déplacement ressemble à une caméra volante, augmenter inertie, inclinaison visuelle et retours moteur.
|
||||
- Si le POV gêne dans les passages serrés, ajuster le FOV, le roulis transmis et les limites du regard.
|
||||
- Si la batterie est incomprise, renommer explicitement la jauge « propulsion » et renforcer le feedback sous poussée.
|
||||
- Si la profondeur tue trop brutalement, allonger la zone de grâce.
|
||||
- Si les alarmes fatiguent, espacer leur répétition sans réduire leur multimodalité.
|
||||
|
||||
## Non-objectifs
|
||||
|
||||
- Qualité graphique finale.
|
||||
- Sonar.
|
||||
- Recherche d’épave.
|
||||
- Économie.
|
||||
- Assurance persistante.
|
||||
- Marchés.
|
||||
- Dialogue.
|
||||
- Sauvegarde.
|
||||
- Compatibilité manette certifiée.
|
||||
|
||||
## Décisions issues du POC
|
||||
|
||||
- POV unique depuis l'habitacle, derrière un large hublot circulaire.
|
||||
- Caméra physiquement solidaire de la cabine.
|
||||
- W/S pour avancer et reculer ; A/D pour gouverner.
|
||||
- Réponse audiovisuelle immédiate, mouvement linéaire et angulaire inertiel.
|
||||
- Relief proche, particules et balises intermédiaires nécessaires à l'orientation.
|
||||
- Projecteurs indispensables, mais leur diffusion volumétrique reste un risque
|
||||
technique à reprendre avec le renderer de production.
|
||||
|
||||
Le détail des valeurs, limites et solutions provisoires est consigné dans
|
||||
[POC_A_TECHNICAL_BASELINE.md](POC_A_TECHNICAL_BASELINE.md).
|
||||
@@ -0,0 +1,287 @@
|
||||
# POC A — Bilan technique consolidé
|
||||
|
||||
## Statut
|
||||
|
||||
- Date de consolidation : 6 août 2026.
|
||||
- État : POC validé et figé comme référence de conception.
|
||||
- Nature : prototype jetable sous Godot 4.7.1, renderer GL Compatibility.
|
||||
- Suite : POC B consacré au sonar de relief facetté et à sa lisibilité.
|
||||
|
||||
Ce document sépare les décisions validées des valeurs de réglage et des
|
||||
solutions provisoires. Les nombres ci-dessous décrivent la dernière version
|
||||
testée du POC A ; ils ne constituent pas tous des valeurs de production.
|
||||
|
||||
## Résultat du POC
|
||||
|
||||
Le principe d'un mini-sous-marin piloté sous contrainte est validé. Le joueur
|
||||
peut comprendre les ressources, anticiper une profondeur dangereuse, naviguer
|
||||
avec une inertie perceptible et retrouver un objectif depuis un POV intérieur.
|
||||
|
||||
Deux points restent explicitement ouverts :
|
||||
|
||||
- la réactivité exacte des commandes doit encore être affinée ;
|
||||
- les projecteurs et leur diffusion dans l'eau doivent être entièrement repris.
|
||||
|
||||
## Décisions de conception validées
|
||||
|
||||
### Point de vue
|
||||
|
||||
- POV unique depuis l'habitacle.
|
||||
- Vue extérieure abandonnée comme mode de pilotage de production.
|
||||
- Large hublot circulaire avec cadre fixe servant de repère spatial.
|
||||
- Caméra physiquement enfant de la coque et incapable de quitter la cabine.
|
||||
- Tangage et une part du roulis de la coque transmis à la caméra.
|
||||
- Regard vertical limité par le champ utile du hublot.
|
||||
|
||||
### Commandes et mouvement
|
||||
|
||||
- W/S : avancer et reculer.
|
||||
- A/D : gouverner à gauche et à droite, sans translation latérale commandée.
|
||||
- Souris horizontale : modifier la consigne de cap.
|
||||
- Souris verticale : regarder dans les limites du hublot.
|
||||
- Espace/Ctrl : monter et descendre.
|
||||
- Maj : forte poussée.
|
||||
- Le retour à la commande doit être immédiat, mais la réponse physique retardée.
|
||||
- La coque conserve une dérive et une vitesse angulaire progressives.
|
||||
- Le sous-marin ne doit pas tourner presque sur place.
|
||||
|
||||
Le POC ne contient pas encore le retour moteur audio requis en production. Le
|
||||
retour immédiat actuel repose principalement sur l'inclinaison du cockpit, le
|
||||
mouvement des faisceaux et les instruments.
|
||||
|
||||
### Orientation et environnement
|
||||
|
||||
- Un espace vide ne permet pas de lire correctement vitesse ou profondeur.
|
||||
- Relief proche, particules suspendues et silhouettes distinctes sont requis.
|
||||
- Une balise principale distante ne suffit pas après un changement d'objectif.
|
||||
- Des chaînes de petits feux colorés peuvent indiquer un trajet sans flèche HUD.
|
||||
- La visibilité doit conserver des silhouettes au-delà de la portée utile des
|
||||
phares ; une obscurité entièrement noire désoriente sans enrichir la recherche.
|
||||
|
||||
### Survie et interface
|
||||
|
||||
- L'oxygène diminue continuellement.
|
||||
- La batterie représente explicitement la propulsion et ne diminue que sous
|
||||
poussée ou gouvernail actif.
|
||||
- La batterie vide n'entraîne pas une mort instantanée.
|
||||
- La profondeur dangereuse, les dégâts de collision et la marge de retour sont
|
||||
toujours annoncés.
|
||||
- Les alarmes utilisent texte, couleur et son ; aucune information critique ne
|
||||
doit dépendre uniquement de la couleur en production.
|
||||
- L'éjection volontaire nécessite une commande maintenue trois secondes.
|
||||
|
||||
## Baseline de pilotage actuelle
|
||||
|
||||
### Translation
|
||||
|
||||
| Paramètre | Valeur du POC |
|
||||
|---|---:|
|
||||
| Vitesse de croisière | 6,0 m/s |
|
||||
| Forte poussée | 9,5 m/s |
|
||||
| Accélération | 2,0 m/s² |
|
||||
| Freinage | 1,35 m/s² |
|
||||
| Résistance latérale | 2,2 m/s² |
|
||||
|
||||
### Rotation
|
||||
|
||||
| Paramètre | Valeur du POC |
|
||||
|---|---:|
|
||||
| Vitesse de consigne clavier | 55°/s |
|
||||
| Vitesse angulaire maximale | 45°/s |
|
||||
| Accélération angulaire | 30°/s² |
|
||||
| Freinage angulaire | 24°/s² |
|
||||
| Sensibilité souris | 0,0025 rad/pixel |
|
||||
|
||||
La consigne de cap et la rotation réelle sont distinctes. La vitesse angulaire
|
||||
se rapproche progressivement d'une vitesse cible calculée depuis l'erreur de
|
||||
cap, puis se résorbe sans téléporter la coque sur la consigne.
|
||||
|
||||
### Mesure de référence
|
||||
|
||||
Avec W+D maintenus depuis l'arrêt :
|
||||
|
||||
| Temps | Rotation cumulée | Vitesse linéaire |
|
||||
|---|---:|---:|
|
||||
| 0,5 s | environ 4° | 1,00 m/s |
|
||||
| 2,0 s | environ 57° | 3,96 m/s |
|
||||
| 4,0 s | environ 147° | 5,57 m/s |
|
||||
|
||||
Cette réponse a été jugée correcte dans son principe, mais encore perfectible
|
||||
dans son réglage fin.
|
||||
|
||||
## Baseline caméra et hublot
|
||||
|
||||
| Paramètre | Valeur du POC |
|
||||
|---|---:|
|
||||
| FOV vertical Godot (`KEEP_HEIGHT`) | 82° |
|
||||
| Position locale caméra | (0,00 ; 0,52 ; -0,48) m |
|
||||
| Inclinaison initiale | -0,04 rad |
|
||||
| Regard vertical minimal | -0,30 rad, environ -17° |
|
||||
| Regard vertical maximal | 0,20 rad, environ 11° |
|
||||
| Tangage visuel maximal de la coque | 18° |
|
||||
| Roulis visuel maximal de la coque | 16° |
|
||||
| Roulis transmis à la caméra | 55 % |
|
||||
|
||||
Le hublot est un masque circulaire en shader `canvas_item`, corrigé selon le
|
||||
ratio de l'écran. Son rayon normalisé vertical est de 0,435. Le cadre et le
|
||||
verre sont provisoires ; seule la forme circulaire et la présence d'un repère
|
||||
fixe sont validées.
|
||||
|
||||
Le contrôleur contient encore une branche de caméra extérieure héritée des
|
||||
premières itérations. Elle n'est pas validée et doit être supprimée lors de la
|
||||
réécriture de production.
|
||||
|
||||
## Baseline des projecteurs
|
||||
|
||||
| Paramètre | Valeur du POC |
|
||||
|---|---:|
|
||||
| Nombre | 2 |
|
||||
| Portée SpotLight3D | 58 m |
|
||||
| Énergie | 38 |
|
||||
| Angle | 24° |
|
||||
| Divergence horizontale | ±6° |
|
||||
| Inclinaison verticale | -3° |
|
||||
| Ombres | désactivées |
|
||||
|
||||
GL Compatibility n'affiche pas le volume lumineux dans le brouillard. Le POC
|
||||
combine donc :
|
||||
|
||||
1. deux `SpotLight3D` pour éclairer les surfaces ;
|
||||
2. des lentilles émissives en vue extérieure ;
|
||||
3. six plans translucides par phare en POV pour simuler la diffusion dans l'eau ;
|
||||
4. un cône translucide différent pour l'ancienne vue extérieure.
|
||||
|
||||
Les six plans POV se trouvent à 4, 7,5, 12, 18, 25 et 32 mètres. Cette solution
|
||||
est un bricolage jetable : elle produit des halos, dépend fortement du point de
|
||||
vue et ne doit pas être portée telle quelle en production.
|
||||
|
||||
Les ombres des projecteurs ont été désactivées après apparition de bandes de
|
||||
shadow mapping sur les volumes whitebox. Le renderer de production visé reste
|
||||
Forward+ ; le traitement final devra comparer brouillard volumétrique, particules
|
||||
éclairées et solution écran, avec des limites strictes de performance.
|
||||
|
||||
## Baseline de visibilité et navigation
|
||||
|
||||
### Environnement
|
||||
|
||||
| Paramètre | Valeur du POC |
|
||||
|---|---:|
|
||||
| Couleur de fond | `#031823` |
|
||||
| Énergie ambiante | 0,46 |
|
||||
| Couleur ambiante | `#2b6575` |
|
||||
| Densité du brouillard | 0,013 |
|
||||
| Énergie lumineuse du brouillard | 0,52 |
|
||||
| Énergie directionnelle | 0,35 |
|
||||
|
||||
Le parcours comprend sept formations rapprochées supplémentaires et 520
|
||||
particules suspendues. Les particules ont une durée de vie de 14 secondes et une
|
||||
vitesse initiale comprise entre 0,025 et 0,11 m/s. Ces valeurs servent uniquement
|
||||
à rendre parallaxe et vitesse perceptibles.
|
||||
|
||||
### Balises
|
||||
|
||||
| Étape | Position | Rayon |
|
||||
|---|---|---:|
|
||||
| Navigation initiale | (0 ; -22 ; -58) | 8 m |
|
||||
| Plongée critique | (38 ; -66 ; -128) | 4 m |
|
||||
| Récupération | (0 ; -12 ; 12) | 8 m |
|
||||
|
||||
Après la première balise, trois feux orange matérialisent une descente graduelle
|
||||
vers la seconde. Après la seconde, quatre feux verts matérialisent le retour.
|
||||
Les feux intermédiaires ont un rayon de 0,38 m, une émission de 1,5 et une lumière
|
||||
omnidirectionnelle de portée 7 m et d'énergie 1,8.
|
||||
|
||||
Les positions exactes restent des données whitebox et ne constituent pas une
|
||||
règle de level design. La règle validée est qu'un changement d'objectif doit
|
||||
fournir immédiatement un premier repère visible dans le hublot.
|
||||
|
||||
## Baseline de survie
|
||||
|
||||
| Paramètre | Valeur du POC |
|
||||
|---|---:|
|
||||
| Oxygène | 600 s, soit 10 min |
|
||||
| Batterie | 100 % |
|
||||
| Intégrité | 100 % |
|
||||
| Consommation oxygène | 1 s par seconde |
|
||||
| Consommation batterie à pleine poussée | 0,60 %/s |
|
||||
| Profondeur nominale | 60 m |
|
||||
| Profondeur critique | 72 m |
|
||||
| Profondeur d'écrasement | 78 m |
|
||||
|
||||
Entre 60 et 72 mètres, les dégâts de pression progressent de 0,15 à 5 points
|
||||
par seconde selon une courbe quadratique. Entre 72 et 78 mètres, ils progressent
|
||||
de 5 à 18 points par seconde. À partir de 78 mètres, la coque perd 25 points par
|
||||
seconde.
|
||||
|
||||
Une collision commence à infliger des dégâts au-delà d'une composante d'impact
|
||||
de 3,5 m/s. Les dégâts valent `(impact - 3,5) × 4`, avec un délai de 0,45 seconde
|
||||
avant un nouveau dégât de collision.
|
||||
|
||||
L'estimation de retour utilise la distance divisée par 6 m/s, multipliée par la
|
||||
consommation à pleine poussée, plus 0,035 point de batterie par mètre de remontée.
|
||||
Elle reste une approximation volontairement simple.
|
||||
|
||||
## Alarmes et états terminaux
|
||||
|
||||
| Niveau | Seuil de ressource | Répétition sonore |
|
||||
|---|---:|---:|
|
||||
| Attention | ≤ 30 % | un signal à l'entrée du niveau |
|
||||
| Retour | ≤ 15 % | 2,5 s |
|
||||
| Critique | ≤ 5 % | 1,25 s |
|
||||
| Vide/défaillance | 0 % | 0,75 s |
|
||||
|
||||
Pour la profondeur, l'attention commence à 51 m, le retour au-delà de 60 m, le
|
||||
critique à 72 m et la défaillance à 78 m.
|
||||
|
||||
La coque à zéro et l'oxygène à zéro terminent la plongée. La batterie à zéro ne
|
||||
la termine pas immédiatement. F9 force oxygène à 30 secondes, batterie à 12 %
|
||||
et coque à 28 % afin de tester rapidement les alarmes.
|
||||
|
||||
## Ce qui est validé et ce qui ne l'est pas
|
||||
|
||||
### Validé
|
||||
|
||||
- POV intérieur et hublot circulaire.
|
||||
- Caméra fixée dans la cabine.
|
||||
- Mapping W/S, A/D, Espace/Ctrl et Maj.
|
||||
- Séparation entre commande immédiate et réponse physique inertielle.
|
||||
- Séparation oxygène, propulsion et intégrité.
|
||||
- Profondeur nominale lisible et conséquences progressives.
|
||||
- Besoin de relief, particules et repères après changement d'objectif.
|
||||
- Principe des alarmes et de l'éjection volontaire.
|
||||
|
||||
### Provisoire
|
||||
|
||||
- Toutes les valeurs numériques de pilotage.
|
||||
- Position exacte de la caméra et FOV à 82°.
|
||||
- Intensité du roulis et du tangage.
|
||||
- HUD et cadre du hublot.
|
||||
- Géométrie, couleurs et densité du parcours.
|
||||
- Estimation de coût du retour.
|
||||
- Sons synthétiques des alarmes.
|
||||
|
||||
### À reprendre
|
||||
|
||||
- Rendu et puissance perçue des projecteurs.
|
||||
- Retour audio immédiat du moteur, des propulseurs et du gouvernail.
|
||||
- Réglage fin de la réactivité des commandes.
|
||||
- Accessibilité du roulis, du mouvement caméra et du contraste.
|
||||
- Vérification manette et remappage complet.
|
||||
- Migration du rendu vers Forward+.
|
||||
|
||||
## Vérification technique
|
||||
|
||||
- 13 tests headless passent : 9 pour la survie et 4 pour la fondation sonar.
|
||||
- La scène POC A charge sans erreur de script.
|
||||
- Les itérations du hublot, des projecteurs et des guides ont été vérifiées sur
|
||||
un rendu OpenGL Compatibility 1280 × 720 sur Apple M1.
|
||||
- Les tests ne couvrent pas encore l'interface, le shader du hublot, les
|
||||
particules, le mouvement complet du véhicule ni le rendu des projecteurs.
|
||||
|
||||
## Contrat de reprise pour la production
|
||||
|
||||
Le code du POC A peut être réutilisé pour apprendre ou accélérer un autre POC,
|
||||
mais ne doit pas devenir silencieusement le contrôleur de production. Une
|
||||
réécriture devra préserver les décisions validées, repartir des valeurs de cette
|
||||
baseline comme premier réglage et remplacer explicitement chaque solution
|
||||
provisoire.
|
||||
+104
@@ -0,0 +1,104 @@
|
||||
# POC B — Sonar bathymétrique
|
||||
|
||||
**État : principe validé et figé comme référence de conception.**
|
||||
|
||||
Le bilan consolidé, les valeurs techniques et les limites à conserver lors de
|
||||
la reprise sont consignés dans `docs/POC_B_TECHNICAL_BASELINE.md`.
|
||||
|
||||
Les trois premiers langages visuels ont échoué au test de lisibilité : points
|
||||
sur un écran distance/azimut, surfaces facettées sans épaisseur, puis volumes en
|
||||
voxels. Ils permettaient de constater des retours, mais pas de reconnaître
|
||||
immédiatement le fond marin ni de choisir un chemin.
|
||||
|
||||
La version actuelle adopte le langage d'un modèle numérique de terrain : une
|
||||
surface continue observée en perspective, dont la couleur représente l'altitude
|
||||
et dont l'éclairage rend les pentes visibles.
|
||||
|
||||
## Question à valider
|
||||
|
||||
Une carte bathymétrique 3D continue, révélée du proche vers le lointain,
|
||||
permet-elle de reconnaître immédiatement les creux, les hauteurs, un monticule
|
||||
ouvert et la direction praticable ?
|
||||
|
||||
## Décisions de conception conservées
|
||||
|
||||
- Sonar installé sous le nez et couvrant environ 76° devant le sous-marin.
|
||||
- Impulsion manuelle avec F ; un scan complet dure 2,5 secondes.
|
||||
- Révélation progressive du proche vers le lointain.
|
||||
- Petite fenêtre toujours visible, cliquable pour ouvrir la grande vue ; Tab est
|
||||
conservé comme raccourci.
|
||||
- La simulation et le pilotage continuent lorsque la grande vue est ouverte.
|
||||
- Caméra sonar oblique et stable, cap du sous-marin vers le haut de l'écran.
|
||||
- La carte tourne avec le cap du sous-marin.
|
||||
- Un seul ancien relevé est visible pendant son remplacement, puis disparaît.
|
||||
- Aucun nom, cadre ou flèche ne révèle automatiquement une ouverture.
|
||||
- Le scan automatique reste une amélioration future.
|
||||
|
||||
## Nouveau langage visuel
|
||||
|
||||
- Les échantillons sont organisés en grille régulière devant le véhicule.
|
||||
- Les cellules voisines forment un seul maillage continu ; aucun point flottant,
|
||||
cube ou voxel n'est affiché.
|
||||
- Bleu foncé : profondeur ; cyan/vert : élévation moyenne ; jaune/rouge : sommet.
|
||||
- L'éclairage directionnel et les normales lissées rendent les pentes lisibles.
|
||||
- Une jupe sombre entoure le relevé pour l'ancrer comme une maquette de terrain.
|
||||
- Noir : zone inconnue ou hors de la couverture du scan.
|
||||
- Orange : matériau anormal ; une balise lumineuse renforce le retour métallique.
|
||||
- Une maquette blanche du sous-marin reste en bas de la carte.
|
||||
|
||||
## Scène de calibration
|
||||
|
||||
La scène cubique précédente est remplacée par un fond marin réellement sculpté :
|
||||
|
||||
1. Un sol légèrement incliné et irrégulier.
|
||||
2. Deux reliefs arrondis de tailles différentes dans la partie proche.
|
||||
3. Deux hautes crêtes formant un monticule en U.
|
||||
4. Un chenal central bas qui représente l'ouverture lisible dans une carte
|
||||
d'altitude.
|
||||
5. Un objet métallique placé dans ce chenal.
|
||||
|
||||
Une carte d'altitude ne peut pas représenter un plafond au-dessus d'un vide. Une
|
||||
future grotte complète devra donc combiner la bathymétrie extérieure avec une
|
||||
reconstruction locale de ses surfaces intérieures visibles.
|
||||
|
||||
## Parcours de test
|
||||
|
||||
1. Déclencher un scan avec F depuis la position initiale.
|
||||
2. Observer la surface avancer vers le lointain pendant 2,5 secondes.
|
||||
3. Identifier les reliefs proches, les deux crêtes et le chenal central.
|
||||
4. Choisir une direction de déplacement sans aide textuelle.
|
||||
5. Repérer l'anomalie orange.
|
||||
6. Tourner le sous-marin et vérifier que la lecture reste orientée avec le cap.
|
||||
7. Cliquer sur le petit écran, ou utiliser Tab, pour ouvrir la grande vue.
|
||||
8. Déclencher un second scan et observer le remplacement progressif du premier.
|
||||
|
||||
## Critères de passage
|
||||
|
||||
- Le joueur décrit spontanément une carte de relief ou un fond marin.
|
||||
- Les creux et les hauteurs sont distingués sans explication de la palette.
|
||||
- Le chenal entre les crêtes est identifié comme un passage possible.
|
||||
- Le joueur comprend où se trouve son sous-marin et vers où il regarde.
|
||||
- Le petit écran suffit à lire la silhouette générale du terrain.
|
||||
- L'ancien scan ne gêne pas la lecture pendant son remplacement.
|
||||
|
||||
## Base technique actuelle
|
||||
|
||||
- Grille bathymétrique de 49 × 31 échantillons, de 5 à 95 mètres.
|
||||
- Projection horizontale de 76° alignée sur le cap au moment du scan.
|
||||
- Chaque cellule conserve ligne, colonne, position, normale, intensité, matériau,
|
||||
temps de retour et élévation normalisée.
|
||||
- Génération CPU d'un `ArrayMesh` indexé avec normales lissées et couleurs par
|
||||
sommet, rendu dans un `SubViewport` 960 × 540.
|
||||
- Une seconde passe frontale cherche les matériaux anormaux sans ajouter de
|
||||
nuage de points au rendu.
|
||||
- Les deux écrans réutilisent la même `ViewportTexture`.
|
||||
- Deux surfaces au maximum : scan courant et scan précédent en fondu.
|
||||
|
||||
## Non-objectifs de cette version
|
||||
|
||||
- Carte persistante ou accumulation illimitée de relevés.
|
||||
- Véritable reconstruction volumétrique de grottes et surplombs.
|
||||
- Classification automatique des ouvertures.
|
||||
- Courbes de niveau détaillées ; elles restent une option ultérieure.
|
||||
- Bruit, faux retours et interférences acoustiques.
|
||||
- Améliorations de portée, résolution ou balayage automatique.
|
||||
@@ -0,0 +1,430 @@
|
||||
# POC B — Bilan technique consolidé du sonar bathymétrique
|
||||
|
||||
## Statut
|
||||
|
||||
- Date de consolidation : 7 août 2026.
|
||||
- État : direction validée et POC figé comme référence de conception.
|
||||
- Nature : prototype jetable sous Godot 4.7.1, renderer GL Compatibility.
|
||||
- Dépendance : reprend le véhicule, le POV et les commandes validés dans le POC A.
|
||||
- Conclusion : la représentation bathymétrique 3D est retenue ; le système n'est
|
||||
pas considéré comme finalisé ni prêt pour la production.
|
||||
|
||||
Le joueur a jugé la dernière version « vraiment mieux » et sa direction
|
||||
« bien meilleure », tout en signalant qu'il reste des raffinements. Cette
|
||||
validation porte sur le langage visuel et la boucle d'utilisation, pas sur tous
|
||||
les réglages, la fidélité acoustique ou la qualité graphique définitive.
|
||||
|
||||
## Résultat du POC
|
||||
|
||||
Le sonar devient compréhensible lorsqu'il représente le fond marin comme un
|
||||
modèle numérique de terrain continu observé en perspective. Le joueur peut lire
|
||||
les creux et les hauteurs, identifier un passage et distinguer une anomalie sans
|
||||
interpréter un nuage de points abstrait.
|
||||
|
||||
La boucle validée est la suivante :
|
||||
|
||||
1. Le joueur déclenche manuellement une impulsion avec F.
|
||||
2. La carte se révèle pendant 2,5 secondes, du proche vers le lointain.
|
||||
3. La couleur code l'élévation et l'ombrage montre les pentes.
|
||||
4. Une anomalie matérielle est renforcée en orange.
|
||||
5. Le joueur peut consulter le résultat dans un petit écran ou l'agrandir.
|
||||
6. Un nouveau scan remplace progressivement le précédent.
|
||||
|
||||
## Historique des essais et leçons
|
||||
|
||||
### Essai 1 — distance, azimut et points
|
||||
|
||||
Le premier système montrait une progression de retours ponctuels et des
|
||||
distances. Le joueur comprenait la notion de distance, mais ne pouvait ni
|
||||
reconnaître le relief ni transformer les points en itinéraire. L'image devenait
|
||||
encore plus déroutante lorsque son orientation ne suivait pas clairement le cap.
|
||||
|
||||
Leçon : une donnée techniquement interprétable n'est pas nécessairement une
|
||||
information navigable. La rotation de la représentation avec le véhicule est
|
||||
indispensable, mais ne suffit pas à rendre des points lisibles.
|
||||
|
||||
### Essai 2 — surfaces facettées
|
||||
|
||||
Les impacts ont ensuite été reliés en plaques. Les fragments paraissaient
|
||||
flotter et le joueur ne reconnaissait qu'une vague forme en T.
|
||||
|
||||
Leçon : relier des échos ne produit pas automatiquement un terrain. Il faut une
|
||||
surface cohérente, un référentiel stable et une lecture explicite de la hauteur.
|
||||
|
||||
### Essai 3 — volumes voxelisés
|
||||
|
||||
Les plaques ont été épaissies et fusionnées en voxels de trois mètres. Le relief
|
||||
avait davantage de masse, mais les blocs et leurs ruptures dominaient toujours
|
||||
la lecture. La scène restait illisible.
|
||||
|
||||
Leçon : l'épaisseur ne corrige pas une mauvaise grammaire visuelle. Points,
|
||||
facettes et voxels sont abandonnés pour l'affichage principal.
|
||||
|
||||
### Essai 4 — modèle bathymétrique continu
|
||||
|
||||
La dernière version s'inspire des modèles numériques d'élévation : grille
|
||||
régulière, surface continue, caméra oblique, palette d'altitude et relief
|
||||
ombré. La scène cubique a également été remplacée par un fond sculpté. Après un
|
||||
premier test concluant, la portée a été augmentée et la caisse métallique rendue
|
||||
plus visible.
|
||||
|
||||
Leçon : la lisibilité vient de la combinaison de trois indices redondants :
|
||||
silhouette continue, couleur d'altitude et ombrage. Aucun de ces indices ne doit
|
||||
porter seul toute l'information.
|
||||
|
||||
## Décisions de conception validées
|
||||
|
||||
### Déclenchement et temporalité
|
||||
|
||||
- Le scan est une action manuelle sur F.
|
||||
- Le résultat ne doit jamais être immédiat.
|
||||
- Les retours proches apparaissent avant les retours lointains.
|
||||
- La durée de référence est de 2,5 secondes pour 95 mètres.
|
||||
- Un délai technique de 0,35 seconde suit un scan avant la prochaine impulsion.
|
||||
- Le scan automatique est réservé à une amélioration future.
|
||||
- Une éventuelle difficulté facile pourra fournir davantage d'assistance, mais
|
||||
aucune aide automatique n'est requise dans la baseline.
|
||||
|
||||
### Présentation
|
||||
|
||||
- Le sonar montre une maquette 3D continue du fond devant le sous-marin.
|
||||
- Le point de vue est oblique et légèrement surélevé, comparable à une carte de
|
||||
relief plutôt qu'à un écran radar.
|
||||
- Le sous-marin blanc reste en bas de l'image et son cap pointe vers le haut.
|
||||
- La caméra ne devient jamais une caméra libre sortant du véhicule.
|
||||
- Lorsque le sous-marin tourne, la vue sonar tourne avec lui.
|
||||
- Noir signifie inconnu ou hors de la couverture.
|
||||
- Bleu signifie bas/profond ; cyan et vert signifient relief intermédiaire ;
|
||||
jaune et rouge signifient haut.
|
||||
- Orange signale un matériau anormal. Dans le POC, il s'agit d'une caisse.
|
||||
- Les ouvertures ne sont ni nommées, ni encadrées, ni indiquées par une flèche.
|
||||
|
||||
### Interface
|
||||
|
||||
- Un petit écran sonar reste présent dans le cockpit.
|
||||
- Un clic sur cet écran l'agrandit ; Tab fournit le même basculement.
|
||||
- La vue agrandie affiche exactement la même texture que la petite.
|
||||
- Ouvrir la grande vue ne suspend ni la simulation ni les commandes clavier.
|
||||
- Le véhicule peut donc poursuivre son mouvement pendant la consultation.
|
||||
- Le statut textuel indique le pourcentage, la fin du scan et la présence d'une
|
||||
anomalie, sans expliquer automatiquement la géométrie du terrain.
|
||||
|
||||
### Mémoire des relevés
|
||||
|
||||
- Le POC ne construit pas une carte persistante du monde.
|
||||
- Un seul relevé précédent est conservé pendant l'arrivée du suivant.
|
||||
- Cet ancien relevé passe d'environ 52 % d'opacité à l'invisibilité pendant les
|
||||
2,5 secondes du nouveau scan.
|
||||
- Il est supprimé lorsque le nouveau relevé est terminé.
|
||||
|
||||
## Baseline numérique du capteur
|
||||
|
||||
| Paramètre | Valeur actuelle |
|
||||
|---|---:|
|
||||
| Portée minimale | 5 m |
|
||||
| Portée maximale | 95 m |
|
||||
| Ouverture horizontale | 76° |
|
||||
| Grille bathymétrique | 49 colonnes × 31 lignes |
|
||||
| Nombre maximal d'échantillons de terrain | 1 519 |
|
||||
| Durée de révélation | 2,5 s |
|
||||
| Premier retour planifié | 4 % du scan, soit environ 0,10 s |
|
||||
| Délai après impulsion | 0,35 s |
|
||||
| Masque physique | couche 1 |
|
||||
| Taille de cellule du modèle d'échos | 0,65 m |
|
||||
| Hauteur de départ des sondes de terrain | 48 m au-dessus du capteur |
|
||||
| Profondeur des sondes de terrain | 92 m sous le capteur |
|
||||
|
||||
L'origine logique du capteur se trouve à `(0 ; -0,75 ; -2,2)` mètres dans le
|
||||
repère local du sous-marin. La grille forme un trapèze qui s'élargit selon
|
||||
`tan(76° / 2) × distance`.
|
||||
|
||||
Pour chaque ligne, le temps de révélation est interpolé de 4 % à 100 % de la
|
||||
durée totale. Le balayage visible est donc volontairement piloté par la distance
|
||||
avant et non par une simulation exacte du temps aller-retour acoustique.
|
||||
|
||||
## Acquisition bathymétrique actuelle
|
||||
|
||||
La passe principale ne projette pas réellement 1 519 rayons depuis le nez. Elle
|
||||
place une grille horizontale devant le véhicule et lance, pour chaque cellule,
|
||||
une sonde verticale de haut en bas. Le premier impact fournit :
|
||||
|
||||
- la position mondiale ;
|
||||
- la normale de surface ;
|
||||
- la distance au capteur ;
|
||||
- la ligne et la colonne ;
|
||||
- l'intensité ;
|
||||
- la catégorie de matériau ;
|
||||
- le type d'échantillon ;
|
||||
- le temps de retour visuel ;
|
||||
- l'élévation normalisée.
|
||||
|
||||
Cette technique est un substitut de POC destiné à produire une carte d'altitude
|
||||
continue et lisible. Elle peut révéler le dessus d'un relief que le capteur réel
|
||||
ne verrait pas directement. Elle ne doit donc pas être présentée comme une
|
||||
simulation fidèle d'un sonar multifaisceau.
|
||||
|
||||
L'intensité combine :
|
||||
|
||||
1. une atténuation linéaire avec la distance ;
|
||||
2. une réponse d'incidence allant de 0,18 à 1 ;
|
||||
3. une réflectivité propre au collider ;
|
||||
4. un bornage entre 0 et 1.
|
||||
|
||||
La passe bathymétrique utilise une portée d'intensité interne égale à 1,4 fois
|
||||
la portée nominale afin de ne pas perdre les coins éloignés du trapèze.
|
||||
|
||||
## Détection complémentaire des anomalies
|
||||
|
||||
Une seconde passe utilise 31 × 21 rayons réellement projetés depuis le nez :
|
||||
|
||||
| Paramètre | Valeur actuelle |
|
||||
|---|---:|
|
||||
| Ouverture horizontale | 76° |
|
||||
| Ouverture verticale | 64° |
|
||||
| Inclinaison centrale | -18° |
|
||||
| Portée | 95 m |
|
||||
|
||||
Seuls les impacts classés `METAL` sont conservés. Cette passe permet de détecter
|
||||
une anomalie frontale sans réintroduire le nuage de points dans l'affichage.
|
||||
|
||||
Le renderer moyenne actuellement toutes les positions métalliques et affiche un
|
||||
seul marqueur. Plusieurs objets éloignés seraient donc fusionnés en une position
|
||||
moyenne incorrecte. La production devra regrouper les retours en amas distincts.
|
||||
|
||||
## Normalisation de l'élévation
|
||||
|
||||
Pour chaque scan, l'altitude minimale devient 0 et l'altitude maximale devient
|
||||
1, avec une amplitude minimale forcée à six mètres. Ce choix garantit un bon
|
||||
contraste même sur un terrain peu accidenté.
|
||||
|
||||
Conséquence : une même couleur ne correspond pas nécessairement à la même
|
||||
profondeur absolue entre deux scans. La palette actuelle communique la forme
|
||||
locale, pas une mesure bathymétrique universelle. Une production devra choisir
|
||||
entre contraste adaptatif, échelle absolue ou combinaison des deux avec une
|
||||
légende chiffrée.
|
||||
|
||||
## Reconstruction et rendu
|
||||
|
||||
### Maillage
|
||||
|
||||
- Les échantillons sont indexés par `(colonne, ligne)`.
|
||||
- Deux triangles relient chaque groupe complet de quatre cellules adjacentes.
|
||||
- Les normales des faces sont accumulées puis normalisées par sommet pour lisser
|
||||
l'éclairage.
|
||||
- Une absence d'échantillon interrompt le maillage ; les zones inconnues ne sont
|
||||
pas comblées automatiquement.
|
||||
- Les deux faces de la surface sont rendues afin que le tangage du véhicule ne
|
||||
la fasse pas disparaître.
|
||||
- Une jupe verticale de 4,5 mètres ferme le pourtour et donne à la carte l'aspect
|
||||
d'une maquette solide.
|
||||
- Le maillage complet est actuellement reconstruit sur le CPU chaque fois que le
|
||||
nombre de retours visibles change.
|
||||
|
||||
Cette dernière stratégie est acceptable pour le POC mais coûteuse. Un système
|
||||
de production devra mettre à jour des bandes ou tuiles incrémentales, réutiliser
|
||||
les buffers ou déléguer une partie de la reconstruction au GPU.
|
||||
|
||||
### Palette
|
||||
|
||||
| Intervalle normalisé | Dégradé |
|
||||
|---|---|
|
||||
| 0 à 0,28 | `#173f91` vers `#168fc1` |
|
||||
| 0,28 à 0,52 | `#168fc1` vers `#36b979` |
|
||||
| 0,52 à 0,76 | `#36b979` vers `#d7d93d` |
|
||||
| 0,76 à 1 | `#d7d93d` vers `#ee5734` |
|
||||
| Métal | `#ff6b22` |
|
||||
| Jupe | `#152a32` |
|
||||
| Inconnu | fond `#020407` |
|
||||
|
||||
L'intensité du retour ajoute au maximum 8 % de blanc à la couleur du terrain.
|
||||
|
||||
### Viewport et caméra
|
||||
|
||||
| Paramètre | Valeur actuelle |
|
||||
|---|---:|
|
||||
| `SubViewport` | 960 × 540 |
|
||||
| Mise à jour | continue |
|
||||
| Projection | orthographique |
|
||||
| Taille orthographique | 116 m |
|
||||
| Plan lointain | 240 m |
|
||||
| Position caméra relative | 30 m derrière, 65 m au-dessus |
|
||||
| Point visé relatif | 43 m devant, 8 m sous le véhicule |
|
||||
|
||||
Le sonar possède son propre `World3D`, son environnement, deux lumières
|
||||
directionnelles et sa caméra. Ce découplage permet aux vues compacte et agrandie
|
||||
de partager une image stable indépendamment de la caméra principale.
|
||||
|
||||
L'environnement utilise un tonemapper filmique, une énergie ambiante de 0,42,
|
||||
une lumière principale d'énergie 1,25 avec ombres et une lumière de remplissage
|
||||
d'énergie 0,38.
|
||||
|
||||
### Repères visuels
|
||||
|
||||
- Le sous-marin est une capsule blanche émissive de 5,8 mètres, prolongée par un
|
||||
nez conique.
|
||||
- La caisse/anomalie est représentée par un cube orange non éclairé de
|
||||
`8 × 4,5 × 8` mètres, avec une émission d'énergie 4.
|
||||
- Le cube est placé 1,4 mètre au-dessus de la moyenne des retours métalliques
|
||||
afin de rester identifiable dans la petite vue.
|
||||
|
||||
Ces dimensions sont des exagérations d'interface, pas les dimensions physiques
|
||||
exactes des objets détectés.
|
||||
|
||||
## Baseline de l'interface
|
||||
|
||||
| Élément | Dimensions actuelles |
|
||||
|---|---:|
|
||||
| Panneau compact | 320 × 276 px |
|
||||
| Texture compacte | 298 × 190 px |
|
||||
| Panneau agrandi | 1 060 × 652 px |
|
||||
| Texture agrandie | 1 038 × 556 px |
|
||||
|
||||
La légende actuelle est : bleu profond, vert/jaune hauteur, orange
|
||||
caisse/anomalie, noir inconnu. L'interface rappelle la portée de 95 mètres et le
|
||||
fait que le cap se trouve vers le haut.
|
||||
|
||||
Les textes, tailles, bordures et positions sont provisoires. Sont validés : la
|
||||
présence des deux formats, leur texture commune, le clic d'agrandissement et la
|
||||
continuité de la simulation.
|
||||
|
||||
## Scène de calibration
|
||||
|
||||
| Élément | Valeur actuelle |
|
||||
|---|---:|
|
||||
| Position initiale du sous-marin | `(0 ; -25 ; 22)` m |
|
||||
| Terrain physique | 150 × 170 m |
|
||||
| Centre longitudinal du terrain | z = -28 m |
|
||||
| Maillage du terrain | 61 × 69 sommets |
|
||||
| Collision | `ConcavePolygonShape3D`, double face |
|
||||
| Position horizontale de la caisse | `(0 ; -45)` m |
|
||||
| Taille physique de la caisse | `8 × 5 × 7` m |
|
||||
|
||||
Le terrain est généré par une pente légère, deux ondulations sinusoïdales et des
|
||||
fonctions gaussiennes. Il contient deux reliefs proches, deux crêtes hautes, une
|
||||
crête arrière et une dépression centrale étroite. Cette dépression forme un
|
||||
chenal en U lisible comme passage possible. La caisse repose dans ce chenal.
|
||||
|
||||
La scène est un instrument de calibration de lisibilité. Sa topologie et ses
|
||||
dimensions ne constituent pas une règle de level design.
|
||||
|
||||
## Architecture et flux de données
|
||||
|
||||
### Fichiers principaux
|
||||
|
||||
| Fichier | Responsabilité actuelle |
|
||||
|---|---|
|
||||
| `src/sonar_system.gd` | Déclenchement, acquisition, calendrier des retours et historique court |
|
||||
| `src/sonar_model.gd` | Déduplication spatiale et calcul d'intensité |
|
||||
| `src/sonar_relief_renderer.gd` | Reconstruction du maillage et rendu bathymétrique |
|
||||
| `src/sonar_hud.gd` | Vues compacte/agrandie, statuts, légende et interactions |
|
||||
| `src/poc_b.gd` | Assemblage du POC et génération de la scène de calibration |
|
||||
| `tests/run_poc_b_integration.gd` | Validation automatisée de la boucle complète |
|
||||
|
||||
### Signaux
|
||||
|
||||
- `ping_started()` vide le relevé courant et prépare le fondu du précédent.
|
||||
- `ping_progress(current_cells, previous_cells, progress)` alimente le maillage
|
||||
progressif et les statuts.
|
||||
- `ping_completed(current_cells, previous_cells)` fige le nouveau résultat et
|
||||
supprime l'ancien.
|
||||
- `expanded_changed(is_expanded)` gère notamment la capture de la souris.
|
||||
|
||||
Les tableaux sont actuellement copiés en profondeur entre le système, les
|
||||
signaux et le renderer. Cette simplicité protège le POC des mutations partagées,
|
||||
mais deviendra coûteuse avec une carte plus grande.
|
||||
|
||||
## Ce qui est validé et ce qui ne l'est pas
|
||||
|
||||
### Validé
|
||||
|
||||
- Principe d'une surface bathymétrique 3D continue.
|
||||
- Caméra oblique, orthographique et alignée sur le cap.
|
||||
- Triple lecture par silhouette, couleur d'altitude et ombrage.
|
||||
- Impulsion manuelle et résultat non immédiat.
|
||||
- Révélation du proche vers le lointain en 2,5 secondes.
|
||||
- Portée de POC suffisamment utile à 95 mètres et couverture de 76°.
|
||||
- Petit écran cliquable et vue agrandie non bloquante.
|
||||
- Remplacement progressif d'un seul relevé précédent.
|
||||
- Différenciation orange d'une anomalie.
|
||||
- Absence d'aide automatique signalant les ouvertures.
|
||||
|
||||
### Provisoire
|
||||
|
||||
- Toutes les valeurs numériques de portée, résolution et durée.
|
||||
- Palette exacte et seuils de couleur.
|
||||
- Caméra, éclairage, taille de la jupe et modèle du sous-marin.
|
||||
- Taille exagérée du marqueur de caisse.
|
||||
- Terrain et objet de calibration.
|
||||
- Textes et composition de l'interface.
|
||||
- Maintien d'un seul relevé précédent.
|
||||
- Utilisation du renderer GL Compatibility.
|
||||
|
||||
### À reprendre ou approfondir
|
||||
|
||||
- Acquisition physiquement crédible depuis le capteur sous le nez.
|
||||
- Représentation des parois verticales, plafonds, grottes et surplombs.
|
||||
- Regroupement et représentation de plusieurs anomalies.
|
||||
- Échelle bathymétrique absolue ou légende de profondeur.
|
||||
- Coût énergétique, bruit, faux retours et interférences.
|
||||
- Résolution et portée variables selon les améliorations du véhicule.
|
||||
- Accessibilité de la palette et alternatives à la couleur.
|
||||
- Courbes de niveau éventuelles dans la grande vue seulement.
|
||||
- Performance de reconstruction et allocations mémoire.
|
||||
- Contrôles à la manette et navigation complète dans l'interface.
|
||||
|
||||
## Limite structurelle : grottes et surplombs
|
||||
|
||||
Une carte d'altitude associe une seule hauteur à chaque position horizontale.
|
||||
Elle ne peut donc pas représenter simultanément le toit et le sol d'une grotte,
|
||||
ni un objet situé sous un surplomb.
|
||||
|
||||
La production devra probablement utiliser une solution hybride :
|
||||
|
||||
1. une carte bathymétrique continue pour le fond extérieur ;
|
||||
2. des surfaces locales supplémentaires pour les parois et plafonds visibles ;
|
||||
3. une règle d'occlusion empêchant de révéler ce que l'impulsion ne peut pas
|
||||
atteindre ;
|
||||
4. une transition visuelle cohérente entre carte extérieure et intérieur scanné.
|
||||
|
||||
Ce problème doit être testé dans un niveau réel, pas résolu en ajoutant des
|
||||
voxels à la baseline validée.
|
||||
|
||||
## Vérification technique
|
||||
|
||||
- 13 tests unitaires headless passent : neuf pour la survie et quatre pour la
|
||||
fondation sonar.
|
||||
- 14 assertions d'intégration POC B passent.
|
||||
- L'intégration vérifie la durée, la portée, l'ouverture, le caractère non
|
||||
immédiat, la densité du relevé, les coordonnées de grille, l'élévation, la
|
||||
détection métallique, la génération de faces, l'agrandissement, la conservation
|
||||
d'un relevé précédent et son remplacement progressif.
|
||||
- Le rendu a été contrôlé en 960 × 540 puis réduit à 298 × 190.
|
||||
- La vérification visuelle a été effectuée en OpenGL Compatibility sur Apple M1.
|
||||
|
||||
Les tests ne valident pas automatiquement la compréhension humaine du relief,
|
||||
la perception des couleurs, la fidélité acoustique, les performances sur une
|
||||
grande carte ni le comportement de plusieurs anomalies.
|
||||
|
||||
## Contrat de reprise pour la production
|
||||
|
||||
Le code du POC B peut servir de référence, d'outil de calibration ou de point de
|
||||
départ temporaire. Il ne doit pas devenir silencieusement le sonar de production.
|
||||
|
||||
Une réécriture devra préserver :
|
||||
|
||||
- la surface continue et son orientation stable ;
|
||||
- la progression temporelle proche-vers-lointain ;
|
||||
- l'action manuelle et la possibilité d'une amélioration automatique ;
|
||||
- les formats compact et agrandi ;
|
||||
- la redondance couleur, volume et anomalie ;
|
||||
- le principe de ne pas révéler automatiquement le chemin.
|
||||
|
||||
Elle devra remplacer explicitement :
|
||||
|
||||
- les sondes verticales par un modèle d'acquisition cohérent avec le gameplay ;
|
||||
- la reconstruction complète à chaque retour par une mise à jour incrémentale ;
|
||||
- la moyenne unique des anomalies par un regroupement spatial ;
|
||||
- la carte à hauteur unique par une représentation hybride lorsque les grottes
|
||||
le nécessitent ;
|
||||
- les copies profondes et données sous forme de dictionnaires par des structures
|
||||
adaptées aux performances mesurées.
|
||||
@@ -0,0 +1,32 @@
|
||||
# 0001 — Frontières du code de production
|
||||
|
||||
- Statut : accepté
|
||||
- Date : 2026-08-07
|
||||
- Remplace : aucun
|
||||
|
||||
## Contexte
|
||||
|
||||
Les POC A et B mélangent volontairement règles, nœuds Godot, rendu et assemblage.
|
||||
Cette vitesse était adaptée à la validation, mais favoriserait duplication et
|
||||
régressions dans une verticale de plusieurs mois.
|
||||
|
||||
## Décision
|
||||
|
||||
Le code de production est créé sous `game/` et séparé en `domain`,
|
||||
`application`, `world`, `presentation`, `infrastructure` et `composition`.
|
||||
Les dépendances suivent exclusivement les directions décrites dans
|
||||
`docs/ENGINEERING_GUARDRAILS.md`.
|
||||
|
||||
## Conséquences
|
||||
|
||||
- Les règles peuvent être testées sans scène.
|
||||
- L'assemblage Godot reste remplaçable.
|
||||
- Certaines fonctionnalités nécessitent davantage de contrats explicites.
|
||||
- Les contrôles automatiques refusent les dépendances inverses connues.
|
||||
|
||||
## Alternatives considérées
|
||||
|
||||
- Continuer à organiser les scripts par scène : rejeté à cause du risque de
|
||||
règles dupliquées entre HUD, acteurs et écrans.
|
||||
- Un découpage strict par fonctionnalité : intéressant plus tard, mais moins
|
||||
adapté tant que les frontières de la première verticale ne sont pas stables.
|
||||
@@ -0,0 +1,28 @@
|
||||
# 0002 — Les prototypes restent des références jetables
|
||||
|
||||
- Statut : accepté
|
||||
- Date : 2026-08-07
|
||||
- Remplace : aucun
|
||||
|
||||
## Contexte
|
||||
|
||||
Les POC ont validé des comportements importants, mais utilisent des compromis
|
||||
documentés : dictionnaires implicites, reconstruction complète du sonar, sondes
|
||||
verticales, génération de scène monolithique et rendu GL Compatibility.
|
||||
|
||||
## Décision
|
||||
|
||||
`src/` et `scenes/` restent la zone des POC. Aucun code sous `game/` ne peut les
|
||||
importer. Les comportements validés sont réécrits derrière des contrats typés,
|
||||
avec leurs baselines comme spécification.
|
||||
|
||||
## Conséquences
|
||||
|
||||
- La verticale ne dépend pas accidentellement d'une dette de prototype.
|
||||
- Une correction demandée sur un POC reste possible sans toucher la production.
|
||||
- Le premier portage demande un effort explicite et mesurable.
|
||||
|
||||
## Alternatives considérées
|
||||
|
||||
- Déplacer progressivement les fichiers existants dans la production : rejeté,
|
||||
car les dépendances cachées seraient conservées sous de nouveaux chemins.
|
||||
@@ -0,0 +1,28 @@
|
||||
# 0003 — Une barrière qualité unique
|
||||
|
||||
- Statut : accepté
|
||||
- Date : 2026-08-07
|
||||
- Remplace : aucun
|
||||
|
||||
## Contexte
|
||||
|
||||
Des suites lancées séparément sont facilement oubliées. Un test unitaire vert ne
|
||||
détecte pas nécessairement un script non chargé, une scène invalide ou une
|
||||
dépendance architecturale inversée.
|
||||
|
||||
## Décision
|
||||
|
||||
`bash scripts/quality_gate.sh` devient la commande obligatoire avant achèvement
|
||||
d'un changement. Elle vérifie l'architecture, charge toutes les ressources de
|
||||
code et de scène, puis exécute les suites automatisées.
|
||||
|
||||
## Conséquences
|
||||
|
||||
- Le même point d'entrée peut être utilisé localement et en CI.
|
||||
- La durée de vérification augmentera avec la verticale et devra rester suivie.
|
||||
- Un échec ne peut être neutralisé sans correction ou nouvel ADR.
|
||||
|
||||
## Alternatives considérées
|
||||
|
||||
- Documenter plusieurs commandes indépendantes : rejeté, car l'oubli d'une
|
||||
suite deviendrait un comportement normal.
|
||||
@@ -0,0 +1,22 @@
|
||||
# Architecture Decision Records
|
||||
|
||||
Nommer les décisions `NNNN-titre-court.md`. Ne jamais modifier le sens d'un ADR
|
||||
accepté ; créer un nouvel ADR qui le remplace.
|
||||
|
||||
Modèle :
|
||||
|
||||
```markdown
|
||||
# NNNN — Titre
|
||||
|
||||
- Statut : proposé | accepté | remplacé
|
||||
- Date : AAAA-MM-JJ
|
||||
- Remplace : aucun | NNNN
|
||||
|
||||
## Contexte
|
||||
|
||||
## Décision
|
||||
|
||||
## Conséquences
|
||||
|
||||
## Alternatives considérées
|
||||
```
|
||||
Reference in new issue
Block a user