sanctuary-beta/docs/testing.md

Vérifier Sanctuary

Utiliser Java 25 et les dépendances épinglées dans gradle.properties.

./gradlew check build assemblePack --console=plain

check inclut les tests GameTest. Pour un diagnostic ciblé de la génération seule, utiliser ./gradlew :sanctuary:runGameTest --console=plain.

Pour générer de vrais chunks et vérifier le spawn sur d'autres graines :

./gradlew :sanctuary:runGameTest -PsanctuaryTestSeed=42 --console=plain
./gradlew :sanctuary:runGameTest -PsanctuaryTestSeed=8675309 --console=plain

La propriété ne s'applique qu'au mod de test, jamais au mod distribué ni à une sauvegarde de joueur. Chaque commande repart d'un monde de développement neuf.

Tests de forme

La tâche :sanctuary:worldgenSmoke, incluse dans check, vérifie les invariants de l'enveloppe de l'île : absence de noyau imposé, conservation des trous naturels, sculpture du bord, limite extérieure, hauteur et stabilité de la fonction géométrique. Elle complète les tests en jeu ; elle ne charge pas à elle seule les ressources de génération de Minecraft.

La tâche :sanctuary:hydrologySmoke, également incluse dans check, vérifie le planificateur sur des reliefs contrôlés : reproductibilité, variation de la graine, limites de profondeur et d’excavation, support naturel, parois, ruisseau sur plateau compatible et partition indépendante de l’ordre des chunks. Les scénarios vides, percés ou trop minces ne reçoivent aucun bassin de secours.

Tests dans le moteur Minecraft

runGameTest démarre le serveur de test headless officiel de Fabric dans mods/sanctuary/build/run/gameTest/. La tâche cleanGameTestWorld supprime uniquement son monde jetable avant chaque exécution afin de générer des chunks neufs. Il ne déploie rien dans un serveur ou une installation de jeu personnels. La configuration garde eula=false : aucun fichier d'acceptation n'est écrit par Loom. Fabric dispose d'un chemin de démarrage propre à ses tests automatisés.

Le source set gametest est un mod de test séparé, exclu du JAR Sanctuary distribué. Deux adaptations y sont nécessaires, vérifiées contre les classes Minecraft 26.3-pre-2 :

• GameTestServer sélectionne normalement minecraft:flat_all_dimensions. Le mixin de test sélectionne directement le preset de production sanctuary:sanctuary, sans recopier ses JSON.
• Le framework désactive normalement les structures. Le test les active dans WorldOptions pour examiner les chunks après toutes les étapes de génération. La seed du serveur de test est 0 par défaut ; -PsanctuaryTestSeed est transmis à la propriété JVM sanctuary.test.seed utilisée uniquement dans ce mixin.

Le framework déplace aussi le spawn vers une grille de tests située loin du centre. Le test capture donc le spawn juste avant ce déplacement, après l'initialisation normale du monde, et examine les coordonnées absolues de l'île.

Les neuf tests Sanctuary vérifient :

1. Le vrai générateur Sanctuary est chargé et le spawn collectif repose sur une surface déjà présente dans la densité naturelle, avec un sol plein de 3×3 blocs et deux blocs libres et secs pour les graines de régression.
2. Douze chunks entièrement générés sont vides dans les quatre directions, juste après l'enveloppe de décoration puis à environ 512 et 4 096 blocs. Cela couvre notamment l'ancien retour automatique de l'archipel au loin.
3. La densité du datapack réellement chargé, compilée par RandomState, est reproductible pour la seed 0 et change pour la seed 8675309.
4. La densité compilée des graines 0, 42 et 8675309 ne crée aucune matière là où le terrain source est vide. Le relief supérieur reste celui de l'alpha.2 translaté de 64 blocs et le dessous varie avec le terrain et les bruits.
5. Le nouveau monde et son bruit utilisent bien 384 blocs, à partir de Y=0, tandis que les anciens paramètres restent à 256 blocs. Les nuages sont au-dessus de l'île, à Y=352,33.
6. Les chunks complets inspectés gardent une marge vide sous l'île, à Y=0..15.
7. Le relevé après génération compte exactement tous les états des blocs des chunks demandés, avec des totaux cohérents et une complétude explicite. Voir Expansion et ressources pour le mode complet facultatif.
8. Le plan hydrologique se retrouve dans les vrais chunks après décoration : eau retenue, fonds naturels sur trois blocs, parois continues, ouverture au ciel, raccords entre chunks et canne à sucre pouvant survivre. Après des mises à jour réelles de fluides, chaque bloc d’eau doit rester dans ce plan.
9. Les paramètres et le biome des anciennes sauvegardes n’activent ni le traitement hydrologique ni la nouvelle décoration des berges.

La recherche de spawn parcourt l'île finie, par anneaux de quatre blocs jusqu'à 288 blocs du centre. Elle examine d'abord la hauteur brute pour éviter de générer entièrement les colonnes vides, puis vérifie le sol et les dégagements après décoration. Elle préfère une zone naturelle de 3×3 ; si aucune n'est trouvée, elle utilise le premier emplacement naturel sûr d'une colonne avec deux blocs libres. Elle ne pose aucun bloc. Une graine pathologique sans emplacement sûr échantillonné produit une erreur explicite, sans plate-forme de secours.

Le passage avec la graine de serveur 0 produit aussi, pour les trois graines, des PNG et CSV dans mods/sanctuary/build/run/gameTest/diagnostics/ :

• island-density-seed-<graine>.png : vue de dessus et coupes centrales X/Z, avant/après, calculées avec les fonctions de densité réellement compilées. La colonne « alpha.2 » utilise ses anciennes ressources conservées ; la colonne de droite utilise la densité alpha.3, sur toute la hauteur Y=0..383.
• island-heightmap-seed-<graine>.csv : coordonnées et hauteurs échantillonnées des deux versions (-1 indique une colonne vide dans cet échantillon).

La vue de dessus échantillonne tous les quatre blocs en X, Y et Z. Les coupes échantillonnent tous les deux blocs horizontalement et chaque bloc en hauteur. Ces diagnostics montrent les volumes ; ils n'affichent pas les arbres, matériaux, fluides ou structures et ne remplacent pas un essai visuel dans le client.

Le chargement du serveur valide également les codecs et les références des registres de biomes, densités, réglages et presets. Un échec de chargement ou un test obligatoire en échec doit faire échouer la tâche Gradle.

Le framework et les hooks de test sont spécifiques à la version épinglée. Lors d'une mise à jour Minecraft, vérifier ces hooks avant de conclure que les tests exercent toujours le preset de production. La vérification explicite du générateur dans le premier test empêche un résultat positif sur un simple monde plat.

Référence du workflow : tests automatiques Fabric. Les signatures propres à 26.3-pre-2 ont été vérifiées dans les dépendances locales, car la documentation publiée vise actuellement 26.2.

Diagnostic hydrologique

Les essais hydrologiques demandent les chunks contenant tous les sites du plan et un halo d’un chunk. Ils inspectent des chunks FULL, avec minerais, arbres et plantes déjà générés, et comparent tous les blocs d’eau observés au volume annoncé. Leur carte montre les vrais blocs de surface ; le feuillage et les troncs sont masqués pour lire les berges. Il ne s’agit pas d’une capture du jeu.

Les chunks de l’île sont maintenus actifs pendant le test. Chaque position d’eau doit être dans un chunk où les blocs sont effectivement simulés. Un petit témoin d’eau temporaire, enfermé en hauteur dans un de ces mêmes chunks, doit réellement couler ; il est ensuite entièrement retiré. Les sources des sites reçoivent elles aussi des ticks, puis la rétention est revérifiée au tick 200. Attendre près de la grille éloignée du framework ne remplacerait pas ce contrôle.

Les fichiers surface-hydrology-seed-<graine>-generated.json/.png et surface-hydrology-seed-<graine>-after-200-ticks.json/.png sont écrits dans mods/sanctuary/build/run/gameTest/diagnostics/. Ils décrivent les sites et leur nature, leurs coordonnées, le volume d’eau réel, la canne à sucre, les raccords entre chunks, les berges et les bornes inspectées. Le nombre de blocs d’eau n’est pas une mesure de débit. Un résultat sans site STREAM ne valide pas une rivière, même s’il contient des lacs.

Pour itérer sur l’eau sans recalculer les trois grandes cartes de densité :

./gradlew :sanctuary:runGameTest -PsanctuaryDensityMaps=false -PsanctuaryResourceSurvey=off --console=plain

Ces options désactivent seulement les exports de densité et le relevé de ressources. Elles gardent les assertions de densité et tous les tests de comportement, y compris les cartes et contrôles hydrologiques. Le parcours standard conserve les exports complets de densité pour la graine 0.

Vérification client facultative

./gradlew :sanctuary:runClientGameTest -PsanctuaryClientTests=true --console=plain

Ce test charge les vrais SkyRenderer et FogRenderer et vérifie l'application des deux mixins, puis ferme automatiquement le client sans ouvrir de sauvegarde. Il nécessite un environnement graphique ; check ne le lance pas. Ses sources dans src/clientGametest/java ne sont ajoutées au mod de test que lorsque la propriété est activée. Le test de transformation ne remplace pas l'essai visuel de l'horizon dans un nouveau monde Sanctuary.

Pour cet essai visuel en monde de développement créatif, comparer la même vue à Y=70, 62, 32, 8 puis −8. Il ne doit apparaître ni disque noir au passage de Y=63 ni assombrissement d'altitude au passage de Y=32. Les brouillards de l'eau, de la météo et des effets d'aveuglement ou d'obscurité doivent rester présents.

Validation alpha.4 — 8 septembre 2026

Les tests serveur utilisent le preset de production et des mondes neufs. Sur la graine 0, le scénario exige un véritable site STREAM ; les autres graines vérifient la continuité de chaque cours d’eau qu’elles produisent, sans exiger qu’une graine arbitraire soit artificiellement complétée.

Graine	Spawn naturel	Eau après 200 ticks	Canne à sucre	Chunks FULL inspectés	Raccords d’eau aux frontières
0	(0, 251, -4)	1 938	15	94	253
42	(-4, 249, -4)	1 501	24	94	213
8675309	(0, 247, 0)	1 551	12	90	190

Pour la graine 0, le cours d’eau est à Y=250, de X=−48, Z=48 à X=−20, Z=−20. Son chemin suit 18 points et relie deux petites poches d’eau. Deux petits lacs et quatre étangs sont également présents, en comptant la poche de départ du cours d’eau. La graine 42 produit elle aussi un cours d’eau, à Y=221, de (−72, 24) à (−60, −40) en X/Z. Ce sont des observations de ces graines, pas un minimum promis pour toutes les îles.

10/10 tests requis réussissent sur chacune des trois graines, avec un cours d’eau observé sur chacune. Les contrôles comparent chaque bloc d’eau avant et après une simulation réelle confirmée par un témoin d’écoulement et l’activité de tous les chunks concernés. Les quantités d’eau restent identiques. Les cartes des vrais blocs ont été inspectées : les lacs sont arrondis et les chenaux restent continus. Le tracé des cours d’eau comporte encore des segments géométriques ; l’appréciation du relief, des berges et de leur aspect dans le client reste à faire par le joueur. Les cartes masquent la canopée et ne remplacent pas une vue en jeu.

Le plan initial prend 12 060 ms pour la graine 0 et 8 743 ms pour 42 et 9 755 ms pour 8675309, sur le poste Apple M1 à 8 Go utilisé pendant ces essais. Il est calculé une seule fois par état aléatoire de monde, sans charger les chunks voisins. La préparation des 94 chunks FULL de chaque diagnostic est distincte du calcul du plan et ne représente pas le travail requis à chaque lancement de partie.

Les trois exécutions serveur réussies ont été suivies de ./gradlew check build assemblePack -x :sanctuary:runGameTest : le serveur déjà validé séparément n’est pas relancé à l’identique. Les tests de forme et d’hydrologie pure, la compilation et l’assemblage du pack réussissent en 2 s. Le JAR ne contient aucune classe de test, et le .mrpack contient exactement ce même JAR, avec les versions Minecraft et Fabric attendues.

Journaux : build/alpha4-hydrology-v2-seed0.log et build/alpha4-validation-seed42.log, build/alpha4-validation-seed8675309.log et build/alpha4-build.log. Les exports correspondants sont dans le dossier diagnostics décrit plus haut. Les cartes de densité, inchangées par l’hydrologie, ont été exportées lors des premières exécutions de ce ticket ; les assertions de densité restent actives pendant chaque validation.

Validation alpha.3 — 8 septembre 2026

Sur Java 25 / Minecraft 26.3-pre-2 / Fabric Loader 0.19.5 :

Vérification	Résultat
check build assemblePack avec relevé complet, graine 0	8/8 tests requis réussis ; 14 min 49 s, dont le relevé complet
Serveur neuf, graine 42	8/8 réussis ; 1 min 3 s
Serveur neuf, graine 8675309	8/8 réussis ; 1 min 4 s
Test client facultatif	Réussi en 23 s ; les deux injections de rendu sont appliquées

La graine 0 place le spawn naturel en (0, 251, -4) ; la graine 42 en (0, 249, 0) et la graine 8675309 en (0, 247, 0). Les tests confirment les 384 blocs du nouveau monde, les nuages relevés, le vide inférieur et extérieur et la conservation des anciens réglages. Les coupes des trois graines ont été inspectées : l'ancienne silhouette est relevée et le dessous devient irrégulier. Une comparaison supplémentaire de 1 039 155 échantillons de l'ancienne géométrie refactorée donne des densités identiques bit à bit à l'alpha.2.

Le relevé complet constate 8 584 514 blocs non vides dans les 1 444 chunks de l'enveloppe définie. Sa préparation prend 13 min 2,659 s, son comptage et sa préparation JSON 135 ms, sur un Apple M1 avec 8 Go de mémoire. Ce poste exécute d'autres applications et a aussi exécuté le test client pendant le relevé : c'est une mesure locale, pas une promesse de performance. Les quantités exactes et les exclusions figurent dans la référence de ressources.

Les journaux sont build/alpha3-validation-seed0.log, build/alpha3-validation-seed42.log, build/alpha3-validation-seed8675309.log et build/alpha3-client-test.log. Le JAR alpha.3 a été inspecté : aucune classe de test n'est distribuée. Le .mrpack contient exactement le JAR vérifié.

Le test client valide le chargement et l'application des mixins. Il n'ouvre aucun monde et ne remplace donc pas l'essai visuel en vol décrit plus haut.

Historique : validation alpha.2 — 8 septembre 2026

Commande ./gradlew check build assemblePack --console=plain réussie en 1 min 10 s sur Java 25, Minecraft 26.3-pre-2, Fabric Loader 0.19.5, Fabric API 0.160.0+26.3 et Loom 1.17.20, pour Sanctuary 0.1.0-alpha.2. Les deux commandes supplémentaires de graines ont ensuite été exécutées séquentiellement, chacune sur un monde de développement neuf.

Graine	Spawn naturel initial	Tests requis	Durée des tests	Durée Gradle
0	(-4, 187, -4)	5/5 réussis	51,40 s, diagnostics compris	1 min 10 s, build et pack compris
42	(0, 185, 0)	5/5 réussis	1,843 s	20 s
8675309	(0, 183, 0)	5/5 réussis	1,681 s	17 s

Les cinq tests requis comprennent les quatre tests Sanctuary et le test du framework. Pour chacune des trois graines, le spawn possède naturellement une zone sèche de 3×3 avec deux blocs libres ; les douze chunks extérieurs inspectés au statut FULL sont vides. Aucun repli sur une colonne seule n'a été nécessaire.

• Les invariants WorldgenSmoke, le chargement des codecs et registres, la reproductibilité des densités et l'absence de matière ajoutée par la sculpture ont été vérifiés.
• Les trois diagnostics PNG et CSV ont été produits avec la densité actuelle. Leur calcul synchrone explique la durée plus longue du test de graine 0 et son avertissement serveur « Can't keep up » ; ce diagnostic est absent du mod distribué.
• La compilation du JAR, l'assemblage dans build/packwiz/ et la vérification des versions et empreintes du pack ont réussi.
• Le JAR mods/sanctuary/build/libs/sanctuary-0.1.0-alpha.2.jar ne contient aucune classe ni configuration de mixin GameTest.

Les journaux de cette validation sont conservés localement dans build/alpha2-validation-seed0.log, build/alpha2-validation-seed42.log et build/alpha2-validation-seed8675309.log. Les journaux courants de Minecraft sont dans mods/sanctuary/build/run/gameTest/logs/ et sont remplacés au prochain test. Ces preuves et les diagnostics restent ignorés par Git. Les vérifications manuelles ci-dessous restent à effectuer ; les tests n'ont ouvert ni modifié aucune sauvegarde de joueur.

La fondation alpha.1 avait été validée le même jour sur la graine 0, avec un spawn (0, 118, 0) reposant sur l'ancien noyau imposé. Ce résultat historique ne décrit plus la génération alpha.2.

Vérifications manuelles restantes

• Créer un monde avec le preset Sanctuary dans le client et évaluer visuellement la côte, les trous, les surplombs, la végétation et la lecture du vide.
• Rejoindre à plusieurs joueurs, mourir et réapparaître ; les tests headless ne simulent pas de connexion client ni les offsets de réapparition des joueurs.
• Modifier le spawn administrateur, arrêter puis recharger le monde et vérifier sa conservation. Le test automatique couvre le premier démarrage, pas un cycle de sauvegarde et de redémarrage complet.
• Explorer plusieurs seeds dans le client. Les tests compilent trois seeds et chaque invocation génère des chunks complets pour la seed demandée ; leur échantillonnage extérieur ne constitue pas une inspection exhaustive de toutes les coordonnées.
• Tester les resource packs, shaders et mods communautaires après leur ajout et vérification de compatibilité avec la version exacte du pack.