Synchronize verified Sanctuary beta.092 sources and release documentation

docs/super-pistons-beta087.md

@@ -0,0 +1,110 @@
+# beta.087 — Super piston et super piston gluant
+
+## Contrat de sauvegarde avant implémentation
+
+Assemblage volontaire à la clé dorée d'un carré plein de neuf pistons
+rétractés, identiques et orientés dans la même direction. Deux clics de
+confirmation ; les six directions sont admises. Sans cette action, les
+pistons restent indépendants. Aucun changement de la génération ni des
+registres de Fourneau et de Fût.
+
+Les neuf composants deviennent des blocs `sanctuary:super_piston` ou
+`sanctuary:super_sticky_piston`, identifiés par leur orientation et leur
+position dans le carré. Le composant central porte une BlockEntity dédiée,
+schéma 1 : course engagée (0 à 3) et liste des déplacements natifs en cours.
+Les états intermédiaires utilisent les moving pistons
+natifs, avec leur état de bloc et progression sérialisés par Minecraft.
+Les pièces de tête et de tige sont des blocs techniques sans objet récupérable.
+Aucun inventaire ni copie de charge n'est conservé dans le contrôleur.
+
+Un signal redstone sur un des neuf composants demande la sortie ; sa
+coupure demande le retour. Trois pas animés d'un bloc. Chaque pas est planifié
+entièrement avant mutation : obstacle intermédiaire, hauteur, frontière du
+monde, charge et présence des chunks. Aucune charge de chunk forcée.
+L'animation engagée finit avant d'entamer le pas suivant ou d'inverser.
+Après rechargement, les animations natives finissent et le contrôleur reprend
+à partir de l'état courant, sans rattrapage temporel ni restitution d'une
+copie initiale. Les sauvegardes suivent l'atomicité native des chunks ; pas de
+journal inter-chunks pour un crash brutal pendant une sauvegarde.
+
+La charge commune conserve les règles natives d'indéplaçabilité et les
+liaisons slime/miel. Une poussée bloquée suspend l'ensemble de la tête ;
+une traction impossible laisse la charge en place et permet au gluant de
+rentrer, comme un piston natif. Les coffres et autres inventaires indéplaçables restent en place. Les blocs
+que les pistons natifs cassent, notamment les boîtes de Shulker, déposent
+leur objet avec son contenu.
+Le piston normal ne tire pas au retour. Les collisions et le déplacement des
+entités utilisent les moving pistons natifs.
+
+Maj-clic avec la clé dissocie une machine rétractée et désalimentée. Une
+machine active demande de couper son alimentation et de la laisser rentrer.
+Casser une pièce dissocie la structure : les bases restantes redeviennent
+leurs pistons d'origine, les pièces techniques disparaissent sans butin ;
+seuls les composants effectivement cassés déposent leur piston. Les charges
+déjà déplacées restent à leur position actuelle, les animations de charge
+engagées finissent normalement. Une moitié déchargée attend son chargement
+pour valider ou nettoyer ses pièces ; aucun bloc étranger n'est écrasé.
+
+## Valeurs et utilisation
+
+Charge totale acceptée : **108 blocs distincts**, commune aux neuf cases,
+liaisons slime/miel incluses. Ce n'est pas une limite de 12 par colonne.
+Les neuf pistons doivent être du même type, orientés pareil, rétractés et
+sans alimentation. La clé dorée montre d'abord le carré ; un deuxième clic
+sous dix secondes confirme l'assemblage. Maj-clic sur un piston indépendant
+permet de l'orienter vers la face cliquée. Un carré ambigu dans une surface
+plus grande est refusé plutôt que de sélectionner des composants au hasard.
+
+Un signal reçu par n'importe lequel des neuf composants fait avancer la tête
+commune jusqu'à trois blocs. La coupure la fait rentrer ; seule la variante
+gluante ramène la charge. Trois pas animés utilisent les collisions natives.
+Une charge en chunk absent suspend aussi le retour gluant, sans charger le
+chunk et sans l'abandonner comme si elle était un obstacle indéplaçable.
+
+## Apparence
+
+Les cinq PNG fournis sont conservés octet pour octet. Les faces 48 × 48 sont
+réparties sur les neuf composants ; la bande de côté 48 × 16 fait le tour
+du socle. **Les quatre pixels avant partent avec la tête** : le corps ouvert
+ne conserve que douze pixels, avec la texture intérieure reculée et une
+seule tige centrale qui comble l'intervalle. Les UV du côté sont découpés,
+non étirés. Modèles, collisions et retour animé suivent cette géométrie dans
+les six orientations, pour les deux variantes.
+
+La synchronisation utilise les états et données des moving pistons natifs.
+Le client initialise la BlockEntity des seuls paquets marqués par cette
+machine avant leur chargement natif : un simple paquet d'état de bloc ne
+crée pas la BlockEntity d'un moving piston.
+
+## Vérifications
+
+Parcours natif dans un monde plat neuf, graine 87, serveur intégré : douze
+combinaisons direction/variante, assemblage réel à la clé, charge de 108,
+refus à 109, obstacle au deuxième pas puis reprise, coffre immobile avec son
+stock, boîte de Shulker cassée avec ses 17 diamants conservés, liaison slime
+au-delà de la face, séparation slime/miel, retour gluant, transport vertical
+d'une entité, coupure pendant l'animation, sérialisation des mouvements,
+déchargement puis retour dans les chunks et démontage après casse.
+
+Le test vérifie aussi la réception côté client des têtes en mouvement et du
+retour final, les collisions de 12/4 pixels dans les six directions, le refus
+hors hauteur et la suspension sur un chunk absent sans le charger.
+Journal : `build/piston087-client.log` (succès, 1 min 20 s).
+Captures inspectées : `build/piston087-screenshots/`, notamment
+`0015_piston087-normal-face-open.png` et `0016_piston087-sticky-face-closed.png`.
+
+Les essais à deux clients LAN distincts et avec un moteur de shaders tiers
+restent à réaliser. Aucun serveur dédié démarré et aucune EULA acceptée.
+
+`check build assemblePack assembleTestPack` a réussi en 2 min 29 s
+(124 tâches, 104 exécutées), avec `:sanctuary:runGameTest` exclu pour respecter
+le choix de tests client uniquement. Journal : `build/piston087-check.log`.
+Le reçu `build/piston087-artifact.json` vérifie les 55 nouveaux assets, les
+13 nouvelles classes, l'identité des cinq PNG, la conservation des assets
+précédents, les sources embarquées et les archives. Les autres classes
+existantes restent identiques, à l'exception du raccord dans `Multiblocks`.
+
+Archives locales : `build/Sanctuary-beta.087.mrpack` et
+`build/Sanctuary-Test-beta.087.mrpack`. Les archives beta.086 sont inchangées.
+Aucun déploiement dans Prism ni sur le canal publié ; aucun monde personnel
+modifié. Le pack de ressources intégré conserve sa version beta.070.