diff --git a/README.md b/README.md index 684a330..07a5ac8 100644 --- a/README.md +++ b/README.md @@ -1,3 +1,11 @@ # rinkplanner -Planner for Figure Skating free skate \ No newline at end of file +Planner for Figure Skating free skate + +## Dokumentation + +- **Anleitung und Annahmen:** [`docs/manual.md`](docs/manual.md) +- **Architektur und Entscheidungen:** [`docs/architecture.md`](docs/architecture.md) +- **ISU-Regelwerk:** [`docs/isu-rules.md`](docs/isu-rules.md) +- **Roadmap:** [`docs/roadmap.md`](docs/roadmap.md) +- **Builds:** [`docs/builds.md`](docs/builds.md) diff --git a/docs/architecture.md b/docs/architecture.md index 0afbabf..e11f6c1 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -219,6 +219,9 @@ Datenquellen. Bronze, Silver, Gold, Masters oder Masters Elite. Die Auswahl liegt als `Routine.adult_category` an der Kür, ist undo-fähig und wird mitgespeichert. Der Prüfdialog nennt Kategorie und Dauer im Kopf. +- **Hilfe:** Der Button **?** in der Statusleiste öffnet den Dialog + „Hilfe & Annahmen“ mit Base Value, Level-Features, Kategorien, Prüfung und + PCS-/Sturzannahmen. Dieselben Inhalte stehen in `docs/manual.md`. - **Prüfung:** Der Button „Prüfen“ in der Statusleiste validiert alle Elementsegmente gegen Katalog und Level-Regeln. Der Dialog nennt Saison, Element- und Abschnittszahl und zeigt eine Prüfliste (Kürzel, Elementtyp, @@ -393,7 +396,7 @@ Aktueller Stand: - **Adult-Kategorien:** 67 Assertions für Metadaten, Gold/Silver/Bronze, Sprungerlaubnis, Level-Caps, Pflichtelemente, Wiederholungen, Kombinationen, Dauer und unbekannte Kategorien. -- **Whiteboard:** 279 Assertions für Controller-Verdrahtung, Segmenterzeugung, +- **Whiteboard:** 281 Assertions für Controller-Verdrahtung, Segmenterzeugung, Linien-/Bogenpfade, Klemmen an der Bande, Auswahl, Griff- und Richtungs-/Kanten-Bearbeitung, Segmentlöschung, Element-Marker (Setzen, Typwechsel, Inspector inkl. Kürzelauswahl, Standzeit, Base-Value- und diff --git a/docs/findings-2026-10-31-adult-2026-27.md b/docs/findings-2026-10-31-adult-2026-27.md index 792fedb..70c154f 100644 --- a/docs/findings-2026-10-31-adult-2026-27.md +++ b/docs/findings-2026-10-31-adult-2026-27.md @@ -20,7 +20,7 @@ und Bronze. | Wiederholungen | max. 2-mal pro gelistetem Sprung, inkl. Kombinations-Teile | | Kombinationen | Anzahl, Folgen und max. Sprünge pro Kombination | | Punktschätzung | Basiswert + PCS-Annahme + Sturzabzug | -| Tests | 1023 Assertions gesamt, `./tools/test.sh` grün | +| Tests | 1025 Assertions gesamt, `./tools/test.sh` grün | ## Datenupdate 2026/27 @@ -130,6 +130,15 @@ Geschätzte Summe: 49,55 (PCS 0–10, Stürze 0–20); die Werte werden mit der Kür gespeichert. - GOE bleibt unberücksichtigt; die Summe ist eine grobe Planungshilfe. +## Hilfe & Anleitung + +- Neuer **?**-Button in der Statusleiste öffnet den Dialog **Hilfe & + Annahmen**. +- Er erklärt Base Value, Level aus Features, Adult-Kategorien, Prüfung, + PCS-Annahme und Sturzabzug sowie die Grenzen der Schätzung. +- Dieselben Inhalte stehen als Anleitung in `docs/manual.md`; das README + verlinkt sie. + ## Tests - **Katalog:** 166 Assertions (43 Familien, 2026/27-Werte, `ChSp`). @@ -138,9 +147,9 @@ Geschätzte Summe: 49,55 - **Adult:** 67 Assertions (Metadaten, Kategorien, Sprungerlaubnis, Gold-Limits, gültige Gold-Kür, Wiederholungen, Kombinationen, Dauer und unbekannte Kategorie). -- **Whiteboard:** 279 Assertions (Kategorie-Auswahl, Prüfdialog, Gold-Befunde, - Punktschätzung und inline änderbare Annahmen). -- **Gesamt:** 1023 Assertions. +- **Whiteboard:** 281 Assertions (Kategorie-Auswahl, Prüfdialog, Gold-Befunde, + Punktschätzung, inline änderbare Annahmen und Hilfe-Dialog). +- **Gesamt:** 1025 Assertions. Visuell geprüft bei 1400 × 876 und 1024 × 768: Kategorie-Dropdown, Kopfzeile `Kategorie: Gold · 2:50 ±10 s`, Basiswert und Gold-Befunde. diff --git a/docs/isu-rules.md b/docs/isu-rules.md index 3219028..8e55317 100644 --- a/docs/isu-rules.md +++ b/docs/isu-rules.md @@ -13,6 +13,8 @@ Quellen: - ISU International Adult Figure Skating Competitions 2026/27 – Technical Announcement (für Oberstdorf 2027) +Anleitung und Annahmen für die Bedienung: `docs/manual.md`. + ## Zweck Der Katalog liefert die Base Values (BV) zu Elementkürzeln und Leveln. Er ist diff --git a/docs/manual.md b/docs/manual.md new file mode 100644 index 0000000..fd548a8 --- /dev/null +++ b/docs/manual.md @@ -0,0 +1,152 @@ +# Rinkplanner – Anleitung und Annahmen + +Diese Anleitung erklärt die wichtigsten Begriffe und die Annahmen, die die +App für Prüfung und Punktschätzung verwendet. Dieselbe Erklärung ist in der +App über den Button **?** in der Statusleiste erreichbar. + +## Schnellstart + +1. Kür anlegen oder öffnen. +2. In der Statusleiste die **Adult-Kategorie** wählen (Gold, Silver, Bronze, + Masters, Masters Elite). +3. Elemente aufs Eis setzen: Linie, Bogen oder Element-Marker. +4. Im Element-Dialog **Kürzel**, **Features** und ggf. **Standzeit** festlegen. +5. **Prüfen** öffnen: Prüfliste, Befunde und Punktschätzung ansehen. + +## Kürzel und Base Value + +- Das **Kürzel** bezeichnet die Elementfamilie, z. B. `3Lz`, `CCoSp` oder + `StSq`. +- Der **Level** ist die Schwierigkeitsstufe. Bei Pirouetten und + Schrittsequenzen folgt er aus den Features. +- Der **Base Value** wird aus Kürzel und Level im Saisonkatalog 2026/27 + nachgeschlagen (ISU Communication 2786). +- **Sprünge** haben keinen Level; ihr Base Value hängt von Rotation und + Sprungtyp ab. +- **`ChSq`** (Choreo-Sequenz) und **`ChSp`** (Choreographic Spin) sind fest + Level 1. +- Unbekannte Freitext-Codes haben keinen Katalogwert und werden in der + Schätzung nicht gewertet. + +Der Katalog wird jährlich ersetzt. Die Daten liegen unter +`rinkplanner/src/core/rules/data/` und tragen Saison, Quelle und +Gültigkeitsdatum. + +## Level aus Features + +Für Pirouetten und Schrittsequenzen gilt: + +| Anzahl Features | Level | +| :--- | :--- | +| 0 | Base | +| 1 | Level 1 | +| 2 | Level 2 | +| 3 | Level 3 | +| 4 oder mehr | Level 4 | + +- **Pirouetten:** 15 Features (2026/27). Maximal zwei schwierige Variationen + zählen pro Pirouette. Für Level 4 ist zusätzlich eines dieser Features + nötig: schwieriger Ausgang, klare Kantenänderung, beide Richtungen, klare + Temposteigerung, schwieriger Flug-Eingang oder **Windmills**. +- **Schrittsequenzen:** 5 Features. Feature 1 (Vielfalt schwieriger Schritte + und Drehungen) ist Pflicht. +- Features beschreiben die **Ausführung**. Die App kann sie nicht aus der + gezeichneten Linie ableiten; sie werden im Element-Dialog ausgewählt. +- Bei Katalog-Elementen ist der Level-Regler read-only. Der Level folgt aus + den Features; Springe sind Base, `ChSq`/`ChSp` fest Level 1. + +## Adult-Kategorien + +Die Kategorie wird in der Statusleiste gewählt und mit der Kür gespeichert. + +| | Gold | Silver | Bronze | +| :--- | :--- | :--- | :--- | +| Dauer | 2:50 ±10 s | 2:00 ±10 s | 1:40 ±10 s | +| Sprünge | max. 5 | max. 4 | max. 4 | +| Erlaubt | Einfach/Double, ohne 2F/2Lz/2A/Triple | nur Einfach inkl. 1A | nur Einfach ohne Axel | +| Pirouetten | max. 3, inkl. `ChSp` | max. 2 | max. 2 | +| Sequenz | 1 Schrittsequenz | 1 `ChSq` | 1 `ChSq` | +| Level-Cap | Spins 3 / Sequenz 2 | 2 / 2 | 1 / 1 | +| PCS-Faktor | 2,67 | 2,00 | 2,00 | +| Sturzabzug | 1,0 | 0,5 außerhalb Elemente | 0,5 außerhalb Elemente | + +Masters und Masters Elite sind ebenfalls wählbar. Grundlage ist das IAFSC +Technical Announcement 2026/27; es hat bei Konflikten Vorrang vor allgemeinen +ISU-Regeln. + +## Prüfung + +Der Button **Prüfen** zeigt: + +- Kürzel im Katalog, Elementtyp und Level +- Feature-Auswahl, Pflichtfeatures und Level aus Features +- Einmal-pro-Programm-Features +- bei Kategorie: Sprunganzahl, erlaubte Sprünge, Pirouetten, Sequenzen, + Level-Grenzen, Pflichtelemente, Dauer, Wiederholungen und Kombinationen +- Basiswert, PCS-Annahme, Sturzabzug und geschätzte Summe + +Nicht anwendbare Prüfungen nennen den Grund, z. B. „nicht anwendbar (keine +Features gesetzt)“. Warnungen blockieren Speichern und Export nicht. + +## Punktschätzung und Annahmen + +Die Schätzung besteht aus drei Teilen: + +```text +Basiswert = Summe der Base Values +PCS-Annahme = Durchschnitt × 3 Komponenten × Kategorie-Faktor +Sturzabzug = Anzahl Stürze × Kategorie-Abzug +Geschätzte Summe = Basiswert + PCS-Annahme - Sturzabzug +``` + +### PCS-Annahme + +PCS steht für **Program Component Score**. Im ISU-System bewerten die Judges +drei Komponenten: + +- **Composition** – Aufbau, Muster, Musikbezug +- **Presentation** – Ausdruck, Energie, Musikalität +- **Skating Skills** – Kanten, Schritte, Kontrolle, Flow + +Jede Komponente wird mit 0,25 bis 10,00 bewertet. Die drei Werte werden +summiert und mit dem Kategorie-Faktor multipliziert. + +Die App kennt keine echten Judge-Werte und arbeitet deshalb mit **einem +Durchschnitt pro Komponente** (Startwert **5,00**). Das ist eine +Planungsannahme, kein Regelwert. Über **ⓘ Annahmen ändern** im Prüfdialog +lassen sich Durchschnitt und Sturzzahl anpassen; beides wird mit der Kür +gespeichert. + +Beispiel Gold: + +```text +5,00 × 3 × 2,67 = 40,05 PCS +Basiswert 9,50 +Geschätzte Summe 49,55 +``` + +### Was nicht enthalten ist + +- **GOE** (Ausführungsqualität der Judges) +- **1,1-Faktor** für die zweite Programmhälfte +- nicht katalogisierte Kombinationen/Varianten +- die offizielle Wettkampfwertung + +Die Schätzung ist eine Planungshilfe, keine vorhergesagte Punktzahl. Für eine +realistische PCS-Annahme helfen Protokolle früherer Wettkämpfe; der +Durchschnitt sollte zum aktuellen Leistungsstand passen, nicht zum Wunschziel. + +## Grenzen + +- Features und PCS sind Eingaben, keine Messungen aus der Zeichnung. +- Kombinationen werden für Prüfungen aus Freitext wie `3Lz+2T` geparst, noch + nicht strukturell modelliert. +- Max. zwei Features pro Fuß und Feature-Positionsregeln sind offen. +- Adult-spezifische Sonderfälle außerhalb des Announcements 2026/27 sind + nicht abgebildet. + +## Quellen + +- ISU Communication No. 2786 – Scale of Values 2026/27 +- ISU Communication No. 2788 – Levels of Difficulty / GOE 2026/27 +- IAFSC Technical Announcement 2026/27 (Adult-Wettbewerbe, Oberstdorf 2027) diff --git a/docs/roadmap.md b/docs/roadmap.md index 25bae75..7a2263e 100644 --- a/docs/roadmap.md +++ b/docs/roadmap.md @@ -136,6 +136,7 @@ Voraussetzung für Phase 1. - [ ] Strukturierte Sprungkombinationen/-folgen statt Freitext-Parsing - [x] Dauerprüfung gegen die Kategorie-Zeit - [x] PCS und Sturzabzüge in der Punktschätzung (mit Annahmen) +- [x] In-App-Hilfe „Hilfe & Annahmen“ und `docs/manual.md` - [ ] Optional: Suchfeld/Autovervollständigung aus `suggest()` - [ ] Optional: GOE-Tabellen sowie `V`-/Unterrotationsvarianten diff --git a/rinkplanner/scenes/whiteboard/whiteboard.tscn b/rinkplanner/scenes/whiteboard/whiteboard.tscn index 986cd72..a6381b1 100644 --- a/rinkplanner/scenes/whiteboard/whiteboard.tscn +++ b/rinkplanner/scenes/whiteboard/whiteboard.tscn @@ -502,6 +502,14 @@ theme_override_font_sizes/font_size = 15 text = "Abschnitt 1 · 0 Segmente" vertical_alignment = 1 +[node name="HelpButton" type="Button" parent="Layout/StatusBar/StatusBarContent"] +unique_name_in_owner = true +custom_minimum_size = Vector2(56, 56) +layout_mode = 2 +theme_override_font_sizes/font_size = 18 +text = "?" +tooltip_text = "Hilfe und Annahmen" + [node name="AdultCategoryOption" type="OptionButton" parent="Layout/StatusBar/StatusBarContent"] unique_name_in_owner = true custom_minimum_size = Vector2(170, 56) @@ -1027,3 +1035,19 @@ theme_override_colors/font_color = Color(0.580392, 0.639216, 0.721569, 1) theme_override_font_sizes/font_size = 13 text = "Grobe Schätzung: PCS = Durchschnitt × 3 Komponenten × Kategorie-Faktor. Abzug = Stürze × Kategorie-Abzug. GOE ist nicht enthalten." autowrap_mode = 3 + +[node name="HelpDialog" type="AcceptDialog" parent="."] +unique_name_in_owner = true +title = "Hilfe & Annahmen" +size = Vector2i(820, 680) +ok_button_text = "Schließen" + +[node name="HelpText" type="RichTextLabel" parent="HelpDialog"] +unique_name_in_owner = true +offset_left = 12.0 +offset_top = 12.0 +offset_right = 808.0 +offset_bottom = 616.0 +bbcode_enabled = true +scroll_active = true +selection_enabled = true diff --git a/rinkplanner/src/whiteboard/ctrl/whiteboard_controller.gd b/rinkplanner/src/whiteboard/ctrl/whiteboard_controller.gd index e85ac55..4fdbfff 100644 --- a/rinkplanner/src/whiteboard/ctrl/whiteboard_controller.gd +++ b/rinkplanner/src/whiteboard/ctrl/whiteboard_controller.gd @@ -129,6 +129,9 @@ const COMPACT_LAYOUT_WIDTH := 1280.0 @onready var pcs_average_spin: SpinBox = %PcsAverageSpin @onready var falls_spin: SpinBox = %FallsSpin @onready var apply_score_assumptions_button: Button = %ApplyScoreAssumptionsButton +@onready var help_button: Button = %HelpButton +@onready var help_dialog: AcceptDialog = %HelpDialog +@onready var help_text: RichTextLabel = %HelpText @onready var element_duration_spin: SpinBox = %ElementDurationSpin @onready var segment_label_dialog: ConfirmationDialog = %SegmentLabelDialog @onready var segment_label_edit: LineEdit = %SegmentLabelEdit @@ -287,6 +290,7 @@ func _ready() -> void: validation_button.pressed.connect(open_validation_dialog) validation_text.meta_clicked.connect(_on_validation_meta_clicked) apply_score_assumptions_button.pressed.connect(_apply_score_assumptions) + help_button.pressed.connect(open_help_dialog) element_type_option.item_selected.connect(_on_element_type_selected) resized.connect(_apply_responsive_layout) @@ -761,6 +765,144 @@ static func _format_duration(seconds: int) -> String: return "%d:%02d" % [seconds / 60, seconds % 60] +func open_help_dialog() -> void: + help_text.text = _help_content() + var target := Vector2i(820, 680) + var viewport_size := Vector2i(get_viewport_rect().size) + if viewport_size.x > 0: + target.x = mini(target.x, viewport_size.x) + if viewport_size.y > 0: + target.y = mini(target.y, viewport_size.y) + help_dialog.popup_centered(target) + + +func _help_content() -> String: + var lines := PackedStringArray() + lines.append("[b][font_size=22]Hilfe & Annahmen[/font_size][/b]") + lines.append( + "Diese Hilfe erklärt die Annahmen und Prüfungen der App. Sie ist " + + "keine offizielle ISU-Auslegung." + ) + lines.append("") + lines.append("[b][font_size=18]1. Kürzel und Base Value[/font_size][/b]") + lines.append( + "- Das Kürzel bezeichnet die Elementfamilie, z. B. 3Lz, CCoSp oder StSq." + ) + lines.append( + "- Der Level ist die Schwierigkeitsstufe. Bei Pirouetten und " + + "Schrittsequenzen folgt er aus den Features." + ) + lines.append( + "- Der Base Value wird aus Kürzel und Level im Saisonkatalog 2026/27 " + + "nachgeschlagen (ISU Communication 2786)." + ) + lines.append( + "- Sprünge haben keinen Level; ihr Base Value hängt von Rotation und " + + "Sprungtyp ab." + ) + lines.append( + "- ChSq (Choreo-Sequenz) und ChSp (Choreographic Spin) sind fest " + + "Level 1." + ) + lines.append( + "- Unbekannte Freitext-Codes haben keinen Katalogwert und werden in " + + "der Schätzung nicht gewertet." + ) + lines.append("") + lines.append("[b][font_size=18]2. Level aus Features[/font_size][/b]") + lines.append( + "- Pirouetten haben 15 Features, Schrittsequenzen 5 " + + "(ISU Communication 2788)." + ) + lines.append( + "- 0 Features = Base, 1 = Level 1, 2 = Level 2, 3 = Level 3, " + + "4 oder mehr = Level 4." + ) + lines.append( + "- Level 4 bei Pirouetten verlangt zusätzlich eines von: schwieriger " + + "Ausgang, Kantenänderung, beide Richtungen, Temposteigerung, " + + "schwieriger Flug-Eingang oder Windmills." + ) + lines.append( + "- Bei Schrittsequenzen ist Feature 1 (Vielfalt) Pflicht." + ) + lines.append( + "- Features beschreiben die Ausführung. Die App kann sie nicht aus " + + "der gezeichneten Linie ableiten; sie werden im Element-Dialog " + + "ausgewählt." + ) + lines.append("") + lines.append("[b][font_size=18]3. Adult-Kategorie[/font_size][/b]") + lines.append( + "- Die Kategorie wird in der Statusleiste gewählt und mit der Kür " + + "gespeichert." + ) + lines.append( + "- Gold: max. 5 Sprünge, keine 2F/2Lz/2A/Triple, 3 Pirouetten inkl. " + + "ChSp, 1 Schrittsequenz, 2:50 ±10 s, Spins bis Level 3, Sequenz bis " + + "Level 2." + ) + lines.append( + "- Silver: max. 4 Einfachsprünge inkl. 1A, 2 Pirouetten, 1 ChSq, " + + "2:00 ±10 s, Level bis 2." + ) + lines.append( + "- Bronze: max. 4 Einfachsprünge ohne Axel, 1 Sprungkombination, " + + "2 Pirouetten, 1 ChSq, 1:40 ±10 s, Level bis 1." + ) + lines.append( + "- PCS-Faktor und Sturzabzug stehen in den Kategorie-Daten " + + "(Gold 2,67 und 1,0; Silver/Bronze 2,00 und 0,5)." + ) + lines.append("") + lines.append("[b][font_size=18]4. Punktschätzung[/font_size][/b]") + lines.append( + "- Basiswert: Summe der Base Values aller Elemente mit gültigem " + + "Katalogwert." + ) + lines.append( + "- PCS-Annahme: Durchschnitt pro Komponente × 3 Komponenten × " + + "Kategorie-Faktor." + ) + lines.append( + "- Der PCS-Durchschnitt ist eine Planungsannahme, kein Judge-Wert. " + + "Startwert 5,00; er kann über „Annahmen ändern“ angepasst werden." + ) + lines.append( + "- Sturzabzug: Anzahl Stürze × Kategorie-Abzug." + ) + lines.append( + "- Nicht enthalten: GOE, 1,1-Faktor, nicht katalogisierte " + + "Kombinationen und die offizielle Wettkampfwertung." + ) + lines.append( + "- Beispiel Gold: 5,00 × 3 × 2,67 = 40,05 PCS; Basiswert 9,50; " + + "geschätzte Summe 49,55." + ) + lines.append("") + lines.append("[b][font_size=18]5. Prüfung[/font_size][/b]") + lines.append( + "- Der Button „Prüfen“ zeigt Kürzel-, Level-, Feature- und " + + "Kategorie-Prüfungen sowie die Punktschätzung." + ) + lines.append( + "- Warnungen blockieren Speichern und Export nicht. Sie sind " + + "Planungshinweise." + ) + lines.append( + "- Wiederholungen: max. 2-mal pro gelistetem Sprung; " + + "Kombinationsbestandteile zählen mit." + ) + lines.append("") + lines.append("[b]Tipp:[/b] Für eine realistische PCS-Annahme helfen " + + "Protokolle früherer Wettkämpfe. Der Durchschnitt sollte zu deinem " + + "aktuellen Leistungsstand passen, nicht zum Wunschziel.") + lines.append("") + lines.append("[b]Quellen:[/b] ISU Communication 2786 (SoV 2026/27), " + + "2788 (Levels/GOE 2026/27), IAFSC Technical Announcement 2026/27.") + return "\n".join(lines) + + func _on_validation_meta_clicked(meta: Variant) -> void: var key := str(meta) if key == "score_info": diff --git a/rinkplanner/tests/manual/capture_elements.gd b/rinkplanner/tests/manual/capture_elements.gd index 7126ee4..bc5f65d 100644 --- a/rinkplanner/tests/manual/capture_elements.gd +++ b/rinkplanner/tests/manual/capture_elements.gd @@ -91,6 +91,8 @@ func _capture() -> void: controller.element_button.pressed.emit() elif args.size() > 3 and args[3] == "validate": controller.open_validation_dialog() + elif args.size() > 3 and args[3] == "help": + controller.help_button.pressed.emit() elif args.size() > 3 and args[3] == "adultgold": controller.set_adult_category("gold") controller.open_validation_dialog() diff --git a/rinkplanner/tests/run_whiteboard_tests.gd b/rinkplanner/tests/run_whiteboard_tests.gd index 44ac770..bb60bfd 100644 --- a/rinkplanner/tests/run_whiteboard_tests.gd +++ b/rinkplanner/tests/run_whiteboard_tests.gd @@ -1397,6 +1397,17 @@ func _run() -> void: ) controller.validation_dialog.hide() + controller.help_button.pressed.emit() + _check(controller.help_dialog.visible, "help button opens the help dialog") + _check( + controller.help_text.text.contains("Hilfe & Annahmen") + and controller.help_text.text.contains("PCS-Annahme") + and controller.help_text.text.contains("Gold") + and controller.help_text.text.contains("Level 4"), + "help dialog explains base value, levels, categories and PCS" + ) + controller.help_dialog.hide() + scene.queue_free() await process_frame _finish()