Fichiers
vercora/NOTES-PHASE20.md
T
2026-10-11 01:54:18 +02:00

354 lignes
19 KiB
Markdown
Brut Annotations Historique

Ce fichier contient des caractères Unicode ambigus.
Ce fichier contient des caractères Unicode qui peuvent être confondus avec d'autres caractères. Si vous pensez que c'est intentionnel, vous pouvez ignorer cet avertissement. Utilisez le bouton Échappe pour les dévoiler.
# NOTES-PHASE20.md — La collision cesse d'être une affaire d'arbres
Session du 2026-08-26, à la suite de la Phase 19.
La consigne était d'étendre la collision « à tous les objets du monde qui n'en
ont pas encore ». L'inventaire réel du code a réduit ce périmètre à **une seule
lacune** — et c'est le premier résultat de la phase, avant toute ligne écrite.
---
## 1. L'inventaire, avant de coder
| Catégorie | État trouvé dans le code | Décision de la Phase 20 |
|---|---|---|
| Arbres, souches (`Forest`) | Collision depuis la **Phase 6** | Inchangé |
| Objets posés par l'éditeur (`EditorScene`) | Collision depuis la **Phase 15**, avec un drapeau `solid` **par objet** | Inchangé |
| **Faune (`Wildlife`)** | **Aucune collision** | **Corrigé** |
| Objets au sol (`Ground` : bûches, branches, pierres, éclats) | Aucune collision | **Laissé sans collision, délibérément** (§4) |
### 1.1 Les objets d'éditeur avaient déjà tout ce que la consigne demandait
La consigne proposait de « décider d'une approche raisonnable (ex : un flag
solide par asset ou par instance placée) ». Cette décision avait déjà été prise
en Phase 15, et dans le sens le plus fin des deux : `PlacedObject::solid` est un
drapeau **par instance**, réglable en jeu par la touche `K`, sérialisé dans le
format `.vcsc`. La raison donnée à l'époque tient toujours et vaut mieux que
celle qu'on aurait inventée aujourd'hui : le même rocher peut être un obstacle
sur un sentier et un simple décor à flanc de falaise, et surtout un asset dont
l'empreinte cylindrique est fausse (l'abri, qui a un intérieur) doit pouvoir
être posé sans emmurer le joueur.
**Rien n'a donc été touché de ce côté.** Le vérifier était le travail ; le
réécrire aurait été une régression déguisée en livraison.
### 1.2 L'architecture ne demandait aucune généralisation
La consigne demandait de « généraliser le système existant plutôt que d'écrire
un système parallèle ». La généralisation était déjà faite, en deux temps :
- **Phase 6** : `CollisionSolver` (interface) + `moveBody()` (point d'entrée
unique, qui vérifie le résultat du repoussement et refuse le déplacement quand
aucune position libre n'existe) ;
- **Phase 15** : `CompositeCollisionSolver`, qui implémente le même contrat et
le délègue à une liste de sources.
Résultat : brancher la faune est **une ligne** dans `main.cpp`
(`worldSolver.add(wildlife.get())`), et cette ligne suffit pour **les trois
activités qui se déplacent au sol**. C'est la deuxième fois que l'interface de
la Phase 6 tient sa promesse, et cette fois sans qu'on ait eu à l'aménager.
---
## 2. Ce qui a été écrit
`Wildlife` implémente désormais `CollisionSolver`, exactement comme `Forest` et
`EditorScene`.
- **Empreinte** : cylindre vertical, rayon `0,65 m` = **demi-longueur du mesh de
cervide** (`kAnimalLength / 2`), multiplié par `Animal::scale` ; bande
verticale `[sabots ; sabots + 1,05 m × échelle]`.
- **Géométrie** : celle de `Forest::resolve` — cercles dans le plan XZ,
recouvrement d'intervalles en Y, repoussement jusqu'au contact, 4 passes avec
sortie anticipée dès qu'une passe ne touche rien. **Aucun second modèle de
collision n'a été écrit** : le monde doit se cogner partout de la même façon,
sans quoi il y aurait deux comportements à régler, à tester et à garder
d'accord.
- **Le lien mesh ↔ collision est tenu par une assertion de COMPILATION.**
`WildlifeParams` ne peut pas inclure `AnimalMesh.hpp` sans traîner tout le
moteur derrière tout ce qui paramètre la faune, donc `0,65` y est écrit en
clair. Un `static_assert` dans `Wildlife.cpp` vérifie que cette valeur reste
la demi-longueur du mesh : le jour où le cervide changera de taille, ça
échouera à la compilation au lieu de le rendre traversable par le flanc.
### 2.1 Pourquoi le cylindre CONTENANT, et ce qu'il coûte
Même convention que l'empreinte des objets d'éditeur, et pour la même raison :
un collider plus petit que l'objet se traverse par les coins, ce qui est
exactement le défaut qu'on vient corriger.
**Contrepartie assumée, et elle est réelle** : de face, le cervide ne fait que
0,42 m de large ; son cylindre de 0,65 m est donc trop généreux d'une vingtaine
de centimètres de chaque côté. Un cylindre ne peut pas être juste dans les deux
sens, et l'erreur qui bloque un peu tôt est moins choquante que celle qui laisse
passer au travers d'un flanc.
### 2.2 Ce qui reste FAUX, et qui l'est volontairement
**Un animal, lui, traverse toujours les troncs, les rochers posés et ses
congénères.** Ce n'est pas un oubli : c'est le corollaire du « aucune IA » de la
Phase 17. La fuite est une ligne droite, sans évitement d'obstacle — un animal
qui buterait sur un tronc y resterait **collé**, faute de savoir le contourner,
et un cervide encastré dans un arbre serait plus laid que le problème résolu.
Le sens qui compte pour le joueur est celui qui a été traité.
### 2.3 Un animal n'est pas un tronc : il bouge
Deux conséquences, toutes deux assumées et toutes deux déjà couvertes par
`moveBody()` :
- un animal peut venir se poser **sur** un joueur immobile — le joueur ne bouge
pas, donc aucun `moveBody()` n'est appelé, donc rien ne l'écarte. Il sera
repoussé au premier pas : c'est le cas dégénéré que `moveBody()` traite déjà
en dernier recours pour « un arbre planté sur le joueur » ;
- la position « précédente » sur laquelle `moveBody()` se replie a pu devenir
occupée entre deux images. Le repli la teste avant de s'y poser, il n'y avait
donc rien de particulier à écrire.
---
## 3. LA MESURE : témoin négatif et chiffre prédit
Méthode de la Phase 15 : deux mondes **identiques à une option près**, même
graine, même semis, même animal à la même place. La seule différence est la
collision.
Le témoin est `WildlifeParams::solid = false`, exposé en jeu par la nouvelle
option **`--no-animal-collision`**. C'est le témoin qui compte, et
`--no-wildlife` ne pouvait pas le remplacer : supprimer les animaux ne montre
pas qu'on traverse celui qui est là.
Marche de 20 m, droit sur un cervide isolé, par le même `moveBody()` que la
caméra :
| | approche la plus proche | distance parcourue |
|---|---:|---:|
| Témoin, `--no-animal-collision` | **0,0010 m** (le centre de l'animal) | **20,00 m** |
| Avec collision | **1,0418 m** | 13,20 m |
Et **1,0418 m est le chiffre prédit** : rayon de collision de cet animal
(`0,65 × échelle`) + demi-largeur du joueur (`0,35`). Il est atteint **au
millimètre près**. C'est ce qui sépare « ça a l'air de bloquer » de « ça bloque
là où le modèle le dit ».
### 3.1 La première version de ce test avait tort, et la mesure l'a dit
Le test attendait un **arrêt net** à `10 − 1,0418 = 8,96 m`. Mesure : **13,20 m
parcourus**, et une sortie de l'autre côté de l'animal.
Ce n'est pas un défaut, c'est le **glissement** que le solveur par repoussement
produit exprès (`CollisionSolver.hpp` : « on longe un tronc au lieu de s'y
coller net »). Contre un obstacle convexe **isolé**, une poussée frontale n'est
jamais parfaitement frontale à l'arrondi près, et la composante latérale
accumulée finit par faire contourner l'animal — comme on contournerait un tronc.
La grandeur réellement **prédite par le modèle** n'est donc pas la distance
d'arrêt, c'est le **rayon de contact**. C'est elle qui est vérifiée. La leçon
est celle des phases précédentes, un cran plus loin : *un chiffre attendu qui ne
sort pas n'est pas forcément un bug — il faut d'abord savoir lequel des deux,
du code ou de l'attente, décrit le modèle.*
*(La toute première version échouait pour une raison encore différente et plus
bête : avec la population par défaut — 24 animaux espacés d'au moins 14 m — un
trajet de 20 m en croise parfois un SECOND, et la marche s'arrêtait sur
celui-là. La collision marchait ; c'est la distance prédite qui parlait du
mauvais animal. Le test sème désormais `maxAnimals = 1`.)*
### 3.2 Toutes les activités, pas seulement la marche
C'était une exigence explicite de la consigne. Réponse par activité :
- **Marche** (`Camera::resolveCollisions`) : mesurée ci-dessus.
- **Vélo** (`Bike::update`) : **mesuré à part**, et c'est le cas qui compte le
plus. Le vélo roule à 30 km/h, c'est-à-dire à la vitesse de **fuite** de
l'animal (8 m/s) : c'est la seule activité qui peut réellement rattraper un
cervide et lui rentrer dedans. À pied, on ne l'approche jamais — il part à
30 m. Résultat : le témoin passe à moins de 0,5 m du centre, le cycliste avec
collision reste au-delà du rayon de contact.
- **Escalade** (`Climber::update`) : concernée au **pied** de la paroi, jamais
dessus, et pour une raison de MODÈLE et non de code — `WildlifeParams::
maxSlope` (0,90) est inférieur à `ClimberParams::wallSlope` (1,00), donc
**aucun animal ne peut se tenir sur une pente assez raide pour être
grimpable**. C'est le même genre de rapport entre deux constantes réglées
séparément que la leçon de la Phase 17 (`noiseRadius` vs `spawnRadiusMin`),
sauf qu'ici le rapport est celui qu'on veut : une assertion le fige, pour
qu'on ne le perde pas en retouchant l'une des deux. Un second test vérifie la
bande verticale : un grimpeur à 2,4 m au-dessus des sabots n'est pas gêné.
- **Parapente** : **hors périmètre, inchangé, et cohérent avec la Phase 8**, qui
documente déjà « pas de collision avec les arbres pendant le vol ». Le
parapente ne consomme aucun `CollisionSolver` : lui en donner un serait une
phase à part (un vol qui se cogne demande de décider ce qu'est un crash). À
l'atterrissage, le joueur repasse en mode `Walk` et retrouve la collision
complète, faune comprise.
**Aucune de ces trois classes n'a été modifiée.** Elles reçoivent toutes le même
`worldSolver`.
---
## 4. DÉCISION : les objets au sol ne bloquent pas
`Ground` (bûches, branches, pierres, éclats) n'implémente pas `CollisionSolver`
et n'entre pas dans le solveur composite. **C'est une décision, pas un oubli**,
et elle repose sur trois faits mesurables :
1. **Ce sont des cibles de RAMASSAGE.** `Ground::findNearest` exige de s'en
approcher. Un collider solide ferait lutter le joueur contre la mécanique
même qui donne leur raison d'être à ces objets.
2. **Ils sont sous le genou.** Le plus haut est la pierre : `kStoneRadius` vaut
0,20 m, donc 0,40 m de haut posée. Un joueur enjambe ça ; le simuler
demanderait une gestion de marche/step-up qui n'existe pas dans le moteur.
3. **Un débitage en dépose 3 à 4 autour du joueur** (`Forest::scheduleBucking`).
Les rendre solides pourrait l'emmurer dans le bois qu'il vient de produire —
et le solveur n'a aucun moyen de l'en sortir, puisque `moveBody()` refuse
simplement le déplacement quand aucune position libre n'existe.
Le test headless fige cette décision plutôt que de la laisser au commentaire :
il pose une pierre et une bûche sur le trajet et vérifie que le passage reste
libre, en nommant la phase qui a tranché.
**Ce qui rendrait la décision fausse un jour** : un objet au sol nettement plus
gros (un rocher non ramassable, un tronc entier non débité). Le jour où
`GroundItemKind` en accueillera un, c'est un drapeau `solide` par nature d'objet
qu'il faudra — pas un collider pour toute la catégorie.
---
## 5. Vérification
### 5.1 Tests headless
**935 assertions** (902 avant la phase, **+33**), toutes passent, zéro
avertissement à `/W4`. Nouvelle section « Phase 20 : collision de la faune ».
Ce qu'elle couvre :
- le témoin négatif et le chiffre prédit (§3) ;
- cohérence `resolve` / `overlaps` : la sortie de `resolve()` est **libre**,
sans quoi `moveBody()` refuserait tout déplacement le long d'un animal au lieu
de laisser glisser (c'est la raison de la marge d'un millimètre, la même que
dans `Forest` et `EditorScene`) ;
- le cas dégénéré « joueur exactement sur l'axe de l'animal » : aucun NaN, écarté
au contact ;
- la bande verticale (grimpeur au-dessus, joueur au sol) ;
- le rayon suit `Animal::scale`, et le défaut est bien la demi-longueur du mesh ;
- le **solveur composite à trois sources** : le tronc bloque toujours (Phase 6),
le rocher posé bloque toujours (Phase 15), l'animal bloque désormais
(Phase 20), et le passage libre le reste ;
- la décision du §4 (objets au sol traversables) ;
- le vélo et l'invariant d'escalade (§3.2) ;
- l'option `--no-animal-collision` côté interface (`overlaps` faux, `resolve`
rend la position telle quelle).
### 5.2 Build
`tools\build.bat Debug` : configuration et compilation propres, aucun
avertissement neuf. Trois unités recompilées (`Wildlife.cpp`,
`TerrainStreamer.cpp`, `main.cpp`) et l'édition de liens.
### 5.3 Vulkan
Voir §6.
### 5.4 Synchronisation
**Pas de `VK_LAYER_VALIDATE_SYNC=1` cette fois, et c'est justifié plutôt
qu'omis** : cette phase ne touche **aucun objet Vulkan, aucun thread, aucune
barrière, aucun téléversement**. Les trois fichiers modifiés sont
`world/Wildlife.{hpp,cpp}` (géométrie pure, GLM seul) et le câblage dans
`main.cpp`. Le contrôle de synchronisation de la Phase 19 portait sur le chemin
de téléversement des tuiles, qui est rigoureusement inchangé. Le relancer aurait
produit un journal vide sans rien prouver de neuf — et la Phase 12 a établi
qu'un journal propre ne prouve rien tant qu'on n'a pas montré que l'outil
regarde au bon endroit.
---
## 6. Résultat du harnais `run_vulkan_check.ps1`
Joué **en entier** (scénarios A à I) sur le binaire final, puis le scénario B
rejoué seul.
**L'essentiel : zéro `[Validation]`, zéro `[ERROR]`** sur 5 510 lignes de
journal. Les 4 `[WARN]` sont les avertissements bénins habituels (pas de point
d'eau ni de faune sur certaines dalles) ; le harnais ne les compte pas comme des
erreurs.
### 6.1 Non-régression : les systèmes des Phases 15 à 19 sont intacts
| Vérification | Résultat |
|---|---|
| **Éditeur (G), collision des objets posés** | **0,28 m avec la scène contre 21,03 m sans (témoin)** — la mesure de la Phase 15 est reproduite à l'identique |
| Éditeur : posés / supprimés / annulations / F5 / F9 / rechargés en jeu normal | 3 / 1 / 1 / 3 / 3 / 3 objets dont 3 solides |
| Sélection sans viser (F3/F4) | 3 sélections pour 3 touches envoyées |
| **Faune (I), Phase 17** | 24 animaux, fréquentation 100 %, **4 animaux à portée au premier relevé → 1 au dernier** — la zone se vide toujours |
| Besoins (H), Phase 16 | 2 points d'eau détectés, boire au point d'eau `True`, **refus à 30 m `True`** (témoin) |
| Escalade (F), Phase 14 | sommet atteint, +41,6 m, pente 63 à 154 % |
| Parapente (D), Phase 8 | décollage et atterrissage naturel |
| Dalle LiDAR réelle (C), Phase 7 | chargée, arbre visé et abattu, 5 objets ramassés |
| Streaming / LOD, Phases 10-12 et 19 | aucune erreur, fermeture propre partout |
**Le point le plus important pour cette phase est la première ligne** : la
collision des objets d'éditeur, mesurée par témoin, rend exactement le même
chiffre qu'avant. Ajouter une source au `CompositeCollisionSolver` n'a rien
changé aux deux autres.
### 6.2 Les deux points rouges, et ce qu'ils sont
1. **Scénario E (vélo), « pied à terre » `False`.** Échec **antérieur à cette
phase**, documenté depuis la Phase 17 puis dans les NOTES des Phases 18 et
19, laissé non corrigé pour cause de périmètre. La Phase 20 ne l'a ni causé
ni aggravé : le reste du scénario E est vert (en selle `True`, 32,3 km/h en
descente, 11 relevés à l'arrêt en côte au-delà de 23,6 % de pente).
2. **Scénario B, code de sortie −1, « l'arbre 7 n'a pas été abattu ».** Celui-là
ne pouvait pas être classé sans vérification, parce que le scénario B **est**
le chemin de collision : c'est précisément ce que cette phase touche.
**Rejoué seul immédiatement après : vert** — code de sortie 0, fermeture
propre, « tronc debout PUIS souche poussés, sans erreur ni plantage », zéro
`[Validation]`. C'est la flakiness `PostMessage` déjà documentée dans
l'en-tête du script (scancodes, pas de vraie souris : cible d'abattage
manquée de peu ou `WM_CLOSE` lent), et le protocole du projet pour ce cas est
justement de rejouer. **Pas une régression.**
---
## 7. Options ajoutées
| Ajout | Rôle |
|---|---|
| `--no-animal-collision` | La faune reste **visible** mais redevient **traversable** : comportement exact d'avant la Phase 20. **Témoin de mesure**, au même titre que `--no-scene` pour l'éditeur. `--no-wildlife` ne peut pas le remplacer — supprimer les animaux ne montre pas qu'on traverse celui qui est là. |
| Journal `Faune : collision ACTIVE/DÉSACTIVÉE` | Une ligne au démarrage, qui dit laquelle des deux configurations tourne et avec quel rayon. Sans elle, un run de mesure ne peut pas prouver **après coup** de quel côté du témoin il était. |
---
## 8. Ce qui n'est pas fait
1. **La faune ne se cogne à rien.** Voir §2.2 : c'est le corollaire de l'absence
d'IA, et le lever demande un évitement d'obstacle, donc un vrai déplacement,
donc une session à part.
2. **Le cylindre reste faux de face** (§2.1). Un collider orienté (capsule
couchée le long du cap de l'animal) serait juste dans les deux sens — c'est
la même limite que celle notée en Phase 15 pour les objets à intérieur, et la
même réponse : un volume composé plutôt qu'un cylindre englobant.
3. **Aucune conséquence de gameplay au contact.** Bousculer un cervide ne le
fait pas fuir plus vite, ne blesse personne, ne coûte rien. La collision est
physique, pas narrative.
4. **Aucun scénario Vulkan dédié** (un « scénario J »). Le harnais ne pilote que
le clavier et la faune est **semée aléatoirement autour du joueur** : un
scénario reproductible demanderait de pouvoir poser un animal à une position
choisie, c'est-à-dire une entrée de débogage dans `Wildlife`. La preuve de
collision est donc **headless et déterministe** — ce qui est aussi le seul
endroit où le témoin négatif est rigoureux. Le harnais complet a servi à la
**non-régression**, pas à la mesure de cette phase.
5. **Pas de mesure de coût, et l'argument est structurel, pas mesuré.**
`resolve`/`overlaps` balaient au plus `maxAnimals` = 24 cylindres par appel
de déplacement, contre plusieurs centaines d'arbres pour `Forest` sur le même
chemin : le poste ajouté est plus petit d'un ordre de grandeur qu'un poste
déjà présent, et la Phase 19 a établi que l'image est **limitée par le GPU**
(81 % du temps passé à attendre dans `drawFrame`). Chiffrer ce poste
demanderait une instrumentation neuve pour mesurer une fraction d'un temps
d'attente. C'est une justification, pas une mesure : si la population de
faune devait un jour croître d'un ordre de grandeur, il faudrait le chiffrer
pour de bon.