Roll20 character sheet & macros
Go to file
Dandaedre eab808d3e0
Roll20 Sheet Build Successful The Ravenous Roll20 sheet was generated and validated successfully.
Ravenous/ravenous_roll20/pipeline/head This commit looks good Details
JKF update
2026-09-19 07:39:32 +02:00
assets Adds a mascot 2026-09-19 07:25:58 +02:00
docs feat: add craft imports and skill subtabs 2026-09-19 06:37:29 +02:00
ravenous_typst@c47e56d8f8 feat: add craft imports and skill subtabs 2026-09-19 06:37:29 +02:00
roll20_mod feat: add craft imports and skill subtabs 2026-09-19 06:37:29 +02:00
scripts feat: add timed effect reminders and fuzz fixtures 2026-09-19 07:00:02 +02:00
src style: compact temporary effect cards 2026-09-19 07:37:45 +02:00
tests style: compact temporary effect cards 2026-09-19 07:37:45 +02:00
tools feat: add dedicated effect turn tracking 2026-09-19 07:21:30 +02:00
.gitignore Track Roll20 feedback and ignore local exports 2026-09-17 20:28:01 +02:00
.gitmodules Update sm 2026-08-27 20:41:02 +02:00
AGENTS.md feat: add craft imports and skill subtabs 2026-09-19 06:37:29 +02:00
Jenkinsfile JKF update 2026-09-19 07:39:32 +02:00
LICENSE Initial commit 2026-08-26 22:08:01 +02:00
README.md JKF update 2026-09-19 07:39:32 +02:00
TASKS.md JKF update 2026-09-19 07:39:32 +02:00
pyproject.toml Made things 2026-08-27 20:39:13 +02:00
uv.lock Made things 2026-08-27 20:39:13 +02:00

README.md

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

Pour produire un personnage d'exemple aléatoire mais reproductible (toutes les sections répétables, Unicode et caractères sensibles inclus) :

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 :

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