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.

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 quatre 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. Les trous dans l'ancien noyau restent vides, et chaque graine conserve du terrain dans l'échantillon de l'île.

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.1 » reconstitue l'ancienne formule du noyau et du bord en utilisant les bruits actuels ; elle ne reproduit pas exactement l'ancien bruit de bord. La colonne de droite est la densité actuelle.
• 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.

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.