- neues tools/_paths.sh loest den Dokumente-Ordner zur Laufzeit auf: xdg-user-dir DOCUMENTS, sonst ~/Dokumente, sonst ~/Documents - sync_assets.sh und rotoscope.sh nutzen workbench_dir statt $HOME/Documents/workbench_rinkplanner - promote_rotoscope.py und blender/rotoscope.py loesen den Workbench-Pfad genauso auf und bevorzugen weiterhin RINKPLANNER_WORKBENCH - Doku auf den tatsaechlichen Pfad ~/Dokumente/workbench_rinkplanner umgestellt
570 lines
33 KiB
Markdown
570 lines
33 KiB
Markdown
# Rinkplanner – Architektur & Entscheidungen (Phase 1)
|
||
|
||
Stand: 2026-11-01
|
||
Grundlage: `rinkplanner/rinkplanner_definition_agent_guidelines.md`
|
||
Übergeordnete Reihenfolge: `docs/roadmap.md`
|
||
Letzte Session: `docs/findings-2026-10-31-arm-gewichte.md`
|
||
(Session davor: `docs/findings-2026-10-31-kamera-rueckwaerts.md`)
|
||
|
||
## 1. Leitentscheidung
|
||
|
||
Phase 1 ist eine eigenständige 2D-Anwendung. Sie muss ohne 3D-Renderer,
|
||
ohne `Node3D` und ohne Blender-Assets lauffähig sein. Die optionale
|
||
3D-Vorschau wird erst beim Öffnen geladen (D14) und verändert keine Daten.
|
||
|
||
Der bisherige 3D-Test ist ein Machbarkeitsnachweis und liegt isoliert unter
|
||
`rinkplanner/prototype/3d_test/`. Er ist nicht Teil der Phase-1-Runtime und
|
||
wird nicht weiterentwickelt. Phase 2 konsumiert später dasselbe Datenmodell
|
||
über eine eigene Präsentationsschicht.
|
||
|
||
## 2. Repository-Layout
|
||
|
||
```
|
||
/home/torsten/repos/rinkplanner/ # Repo-Root
|
||
├── docs/ # Architektur, ADRs, Regelwerk-Doku
|
||
├── tools/ # Host-Helfer (Tests, Export, CI)
|
||
│ └── blender/ # Rotoscoping-Werkbank
|
||
└── rinkplanner/ # Godot-Projekt (res://)
|
||
├── project.godot
|
||
├── src/
|
||
│ ├── core/model/ # reine Daten-Resources
|
||
│ ├── core/rules/ # ISU-Katalog (JSON + Lookup)
|
||
│ ├── presentation3d/ # 3D-Vorschau, lazy geladen
|
||
│ └── whiteboard/ # Phase 1: view / ctrl / io
|
||
├── scenes/ # dünne Szenen, die Views zusammensetzen
|
||
├── assets/
|
||
│ ├── asset_manifest.json # externe 3D-Assets (Metadaten)
|
||
│ └── external/ # synchronisiert, gitignored
|
||
├── tests/ # headless GDScript-Tests
|
||
└── prototype/3d_test/ # alter 3D-Test, eingefroren
|
||
```
|
||
|
||
`docs/` und `tools/` liegen bewusst außerhalb von `res://`. Sie werden von
|
||
Godot nicht importiert und enthalten keine Laufzeitabhängigkeiten.
|
||
|
||
## 3. Datenmodell (Model)
|
||
|
||
```
|
||
Routine
|
||
├── rink: RinkDimensions
|
||
└── sections: Array[RoutineSection]
|
||
└── segments: Array[PathSegment]
|
||
└── curve: Curve2D
|
||
```
|
||
|
||
Implementiert in `rinkplanner/src/core/model/`:
|
||
|
||
| Klasse | Verantwortung |
|
||
| :--- | :--- |
|
||
| `Routine` | Wurzelaggregat, Validierung, Gesamtdauer/-länge, Section-Lookup, Adult-Kategorie |
|
||
| `RoutineSection` | chronologischer Block, Ghosting-Einheit, Segmentliste |
|
||
| `PathSegment` | Pfad mit Richtung, Kante, Dauer, Element-Marker, Sprungkombination und Label |
|
||
| `RinkDimensions` | Maße, Koordinaten, Punkte-/Kurvenprüfung |
|
||
|
||
Implementiert in `rinkplanner/src/core/rules/`:
|
||
|
||
| Klasse | Verantwortung |
|
||
| :--- | :--- |
|
||
| `ElementDefinition` | Elementfamilie (z. B. `CCoSp`) mit Typ, Name und Base Values je Level |
|
||
| `ElementCatalog` | saisonaler JSON-Katalog, Lookup nach Kürzel/Level, Vorschläge, Prüfung |
|
||
| `ElementFeature` | Level-Feature mit Zählgrenze und Programm-Flag |
|
||
| `ElementLevelRules` | saisonale Feature-Sätze, Pflichtfeatures und Level-Berechnung |
|
||
| `AdultCategoryRules` | Adult-Kategorien mit Limits, Level-Caps und Pflichtelementen |
|
||
| `RoutineValidator` | prüft Elementdaten gegen Katalog und Level-Regeln |
|
||
| `ValidationIssue` | Befund mit Schweregrad, Meldung und Abschnitts-/Segmentbezug |
|
||
| `ValidationReport` | Befunde, Prüfstatistik und Basiswert-Schätzung |
|
||
| `ValidationCheck` | eine Prüfkategorie mit geprüft/bestanden/Befunden |
|
||
|
||
### Entscheidungen
|
||
|
||
**D1 – Segment statt Section als Träger von Richtung und Kante.**
|
||
Ein `RoutineSection` kann viele Kanten- und Richtungswechsel enthalten. Deshalb
|
||
liegen `direction` und `edge` auf `PathSegment`, nicht auf der Section.
|
||
|
||
**D2 – Zeit ist die Autorengröße, Geschwindigkeit wird abgeleitet.**
|
||
`PathSegment.duration_seconds` wird gepflegt. Die Strecke kommt aus der Kurve;
|
||
`get_speed_mps()` berechnet daraus die Geschwindigkeit. Das hält die
|
||
Dot-Simulation deterministisch und vermeidet widersprüchliche Metadaten.
|
||
|
||
**D3 – Marker sind gültige Segmente.**
|
||
Ein Segment mit Länge braucht eine positive Dauer. Ein reiner Element-Marker
|
||
(Länge 0, z. B. Sprungpunkt) darf Dauer 0 haben und wird über `is_marker()`
|
||
erkannt. Seit der Element-Marker-Session trägt das Segment zusätzlich
|
||
`element_type` (Sprung, Pirouette, Sequenz), `element_code` (Kürzel, max.
|
||
24 Zeichen), `element_level` (0 = Base, 1–4) und `element_duration_seconds`
|
||
(Standzeit, nur Punktmarker). Ein Punktmarker ist ein
|
||
Segment mit einer Ein-Punkt-Kurve, `is_element_marker()` ist wahr. Eine
|
||
Sequenz als Bereich bleibt ein normales Segment mit Länge und wird nur
|
||
getaggt; `element_id` bleibt für die spätere Regelwerk-Referenz reserviert.
|
||
|
||
**D4 – Koordinaten in Metern, Ursprung in der Rinkmitte.**
|
||
+X verläuft entlang der langen Achse (−30 m … +30 m), +Y entlang der kurzen
|
||
Achse (−15 m … +15 m). Nur die View rechnet in Pixel um. Gespeicherte Daten
|
||
sind damit auflösungsunabhängig.
|
||
|
||
**D5 – Beschriftungen sind Freitext am Segment.**
|
||
Jedes Segment kann ein `label` tragen (max. 40 Zeichen, getrimmt). Es wird im
|
||
aktiven Abschnitt neben dem Segmentmittelpunkt gezeichnet, in Präsentation und
|
||
Export für alle sichtbaren Abschnitte. Der globale Schalter „Labels“ blendet
|
||
alle Beschriftungen in der Ansicht aus; Exporte enthalten sie immer. Das gilt
|
||
auch für Elementkürzel; die Marker-Form selbst bleibt beim Ausblenden sichtbar.
|
||
|
||
**D6 – IDs sind Pflicht und global eindeutig.**
|
||
`routine_id`, `section_id` und `segment_id` werden validiert. Die ID-Erzeugung
|
||
gehört in den Controller, nicht ins Modell.
|
||
|
||
**D7 – Validierung liefert Fehlertexte.**
|
||
`validate() -> PackedStringArray` ist die primäre API; `is_valid()` ist nur
|
||
eine Abkürzung. So kann die UI Fehler konkret anzeigen.
|
||
|
||
**D8 – Das ISU-Regelwerk ist saisonal externalisiert.**
|
||
Der Elementkatalog liegt als JSON unter `src/core/rules/data/` und trägt
|
||
Saison, Quelle und Gültigkeitsdatum. `ElementCatalog` liest ihn zur Laufzeit
|
||
und löst Kürzel plus Level zu Base Values auf. Segmente speichern nur
|
||
`element_code` und `element_level`, keine abgeleiteten Punkte; dadurch bleibt
|
||
eine neue SoV eine reine Datenaustausch-Aufgabe. Kürzel werden
|
||
case-insensitiv und auch als kanonischer Code mit Level-Suffix (`CCoSp4`,
|
||
`StSqB`) gefunden; ein Suffix im Kürzel hat Vorrang und wird beim Übernehmen
|
||
ins Level-Feld normalisiert. Unbekannte Kürzel oder Level liefern `-1` statt
|
||
einen stillen Standardwert. Das JSON wird über `include_filter="*.json"` in die
|
||
Exporte aufgenommen.
|
||
|
||
**D9 – Level-Features sind Daten, der Level folgt aus ihnen.**
|
||
`ElementLevelRules` liest eine eigene saisonale JSON-Datei mit Feature-Sätzen
|
||
und Schwellen. Ausgewählte Features liegen als Codes am Segment
|
||
(`element_features`); Duplikate sind erlaubt, damit z. B. zwei schwierige
|
||
Variationen zwei Features zählen. Für Katalog-Elemente setzt der Controller
|
||
`element_level` automatisch aus dem Feature-Ergebnis; der Level-Regler ist
|
||
dann read-only. Sprünge sind fest Base, `ChSq` und `ChSp` fest Level 1.
|
||
Unbekannte Freitext-Codes behalten einen manuellen Level als Fallback; die
|
||
Validierung meldet dort weiterhin Abweichungen.
|
||
|
||
**D10 – Validierung liefert Befunde statt eines Ja/Nein.**
|
||
`RoutineValidator` prüft Elementdaten gegen Katalog und Level-Regeln und
|
||
liefert `ValidationIssue`-Objekte mit Schweregrad (Fehler/Warnung), Meldung
|
||
und Abschnitts-/Segmentbezug. `validate_report()` ergänzt eine Prüfstatistik:
|
||
Element- und Abschnittszahl sowie pro Kategorie, wie viele Fälle geprüft und
|
||
bestanden wurden. Zusätzlich summiert der Report die Base Values aller
|
||
Elemente mit gültigem Katalogwert und führt eine Wertungsliste. Bei gewählter
|
||
Adult-Kategorie ergänzt der Dialog eine grobe Punktschätzung aus Basiswert,
|
||
PCS-Annahme (Durchschnitt × 3 × Kategorie-Faktor) und Sturzabzug
|
||
(Stürze × Kategorie-Abzug). GOE bleibt unberücksichtigt.
|
||
Die Prüfung ist bewusst getrennt von `Routine.validate()`:
|
||
Das Modell prüft Struktur und Pfade, der Validator prüft fachliche
|
||
Elementdaten. Die Oberfläche zeigt die Prüfliste und die Befunde in einem
|
||
Dialog; sie blockiert Speichern oder Export nicht. Noch nicht abgedeckt sind
|
||
die Begrenzung auf zwei Features pro Fuß und Feature-Positionsregeln.
|
||
|
||
**D11 – Adult-Kategorien sind eigene saisonale Daten.**
|
||
`AdultCategoryRules` liest das IAFSC-Technical-Announcement als eigene
|
||
JSON-Datei. Die Kategorie liegt als `Routine.adult_category` an der Kür und
|
||
kann in der Statusleiste gewählt werden. Der Validator prüft Elementanzahl,
|
||
erlaubte Sprungrotationen, Level-Caps, Pflichtelemente, Dauer, Wiederholungen
|
||
und Kombinationsgrenzen. Das Announcement hat bei Konflikten Vorrang vor den
|
||
allgemeinen ISU-Regeln; deshalb bleiben Kategorie und Saison getrennte
|
||
Datenquellen.
|
||
|
||
**D12 – Sprungkombinationen sind strukturiert.**
|
||
`PathSegment.element_code` bleibt der erste Sprung; `combination_jumps` hält
|
||
bis zu zwei weitere Sprünge, `jump_kind` unterscheidet Einzelsprung,
|
||
Kombination und Folge. Der Base Value wird aus den Teilen summiert, die
|
||
Wiederholungs- und Kombinationsprüfung arbeitet auf denselben Teilen. Alte
|
||
Freitext-Kürzel wie `3Lz+2T` werden beim Laden oder Übernehmen automatisch in
|
||
die strukturierte Form überführt; nicht parsebare Sonderfälle bleiben als
|
||
Text erhalten. Sprungfolgen verlangen einen Axel als zweiten oder dritten
|
||
Sprung. Der Export verwendet die zusammengesetzte Caption (`3Lz+2T`,
|
||
`3Lz+2A+SEQ`).
|
||
|
||
**D13 – 3D-Assets liegen extern, das Repo hält nur das Manifest.**
|
||
Die Binärdateien (GLB, `.blend`, Texturen) liegen im Workbench-Archiv unter
|
||
`~/Dokumente/workbench_rinkplanner`, nicht im Git-Repo. Das Repo enthält
|
||
`assets/asset_manifest.json` mit ID, Quell-/Zielpfad, SHA-256, Größe,
|
||
Platzierungsdaten und Rig-Metadaten. `tools/sync_assets.sh` prüft beide
|
||
Seiten gegen den Hash, kopiert nach `assets/external/` (gitignored) und stößt
|
||
den Godot-Import an. Damit bleiben Checkout und Build klein, während die
|
||
Arbeitsdateien versioniert und reproduzierbar bleiben. Phase 1 lädt keine
|
||
3D-Ressourcen; die Pipeline ist Vorbereitung für Phase 2. Details:
|
||
`docs/assets.md`.
|
||
Für Rechner ohne Workbench spiegelt `tools/sync_assets.sh --publish` die
|
||
Dateien zusätzlich auf den bestehenden FTP-Server der Kür-Synchronisation;
|
||
`--sync` lädt sie bei Bedarf und prüft sie gegen den Manifest-Hash. Der
|
||
FTP-Spiegel ist eine Verteilungskopie, keine zweite Quelle der Wahrheit.
|
||
|
||
**D14 – Die 3D-Vorschau ist eine isolierte, schreibgeschützte
|
||
Präsentationsschicht.**
|
||
`Presentation3D` liegt unter `src/presentation3d/` und wird erst beim ersten
|
||
Klick auf **3D** geladen. Phase 1 startet weiterhin ohne `Node3D`; der
|
||
2D-Workflow kennt nur den Button und den Moduswechsel. Die Vorschau liest
|
||
`Routine` und den Playback-Zustand, schreibt aber keine Daten. Koordinaten:
|
||
2D `(x, y)` wird zu 3D `(x, 0, -y)`, die Blickrichtung entsprechend. Der
|
||
Skater kommt über die Manifest-ID `character.skater.figure`; fehlt die GLB,
|
||
wird ein Platzhalter gebaut. Der Modus ist bewusst kein Editor: Auswahl,
|
||
Zeichnen und Elementdialoge bleiben in 2D. Die Kamera folgt dem Skater oder
|
||
zeigt eine Übersicht; der Wechsel läuft über den Button „Kamera".
|
||
|
||
**D15 – Rotoscoping bleibt in Blender; Godot konsumiert nur GLB-Clips.**
|
||
Die Werkbank unter `tools/blender/` erzeugt aus dem Produktions-Rig eine
|
||
vorbereitete Blender-Szene mit Kamera, Rink-Guide und Referenzvideo,
|
||
exportiert alle Aktionen als GLB und übernimmt sie per
|
||
`tools/rotoscope.sh promote` in das Asset-Manifest. Clips sind **in-place**:
|
||
Die Fortbewegung kommt aus der Kür-Kurve, nicht aus Root-Motion. Video- und
|
||
Arbeitsdateien bleiben im Workbench-Archiv. Godot kennt nur die GLB und die
|
||
Clipnamen; die Zuordnung Element → Clip ist ein späterer Schritt. Details:
|
||
`docs/rotoscoping.md`.
|
||
|
||
**D16 – Die Kufenspur ist eine reine 3D-Visualisierung.**
|
||
`SkateTrail3D` zeichnet zwei Ribbons an den geschätzten Blade-Positionen.
|
||
Die Farbe kommt aus `PathSegment.direction`: türkis für vorwärts, orange für
|
||
rückwärts. Die Alterung läuft über die Playback-Zeit (1,3 s), nicht über die
|
||
Echtzeit; beim Pausieren bleibt die Spur stehen. Am Kür-Ende, wenn die
|
||
Wiedergabe stoppt, läuft sie in Echtzeit aus. Bei Positionssprüngen über
|
||
1,5 m, Zeit-Rücksprüngen oder `clear_pose` wird sie verworfen. Sie schreibt
|
||
keine Modelldaten und ist nur in der 3D-Vorschau sichtbar.
|
||
|
||
**D17 – Charakter-Exporte behalten acht Bone-Influences.**
|
||
Der Skater hat bis zu neun Gewichte pro Vertex, besonders an den Ärmeln.
|
||
Der glTF-Standardexport trimmt auf vier und lässt die Ärmel in Godot
|
||
kollabieren. Alle Charakter-Exporte setzen `export_all_influences=True`;
|
||
Godot importiert `JOINTS_1`/`WEIGHTS_1` und nutzt 8-Bone-Skinning. Der
|
||
Manifest-Test prüft `ARRAY_FLAG_USE_8_BONE_WEIGHTS`. Vier Einflüsse sind für
|
||
diesen Rig nicht zulässig.
|
||
Zusätzlich wird die Armregion **ringweise** (x-basiert) gewichtet, mit den
|
||
Übergängen am echten Ellbogen (x ≈ 0,37) und Handgelenk (x ≈ 0,65). Die
|
||
PSEUDO-VOXELS-Gewichte bleichten sonst in `spine_03`/`head`; die offenen
|
||
Ärmelflächen verlieren dadurch ihr Volumen. Details:
|
||
`docs/findings-2026-10-31-arm-gewichte.md`.
|
||
|
||
**D18 – Die Folgekamera folgt der Fahrtrichtung.**
|
||
Der Kamera-Rückwärtsversatz kommt aus der Bahn-Tangente, nicht aus dem
|
||
Körper-Yaw. Bei Vorwärtsfahrt ist beides gleich; bei Rückwärtsfahrt bleibt
|
||
die Kamera auf derselben Bahnseite, während sich die Läuferin zur Kamera
|
||
dreht. Dadurch schwenkt die Kamera am Richtungswechsel nicht um 180°, und
|
||
die Läuferin ist auch von vorn zu sehen. Element-Marker behalten die letzte
|
||
Fahrtrichtung.
|
||
|
||
## 4. View- und Controller-Grenzen
|
||
|
||
- **View** (`Node2D`/`Control`) liest das Modell und zeichnet. Sie verändert
|
||
keine Modelldaten und enthält keine Fachlogik.
|
||
- **Meter→Pixel** läuft ausschließlich über `CanvasTransform` (reine
|
||
Mathematik, headless testbar). `RinkCanvas` zeichnet Rink, Mittellinie und
|
||
Mittelkreis und behandelt Pan/Zoom (Maus, Touch, Pinch).
|
||
- **Controller** übersetzt Touch-/Maus-Eingaben in Modelloperationen
|
||
(Segment anlegen, Kante umschalten, Section wechseln, Playback steuern).
|
||
- **Zeichenwerkzeuge:** `WhiteboardController` hält eine Draft-Routine mit
|
||
einer Section. Die Toolbar bietet Auswählen, Linie, Bogen links, Bogen
|
||
rechts und Element; Richtung (vorwärts/rückwärts) und Kante (innen/außen)
|
||
gelten für das nächste Segment. Neue Segmente starten mit dem gewählten
|
||
Timing-Profil (Default Adult Gold, 4,3 m/s); Züge über die Bande werden per
|
||
`clamp_point()` auf die Eisfläche begrenzt.
|
||
- **Bogen-Vorlage:** `ArcGeometry` erzeugt einen Kreisbogen mit 40 % der
|
||
Sehnenlänge als Pfeilhöhe und liefert eine gesampelte `Curve2D`-Polyline.
|
||
Liegt der Bogen außerhalb des Rinks, wird die Pfeilhöhe schrittweise
|
||
reduziert; die gerade Sehne ist der letzte Fallback. Die Bogen-Seite ist
|
||
relativ zur Ziehrichtung (Start → Ende) definiert.
|
||
- **Auswahl und Bearbeitung:** Im Modus „Auswählen“ pickt ein Tipp auf das
|
||
aktive Segment. Start- und Endpunkt haben weiße Griffe, Bögen zusätzlich
|
||
einen orangen Bogen-Griff. Endpunkt-Griffe verschieben die Kurve, der
|
||
Bogen-Griff ändert Tiefe und Seite. Richtung und Kante lassen sich über die
|
||
Toolbar auch nachträglich ändern; die Buttons spiegeln dabei den Zustand
|
||
des ausgewählten Segments. Ohne Auswahl gelten sie für das nächste Segment.
|
||
Ein Griff-Drag beginnt mit der ersten Bewegung; ein bloßer Tipp auf einen
|
||
Griff erzeugt keinen Undo-Eintrag.
|
||
„Segment löschen“ in der Statusleiste ist nur bei Auswahl aktiv; zusätzlich
|
||
löschen Entf und Backspace das ausgewählte Segment. Ghost-Sections sind
|
||
nicht interaktiv. Die Bogenparameter werden als `template`,
|
||
`arc_depth_ratio` und `arc_bulge_left` am `PathSegment` gespeichert, damit
|
||
die Kurve nach dem Editieren neu aufgebaut werden kann.
|
||
- **Element-Marker:** Das Werkzeug „Element“ setzt per Tipp einen Punktmarker
|
||
(Ein-Punkt-Kurve, Dauer 0) des in der Timing-Leiste gewählten Typs
|
||
(Sprung/Pirouette/Sequenz). Der Marker wird direkt ausgewählt; der Button
|
||
„Element“ öffnet den Inspector für Typ, Kürzel und Level. Im
|
||
Auswahlmodus lässt sich der Marker über seinen Griff verschieben. Sequenz-
|
||
Bereiche entstehen, indem ein gezeichnetes Segment über den Inspector
|
||
getaggt wird. Punktmarker haben eine **Standzeit** (`element_duration_seconds`)
|
||
mit Typ-Defaults (Sprung 0,7 s, Pirouette 8 s, Sequenz 0 s), die im
|
||
Inspector übersteuert wird und in die Timeline eingeht. Das Kürzel wird
|
||
über eine Auswahlbox aus dem Katalog gewählt (mit Freitext-Fallback für
|
||
Kombinationen und Varianten). Der Inspector zeigt
|
||
außerdem den **Base Value** des eingegebenen Kürzels und Levels aus dem
|
||
Saisonkatalog; unbekannte Kürzel werden als „nicht im Katalog“ markiert.
|
||
Der Button **Features (n)** öffnet die Checkbox-Liste der Level-Features
|
||
(Pirouetten, Schrittsequenzen) und übernimmt die Auswahl undo-fähig. Der
|
||
Level wird daraus automatisch gesetzt und der Level-Regler ist bei
|
||
Katalog-Elementen read-only; Sprünge sind fest Base, `ChSq` fest Level 1.
|
||
Die Feature-Auswahl bleibt bis zum Übernehmen pending; erst dann werden
|
||
Typ, Kürzel, Features, Level und Standzeit in einem Undo-Schritt
|
||
gespeichert. Ein Hinweis zeigt Feature-Anzahl und abgeleitetes Level.
|
||
Die Timing-Details (Dauer/Tempo/Profil) werden beim Setzen und für
|
||
Punktmarker ausgeblendet, damit die Leiste auch im Landscape kompakt bleibt.
|
||
- **Kategorie:** Ein Dropdown in der Statusleiste wählt „Ohne Kategorie“,
|
||
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,
|
||
Level, ChSq-Level, Feature-Auswahl, Pflichtfeatures, Level aus Features,
|
||
Einmal pro Programm sowie bei Kategorie: Sprunganzahl, erlaubte Sprünge,
|
||
Pirouetten, Sequenzen, Level-Grenzen, Pflichtelemente) mit
|
||
„bestanden/geprüft“-Zählern. Nicht anwendbare
|
||
Kategorien nennen den Grund (z. B. „keine Features gesetzt“). Darunter
|
||
stehen die Befunde mit Abschnitt und Element; ein leeres Ergebnis wird
|
||
positiv bestätigt. Der Basiswert zeigt seine Grenzen hinter dem Link
|
||
„ⓘ Was ist enthalten?“. Speichern und Export bleiben möglich.
|
||
- **Section-Verwaltung:** Ein Panel rechts zeigt die chronologische
|
||
Abschnittsliste. Neue Sections werden angelegt, umbenannt, gelöscht und
|
||
hoch-/runtergeschoben; `sequence_order` wird nach jeder Änderung
|
||
durchnummeriert, die Section-IDs bleiben stabil. Die aktive Section wird
|
||
voll gezeichnet, alle anderen mit 20 % Deckkraft geghostet. Beim Wechsel
|
||
wird eine eventuelle Segmentauswahl verworfen.
|
||
- **Dokument-Lifecycle:** Das Datei-Menü bietet Neu, Öffnen, Speichern und
|
||
Speichern unter. Ein Dirty-State markiert ungespeicherte Änderungen im
|
||
Fenstertitel; Neu/Öffnen fragen vor dem Verwerfen. Autosave und Restore
|
||
laufen unabhängig davon im Hintergrund.
|
||
- **Undo/Redo:** Snapshot-Historie mit maximal 50 Einträgen über Segment-,
|
||
Griff-, Richtungs-/Kanten- und Section-Änderungen. Die Historie stellt die
|
||
aktive Section wieder her, nicht die Zoom-/Pan-Ansicht. Strg+Z,
|
||
Strg+Shift+Z und Strg+Y; die Toolbar-Buttons sind am jeweiligen Ende der
|
||
Historie deaktiviert. Öffnen und Neu starten eine neue Historie.
|
||
- **Playback:** Ein Marker durchläuft alle Sections und Segmente
|
||
kontinuierlich per Bogenlängen-Sampling (`sample_baked()`). Die Blickrichtung
|
||
folgt der Kurventangente; bei Rückwärts-Segmenten wird sie um 180° gedreht,
|
||
sodass die Bewegung entlang des Pfades und die Körperrichtung getrennt
|
||
sichtbar sind. Punktmarker halten die Ankunftsrichtung, Pirouetten drehen
|
||
den Marker während der Standzeit mit 1,5 Umdrehungen pro Sekunde. Während
|
||
des Playbacks wird die aktuelle Section hervorgehoben,
|
||
ohne die Bearbeitungs-Section zu wechseln. Steuerung: Play/Pause, Reset,
|
||
Timeline-Scrubbing und Geschwindigkeit 0,25×–2,0×. Die Dauer kommt aus dem
|
||
Segment-Timing (Default Adult Gold, 4,3 m/s) bzw. bei Punktmarkern aus der
|
||
Element-Standzeit. Nicht verbundene Segmente
|
||
führen zu einem Sprung des Markers an den Start des nächsten Segments.
|
||
- **Geschwindigkeitsannahmen:** Die belastbaren Referenzwerte, Level-Profile
|
||
und Kalibrierung stehen in `docs/speed-assumptions.md`.
|
||
- **Segment-Timing:** Die Timing-Leiste zeigt Dauer und Tempo des ausgewählten
|
||
Segments. Beide Werte sind gekoppelt; `PathSegment.timing_mode` legt fest,
|
||
welche Größe bei Geometrieänderungen erhalten bleibt. Level-Presets
|
||
(Adult Bronze bis Elite), `±`-Schritte, „Standard“ (Adult Gold, 4,3 m/s) und
|
||
ein Kalibrierdialog (Strecke/Zeit → m/s) sind umgesetzt.
|
||
- **Darstellung:** vorwärts durchgezogen, rückwärts gestrichelt, außen rot,
|
||
innen blau. Inaktive Sections werden mit 20 % Deckkraft geghostet.
|
||
- **Ghosting** ist reine View-Logik: pro Section ein eigener Layer,
|
||
inaktive Layer auf 20 % Deckkraft, `mouse_filter = IGNORE`.
|
||
- **Playback** samplet `Curve2D` nach Bogenlänge (`get_baked_length()` /
|
||
`sample_baked()`), nicht nach Control-Point-Index.
|
||
- Phase-1-Code importiert nichts aus `prototype/` und enthält keine
|
||
`Node3D`-Abhängigkeiten.
|
||
|
||
## 5. Rendering und Plattformen
|
||
|
||
Gesetzt in `rinkplanner/project.godot`:
|
||
|
||
| Plattform | Renderer |
|
||
| :--- | :--- |
|
||
| Desktop (Linux/Windows/macOS) | `forward_plus` |
|
||
| Android | `mobile` |
|
||
|
||
Ziele sind ausschließlich native Builds; einen Web-Export gibt es nicht
|
||
mehr. Details und Befehle: `docs/builds.md`.
|
||
|
||
### UI-Skalierung (Touch-first)
|
||
|
||
`window/stretch/mode="disabled"`: Die Oberfläche wird in realen Fensterpixeln
|
||
gelayoutet. Zusätzlich setzt der Controller `Window.content_scale_factor` auf
|
||
die Bildschirm-Skalierung (`DisplayServer.screen_get_scale()`). Auf dem
|
||
Tablet (DPR ≈ 2,6) entspricht eine Layout-Einheit damit einem CSS-Pixel und
|
||
wird trotzdem in Gerätepixeln gerendert:
|
||
|
||
- Ein 56-px-Button ist auf dem Tablet wirklich 56 CSS-Pixel groß, statt durch
|
||
eine feste Designauflösung kleingerechnet zu werden.
|
||
- Das Rink bleibt in Metern; nur die Pixelabbildung ändert sich.
|
||
- Der PNG-Export ist unabhängig davon (eigener `SubViewport`, 2560 × 1600).
|
||
|
||
### Responsive Leiste
|
||
|
||
- Ab 1280 px Breite: volle Beschriftungen („Rinkplanner“, „Werkzeug“,
|
||
„Rückgängig“, „Wiederholen“, „Kalibrieren“).
|
||
- Unter 1280 px: kompakte Beschriftungen („Undo“, „Redo“, „Kalib.“), Titel und
|
||
Werkzeug-Label entfallen, das Sections-Panel wird 260 statt 300 px breit.
|
||
- Die Timing-Leiste ist ein `HFlowContainer` und bricht bei Bedarf um, statt
|
||
seitlich abgeschnitten zu werden.
|
||
- Geprüfte Landschaftsbreiten: 1024 px (kleine Tablets) und 1400 px
|
||
(Galaxy Tab S9+). Hochformat ist noch nicht gestaltet.
|
||
|
||
### Zeichen-Cache
|
||
|
||
`RinkCanvas` cached die in Bildschirmpunkte gesampelten Kurven pro Segment.
|
||
Der Cache wird verworfen, sobald sich Pan/Zoom oder die Kontrollpunkte ändern.
|
||
Gerade Linien (zwei Punkte ohne Griffe) werden direkt als zwei Punkte
|
||
gezeichnet. Im Stresstest (480 Segmente, 12 Sections) sinkt die mittlere
|
||
Redraw-Zeit dadurch von ca. 48 ms auf ca. 7–10 ms.
|
||
|
||
### Touch-Ziele
|
||
|
||
Mindestens 56 × 56 px. Für Desktop-Tests kann temporär
|
||
`input_devices/pointing/emulate_touch_from_mouse=true` aktiviert werden;
|
||
standardmäßig bleibt es aus. Chrome sendet zusätzlich synthetische
|
||
Maus-Events: eines vor `touchstart` (wird beim Touch-Start verworfen) und
|
||
ggf. eines nach `touchend` (300-ms-Guard).
|
||
|
||
## 6. Export und Persistenz
|
||
|
||
- **SVG** wird direkt aus dem Modell serialisiert (Kurven als Pfade,
|
||
Section-Nummern, Legende, Rink), nicht aus einem Screenshot. Damit bleibt
|
||
der Export auflösungsunabhängig. Element-Marker werden als eigene Gruppe
|
||
(`class="element-marker"`) mit Typform und Kürzel gezeichnet, Sequenz-
|
||
Bereiche tragen ihr Kürzel wie ein Label.
|
||
- **PNG** entsteht über eine eigene Export-Szene in einem `SubViewport`
|
||
(2560 × 1600) mit Titel, Section-Nummern und Legende.
|
||
- **Umfang:** Gesamte Kür oder aktiver Abschnitt; Dateien landen unter
|
||
`user://exports/`.
|
||
- **PDF** ist nicht nativ in Godot. Erste Stufe: Browser-Druck aus SVG;
|
||
eine echte PDF-Ausgabe ist ein separates Arbeitspaket.
|
||
- **Persistenz** erfolgt lokal als `.tres`-Ressourcen unter
|
||
`user://routines/`. `Routine.schema_version` (aktuell 2) schützt vor
|
||
inkompatiblen neueren Dateien; Schema-1-Dateien werden beim Laden migriert
|
||
und behalten ihre bisherige Dauer. Die Elementfelder kamen additiv mit
|
||
Defaults hinzu, deshalb bleibt das Schema bei 2. Benannte Kürläufe werden über das Datei-Menü gespeichert
|
||
und geladen; der Öffnen-Dialog nutzt 48-px-Buttons statt einer kleinen
|
||
Dateiliste.
|
||
- **Autosave** schreibt nach 1,5 s Inaktivität nach `user://autosave.tres`
|
||
und wird beim Start automatisch wiederhergestellt. Der Dirty-State wird im
|
||
Fenstertitel als `*` angezeigt. Beim Verlassen wird zusätzlich gespeichert.
|
||
- **Builds:** Linux, Windows, macOS und Android über
|
||
`tools/export_*.sh`; Presets in `rinkplanner/export_presets.cfg`.
|
||
Android nutzt das Template-Export-Verfahren ohne Gradle-Projekt,
|
||
`arm64-v8a`, `minSdk 24`, `targetSdk 36`, Landscape und Immersive Mode.
|
||
Details in `docs/builds.md`.
|
||
- **Lokale Daten:** `user://` liegt pro Plattform getrennt (Linux
|
||
`~/.local/share/godot/app_userdata/Rinkplanner/`, Android im
|
||
app-internen Speicher).
|
||
- **Kontosync:** manueller FTP-/FTPS-Abgleich der `.tres`-Dateien über
|
||
`FtpClient`, `SyncPlan` und `RoutineSync`; Details in `docs/sync.md`.
|
||
Zugangsdaten liegen in `user://sync.cfg`, der letzte gemeinsame Stand in
|
||
`user://sync_state.cfg`. Beim ersten Abgleich einer beidseitig vorhandenen
|
||
Datei übernimmt die Serverfassung den Namen, die lokale bleibt als
|
||
`(Lokal …)`-Kopie; bei einem echten Konflikt bleibt die lokale Fassung
|
||
Hauptdatei und die Serverfassung kommt als `(Server …)`-Kopie dazu.
|
||
|
||
## 7. Tests
|
||
|
||
Headless, ohne Editor und ohne Display:
|
||
|
||
```bash
|
||
./tools/test.sh
|
||
```
|
||
|
||
Aktueller Stand:
|
||
|
||
- **Model:** 100 Assertions für Rink-Geometrie, Clamping, Segment-Timing,
|
||
Timing-Modi, Template-Metadaten, Element-Marker samt Kürzel-/Level-/Dauer-Grenzen,
|
||
Schema-Version, Section-Aggregation und Routine-Validierung.
|
||
- **Regelwerk:** 169 Assertions für Katalog-Metadaten, Saison/Quelle,
|
||
Sprung-/Pirouetten-/Sequenz-Base-Values, Level-Auflösung, Kürzel-Suffixe,
|
||
Case-Insensitivität, Vorschläge, Segment-Integration und fehlerhafte Kataloge.
|
||
- **Level-Features:** 51 Assertions für Feature-Metadaten, Schwellen,
|
||
schwierige Variationen, Windmills, Level-4-Voraussetzungen, Pflichtfeatures
|
||
bei Schrittsequenzen, feste Level (`ChSq`, `ChSp`), Feature-Validierung und
|
||
die Speicherung am Segment.
|
||
- **Validierung:** 66 Assertions für unbekannte Kürzel, Typ-Mismatches,
|
||
nicht verfügbare Level, Sprung-/ChSq-Sonderfälle, Feature-Fehler,
|
||
Pflichtfeatures, Level-Abweichungen, programmweite Einmal-Features, die
|
||
Prüfstatistik je Kategorie und die Basiswert-Summe.
|
||
- **Canvas:** 90 Assertions für Meter→Pixel-Mapping, Fit/Zoom/Pan,
|
||
Rink-Kontur und die reine Bogen-Geometrie.
|
||
- **Adult-Kategorien:** 70 Assertions für Metadaten, Gold/Silver/Bronze,
|
||
Sprungerlaubnis, Level-Caps, Pflichtelemente, Wiederholungen, Kombinationen,
|
||
Dauer und unbekannte Kategorien.
|
||
- **Whiteboard:** 297 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
|
||
Feature-Hinweis, Feature-Menü, strukturierte Sprungkombinationen,
|
||
Verschieben, Löschen), Section-Verwaltung,
|
||
Ghosting-Zustand, Segment-Labels inklusive Dialog und Sichtbarkeits-Schalter,
|
||
Speichern/Laden, Schema-Prüfung, Dirty-State, Prüfdialog mit
|
||
Punktschätzung und inline änderbaren Annahmen,
|
||
Navigationsmodus und den Maus-Drag-Pfad.
|
||
- **History:** 53 Assertions für Undo/Redo von Segmenten, Kanten, Labels, Sections,
|
||
Zeichengesten und Griff-Bearbeitung, Toolbar-Buttons, Erhalt der Ansicht
|
||
sowie das Zurücksetzen der Historie.
|
||
- **Playback:** 45 Assertions für Dauer/Timeline, Vorwärts-/Rückwärts-
|
||
Blickrichtung, Section-Hervorhebung, Play/Pause/Reset inklusive
|
||
Button-Verdrahtung, Scrubbing, Geschwindigkeitswechsel, Standzeiten von
|
||
Elementen und die Rotation des Markers in einer Pirouette.
|
||
- **Timing:** 41 Assertions für Dauer-/Tempo-Kopplung, Level-Presets,
|
||
Kalibrierung, Undo, Persistenz und Schema-1-Migration.
|
||
- **Export:** 31 Assertions für SVG-Struktur, Titel-Escaping, Segment-Labels,
|
||
Element-Marker, strukturierte Sprungkombinationen, Section-Filter,
|
||
Segmentfarben/-strichelung und das Schreiben der Exportdatei.
|
||
- **Touch/Tablet:** 28 Assertions für Ein-Finger-Zeichnen, Zwei-Finger-Pan,
|
||
Pinch-Zoom, Tipp-Auswahl, Griff-Bearbeitung, Element-Marker per Tipp,
|
||
Abbruch bei zweitem Finger,
|
||
Unterdrückung synthetischer Maus-Events aus Chrome sowie das responsive
|
||
Leistenlayout bei 1024 und 1400 px.
|
||
- **Performance:** Stresstest mit 480 Segmenten in 12 Sections; die mittlere
|
||
Redraw-Zeit muss unter 120 ms bleiben (aktuell ca. 7–10 ms).
|
||
- **Sync:** 32 Assertions für Vergleichsregeln, Konfliktnamen, Zeitstempel,
|
||
PASV/EPSV/MDTM-Parsing, Sync-Stand und die Einstellungs-Verdrahtung.
|
||
Der FTP-Client wurde zusätzlich gegen den echten Zielserver geprüft
|
||
(Upload, Download, Übernahme, Konflikt, Aufräumen).
|
||
- **3D-Assets:** 57 Assertions für Manifest-Schema, Pfade, FTP-Pfade,
|
||
Platzierung, Rig-Metadaten, Animationen, Hashes und – falls synchronisiert
|
||
– Größe, SHA-256 sowie die 8-Bone-Gewichte der GLB-Datei.
|
||
- **3D-Vorschau:** 61 Assertions für Koordinatenabbildung, Rink-Geometrie,
|
||
Kamera-Modi, Kamera-Fahrtrichtung, Platzhalter-Fallback, Kufenspur
|
||
(Farbe, zwei Kufen, Reset, Abbau am Kür-Ende) und den 2D/3D-Moduswechsel
|
||
samt geteilter Playback-Position.
|
||
- **Blender-Werkbank:** Rotoscoping wird separat geprüft
|
||
(`tools/rotoscope.sh test-reference` → `setup` → `export` → `promote
|
||
--dry-run`), nicht in `./tools/test.sh`, weil Blender und ffmpeg
|
||
Host-Abhängigkeiten sind.
|
||
|
||
Autosave/Restore wird zusätzlich in einem isolierten `XDG_DATA_HOME`
|
||
end-to-end geprüft.
|
||
|
||
Visuelle Smoke-Tests laufen zusätzlich über `xvfb-run` und einen
|
||
Viewport-Screenshot; sie ersetzen die headless Tests nicht.
|
||
|
||
## 8. Offene Entscheidungen
|
||
|
||
1. **Eckenradius:** 8,5 m ist als Default gesetzt. ISU- und IIHF-Regelwerk
|
||
können abweichen; der Wert gehört später in die Regelkonfiguration.
|
||
2. **Element-Instanzen:** Punktmarker sind seit der Element-Session
|
||
`PathSegment` mit Ein-Punkt-Kurve (D3). `element_id` bleibt für die
|
||
Referenz auf einen künftigen Regelkatalog frei; ob Level/Features aus dem
|
||
Katalog statt am Segment hängen, entscheidet das Regelmodell.
|
||
3. **History-Grenzen:** 50 Snapshots ohne Coalescing; Undo zurück zum
|
||
gespeicherten Stand setzt den Dirty-Marker nicht automatisch zurück. Für
|
||
lange Sessions ist zu prüfen, ob das reicht.
|
||
4. **Section-Übergänge:** Playback läuft derzeit kontinuierlich ohne
|
||
Übergangspause; Section-Startzeiten werden ausschließlich aus den
|
||
Segmentdauern abgeleitet. Ob explizite Übergangszeiten nötig sind, zeigt
|
||
die Praxis.
|
||
5. **Kurven und Templates:** Linie, Kreisbogen und die Bearbeitung von
|
||
Start/Ende, Seite und Tiefe sind umgesetzt. Offen sind Freihand sowie
|
||
weitere Templates wie Acht und Dreier.
|
||
6. **Segment-Verknüpfung:** Beim Verschieben eines Endpunkts werden
|
||
Nachbarsegmente nicht automatisch mitgezogen. Ob Pfade später als
|
||
zusammenhängende Kette editiert werden, ist offen.
|
||
7. **Section-Darstellung:** Die aktuelle Scrollliste funktioniert für wenige
|
||
Abschnitte. Bei langen Kürprogrammen ist zu prüfen, ob eine horizontale
|
||
Timeline mit Zeitproportionen die bessere Bedienung ist.
|
||
8. **Persistenz-Backups:** Autosave nutzt genau einen Slot. Ob zusätzlich
|
||
rotierende Backups oder Versionen pro Speichervorgang nötig sind, zeigt
|
||
sich im Praxisbetrieb.
|
||
9. **Dateinamen:** Die Normalisierung ersetzt Leerzeichen und entfernt
|
||
Pfadzeichen, transliteriert aber keine Umlaute. Für Windows und den
|
||
geplanten FTP-Sync ist zu prüfen, ob eine ASCII-Normalisierung robuster
|
||
ist.
|
||
10. **Snapshot-Clone:** `_clone_routine()` kopiert die Modellfelder manuell.
|
||
Neue Felder am Modell müssen dort ergänzt werden, sonst fehlen sie in
|
||
Undo/Redo-Snapshots.
|
||
11. **Segment-Timing:** Dauer/Tempo, Presets, Kalibrierung und Migration sind
|
||
umgesetzt. Offen sind Beschleunigung/Verzögerung innerhalb eines Segments
|
||
und eine noch genauere Profilpflege aus eigenen Messungen.
|
||
12. **Playback-Komfort:** Loop, Scrubbing während des Abspielens und
|
||
Audio-Synchronisation sind bewusst noch nicht enthalten.
|