sanctuary-beta/docs/atlas-beta005.md

# MAP-01 — carte Sanctuary native, beta.005

Ticket autorisé le 13 septembre 2026, branche `codex/native-map-beta005`.
Carte de dessus écrite dans Sanctuary, inspirée des interactions de Xaero
(glisser, zoomer, se recentrer). Aucun code, asset ou dépendance Xaero repris.

## Comportement livré

Le Blocodex ouvre une carte de surface de l'Overworld : nord en haut, terrain
coloré, position et orientation de l'habitant, déplacement, zoom, recentrage.
L'aptitude **Grande carte** coûte provisoirement 4 niveaux, configurables.
L'exploration commence avant cet achat, conformément au choix du créateur.
La mini-carte, les marqueurs et le partage volontaire entre habitants restent
des tickets distincts. Aucun partage automatique de découvertes.

La vue habitant affiche ses propres relevés. La vue opérateur est un choix
explicite contrôlé par le serveur (`COMMANDS_GAMEMASTER`, commandes autorisées
en solo). Elle peut inspecter les chunks déjà chargés, sans les inscrire dans
les découvertes personnelles et sans charger/générer de terrain supplémentaire.
La carte représente la surface supérieure, sans carte des grottes ni radar.

Les couleurs de création d'habitant affichent des noms FR/EN (Azur,
Pamplemousse, Sauge…) associés à leur teinte, en caractères Minecraft normaux.
Les boutons et leur texte coloré restent natifs ; l'attribution RGB ne change
pas. Les longs noms disposent du défilement et de l'infobulle vanilla.
La carte laisse le monde évoluer pendant sa consultation, y compris en solo.

## Contrat de sauvegarde et migration, écrit avant le code

Les identifiants, chunks, graines et contrats de génération sont inchangés.
Seuls les mondes dont la progression Sanctuary est déjà active participent.

L'attachement `sanctuary:progression` passe du schéma 1 au schéma 2 : ajout du
booléen `atlas`, initialement faux. Le lecteur valide les anciens champs et
l'historique puis les conserve ; un prochain achat écrit le schéma 2. Les rangs,
l'aptitude Noms, les coûts déjà payés et dates ne changent pas. Les morts et
reconnexions conservent l'achat de Grande carte. Aucun prestige introduit.

`progression.json` schéma 1 reste accepté sans réécriture : `atlasCost` vaut 4
par défaut. Les nouvelles configurations utilisent le schéma 2 et ce champ.
Pour régler le prix dans un ancien fichier, passer `schema` à 2 et ajouter
`"atlasCost": 4` (ou le prix voulu), en conservant les autres valeurs.

Des fichiers additifs `data/sanctuary-atlas/<UUID>.json` (schéma 1) conservent
les relevés de surface de l'Overworld, liés à l'UUID et à la graine. Une tuile
contient 16×16 couleurs de carte vanilla. Les relevés portent sur les chunks
chargés dans un rayon de deux chunks autour de l'habitant, progressivement.
Il s'agit d'une proximité cartographiée, pas d'une visibilité optique exacte.
Les revisites actualisent le terrain ; les zones lointaines restent le dernier
relevé. Les parcours antérieurs à beta.005 ne peuvent pas être reconstitués.

Écriture atomique périodique et à la déconnexion/fermeture ; les derniers relevés
peuvent être perdus lors d'un arrêt brutal. Une limite de 16 384 chunks par
habitant borne ce premier lot ; une carte pleine reste consultable et signale
qu'elle ne peut plus ajouter de zones. Un fichier invalide est conservé et
désactive la carte concernée, sans effacer les données ni bloquer les autres.

Avant une utilisation dans une sauvegarde personnelle, conserver une sauvegarde
complète. Un retour à beta.004 exige la copie antérieure à la migration : son
lecteur de progression ne connaît pas les achats `atlas`. Aucun monde personnel
n'est ouvert par ce ticket, les essais utilisent des mondes de développement.

## Vérification

- `./gradlew check build -PsanctuaryFocusedTests=progression,map` : contrats
  de progression et de relevés, et **7/7 tests natifs serveur** réussis.
- `./gradlew :sanctuary:runClientGameTest -PsanctuaryClientTests=true
  -PsanctuaryProgressionClientTests=true` : réussi, **1 min 46 s**. Vrai client,
  création avant spawn, noms de couleurs FR, achat réel de Grande carte,
  relevés antérieurs à l'achat, zoom/glisser/recentrer, GUI 320×240 et autres
  tailles, commandes désactivées puis activées, inspection explicite,
  révocation et effacement des tuiles opérateur, retour au menu pause,
  mort et redémarrage du même monde de test.
- La maquette archivée et les packs beta.003/004 restent immuables.
- Captures : `build/beta005-preview/`. Logs : `build/beta005-client.log`,
  `build/beta005-check-build.log`, `build/beta005-delivery.log`.

Les essais ne mesurent pas encore une charge de 30 joueurs ni la durée d'une
saison complète. La suite générale garde les deux assertions worldgen
historiques signalées en beta.004 (hauteur 384 attendue contre 640 et support
de sédiment seed 0) ; ce lot n'a pas modifié la génération.

## Tester

Installer le pack beta.005 côté client et la même version côté serveur.
Dans le Blocodex (**B** ou **Échap**), acheter **Grande carte** dans Progression,
puis ouvrir **Monde → Grande carte**. Glisser pour déplacer, molette ou boutons
pour zoomer, Recentrer ou Début pour revenir au joueur. Les flèches déplacent
la vue. Une zone noire n'est pas encore relevée ; le vide relevé est bleu sombre.
Le relevé complet des environs immédiats prend environ cinq secondes.

Avec les commandes autorisées en solo ou les droits opérateur, ouvrir la même
carte puis choisir **Vue opérateur**. Cet accès ne nécessite pas l'achat de
l'aptitude ; revenir à **Vue habitant** retrouve ses seuls relevés et l'exigence
de l'aptitude. L'inspection ne charge pas de terrain distant : une zone absente
peut simplement ne plus être chargée côté serveur.

Les relevés couvrent l'Overworld supérieur, par proximité de deux chunks, sans
reconstituer les parcours antérieurs à beta.005. Les marqueurs, mini-carte,
partages, grottes, statistiques/advancements dans le Blocodex, filtrage des blocs
inconnus et vitrines/favoris de l'habitant restent les prochains tickets.


## Livraison locale vérifiée

`./gradlew check build assemblePack -PsanctuaryFocusedTests=progression,map`
réussit en 4 min 09 s ; **7/7 tests natifs serveur**. Export packwiz puis
vérification du ZIP, JAR embarqué, versions internes, dépendance Fabric API,
index packwiz, libellés FR/EN, six icônes originales et absence du mod de test.

- MRpack : `build/Sanctuary-beta.005.mrpack`, 2 248 215 octets.
- SHA-256 : `4a71465349af334b5bdeed4b0cc42dbef55de94e6acb7f0ab798cda477e6dc0e`.
- Reçu : `build/atlas005-artifact.json`.
- JAR : `mods/sanctuary/build/libs/sanctuary-beta.005.jar`.

Les empreintes des MRpacks beta.003/004 et des deux ZIP d'archives Web v1 sont
inchangées. Aucune publication distante, synchronisation Prism ou installation
sur un serveur personnel n'a été effectuée.