# 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`](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. ```text !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 : ```sh 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 : ```sh 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`](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. ```text !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 : ```text !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 : ```text !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 : ```sh 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`](../TASKS.md).