Document variants and verify reproducible Roll20 builds

This commit is contained in:
Dandaedre 2026-09-18 23:29:36 +02:00
parent d732ade3cf
commit e05d6d731c
Signed by: Dandaedre
GPG Key ID: 440C6592E8A26D99
4 changed files with 98 additions and 10 deletions

View File

@ -31,3 +31,64 @@ Exemple (avec chatSetAttr) [chatSetAttr](https://github.com/Roll20/roll20-api-sc
```sheet-```. Il faut donc prévoir le CSS en conséquence.
##### Ces informations proviennent de la doc Roll20, et plus particulièrement de la page [Building Character Sheet](https://wiki.roll20.net/Building_Character_Sheets).
## Générateur YAML (base et cyberpunk)
La nouvelle génération utilise uniquement les variantes **base** et **cyberpunk**.
Les anciennes feuilles à la racine restent comme références pour les attributs
Roll20 et les règles qui ne sont pas encore modélisées. Le dossier
`model_ravenous_roll20/` est une référence de méthode, sans contenu Ravenous
importé dans la feuille D10.
Installer PyYAML dans un environnement virtuel puis construire :
```sh
python -m venv .venv
.venv/bin/python -m pip install -r requirements.txt
.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
.venv/bin/python tools/build.py --variant cyberpunk --theme night --check
.venv/bin/python -m unittest discover -s tests -v
```
Chaque commande produit `sheet.html`, `sheet.css`, `translation.json`,
`sheet.json` et `build-info.json` dans `build/<variant>/<theme>/`. Le dossier
peut être changé avec `--output-dir`. Copier HTML, CSS et traduction dans les
onglets correspondants de l'éditeur de feuille personnalisée Roll20.
`sheet.json` sert de manifeste pour un dépôt de feuilles; `build-info.json`
indique la variante, le thème, le nombre de compétences et une empreinte.
`--check` compare les fichiers existants sans les réécrire.
Les compétences fixes sont dans `data/base_skills.yaml` et
`data/cyberpunk_skills.yaml`. Le premier reprend les compétences de combat
nommées dans la feuille de base; la feuille de base conserve aussi des lignes
libres. Le second est issu du catalogue `helpers/cyberpunk2.txt` de
`origin/cyberpunk-latest` (153 compétences), comparé à `origin/cyberpunk`.
Les sections, champs et variantes sont définis dans `data/sheet_model.yaml`;
les palettes sont dans `data/themes.yaml`. Ajouter une compétence ne demande
pas de modifier le code Python. Les identifiants sont stables et validés avant
la génération. Le changement de thème ne change que les couleurs et la classe
racine du HTML.
### Compatibilité et limites
La nouvelle feuille conserve les noms des caractéristiques, des ressources,
des compétences fixes de combat de base et de plusieurs champs d'armes. La
variante cyberpunk conserve les noms de compétences de l'ancien générateur et
les PV/protection/intégrité par localisation. Les sections répétables sont
reconstruites à partir du modèle; les lignes déjà stockées sous un autre nom
de section ne migrent pas automatiquement. La feuille précédente comportait
aussi des macros `!crit` et des calculs de combat complexes; le nouveau build
ne les appelle pas. Les boutons de jet de la nouvelle feuille utilisent un
seuil moins un dé et affichent le résultat via un roll template. Les valeurs
avancées de combat et les comportements des scripts Mod restent dans les
anciennes sources tant qu'ils n'ont pas de modèle D10 vérifié.
Les tests locaux valident les quatre combinaisons variante/thème, les
références d'attribut dans les jets, les couleurs, les identifiants et le build
reproductible. Ils ne simulent pas le parseur de dés, l'affichage ou la
sauvegarde de Roll20. Dans le Custom Sheet Sandbox, charger chaque variante,
ajouter une ligne répétable, lancer les jets, sauvegarder et rouvrir deux
personnages. La [documentation officielle Roll20](https://help.roll20.net/hc/en-us/categories/360003756473-Sheet-Development)
décrit l'éditeur et les limitations des feuilles personnalisées.

View File

@ -1,11 +1,11 @@
# D10 sheet work
- [x] Inventory base, cyberpunk, and Ravenous model; set scope and agent rules.
- [ ] Define variant models, skill YAML, and stable identifiers; document source mapping.
- [ ] Build a deterministic generator for Roll20 HTML, CSS, and sheet.json.
- [ ] Add base and cyberpunk themes without altering stored fields or rules.
- [ ] Test validation, generated fields, references, and both variant builds.
- [ ] Document build, use, variant differences, and Roll20 sandbox checks.
- [x] Define variant models, skill YAML, and stable identifiers; document source mapping.
- [x] Build a deterministic generator for Roll20 HTML, CSS, translation.json, and sheet.json.
- [x] Add parchment and night themes without altering rolls or stored fields.
- [x] Test validation, generated fields, references, and both variant builds.
- [x] Document build, use, variant differences, migration limits, and Roll20 sandbox checks.
## Live Roll20 checks after local verification

View File

@ -24,6 +24,10 @@ class BuildTests(unittest.TestCase):
self.assertNotIn('Ravenous', files['sheet.html'])
self.assertIn('--d10-accent:', files['sheet.css'])
self.assertEqual(files, build.build(variant, theme, Path(tmp)))
build.build(variant, theme, Path(tmp), check=True)
(Path(tmp) / 'sheet.css').write_text('stale', encoding='utf-8')
with self.assertRaisesRegex(ValueError, 'stale'):
build.build(variant, theme, Path(tmp), check=True)
def test_attributes_referenced_by_generated_rolls(self):
for variant in ('base', 'cyberpunk'):
@ -35,6 +39,11 @@ class BuildTests(unittest.TestCase):
self.assertEqual(len(declared), len(set(declared)))
self.assertIn('base-Force', declared)
self.assertIn('Life_Points', declared)
self.assertIn('general_attack_threshold', declared)
self.assertIn('general_item_weapon1', declared)
if variant == 'cyberpunk':
self.assertIn('Life_Points_head', declared)
self.assertIn('repeating_distance', markup)
def test_theme_is_visual_only(self):
with tempfile.TemporaryDirectory() as tmp:

View File

@ -56,14 +56,22 @@ def validate(model, skills, theme):
sections = skills['sections']
if not isinstance(sections, list) or not sections:
raise ValueError('skills need sections')
generated_fields = set()
for section in sections:
for group in section['groups']:
prefix = ''.join(c for c in group['name'].replace(' ', '') if c.isascii() and c.isalpha()).lower()
if not prefix:
raise ValueError(f'group has no usable identifier: {group["name"]!r}')
seen = set()
for skill in group.get('skills', []):
key = ident(skill['id'])
if key in seen:
raise ValueError(f'duplicate skill in {group["name"]}: {key}')
seen.add(key)
stem = f'{prefix}_skilllevel_{key}'
if stem in generated_fields:
raise ValueError(f'duplicate generated skill field: {stem}')
generated_fields.add(stem)
if skill.get('parent') and skill['parent'] not in seen:
raise ValueError(f'unknown or later parent for {key}')
for block in model['repeating']:
@ -192,7 +200,7 @@ def render(model, skills, variant, theme_name, theme):
return html_text, css
def build(variant, theme_name, output):
def build(variant, theme_name, output, check=False):
source = read_yaml(DATA / 'sheet_model.yaml')
themes = read_yaml(DATA / 'themes.yaml')['themes']
if variant not in source['variants']:
@ -213,9 +221,15 @@ def build(variant, theme_name, output):
files['build-info.json'] = json.dumps({'variant': variant, 'theme': theme_name,
'skills': sum(len(g.get('skills', [])) for s in skills['sections'] for g in s['groups']),
'sha256': hashlib.sha256((html_text + css).encode()).hexdigest()}, indent=2) + '\n'
output.mkdir(parents=True, exist_ok=True)
for name, content in files.items():
(output / name).write_text(content, encoding='utf-8')
if check:
stale = [name for name, content in files.items()
if not (output / name).exists() or (output / name).read_text(encoding='utf-8') != content]
if stale:
raise ValueError(f'generated files are missing or stale: {", ".join(stale)}')
else:
output.mkdir(parents=True, exist_ok=True)
for name, content in files.items():
(output / name).write_text(content, encoding='utf-8')
return files
@ -225,12 +239,16 @@ def main():
parser.add_argument('--theme', choices=('parchment', 'night'), default='parchment')
parser.add_argument('--output-dir', type=Path)
parser.add_argument('--list-themes', action='store_true')
parser.add_argument('--check', action='store_true', help='verify existing output without writing')
args = parser.parse_args()
if args.list_themes:
print('\n'.join(read_yaml(DATA / 'themes.yaml')['themes']))
return
output = args.output_dir or ROOT / 'build' / args.variant / args.theme
build(args.variant, args.theme, output)
try:
build(args.variant, args.theme, output, check=args.check)
except ValueError as error:
parser.error(str(error))
print(output)
if __name__ == '__main__':