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.