d10_cs_generator/README.md

225 lines
12 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# Système D10 — feuilles Roll20
Ce dépôt génère deux feuilles de personnage Roll20 : **base** et **cyberpunk**.
Les compétences fixes sont dans `data/base_skills.yaml` et
`data/cyberpunk_skills.yaml`. Les champs et variantes sont dans
`data/sheet_model.yaml`, les couleurs dans `data/themes.yaml`, et le style
commun dans `templates/sheet.css`. `tools/build.py` produit les fichiers à
charger dans Roll20.
Le dossier `agent_models/` est une zone de références locales fournie par
l'utilisateur; il est ignoré par Git et n'entre pas dans la génération D10.
[`FEATURES.md`](FEATURES.md) décrit les comportements sous forme de dossiers
portables et [`ARCHITECTURE.md`](ARCHITECTURE.md) décrit les composants, les
flux et l'ordre de reconstruction. Les scripts Mod sont conservés dans
[`scripts/`](scripts/) et s'installent séparément de la feuille.
## Construire
```sh
python -m venv .venv
.venv/bin/python -m pip install -r requirements.txt
./build.sh
./build.sh --clean
```
`build.sh` génère les deux variantes avec leurs sélecteurs de thème sous
`RPG/d10_character_sheet/`. Avec `--clean`, il supprime d'abord ce dossier
ainsi que `build/`, puis reconstruit les fichiers publiables. Il utilise
`.venv/bin/python` si disponible, sinon `python3` avec les dépendances déjà
installées. Pour générer un thème isolé ou lister les thèmes :
```sh
.venv/bin/python tools/build.py --variant base --theme parchment
.venv/bin/python tools/build.py --variant cyberpunk --theme night
.venv/bin/python tools/build.py --list-themes
```
Chaque build crée `sheet.html`, `sheet.css`, `translation.json`, `sheet.json`
et `build-info.json` dans `build/<variante>/<thème>/`. Le build cyberpunk copie
aussi les deux images originales de `assets/`. Il est possible de
choisir un autre répertoire avec `--output-dir`. Charger le HTML, le CSS et
la traduction dans les onglets correspondants de l'éditeur de feuille
personnalisée Roll20. `sheet.json` est un manifeste; `build-info.json` contient
la variante, le thème, le nombre de compétences et une empreinte du résultat.
Les sections **01 Caractéristiques** et **02 Ressources** restent visibles.
La variante base a deux onglets principaux, **Compétences** et **Combat**.
Dans Compétences, quatre sous-onglets séparent **Combat et combat libre**,
**Compétences libres**, **Magie** et **Équipement**. Les lignes répétables
gardent leurs noms d'attributs et de section. La variante cyberpunk conserve
les onglets **Compétences**, **Combat** et **Autres**. Ses sous-onglets issus du
catalogue YAML sont **Physique**, **Intellectuelles** et **Social**.
Les compétences libres et les contacts répétables restent dans **Autres**.
Les contacts ont un nom et un niveau, sans caractéristique associée. Leur
bouton **Show** affiche ces informations dans le chat sans lancer de dé.
Les consommables d'**Arsenal** ont aussi un bouton **Show** qui affiche leur
nom, leur quantité et leurs notes sans lancer de dé ni modifier la quantité.
L'onglet **Combat** cyberpunk contient seulement l'initiative et son jet;
les attaques et dégâts des armes sont gérés dans **Arsenal**, sous **Combat**.
Les personnages qui avaient sélectionné l'ancien onglet de compétences
**Arsenal** voient **Physique** lors du prochain affichage des compétences.
La variante base
conserve ses champs de combat génériques et ses armes équipées.
Le choix principal est stocké dans `d10_tab`, celui des sous-onglets base dans
`d10_skill_tab` et celui des catégories cyberpunk dans `d10_category_tab`.
Les personnages qui avaient enregistré `core` ou, pour la variante base,
`other` affichent **Compétences** jusqu'au prochain clic. L'en-tête reste visible.
**Arsenal** contient **Distance**, **Mêlée** et **Consommable**. Les armes restent
dans les sections répétables `distance` et `melee`. Le sélecteur de thème dans l'en-tête des deux variantes conserve
le choix dans `d10_theme_choice` et applique immédiatement la palette via
`d10_theme`. La variante base propose **Parchemin** et **Nuit** uniquement.
Les 18 palettes du dossier local `styles/themes/` ont été
adaptées aux cinq couleurs de la feuille et copiées dans `data/themes.yaml`;
le build ne dépend pas de ce dossier. `parchment` et `night` restent disponibles
sous les noms **Parchemin** et **Nuit** dans le sélecteur cyberpunk.
`--theme` choisit le thème initial; tous les thèmes modifient seulement les
couleurs et la visibilité de la silhouette, sans modifier les champs ni les jets.
Chaque arme cyberpunk a un seuil de base, une précision et une spécialité de
combat facultative. Le nombre de dés est demandé à chaque attaque dans une
fenêtre Roll20, avec 1 par défaut. Les jets de combat utilisent des d10 avec
`cs1cf10`; les autres jets utilisent le dé sélectionné avec `cs1cfX`, où X
est le nombre de faces. L'attaque compte les dés inférieurs ou
égaux à `seuil de base + compétence + précision`. Pour un tir simple ou une
attaque de mêlée, les dégâts valent `dégâts de base + (réussites retenues − 1)
× dégâts / réussite`, ou zéro sans réussite. **Rmax** limite les réussites
retenues; `0` signifie sans limite et préserve les anciennes fiches. Pour une
rafale ou un tir automatique, la carte affiche séparément les dégâts de chaque
tir réussi (`X, X, X`) sans les additionner. Chaque tir inflige les dégâts de
base; un dé naturel de 1 inflige `dégâts de base + dégâts / réussite` pour ce
tir (`X + bonus, X, X`). Le nombre d'instances de dégâts ne peut jamais dépasser
le nombre de balles tirées, même lorsque Rmax vaut 0. Rmax ne s'applique pas à ces modes. Une rafale ajoute
un dé. Les tirs vérifient le coût en munitions du mode choisi et retirent
ces munitions du chargeur après le jet. Une rafale ou un tir automatique peut
être déclenché avec moins de munitions que son coût normal; il vide alors le
chargeur. Un chargeur vide bloque toujours le tir. La réserve compte les **chargeurs de
rechange**, et non les balles. Recharger consomme un chargeur de réserve et
remplit le chargeur actuel à sa capacité; les balles qui restaient dans
l'ancien chargeur sont perdues. Les personnages existants dont la réserve
comptait des balles doivent corriger cette valeur. Le bouton
**Dégâts** applique la formule du tir simple avec Rmax aux réussites saisies
manuellement, sans dépenser de
munitions. Les champs historiques `name`, `damage` et `notes` de ces deux
sections sont conservés; les nouvelles valeurs doivent être renseignées sur
les personnages existants. Les anciennes sections historiques
`ranged-weapons` et `melee-weapons` ne migrent pas automatiquement.
Les boutons de Distance utilisent chacun un événement nommé. Les identifiants
d'action répétables n'utilisent plus de tiret bas
(`firesingle`, `fireburst`, `fireauto` et `damage`); ce sont des identifiants de
boutons, pas des attributs sauvegardés, donc ce changement ne déplace aucune
donnée de personnage.
Dans la variante cyberpunk, 02 affiche aussi deux cartes côte à côte :
**Santé** (PV de la tête, du torse et des membres) et **Armure** (protection,
intégrité et intégrité maximale aux mêmes localisations). Les cases sont
posées sur les images originales `robotman_health_r.png` et
`robotman_armor_r.png`. Les attributs de localisation existants gardent leurs
noms; les nouveaux maxima portent le suffixe `_maximum`. Sur un écran étroit,
les cartes se placent l'une sous l'autre. Les champs numériques masquent les
flèches de réglage des navigateurs Firefox et Chromium.
Par défaut, le HTML cyberpunk référence directement les deux PNG publiés dans
[`RPG/d10_character_sheet/assets/`](https://books.dandaedre.com/RPG/d10_character_sheet/assets/).
Pour un aperçu local sans réseau, les PNG restent copiés à côté de `sheet.html`
et peuvent être référencés avec une valeur vide :
```sh
.venv/bin/python tools/build.py --variant cyberpunk --theme parchment \
--asset-base-url ''
```
Une autre adresse HTTPS publique peut être fournie avec `--asset-base-url`.
Charger le HTML généré dans l'éditeur Roll20 avec le CSS et la traduction.
## Échanges JSON de personnages
Les deux variantes affichent **Échanges JSON** dans l'en-tête. Cette interface
requiert l'installation séparée de `scripts/d10_character_io.js` dans les Mod
Scripts de la campagne Roll20. **Exporter** crée un handout contenant le format
versionné `d10-roll20-character` version 1. **Restaurer** demande l'identifiant
de ce handout et remplace les attributs et capacités du personnage courant sans
changer son identifiant Roll20 ni ses tokens liés.
L'export conserve les valeurs actuelles/maximales, les lignes répétables, les
capacités, la bio et les métadonnées auxquelles l'utilisateur a accès. Un joueur
ne peut exporter ou restaurer qu'un personnage qu'il contrôle; ses exports
n'incluent pas les notes MJ et sa restauration ne peut pas changer les notes
MJ, les contrôleurs ou la visibilité du journal. Seul un MJ peut créer un
nouveau personnage :
```text
!d10-export
!d10-export --id CHARACTER_ID
!d10-import --handout HANDOUT_ID
!d10-import --replace --id CHARACTER_ID --handout HANDOUT_ID
```
La restauration supprime d'abord les attributs et capacités existants de la
cible. Conserver un export récent avant de l'utiliser. Les handouts privés
d'export MJ contiennent les notes MJ et doivent rester privés. Le contrat
complet et ses critères de portage sont dans la fonctionnalité F07 de
[`FEATURES.md`](FEATURES.md).
## Publication Jenkins
L'agent Jenkins doit disposer de Python 3 avec `venv`. Les tests JavaScript des
onglets et des échanges JSON s'exécutent si Node.js est présent; son absence ne bloque pas la
publication. Le `Jenkinsfile` exécute les tests Python, construit une feuille
par variante et archive les résultats sous `RPG/d10_character_sheet/`. Le
dossier `RPG/d10_character_sheet/assets/` contient les deux PNG originaux. Les
fichiers HTML, CSS et JSON de chaque build sont dans
`RPG/d10_character_sheet/<variante>/`. Les anciens dossiers par thème sont
supprimés lors de la publication. La commande locale équivalente est :
```sh
.venv/bin/python tools/publish_builds.py
D10_BUILD_ROOT=RPG/d10_character_sheet node tests/test_tabs.mjs
node tests/test_character_io.mjs
```
Jenkins archive ces fichiers comme artifacts du job, puis déploie les builds de
`master` vers `/mnt/books/RPG/d10_character_sheet/` avec `rsync`, selon le même
principe que le pipeline Ravenous. Les autres branches ne sont pas déployées.
Les builds Jenkins utilisent désormais directement l'URL publique du dossier
`assets/` pour les images de la feuille cyberpunk.
## Vérifier
```sh
.venv/bin/python -m unittest discover -s tests -v
./build.sh
.venv/bin/python tools/build.py --variant base --theme parchment --output-dir RPG/d10_character_sheet/base --check
.venv/bin/python tools/build.py --variant cyberpunk --theme parchment --output-dir RPG/d10_character_sheet/cyberpunk --check
D10_BUILD_ROOT=RPG/d10_character_sheet node tests/test_tabs.mjs
node tests/test_character_io.mjs
```
Le test des onglets utilise les builds publiés `base` et `cyberpunk`;
exécuter `./build.sh` avant de le lancer. `--check` compare les
fichiers existants aux sources sans les réécrire. Les tests vérifient la
génération, les références d'attribut, les actions des onglets et les échanges
JSON dans une simulation de l'API Mod, mais ne
simulent pas l'affichage, le parseur de dés ou la sauvegarde de Roll20.
Le Custom Sheet Sandbox doit encore servir à valider les interactions et la
persistance des valeurs; les points précis sont dans [`TASKS.md`](TASKS.md).
## Sources et compatibilité
Le modèle de base reprend les attributs principaux de l'ancienne feuille
`feuille_sysd10.html`; les compétences cyberpunk viennent de la branche
`origin/cyberpunk-latest`, vérifiée contre `origin/cyberpunk`. Les anciennes
sources sont conservées dans l'historique Git, pas dans la génération.
Les noms des caractéristiques, ressources et de plusieurs champs de combat
ont été gardés quand cela était possible. Les sections répétables reconstruites
sous un autre nom ne migrent pas automatiquement.
La feuille historique utilisait aussi les macros `!crit` et des calculs de
combat complexes. Le nouveau build utilise un seuil moins un dé et un roll
template; il n'appelle pas ces macros. Le script
`scripts/d10_character_io.js` est testé séparément pour les échanges JSON. Les
scripts historiques `change.js` et `crit.js` restent disponibles sans
validation avec la nouvelle feuille. Les fonctionnalités avancées non
modélisées ne doivent pas être supposées compatibles.