rinkplanner/docs/isu-rules.md
torsten 0613ffca3e feat: ISU-Level-Features und Level-Berechnung
- ElementFeature/ElementLevelRules mit Daten aus ISU Communication 2701
- 14 Pirouetten- und 4 Schrittsequenz-Features inkl. Pflicht- und
  Level-4-Regeln
- PathSegment.element_features mit Duplikaten fuer schwierige Variationen
- Feature-Menue und abgeleiteter Level-Hinweis im Element-Inspector,
  Auswahl undo-faehig
- 47 neue Level-Assertions, Whiteboard-Tests auf 228 erweitert (833 gesamt)
- Doku: isu-rules, Findings, Architektur und Roadmap aktualisiert
2026-10-31 09:21:03 +01:00

185 lines
7.6 KiB
Markdown
Raw 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.

# ISU-Regelwerk – Elementkatalog und Level-Features
Stand: 2026-10-31
Saison: **2025/26**
Quellen:
- ISU Communication No. 2707, *Single & Pair Skating – Scale of Values
valid as of July 1, 2025* (ersetzt Communication 2656)
- ISU Communication No. 2701, *Single & Pair Skating – Levels of Difficulty
and Guidelines for marking Grade of Execution and Program Components,
Season 2025/26* (ersetzt Communication 2623)
## Zweck
Der Katalog liefert die Base Values (BV) zu Elementkürzeln und Leveln. Er ist
bewusst reine Daten und vom Whiteboard entkoppelt: Eine neue Saison ersetzt
eine JSON-Datei, nicht den Modell- oder Controller-Code.
Aktuell abgedeckt:
- **24 Sprünge** von `1T` bis `4A`
- **16 Pirouettenfamilien** der Einzel- und Paarlauf-SoV
(einpositionig, mit Fußwechsel, Kombinationen, jeweils auch geflogen)
- **2 Sequenzen**: `StSq` (Base–4) und `ChSq` (nur Level 1)
- **Level-Features** für Pirouetten (14) und Schrittsequenzen (4) inklusive
Level-Berechnung nach Feature-Anzahl
Nicht abgedeckt (bewusst offen): GOE-Tabellen, reduzierte `V`-Varianten,
Unterrotations-/Fehlkanten-Suffixe (`<`, `<<`, `q`, `e`, `!`), Sprungkombinationen
und -folgen, Paarlauf-Hebungen/Twists/Throws sowie Eistanz-Elemente.
## Dateien
| Datei | Inhalt |
| :--- | :--- |
| `rinkplanner/src/core/rules/data/isu_sov_2025_26.json` | Katalog mit Base Values |
| `rinkplanner/src/core/rules/data/isu_levels_2025_26.json` | Level-Features und Schwellen |
| `rinkplanner/src/core/rules/element_catalog.gd` | Laden, Lookup, Vorschläge, Prüfung |
| `rinkplanner/src/core/rules/element_definition.gd` | eine Elementfamilie mit BV je Level |
| `rinkplanner/src/core/rules/element_level_rules.gd` | Feature-Lookup und Level-Berechnung |
| `rinkplanner/src/core/rules/element_feature.gd` | ein Level-Feature mit Zählgrenzen |
| `rinkplanner/tests/run_rules_tests.gd` | Katalog-Tests inkl. Stichproben |
| `rinkplanner/tests/run_level_tests.gd` | Feature- und Level-Tests |
## Datenformat
```json
{
"schema_version": 1,
"season": "2025/26",
"discipline": "Single & Pair Skating",
"valid_from": "2025-07-01",
"source": "ISU Communication No. 2707, ...",
"elements": [
{
"code": "3Lz",
"name": "Triple Lutz",
"type": "jump",
"base_value": 5.90
},
{
"code": "CCoSp",
"name": "Change foot combination spin",
"type": "spin",
"base_values": {
"B": 1.70, "1": 2.00, "2": 2.50, "3": 3.00, "4": 3.50
}
}
]
}
```
- `code` ist die **Familie** ohne Level-Suffix (`3Lz`, `CCoSp`, `StSq`).
- `type` ist `jump`, `spin` oder `sequence` und wird auf
`PathSegment.ElementType` abgebildet.
- Sprünge haben genau einen `base_value` (Level 0). Pirouetten und Sequenzen
nutzen `base_values` mit `"B"` für Base und `"1"`–`"4"` für die Level.
- Werte sind Dezimalzahlen mit Punkt; die UI zeigt sie mit Komma.
## Lookup-Regeln
`ElementCatalog` bietet:
```gdscript
var catalog := ElementCatalog.load_default()
catalog.find("CCoSp") # ElementDefinition oder null
catalog.get_base_value("CCoSp", 4) # 3.50
catalog.get_base_value("CCoSp4", -1) # 3.50 (Level aus Suffix)
catalog.get_base_value("3Lz", 2) # 5.90 (Sprunglevel wird ignoriert)
catalog.get_base_value("3X") # -1.0
catalog.get_segment_base_value(segment) # BV eines getaggten Segments
catalog.suggest(PathSegment.ElementType.SPIN, "ccosp", 8)
```
- Lookup ist getrimmt und case-insensitiv.
- Kanonische Codes mit Suffix (`CCoSp4`, `StSqB`) werden akzeptiert; ein Suffix
im Kürzel hat Vorrang vor der Level-Auswahl.
- Der Controller trennt beim Übernehmen ein Level-Suffix vom Kürzel ab und
setzt das Level-Feld. Gespeichert wird immer die Familie, z. B. `CCoSp` +
Level 4 statt `CCoSp4` + Level 3.
- Unbekannte Kürzel, falsche Typen und nicht vorhandene Level liefern `-1.0`
statt eines stillen Defaults.
- Existiert ein Element nur auf einem Level (`ChSq1`), löst ein bloßes `ChSq`
auf dieses eine Level auf.
- Der Base Value wird **nicht** am Segment gespeichert. Das Segment trägt nur
`element_code` und `element_level`; die Anzeige fragt den Katalog.
## Level-Features
Die Level-Regeln stehen in einer eigenen JSON-Datei, weil sie aus einer
anderen ISU-Communication stammen und sich unabhängig von den Base Values
ändern können. Pro Elementtyp gibt es Feature-Definitionen, Pflichtfeatures
und – bei Pirouetten – die Menge der Features, von denen mindestens eines für
Level 4 nötig ist.
| Elementtyp | Features | Besonderheit |
| :--- | :--- | :--- |
| Pirouette | 14 | Max. 2 schwierige Variationen pro Pirouette; Level 4 verlangt eines von 6 bestimmten Features |
| Schrittsequenz | 4 | Feature 1 (Vielfalt) ist Pflicht; ohne sie bleibt die Sequenz Base |
| `ChSq` | – | Fest Level 1 |
| Sprung | – | Nicht levelbar |
Die Schwelle ist für beide Typen gleich: 1 Feature → Level 1, 2 → Level 2,
3 → Level 3, 4 oder mehr → Level 4. Ohne Feature bleibt das Element Base.
`ElementLevelRules.calculate_level()` liefert neben dem Level auch die
gezählten, ignorierten und fehlenden Pflichtfeatures:
```gdscript
var rules := ElementLevelRules.load_default()
var result := rules.calculate_level(
PathSegment.ElementType.SPIN,
"CCoSp",
PackedStringArray(["difficult_variation", "difficult_exit"])
)
# result.level == 2, result.counted_features == 2
```
Das Segment speichert die Auswahl als `element_features`
(`PackedStringArray`). Duplikate sind erlaubt, damit zwei schwierige
Variationen als zwei Features zählen. Die Daten enthalten außerdem
`once_per_program` (Feature zählt nur beim ersten Versuch im Programm) und
`max_per_element`. Die Programmprüfung und die Begrenzung „max. zwei Features
pro Fuß“ sind noch nicht umgesetzt.
## Bedienung
Der Element-Inspector zeigt unter der Level-Auswahl `Base Value: 3,50`.
Unbekannte Kürzel erscheinen als „Kürzel nicht im Katalog 2025/26“. Der
Hinweis aktualisiert sich bei Änderungen an Typ, Kürzel und Level; der Tooltip
nennt Saison und Quelle.
Darunter liegt der Button **Features (n)**. Er öffnet eine Checkbox-Liste mit
den Features des Elementtyps; die Auswahl wird beim Schließen übernommen und
ist undo-fähig. Ein Hinweis zeigt die gezählten Features, das daraus
abgeleitete Level und – bei Abweichung – das manuell gewählte Level, z. B.
`Features: 2 · Level 2 · gewählt: Level 4`. Das gewählte Level bleibt
autoritativ; die Feature-Prüfung ersetzt es nicht stillschweigend.
## Neue Saison einpflegen
1. Neue ISU-Communication (Scale of Values) beschaffen und als JSON nach dem
obigen Schema anlegen, z. B. `isu_sov_2026_27.json`.
2. `season`, `valid_from` und `source` aktualisieren.
3. `ElementCatalog.DEFAULT_PATH` auf die neue Datei zeigen lassen.
4. Stichproben in `tests/run_rules_tests.gd` auf die neuen Werte anpassen
(mindestens ein Sprung, eine Pirouette, eine Sequenz).
5. Neue Level-Communication (Levels of Difficulty) als
`isu_levels_2026_27.json` anlegen, `ElementLevelRules.DEFAULT_PATH`
umstellen und `tests/run_level_tests.gd` anpassen.
6. `./tools/test.sh` ausführen.
7. Die alte Datei kann für Nachvollziehbarkeit im Repo bleiben; aktiv ist
immer genau eine Datei pro Regelart.
Die JSON-Dateien werden über `include_filter="*.json"` in allen Export-Presets
mit ausgeliefert.
## Nächste Ausbaustufen
- Programmweite Feature-Grenzen (`once_per_program`, max. 2 Features pro Fuß)
- Abgleich zwischen gewähltem Level und Feature-Ergebnis in der Validierung
- GOE-Tabellen und `V`-/Unterrotations-Varianten
- Sprungkombinationen und -folgen als zusammengesetzte Elemente
- Programmvalidierung (erlaubte Elementanzahl, Wiederholungen, Adult-Regeln)
- Vorschlagsliste im Inspector direkt aus `suggest()`