sanctuary-beta/docs/expansion.md

Climats, expansion et ressources

Ce document fixe les décisions de conception pour la suite de Sanctuary. L’alpha.12 fournit un laboratoire avec registre persistant et commandes opérateur, suivant le contrat de laboratoire. Le déblocage par recherches et contributions reste à 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.

Taille de l’île initiale — alpha.11

Deux choix de départ sont proposés : Petit et Grand, Grand par défaut. Petit garde un diamètre nominal de 512 blocs ; Grand vise environ 724 blocs, soit deux fois l’aire nominale de Petit. La hauteur reste de 384 blocs. Les repères internes 5/10 servent au calcul de surface, sans nom de capacité affiché ni promesse sur le nombre de joueurs, les minerais ou l’aire constructible.

Cette taille se choisit pour un nouveau monde et ne remplace pas le futur déblocage collectif de continents. Grand utilise population_10 ; les anciennes sauvegardes 5/20/100 conservent leurs réglages et leurs dimensions. Les formats 20/100 sont cachés de la création. Les mesures de l’alpha.10 conservées plus bas restent historiques ; les contrôles alpha.11 sont dans Validation.

Les huit directions et les branches climatiques

Sanctuary Island constitue le point de départ tempéré, légèrement humide. La boussole climatique est une convention facultative : nord froid, sud chaud, ouest sec et est humide. Les diagonales combinent ces tendances. La direction géographique ne contraint plus le climat. Les joueurs pourront choisir de prolonger une voie climatique ou de bifurquer vers d’autres découvertes.

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 associations sont les raccourcis par défaut, pas une loi du monde. Une branche conserve son parent, sa direction et son climat explicite. Plusieurs couronnes peuvent donc proposer des biomes nouveaux au nord comme au sud. Le point d’origine reste enregistré même si un joueur déplace son lit ou le spawn. Les familles de climats ne sont pas des 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’alpha.5 proposait cinq biomes tempérés dont Dappled Forest. L’alpha.6 réserve ce dernier aux futurs continents et donne à l’île une palette plus douce de prairies, prairies fleuries, bosquets, corniches moussues et zones rocheuses. La répartition tient compte de l’altitude, y compris dans les strates inférieures. La variation locale et l’humidité dépendent de la graine ; elles ne constituent pas encore le champ de recherche directionnel des continents.

L’alpha.7 densifie les forêts de chênes et de bouleaux en surface et donne aux corniches intérieures humides des chênes noirs et des champignons. Des champignons vanilla peuvent aussi se rencontrer en surface. Les clairières fleuries et les affleurements restent présents. Les essences rares et un éventuel arbre remarquable dépendent du terrain ; chaque graine n’est pas tenue de fournir tous les bois. Les minerais de départ peuvent affleurer, avec des petits filons et sans correction des stocks après comptage.

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 bassins gardent un fond et des berges fermés. Une grande rivière reste facultative : elle doit suivre le relief et former un parcours lisible avec source, chute et bassin. Ses exutoires peuvent laisser couler l’eau dans le vide. Sans parcours suffisamment long, l’île conserve seulement ses petits bassins. L’alpha.6 livre cette variante à bassins seuls ; la grande rivière reste à développer. L’alpha.5 ajoute séparément quelques sources sortant d’une niche rocheuse naturelle : leurs cascades peuvent descendre dans le vide et servir à remonter verticalement. Cet écoulement est volontaire ; il ne doit pas entraîner des fuites sur toutes les rives.

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

Ressources de départ — depuis l’alpha.5

L’île vise les premières étapes de survie, les outils, l’enchantement et la redstone. Les sept minerais (charbon, fer, cuivre, or, redstone, lapis et diamant) utilisent des petites veines à des altitudes compatibles avec le terrain relevé. Le charbon et le fer ne reprennent plus leurs fréquences vanilla beaucoup trop généreuses dans cette géométrie. Une petite réserve de lave peut apparaître dans une niche rocheuse accessible pour les premières productions et l’accès au Nether. Le bois, la pierre, les animaux et les cultures renouvelables conservent leur fonctionnement Minecraft : ce réglage des minerais ne constitue pas une interdiction des grandes constructions.

Les placements restent probabilistes, sans quota de rattrapage après comptage. Une graine peut donc manquer d’une ressource ; la présence de tout le parcours Minecraft n’est pas garantie. Les structures donnant accès à l’End et leur lien avec l’expansion restent à concevoir.

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.

# 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. La propriété Gradle -PsanctuaryTestPlayers choisit le profil interne. L’alpha.11 utilise 5 pour Petit et 10 pour Grand, ce dernier par défaut ; 20 et 100 servent à la compatibilité historique. Le mode island calcule l’enveloppe du profil actif, avec 16 blocs de marge de décoration et un halo de préparation d’un chunk. Les valeurs ci-dessous sont les bornes calculées lors de l’alpha.10, pas des relevés exécutés ni un nombre de chunks déjà validé pour le nouveau Grand :

Profil	Chunks comptés par island	Chunks FULL préparés avec halo
5	1 444	1 600
20	4 900	5 184
100	22 500	23 104

Un relevé de toute l’emprise peut être très coûteux et ne s’exécute pas par défaut. La marge devra être revue si une future génération produit des structures ou décorations qui la dépassent. Les diagnostics alpha.10 courants restent des inspections ciblées ; leurs nombres de minerais ne sont pas ceux d’un relevé island complet.

Les nouveaux fichiers sont nommés mods/sanctuary/build/run/gameTest/diagnostics/resource-survey-players-<capacité>-seed-<graine>-<mode>.json. Sur un générateur historique, le nom émis par l’outil actuel porte legacy. Les anciens chemins resource-survey-seed-… cités plus bas désignent uniquement les relevés archivés de leurs versions respectives.

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.