ravenous_roll20/README.md

12 KiB

Ravenous — feuille Roll20

Feuille de personnage Roll20 générée depuis les données du livre 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 :

git submodule update --init --recursive

Puis construire avec uv (aucun pip global n'est utilisé) :

./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 :

./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 :

./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) :

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 :

./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.

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 :

!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 :

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 :

!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 :

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 :

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.

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. 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é :

!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. Vérification locale :

node tests/test_craft_import.mjs

Mise à jour depuis le livre

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.