ravenous_roll20/docs/mod-scripts.md

4.2 KiB

Scripts Mod et échanges JSON Ravenous

Les scripts de roll20_mod/ sont facultatifs et s'installent séparément de la feuille. Ils nécessitent l'accès Roll20 aux scripts Mod. Pour les commandes qui ciblent une fiche, sélectionnez un token lié ou fournissez explicitement --id ID_DU_PERSONNAGE.

Gardez les handouts d'export privés : les sauvegardes peuvent contenir bio, notes, capacités et données réservées au MJ. Les actions prêtes à copier sont regroupées dans macros.md.

Personnages et créatures

Installez roll20_mod/ravenous_character_io.js. Le format ravenous-roll20-character v1 permet au MJ de créer ou remplacer un personnage. Un joueur peut exporter et remplacer un personnage qu'il contrôle à partir d'un handout auquel il a accès.

!ravenous-export
!ravenous-export --id ID_DU_PERSONNAGE
!ravenous-import --handout ID_DU_HANDOUT
!ravenous-import --replace --handout ID_DU_HANDOUT
!ravenous-import --replace --id ID_DU_PERSONNAGE --handout ID_DU_HANDOUT

Les boutons Exporter et Restaurer de la fiche ajoutent l'ID du personnage courant. L'export joueur crée un handout contrôlé par ce joueur avec le JSON dans ses Notes. L'export MJ crée un handout privé avec le JSON dans ses GM Notes. Un remplacement conserve l'objet personnage, son ID, ses tokens liés, son avatar, ses droits et ses notes MJ, mais remplace nom, bio, attributs et capacités après validation complète du JSON.

Pour convertir la base de créatures épinglée :

git -C ravenous_typst submodule update --init data/src/db
uv run python tools/export_monsters.py --id 1 --output /tmp/monster-1.json
uv run python tools/export_monsters.py --all --output /tmp/ravenous-monsters

Le convertisseur garde les données sans équivalent fidèle dans les GM Notes. Les dés, seuils et dégâts inconnus restent à zéro et doivent être contrôlés par le MJ avant utilisation.

Une sauvegarde de test reproductible est générée avec :

uv run python tools/generate_character.py --seed 42 --output /tmp/ravenous-example.json

Artisanat

Installez roll20_mod/ravenous_craft_import.js. Le contrat complet est décrit dans craft-json-v1.md. Les attaques, protections, consommables et effets temporaires sont importés comme lignes éditables ; les recettes et effets ne sont pas recalculés.

!ravenous-import-craft --handout ID_DU_HANDOUT
!ravenous-import-craft --id ID_DU_PERSONNAGE --handout ID_DU_HANDOUT
!ravenous-export-craft --id ID_DU_PERSONNAGE

Un joueur doit contrôler le personnage et pouvoir lire le handout ; le MJ peut cibler tous les objets. Les fichiers build/example-craft-forge.json et build/example-craft-alchemy.json couvrent les quatre destinations prises en charge.

Effets partagés et bibliothèque

Installez roll20_mod/ravenous_shared_effects.js pour rendre le bouton Ajouter à ma fiche actif sur les cartes d'effet. Le joueur choisit un token lié à un personnage qu'il contrôle ; le script refuse les autres fiches.

Installez roll20_mod/ravenous_effects_import.js pour échanger une bibliothèque ravenous-roll20-effects v1 :

!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 rejoint DoT & effets avec son ID, son type, sa durée et ses rappels. L'import n'active pas l'effet dans le suivi des tours. Les champs inconnus, valeurs hors limites et accès non autorisés sont rejetés.

Prototype minimal

roll20_mod/ravenous_import_name.js démontre la création MJ d'un personnage à partir de son nom uniquement :

!ravenous-import-name {"name":"Ariane"}

Ce prototype crée toujours un nouveau personnage et n'importe aucun autre champ ; utilisez le script d'échange complet pour les sauvegardes réelles.

Vérification locale

Après ./scripts/build.sh, exécutez :

node tests/test_mod_import.mjs
node tests/test_character_io.mjs
node tests/test_craft_import.mjs
node tests/test_effects_import.mjs
node tests/test_shared_effects.mjs

Ces tests simulent une partie de l'API Mod, pas le stockage ou l'affichage réel de Roll20. Les validations manuelles restantes sont dans TASKS.md.