diff --git a/README.md b/README.md index c8141e2..bb94b8c 100644 --- a/README.md +++ b/README.md @@ -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. diff --git a/TASKS.md b/TASKS.md index a9dcde9..2891ab8 100644 --- a/TASKS.md +++ b/TASKS.md @@ -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 diff --git a/docs/craft-json-v1.md b/docs/craft-json-v1.md index 996c0d1..85c4d69 100644 --- a/docs/craft-json-v1.md +++ b/docs/craft-json-v1.md @@ -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. diff --git a/docs/development.md b/docs/development.md new file mode 100644 index 0000000..328fbf3 --- /dev/null +++ b/docs/development.md @@ -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). diff --git a/docs/mod-scripts.md b/docs/mod-scripts.md new file mode 100644 index 0000000..4c792c4 --- /dev/null +++ b/docs/mod-scripts.md @@ -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). diff --git a/docs/roll20-usage.md b/docs/roll20-usage.md new file mode 100644 index 0000000..9444a5e --- /dev/null +++ b/docs/roll20-usage.md @@ -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).