sanctuary-beta/docs/familiar-combat-beta054.md

# beta.054 — familiers de combat, duels et mises

Branche `codex/familiar-combat-beta054`. Cette version ajoute le combat physique,
les profils des 88 espèces, les ordres et les duels avec mises en objets. Le
catalogue de conception reste [la refonte](familiar-combat-design.md). La
validation des duels ci-dessous ne constitue pas une validation exhaustive de
chacun des comportements et services de vie commune des 88 fiches.

## Compatibilité et migration additive

- Les identifiants d'objets, d'entités, d'aptitudes et de sauvegardes existants
  restent stables. Aucun monde personnel n'est ouvert ou modifié par les tests.
- Un ancien œuf équipé reçoit une identité individuelle au premier usage du
  nouveau système. Son objet, son nom, sa taille et ses autres composants sont
  conservés. Les œufs non utilisés ne sont pas réécrits.
- L'identité utilise une entrée séparée de `custom_data` ; la santé, le K.-O.,
  les techniques et souvenirs utilisent un registre versionné séparé du monde.
  Les registres historiques de progression et de pouvoirs restent lisibles.
- Un identifiant ou schéma inconnu est conservé et désactivé, jamais converti
  silencieusement en un nouveau compagnon. Une copie du même œuf représente le
  même individu ; elle ne crée pas une réserve de santé supplémentaire.
- Retrait, transfert, mort, prestige et reconnexion ne réinitialisent ni la vie
  ni les délais. Un seul exemplaire d'un individu peut être actif sur le serveur.
- Les futures espèces disposent de profils nommés et versionnés ; leur retrait
  temporaire conserve les données de leurs individus pour une réinstallation.
- Revenir à beta.053 masque les données nouvelles sans les supprimer. Les
  modifications faites avec une ancienne version ne sont pas une synchronisation
  inverse du combat : sauvegarder le monde avant tout retour de version.

## Règles de cette livraison

Un compagnon actif, combat en temps réel, actions émises depuis sa position.
Suivre, engager, protéger et rappeler ; G lance la technique équipée et une
touche configurable ouvre les ordres. Les signatures sont immédiatement
accessibles ; le Lien actif déjà acheté garde sa valeur pour les variantes.
Les nouveaux menus réutilisent les contrôles et textures natifs.

Le combat termine après une période sans engagement réel. Rappeler reste
possible immédiatement ; changer d'individu attend la fin de cette période.
Les dégâts ennemis peuvent provoquer un K.-O., jamais détruire l'œuf. Les
caresses et coups amicaux gardent leur retour visuel et sonore sans dégâts.
Les soins utilisent des ressources réelles et le repos hors combat.

Les attaques autonomes et les nouvelles techniques de combat préservent le
terrain. Les anciens usages de travail, dont démolition et allumage, sont
séparés et explicitement sélectionnés hors combat ; leurs droits et ressources
restent applicables. Les anciens bonus de combat ne s'ajoutent pas aux nouveaux.
Le consentement allié, les factions et le réglage PvP s'appliquent côté serveur.

## Duels entre joueurs

### Duels et mises — contrat ajouté le 15 septembre

Les deux joueurs acceptent une invitation locale, puis valident chacun les deux
mises affichées. Une mise est facultative et contient au plus une pile d'objets,
avec ses composants natifs. Les cases de l'inventaire débloqué servent à choisir
la pile (clic) ou un objet (clic droit). L'emplacement de mise est un aperçu :
les objets restent dans l'inventaire jusqu'à la double validation. Toute
modification annule les validations ; une ancienne révision ne peut accepter
une nouvelle offre. Les quantités sont revérifiées et retirées côté serveur.

Trois secondes de préparation, trois minutes de combat maximum. Les permissions
du duel concernent exclusivement les deux familiers, même entre alliés ou quand
le PvP général est désactivé. Les propriétaires peuvent donner les ordres et
utiliser leurs techniques, mais ne frappent pas directement le familier adverse.
Le terrain reste soumis au contrat du combat. Pas d'apprentissage par duels.
Vie et recharges réelles persistent après le résultat ; aucune guérison de duel.

K.-O., abandon explicite, rappel, changement d'individu ou sortie du périmètre
de 24 blocs donnent la victoire à l'adversaire. Une interruption technique,
déconnexion ou expiration sans gagnant restitue les mises. Le résultat indique
les dégâts, impacts et techniques pour faciliter les essais. Une déconnexion
volontaire reste indistinguable d'une coupure réseau : ces paris amicaux ne
constituent pas un classement compétitif résistant à ce comportement.

Le gagnant reçoit les deux mises. Un inventaire plein conserve le paiement dans
le registre, accessible depuis Duel. Aucun gain n'est lâché au sol. Le nouveau
fichier `sanctuary/familiar-stakes-v1.json` et le reçu joueur additif
`sanctuary:familiar_duel_receipt` forment le contrat de transaction : journal
écrit avant le débit, inventaire et reçu sauvegardés ensemble, résultat écrit
avant paiement, puis accusé de réception sauvegardé avant purge du journal.
Dans 26.3-pre-2, l'hôte solo est lui aussi sauvegardé dans `playerdata` ;
`level.dat` conserve son `singleplayer_uuid`, pas son inventaire.
La reprise d'un journal encore actif restitue les objets réellement débités ;
un résultat déjà enregistré conserve son gagnant. Une erreur ou un schéma
inconnu désactive les paris et préserve les données pour récupération.

Retour à beta.053 : ne pas jouer avec des mises en attente. Terminer les duels
et récupérer tous les objets avant un retour de version ; sinon restaurer la
sauvegarde complète correspondante, jamais uniquement le journal ou un joueur.
Ces ajouts ne réécrivent aucun monde historique hors de la migration paresseuse
explicitée plus haut. Les tests utilisent exclusivement des mondes de développement.

## Niveaux stockés — contrat du 15 septembre

La fiche du familier permet de déposer ou retirer l'XP hors combat et hors
invitation/duel. Les montants sont des points d'XP exacts : un cran correspond
à la prochaine frontière de niveau du familier au dépôt et au niveau entier
inférieur au retrait, suivant la courbe Minecraft.
« Tout déposer » et « Tout retirer » conservent également les points partiels.
Le niveau est attaché à l'individu dans l'œuf et suit les échanges, jamais au
joueur. Chaque niveau donne +2,5 % de vie maximale et +1,25 % de dégâts,
sans plafond de progression de jeu. La rareté monte d'un palier tous les dix
niveaux, jusqu'à légendaire ; les statistiques continuent ensuite à progresser.
Changer la charge conserve la vie courante absolue (bornée par le nouveau
maximum) et ne soigne pas. Les délais et souvenirs sont conservés.

Migration additive explicite : les individus de schéma 1 se lisent avec zéro
XP ; leur prochaine écriture produit le schéma 2 avec `storedXp`. Le registre
extérieur reste `familiars-v1.json`. Les schémas inconnus restent préservés.
Un nouveau journal `sanctuary/familiar-xp-v1.json` contient uniquement les
transferts en attente. Le reçu joueur `sanctuary:familiar_xp_receipt` est
sauvegardé avec l'XP native avant de valider la nouvelle charge du familier.
Une reprise termine uniquement une opération dont ce reçu existe ; autrement,
elle l'annule sans crédit. Un individu avec transfert non résolu est gelé
jusqu'à la reconnexion du joueur concerné. Une erreur conserve le journal et
désactive les transferts. Le compteur utilise des entiers 64 bits ; une
opération dépassant la représentation native du joueur est refusée sans perte.
Les copies d'un œuf partagent le même solde serveur. Avant un retour à une
ancienne version, retirer l'XP et terminer tous les transferts ; restaurer une
sauvegarde complète plutôt que des fichiers individuels.

Les points de vie sont conservés dans les unités du profil de base, puis
convertis en réserve effective pour les dégâts et les affichages Sanctuary.
Cela permet de dépasser la limite de l'attribut natif de santé, sans introduire
un plafond caché à la progression. Les soins et le repos restaurent la même
fraction de la réserve qu'avant cette extension.

## Vérifications

Sur Minecraft 26.3-pre-2, Java 25, dans un monde plat de développement :

- `Combat054ClientChecks` : chargement des 88 profils, attaque autonome du loup
  depuis son entité physique, blessure persistante, sauvegarde et vraie
  reconnexion ; menus FR/EN.
- `Duel054Checks` : deux entités `ServerPlayer`, invitation, double validation,
  changement de mise et refus d'une ancienne validation, refus d'une case
  verrouillée, aucun débit avant consentement mutuel.
- Combat autonome, adversaire limité au familier, absence d'aide du rival,
  dégâts directs du propriétaire refusés, K.-O., paiement exact, réclamation
  répétée sans duplication et absence d'apprentissage par duel.
- Duel sans mise, projectile natif, projectile non sauvegardable, abandon,
  blessure conservée et refus d'un projectile arrivé après la fin du duel.
- Clic natif sur la mise dans le menu, aller-retour réseau et mise effacée
  côté serveur ; affichage et commandes FR/EN.
- Inventaire plein, gain conservé, récupération ultérieure, reprise du journal
  interrompu, restitution sans double paiement, coffre renommé avec contenu
  natif conservé après le transit.

Les tests serveur ci-dessus tournent dans le client intégré, sans accepter
l'EULA d'un serveur dédié. Ils ne remplacent pas une session de charge avec
deux clients réseau indépendants. Captures : `build/combat054-evidence/` ; journal
client : `build/combat054-final-client-pack.log`.

`Experience054Checks` vérifie également les frontières de la courbe XP native,
les allers-retours d'XP même après une dépense de niveaux, les points partiels,
le refus d'une requête périmée, le gel dès l'invitation de duel et pendant un
combat. Un familier de niveau 120 inflige les dégâts supplémentaires réels ;
sa réserve de santé reçoit les dégâts en unités effectives. Dépôt et retrait
ne restaurent pas sa vie. La migration de schéma 1 conserve les inconnus.
La reprise est testée avant débit, après reçu joueur et après écriture du
familier ; les tentatives répétées ne multiplient pas les crédits. Un échange entre deux
joueurs conserve la charge, permet au nouveau propriétaire de la retirer et
refuse qu'une copie conservée par l'ancien propriétaire serve à la voler. Les boutons
natifs, la rareté légendaire de l'œuf et une nouvelle ouverture du monde avec
l'XP stockée sont vérifiés. Ce ne sont pas des tests d'arrachement physique du
disque ou de panne électrique.

## Limites de la refonte à vérifier par espèce

La validation exhaustive conserve comme critères : comportement favorable et refus utile pour chaque espèce,
munitions/consommables conservés, origine des attaques, protections finies,
K.-O./soins, rappel/changement/transfert/reconnexion, PvP et factions, absence de
destruction autonome, menus FR/EN et conservation des fonctionnalités historiques.
Les valeurs restent des valeurs de test. Certains services de vie commune et certaines variantes utilisent encore des
comportements génériques : plateforme commune pour plusieurs espèces,
ancrage par ralentissement, suivi de cible simple et protection sans renvoi
réel de projectile. Leur fidélité au catalogue reste à finaliser. Les duels
rendent les essais possibles ; cette livraison ne constitue pas la finition
exhaustive des 88 fiches ni la fin de leur équilibrage.