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é dans la densité, simplement relevé de 64 blocs. L’hydrologie traite ensuite les lits et les rives près de la surface.
• 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. Aucun terrain ne réapparaît 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.
• Les nouveaux mondes utilisent une palette tempérée de prairies, de bosquets, de corniches moussues et de zones rocheuses, répartie aussi en hauteur. Dappled Forest est réservé aux futurs continents. Leur végétation et leurs animaux proviennent de Minecraft 26.3-pre-2. Les nouveaux identifiants ne reprennent pas les tags de structures vanilla, afin de ne pas placer leurs structures dans le vide.
• Les carvers, géodes, donjons, grands lacs de lave et sources vanilla sont retirés. L’eau de Sanctuary suit son propre plan de surface et de niches rocheuses. Les arbres et les petits filons ont besoin du terrain existant. Aucun mod de biomes externe n’est nécessaire.

L’alpha.6 associe ces biomes aux plages, aux eaux et aux petits filons décrits ci-dessous. Les ressources de survie ne se limitent pas au bois et à la pierre, mais cet incrément ne garantit pas encore une partie Minecraft complète sur chaque seed. L’accès à chaque progression vanilla et les ressources renouvelables nécessitent des vérifications concrètes. Les stocks réels sont relevés après la génération, sans corriger une île pour atteindre un quota.

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 : aucun plancher rocheux ne doit apparaître dans Y=0..15. À partir de l’alpha.5, seules les eaux descendantes de sources explicitement déclarées peuvent traverser cette marge.

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é.

Hydrologie de surface — génération v4

La version 0.1.0-alpha.4 conserve la densité, la hauteur et le ciel de l’alpha.3. Les nouveaux mondes sélectionnent les paramètres sanctuary:sanctuary_hydrology et le biome sanctuary:starter_forest_hydrology. Le type de dimension reste sanctuary:sanctuary_384. Les anciens paramètres et le biome sanctuary:starter_forest restent disponibles et inchangés : ils n’activent pas cette hydrologie dans les sauvegardes antérieures.

Un plan calculé depuis le relief et la graine recherche des emplacements de surface pour des étangs, des petits lacs et un premier cours d’eau calme. Le lit peut être légèrement creusé dans la roche existante. Avant d’accepter un emplacement, le plan vérifie le fond et les parois en trois dimensions ainsi que l’ouverture vers le ciel. Un trou profond dans la carte de hauteur ne suffit pas à constituer un lac. Aucune digue ni masse de roche n’est ajoutée pour boucher une fuite, et aucun bassin souterrain n’est rempli.

Les fonds alternent sable, gravier et argile ; les berges basses peuvent recevoir du sable. Dans ce nouveau biome, les disques de sédiments vanilla et les veines de gravier sont remplacés par ces dépôts de rive et de fond : une feature ultérieure ne doit pas transformer leur support en gravier instable. Les sources de magma sous-marines sont également absentes. Après les arbres et la végétation, de la canne à sucre peut pousser sur les rives qui respectent ses règles de placement vanilla. Le nombre de sites, leur eau et leurs ressources dépendent du terrain : le générateur ne complète pas une graine pour atteindre un quota économique.

Le plan est indépendant des chunks chargés. Chaque chunk applique uniquement ses propres colonnes après le terrain et avant la décoration, ce qui permet de raccorder un même plan d’eau aux frontières des chunks. Les anciens chunks ne sont jamais retouchés, et aucun travail hydrologique ne se déclenche au simple chargement d’une sauvegarde.

Cette première version vise de petites eaux retenues et des cours d’eau calmes sur les plateaux. Le cours d’eau est un chenal à niveau constant reliant des plans d’eau ; il ne simule pas encore une pente vers l’aval ou un débit. Les tracés peuvent passer par les diagonales, mais leur eau reste connectée de bloc en bloc. L’excavation est limitée à six blocs, l’eau à quatre blocs de profondeur, avec un fond plein sur trois blocs d’épaisseur, dont deux blocs naturels sous le sédiment. Ce contrat alpha.4 reste celui de ses sauvegardes. Les sources en cascade sont ajoutées séparément dans la génération v5 ; les grandes rivières en pente, océans, aquifères, climats multiples et continents restent des incréments distincts.

Plages, sources et mosaïque tempérée — génération v5

L’implémentation 0.1.0-alpha.5 sélectionne la nouvelle clé de paramètres sanctuary:sanctuary_natural (SanctuarySpawn.NATURAL_SETTINGS). Elle conserve la densité relevée, les 384 blocs de hauteur et le ciel de l’alpha.3. La classe NaturalHydrology et son application sont séparées de SurfaceHydrology et HydrologyRuntime : le code, les paramètres sanctuary:sanctuary_hydrology et le biome sanctuary:starter_forest_hydrology de l’alpha.4 restent inchangés. Les clés alpha.2 et alpha.3 restent également disponibles avec leur comportement antérieur. Ces changements concernent uniquement les nouveaux mondes : aucune conversion de sauvegarde, régénération de chunk ou expansion n’est effectuée.

Dépôts et eau de surface

Le plan recherche des étangs, de petits lacs et un cours d’eau calme dans le relief naturel. L’excavation maximale passe à quatre blocs, pour une eau de trois blocs de profondeur au plus. Les bassins gardent un fond et des parois naturels pleins ; aucune digue n’est ajoutée et aucune chambre souterraine n’est remplie. Le cours d’eau reste à niveau constant : il ne modélise pas un débit ni une pente continue vers l’aval.

Les plages sont des nappes irrégulières qui suivent les faibles variations du relief autour des plans d’eau. Elles peuvent s’étendre sur plusieurs blocs, se rapprocher d’une autre poche d’eau et retrouver progressivement l’herbe ou la pierre. Les matériaux varient entre sable, gravier, pierre et terre enherbée ; l’argile peut apparaître dans les fonds. Le traitement d’une terrasse sèche retire au plus deux blocs du relief existant.

Chaque dépôt remplace trois à cinq couches de terrain déjà plein et garde deux couches naturelles de support en dessous. Ce support permet notamment au sable et au gravier de rester en place après les mises à jour de gravité. Les veines de gravier, disques de sédiments et magma sous-marin vanilla ne sont pas réintroduits dans ces nouveaux biomes. Les autres décorations rocheuses et les minerais peuvent encore remplacer la pierre ; ils ne remplacent pas les couches de sable, gravier ou argile. Les rives compatibles peuvent porter de la canne à sucre après la végétation. Les troncs couchés vanilla peuvent occuper quelques blocs de la surface d’un étang ; les contrôles distinguent cette décoration de l’eau restante et vérifient leur fond ou l’eau sous les troncs, les sources voisines et la rétention du bassin.

Sources rocheuses et cascades

Le plan peut retenir jusqu’à trois sources dans des niches rocheuses naturelles, séparées des dépôts modifiés. Une source remplace un seul bloc de roche, sous un toit, sur un fond et entre trois côtés déjà pleins. Son unique sortie horizontale est naturellement ouverte sur une chute d’au moins huit blocs. Le générateur ne construit ni pylône, ni corniche, ni tunnel pour obtenir ce résultat.

Seul le bloc source est généré. Les ticks de fluide de Minecraft forment la cascade et ses éventuels passages sur des paliers. Ces écoulements peuvent descendre jusque dans le vide, conformément au comportement demandé. Cette exception concerne les sources déclarées. Le trajet calculé dans la roche nue est une prévision : les arbres générés ensuite peuvent dévier une chute. Les diagnostics vérifient donc les connexions réelles de chaque bloc d’eau vers une source, dans l’emprise des chunks inspectés et de leur halo. Ils échouent si de l’eau touche une frontière non inspectée ou si un bassin perd sa coque. Les déviations par rapport à la prévision restent mesurées dans le rapport. Le comportement des fluides reste celui de Minecraft, y compris lorsque les joueurs modifient une rive.

Petite réserve de lave

StarterLavaDeposit recherche au plus une niche de 18 blocs sources dans la roche existante, accessible par un passage sec de deux blocs de haut depuis une corniche naturelle. Le fond garde trois blocs pleins, les parois deux et la couverture huit ; ces supports sont vérifiés avant les écritures. La niche reste éloignée des eaux et de leurs parcours. Elle fournit de la lave prélevable pour les premières productions et un portail du Nether. Si aucun site ne convient, le plan reste vide : aucun bassin artificiel n’est ajouté dans le vide.

Les tests vérifient l’accès praticable, la rétention de la lave et l’absence d’incendie après simulation.

Biomes et minerais

Le biome source sanctuary:temperate_island utilise deux champs de bruit initialisés par la seed pour répartir cinq variantes horizontales. Une rive et la roche sous elle restent dans la même variante :

Identifiant	Variante
sanctuary:temperate_forest	Forêt dominante
sanctuary:temperate_plains	Clairières et plaines tempérées
sanctuary:temperate_birch_forest	Forêt de bouleaux
sanctuary:temperate_flower_forest	Forêt fleurie
sanctuary:temperate_dappled_forest	Dappled Forest, peupliers et végétation associée

Dappled Forest est un biome vanilla introduit dans Minecraft 26.3 Snapshot 1. Cette variante reprend ses données de 26.3-pre-2, avec une humidité légèrement relevée pour Sanctuary. Elle n’ajoute ni dépendance externe ni structure de camp. La palette tempérée ne constitue pas encore le catalogue TerraMix ni le champ climatique des futurs continents.

Les nouveaux biomes remplacent les filons vanilla de métaux par de petites features sanctuary:island_ore_*, à des altitudes adaptées à l’île relevée :

Ressource	Taille du filon	Tentatives par chunk	Plage Y
Charbon	6	2	96–288
Fer	4	2	88–248
Cuivre	4	1	96–248
Or	4	1	104–224
Redstone	4	1	96–224
Lapis	3	Une tentative, chance 1/2	112–232
Diamant	3	Une tentative, chance 1/4	104–208

Ces paramètres décrivent des tentatives, pas des quantités promises : le filon doit rencontrer la roche existante, et sa forme dépend du hasard de génération. La sélection des biomes et des eaux ne cherche aucun stock cible. Un relevé partiel reste un relevé partiel ; la présence des sept ressources sur une seed de référence ne garantit pas leur présence sur toutes les seeds.

La validation de l’alpha.5 est suivie dans Validation. Ses diagnostics sont conçus pour inspecter les blocs décorés, les profils des dépôts, les jointures de chunks, les biomes et les ressources, puis simuler réellement les fluides dans les chunks des sites. Les cartes et profils PNG montrent des lectures de blocs, pas un rendu Minecraft. La descente des cascades est contrôlée après activation effective des chunks qui les simulent.

Prairies et corniches — génération v6

L’alpha.6 utilise sanctuary:sanctuary_layered et le biome source sanctuary:layered_island. Les formes et le ciel restent ceux de la génération relevée. Les anciennes classes, biomes et règles de matériaux restent disponibles pour les sauvegardes alpha.2 à alpha.5 ; seul le preset de création choisit v6.

Une palette qui varie aussi en hauteur

Les cinq variantes partagent leurs teintes d’herbe et de feuillage. Les champs de climat liés à la seed déforment de larges bandes d’altitude, autour de Y154 et Y214 : prairies et prairies fleuries sur le dessus, bosquets et corniches moussues plus bas. Des zones rocheuses traversent ces bandes et remplacent la couverture de terre par de la pierre sur le relief existant. Les prairies gardent quelques arbres épars et leur végétation vanilla. Dappled Forest n’appartient plus à cette palette ; son utilisation sur de futurs continents reste à développer.

Identifiant	Ambiance
sanctuary:layered_meadow	Prairie tempérée
sanctuary:layered_flower_meadow	Prairie fleurie
sanctuary:layered_lower_grove	Bosquet inférieur
sanctuary:layered_mossy_terraces	Corniches moussues
sanctuary:layered_rocky_terraces	Affleurements rocheux

LowerTerraceVegetationFeature parcourt aussi les sols naturels sous les surplombs, au moins huit blocs sous une surface supérieure. Elle demande trois blocs pleins de support et deux blocs libres au-dessus. Elle peut remplacer la surface existante par de la mousse et planter fougères, fleurs ou petits arbustes lorsque leurs règles de survie le permettent. Les cellules hydrologiques, les sources, les parcours d’eau prévus et les supports de lave sont protégés. Il n’y a ni corniche construite dans l’air ni ajout d’éclairage artificiel.

Bassins et sources de paroi

LayeredHydrology conserve les petits bassins et les dépôts épais, avec une plus grande présence de pierre. Le court STREAM à niveau constant de l’alpha.5 n’est pas repris. Cette version retient uniquement les étangs et les petits lacs ; elle ne cherche pas de grande rivière. Le parcours traversant avec source, cascade et bassin reste un ticket distinct, à démontrer sur le relief Minecraft réel. Aucun chenal de secours n’est creusé.

La profondeur reste limitée à trois blocs et l’incision à quatre. Le plan vérifie le fond et les rives avant d’appliquer ses écritures, dans les nouveaux chunks seulement. Le sable, le gravier, l’argile et la roche suivent les rives. Des niches de source sont également recherchées dans les strates inférieures, et pas seulement près de la surface la plus haute. Leurs chutes sont produites par les ticks de Minecraft à partir d’un seul bloc source. Le post-traitement des nouveaux chunks libère uniquement leur ouverture, déjà vide dans la densité naturelle, pour qu’un lichen ou une plante ne bouche pas la source. Les positions sont marquées dans la file vanilla pendant la génération, puis consommées une seule fois. Un rechargement ne dégage pas une bouche modifiée par un joueur. Aucune chute n’est préremplie et aucun nouveau passage n’est creusé dans la roche.

Les parcours, les écoulements et la végétation réellement observés, ainsi que les limites du modèle, sont consignés dans Validation.

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, sanctuary:sanctuary_384 ou sanctuary:sanctuary_hydrology, sanctuary:sanctuary_natural ou sanctuary:sanctuary_layered. 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.