115 lines
4.2 KiB
Markdown
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).
|