docs: streamline README and usage guides
Roll20 Sheet Build Successful The Ravenous Roll20 sheet was generated and validated successfully.
Ravenous/ravenous_roll20/pipeline/head This commit looks good Details

This commit is contained in:
Dandaedre 2026-10-04 03:58:12 +02:00
parent b37cb470b2
commit 5ad0c75233
Signed by: Dandaedre
GPG Key ID: 440C6592E8A26D99
6 changed files with 391 additions and 444 deletions

504
README.md
View File

@ -1,458 +1,94 @@
# Ravenous — feuille Roll20
![version](https://assets.dandaedre.com/coverage/Ravenous/ravenous_roll20/main/version.svg)
![tests](https://assets.dandaedre.com/coverage/Ravenous/ravenous_roll20/main/test.svg)
![couverture](https://assets.dandaedre.com/coverage/Ravenous/ravenous_roll20/main/coverage.svg)
![Version actuelle](https://assets.dandaedre.com/coverage/Ravenous/ravenous_roll20/main/version.svg)
![Tests CI](https://assets.dandaedre.com/coverage/Ravenous/ravenous_roll20/main/test.svg)
![Couverture Python](https://assets.dandaedre.com/coverage/Ravenous/ravenous_roll20/main/coverage.svg)
Feuille de personnage Roll20 générée depuis les données du livre
[`ravenous_typst`](ravenous_typst). Le résultat reprend la palette parchemin,
or et sang du livre et fournit :
Feuille de personnage française pour jouer à Ravenous dans Roll20. Le dépôt
génère la feuille depuis les données épinglées du livre
[`ravenous_typst`](ravenous_typst), ainsi que deux outils web statiques pour
l'artisanat et les effets. La génération et les tests locaux sont automatisés ;
les comportements qui nécessitent encore une validation dans Roll20 sont suivis
dans [`TASKS.md`](TASKS.md).
- les caractéristiques et statistiques dérivées de Ravenous ;
- toutes les compétences générales officielles, les compétences maison et leurs modificateurs ;
- les attaques et protections sous forme de sections répétables, avec jets de défense et calcul des dégâts dans Roll20 ;
- une page de santé détaillée par localisation (PV, protection et armure), ainsi que toutes les résistances physiques et élémentaires ;
- les potions, nourritures et effets temporaires en texte libre, publiables dans
le chat ;
- l'ajout individuel des techniques d'école depuis les TSV du livre, avec
traduction du balisage Typst et bouton d'activation dans le chat.
- un sélecteur d'origine et l'ajout de ses pouvoirs stade par stade dans un
onglet dédié, avec des lignes libres pour les pouvoirs personnalisés.
## Prérequis
## Construction locale
- Git, Python 3.11 ou plus récent et [`uv`](https://docs.astral.sh/uv/) ;
- une partie Roll20 acceptant une feuille personnalisée ;
- Node.js uniquement pour les simulations locales des workers et scripts Mod ;
- un abonnement Roll20 donnant accès aux scripts Mod pour les imports et
exports facultatifs.
Initialiser le sous-module une première fois :
## Installation rapide
Depuis la racine du dépôt :
```sh
git submodule update --init --recursive
```
Puis construire avec `uv` (aucun `pip` global n'est utilisé) :
```sh
./scripts/build.sh
```
Le script crée `.venv/` et produit dans `build/` :
Dans l'éditeur de feuille personnalisée Roll20, choisissez le mode CSE actuel,
laissez **Legacy Sanitization désactivé**, puis copiez :
- `ravenous.html`, `ravenous.css` et `translation.json`, à charger dans
l'éditeur de feuille personnalisée Roll20 ;
- `sheet.json`, comme base pour une future soumission au dépôt communautaire
Roll20 (une capture `ravenous.png` devra alors être ajoutée) ;
- `build-info.json`, qui indique le nombre d'écoles, techniques et compétences
importées ainsi que l'empreinte du contenu.
- `build/ravenous.html` dans le panneau HTML ;
- `build/ravenous.css` dans le panneau CSS ;
- `build/translation.json` dans le panneau Traductions.
### Choisir un thème
Ouvrez une fiche dans le Custom Sheet Sandbox. Le résultat attendu est une
feuille Ravenous à huit onglets avec caractéristiques calculées, compétences,
combat, santé, consommables, écoles, pouvoirs et suivi des effets.
Chaque personnage choisit son thème avec le sélecteur **Apparence** en haut de
la feuille. La sélection est conservée dans l'attribut Roll20 `theme` et
s'applique également aux cartes de chat du personnage. Toutes les palettes de
`ravenous_typst/setup/theme/themes.typ` sont intégrées automatiquement au build ;
le thème initial vient de `document.color_scheme` dans
`ravenous_typst/data/config/build.yaml`.
## Utilisation
Pour afficher les identifiants disponibles :
```sh
./scripts/build.sh --list-themes
```
Pour produire un bundle dont le thème initial et de secours couvre aussi les
contrôles et boîtes d'interface situés hors de la zone recolorée, utilisez
`--theme-ui`. Tous les thèmes restent ensuite disponibles dans **Apparence** :
```sh
./scripts/build.sh --theme-ui steel --output-dir build-steel
./scripts/build.sh --theme-ui steel --output-dir build-steel --check
```
La limite des tiers d'école vient directement de
`ravenous_typst/data/config/build.yaml` : seuls les tiers strictement inférieurs
à `build.max_tier_exclusive` sont proposés par la feuille. Les trigrammes affichés
dans le menu des techniques viennent de `schools.trigrams` dans ce même fichier.
Pour vérifier qu'un build versionné correspond aux sources :
La fiche conserve ses valeurs dans les attributs Roll20. Les jets utilisent la
carte de chat Ravenous ; les actions **Défendre** et **Subir** demandent le token
du défenseur. Les dépenses, PV, intégrité d'armure et effets mécaniques restent
manuels.
- [Installer et utiliser la feuille dans Roll20](docs/roll20-usage.md)
- [Sauvegarder, importer et partager avec les scripts Mod](docs/mod-scripts.md)
- [Copier les macros Roll20 prêtes à l'emploi](docs/macros.md)
- [Utiliser le format JSON d'artisanat](docs/craft-json-v1.md)
Les compagnons statiques publiés sont :
- l'[atelier d'artisanat](https://assets.dandaedre.com/ravenous_roll20/ravenous_craft/) ;
- la [bibliothèque d'effets](https://assets.dandaedre.com/ravenous_roll20/ravenous_effects/).
## Documentation
- [`FEATURES.md`](FEATURES.md) : comportement attendu et critères
d'acceptation ;
- [`ARCHITECTURE.md`](ARCHITECTURE.md) : attributs persistants, formats, flux et
frontières entre composants ;
- [`docs/development.md`](docs/development.md) : thèmes, tests, couverture, mise
à jour du livre et publication ;
- [`TASKS.md`](TASKS.md) : validations Roll20 effectuées et travail restant ;
- [`AGENTS.md`](AGENTS.md) : règles de contribution et matrice complète de
vérification.
## Développement
Les commandes courantes sont :
```sh
./scripts/build.sh
uv run python -m unittest discover -s tests -v
node tests/test_worker.mjs
./scripts/run-python-coverage.sh
./scripts/build.sh --check
```
Les tests Python vérifient la génération. Des tests Node exécutent aussi le
sheet worker généré avec une simulation minimale des API Roll20 (recalcul,
résistances, protections, techniques et calculs de jets) :
La couverture des générateurs Python doit rester au-dessus du seuil de 85 %
défini dans `.coveragerc`. Consultez le
[guide de développement](docs/development.md) pour les suites des sites
compagnons, les autres tests Node et les contrôles déterministes.
```sh
uv run python -m unittest discover -s tests -v
node tests/test_worker.mjs
```
## Licence et état du projet
La couverture des générateurs Python se mesure avec la commande unique :
```sh
./scripts/run-python-coverage.sh
```
`coverage.py`, épinglé dans les dépendances de développement, applique le seuil
minimal de **85 % de couverture de lignes** défini par `.coveragerc`. La commande
écrit temporairement les données dans `coverage/.coverage` et le résumé lisible
par machine dans `coverage/coverage-summary.json`; tout le dossier `coverage/`
est ignoré par Git.
Si Podman est disponible, le même test Node peut tourner dans un conteneur
isolé, sans accès réseau et avec le dépôt monté en lecture seule. Construisez
d'abord la feuille ; le premier lancement télécharge l'image officielle Node :
```sh
./scripts/build.sh
./scripts/test-worker-container.sh
```
Cette simulation ne reproduit pas le moteur de dés, le navigateur ou le chat de
Roll20. Les interactions doivent aussi être testées dans le Custom Sheet
Sandbox de Roll20. La procédure de vérification est détaillée dans
Le code de ce dépôt est distribué sous [licence MIT](LICENSE). La feuille reste
une version de travail : les tests structuraux et les simulations locales ne
remplacent pas une validation dans une vraie partie Roll20. Les limites connues
et la procédure de signalement par reproduction sont consignées dans
[`TASKS.md`](TASKS.md).
## Essai d'import JSON par Mod Roll20
Un prototype minimal se trouve dans `roll20_mod/ravenous_import_name.js`. Il
crée un **nouveau personnage avec son nom seulement** ; il ne modifie aucun
personnage existant et n'importe pas encore les autres champs. Le créateur de
la partie doit disposer de l'accès aux Mod scripts de Roll20 (Pro/Elite).
Dans la page de la partie, ouvrez **Settings → Mod Scripts → New Script**,
collez le contenu du fichier, nommez le script puis cliquez sur **Save Script**.
Dans le chat de cette même partie, en tant que MJ, entrez :
```text
!ravenous-import-name {"name":"Ariane"}
```
Vérifiez qu'un nouveau personnage nommé « Ariane » apparaît dans le journal.
Chaque commande valide crée un personnage supplémentaire. Pour exécuter les
tests locaux de ce prototype :
```sh
node tests/test_mod_import.mjs
```
## Effets de compétence partagés
Le sous-onglet **DoT & effets** de l'onglet **Effets & tours** conserve une bibliothèque
de plusieurs altérations, dégâts ou soins sur la durée, bonus et malus. Chaque
effet peut être montré seul dans le chat puis référencé par son ID depuis les
options d'un pouvoir d'origine ou d'une technique d'école. Plusieurs effets peuvent être proposés
sur la même carte de jet et chacun possède son propre bouton d'ajout.
Pour rendre le bouton **Ajouter à ma fiche** fonctionnel, installez aussi
`roll20_mod/ravenous_shared_effects.js` comme Mod script. Le destinataire clique
le bouton, choisit un token lié à un personnage qu'il contrôle, puis retrouve
l'effet dans **Effets & tours** avec sa durée et ses rappels. Le script refuse
d'écrire sur un personnage que le joueur ne contrôle pas. Vérification locale :
```sh
node tests/test_shared_effects.mjs
```
La bibliothèque statique d'effets exporte aussi une sélection complète au
format versionné `ravenous-roll20-effects` v1. Installez
`roll20_mod/ravenous_effects_import.js`, puis sélectionnez le token du
personnage destinataire ou indiquez son ID :
```text
!ravenous-import-effects {"format":"ravenous-roll20-effects","version":1,"effects":[{"effect_id":"combustion","type":"dot","name":"Combustion"}]}
!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 est ajoutée à **DoT & effets** avec son ID, son type, sa durée
structurée et ses rappels. Le script refuse les champs inconnus, les valeurs
hors limites, les personnages non contrôlés et les handouts inaccessibles. Le
JSON exporté prépare une bibliothèque réutilisable ; il n'active pas les effets
dans le suivi des tours. L'export crée un handout privé contenant toutes les
entrées de **DoT & effets**. Les actions Fiche, Artisanat et Effets sont regroupées
dans le menu **Échanges JSON** de l'en-tête afin de ne pas surcharger la fiche.
Vérification locale :
```sh
node tests/test_effects_import.mjs
```
## Sauvegarde et import de personnages et de créatures
`roll20_mod/ravenous_character_io.js` est le script Mod d'échange de personnages.
Installez-le comme **New Script** dans une partie avec la feuille Ravenous. Il
utilise le format JSON versionné `ravenous-roll20-character`. Un MJ peut créer un
nouveau personnage ; un joueur peut exporter un personnage qu'il contrôle et le
remplacer en place à partir d'un handout auquel il a accès.
Dans le chat, en tant que MJ :
```text
!ravenous-export
!ravenous-export --id ID_DU_PERSONNAGE
!ravenous-import --handout ID_DU_HANDOUT
!ravenous-import {"format":"ravenous-roll20-character","version":1,"name":"Ariane","attributes":[]}
```
Pour un joueur, sélectionnez un token lié à son personnage :
```text
!ravenous-export
!ravenous-import --replace --handout ID_DU_HANDOUT
```
Les boutons **Exporter** et **Restaurer** dans l'en-tête de la feuille envoient
ces mêmes commandes avec l'ID du personnage courant ; ils ne nécessitent donc
pas de token sélectionné. **Restaurer** demande l'ID du handout source.
L'export joueur crée un handout contrôlé par ce joueur et place le JSON dans ses
**Notes** visibles. Le remplacement conserve l'objet personnage, son ID, ses
tokens liés, son avatar, ses droits et ses notes MJ ; il remplace son nom, sa bio,
ses attributs de feuille et ses capacités. Le JSON est entièrement validé avant
la suppression des anciennes lignes. Un joueur ne peut cibler qu'un personnage
qu'il contrôle ni lire un handout auquel il n'a pas accès. Le MJ peut aussi faire
un remplacement avec `--replace`, éventuellement suivi de `--id ID_DU_PERSONNAGE`.
Sans ID, sélectionnez exactement un token lié au personnage avant la commande.
Utilisez `--id` si vous ne disposez pas d'un token lié. L'export MJ crée un handout
réservé au MJ, dont les **GM Notes** contiennent le JSON
lisible. Copiez ce JSON dans un fichier pour le stocker hors de Roll20. Pour
importer un fichier volumineux, créez un handout, collez le JSON dans ses GM
Notes, puis utilisez `--handout` avec son ID. La commande directe convient aux
petits JSON. Gardez les handouts d'export privés : ils contiennent les notes MJ.
Les IDs sont visibles dans l'URL des objets Roll20. Après import, ouvrez le
personnage pour laisser les sheet workers recalculer les valeurs dérivées.
Pour créer un JSON depuis la base SQLite du livre du MJ :
```sh
git -C ravenous_typst submodule update --init data/src/db
python tools/export_monsters.py --id 1 --output /tmp/monster-1.json
python tools/export_monsters.py --all --output /tmp/ravenous-monsters
```
Pour produire un personnage d'exemple aléatoire mais reproductible (toutes les
sections répétables, Unicode et caractères sensibles inclus) :
```sh
python tools/generate_character.py --seed 42 --output /tmp/ravenous-example.json
```
Une même graine produit exactement le même JSON, ce qui permet de reproduire un
échec d'import. Sans `--output`, le JSON est écrit sur la sortie standard. La CI
génère, valide et archive également `build/example-character.json`. Elle
l'importe dans le simulateur de l'API Mod lorsque Node est disponible sur
l'agent ; l'absence de ce runtime n'empêche pas la construction de la feuille.
Le script `./scripts/build.sh` génère automatiquement ce même exemple dans son
dossier de sortie, et `./scripts/build.sh --check` vérifie également son contenu.
Jenkins exporte en plus les monstres d'ID 2 (`Yajjpnir`) et 5 (`Baloth Joueur`)
dans `build/example-monster-2.json` et `build/example-monster-5.json`, les
archive, puis les importe séparément avec le même simulateur pour vérifier les
localisations, attaques et pouvoirs générés.
Le build génère aussi deux charges utiles prêtes à importer :
`build/example-craft-forge.json` (attaque et protection) et
`build/example-craft-alchemy.json` (consommable et effet temporaire). Copiez le
contenu d'un fichier dans les GM Notes d'un handout privé, puis sélectionnez un
token lié au personnage et lancez :
```text
!ravenous-import-craft --handout ID_DU_HANDOUT
```
Ces exemples couvrent les quatre sections répétables prises en charge par
l'importeur et sont régénérés et vérifiés de façon déterministe par la CI.
Le convertisseur reprend les caractéristiques directement compatibles, les
localisations en lignes répétables, les capacités avec dégâts en attaques, et
les autres capacités en pouvoirs. Leurs descriptions et valeurs de dégâts
restent dans les notes des lignes. La base complète de la créature, y compris
les phases et les valeurs sans équivalent fidèle dans la feuille de chasseur,
est conservée en JSON dans les GM Notes du personnage. Les champs de jet
inconnus sont laissés à zéro : le MJ doit régler dés, seuils et dégâts avant
d'utiliser les boutons d'attaque. Les sheet workers de la feuille de chasseur
recalculent certaines valeurs dérivées à l'ouverture.
Vérification locale :
```sh
uv run python -m unittest discover -s tests -v
python tools/export_monsters.py --id 1 --output /tmp/ravenous-monster-test.json
RAVENOUS_MONSTER_JSON=/tmp/ravenous-monster-test.json node tests/test_character_io.mjs
```
Ces tests simulent l'API Mod et valident le format avec la base épinglée. Un
essai dans une partie Roll20 reste nécessaire pour confirmer l'affichage et
les limites des GM Notes.
## Rappels d'effets et tours
L'onglet **Effets & tours** regroupe les effets temporaires et les commandes de
tour. Les effets peuvent porter des rappels distincts de début et de fin de
tour. Leur durée structurée peut être manuelle, exprimée en tours, liée au
prochain début/à la prochaine fin de tour, ou réservée à la fin du combat et au
futur décompte par actions. Les boutons **Début du tour** et **Fin du tour**
affichent uniquement les rappels de la phase, décrémentent les durées concernées
et annoncent les effets terminés. Ils ne modifient jamais automatiquement PV,
armure, résistances ou ressources.
Le bouton **Supprimer les effets inactifs** nettoie en une fois les lignes déjà
terminées. Chaque ajout, traitement de phase et nettoyage affiche d'abord son
état d'exécution puis un message de résultat directement dans l'onglet concerné.
La configuration avancée d'un consommable peut être copiée dans les effets
actifs avec **Appliquer comme effet**. Une technique ou un pouvoir peut aussi
être copié avec **Suivre comme effet**, puis recevoir ses rappels structurés sans
tenter d'interpréter librement sa prose. À la construction, des heuristiques
centralisées reconnaissent les formulations françaises de début/fin de tour,
de prochain tour, de durée en tours et de fin de combat dans les données du
livre. Ces métadonnées sont donc recalculées automatiquement à chaque mise à
jour du livre, y compris pour les techniques et pouvoirs déjà ajoutés. Les
anciennes lignes d'effets, dépourvues de champs structurés, restent actives en
durée manuelle.
## Import d'objets fabriqués
`roll20_mod/ravenous_craft_import.js` importe les résultats finalisés d'un
futur site d'artisanat dans un personnage existant. Le contrat JSON versionné
et les exemples sont définis dans [`docs/craft-json-v1.md`](docs/craft-json-v1.md).
Il couvre les armes, protections, consommables et effets temporaires. Le Mod ne
recalcule pas la recette et n'applique aucun effet automatiquement.
Installez le script comme Mod, puis sélectionnez le token du personnage et
utilisez un JSON direct ou les GM Notes d'un handout privé :
```text
!ravenous-import-craft {"format":"ravenous-roll20-craft","version":1,"items":[{"type":"consumable","name":"Potion rouge","kind":"Potion","quantity":1}]}
!ravenous-import-craft --handout ID_DU_HANDOUT
!ravenous-import-craft --id ID_DU_PERSONNAGE --handout ID_DU_HANDOUT
```
Les boutons **Export artisanat** et **Import artisanat** de l'en-tête ciblent
directement le personnage courant. L'export regroupe ses attaques, protections,
consommables et effets temporaires compatibles dans un handout. Pour un joueur,
ce handout lui est attribué et le JSON se trouve dans ses Notes visibles ; le
bouton d'import peut ensuite le charger dans un autre personnage qu'il contrôle.
Les joueurs peuvent utiliser cette commande uniquement avec un personnage
qu'ils contrôlent et un handout auquel ils ont accès. Le MJ n'est pas soumis à
ces restrictions. Des actions de macro prêtes à copier pour cet import et les
autres commandes Mod sont regroupées dans [`docs/macros.md`](docs/macros.md).
Vérification locale :
```sh
node tests/test_craft_import.mjs
```
## Mise à jour depuis le livre
```sh
git submodule update --remote ravenous_typst
./scripts/build.sh
```
Les compétences proviennent de
`ravenous_typst/data/src/character_sheet.yaml` et les techniques de
`ravenous_typst/data/src/schools/*.tsv`. Les transformations sont dans
`tools/build.py`; le HTML et le CSS maintenus à la main restent dans `src/`.
Les origines et leurs pouvoirs proviennent de
`ravenous_typst/data/src/origines/*.yaml`.
Les spécialités imbriquées (`subskills`) sont également importées ; leur nom
complet et leur identifiant incluent la compétence parente pour éviter les
ambiguïtés, mais l'affichage les indente sous leur parent et ne répète pas son
nom.
Il n'est donc pas nécessaire de recopier les données lors d'une mise à jour du
livre.
## CI et publication
Le `Jenkinsfile`, inspiré de celui de `ravenous_typst`, initialise les
sous-modules, installe `uv` via Cargo si nécessaire, reconstruit la feuille,
exécute les tests et vérifie que `build/` est à jour. Jenkins archive ensuite
le dossier complet avec empreintes.
Sur l'agent FreeBSD, il vérifie aussi que le Python utilisé par `uv` dispose de
`sqlite3` et installe au besoin le paquet `pyXY-sqlite3` correspondant via
`pkg` (directement ou avec `sudo`/`doas` non interactif). Les tests du
convertisseur de monstres en ont besoin.
À chaque build, Jenkins recrée `coverage/`, n'enregistre le succès des tests et
de la mesure qu'après leur exécution complète, puis génère exactement
`coverage/version.svg`, `coverage/test.svg` et `coverage/coverage.svg`. La
version vient de `[project].version` dans `pyproject.toml`. Ces trois fichiers,
et eux seuls, sont archivés avec empreintes. Sur la branche par défaut `main`,
ils sont publiés atomiquement dans
`/mnt/assets/coverage/Ravenous/ravenous_roll20/main/` et servis aux URL affichées
sous le titre de ce README. Les autres branches les génèrent et les archivent
sans modifier les badges publics. Une construction `main` en échec publie un
test rouge et une couverture neutre si sa mesure n'a pas abouti.
Le moteur SVG est la copie du script maintenu
`agent-tasks/scripts/ci-coverage-badges.sh` à la révision
`fb9d8f7d16f100c2d1377f23394a2302eac9ab18`. Le serveur d'actifs, configuré hors
de ce dépôt, devrait monter ces fichiers en lecture seule, désactiver le listing
des dossiers, servir les SVG avec une politique CSP restrictive et revalider
rapidement ces URL mutables.
Les branches `main` et `master` sont publiées dans
`/mnt/assets/ravenous_roll20/ravenous_sheet`, correspondant à
`https://assets.dandaedre.com/ravenous_roll20/ravenous_sheet/`. Jenkins crée le
dossier cible s'il manque. La racine `ravenous_roll20` n'est jamais synchronisée
avec `--delete` ; seule la sous-arborescence du produit l'est. Les branches
`candlelight` et `lighthouse` utilisent respectivement les dossiers suffixés
`_candlelight` et `_lighthouse`. Les autres branches sont construites et
archivées sans être déployées. Le pipeline ne modifie plus `/mnt/books`.
Le pipeline construit également la preuve de concept de l'atelier d'artisanat
statique depuis `craft_web/`. Elle est publiée dans
`/mnt/assets/ravenous_roll20/ravenous_craft`, soit
`https://assets.dandaedre.com/ravenous_roll20/ravenous_craft/`, avec les suffixes
`_candlelight` et `_lighthouse`. Le site ne requiert ni Node.js ni serveur
applicatif : Python génère ses fichiers HTML, CSS, JavaScript et son catalogue.
La bibliothèque statique d'altérations et d'effets de `effects_web/` suit le
même cycle de construction, de test déterministe, d'archivage et de
publication. La production est disponible sous
`https://assets.dandaedre.com/ravenous_roll20/ravenous_effects/`; les branches de
développement et de revue utilisent respectivement les suffixes `_candlelight`
et `_lighthouse`. Son catalogue, ses thèmes et son schéma JSON sont générés à
partir de la même révision épinglée du livre.
## Notes Roll20
Dans une partie utilisant une feuille personnalisée, copiez le contenu des
trois fichiers HTML, CSS et traduction dans les panneaux correspondants. La
feuille cible le mode CSE actuel : laissez **Legacy Sanitization désactivé**.
La police Google distante est facultative ; sans accès réseau, les polices de
secours Georgia/serif sont utilisées et toute la mise en page reste active. La
prévisualisation intégrée de Roll20 ne simule pas complètement les sheet
workers ni les sections répétables : validez les imports et les jets dans le
bac à sable de feuille ou dans une partie de test.
Pour utiliser **Défendre** ou **Subir** depuis la carte d'une attaque, cliquez
le token du défenseur lorsque Roll20 affiche le ciblage « Défenseur ».
La macro utilise alors sa compétence d'Esquive ou de
Parade et son modificateur temporaire, sans ajouter la caractéristique associée.
Le bouton **Jets secrets** dans l'en-tête envoie les jets du personnage
uniquement au maître de jeu. Les actions Défendre et Subir suivent le réglage
du token défenseur ciblé.
Avant d'utiliser **Subir** depuis une attaque, cochez dans l'onglet Santé les
résistances applicables et, dans l'onglet Combat, les protections couvrant la
localisation. Les résistances cochées se cumulent et retirent chacune deux DMG
par point. Une protection cochée ne compte que si son intégrité est supérieure
à zéro ; le calcul retire alors sa Protection ainsi que la Force finale du
défenseur ciblé.
Le menu Protection de **Subir** permet d'utiliser les protections cochées ou la
protection d'une localisation fixe/personnalisée. Pour l'AB, les résistances
retirent un point par point et seule la première protection valide de la liste
Combat s'applique, sans la Force ; ordonnez donc les protections de haut en bas
selon leur ordre d'impact.
Dans l'onglet **Chasseur**, choisissez l'origine du personnage. Dans l'onglet
**Pouvoirs**, choisissez un stade puis cliquez sur **Ajouter les pouvoirs du
stade**. Tous les pouvoirs de ce stade pour l'origine sélectionnée sont ajoutés.
Une même entrée ne peut être ajoutée qu'une fois. Les lignes sont
modifiables et la section répétable permet d'ajouter des pouvoirs personnalisés.
Changer d'origine ne supprime pas les pouvoirs existants. Les pouvoirs sont
affichables dans le chat mais n'appliquent pas automatiquement leurs effets.

View File

@ -24,9 +24,9 @@ parser, browser, or chat.
all master-visible monsters locally.
- [x] Allow players to export controlled characters and restore them in place
without changing character IDs, token links, ownership, or GM-only notes.
- [x] Define the versioned craft JSON interface and add a GM-only Mod importer
for weapons, protections, consumables, and temporary effects. Validate all
destinations, handout input, and invalid payloads locally.
- [x] Define the versioned craft JSON interface and add a permission-aware Mod
importer for weapons, protections, consumables, and temporary effects.
Validate all destinations, handout input, and invalid payloads locally.
- [x] Add structured start/end-turn reminders to temporary effects, including
turn countdowns, expiration notices, and copying reminder configuration from
consumables. Keep mechanical changes manual.
@ -43,8 +43,13 @@ parser, browser, or chat.
- [x] Add Python line coverage and mutable CI badges following the shared badge
contract. **2026-10-04:** the local coverage command measured 91.8% line
coverage against an 85% floor; renderer and temporary-root publication tests
pass. Real Jenkins archival/publication and public URL retrieval remain to be
observed on the next `main` build.
pass. After the `main` build, all three public URLs returned HTTP 200, parsed
as XML and reported version 0.1.0, passing tests and 92% rounded coverage.
- [x] Reduce the README to onboarding, first use, navigation, development and
license/status information; move Roll20 use, Mod workflows and CI details to
focused documentation. **2026-10-04:** local links and anchors resolve, all
retained public links return HTTP 200, and the documented quick-start and
validation commands pass locally.
## Next: Roll20 smoke test

View File

@ -86,8 +86,9 @@ Example containing two outputs from one craft:
## Roll20 commands
Install `roll20_mod/ravenous_craft_import.js` as a Mod script. Commands are
GM-only. With one destination token selected:
Install `roll20_mod/ravenous_craft_import.js` as a Mod script. A player may
target a character they control and read a shared/controlled handout; a GM may
target any character and handout. With one destination token selected:
```text
!ravenous-import-craft {"format":"ravenous-roll20-craft","version":1,"items":[{"type":"consumable","name":"Potion rouge","kind":"Potion","quantity":1}]}
@ -101,6 +102,7 @@ Without a token, or to target a character directly:
!ravenous-import-craft --id CHARACTER_ID --handout HANDOUT_ID
```
For large JSON, paste it into a private handout's **GM Notes** and use the
handout form. Open the destination sheet after import so its workers refresh
derived protection summaries.
For large JSON, a GM can paste it into a private handout's **GM Notes**. A
player must use the visible **Notes** of a shared or controlled handout. Then use
the handout form and open the destination sheet so its workers refresh derived
protection summaries.

106
docs/development.md Normal file
View File

@ -0,0 +1,106 @@
# Développer et publier Ravenous Roll20
Ce guide regroupe les commandes avancées retirées du README. Les contrats de
comportement et d'architecture restent respectivement dans
[`FEATURES.md`](../FEATURES.md) et [`ARCHITECTURE.md`](../ARCHITECTURE.md).
## Construction
Prérequis : Git, Python 3.11 ou plus récent et `uv`. Depuis la racine :
```sh
git submodule update --init --recursive
./scripts/build.sh
```
Le build écrit la feuille, les métadonnées et les fixtures déterministes dans
`build/`. Il lit notamment `ravenous_typst/data/src/character_sheet.yaml`, les
écoles TSV, les origines YAML, les glossaires et
`ravenous_typst/data/config/build.yaml`. Les modèles maintenus à la main sont
dans `src/`; ne modifiez pas directement `build/`.
## Thèmes
Les palettes viennent de `ravenous_typst/setup/theme/themes.typ`. Le thème
initial vient de `document.color_scheme` dans la configuration du livre.
```sh
./scripts/build.sh --list-themes
./scripts/build.sh --theme-ui steel --output-dir build-steel
./scripts/build.sh --theme-ui steel --output-dir build-steel --check
```
Tous les thèmes restent sélectionnables par personnage, quel que soit le thème
initial du bundle.
## Vérification complète
```sh
./scripts/build.sh
uv run python -m unittest discover -s tests -v
node tests/test_worker.mjs
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
uv run python -m unittest discover -s craft_web/tests -v
uv run python -m unittest discover -s effects_web/tests -v
./scripts/run-python-coverage.sh
./scripts/build.sh --check
uv run python craft_web/tools/build.py --check
uv run python effects_web/tools/build.py --check
```
La couverture mesure les générateurs Python, écrit des fichiers ignorés dans
`coverage/` et impose le seuil de lignes de 85 % défini dans `.coveragerc`.
`./scripts/test-worker-container.sh` peut exécuter le test du worker dans un
conteneur Podman isolé après le build. Aucun de ces tests ne remplace une
validation dans Roll20.
## Mettre à jour les données du livre
```sh
git submodule update --remote ravenous_typst
./scripts/build.sh
```
Contrôlez le diff du sous-module et les descriptions traduites avant de valider
la mise à jour. La limite des tiers d'école et les trigrammes proviennent de la
configuration épinglée ; ne les recopiez pas dans les modèles.
## CI, badges et publication
Jenkins initialise les sous-modules, prépare `uv` et SQLite, construit les trois
livrables, exécute les tests, impose la couverture, archive les résultats et
vérifie les builds déterministes.
Les badges `version.svg`, `test.svg` et `coverage.svg` sont finalisés même après
un échec, archivés seuls avec empreintes et publiés uniquement depuis `main`
dans `/mnt/assets/coverage/Ravenous/ravenous_roll20/main/`. Ils sont servis à :
- `https://assets.dandaedre.com/coverage/Ravenous/ravenous_roll20/main/version.svg` ;
- `https://assets.dandaedre.com/coverage/Ravenous/ravenous_roll20/main/test.svg` ;
- `https://assets.dandaedre.com/coverage/Ravenous/ravenous_roll20/main/coverage.svg`.
Le moteur SVG est copié depuis `agent-tasks` à la révision
`fb9d8f7d16f100c2d1377f23394a2302eac9ab18`. Le serveur d'actifs devrait monter
les fichiers en lecture seule, désactiver le listing, appliquer une CSP
restrictive aux SVG et revalider rapidement ces URL mutables.
Les branches de publication des trois produits sont :
- `main` et `master` : noms de production ;
- `candlelight` : suffixe `_candlelight` ;
- `lighthouse` : suffixe `_lighthouse` ;
- les autres branches : construction et archivage sans déploiement.
Les cibles de production sont :
- `/mnt/assets/ravenous_roll20/ravenous_sheet/` ;
- `/mnt/assets/ravenous_roll20/ravenous_craft/` ;
- `/mnt/assets/ravenous_roll20/ravenous_effects/`.
Chaque aide de déploiement vérifie une liste blanche et utilise `rsync --delete`
uniquement dans le sous-dossier du produit. Les détails de flux et de sécurité
sont dans [`ARCHITECTURE.md`](../ARCHITECTURE.md#ci-and-deployment-topology).

114
docs/mod-scripts.md Normal file
View File

@ -0,0 +1,114 @@
# 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).

84
docs/roll20-usage.md Normal file
View File

@ -0,0 +1,84 @@
# Installer et utiliser la feuille Ravenous dans Roll20
Ce guide complète l'[installation rapide](../README.md#installation-rapide) avec
les réglages Roll20 et les comportements de jeu qui ne tiennent pas dans le
README.
## Installation
Construisez d'abord les fichiers depuis la racine du dépôt :
```sh
git submodule update --init --recursive
./scripts/build.sh
```
Dans une feuille personnalisée Roll20, utilisez le mode CSE actuel et laissez
**Legacy Sanitization désactivé**. Copiez `build/ravenous.html`,
`build/ravenous.css` et `build/translation.json` dans leurs panneaux respectifs.
La prévisualisation de l'éditeur ne simule pas complètement les workers, le
moteur de dés ou les sections répétables : utilisez le Custom Sheet Sandbox ou
une partie de test.
La police Google distante est facultative. Sans accès réseau, les polices de
secours Georgia/serif conservent la mise en page.
## Apparence et contenu généré
Chaque personnage choisit son thème dans **Apparence**. Ce choix est conservé
dans l'attribut `theme` et s'applique aussi aux cartes de chat. Les compétences,
techniques, origines et pouvoirs officiels viennent de la révision épinglée du
livre ; les lignes personnalisées restent modifiables.
Dans **Chasseur**, sélectionnez une origine. Dans **Pouvoirs**, choisissez un
stade puis **Ajouter les pouvoirs du stade**. Une source officielle ne peut être
ajoutée qu'une fois. Changer d'origine ne supprime pas les pouvoirs existants et
n'ajoute rien automatiquement.
## Combat et dégâts
Les jets de compétence et d'attaque publient une carte Ravenous dans le chat.
Pour **Défendre** ou **Subir**, choisissez le token du défenseur lorsque Roll20
affiche la cible « Défenseur ». La défense utilise Esquive ou Parade et son
modificateur temporaire. **Jets secrets** envoie les jets du personnage au MJ ;
les actions suivantes respectent le réglage du défenseur ciblé.
Avant **Subir** :
1. cochez les résistances applicables dans **Santé** ;
2. cochez les protections couvrant la localisation dans **Combat** ;
3. choisissez les protections cochées ou une localisation fixe/personnalisée.
Pour les DMG, chaque point d'une résistance cochée retire deux points ; une
protection ne compte que si son intégrité est positive, puis retire sa valeur de
Protection et la Force finale du défenseur. Pour l'AB, les résistances retirent
un point par point et seule la première protection valide de la liste Combat
s'applique, sans la Force. Ordonnez donc les protections selon leur ordre
d'impact.
Ces actions affichent le résultat : elles ne modifient ni les PV ni l'intégrité
de l'armure.
## Effets et tours
**Effets & tours** conserve les effets temporaires et une bibliothèque
réutilisable **DoT & effets**. Les boutons de début et fin de tour affichent les
rappels, décrémentent uniquement les durées configurées pour leur phase et
signalent les effets terminés. Ils ne changent jamais automatiquement PV,
armure, résistances ou ressources.
Un consommable peut être copié avec **Appliquer comme effet**. Une technique ou
un pouvoir peut être copié avec **Suivre comme effet**, puis recevoir des
rappels structurés. Les anciennes lignes sans métadonnées restent en durée
manuelle. **Supprimer les effets inactifs** retire les lignes déjà terminées.
Pour appliquer un effet réutilisable à un autre personnage, installez le script
décrit dans le [guide des scripts Mod](mod-scripts.md#effets-partagés-et-bibliothèque).
## Frontières d'automatisation
La feuille calcule les totaux, les statistiques dérivées et l'affichage des
dégâts. Elle ne dépense pas les ressources, ne retire pas les PV, ne dégrade pas
l'armure et n'applique pas la prose des techniques, pouvoirs, consommables ou
effets. Les invariants complets sont dans [`FEATURES.md`](../FEATURES.md) et la
matrice de validation réelle dans [`TASKS.md`](../TASKS.md).