sanctuary-beta/docs/tutorial-xp-beta016.md

# 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é.