# beta.063 — audit du chargement et règle de jeu Sanctuary

> Suite livrée dans [beta.064](loading-cache-beta064.md) : cache des plans et
> étapes réelles sur fond uni, sans le portail de la proposition ci-dessous.
> L’audit et les mesures beta.063 restent conservés ici.

Branche `codex/loading-audit-gameplay-beta063`, après beta.062 conservée.

## Contrat

L'audit mesure séparément le démarrage du client, la création du terrain,
Hello World, l'introduction et l'arrivée. Il compare une île neuve, sa
réouverture, un monde plat et un monde Minecraft classique, sans utiliser
de sauvegarde personnelle. L'habillage du préchargement est une proposition
à examiner, pas une optimisation de terrain déjà livrée.

La règle native `sanctuary:use_sanctuary`, « Utiliser Sanctuary », permet
de choisir les règles Sanctuary à la création d'un monde, indépendamment
de son générateur. Elle est activée par défaut dans le pack ; la désactiver
avant la création conserve les capacités ordinaires du joueur. Activée sur
un monde plat ou classique, elle apporte Hello World, la progression,
l'inventaire, les familiers, les factions et les systèmes qui en dépendent,
ainsi que les modes temporel et météorologique Sanctuary.

Cette règle ne change jamais le générateur, le spawn natif, les chunks ou les
structures du monde choisi. Les fonctions propres aux îles et aux expansions
restent réservées à ce terrain. Les ressources et ajouts autonomes du mod
restent chargés, y compris quand cette règle est désactivée.

Le choix est fixé pour la partie : les commandes et options d'une partie
déjà ouverte ne peuvent pas le basculer. Le serveur conserve le choix natif
dans `level.dat` ; les données existantes d'habitant continuent d'identifier
une partie Sanctuary lors des réouvertures. Pas de nouveau format propriétaire.
Les parties Sanctuary et le module plat de test antérieurs conservent leur
admission historique ; la protection existante des anciennes parties sans
progression reste appliquée. Aucun Overworld classique déjà joué n'est
converti automatiquement. Une conversion reste hors de cette livraison,
conformément à la précision de l'utilisateur.

## Mesures du 15 septembre 2026

Client natif Minecraft **26.3-pre-2**, Fabric **0.19.5**, API
**0.160.0+26.3**, Java 25 ; Mac Apple M1, huit processeurs logiques,
tas JVM 2 Gio. Une exécution par scénario dans le même client, dans cet
ordre, avec enregistrement JFR `profile`. Graine **42**, île Moyen **724**,
structures actives, distances de rendu et de simulation **8**. Les autres
applications du bureau restent ouvertes. Ce sont des observations locales,
pas une moyenne représentative ni une preuve de gain entre versions.

Le compteur commence à la demande de création/ouverture. « Jouable » signifie
joueur présent, écran de jeu actif et fondu d'arrivée terminé. Hello World est
validé automatiquement ; le temps passé à choisir son personnage est exclu.
L'introduction complète reste active, même sur les terrains Minecraft.

| Scénario | Hello World prêt | Fin de la séquence d'introduction | Jouable |
| --- | ---: | ---: | ---: |
| Nouvelle île Sanctuary | 74,292 s | 103,889 s | **122,101 s** |
| Réouverture de cette île | Déjà accompli | Non rejouée | **58,701 s** |
| Nouveau monde plat + Sanctuary | 0,929 s | 30,489 s | **33,246 s** |
| Nouveau monde classique + Sanctuary | 3,809 s | 33,458 s | **37,632 s** |

Le premier lancement du processus client jusqu'au début du parcours au menu
prend environ **15 s**, en plus de ces durées. Il utilise les ressources déjà
présentes sur cette machine : ce n'est pas une installation ou un cache disque
à froid. Le profilage commence aux scénarios monde ; ce démarrage client est
chronométré, mais pas attribué fonction par fonction.

## Ce qui se passe réellement

1. Le client charge les classes, ressources, textures et sons. L'enregistrement
   des services Sanctuary n'est pas encore la planification complète des îles.
2. Après « Créer », le serveur intégré construit les niveaux. Dans
   `ExpansionRuntime.register`, l'événement `ServerLevelEvents.LOAD` prépare les
   plans du générateur : eau, traversées, réseaux souterrains, sanctuaire minier,
   patrimoine, village et expéditions. Cette étape bloque l'accès à Hello World.
3. Le serveur choisit le spawn et prépare les chunks d'arrivée. La configuration
   réseau ouvre Hello World puis l'introduction ; une partie de la préparation
   du monde continue pendant ces **29,5 s** de cinéma.
4. La séquence se termine, mais le monde peut ne pas être prêt. L'écran blanc
   couvre alors l'attente, puis le fondu rend le jeu visible. Sur l'île mesurée,
   environ **18,2 s** séparent la fin de l'intro de l'état jouable.

La première planification de l'Overworld occupe environ **58,8 s** entre
`SERVER_STARTING` et la fin de son événement `LOAD`. À la réouverture, elle
occupe encore **56,8 s**. La majeure partie de ces plans est recalculée à chaque
nouvelle instance du générateur ; le journal aérien existant ne met pas tous
les autres plans en cache.

Le `Time elapsed` natif est trompeur pour cet audit : il annonce **434 ms** à
la réouverture alors que l'entrée prend **58,7 s**. Ce compteur démarre après
les calculs lourds. Il ne doit pas servir seul de mesure du chargement complet.

## Où part le CPU

Les journaux de cette réouverture attribuent **23,913 s** aux traversées,
**14,590 s** au patrimoine, **7,758 s** au sanctuaire minier et **2,999 s** au
village. L'hydrologie annonce **13,052 s**, mais elle est appelée pendant la
préparation des traversées : **ne pas additionner ces deux durées**.

Dans les échantillons JFR des méthodes Java en exécution à la réouverture :

| Méthode | Part des échantillons |
| --- | ---: |
| `SmearedPerlinNoise.addToVolume` | 37,81 % |
| `NoiseStack.Perlin.get` | 22,80 % |
| `GradientNoise.permute` | 8,51 % |

Ces trois fonctions de bruit totalisent **69,12 %** des échantillons. Ce n'est
ni une part exacte du temps mural ni un gain récupérable annoncé. Les pauses
GC totalisent **838 ms** sur le profil de réouverture, contre **1,71 s** pour
la création de l'île. La pression mémoire existe, mais elle n'explique pas
l'essentiel de cette attente ; augmenter seulement la RAM ne cible pas le
coût dominant identifié.

Les profils incluent quelques secondes de jeu et la fermeture du monde.
Une première tentative avec `waitForChunksDownload()` a attendu la complétion
du rendu au-delà de l'arrivée jouable ; elle est conservée à part et exclue
des résultats ci-dessus. Les assertions finales utilisent la présence du joueur,
l'écran natif et la fin du fondu, pas ce critère plus strict du banc de tests.

Sources : `ExpansionRuntime.java:35`, `SanctuaryChunkGenerator.java:93` et `:291`,
`ProgressionService.java:194`, `IntroScreen.java:51` et `:170`,
`IntroSpawnFlash.java:20`. Les appels répétés à `prepareTransit` sont gardés :
certains sont protégés et certains prennent en compte les liens du patrimoine.
L'audit n'en déduit pas qu'ils peuvent simplement être supprimés.

## Habillage proposé, après retour utilisateur

**Conserver toute l'introduction**, sa durée, sa musique au dévoilement du
portail et son flash. L'habillage proposé concerne uniquement l'attente qui
précède Hello World et la réouverture d'une partie.

Écran sobre proche de Minecraft : fond sombre uni, portail natif au centre,
texte Minecraft discret et bouton Annuler natif. Aucun grand logo ajouté,
aucune carte décorative, aucun encadrement ni panneau de diagnostic permanent.
Les textures du portail, de l'obsidienne, du bouton et la police bitmap de la
proposition proviennent des ressources locales de Minecraft 26.3-pre-2.

Le texte décrit l'étape réelle : ressources, calcul du terrain, préparation
des alentours. Une barre et un compte de chunks peuvent apparaître uniquement
lorsque leur total est connu ; les calculs de plans restent sans faux pourcentage.
Le compteur `86 / 225` de la maquette est un exemple d'état, pas une mesure.
Annuler demande un arrêt propre au serveur, sans quitter au milieu d'une
écriture. Son comportement réel devra être intégré et testé avec l'écran.

La proposition interactive a été simplifiée après rejet de la première
direction. **Elle n'est pas intégrée au rendu du jeu dans beta.063.**

## Prochains tickets proposés

| Priorité | Résultat vérifiable | Garde-fous / validation |
| --- | --- | --- |
| 1 — Cache des plans | Réouvrir une île en relisant ses plans dérivés validés | Clé graine, révision de génération, paramètres et configurations ; écriture atomique ; corruption ou cache absent → recalcul ; comparaison exacte des plans et chunks, sans régénérer de monde utilisateur. Contrat de cache à formaliser avant développement. |
| 2 — Préchargement natif | Afficher l'écran épuré dès le début de la création et à la réouverture | Phases instrumentées, fermeture propre, texte FR/EN, annulation et erreur visibles ; intro intacte ; mesures du coût de l'écran. |
| 3 — Réutiliser les sondages | Éviter les colonnes de terrain recalculées entre plusieurs planificateurs | Cache borné, mêmes entrées et mêmes valeurs, empreintes bit à bit sur plusieurs graines ; reprendre la méthode de `docs/initial-loading.md`. |
| 4 — Travail en parallèle | Réduire le chemin critique restant après les caches | Seulement sur données immuables ; aucun accès au niveau Minecraft depuis des threads arbitraires ; gains mesurés et déterminisme vérifié. |

Aucun gain de ces futurs tickets n'est compté comme livré. La génération et
ses paramètres sont inchangés dans beta.063. La proposition respecte le choix
de conserver l'intro ; l'attente blanche mesurée reste un constat, pas une
modification autorisée de cette séquence.

## Utiliser la règle de jeu

À la création d'un nouveau monde, choisir le terrain **classique** ou
**plat**, puis laisser **Utiliser Sanctuary : Oui** dans les règles de jeu,
catégorie Joueur. Hello World et les règles Sanctuary s'appliquent au terrain
natif. Les capacités ordinaires sont conservées avec **Non**. Ce choix ne
nécessite pas une installation du module de test rapide.

`/gamerule sanctuary:use_sanctuary` permet de consulter le réglage. Une tentative
de changement en jeu est refusée avec une explication FR/EN ; les autres règles
restent modifiables. La capture du choix se fait au chargement de l'Overworld :
dans cette version, `getGlobalGameRules()` n'est pas disponible avant sa création.

## Vérifications

- Audit client natif : île neuve, même île réouverte, plat et classique neufs,
  intro complète ; `LOADING063_AUDIT_PASS`.
- Parcours fonctionnel client et serveur intégré : plat/classique × activé/
  désactivé, chacun créé puis réouvert, soit **8 ouvertures** ;
  `GAMEPLAY063_PASS`. Vérifie Hello World uniquement si activé, sa non-répétition,
  le familier initial conservé, les 3/10 cœurs et 1/4 rangées selon le mode,
  l'absence de session d'expansion sur terrain natif, le temps et la météo.
- Vérifie le refus des mutations en jeu des règles globales et du niveau,
  le refus explicite de la commande et la modification d'une autre gamerule.
  Libellé et description natifs testés en français et en anglais.
- La non-conversion des anciens mondes classiques repose sur la garde
  d'admission examinée dans le code ; aucun monde personnel n'est ouvert.

Commandes reproductibles (Java 25) :

```sh
./gradlew :sanctuary:runClientGameTest -x :sanctuary:runGameTest \
  -PsanctuaryClientTests=true -PsanctuaryLoading063ClientTests=true \
  -PsanctuaryQuickTests=true -PsanctuaryClientNoVsync=true

./gradlew :sanctuary:runClientGameTest -x :sanctuary:runGameTest \
  -PsanctuaryClientTests=true -PsanctuaryGameplay063ClientTests=true \
  -PsanctuaryQuickTests=true -PsanctuaryClientNoVsync=true
```

Preuves locales ignorées : `build/loading063-audit.log`,
`build/loading063-evidence/timings.tsv` (extrait des événements du journal),
les deux profils JFR d'île et leurs vues CPU/GC dans ce même dossier,
`build/gameplay063-client.log`. Les JFR plat/classique du dossier temporaire
du runner ont été nettoyés au test suivant ; leurs chronométrages restent dans
le journal intégral. Archiver `mods/sanctuary/build/run/clientGameTest/loading063/`
avant de relancer un parcours pour conserver tous les profils.

`./gradlew check build assemblePack assembleTestPack` réussit en **2 min 22 s**,
avec `-x :sanctuary:runGameTest -PsanctuaryClientTests=true
-PsanctuaryGameplay063ClientTests=true -PsanctuaryQuickTests=true
-PsanctuaryClientNoVsync=true`. Les tests serveur dédiés restent exclus, selon
le refus antérieur d'accepter leur EULA ; les huit ouvertures ci-dessus utilisent
le serveur intégré au client natif et vérifient réellement les règles côté serveur.

Les deux archives locales sont vérifiées : dépendances exactes, ZIP, identité
des **1 628 classes compilées**, ressources, absence de classes de test, même
contenu normal/Test sauf le module rapide. Le JAR, les classes d'introduction,
les ressources et les sons non concernés sont comparés à beta.062 ; le terrain
et toute la séquence d'introduction restent identiques. Les anciens packs
beta.062 sont conservés avec leurs empreintes originales.

- [Pack normal beta.063](../build/Sanctuary-beta.063.mrpack), SHA-256
  `1af1ff168f5cf97d7f44bb28398eb79efae8e1c4858f05d5b4291b1dfe48ad93`.
- [Pack Test beta.063](../build/Sanctuary-Test-beta.063.mrpack), SHA-256
  `405a55e76233c8403f27320f104e09ee590cae652b97b4396dd6a5b1a7dd0531`.

Reçu `build/loading063-artifact.json`, build `build/loading063-check.log`.
Pas de déploiement Prism, de changement de canal ou de sauvegarde personnelle.