- Oberfläche in CSS-Pixeln layouten (stretch disabled, content_scale_factor = Bildschirm-Skalierung), damit 56-px-Ziele auf Tablets auch 56 CSS-Pixel groß sind - Kompakte Werkzeugleiste unter 1280 px, umbruchfähige Timing-Leiste; 1024 px (iPad-Landscape) und 1400 px (Tab S9+) geprüft - Chrome-Guard gegen synthetische Maus-Events vor/nach Touch-Gesten - Web-Export-Preset und tools/export_web.sh (single-threaded) - Kurven-Cache und Linien-Fastpath: Stresstest mit 480 Segmenten von ca. 48 ms auf ca. 7-10 ms pro Redraw - Neue Suiten für Touch/Layout und Performance, Tablet-Testanleitung in docs/web-test.md
16 KiB
Rinkplanner – Architektur & Entscheidungen (Phase 1)
Stand: 2026-10-30
Grundlage: rinkplanner/rinkplanner_definition_agent_guidelines.md
Übergeordnete Reihenfolge: docs/roadmap.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.
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)
└── rinkplanner/ # Godot-Projekt (res://)
├── project.godot
├── src/
│ ├── core/model/ # reine Daten-Resources
│ └── core/rules/ # ISU-Regeln (folgt)
├── whiteboard/ # Phase 1: view / ctrl / io (folgt)
├── scenes/ # dünne Szenen, die Views zusammensetzen
├── assets/
├── 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 |
RoutineSection |
chronologischer Block, Ghosting-Einheit, Segmentliste |
PathSegment |
durchgehender Pfad mit Richtung, Kante, Dauer, Element-Marker |
RinkDimensions |
Maße, Koordinaten, Punkte-/Kurvenprüfung |
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.
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 – 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.
D6 – Validierung liefert Fehlertexte.
validate() -> PackedStringArray ist die primäre API; is_valid() ist nur
eine Abkürzung. So kann die UI Fehler konkret anzeigen.
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).RinkCanvaszeichnet 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:
WhiteboardControllerhält eine Draft-Routine mit einer Section. Die Toolbar bietet Auswählen, Linie, Bogen links und Bogen rechts; 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 perclamp_point()auf die Eisfläche begrenzt. - Bogen-Vorlage:
ArcGeometryerzeugt einen Kreisbogen mit 40 % der Sehnenlänge als Pfeilhöhe und liefert eine gesampelteCurve2D-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.
„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_ratioundarc_bulge_leftamPathSegmentgespeichert, damit die Kurve nach dem Editieren neu aufgebaut werden kann. - Section-Verwaltung: Ein Panel rechts zeigt die chronologische
Abschnittsliste. Neue Sections werden angelegt, umbenannt, gelöscht und
hoch-/runtergeschoben;
sequence_orderwird 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. 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). 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_modelegt 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
Curve2Dnach Bogenlänge (get_baked_length()/sample_baked()), nicht nach Control-Point-Index. - Phase-1-Code importiert nichts aus
prototype/und enthält keineNode3D-Abhängigkeiten.
5. Rendering und Plattformen
Gesetzt in rinkplanner/project.godot:
| Plattform | Renderer |
|---|---|
| Desktop | forward_plus |
| Mobile | mobile |
| Web (Wasm) | gl_compatibility |
UI-Skalierung (Touch-first)
window/stretch/mode="disabled": Die Oberfläche wird in realen Fenster- bzw.
CSS-Pixeln gelayoutet. Zusätzlich setzt der Controller
Window.content_scale_factor auf die Bildschirm-Skalierung
(DisplayServer.screen_get_scale()). Damit entspricht eine Layout-Einheit auf
Tablets 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
HFlowContainerund bricht bei Bedarf um, statt seitlich abgeschnitten zu werden. - Geprüfte Landschaftsbreiten: 1024 px (iPad-Landscape) 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.
- 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 unteruser://routines/.Routine.schema_version(aktuell 2) schützt vor inkompatiblen neueren Dateien; Schema-1-Dateien werden beim Laden migriert und behalten ihre bisherige Dauer. 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.tresund wird beim Start automatisch wiederhergestellt. Der Dirty-State wird im Fenstertitel als*angezeigt. Beim Verlassen wird zusätzlich gespeichert. - Web:
FileAccessschreibt in den IndexedDB-Speicher. Im echten Chrome-Touch-Test auf einem 1024-px- und einem 1400-px-Layout (DPR 2) überlebt die Kür einen Browser-Reload. - Web-Build:
tools/export_web.shexportiert nachbuild/web/(single-threaded, kein COOP/COEP nötig). Details indocs/web-test.md.
7. Tests
Headless, ohne Editor und ohne Display:
./tools/test.sh
Aktueller Stand:
- Model: 55 Assertions für Rink-Geometrie, Clamping, Segment-Timing, Timing-Modi, Template-Metadaten, Schema-Version, Section-Aggregation und Routine-Validierung.
- Canvas: 90 Assertions für Meter→Pixel-Mapping, Fit/Zoom/Pan, Rink-Kontur und die reine Bogen-Geometrie.
- Whiteboard: 129 Assertions für Controller-Verdrahtung, Segmenterzeugung, Linien-/Bogenpfade, Klemmen an der Bande, Auswahl, Griff- und Richtungs-/Kanten-Bearbeitung, Segmentlöschung, Section-Verwaltung, Ghosting-Zustand, Speichern/Laden, Schema-Prüfung, Dirty-State, Navigationsmodus und den Maus-Drag-Pfad.
- History: 47 Assertions für Undo/Redo von Segmenten, Kanten, Sections, Zeichengesten und Griff-Bearbeitung, Toolbar-Buttons, Erhalt der Ansicht sowie das Zurücksetzen der Historie.
- Playback: 38 Assertions für Dauer/Timeline, Vorwärts-/Rückwärts- Blickrichtung, Section-Hervorhebung, Play/Pause/Reset inklusive Button-Verdrahtung, Scrubbing und Geschwindigkeitswechsel.
- Timing: 41 Assertions für Dauer-/Tempo-Kopplung, Level-Presets, Kalibrierung, Undo, Persistenz und Schema-1-Migration.
- Export: 17 Assertions für SVG-Struktur, Titel-Escaping, Section-Filter, Segmentfarben/-strichelung und das Schreiben der Exportdatei.
- Touch/Tablet: 21 Assertions für Ein-Finger-Zeichnen, Zwei-Finger-Pan, Pinch-Zoom, Tipp-Auswahl, Griff-Bearbeitung, 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).
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
- Eckenradius: 8,5 m ist als Default gesetzt. ISU- und IIHF-Regelwerk können abweichen; der Wert gehört später in die Regelkonfiguration.
- Element-Instanzen: Aktuell verweist
PathSegment.element_idauf ein Element. Ob Sprünge/Pirouetten eigene Instanzen mit Position und Zeit brauchen, wird mit dem Regelmodell entschieden. - 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.
- 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.
- 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.
- Segment-Verknüpfung: Beim Verschieben eines Endpunkts werden Nachbarsegmente nicht automatisch mitgezogen. Ob Pfade später als zusammenhängende Kette editiert werden, ist offen.
- 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.
- Persistenz-Backups: Autosave nutzt genau einen Slot. Ob zusätzlich rotierende Backups oder Versionen pro Speichervorgang nötig sind, zeigt sich im Praxisbetrieb.
- Dateinamen: Die Normalisierung ersetzt Leerzeichen und entfernt Pfadzeichen, transliteriert aber keine Umlaute. Für Web/Windows ist zu prüfen, ob eine ASCII-Normalisierung robuster ist.
- 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. - 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.
- Playback-Komfort: Loop, Scrubbing während des Abspielens und Audio-Synchronisation sind bewusst noch nicht enthalten.