sanctuary-beta/docs/worldgen.md

Premier monde Sanctuary

Le preset sanctuary:sanctuary crée l'île principale à l'origine de l'Overworld, entourée de vide sans répétition d'îles à grande distance. C'est une première tranche de génération pour Minecraft 26.3-pre-2 / Fabric, pas encore le système d'expansion collective.

Créer un monde

En solo : créer un nouveau monde et choisir le type de monde Sanctuary dans les options de génération. Les types de monde vanilla restent disponibles.

Sur un nouveau serveur Fabric disposant du mod et de Fabric API :

level-type=sanctuary:sanctuary
level-name=sanctuary
level-seed=0

La seed est libre. Modifier level-type ne convertit pas un monde existant : utiliser un nouveau level-name pour tester une autre génération. Les fichiers de test et les sauvegardes personnelles doivent rester distincts.

Ce qui est généré

• Le générateur reste celui de Minecraft, minecraft:noise.
• La forme reprend le champ de bruit flottant actif en 26.2 : old_blended_noise avec xz_scale=0.25, y_scale=0.25, xz_factor=80, y_factor=160, smear=4, ainsi que son gradient supérieur. Il est échantillonné 64 blocs plus bas pour relever l'île entière de 64 blocs. Reliefs, surplombs, trous et fragments dépendent de la seed Minecraft. L'ancien gradient inférieur uniforme est remplacé par la sculpture irrégulière décrite ci-dessous.
• Le terrain naturel reste libre de laisser un trou à l'origine, de former des surplombs ou de se séparer en fragments. Aucun noyau ellipsoïdal, cylindre ou plateforme de départ n'est ajouté. Au-dessus de Y=144, le relief de la génération précédente est conservé, simplement relevé de 64 blocs.
• Le pourtour est sculpté par retrait de matière à partir du rayon 128 blocs. Le contour de référence de 256 blocs est déformé par les bruits, entre 204 et 288 blocs ; il indique la fin de l'érosion, pas un mur de roche. La côte réelle apparaît plus tôt, selon la densité du terrain et la seed. Il reste du vide permanent au-delà de 288 blocs, sans répétition d'îles. Les arbres peuvent dépasser la côte rocheuse de quelques blocs.
• Les nouveaux mondes utilisent 384 blocs de hauteur, de Y=0 à Y=383, pour la dimension et le générateur. La roche disparaît avant leurs limites. Il n'y a ni plancher de bedrock, ni mer globale, ni reprise du terrain à distance. Le Nether et l'End restent ceux de Minecraft.
• sanctuary:starter_forest reprend végétation, minerais et animaux de la forêt vanilla 26.3. Ses blocs sont exclusivement vanilla. C'est un biome distinct pour ne pas hériter des tags de structures vanilla et de leurs apparitions possibles dans le vide.
• Les carvers, géodes, donjons, lacs de lave et sources sont retirés de cette forêt initiale. Les minerais remplacent la roche existante et les arbres ont besoin de sol. Aucun mod de biomes externe n'est nécessaire.

Ce premier prototype ne fournit pas encore d'eau : hydrologie, répartition complète des ressources de survie et variété de biomes constituent le prochain ticket de terrain. Les minerais vanilla conservent leurs plages d'altitude ; leur abondance n'est donc pas encore équilibrée pour une île flottante.

Sculpture du pourtour — conservée depuis la génération v2

La version 0.1.0-alpha.2 retire deux contraintes de la génération v1 (0.1.0-alpha.1) : le noyau central qui remplissait les creux du bruit naturel, et la découpe radiale qui pouvait exposer une tranche verticale à toutes les altitudes. Les identifiants sanctuary:* du preset et de la fonction restent stables. Il s'agit d'une évolution du terrain, pas d'une migration de sauvegarde.

Trois passes composent désormais la densité finale, après l'interpolation du champ historique :

1. Un bruit horizontal à grande échelle déforme le contour. Dans la bande extérieure, large de 128 blocs avant déformation, une érosion progressive (2 × t⁴) augmente le seuil nécessaire pour conserver de la roche. Une érosion supplémentaire, quadratique selon la hauteur et nulle à l'intérieur, fait reculer les faces hautes et basses même lorsque le bruit naturel est saturé dans une grande masse pleine. Elle arrondit le pourtour sans ajouter de volume au centre.
2. Un bruit 3D, échantillonné à la hauteur réelle, déplace ce contour et creuse des renfoncements plus larges. Le bord peut ainsi changer de position avec l'altitude au lieu de prolonger une ligne verticale.
3. Un second bruit 3D, plus fin, ajoute de petites irrégularités. Ces deux passes s'atténuent progressivement vers l'intérieur ; elles ne remplissent jamais un trou du terrain initial.

Les bruits island_edge, island_sculpt et island_detail sont tous initialisés avec la seed du monde. Ils utilisent respectivement les octaves de base -7, -5 et -3. Les nouvelles entrées sculpt et detail du codec sont optionnelles pour garder les anciennes définitions JSON lisibles ; leur absence ne rétablit pas le noyau de la génération v1.

L'érosion est toujours soustraite à la densité bornée du terrain. Une densité nulle ou négative ne peut donc jamais devenir solide. Même avec un terrain d'entrée maximalement positif, elle est négative dès le rayon 280, avant la limite de sécurité 288. Deux transitions verticales douces protègent aussi les bornes de hauteur, sans découper de dalle à Y=0 ou Y=256.

Ces formules sont toujours utilisées par les sauvegardes de la génération v2. La génération v3 conserve la sculpture latérale dans le repère de l'île relevée.

Île relevée et dessous irrégulier — génération v3

La version 0.1.0-alpha.3 crée les nouveaux mondes avec les paramètres et le type de dimension sanctuary:sanctuary_384 : min_y=0, height=384 et logical_height=384. Le nom du preset sélectionné reste sanctuary:sanctuary. Le gain de hauteur n'agrandit pas le rayon horizontal et n'active aucun continent.

Le bruit naturel et les bruits de sculpture sont échantillonnés à Y−64. Le profil supérieur et les bords approuvés en alpha.2 sont ainsi relevés sans changer de seed ou étirer l'île. Sur les graines de régression, les sommets proches de Y=184 se retrouvent vers Y=248, avec de l'espace libre au-dessus.

Sous l'île, déplacer l'ancien gradient inférieur aurait seulement déplacé son plan de coupe. floating_archipelago_384 conserve donc le bruit naturel sans ce gradient inférieur. Une nouvelle érosion travaille sur une transition de 72 blocs, dont l'altitude varie avec le bruit 3D island_underside et les deux bruits de sculpture existants. Elle laisse les lobes naturels se poursuivre vers le bas, puis les amincit à différentes hauteurs ; elle n'ajoute ni socle ni surface garantie. La transition n'affecte plus le terrain à partir de Y=144. Une marge vide protège le bas de la dimension ; le contrôle des chunks terminés vérifie que la tranche Y=0..15 ne contient aucun bloc.

Les champs optionnels du codec vertical_offset, height et underside valent respectivement 0, 256 et un bruit nul par défaut. Seule la nouvelle fonction sanctuary:final_density_384 active l'offset 64, la hauteur 384 et le bruit du dessous. Les anciennes fonctions final_density, floating_archipelago et les paramètres sanctuary:sanctuary restent inchangés : les sauvegardes alpha.2 qui les référencent gardent leur hauteur de génération et leur ancien terrain.

Créer un nouveau monde pour tester l'île relevée. L'actualisation du pack ne convertit pas les sauvegardes existantes ; aucun chunk n'est supprimé, déplacé ou régénéré. Il n'existe pas de migration automatique des anciens mondes vers la dimension de 384 blocs. Changer manuellement leurs références de générateur ou de dimension sort de ce contrat de compatibilité.

Apparition commune

Une injection limitée à la création initiale cherche du sol naturel depuis l'origine vers l'extérieur, dans toute l'emprise finie de l'île. Elle préfère une surface stable de 3 × 3 blocs, avec deux blocs libres en hauteur. En l'absence d'une telle surface, elle retient une colonne de sol praticable ; si aucun emplacement naturel sûr n'existe, la création signale la seed concernée plutôt que d'ajouter une plateforme. Elle ne s'applique qu'à l'Overworld utilisant les paramètres sanctuary:sanctuary. Elle enregistre le spawn partagé dans la sauvegarde et ne le réinitialise pas au redémarrage : les modifications administratives de /setworldspawn restent conservées. Les lits et la dispersion habituelle du spawn suivent encore les règles de Minecraft.

Adaptation 26.2 → 26.3

Les références historiques sont sanctuary/worldgen/density_function/base_3d_noise.json et floating_archipelago.json dans l'ancien module Sanctuary. L'ancien masque annulaire n'est pas conservé : après son anneau de vide, il faisait réapparaître un archipel infini. Les anciennes surcharges de minecraft:normal, dimensions supplémentaires, intégrations TerraMix et injections globales de features ne font pas partie de ce port.

Minecraft 26.3 a changé l'API de génération : les fonctions de densité compilent maintenant un DensitySampler, leurs opérateurs JSON utilisent left / right / input, les gradients utilisent from_coordinate et les surfaces passent par le registre worldgen/material_rule. Les données de cette branche suivent ces formats réels ; copier directement les JSON 26.2 ne suffit pas. Les bruits utilisent également base_octave, octave_count et amplitude_modifiers. Le seul opérateur Java ajouté, sanctuary:main_island, compose le terrain et les bruits de sculpture, applique le repère vertical choisi et impose la limite extérieure après interpolation.

Vérification

./gradlew :sanctuary:worldgenSmoke
./gradlew :sanctuary:runGameTest

Le smoke test vérifie qu'aucun sol n'est ajouté, que l'intérieur conserve le champ naturel et que l'érosion évolue progressivement sur un profil de terrain contrôlé. Il vérifie aussi qu'un lobe plein recule d'au moins 30 blocs en haut et en bas par rapport à son milieu, pour éviter une paroi verticale simplement déplacée. Il couvre aussi l'influence des deux bruits de sculpture, le vide avant les bornes de sécurité, et le vide dans les quatre directions même avec un bruit entièrement positif. Les coordonnées testées incluent les limites de Minecraft et des entiers Java pour détecter débordements et répétitions involontaires.

Les GameTests chargent le preset réel sur un serveur éphémère, vérifient le spawn après décoration, puis inspectent des chunks complets à distance dans les quatre directions. Ils comparent aussi la densité compilée avec deux instances de la même seed et une seed différente. Cela détecte les références JSON invalides et les blocs que des features pourraient ajouter après le calcul de densité. Les injections du serveur de test sont isolées dans src/gametest et ne sont pas distribuées dans le mod.

Les graines de régression des générations v2 et v3 sont 0, 42 et 8675309. Le serveur de test exporte leurs cartes de hauteur et coupes de densité dans mods/sanctuary/build/run/gameTest/diagnostics/. Ces images permettent de comparer la vraie densité alpha.2, toujours chargée, avec la nouvelle île relevée dans toute la hauteur 0..383. Les assertions vérifient la translation du relief supérieur, la variation des hauteurs du dessous, l'absence de plancher, les 384 blocs de génération et la conservation des anciens paramètres 256. Ces images ne montrent pas les arbres ni les matériaux et ne remplacent pas un essai visuel en jeu.

Contrat du prochain ticket : expansion

Avant de créer des continents, définir une donnée persistante par monde contenant pour chaque région son identifiant, centre, direction, emprise, seed dérivée, version de générateur et état de déblocage. L'île principale devient la première région de ce registre ; les nouvelles régions utilisent des coordonnées absolues, sans cellules périodiques.

L'activation doit être une action du serveur, reproductible et sauvegardée, conditionnée ensuite par les contributions collectives. Elle doit tenir compte du fait qu'un joueur peut déjà avoir chargé ou construit dans le vide : un chunk existant ne se régénère pas simplement parce que la liste des continents change. Le ticket doit choisir une réservation d'espace ou une matérialisation contrôlée qui protège les constructions et ne remplace jamais aveuglément des chunks sauvegardés.

La version de génération et les emprises doivent être gelées avant les premières sauvegardes destinées à durer. Ce prototype ne promet pas encore de migration automatique des mondes entre deux versions de terrain.