ravenous_roll20/README.md

249 lines
11 KiB
Markdown

# Ravenous — feuille Roll20
Feuille de personnage Roll20 générée depuis les données du livre
[`ravenous_typst`](ravenous_typst). Le résultat reprend la palette parchemin,
or et sang du livre et fournit :
- les caractéristiques et statistiques dérivées de Ravenous ;
- toutes les compétences générales officielles, les compétences maison et leurs modificateurs ;
- les attaques et protections sous forme de sections répétables, avec jets de défense et calcul des dégâts dans Roll20 ;
- une page de santé détaillée par localisation (PV, protection et armure), ainsi que toutes les résistances physiques et élémentaires ;
- les potions, nourritures et effets temporaires en texte libre, publiables dans
le chat ;
- l'ajout individuel des techniques d'école depuis les TSV du livre, avec
traduction du balisage Typst et bouton d'activation dans le chat.
- un sélecteur d'origine et l'ajout de ses pouvoirs stade par stade dans un
onglet dédié, avec des lignes libres pour les pouvoirs personnalisés.
## Construction locale
Initialiser le sous-module une première fois :
```sh
git submodule update --init --recursive
```
Puis construire avec `uv` (aucun `pip` global n'est utilisé) :
```sh
./scripts/build.sh
```
Le script crée `.venv/` et produit dans `build/` :
- `ravenous.html`, `ravenous.css` et `translation.json`, à charger dans
l'éditeur de feuille personnalisée Roll20 ;
- `sheet.json`, comme base pour une future soumission au dépôt communautaire
Roll20 (une capture `ravenous.png` devra alors être ajoutée) ;
- `build-info.json`, qui indique le nombre d'écoles, techniques et compétences
importées ainsi que l'empreinte du contenu.
### Choisir un thème à l'export
Le thème par défaut est `document.color_scheme` dans
`ravenous_typst/data/config/build.yaml`. Pour voir les thèmes définis dans le
livre puis exporter un autre CSS sans remplacer le build par défaut :
```sh
./scripts/build.sh --list-themes
./scripts/build.sh --theme steel --output-dir build-steel
./scripts/build.sh --theme steel --output-dir build-steel --check
```
Chargez `build-steel/ravenous.css` avec le HTML et la traduction du même dossier
dans Roll20. La feuille et ses cartes de chat utilisent la palette choisie.
Les couleurs viennent de `ravenous_typst/setup/theme/themes.typ` ; `src/ravenous.css`
reste le modèle CSS commun.
La limite des tiers d'école vient directement de
`ravenous_typst/data/config/build.yaml` : seuls les tiers strictement inférieurs
à `build.max_tier_exclusive` sont proposés par la feuille. Les trigrammes affichés
dans le menu des techniques viennent de `schools.trigrams` dans ce même fichier.
Pour vérifier qu'un build versionné correspond aux sources :
```sh
./scripts/build.sh --check
```
Les tests Python vérifient la génération. Des tests Node exécutent aussi le
sheet worker généré avec une simulation minimale des API Roll20 (recalcul,
résistances, protections, techniques et calculs de jets) :
```sh
uv run python -m unittest discover -s tests -v
node tests/test_worker.mjs
```
Si Podman est disponible, le même test Node peut tourner dans un conteneur
isolé, sans accès réseau et avec le dépôt monté en lecture seule. Construisez
d'abord la feuille ; le premier lancement télécharge l'image officielle Node :
```sh
./scripts/build.sh
./scripts/test-worker-container.sh
```
Cette simulation ne reproduit pas le moteur de dés, le navigateur ou le chat de
Roll20. Les interactions doivent aussi être testées dans le Custom Sheet
Sandbox de Roll20. La procédure de vérification est détaillée dans
[`TASKS.md`](TASKS.md).
## Essai d'import JSON par Mod Roll20
Un prototype minimal se trouve dans `roll20_mod/ravenous_import_name.js`. Il
crée un **nouveau personnage avec son nom seulement** ; il ne modifie aucun
personnage existant et n'importe pas encore les autres champs. Le créateur de
la partie doit disposer de l'accès aux Mod scripts de Roll20 (Pro/Elite).
Dans la page de la partie, ouvrez **Settings → Mod Scripts → New Script**,
collez le contenu du fichier, nommez le script puis cliquez sur **Save Script**.
Dans le chat de cette même partie, en tant que MJ, entrez :
```text
!ravenous-import-name {"name":"Ariane"}
```
Vérifiez qu'un nouveau personnage nommé « Ariane » apparaît dans le journal.
Chaque commande valide crée un personnage supplémentaire. Pour exécuter les
tests locaux de ce prototype :
```sh
node tests/test_mod_import.mjs
```
## Sauvegarde et import de personnages et de créatures
`roll20_mod/ravenous_character_io.js` est le script Mod destiné aux MJ. Installez-le
comme **New Script** dans une partie avec la feuille Ravenous. Il utilise le format
JSON versionné `ravenous-roll20-character` et crée toujours un nouveau personnage
à l'import. Les attributs (y compris les lignes répétables), les capacités Roll20,
la bio, les notes MJ et les droits de consultation/contrôle sont conservés.
Dans le chat, en tant que MJ :
```text
!ravenous-export
!ravenous-export --id ID_DU_PERSONNAGE
!ravenous-import --handout ID_DU_HANDOUT
!ravenous-import {"format":"ravenous-roll20-character","version":1,"name":"Ariane","attributes":[]}
```
Sans ID, sélectionnez exactement un token lié au personnage avant la commande.
Utilisez `--id` si vous ne disposez pas d'un token lié. L'export crée un handout
réservé au MJ, dont les **GM Notes** contiennent le JSON
lisible. Copiez ce JSON dans un fichier pour le stocker hors de Roll20. Pour
importer un fichier volumineux, créez un handout, collez le JSON dans ses GM
Notes, puis utilisez `--handout` avec son ID. La commande directe convient aux
petits JSON. Gardez les handouts d'export privés : ils contiennent les notes MJ.
Les IDs sont visibles dans l'URL des objets Roll20. Après import, ouvrez le
personnage pour laisser les sheet workers recalculer les valeurs dérivées.
Pour créer un JSON depuis la base SQLite du livre du MJ :
```sh
git -C ravenous_typst submodule update --init data/src/db
python tools/export_monsters.py --id 1 --output /tmp/monster-1.json
python tools/export_monsters.py --all --output /tmp/ravenous-monsters
```
Le convertisseur reprend les caractéristiques directement compatibles, les
localisations en lignes répétables, les capacités avec dégâts en attaques, et
les autres capacités en pouvoirs. Leurs descriptions et valeurs de dégâts
restent dans les notes des lignes. La base complète de la créature, y compris
les phases et les valeurs sans équivalent fidèle dans la feuille de chasseur,
est conservée en JSON dans les GM Notes du personnage. Les champs de jet
inconnus sont laissés à zéro : le MJ doit régler dés, seuils et dégâts avant
d'utiliser les boutons d'attaque. Les sheet workers de la feuille de chasseur
recalculent certaines valeurs dérivées à l'ouverture.
Vérification locale :
```sh
uv run python -m unittest discover -s tests -v
python tools/export_monsters.py --id 1 --output /tmp/ravenous-monster-test.json
RAVENOUS_MONSTER_JSON=/tmp/ravenous-monster-test.json node tests/test_character_io.mjs
```
Ces tests simulent l'API Mod et valident le format avec la base épinglée. Un
essai dans une partie Roll20 reste nécessaire pour confirmer l'affichage et
les limites des GM Notes.
## Mise à jour depuis le livre
```sh
git submodule update --remote ravenous_typst
./scripts/build.sh
```
Les compétences proviennent de
`ravenous_typst/data/src/character_sheet.yaml` et les techniques de
`ravenous_typst/data/src/schools/*.tsv`. Les transformations sont dans
`tools/build.py`; le HTML et le CSS maintenus à la main restent dans `src/`.
Les origines et leurs pouvoirs proviennent de
`ravenous_typst/data/src/origines/*.yaml`.
Les spécialités imbriquées (`subskills`) sont également importées ; leur nom
complet et leur identifiant incluent la compétence parente pour éviter les
ambiguïtés, mais l'affichage les indente sous leur parent et ne répète pas son
nom.
Il n'est donc pas nécessaire de recopier les données lors d'une mise à jour du
livre.
## CI et publication
Le `Jenkinsfile`, inspiré de celui de `ravenous_typst`, initialise les
sous-modules, installe `uv` via Cargo si nécessaire, reconstruit la feuille,
exécute les tests et vérifie que `build/` est à jour. Jenkins archive ensuite
le dossier complet avec empreintes.
Sur l'agent FreeBSD, il vérifie aussi que le Python utilisé par `uv` dispose de
`sqlite3` et installe au besoin le paquet `pyXY-sqlite3` correspondant via
`pkg` (directement ou avec `sudo`/`doas` non interactif). Les tests du
convertisseur de monstres en ont besoin.
Les branches `main` et `master` sont publiées dans
`/mnt/books/ravenous_sheet`, correspondant à
`https://books.dandaedre.com/ravenous_sheet/`. Les branches `candlelight` et
`lighthouse` utilisent respectivement les dossiers suffixés `_candlelight` et
`_lighthouse`. Les autres branches sont construites et archivées sans être
déployées.
## Notes Roll20
Dans une partie utilisant une feuille personnalisée, copiez le contenu des
trois fichiers HTML, CSS et traduction dans les panneaux correspondants. La
feuille cible le mode CSE actuel : laissez **Legacy Sanitization désactivé**.
La police Google distante est facultative ; sans accès réseau, les polices de
secours Georgia/serif sont utilisées et toute la mise en page reste active. La
prévisualisation intégrée de Roll20 ne simule pas complètement les sheet
workers ni les sections répétables : validez les imports et les jets dans le
bac à sable de feuille ou dans une partie de test.
Pour utiliser **Défendre** ou **Subir** depuis la carte d'une attaque, cliquez
le token du défenseur lorsque Roll20 affiche le ciblage « Défenseur ».
La macro utilise alors sa compétence d'Esquive ou de
Parade et son modificateur temporaire, sans ajouter la caractéristique associée.
Le bouton **Jets secrets** dans l'en-tête envoie les jets du personnage
uniquement au maître de jeu. Les actions Défendre et Subir suivent le réglage
du token défenseur ciblé.
Avant d'utiliser **Subir** depuis une attaque, cochez dans l'onglet Santé les
résistances applicables et, dans l'onglet Combat, les protections couvrant la
localisation. Les résistances cochées se cumulent et retirent chacune deux DMG
par point. Une protection cochée ne compte que si son intégrité est supérieure
à zéro ; le calcul retire alors sa Protection ainsi que la Force finale du
défenseur ciblé.
Le menu Protection de **Subir** permet d'utiliser les protections cochées ou la
protection d'une localisation fixe/personnalisée. Pour l'AB, les résistances
retirent un point par point et seule la première protection valide de la liste
Combat s'applique, sans la Force ; ordonnez donc les protections de haut en bas
selon leur ordre d'impact.
Dans l'onglet **Chasseur**, choisissez l'origine du personnage. Dans l'onglet
**Pouvoirs**, choisissez un stade puis cliquez sur **Ajouter les pouvoirs du
stade**. Tous les pouvoirs de ce stade pour l'origine sélectionnée sont ajoutés.
Une même entrée ne peut être ajoutée qu'une fois. Les lignes sont
modifiables et la section répétable permet d'ajouter des pouvoirs personnalisés.
Changer d'origine ne supprime pas les pouvoirs existants. Les pouvoirs sont
affichables dans le chat mais n'appliquent pas automatiquement leurs effets.