ravenous_roll20/README.md

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

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.