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
• Amendé : 2026-10-06 (vocabulaire de formes, voir « Amendement 1 »)
• 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.

Amendement 1 — vocabulaire de formes (2026-10-06)

Le point 3 est précisé sans changer le contrat de données. La recette est une somme de primitives additives, suivie de modificateurs qui reçoivent la pente locale du champ en cours, puis du plancher, de la règle de matériau par pente, des matériaux imposés par primitive et des MaterialPatch.

• Primitives lisses : plan incliné, bosse gaussienne, crête, sillon, rupture de pente, rides, rugosité déterministe.
• Primitives de relief marqué : Canyon (tranchée à fond plat le long d'une polyligne, contour bruité), Escarpment (rupture de pente le long d'une polyligne, le terrain descend à droite du sens de parcours), Outcrop (butte ou fosse à sommet plat, contour bruité, matériau roche imposé), BoulderField (blocs semi-ellipsoïdaux tirés par graine, combinés par maximum, roche imposée).
• Modificateurs : Strata quantifie les pentes raides en gradins horizontaux dans un rectangle monde, les fonds et sommets plats ne bougent pas ; SlopeRoughness ajoute un bruit à crêtes pondéré par la pente (roche éraillée, sable lisse). Roughness accepte un nombre d'octaves et un type fractal pour donner du relief de fond à plusieurs échelles.

Tout aléa passe par une graine explicite (FastNoiseLite, RandomNumberGenerator) ; tests/unit/run_site_baker_tests.gd vérifie que le Banc du Vigilant se recuit à l'identique. Le site de démonstration content/sites/terrain_showcase.tres (« Jardin des Formes ») sert de catalogue et de banc d'essai des contrats géométriques (docs/briefs/terrain-varied-landforms.md).

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.