ravenous_roll20/docs/mod-scripts.md

115 lines
4.2 KiB
Markdown

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