Ransom-s-wake/docs/adr/0012-authored-heightfield-dive-sites.md

0012 — Sites de plongée en champ de hauteur authoré

• Statut : accepté
• Date : 2026-10-06
• Remplace : aucun

Contexte

Le seul terrain de production est une formule analytique codée dans vehicle_test_environment.gd. La tranche 3 exige un site conçu à la main, lisible au sonar (ADR 0010 : surface unique), avec une route sûre et une route risquée, et le sonar a besoin de distinguer roche et sable par cellule, pas par corps. Il faut un contrat de données pour le terrain, son stockage dans le dépôt et sa production.

Décision

1. Un site de plongée est décrit par une ressource typée DiveSiteDefinition (game/domain/sites/) : identifiant, terrain, limites jouables, point de départ, placements d'objets et routes de contrôle.
2. Le terrain est un champ de hauteur à surface unique SiteTerrainData : grille régulière de columns × rows cellules de cell_size_m mètres, élévations en mètres (axe Y monde, négatif sous la surface) dans un PackedFloat32Array, matériau sonar par cellule dans un PackedByteArray (SonarMaterial.Value, ROCK ou SAND). Repère : +X est, +Z sud, +Y haut ; la colonne croît avec +X, la ligne avec +Z ; la cellule (0, 0) est à (origin_x_m, origin_z_m).
3. Les données sont cuites hors exécution par tools/bake_site_terrain.gd à partir d'une recette déclarative de primitives géomorphologiques nommées (plateau, crête, piton, sillon, rupture de pente, rides, rugosité déterministe par graine). La recette est le document d'auteur versionné ; le résultat est écrit en .res binaire sous content/sites/. Le jeu ne génère jamais de terrain à l'exécution. tools/ dépend du domaine (game/domain/) et de rien d'autre ; aucun code sous game/ ou content/ ne dépend de tools/, ce que la barrière d'architecture vérifie.
4. Un PNG 16 bits n'est pas utilisé pour les hauteurs : le chargeur d'images de Godot ramène les PNG 16 bits en 8 bits, soit des marches de 0,27 m sur 68 m de dénivelé. Un PNG 8 bits de prévisualisation est produit pour la revue humaine seulement.
5. Un seul acteur de monde, BathymetricTerrainActor, construit le maillage visuel et la HeightMapShape3D depuis le même champ ; un test compare les deux. Il expose sonar_material_at(position) et sonar_reflectivity_at(position) que l'acquisition sonar privilégie sur les métadonnées de corps.
6. Les limites de la zone jouable sont une règle applicative (PlayableBoundsRule) qui produit un avertissement ; elles ne sont jamais un mur de terrain (ADR 0010).

Conséquences

• L'environnement de test du véhicule devient une définition de site cuite, sans formule analytique dans game/.
• Toute modification de terrain passe par la recette puis une cuisson ; les fichiers .res sont des artefacts dérivés mais versionnés pour que le chargement du site reste sous 3 s et que le jeu n'ait pas besoin de l'outil.
• Les tests de contrat de contenu peuvent vérifier profondeur, position et dégagement des placements contre le champ de hauteur réel.
• Une sculpture manuelle (Blender) ultérieure devra ré-exporter vers le même SiteTerrainData ; le contrat ne change pas.

Alternatives considérées

• Plugin de terrain externe : rejeté, dépendance et ADR supplémentaires sans besoin démontré ; une heightmap tuilée suffit à la V1.
• Génération à l'exécution depuis la recette : rejeté, le plan impose un site conçu à la main et un chargement borné ; la cuisson garantit un artefact figé et revu.
• Heightmap PNG 16 bits : rejeté pour la raison de précision ci-dessus.
• Maillage sculpté sans champ de hauteur : rejeté, le sonar et les tests ont besoin d'une requête de hauteur et de matériau par position.