20 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.cssettranslation.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 captureravenous.pngdevra 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
Chaque personnage choisit son thème avec le sélecteur Apparence en haut de
la feuille. La sélection est conservée dans l'attribut Roll20 theme et
s'applique également aux cartes de chat du personnage. Toutes les palettes de
ravenous_typst/setup/theme/themes.typ sont intégrées automatiquement au build ;
le thème initial vient de document.color_scheme dans
ravenous_typst/data/config/build.yaml.
Pour afficher les identifiants disponibles :
./scripts/build.sh --list-themes
Pour produire un bundle dont le thème initial et de secours couvre aussi les
contrôles et boîtes d'interface situés hors de la zone recolorée, utilisez
--theme-ui. Tous les thèmes restent ensuite disponibles dans Apparence :
./scripts/build.sh --theme-ui steel --output-dir build-steel
./scripts/build.sh --theme-ui steel --output-dir build-steel --check
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
Effets de compétence partagés
Le sous-onglet DoT & effets de l'onglet Effets & tours conserve une bibliothèque de plusieurs altérations, dégâts ou soins sur la durée, bonus et malus. Chaque effet peut être montré seul dans le chat puis référencé par son ID depuis les options d'un pouvoir d'origine ou d'une technique d'école. Plusieurs effets peuvent être proposés sur la même carte de jet et chacun possède son propre bouton d'ajout.
Pour rendre le bouton Ajouter à ma fiche fonctionnel, installez aussi
roll20_mod/ravenous_shared_effects.js comme Mod script. Le destinataire clique
le bouton, choisit un token lié à un personnage qu'il contrôle, puis retrouve
l'effet dans Effets & tours avec sa durée et ses rappels. Le script refuse
d'écrire sur un personnage que le joueur ne contrôle pas. Vérification locale :
node tests/test_shared_effects.mjs
La bibliothèque statique d'effets exporte aussi une sélection complète au
format versionné ravenous-roll20-effects v1. Installez
roll20_mod/ravenous_effects_import.js, puis sélectionnez le token du
personnage destinataire ou indiquez son ID :
!ravenous-import-effects {"format":"ravenous-roll20-effects","version":1,"effects":[{"effect_id":"combustion","type":"dot","name":"Combustion"}]}
!ravenous-import-effects --handout ID_DU_HANDOUT
!ravenous-import-effects --id ID_DU_PERSONNAGE --handout ID_DU_HANDOUT
!ravenous-export-effects --id ID_DU_PERSONNAGE
Chaque entrée est ajoutée à DoT & effets avec son ID, son type, sa durée structurée et ses rappels. Le script refuse les champs inconnus, les valeurs hors limites, les personnages non contrôlés et les handouts inaccessibles. Le JSON exporté prépare une bibliothèque réutilisable ; il n'active pas les effets dans le suivi des tours. L'export crée un handout privé contenant toutes les entrées de DoT & effets. Les actions Fiche, Artisanat et Effets sont regroupées dans le menu Échanges JSON de l'en-tête afin de ne pas surcharger la fiche. Vérification locale :
node tests/test_effects_import.mjs
Sauvegarde et import de personnages et de créatures
roll20_mod/ravenous_character_io.js est le script Mod d'échange de personnages.
Installez-le comme New Script dans une partie avec la feuille Ravenous. Il
utilise le format JSON versionné ravenous-roll20-character. Un MJ peut créer un
nouveau personnage ; un joueur peut exporter un personnage qu'il contrôle et le
remplacer en place à partir d'un handout auquel il a accè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":[]}
Pour un joueur, sélectionnez un token lié à son personnage :
!ravenous-export
!ravenous-import --replace --handout ID_DU_HANDOUT
Les boutons Exporter et Restaurer dans l'en-tête de la feuille envoient ces mêmes commandes avec l'ID du personnage courant ; ils ne nécessitent donc pas de token sélectionné. Restaurer demande l'ID du handout source.
L'export joueur crée un handout contrôlé par ce joueur et place le JSON dans ses
Notes visibles. Le remplacement conserve l'objet personnage, son ID, ses
tokens liés, son avatar, ses droits et ses notes MJ ; il remplace son nom, sa bio,
ses attributs de feuille et ses capacités. Le JSON est entièrement validé avant
la suppression des anciennes lignes. Un joueur ne peut cibler qu'un personnage
qu'il contrôle ni lire un handout auquel il n'a pas accès. Le MJ peut aussi faire
un remplacement avec --replace, éventuellement suivi de --id ID_DU_PERSONNAGE.
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 MJ 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.
Jenkins exporte en plus les monstres d'ID 2 (Yajjpnir) et 5 (Baloth Joueur)
dans build/example-monster-2.json et build/example-monster-5.json, les
archive, puis les importe séparément avec le même simulateur pour vérifier les
localisations, attaques et pouvoirs générés.
Le build génère aussi deux charges utiles prêtes à importer :
build/example-craft-forge.json (attaque et protection) et
build/example-craft-alchemy.json (consommable et effet temporaire). Copiez le
contenu d'un fichier dans les GM Notes d'un handout privé, puis sélectionnez un
token lié au personnage et lancez :
!ravenous-import-craft --handout ID_DU_HANDOUT
Ces exemples couvrent les quatre sections répétables prises en charge par l'importeur et sont régénérés et vérifiés de façon déterministe par la CI.
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 boutons Export artisanat et Import artisanat de l'en-tête ciblent directement le personnage courant. L'export regroupe ses attaques, protections, consommables et effets temporaires compatibles dans un handout. Pour un joueur, ce handout lui est attribué et le JSON se trouve dans ses Notes visibles ; le bouton d'import peut ensuite le charger dans un autre personnage qu'il contrôle.
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/assets/ravenous_roll20/ravenous_sheet, correspondant à
https://assets.dandaedre.com/ravenous_roll20/ravenous_sheet/. Jenkins crée le
dossier cible s'il manque. La racine ravenous_roll20 n'est jamais synchronisée
avec --delete ; seule la sous-arborescence du produit l'est. 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. Le pipeline ne modifie plus /mnt/books.
Le pipeline construit également la preuve de concept de l'atelier d'artisanat
statique depuis craft_web/. Elle est publiée dans
/mnt/assets/ravenous_roll20/ravenous_craft, soit
https://assets.dandaedre.com/ravenous_roll20/ravenous_craft/, avec les suffixes
_candlelight et _lighthouse. Le site ne requiert ni Node.js ni serveur
applicatif : Python génère ses fichiers HTML, CSS, JavaScript et son catalogue.
La bibliothèque statique d'altérations et d'effets de effects_web/ suit le
même cycle de construction, de test déterministe, d'archivage et de
publication. La production est disponible sous
https://assets.dandaedre.com/ravenous_roll20/ravenous_effects/; les branches de
développement et de revue utilisent respectivement les suffixes _candlelight
et _lighthouse. Son catalogue, ses thèmes et son schéma JSON sont générés à
partir de la même révision épinglée du livre.
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.