# Rinkplanner – Architektur & Entscheidungen (Phase 1) Stand: 2026-10-30 Grundlage: `rinkplanner/rinkplanner_definition_agent_guidelines.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). `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 Navigieren, Linie, Bogen links und Bogen rechts; Richtung (vorwärts/rückwärts) und Kante (innen/außen) gelten für das nächste Segment. Die Dauer wird mit 6 m/s aus der Länge abgeleitet, Züge über die Bande werden per `clamp_point()` auf die Eisfläche begrenzt. - **Bogen-Vorlage:** Der Bogen wird als Kreisbogen mit 40 % der Sehnenlänge als Pfeilhöhe erzeugt und als `Curve2D`-Polyline gespeichert. 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. - **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 | `forward_plus` | | Mobile | `mobile` | | Web (Wasm) | `gl_compatibility` | Die Designauflösung ist 1920 × 1200 mit `canvas_items` / `expand`; die Oberfläche skaliert mit, das Rink-Koordinatensystem bleibt in Metern. Touch-Ziele: mindestens 48 × 48 px. Für Desktop-Tests kann temporär `input_devices/pointing/emulate_touch_from_mouse=true` aktiviert werden; standardmäßig bleibt es aus. ## 6. Export und Persistenz - **SVG** wird direkt aus dem Modell serialisiert (Kurven als Pfade), nicht aus einem Screenshot. Damit bleibt der Export auflösungsunabhängig. - **PNG** entsteht über einen Viewport-Render in hoher Auflösung. - **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. Auf Web schreibt `FileAccess` in den IndexedDB-Speicher; Speichern/Laden/Autosave brauchen deshalb eine explizite UX. ## 7. Tests Headless, ohne Editor und ohne Display: ```bash ./tools/test.sh ``` Aktueller Stand: - **Model:** 42 Assertions für Rink-Geometrie, Clamping, Segment-Timing, Section-Aggregation und Routine-Validierung. - **Canvas:** 67 Assertions für Meter→Pixel-Mapping, Fit/Zoom/Pan und die Rink-Kontur inklusive Eckradien. - **Whiteboard:** 55 Assertions für Controller-Verdrahtung, Segmenterzeugung, Linien-/Bogenpfade, Klemmen an der Bande, Undo, Navigationsmodus und den Maus-Drag-Pfad. 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:** Aktuell verweist `PathSegment.element_id` auf ein Element. Ob Sprünge/Pirouetten eigene Instanzen mit Position und Zeit brauchen, wird mit dem Regelmodell entschieden. 3. **Undo/Redo:** Aktuell entfernt „Rückgängig“ nur das letzte Segment. Vollständiges Undo/Redo (Command-Pattern oder Snapshots) bleibt offen. 4. **Section-Übergänge:** Ob Sections eine explizite Startzeit erhalten oder ausschließlich aus Segmentdauern abgeleitet werden, klärt die Playback-Implementierung. 5. **Kurven und Templates:** Linie und Kreisbogen sind umgesetzt. Offen sind Freihand, das nachträgliche Bearbeiten von Bogenparametern (Start/Ende, Seite, Tiefe) sowie weitere Templates wie Acht und Dreier. 6. **Bogen-Metadaten:** Der Bogen wird aktuell als gesampelte Kurve gespeichert. Für spätere Parameter-Editierung sollte `PathSegment` die Template-Art und ihre Parameter zusätzlich als Metadaten tragen.