sanctuary-beta/docs/head-cosmetics-beta021.md

# beta.023 — cosmétiques de tête interactifs

Ticket commencé en beta.021 le 13 septembre 2026, branche
`codex/head-cosmetics-beta021`. Finalisation en beta.023 après le correctif
de chargement beta.022 préparé dans un autre espace de travail.

## Contrat avant implémentation

Le slot tête reste un objet réel, sans protection, collision, redstone ou effet
de bloc. Les œufs sur la tête gardent leur rendu d’objet. Les autres accessoires,
familiers et pouvoirs ne changent pas.

Les bannières utilisent leurs couleurs et motifs natifs, y compris la bannière
menaçante. Lits et portes ont leurs deux moitiés. Les minecarts utilisent leur
modèle d’entité sans créer d’entité dans le monde. Feuilles, verre et toile
d’araignée enveloppent la tête. Les panneaux utilisent leur texte natif.

Clic droit sur un autre porteur : écrire sur son panneau, ajouter une bougie
au gâteau avec une bougie en main, allumer avec briquet ou boule de feu,
éteindre à main vide, changer la pose d’une statue de golem à main vide.
Une bougie éteinte sur un gâteau peut être retirée à main vide et est rendue.
L’ajout consomme une bougie hors créatif ; allumer use le briquet ou consomme
la boule de feu. Aucun feu ni lumière de bloc n’est créé dans le monde.
Maj garde le geste de portage. Les trois interactions bougie/gâteau/statue sont
aussi accessibles par clic droit sur la case cosmétique dans l’inventaire,
avec l’objet au curseur. Un curseur vide éteint, retire la bougie ou change la
pose ; la bougie retirée revient au curseur. Clic gauche retire normalement
le cosmétique et Maj-clic conserve le transfert natif. Aucun bouton supplémentaire.
Le porteur ne peut jamais écrire sur son propre panneau, même opérateur.

Les huit emplacements d’équipement ont une infobulle de rôle : tête, buste,
jambes, pieds, main secondaire, familier, cape et cosmétique. Elle reste présente
avec un objet équipé, à côté des informations natives de cet objet.

## TNT : exception de gameplay demandée

Un coup infligeant des dégâts amorce la TNT équipée. L’objet est consommé,
remplacé par une vraie TNT native avec une mèche de 80 ticks (4 secondes à
20 TPS), qui suit la tête. Retirer ou remplacer le cosmétique n’annule rien.
La mort, la déconnexion ou le changement de dimension la détachent au dernier
endroit, où elle poursuit sa mèche. Son explosion native endommage les entités
et les blocs selon les règles du serveur, avec l’attaquant comme responsable
lorsque possible. Une seule TNT peut être amorcée sur un même porteur à la fois.
Aucune immunité nouvelle n’est accordée au porteur. La TNT utilise sa sauvegarde
native (position et mèche) ; après redémarrage elle reste au dernier lieu sauvé.

## Stockage et réseau

Le schéma 1 des accessoires reste inchangé. Les composants natifs de la pile
portent `sign_text_front`, `sign_text_back`, `banner_patterns` et `block_state`.
Le gâteau reçoit uniquement une clé additive `sanctuary:head_candle` dans
`custom_data`, contenant l’identifiant de sa bougie. L’absence de cette clé
signifie un gâteau ordinaire. Elle ne transforme pas la pose native du gâteau
en bloc : retirer sa bougie avant de le poser permet de la récupérer.
Toutes les autres données de l’objet sont préservées. Les piles existantes
sont lues sans migration ni réécriture de monde.

Le serveur valide proximité, visibilité, objets, coût et état courant. L’éditeur
natif de panneau est relié à un paquet dédié, jamais au paquet d’édition d’un
bloc du monde. Une session temporaire et un instantané de l’objet empêchent
d’écrire sur un panneau remplacé ou à distance. Le texte accepté est constitué
de quatre lignes sans commandes, avec le filtrage de texte natif du serveur.
Le client et le serveur de cette livraison utilisent `head_cosmetics_v2`.
La version 2 distingue l’interaction avec l’objet au curseur de l’ancien bouton
utilisant la main principale ; un ancien client est refusé à la connexion
pour éviter de donner deux sens différents au même geste. Client et serveur
doivent être mis à jour ensemble.

## Validation

Livraison locale **beta.023**, client et serveur de même version.

- `./gradlew check build assemblePack :sanctuary:runClientGameTest` réussi,
  avec les suites cosmétiques, accessoires, familiers, progression, mouvement,
  inventaire, transferts, rangement, cycle, minage, construction, premiers pas
  et optimisation : **117 tests serveur**, puis parcours client natif.
- Actions au curseur : bougie consommée une seule fois, briquet usé ou cassé,
  extinction puis restitution au curseur, main principale conservée. Un menu
  de coffre ouvert refuse le paquet réservé à l’inventaire personnel.
- Clic gauche retire le cosmétique ; le clic droit d’un panneau personnel
  garde le transfert natif et n’ouvre pas l’éditeur. Le mixin ignore Maj.
- Autre joueur : vrais clics sur panneaux classiques/suspendus, éditeur natif,
  texte réseau puis rendu. Motifs menaçants et seize couleurs de bannières,
  deux moitiés de portes/lits, six minecarts, verre/feuilles/toile et œuf inchangé.
- TNT : dégâts réels, coup fatal avant les drops, quatre secondes de mèche,
  suivi et explosion native malgré le retrait du cosmétique.
- Optimisation beta.022 intégrée : **588 288 comparaisons bit à bit** réussies
  et classes de densité identiques à celles du précédent pack vérifié.
- ZIP, versions, dépendances exactes, JAR embarqué et Demeure imbriqué vérifiés.
  Exports beta.020/beta.022 immuables ; PNG existants conservés ; aucun test
  ni monde distribué. Sources figées pendant la construction finale.

Commande de vérification :

```sh
./gradlew check build assemblePack :sanctuary:runClientGameTest \
  -PsanctuaryClientTests=true -PsanctuaryHeadCosmeticsClientTests=true \
  -PsanctuaryFocusedTests=cosmetics,accessories,familiar,companions,progression,movement,inventory,inventoryflow,sorting,cycle,mining,building,tutorial,startup
```

Export : [Sanctuary-beta.023.mrpack](../build/Sanctuary-beta.023.mrpack).
SHA-256 : `2140d477f2e105884ffdfe8d3d7a1199a1fdf3d298ad97dc7880c89918eb22c4`.
Preuves ignorées : `build/cosmetics023-artifact.json`,
`build/cosmetics023-check-build.log`, captures du client et diagnostics serveur.

Les essais graphiques ont lieu sur Mac M1, dans un monde de développement
neuf, avec un second avatar serveur de test ; aucune session distante réelle,
ni validation Windows, ni installation Prism n’est revendiquée. Le portage
JEI est le [ticket suivant](recipes-jei-beta022.md), pas une fonction de ce pack.