Prefer native Vulkan and stabilize PBR lighting in beta.142

docs/pbr-refresh-beta142.md

@@ -0,0 +1,154 @@
+# PBR-142 — Stabilité du relief et Vulkan par défaut
+
+Socle beta.141 `7ce01c4`, branche `codex/pbr-refresh-beta142`.
+Minecraft 26.3 / Java 25. Livraison beta.142.
+
+## Contrat
+
+Corriger le clignotement lors de la reconstruction des sections PBR : conserver
+le rendu précédent jusqu'à ce que le remplaçant soit disponible et éviter les
+reconstructions dues seulement aux lumières dynamiques. Une invalidation pendant
+une reconstruction doit être conservée, sans annuler indéfiniment le travail.
+Le PBR passe à 80 % par défaut, valeur confirmée par l'utilisateur ; les choix
+explicitement enregistrés restent conservés.
+
+La capture `2026-09-18_04.19.34.png` montre des points très clairs, plus fins
+que les pixels des textures, sur des parois et un plafond de grotte. L'utilisateur
+confirme OpenGL et leur disparition quand seul le PBR est coupé. Examiner
+les lectures de textures et les calculs aux angles rasants séparément du cache.
+
+Tests natifs prévus : recalcul de section sous observation, invalidations
+répétées, remplacement atomique, suppression réelle de blocs, lumière portée,
+cache et préférences ; OpenGL et Vulkan. Pas de monde personnel ouvert.
+
+## Précision du signalement et implémentation
+
+L'utilisateur précise ensuite que le bruit apparaît **en mouvement**, et demande
+le passage à Vulkan. Il ne faut donc pas attribuer les points de sa capture au
+seul clignotement de reconstruction : ce sont deux vérifications distinctes.
+
+- Les sections PBR publiées restent affichées jusqu'au remplacement de leur
+  maillage. Une nouvelle invalidation durant la construction est mémorisée ;
+  elle n'annule plus continuellement le travail. Le budget permanent reste
+  24 Mio, avec temporairement l'ancien et le nouveau maillage d'une section.
+- Les invalidations de lumière dynamique ne régénèrent plus la géométrie PBR.
+  Les changements de blocs et de lumière du ciel restent pris en compte.
+- Lectures explicites des texels de profondeur/scène et du niveau de matériau,
+  gradients de texture calculés avant les rejets de fragments. Les produits
+  scalaires des reflets sont bornés, la puissance entière de Fresnel est
+  explicite, les résultats non finis ne remplacent pas la scène native.
+  Aucun flou ajouté aux textures.
+- Le choix graphique natif « Par défaut » devient « Vulkan (par défaut) »
+  (FR/EN) et essaie Vulkan en premier. Minecraft conserve son repli OpenGL si
+  Vulkan ne peut pas être initialisé. Un choix **OpenGL explicite** reste
+  disponible ; pour une installation ainsi réglée, sélectionner Vulkan dans
+  les réglages vidéo puis redémarrer. Aucun moteur externe ni VulkanMod ajouté.
+- 80 % est la nouvelle intensité PBR initiale. Les valeurs déjà enregistrées
+  explicitement restent conservées.
+
+Le code Minecraft 26.3 a été inspecté : `PreferredGraphicsApi.VULKAN` essaie
+Vulkan puis OpenGL ; le choix natif `DEFAULT` essayait auparavant OpenGL d'abord.
+Tous les effets Sanctuary utilisent déjà l'API graphique native. Le seul hook
+OpenGL direct est le correctif spécifique de lecture des panoramas dans
+`GlCommandEncoder` ; il ne remplace pas la voie Vulkan native.
+
+Référence pour les lectures après contrôle divergent :
+[documentation Khronos des samplers](https://wikis.khronos.org/opengl/Sampler_%28GLSL%29).
+La correction rend ces lectures explicites ; elle ne constitue pas à elle seule
+une reproduction du défaut sur le pilote Windows de l'utilisateur.
+
+## Observations de diagnostic
+
+Le détecteur de points blancs isolés (minimum RGB 170, au moins cinq voisins
+sur huit sous 120) compte 669 points sur l'image utilisateur et zéro sur la
+première grotte de contrôle. Il s'agit de scènes, résolutions et pilotes différents,
+pas d'un avant/après reproduisant exactement le bug utilisateur. Les rendus
+natifs OpenGL de contrôle étaient déjà exempts de ce grain avant les nouvelles
+protections du shader ; le signalement Windows reste donc à reconfirmer là-bas.
+
+Le test de rafraîchissement conserve les mêmes maillages publiés durant douze
+invalidations consécutives, compare l'image et vérifie que des remplacements
+aboutissent. Le test de torche alterne quatre fois les torches normales/des âmes
+sans reconstruction des normales. Le contrôle de mouvement presse réellement
+Avancer, maintient la torche et le PBR actifs et vérifie un déplacement d'au moins
+un bloc avant de vérifier les 24 captures. Les angles -30°, 0° et 35° sont aussi
+contrôlés, ainsi que les effets combinés et les préférences.
+
+### Domaine invalide du reflet de la torche en main
+
+Pour la lumière du joueur en vue subjective, la source est la caméra : le
+vecteur lumière et le vecteur de vue sont parallèles. L'ancien
+`pow(1 - max(dot(v,h),0),5)` n'avait aucune borne supérieure pour ce produit
+scalaire. Un calcul reproductible Float32 (100 000 positions, graine 142)
+donne 19 991 bases légèrement négatives, jusqu'à -2,3841858e-7, contre zéro
+après clamp. C'est une reproduction numérique d'un **domaine de calcul invalide**,
+pas une reproduction des pixels produits par le pilote utilisateur.
+
+GLSL 3.30 ne définit pas `pow` pour une base négative, même avec un exposant
+entier : [spécification Khronos, fonctions exponentielles](https://registry.khronos.org/OpenGL/specs/gl/GLSLangSpec.3.30.pdf).
+Le correctif borne les cosinus à [0,1] et remplace cette puissance par des
+multiplications. La torche alignée sur la caméra ne dépend donc plus du traitement
+de cette entrée invalide par le pilote. Reçu numérique ignoré :
+`build/pbr142-fresnel-domain.json`.
+
+### Mise à jour des fixtures antérieures
+
+La suite Vulkan complète s'est arrêtée au contrôle SSGI de coin : l'oracle
+ne trouvait plus de pierre neutre (`rows=0`), car les lumières colorées ajoutées
+depuis beta.139/140 teintaient la pierre avec la lave. Le test de proximité SSGI
+et le test PBR solaire isolent désormais leur effet en coupant cette autre passe.
+Aucun seuil n'a été diminué et aucun changement de rendu SSGI n'est livré.
+Le sous-ensemble en échec est relancé séparément ; les étapes précédentes
+(ombres, CTM, bloom, lens flare, déplacement SSGI) avaient réussi.
+
+## Vérifications natives
+
+Sur Mac Apple M1, Java 25 et Minecraft 26.3 :
+
+- OpenGL : suite couleurs/directions/rafraîchissement en 3 min 36 s, puis
+  déplacement continu avec torche active en 1 min 36 s. Zéro point blanc isolé
+  sur les 24 images de mouvement et les trois angles de grotte.
+- Vulkan/MoltenVK 1.4.2 : sélection automatique sans argument de moteur,
+  couleurs/directions/rafraîchissement en 3 min 47 s. Dernier test continu avec
+  torche active en 1 min 37 s, zéro point blanc isolé sur les 24 images.
+- Ombrages lune/midi/feuilles, distances et précisions, stabilité temps réel,
+  CTM, bloom (minerais, torche, lampe, lave, soleil), émissifs indépendants et
+  lens flare validés sous Vulkan dans la suite d'effets. Le déplacement SSGI
+  sur douze blocs passe également. La suite s'arrête ensuite sur l'oracle
+  ancien de couleur de pierre décrit ci-dessus : ne pas présenter ce lancement
+  de 7 min 15 s comme une réussite complète.
+- Reprise ciblée après isolation de cet oracle : SSGI près des surfaces puis
+  PBR extérieur réussis sous Vulkan en 2 min 55 s. Proximité 35/100, haute
+  résolution, léger mouvement, toit ajouté/retiré, reload, resize, zéro/OFF et
+  effets combinés. Gain SSGI au coin test : 6,01 sur 99 lignes à 35 %.
+- Les nouvelles valeurs initiales et les choix enregistrés sont testés, dont
+  une intensité PBR explicitement enregistrée à 50 qui reste à 50.
+
+Les premiers essais du nouveau contrôle de mouvement ont permis de corriger
+son entrée clavier : `pressKey` ne maintient pas une touche enfoncée. Le test
+final utilise `holdKey` puis `releaseKey`, vérifie le déplacement réel et refuse
+la disparition de la lumière portée ou du PBR pendant les captures.
+
+Les jeux de test utilisent uniquement des mondes neufs et ignorés. La capture
+et le pilote Windows utilisateur n'ont pas été reproduits à l'identique ; leur
+retest reste ouvert malgré les corrections numériques et les contrôles natifs.
+
+## Construction et archives
+
+`./gradlew check build assemblePack assembleTestPack -x :sanctuary:runGameTest`
+réussit en **2 min 38 s**, 126 tâches. Le GameTest serveur dédié reste exclu
+selon le refus EULA antérieur ; les suites clientes ci-dessus ont réellement
+utilisé les deux moteurs natifs. `git diff --check` passe.
+
+Les archives normale/Test embarquent le même JAR, leurs versions/index/hashes
+sont vérifiés, leurs sources correspondent aux fichiers courants. Le template
+contient exactement les ressources attendues. Les onze entrées de production
+modifiées par rapport à beta.141 sont limitées au PBR, au choix graphique et
+aux traductions ; les ressources de jeu antérieures sont conservées.
+
+SHA-256 du JAR : `0bc2da9df2ef004e6dc78932cfde7b31b7717c63c83ceed789d151177c41bc1a`.
+
+- `Sanctuary-beta.142.mrpack` : 10464746 octets ; SHA-256 `dba4fd8e1e3b20136faa1c1de3494df3cb250c87de199c04e07883c786ca48ee`.
+- `Sanctuary-Test-beta.142.mrpack` : 10483672 octets ; SHA-256 `d56b81a4aea6649a40a3c49dedee904989943a518ad0ae7c520b808dd0f9b9a7`.
+
+Reçu détaillé ignoré : `build/shader142-artifact.json`.