Raise Sanctuary to 384 blocks and survey generated resources

docs/expansion.md

@@ -0,0 +1,202 @@
+# Climats, expansion et ressources
+
+Ce document fixe les décisions de conception pour la suite de Sanctuary. Le
+registre persistant des continents, leur déblocage et leur génération dans les
+huit directions restent à implémenter. Le relevé de ressources décrit plus bas
+est un outil de développement séparé, exécuté dans le monde jetable des GameTests.
+
+## Les huit directions climatiques
+
+Sanctuary Island constitue le point de départ **tempéré, légèrement humide**.
+Le nord conduit vers le froid, le sud vers le chaud, l'ouest vers le sec et
+l'est vers l'humide. Les diagonales combinent ces tendances.
+
+| Direction | Axe Minecraft depuis Sanctuary | Tendance climatique |
+| --- | --- | --- |
+| Nord | `−Z` | Froid |
+| Nord-est | `+X, −Z` | Froid et humide |
+| Est | `+X` | Humide |
+| Sud-est | `+X, +Z` | Chaud et humide |
+| Sud | `+Z` | Chaud |
+| Sud-ouest | `−X, +Z` | Chaud et sec |
+| Ouest | `−X` | Sec |
+| Nord-ouest | `−X, −Z` | Froid et sec |
+
+Ces directions définissent des familles de climats, pas huit biomes uniformes.
+Le relief, l'altitude, les variations locales et la graine doivent conserver
+des géographies distinctes à l'intérieur de chaque continent. Les amplitudes
+de température et d'humidité, leur évolution avec la distance et les seuils
+de sélection des biomes feront partie du ticket de génération des continents.
+Les ressources et cultures futures, notamment celles d'It's Alive !, pourront
+ainsi demander l'exploration de plusieurs climats.
+
+L'île initiale utilise encore un biome de départ spécifique. Une température
+ou une humidité du biome ne constitue pas à elle seule une carte climatique
+directionnelle : cette carte et la sélection des biomes des continents restent
+des travaux distincts.
+
+## Eau de surface et exploration
+
+L'île de départ doit pouvoir accueillir naturellement des étangs et lacs de
+surface, des berges propices à la canne à sucre et, lorsque le relief s'y prête,
+des rivières. L'eau s'inscrit dans les creux et les chemins du terrain existant.
+Les rivières flottantes et les cascades doivent tenir compte de la continuité
+de leur lit et du vide sous les îles.
+
+Le contrat ne demande ni un bassin souterrain imposé pour obtenir un stock
+d'eau, ni une cuvette ajoutée systématiquement à une position fixe. Une surface
+d'eau doit reposer sur un fond naturel et disposer de berges cohérentes ; un
+volume rocheux fermé sous terre ne devient pas un lac de surface. Les plantations
+de canne à sucre doivent respecter leurs conditions de placement, sans modifier
+la carte pour atteindre une quantité prédéterminée.
+
+Un étang, un lac, une rivière et un bassin souterrain sont donc des résultats
+différents à vérifier. Un prototype d'étangs ne valide pas automatiquement les
+rivières ou l'ensemble de l'hydrologie. Le détail effectivement livré à chaque
+version reste décrit dans [Génération](worldgen.md), avec ses limites.
+
+## Observer les ressources après génération
+
+La génération produit le monde ; l'économie apprend ensuite ce que le monde
+contient. On ne force pas un nombre de blocs de pierre, de bûches ou de minerais
+pour faire correspondre la géographie à un budget. Un relevé peut constater
+qu'une ressource est absente, rare ou abondante pour une graine donnée. Ce constat
+ne déclenche pas de remplissage ni de remplacement de blocs.
+
+Le relevé initial servira de référence pour préparer l'économie et la progression
+collective. Il distingue les blocs présents, les ressources réellement accessibles
+aux joueurs, les ressources renouvelables et les objets obtenus en les récoltant.
+Un bloc de minerai n'est pas un nombre garanti d'objets : outils, enchantements,
+butins et transformations relèvent d'autres règles. Les blocs de bois ne comptent
+pas des arbres, et un comptage de blocs d'eau ne mesure pas un débit de rivière.
+
+Une observation dans une petite zone reste une observation locale. On ne peut
+pas multiplier son résultat pour annoncer la quantité totale de l'île. Les
+rapports de continents devront conserver leur propre graine, version, emprise
+et état de génération, afin d'additionner seulement des régions connues et
+disjointes lorsque le besoin économique sera défini.
+
+## Relevé de développement disponible
+
+`ResourceSurveyDiagnostics`, dans `src/gametest`, lit les chunks au statut
+`FULL`, après le terrain, les matériaux et les décorations. Il ne figure pas
+dans le JAR Sanctuary distribué et n'ajoute aucune commande joueur ou admin.
+La tâche repart d'un monde GameTest neuf, jamais d'une sauvegarde personnelle.
+
+Le relevé standard inspecte **neuf chunks**, soit un carré de 48×48 blocs autour
+du chunk du spawn naturel, sur toute la hauteur de la dimension. Il prépare
+d'abord ces chunks et un halo voisin, puis compte exactement chaque cellule des
+palettes de leurs sections. La grille éloignée du framework est exclue et sa
+distance est vérifiée. Aucun objet posé, inventaire, contenu de coffre ou mob
+n'est inclus dans ces comptes de blocs.
+
+```sh
+# Contrôle standard : neuf chunks inspectés, total local uniquement.
+./gradlew :sanctuary:runGameTest -PsanctuaryResourceSurvey=sample --console=plain
+
+# Relevé de toute l'enveloppe déclarée de Sanctuary, sur un monde jetable neuf.
+./gradlew :sanctuary:runGameTest -PsanctuaryTestSeed=0 -PsanctuaryResourceSurvey=island --console=plain
+
+# Désactiver seulement le relevé pour un autre diagnostic.
+./gradlew :sanctuary:runGameTest -PsanctuaryResourceSurvey=off --console=plain
+```
+
+Les modes sont transmis à la propriété JVM de test
+`sanctuary.test.resourceSurvey`. Le mode `island` couvre **1 444 chunks** :
+`X` et `Z` de **−304 inclus à 304 exclu**, correspondant à l'enveloppe de terrain
+de rayon 288 et une marge de décoration de 16 blocs. Un halo d'un chunk porte
+la préparation à **1 600 chunks FULL** ; seuls les 1 444 chunks demandés sont
+comptés. Ce relevé complet est plus coûteux et ne s'exécute pas par défaut.
+La marge devra être revue si une future génération peut produire des structures
+ou décorations au-delà de cette enveloppe.
+
+Le JSON est écrit dans
+`mods/sanctuary/build/run/gameTest/diagnostics/resource-survey-seed-<graine>-<mode>.json`.
+Il contient :
+
+- La graine, la version Minecraft, le preset et les réglages de génération,
+  ainsi que `generator.version = sanctuary@<version du mod>`.
+- Le spawn naturel, les bornes exactes en blocs et chunks, les hauteurs de la
+  dimension et du bruit, les coordonnées de chaque chunk inspecté au statut
+  `FULL`, les dates UTC et les durées de préparation et de comptage.
+- Le total de toutes les cellules, les cellules d'air, les blocs non vides,
+  puis les comptes par identifiant de registre et par état complet, propriétés
+  comprises, par exemple `minecraft:oak_log[axis=y]`.
+- Des agrégats explicites pour la pierre, les bûches, les feuilles, les minerais
+  de charbon, fer, cuivre, or, redstone, lapis, diamant et émeraude, l'eau, la
+  lave, le sable, le gravier, l'argile, la canne à sucre et les sols.
+- La complétude dans les bornes demandées, la couverture ou non de l'enveloppe
+  déclarée de l'île et l'absence d'extrapolation. Aucun mode ne prétend inventorier
+  tout le monde Minecraft, ses autres dimensions ou ses futures expansions.
+
+Les variantes ordinaires et deepslate des minerais sont détaillées. Les agrégats
+fondés sur des tags indiquent leur définition et les membres observés. Certains
+groupes se recouvrent, comme `stone` et `base_stone_overworld`, ou les blocs
+d'eau et les blocs contenant un état d'eau : ils ne doivent pas être additionnés.
+Les sommes des identifiants et des états doivent chacune être exactement égales
+au volume inspecté, y compris l'air ; une incohérence fait échouer le GameTest.
+
+Ce rapport est un instantané après génération, avec l'heure du jeu observée.
+Il ne prédit pas les pousses, les récoltes, les pertes ni la production future.
+Le format JSON est versionné pour l'outil de test ; ce n'est pas encore un
+format de sauvegarde serveur ou un registre persistant de l'économie.
+
+## Référence mesurée — graine 0, alpha.3
+
+Le **8 septembre 2026**, un relevé complet de l'enveloppe déclarée a été effectué
+sur un monde neuf de graine **0**, avec `sanctuary@0.1.0-alpha.3` et les réglages
+`sanctuary:sanctuary_384`. Il couvre **1 444 chunks FULL**, de **−304 inclus à
+304 exclu en X et Z**, et de **0 inclus à 384 exclu en Y**. Le volume inspecté
+est donc exactement **608 × 608 × 384 = 141 950 976 cellules**.
+
+| Ressource observée | Nombre de blocs |
+| --- | ---: |
+| Pierre (`minecraft:stone`) | 7 355 184 |
+| Bûches, tag `minecraft:logs` | 10 946 |
+| Minerai de charbon | 101 399 |
+| Minerai de fer | 67 198 |
+| Minerai de cuivre | 2 352 |
+| Minerai de diamant | 6 |
+| Minerais d'or, redstone, lapis et émeraude | 0 chacun |
+| Gravier | 121 044 |
+| Terre et blocs d'herbe | 728 630 |
+| Feuilles | 117 735 |
+| Eau, y compris les blocs contenant de l'eau | 0 |
+| Canne à sucre | 0 |
+| Sable, argile et lave | 0 chacun |
+
+Les bûches comprennent **8 765 bûches de chêne** et **2 181 de bouleau**.
+Les minerais présents sont ici leurs variantes ordinaires ; aucune variante
+deepslate n'a été observée. Toutes catégories confondues, le relevé compte
+**8 584 514 blocs non vides** et **133 366 462 cellules d'air**. Ce sont les
+quantités observées dans cette graine et cette version, sans quota ni correction
+du terrain. Les zéros d'eau et de canne à sucre confirment que l'hydrologie
+demandée reste à réaliser ; ils ne constituent pas une cible à conserver.
+
+La source détaillée est le fichier local non versionné
+`mods/sanctuary/build/run/gameTest/diagnostics/resource-survey-seed-0-island.json`,
+terminé à **11:34:08 UTC**. Une lecture indépendante du JSON a confirmé les
+1 444 coordonnées de chunks distinctes, les sommes par chunk, les agrégats et
+l'égalité exacte entre le volume, le compte par identifiant et le compte par
+état complet. Les huit tests requis du serveur ont réussi pendant cette exécution.
+
+La préparation des chunks a pris **782 659 ms**, soit **13 min 2,659 s** ; le
+comptage et la préparation des données à sérialiser ont pris **135 ms**. Cette
+mesure locale a été effectuée sur un **Apple M1 avec 8 Go de mémoire**, avec un
+essai client concurrent pendant environ 23 secondes. Elle décrit une machine
+chargée et cette exécution, pas une performance garantie sur d'autres machines.
+Le temps de préparation est distinct du coût du comptage par palettes.
+
+## Contrat du prochain ticket d'expansion
+
+Avant toute activation de continent, enregistrer côté serveur son identifiant,
+sa direction parmi les huit, son centre, son emprise, sa graine dérivée, sa
+version de génération, son profil climatique et son état de déblocage.
+Le relevé des ressources intervient après la génération effective de sa région,
+avec une complétude explicite, indépendamment des contributions qui l'ont ouverte.
+
+Les zones déjà explorées dans le vide peuvent contenir des chunks sauvegardés
+ou des constructions. L'activation exige donc un contrat de réservation ou de
+matérialisation qui les protège ; elle ne peut pas régénérer silencieusement
+les chunks existants. Les règles de contribution, distances, tailles,
+réservations, migrations et prix ne sont pas décidées par ce diagnostic.