rinkplanner/docs/architecture.md
torsten 2edd756920 fix: play M4A/AAC music on macOS via WAV conversion
- detect audio containers by content instead of file extension
- convert ISO media/M4A/AAC with afconvert to mono PCM WAV
- handle mislabeled .mp3 files and already referenced old routines
- show a clear not-playable state and add audio tests
2026-11-10 20:04:33 +01:00

42 KiB
Raw Blame History

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-11-01-godot-ai-bridge.md (Session davor: docs/findings-2026-10-31-arm-gewichte.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/io/                      # JSON-Dateiformat, Legacy-Import
    │   ├── 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, Elementauflösung
PathSegment Pfad mit Richtung, Kante, Dauer, Elementdaten (Lead), Gruppen-ID und Label
ResolvedElement Lese-Sicht auf ein Element: Lead, Mitgliedssegmente, Dauer, Caption, Gruppenanker
RinkDimensions Maße, Koordinaten, Punkte-/Kurvenprüfung
RoutineFile JSON-Serialisierung, atomare Saves, Legacy-.tres-Import

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, Freeline 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.
  • Freeline: Der Freeline-Modus sammelt die gezogene Bewegung als mehrpunktige Curve2D (ca. 2,5 px Punktabstand, max. 4.000 Punkte pro Segment). Die Vorlage Template.FREEHAND bleibt erhalten, damit Start-/Endgriffe nur den jeweiligen Endpunkt verschieben und die Kurve nicht zu einer Linie zusammenfällt. Im Auswahlmodus zeigt der Canvas bis zu 64 gleichmäßig verteilte Zwischenpunkte als kleine Griffe; ein Drag bewegt den jeweiligen Kurvenpunkt (Detail-Index im Handle-Signal), alle anderen Punkte bleiben unverändert. „Glätten“ in der Timing-Leiste führt zwei Laplacian-Durchgänge auf den Innenpunkten aus (Endpunkte fest, undo-fähig, mehrfach anwendbar). Eine iterative RDP-Reduktion entfernt beim Abschluss (ca. 1 px Toleranz, zoomabhängig) und über „Vereinfachen“ überflüssige Zwischenpunkte; Endpunkte und Form bleiben erhalten. Länge, Dauer, Playback, 3D, SVG und PDF nutzen dieselbe Kurve wie die anderen Pfadsegmente.
  • 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: Die Werkzeuge „Sprung“ und „Pirouette“ setzen per Tipp einen Punktmarker (Ein-Punkt-Kurve, Dauer 0) des jeweiligen Typs; der Typ ist damit schon vor dem Platzieren festgelegt. Die Einfügeposition folgt der gezeichneten Laufspur: Der Marker landet an der Stelle zwischen den Segmenten, deren Pfad dem Tipp am nächsten liegt – auch am Anfang oder in der Mitte eines Abschnitts. Wiederholte Tipps an derselben Stelle behalten ihre Reihenfolge. 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. Das Sequenz-Symbol startet den Sequenz-Zeichenmodus: Die erste gezeichnete Strecke wird Lead eines Bereichs, weitere Strecken treten über dieselbe element_group_id bei. Die Gruppe zählt in Prüfung, Basiswert, Adult-Regeln, Timeline und Export als ein Element. Ein beliebiges Mitglied lässt sich auswählen; der Inspector bearbeitet immer das Lead- Segment. Beim Löschen des Leads übernimmt das nächste Mitglied die Elementdaten. RoutineSection.get_elements() löst Einzelelemente und Gruppen zu ResolvedElement-Sichten auf; alle Wertungs- und Anzeigepfade iterieren darüber statt über die Rohsegmente. Die Mehrfachauswahl (Knopf im Abschnittsbereich oder Shift/Cmd/Ctrl-Klick) erlaubt das nachträgliche Gruppieren zusammenhängender Segmente über „Sequenz gruppieren“; der Controller prüft Lücken, Marker und bestehende Elemente, bevor er den Undo-fähigen Gruppenschritt ausführt. Punktmarker haben eine Standzeit (element_duration_seconds) mit Typ-Defaults (Sprung 0,7 s, Pirouette 4 s, Sequenz 0 s), die im Inspector übersteuert wird und in die Timeline eingeht. Pirouetten tragen zusätzlich eine Umdrehungszahl (element_revolutions, Default aus 4 s × 2,5 U/s = 10) und eine Drehrichtung (element_rotation_direction, Default linksherum, weil ~85–90 % der Läufer gegen den Uhrzeigersinn drehen); der Playback dreht mit Umdrehungen / Standzeit in dieser Richtung. Sprünge zeigen im Canvas einen Sprungvektor entlang der Ankunftsrichtung mit der Distanz im Kürzel-Label (3Lz · 3,0 m); ohne manuelle Änderung wird die Weite aus dem Kürzel abgeleitet (1 m pro Luftumdrehung, Axel +0,5). Die Pfeilspitze ist ein Griff: Ziehen speichert Richtung und Weite in element_jump_vector und überschreibt damit die Heuristik. Beim Abspielen wächst der Marker in der Luft (Sinuskurve über die Standzeit) und dreht sich mit der Sprungdrehung (3Lz = 3 Umdrehungen), ebenfalls in der eingestellten Richtung. Beim Abspielen wandert der Marker entlang des Sprungvektors vom Absprung zum Landepunkt; folgt die gezeichnete Spur nicht dort weiter, springt der Marker wie bei anderen nicht verbundenen Segmenten zum nächsten Startpunkt. 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 der geplanten Umdrehungszahl geteilt durch die Standzeit (Fallback für alte Dateien: 2,5 U/s) in der eingestellten Drehrichtung. Sprünge drehen sich mit ihrer Luftumdrehung (aus dem Kürzel, z. B. 3Lz = 3), wandern dabei vom Absprung entlang des Sprungvektors zum Landepunkt und der Marker wächst zur Sprungmitte hin auf das 1,85-Fache, um die Luftphase zu zeigen. Während des Playbacks wird die aktuelle Section hervorgehoben, ohne die Bearbeitungs-Section zu wechseln. Ein ▶ markiert sie in der Abschnittsliste; ihr Name erscheint kurz oben auf der Eisfläche und blendet sich innerhalb von zwei Sekunden aus. Steuerung: Icon-Knöpfe für Start/Pause und Reset (Rekorder-Symbole, Tooltips nennen die Aktion), Timeline-Scrubbing und Geschwindigkeit 0,25×–2,0×. Ein optionales Musikstück liegt neben der Kür-JSON in user://routines/ und läuft über einen AudioStreamPlayer auf derselben Zeitbasis. AudioFile erkennt MP3/OGG/WAV an den echten Dateibytes; M4A/AAC und falsch als .mp3 benannte ISO-Container werden auf macOS mit afconvert zu mono PCM-WAV (44,1 kHz) konvertiert. Start, Pause, Reset, Scrubbing und Geschwindigkeit wirken auf Bild und Ton. Über der Timeline liegt eine Label-Spur: Labels von Segmenten und Kürzel von Elementen ohne Freitext erscheinen schräg an ihrem Startzeitpunkt (auch Elemente mit 0 s Standzeit); beim Überfahren zeigt ein Tooltip den Zeitpunkt im Track. Ein Klick in die Spur legt ein eigenes, frei beschriftetes Timeline-Label an, das per Klick wieder bearbeitet oder gelöscht werden kann. Ein Wechsel des aktiven Abschnitts setzt Marker, Timeline-Slider und Label-Spur an den Anfang dieses Abschnitts; eine laufende Wiedergabe hält dabei an. 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

  • Die Werkzeuge liegen als Icon-Leiste in der Kopfzeile: Mauszeiger für „Auswählen“, Linie, linker und rechter Bogen sowie drei Element-Icons (springendes Strichmännchen mit Pfeil = Sprung, hockendes mit Kreispfeil = Pirouette, gehendes = Sequenz). Beim Start ist „Auswählen“ aktiv. Das aktive Werkzeug wird erhellt (weißes Icon) und mit einem weißen Rahmen markiert; Tooltips nennen den Namen.
  • Ab 1390 px Breite: volle Beschriftungen („Rinkplanner“, „Vorwärts“, „Rückgängig“, „Wiederholen“, „Kalibrieren“).
  • Unter 1390 px: kompakte Beschriftungen („Undo“, „Redo“, „Vor“, „Rück“, „Fit“, „Kalib.“), der Titel entfällt, die Werkzeug-Icons werden 44 statt 48 px breit, das Sections-Panel 260 statt 300 px.
  • 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 erzeugt RoutinePdfExporter direkt als Vektordokument über einen kleinen eigenen PDF-Writer (Helvetica/WinAnsi, keine externe Bibliothek): eine Übersichtsseite mit allen Laufwegen und der Abschnittstabelle, danach eine Seite pro Abschnitt. Die Badges nummerieren die Elemente in Reihenfolge; die Tabelle hat eine Zeile pro Element mit Start-/Endzeit, Dauer, Element/Label und bei Sequenzbereichen der Teilstrecken-Anzahl. Reine Laufwege ohne Element werden gezeichnet, aber nicht tabelliert. Lange Abschnitte laufen auf Fortsetzungsseiten weiter. Die Kurven werden als PDF-Bézierkurven aus den Curve2D-Handles geschrieben. Nach jedem Export zeigt ein Abschlussdialog den absoluten Pfad und bietet Öffnen, Ordner anzeigen und Pfad kopieren über OS.shell_open / OS.shell_show_in_file_manager; optional startet das Ergebnis direkt im Standardprogramm.
  • Persistenz erfolgt lokal als JSON unter user://routines/ (RoutineFile, Format rinkplanner.routine). Die Datei enthält schema_version (aktuell 6); neuere Schemata werden abgelehnt, ältere Dateien beim Laden migriert (Schema 1: Dauer→Tempo, Schema 2→3: additives Feld music_file, Schema 3→4: additive Timeline-Labels, Schema 4→5: additives Feld element_group_id für Sequenzbereiche, Schema 5→6: Vorlagenwert freehand für Freeline-Segmente). Die Elementfelder kamen additiv mit Defaults hinzu. Legacy-.tres-Dateien bleiben lesbar: Vor ResourceLoader.load prüft RoutineFile eine Whitelist (nur die vier Modellskripte, kein eingebettetes GDScript, keine Szenen). Neue Speicherungen schreiben immer .json; eine geöffnete .tres wird beim nächsten Speichern zur .json-Datei migriert. Speichern läuft atomar über eine Temp-Datei mit .bak-Sicherung. Benannte Kürläufe werden über das Datei-Menü gespeichert und geladen; der Öffnen-Dialog zeigt .json und Legacy-.tres, wobei eine vorhandene .json die gleichnamige .tres verdeckt. music_file nennt nur den Dateinamen; die Audiodatei liegt flach daneben in user://routines/ und wird vom Sync mitübertragen. Nach einer M4A/AAC-Konvertierung verweist music_file auf das erzeugte WAV. timeline_labels speichert freie Timeline-Annotationen als {time_seconds, text}.
  • Autosave schreibt nach 1,5 s Inaktivität nur bei ungespeicherten Änderungen nach user://autosave.json; beim Speichern oder Öffnen einer Datei wird der Autosave entfernt. Der letzte Dateipfad liegt in user://session.cfg. Beim Start wird der Autosave nur übernommen, wenn er neuer als die zugehörige Datei ist; dann bleibt der Dateipfad erhalten und die Kür ist als geändert markiert. Der Dirty-State wird im Fenstertitel als * angezeigt. Beim Verlassen wird bei Änderungen zusätzlich gespeichert.
  • Überschreibschutz: „Speichern unter“ und Export fragen nach, bevor eine vorhandene Datei ersetzt wird.
  • 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. Der Export enthält die Skater-GLB (assets/external/characters/*.glb) und den Runtime-Bridge-Autoload, aber keine Test-, Prototyp- oder Editor-Addon-Skripte. tools/check_export.sh exportiert und startet den Linux-Build headless als Smoke-Test. 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 Cloud-Abgleich der .json- und Legacy-.tres-Dateien über RemoteStore, DropboxStore, GoogleDriveStore, SyncPlan und RoutineSync; Details in docs/sync.md, Einrichtung der OAuth-Apps in docs/cloud-setup.md. Jeder Nutzer verbindet sein eigenes Dropbox-Konto; das Google-Drive-Backend ist vorbereitet, aber derzeit nicht freigeschaltet. Refresh-Tokens liegen in user://sync.cfg, der letzte gemeinsame Stand in user://sync_state.cfg. Beim ersten Abgleich einer beidseitig vorhandenen Datei übernimmt die Cloud-Fassung den Namen, die lokale bleibt als (Lokal …)-Kopie; bei einem echten Konflikt bleibt die lokale Fassung Hauptdatei und die Cloud-Fassung kommt als (Server …)-Kopie dazu. Konfliktnamen behalten die jeweilige Endung.

7. Tests

Headless, ohne Editor und ohne Display:

./tools/test.sh
# inklusive Export-Smoke-Test:
./tools/test.sh --export

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.
  • Dateiformat: 54 Assertions für JSON-Roundtrip (inkl. Kurven-Handles, Elemente, Features, Kombinationen), Schema-/Enum-Fehler, atomare Saves und die Legacy-.tres-Whitelist (eingebettetes GDScript und fremde Skripte werden vor dem Laden abgelehnt).
  • 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: 314 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, Überschreibschutz, Autosave-/Session-Wiederherstellung und den Dialog-sicheren Delete-Shortcut, 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: 99 Assertions für Dauer/Timeline, Vorwärts-/Rückwärts- Blickrichtung, Section-Hervorhebung und -Banner, Play/Pause/Reset inklusive Button-Verdrahtung, Scrubbing, Geschwindigkeitswechsel, Standzeiten von Elementen, Markerrotation in einer Pirouette sowie Timeline-Tooltips.
  • 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: 59 Assertions für Vergleichsregeln, Konfliktnamen (JSON und Legacy-.tres), Zeitstempel, URL/PKCE-Helfer, Cloud-Pfade, App-Konfiguration, Sync-Stand und die Einstellungs-Verdrahtung. Die echten Cloud-APIs werden nicht in den automatischen Tests angesprochen (OAuth erfordert ein Testkonto); der Ablauf ist in docs/cloud-setup.md beschrieben.
  • 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.

tools/check_export.sh baut zusätzlich den Linux-Release, startet ihn headless und prüft auf Autoload-/Startfehler, ausgeschlossene Tests und die Skater-GLB im Build.

Autosave/Restore wird zusätzlich in einem isolierten XDG_DATA_HOME end-to-end geprüft (neuer Autosave hängt am letzten Dateipfad, sauberes Speichern entfernt ihn).

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 Cloud-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 umgesetzt; offen sind Loop-Modus und eine Lautstärkeregelung für die Musik.