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.

Les tâches :sanctuary:naturalHydrologySmoke et :sanctuary:starterLavaSmoke complètent ces contrôles pour l’alpha.5 : dépôts de trois à cinq couches sur support naturel, terrasses peu creusées, niches de source, parcours de cascade et petite réserve de lave avec accès sec. Elles vérifient le déterminisme et l’absence de remplissage de secours lorsque la géométrie ne convient pas.

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. Aucun plancher solide n’apparaît sous l’île, à Y=0..15. Dans la génération alpha.5, seules les eaux des cascades déclarées peuvent traverser cette marge.
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 : profils épais de sédiments, bassins retenus, raccords entre chunks, canne à sucre valide, niches rocheuses et descente réelle des cascades. Les cinq biomes et les minerais sont inspectés sur le terrain. Une réserve de lave présente conserve ses 18 sources, ses supports et son accès après simulation.
9. Les anciennes clés gardent leur traitement d’origine. Seuls les nouveaux paramètres activent les rives, biomes et sources de l’alpha.5.

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.

Pour l’alpha.5, les chunks de l’île sont maintenus actifs, puis le test attend ServerLevel.isPositionTickingWithEntitiesLoaded sur chaque chunk de fluide. Ce prédicat, réellement utilisé par le planificateur des ticks en 26.3, exige à la fois le statut de simulation et le chargement des entités. FULL et shouldTickBlocksAt seuls ne prouvent pas que les ticks programmés s’exécutent. Un témoin d’eau temporaire est vérifié dans chaque chunk de source et de lave, puis retiré entièrement. La simulation des sites dure 1 800 ticks après cette activation. La graine 0 doit notamment démontrer une cascade qui atteint Y=0.

Les fichiers natural-hydrology-seed-<graine>-generated.json/.png et natural-hydrology-seed-<graine>-after-1800-ticks.json/.png sont écrits dans mods/sanctuary/build/run/gameTest/diagnostics/, avec des profils PNG des cascades. Ils décrivent les sites, dépôts, fluides, biomes et ressources des chunks inspectés, ainsi que la graine et la version. Ce relevé de ressources reste local à ces chunks et ne représente pas le stock total de l’île.

Le diagnostic alpha.4 est conservé séparément, avec ses fichiers surface-hydrology-…-after-200-ticks et ses eaux entièrement retenues. Le nombre de blocs d’eau ne mesure pas un 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 général (neuf chunks ou île entière). Le diagnostic hydrologique garde ses propres comptes locaux. Les options 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.5 — 8 septembre 2026

Les essais utilisent Minecraft 26.3-pre-2, Java 25 et le preset de production sur des mondes neufs, sur Apple M1 à 8 Go. Le diagnostic attend les chunks réellement simulables avant de mesurer 1 800 ticks de fluides.

Les dix tests serveur réussissent sur chacune des graines 0, 42 et 8675309. La vérification finale check build assemblePack, avec les cartes de densité et le relevé général facultatifs désactivés, réussit en 3 min 11 s sur la graine 0. Les contrôles ciblés de ressources, de biomes et de fluides restent actifs. Les tâches de forme, d’hydrologie et de lave réussissent aussi.

Graine	Spawn naturel	Eau des bassins	Eau des cascades	Canne à sucre	Lave	Chunks FULL inspectés
0	(0, 252, 0)	1 930	1 649	52	18	189
42	(0, 249, 0)	1 859	1 058	25	18	177
8675309	(0, 247, 0)	1 830	3 960	16	18	195

Sur la graine 0, les trois sources partent de (-108, 227, -96), (-26, 203, -141) et (-82, 176, 141) et atteignent toutes Y=0. Les trois sources des graines 42 et 8675309 atteignent également Y=0. Les bassins conservent leur volume ; la niche de lave conserve 18 sources et son accès praticable, sans incendie détecté. Le cours d’eau reste continu à travers les frontières de chunks.

Les dépôts ont trois à cinq couches et deux supports naturels en dessous. La rive sèche la plus éloignée de l’eau atteint une distance de Manhattan de 20 blocs sur la graine 0, 28 sur la graine 42 et 27 sur la graine 8675309. Les cartes montrent des plages larges et asymétriques, des bandes de gravier et des interruptions par la roche ou l’herbe. Quelques petites poches restent anguleuses à l’échelle du bloc. Les profils montrent les cascades réelles ; ces lectures de blocs ne remplacent pas l’appréciation du relief et des couleurs dans le client.

Les cinq biomes sont vérifiés dans des chunks réels. Dans les 189 chunks inspectés de la graine 0, le relevé compte 754 minerais de charbon, 464 de fer, 197 de cuivre, 215 d’or, 210 de redstone, 23 de lapis et 14 de diamant. Ce sont des blocs présents, pas des rendements de minage ni un total pour l’île entière. Le bois, la pierre et les ressources renouvelables n’ont pas de plafond de construction ajouté. La progression complète et l’équilibrage coopératif restent à éprouver en partie.

Le calcul initial du plan hydrologique prend 23 623 ms dans la vérification finale de la graine 0 et 24 475 ms dans l’essai de la graine 42 ; la recherche de lave ajoute respectivement 1 075 ms et 1 568 ms. Le plan est mis en cache par état aléatoire de monde, sans charger de chunks voisins. Ces durées sont distinctes du chargement des chunks de diagnostic.

Le premier essai court a révélé un défaut du banc de test : un chunk FULL muni d’un ticket pouvait encore attendre ses entités et ne pas exécuter ses ticks de fluide. Le contrôle utilise désormais le prédicat exact du moteur et un témoin indépendant par chunk de source. Un autre essai a rencontré trois blocs de chêne couché vanilla au niveau supérieur d’un étang. Le diagnostic conserve cette décoration et distingue le volume d’eau prévu des sources restantes : seuls des troncs horizontaux de surface jouxtant une source, avec de l’eau dessous ou le fond peu profond plein, sont acceptés. Leur position et leur état exacts, l’appui ou l’eau sous le bois, les parois et le reste des sources sont vérifiés après simulation. Le contrôle de continuité du cours d’eau reste strict. Le dernier essai de la graine 8675309 conserve les 1 830 sources prévues sans tronc dans l’étang ; le décor vanilla peut varier avec l’ordre de génération des chunks, tandis que le plan Sanctuary reste identique.

Deux arbres sur des paliers de la troisième graine dévient aussi les cascades. Le trajet sur densité nue ne prévoit pas ces feuilles. Le diagnostic final compare cette prévision aux blocs réels, puis vérifie les composantes d’eau par connexions de face : toute composante hors bassin doit rejoindre une source déclarée. Aucune eau ne doit toucher un chunk horizontal non inspecté. L’emprise reste celle prévue initialement avec son halo d’un chunk, sans élargissement après observation des écoulements. Sur la graine 8675309, les trois composantes comptent 2 445, 1 152 et 363 blocs d’eau après simulation ; toutes rejoignent leur source et restent entièrement dans les chunks inspectés. Les anciennes classes et ressources de terrain et d’hydrologie sont également comparées octet par octet avec l’alpha.4.

Journaux : build/alpha5-build.log, build/alpha5-seed42-final.log et build/alpha5-seed8675309-provenance.log. Les exports JSON/PNG sont dans le dossier diagnostics décrit plus haut. Le dernier contrôle par composantes d’eau est exécuté sur les graines 8675309 et 0 ; l’essai réussi de la graine 42 utilisait encore le contrôle plus restrictif du trajet prévu sur densité nue. Le code de génération est identique entre ces essais.

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.