# 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.