316 lines
15 KiB
Markdown
316 lines
15 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
|
|
```
|
|
|
|
Pour produire un personnage d'exemple aléatoire mais reproductible (toutes les
|
|
sections répétables, Unicode et caractères sensibles inclus) :
|
|
|
|
```sh
|
|
python tools/generate_character.py --seed 42 --output /tmp/ravenous-example.json
|
|
```
|
|
|
|
Une même graine produit exactement le même JSON, ce qui permet de reproduire un
|
|
échec d'import. Sans `--output`, le JSON est écrit sur la sortie standard. La CI
|
|
génère, valide et archive également `build/example-character.json`. Elle
|
|
l'importe dans le simulateur de l'API Mod lorsque Node est disponible sur
|
|
l'agent ; l'absence de ce runtime n'empêche pas la construction de la feuille.
|
|
Le script `./scripts/build.sh` génère automatiquement ce même exemple dans son
|
|
dossier de sortie, et `./scripts/build.sh --check` vérifie également son contenu.
|
|
|
|
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.
|
|
|
|
## Rappels d'effets et tours
|
|
|
|
L'onglet **Effets & tours** regroupe les effets temporaires et les commandes de
|
|
tour. Les effets peuvent porter des rappels distincts de début et de fin de
|
|
tour. Leur durée structurée peut être manuelle, exprimée en tours, liée au
|
|
prochain début/à la prochaine fin de tour, ou réservée à la fin du combat et au
|
|
futur décompte par actions. Les boutons **Début du tour** et **Fin du tour**
|
|
affichent uniquement les rappels de la phase, décrémentent les durées concernées
|
|
et annoncent les effets terminés. Ils ne modifient jamais automatiquement PV,
|
|
armure, résistances ou ressources.
|
|
Le bouton **Supprimer les effets inactifs** nettoie en une fois les lignes déjà
|
|
terminées. Chaque ajout, traitement de phase et nettoyage affiche d'abord son
|
|
état d'exécution puis un message de résultat directement dans l'onglet concerné.
|
|
|
|
La configuration avancée d'un consommable peut être copiée dans les effets
|
|
actifs avec **Appliquer comme effet**. Une technique ou un pouvoir peut aussi
|
|
être copié avec **Suivre comme effet**, puis recevoir ses rappels structurés sans
|
|
tenter d'interpréter librement sa prose. À la construction, des heuristiques
|
|
centralisées reconnaissent les formulations françaises de début/fin de tour,
|
|
de prochain tour, de durée en tours et de fin de combat dans les données du
|
|
livre. Ces métadonnées sont donc recalculées automatiquement à chaque mise à
|
|
jour du livre, y compris pour les techniques et pouvoirs déjà ajoutés. Les
|
|
anciennes lignes d'effets, dépourvues de champs structurés, restent actives en
|
|
durée manuelle.
|
|
|
|
## Import d'objets fabriqués
|
|
|
|
`roll20_mod/ravenous_craft_import.js` importe les résultats finalisés d'un
|
|
futur site d'artisanat dans un personnage existant. Le contrat JSON versionné
|
|
et les exemples sont définis dans [`docs/craft-json-v1.md`](docs/craft-json-v1.md).
|
|
Il couvre les armes, protections, consommables et effets temporaires. Le Mod ne
|
|
recalcule pas la recette et n'applique aucun effet automatiquement.
|
|
|
|
Installez le script comme Mod, puis sélectionnez le token du personnage et
|
|
utilisez un JSON direct ou les GM Notes d'un handout privé :
|
|
|
|
```text
|
|
!ravenous-import-craft {"format":"ravenous-roll20-craft","version":1,"items":[{"type":"consumable","name":"Potion rouge","kind":"Potion","quantity":1}]}
|
|
!ravenous-import-craft --handout ID_DU_HANDOUT
|
|
!ravenous-import-craft --id ID_DU_PERSONNAGE --handout ID_DU_HANDOUT
|
|
```
|
|
|
|
Les joueurs peuvent utiliser cette commande uniquement avec un personnage
|
|
qu'ils contrôlent et un handout auquel ils ont accès. Le MJ n'est pas soumis à
|
|
ces restrictions. Des actions de macro prêtes à copier pour cet import et les
|
|
autres commandes Mod sont regroupées dans [`docs/macros.md`](docs/macros.md).
|
|
Vérification locale :
|
|
|
|
```sh
|
|
node tests/test_craft_import.mjs
|
|
```
|
|
|
|
## 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.
|