- isolate the legacy 3D test under prototype/3d_test - add typed Routine, RoutineSection, PathSegment and RinkDimensions resources - add headless model and canvas tests (103 assertions) - add CanvasTransform and RinkCanvas with pan, zoom and touch pinch - add whiteboard main scene and platform renderer overrides - document architecture decisions in docs/architecture.md
6.7 KiB
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).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).
- 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 |
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 schreibtFileAccessin den IndexedDB-Speicher; Speichern/Laden/Autosave brauchen deshalb eine explizite UX.
7. Tests
Headless, ohne Editor und ohne Display:
./tools/test.sh
Aktueller Stand:
- Model: 36 Assertions für Rink-Geometrie, Segment-Timing, Section-Aggregation und Routine-Validierung.
- Canvas: 67 Assertions für Meter→Pixel-Mapping, Fit/Zoom/Pan und die Rink-Kontur inklusive Eckradien.
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. - Undo/Redo: Command-Pattern im Controller oder Resource-Snapshots – Entscheidung vor dem ersten Zeichen-Tool.
- Section-Übergänge: Ob Sections eine explizite Startzeit erhalten oder ausschließlich aus Segmentdauern abgeleitet werden, klärt die Playback-Implementierung.
- Zeichenwerkzeug: Ob freie Kurven direkt als Bézier-Segmente oder über Template-Geometrie (Lobe, Bogen, Acht) entstehen, entscheidet der erste Tool-Prototyp. Der 3D-Prototyp ist nicht mehr die Hauptszene.