Initialize Sanctuary Fabric 26.3 prototype and pack

docs/worldgen.md

@@ -0,0 +1,123 @@
+# 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 :
+
+```properties
+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 ses deux gradients verticaux. Reliefs, surplombs, trous et fragments
+  dépendent donc de la seed Minecraft.
+- Une enveloppe limite l'île à un rayon nominal de **256 blocs**. Le bord varie
+  avec un second bruit lié à la seed, jusqu'à **288 blocs au maximum** pour la
+  roche. Les arbres peuvent dépasser ce bord de quelques blocs.
+- Une masse centrale ellipsoïdale, centrée en `(0, 76, 0)`, garantit du sol
+  même quand le bruit historique creuse l'origine. Son rayon horizontal est de
+  96 blocs et son rayon vertical de 42 blocs. Le reste du relief peut monter
+  au-dessus de cette masse. La géométrie du noyau est volontairement stable.
+- La roche se trouve entre `Y=1` et `Y=255` ; 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.
+
+## Apparition commune
+
+Une injection limitée à la création initiale cherche une surface de 3 × 3 blocs
+stable, avec deux blocs libres en hauteur, à proximité de l'origine. 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 les deux
+champs de bruit et impose la limite extérieure après interpolation.
+
+## Vérification
+
+```sh
+./gradlew :sanctuary:worldgenSmoke
+./gradlew :sanctuary:runGameTest
+```
+
+Le smoke test vérifie le noyau garanti même avec un bruit entièrement négatif,
+le vide dans les quatre directions même avec un bruit entièrement positif, les
+limites verticales, la préservation de l'influence du champ de terrain et la
+symétrie de l'enveloppe pour des entrées identiques. Les coordonnées testées incluent la limite du monde et
+les grands entiers 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.
+
+## 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.