# Les capacités spéciales

Référence d'usage (ligne 59 du suivi, 02/10/2026). Les idées de capacités à
venir sont dans le Sheet de suivi, onglet « Idées abstraites », thème
Capacités spéciales.

## Ce que c'est

Une capacité est un comportement qu'aucune donnée générique ne sait décrire :
faire apparaître des acolytes, se téléporter, voler un ingrédient. Chaque
**genre** de capacité est du code du jeu ; l'auteur en configure des
**exemplaires** réutilisables, puis les fait partir depuis une attaque ou depuis
la fiche d'un monstre.

Une capacité agit sur le jeu, jamais sur le seul dessin : les acolytes
invoqués sont de vraies créatures, avec leur corps, leurs attaques et leurs
règles. La logique 2D reste l'autorité ; le pont 3D les montre comme les autres.

## Où vivent les réglages

| Emplacement | Ce qu'il porte |
| --- | --- |
| `data/ability_contract.json` | Les genres que le code sait jouer, leurs réglages (type, bornes, défaut, libellé) et les moments de déclenchement. **Ce n'est pas une donnée d'auteur** : c'est le contrat du code, lu par PHP, par la page et par Godot. |
| `abilities` (onglet **Capacités**) | Les exemplaires configurés : un nom, un genre, ses réglages. |
| Piste **Capacités** de la frise d'un pattern d'attaque | Un bloc fait partir une capacité, une fois, au début du bloc. |
| `enemies[…].ability_triggers` (section **Capacités déclenchées**) | À l'apparition, à la mort, sous un seuil de PV. Un niveau est une fiche complète et garde les siens. |

## Deux façons de la faire partir

**Par une attaque.** C'est la voie normale : la capacité hérite de tout ce
qu'une attaque sait déjà faire. L'IA la choisit au poids et à la distance, sa
recharge la retient, l'animation et le télégraphe l'annoncent, une phase de
combat peut changer la liste des attaques. Une attaque interrompue avant le
bloc ne déclenche rien. Un pattern peut ne porter **aucun coup** — une pure
invocation — mais il doit alors fixer sa distance de déclenchement : sans zone
qui blesse, rien d'autre ne dit à quelle distance il part.

**Par la fiche.** Pour ce qui n'est pas un geste :

- *À l'apparition* : une fois, quand la créature entre dans la salle.
- *À la mort* : au moment où elle tombe, à l'endroit où elle tombe. C'est
  ainsi qu'on écrit « se diviser à la mort ».
- *Sous un seuil de PV* : une seule fois par vie, au coup qui fait passer le
  seuil, et seulement si la créature tient encore debout — le coup fatal laisse
  parler les capacités « à la mort ».

## Invoquer des acolytes

| Réglage | Effet |
| --- | --- |
| Créature, nombre | Qui apparaît, combien par invocation. |
| Vivants au plus | Le plafond des acolytes de ce lanceur, toutes invocations confondues. 0 = sans plafond. |
| Placement, rayon | Autour du lanceur, autour du héros, ou le long des bords de l'arène. Toujours à l'intérieur des murs. |
| Retiennent la salle | La sortie reste fermée tant qu'ils vivent. Sinon, la salle se vide sans eux. |
| Disparaissent avec le lanceur | Ils partent quand leur maître tombe : ni butin, ni compte de victime. |
| Lâchent leur butin | Par défaut non : sans cela, invoquer deviendrait une ferme à butin. |

Trois règles que le code tient seul :

- **Pas d'héritiers liés à un mort.** Les acolytes nés d'une capacité « à la
  mort » sont libres : les lier au lanceur les ferait disparaître aussitôt.
- **La salle compte avant de se croire vide.** À la mort, les acolytes liés
  partent, puis les capacités « à la mort » jouent, et seulement ensuite la
  salle apprend la mort. Une invocation qui retient la salle est donc comptée
  avant que la sortie s'ouvre.
- **Une invocation n'est jamais refusée par les conditions de sa fiche** (08/10,
  phase 9). Ses versions suivent leurs conditions comme dans une vague ; si
  aucune n'est admissible, c'est la fiche de base qui vient. La machine que
  Big Egg 4 active en fuyant n'attend pas, pour naître, la fuite qu'elle
  précède ; ses conditions ne servent qu'à la vague des visites suivantes.
- **Trois générations au plus.** Une créature invoquée peut invoquer à son
  tour, jusqu'à la troisième génération. Une fiche qui s'invoque elle-même ne
  boucle pas sans fin.

## Fuir

Ajouté le 07/10/2026 (phase 4 du plan de l'histoire, pour Carl). Déclenchée
d'ordinaire « sous un seuil de PV », la créature quitte la salle en courant par
le bord le plus proche de l'arène, puis disparaît une fois dehors.

| Réglage | Effet |
| --- | --- |
| Vitesse de fuite | Un multiple de sa vitesse (0,5 à 5 ; 1,6 par défaut). |
| Lâche son butin | Par défaut non : elle n'est pas tombée. |

Ce que le code tient seul : elle sort du combat tout de suite (ni coup, ni
contact, ni corps), **compte comme vaincue pour la porte**, emmène ses acolytes
liés, monte le compteur `enemies.<id>.total_fled` et fait partir le crochet
« Quand il prend la fuite » (`on_flee`) — c'est là qu'on pose un fait ou qu'on
donne un objet (la jambe de Carl). Son compteur de morts, lui, ne bouge pas.

**Fuir remplace mourir** (billet 116, 15/10/2026). Un coup mortel qui franchit
le seuil d'une fuite pas encore partie la fait fuir quand même : il lui reste un
filet de vie, sous le seuil. Avant, un coup assez fort pour sauter la fenêtre
« sous le seuil, encore debout » tuait la créature : Carl (50 PV, seuil à 20)
mourait à coup sûr sous les dégâts fixés du débogage. Seule la console qui vide
la salle tue encore. Une fuite qui doit rendre le butin « à la mort » coche
« Lâche son butin » : c'est le cas de Carl depuis ce billet (viande, jambe
ingrédient).

## Ajouter un genre

1. Le coder dans `scripts/combat/abilities.gd` : une branche dans `trigger`,
   sa fonction.
2. Le déclarer dans `data/ability_contract.json`, avec ses réglages. Les types
   connus sont `int`, `number`, `bool`, `choice` et `enemy` ; un type neuf
   demande sa validation dans `ability_contract.php` et
   `scripts/core/ability_contract.gd`.
3. La page dessine le formulaire seule ; rien à ajouter dans `app.js`.
4. Un contrôle dans `scripts/core/abilities_check.gd`.

## Éprouver

`python tools/dev/dev.py check --area abilities` (aussi tiré par la zone
`gameplay`) : du maître au catalogue, la normalisation, la frise, puis dans le
vrai donjon l'invocation, le plafond, la salle retenue ou non, le butin coupé,
le départ avec le maître, chaque moment de fiche, la limite de générations et
le geste d'une attaque, interrompue comprise. Côté outil :
`tests/ability_validation_test.php` et `tests/ability_editor_test.js`.