sanctuary-beta/docs/familiar-interactions-beta020.md

# beta.020 — interactions, lecture des œufs et plongeon

Ticket du 13 septembre 2026, branche `codex/familiar-interactions-beta020`.
**Livraison locale beta.020 vérifiée — 13 septembre 2026.**

## Demande retenue

- Maj + clic droit sur un joueur : monter sur sa tête. Sur un animal : le porter,
  puis refaire le geste pour le déposer. Le porteur est ralenti et les coups entre
  porteur et passager sont interdits. Une seule place, sans empilement dans beta.020 ; les piles sont ajoutées par
  [beta.027](player-stacks-beta027.md).
- Caresser le familier ne produit que des cœurs. Le clic gauche provoque une
  réaction visuelle de coup sans retirer de vie. Préférer son modèle bébé natif.
  [beta.029](familiar-hit-feedback-beta029.md) ajoute le cri de l’espèce et le recul.
- Nommer l’œuf à l’enclume ou utiliser une étiquette sur son propre familier.
  Le nom appartient à l’œuf ; déséquiper l’œuf fait disparaître le compagnon.
- Nom de l’œuf coloré par rareté : blanc, jaune, vert, bleu, violet.
  L’infobulle présente les noms cryptiques du passif et de l’actif. L’aptitude
  **Étude des familiers**, à quatre niveaux, révèle les explications.
- Retirer l’écran Familier des aptitudes et le bouton d’activation du pouvoir.
  Les réglages et le carnet rejoignent Habitant. Les aides alliées sont acceptées
  par défaut ; leur réglage reste personnel.
- Saut en sprint, puis touche S’allonger en vol : plongeon vers l’avant, une
  impulsion par saut. L’arrivée au sol ou dans l’eau termine cette posture.
  [beta.028](dive-until-collision-beta028.md) retire ensuite la limite de durée
  et ajoute explicitement les collisions au plafond.
- Taille aléatoire propre à chaque œuf, avec des familiers minuscules ou géants.

## Contrat de données

Les pièces jointes existantes, leurs schémas et les identifiants des œufs restent
stables. Un nouveau reçu indépendant `sanctuary:companion_study`, schéma 1,
conserve l’achat de l’aptitude après mort et prestige. Absent : aptitude verrouillée.
Invalide ou version inconnue : reçu conservé, achat et révélation refusés.
Les choix d’aide déjà enregistrés sont conservés ; l’absence d’état utilise
le nouveau défaut accepté. Les noms utilisent le composant natif `CUSTOM_NAME`.

Le portage et le plongeon sont temporaires. Aucun animal n’est converti en objet,
dupliqué ou remplacé : son UUID, ses équipements et ses données restent ceux de
l’entité native. Les animaux portés sont sauvegardés comme entités indépendantes,
sans enregistrer le portage dans les données d’un joueur. Une déconnexion, mort
ou transition de dimension termine le portage. Aucun monde personnel n’est
modifié par les outils de développement.

Client et serveur beta.020 doivent être installés ensemble. Cette livraison
conserve les prix et recharges des 88 pouvoirs et les règles d’obtention des œufs.

Le premier équipement d’un œuf sans taille ajoute au composant natif
`minecraft:custom_data` une entrée `sanctuary:familiar_size`, composée de
`schema: 1` et `per_mille: 120..6000`. Les autres données de l’objet restent
intactes. Les anciens œufs reçoivent ce trait lorsqu’ils sont équipés, sans
parcours des mondes ni conversion des inventaires existants. Un œuf équipé
occupe une case unique ; les œufs d’une pile sont individualisés lors de leur
équipement. Une copie de l’œuf déjà individualisé garde sa taille.

Le trait voyage avec l’objet lors d’un don, d’un renommage, d’une mort ou d’un
prestige, et survit à la sauvegarde/reconnexion. Une entrée inconnue ou invalide
est conservée telle quelle ; le rendu utilise alors la taille ordinaire.

## Pouvoirs de perception et téléportations

Les détections de blocs connus, le sonar, les circuits et les marques restent
visibles derrière les parois. Les téléportations Endermite / Enderman peuvent
traverser les murs ; le point d’arrivée reste libre et soutenu, dans la portée
et les zones autorisées. Le freinage d’une chute efface sa distance accumulée :
un atterrissage après le ralentissement ne réapplique pas les dégâts antérieurs.
Une nouvelle chute après la fin du pouvoir accumule à nouveau sa propre distance.

## Gestes dans le jeu

Maj + clic droit prend un animal ou monte sur un joueur. Un nouveau Maj + clic
droit dépose le passager même avec la main vide, sans devoir viser au-dessus de
sa propre tête. Le joueur porté relâche Maj puis appuie de nouveau pour descendre.
Le porteur se déplace 25 % moins vite ; la réduction disparaît dès qu’il est libre.
Les chats, loups et perroquets utilisent une pose assise ; les autres animaux
reposent au-dessus de la tête. L’espace occupé est vérifié avant de les porter.

Les noms utilisent l’œuf et l’étiquette natifs. Les modèles bébés sont choisis
lorsqu’un modèle bébé existe dans Minecraft ; aucune intelligence hostile n’est
appliquée au familier. La caresse garde uniquement les cœurs. Le coup léger est
une animation, sans dégâts, enchantement offensif ni usure de l’arme.

L’infobulle native affiche la rareté et deux noms d’effets. **Progression → Étude
des familiers** coûte 4 niveaux et ajoute les explications aux infobulles. Aucun
mod Item Description supplémentaire n’est nécessaire pour cet affichage.
**Habitant** contient le choix d’aide alliée et le carnet. **G** reste la touche
reconfigurable du pouvoir ; aucun bouton d’activation dans ces menus.

## Tailles des familiers

La taille est tirée par le serveur une seule fois, indépendamment de l’espèce et
de la rareté. Elle multiplie le modèle réduit du familier, bébé lorsque possible :

| Fréquence | Multiplicateur visuel |
| --- | --- |
| 90 % | ×0,65 à ×1,50 |
| 5 % | ×0,12 à ×0,35 |
| 5 % | ×2,50 à ×6,00 |

L’infobulle indique Minuscule, Petit, Ordinaire, Grand ou Colossal après le
premier équipement. Le nom affiché suit la hauteur du modèle et les volants
géants s’estompent en fonction de leur encombrement visuel. Les pouvoirs,
la vitesse et le corps utilisé pour la navigation restent identiques : la
taille visuelle ne bloque pas le compagnon dans une porte et ne modifie pas
l’équilibrage de son œuf. La zone d’interaction reste celle du familier mobile.

## Vérifications de livraison

- `./gradlew check build assemblePack -PsanctuaryFocusedTests=familiar,companions,accessories,movement,progression,cycle,mining,building,inventory,inventoryflow,sorting,tutorial` : contrôles purs et **104 tests serveur réussis**.
- Portage joueur/animal, position sur la tête, coups interdits, ralentissement, sauvegarde native sans duplication ni véhicule-joueur enregistré, dépose et conflit avec double-Maj.
- Achat de l’Étude facturé une fois, sauvegarde/rechargement, mort et prestige réel ; données invalides conservées et refus historique des aides maintenu.
- Taille tirée une fois, distribution bornée, données étrangères conservées, sauvegarde et transfert de l’œuf à un autre habitant sans changement de taille.
- Plongeon autorisé après départ en sprint, sans deuxième impulsion en vol ; sortie dans l’eau sans déverrouiller Nage. Poule freinant une chute déjà accumulée, nouvelle chute native ; sonar derrière un mur et téléportation au travers vers un espace libre.
- Deux parcours client natifs dans de nouveaux mondes de développement, graine 42 : achat et infobulles, Habitant aux échelles 2/3/4, Maj + clic droit réel pour porter/déposer, chat bébé assis, plongeon avec une touche reconfigurée et rendu horizontal, synchronisation de taille et captures des extrêmes.
- Les 88 modèles sont extraits à deux instants, puis aux multiplicateurs ×0,12 et ×6. Éclairage, fondu du corps et des yeux des volants, activation réelle avec G, recharge commune et échange de villageois restent validés.
- Le MRpack et les JAR sont contrôlés : CRC, versions exactes, identité du mod embarqué et de Demeure imbriqué, FR/EN, 88 passifs/actifs et leurs noms cryptiques, absence de code de test, sources identiques à celles du build. Les anciens PNG et l’export beta.019 restent inchangés.

Ces essais ne remplacent pas un équilibrage collectif des 88 paires de pouvoirs.
Le rendu et les gestes de portage ont été observés sur un client intégré ; les
interactions entre deux joueurs sont couvertes côté serveur, sans essai visuel
à deux clients. L’obtention des œufs, les rangs I–III et Anomaly restent à définir.
Aucune installation personnelle ni aucun canal de mise à jour n’a été modifié.

Export : [Sanctuary-beta.020.mrpack](../build/Sanctuary-beta.020.mrpack).
Reçu : `build/familiar020-artifact.json` ; captures : `build/familiar020-evidence/`.

SHA-256 MRpack : `98d1cdb8aa5b7b5249a4e23eabea963aff394cb416d8d78f7bc1bf49450c9e78`.
SHA-256 JAR : `3ec020eb381653f4cc53dad719338db9ec534c83f1c1a8552f0c77d42d3e739b`.