Record Sanctuary sources through beta.060 and Git validation

docs/tutorial-xp-beta016.md

@@ -0,0 +1,98 @@
+# beta.016 — XP des premiers pas
+
+Ticket du 13 septembre 2026, branche `codex/tutorial-xp-beta016`.
+Contrat préalable à l'implémentation et à l'ajout de données persistantes.
+
+## Comportement et budget
+
+Les cinq actions de `TutorialSteps` dans Minecraft 26.3-pre-2 reçoivent une
+récompense personnelle de **8 points d'XP** chacune par défaut. Les 40 points
+font quatre niveaux depuis zéro sans autre gain ni dépense. Ouvrir l'inventaire
+suffit à pouvoir acheter le premier rang d'une compétence. Chaque action peut
+être accomplie indépendamment de l'ordre du tutoriel client.
+
+| Identifiant stable | Action validée |
+| --- | --- |
+| `movement` | Marcher au moins deux mètres et tourner la vue d'au moins 15° pendant la connexion |
+| `find_tree` | Observer un bloc du tag natif `completes_find_tree_tutorial`, ou obtenir/miner une bûche |
+| `punch_tree` | Miner réellement une première bûche (`logs`) en survie |
+| `open_inventory` | Ouvrir l'inventaire personnel |
+| `craft_planks` | Fabriquer des planches : statistique native de fabrication du tag `planks` |
+
+Un message personnel FR/EN annonce l'étape et les points reçus. Le tutoriel
+vanilla et ses préférences restent en place ; ces récompenses fonctionnent
+aussi quand Minecraft n'affiche plus ses conseils. Aucun changement des
+advancements Minecraft, aucun nouvel advancement Sanctuary pour ces gestes.
+
+Les étapes ne se récompensent qu'une fois par UUID dans ce monde : conserver
+leur état après reconnexion, mort et New Game+. Les points non dépensés suivent
+les règles existantes de mort. Créatif et spectateur n'accordent rien ; un
+opérateur jouant en survie suit les mêmes étapes que les autres habitants.
+Les anciennes statistiques ne déclenchent pas de paiement rétroactif : les
+habitants existants peuvent accomplir ces actions une fois après la mise à jour.
+
+## Autorité et migration
+
+Le serveur attribue les XP et constate les déplacements/statistiques, la vue
+des blocs et la fabrication. L'ouverture de l'inventaire est un écran local :
+le client la signale, et le serveur vérifie que le joueur est vivant, en survie
+ou aventure, dans son propre menu d'inventaire, avec une progression active.
+Ce signal ne contient ni quantité d'XP ni identifiant de récompense libre. Un
+client modifié pourrait anticiper ce seul geste ; il ne peut pas répéter le gain.
+
+Ajout de l'attachement persistant `sanctuary:tutorial`, schéma 1, contenant les
+étapes terminées, leur date et le nombre de points payé. Absent des anciennes
+sauvegardes, il commence vide. Il est enregistré **dans le même instantané joueur
+que l'XP**, copié à la mort et laissé intact par le New Game+. Le schéma 8 de
+progression et les journaux existants ne changent pas. Les données inconnues ou
+corrompues sont refusées sans remplacement silencieux.
+
+Nouvelle configuration `config/sanctuary/tutorial.json`, schéma 1 : `enabled`
+et `xpPerStep` (8 par défaut, 0 à 10 000), lue au démarrage du serveur. La créer uniquement si absente ;
+conserver toute configuration valide existante. Une étape terminée ne peut
+pas être repayée après changement du montant. Aucun paiement périodique,
+aucune remise à zéro des étapes au prestige.
+
+Capacité réseau `sanctuary:tutorial_v1`, message d'ouverture
+`sanctuary:tutorial_inventory_opened`, état personnel `sanctuary:tutorial_state`.
+Client et serveur utilisent beta.016 ensemble. Aucune intervention sur le
+terrain, les expansions ou une installation de jeu personnelle.
+
+## Vérification prévue
+
+Contrôler les déclencheurs réels, le total, les actions répétées, les modes de
+jeu, l'achat avec l'XP du tutoriel, les sauvegardes, le respawn et le New Game+.
+Vérifier les configurations et données malformées. Exécuter les tests Gradle
+et un parcours client natif, puis exporter un MRpack beta.016 vérifié qui conserve
+les nouvelles icônes beta.015 et les sprites vanilla de respiration/faim.
+
+## Validation serveur réalisée
+
+`./gradlew check build assemblePack
+-PsanctuaryFocusedTests=progression,mining,building,inventory,cycle,inventoryflow,sorting,tutorial`
+réussit avec **57 tests natifs** et tous les contrôles purs (`build/tutorial016-check-build.log`).
+
+Les tests beta.016 passent par les statistiques natives de déplacement, une
+observation Blocodex, un vrai bloc détruit et la sortie d'une recette du menu 2 × 2.
+Le total de 40 XP atteint quatre niveaux ; une récompense d'ouverture seule
+permet un achat. Répétition, coffre, réception de planches, créatif/spectateur,
+désactivation et changement de montant n'offrent aucun gain supplémentaire indu.
+Le même instantané joueur recharge l'XP et ses étapes ; le respawn et un vrai
+New Game+ conservent les étapes, sans recréditer les points perdus.
+
+Les contrôles purs vérifient les champs inconnus/manquants/dupliqués, schémas
+futurs, montants fractionnaires/négatifs/hors limite et configurations invalides
+sans écrasement. Le schéma de progression reste 8.
+
+Le client natif (`runClientGameTest -PsanctuaryClientTests=true
+-PsanctuaryTutorialClientTests=true`) passe également : E rapporte 8 XP,
+vingt répétitions du message ne rapportent rien, puis l'achat du premier cœur
+fonctionne. Les six icônes et les libellés FR/EN sont contrôlés à l'écran.
+Capture : `mods/sanctuary/build/run/clientGameTest/screenshots/0001_sanctuary-beta016-tutorial-xp-fr_fr.png`.
+
+Export local vérifié : [Sanctuary-beta.016.mrpack](../build/Sanctuary-beta.016.mrpack),
+2 549 212 octets, SHA-256
+`79f92b05d41c35d7408298831d1ac9edb18be9f86349400fdc044ee1ef37e60c`.
+Versions internes, dépendance Fabric API, intégrité ZIP et icônes identiques aux
+sources du resource pack contrôlées (`build/tutorial016-artifact.json`).
+Les exports beta.003–015 sont inchangés. Aucun déploiement personnel effectué.