champions-of-luneraria/docs/port/U3-UI.md

# U3 · G3-HUD portieren

Stand: 1. Oktober 2026.

| Teil | Inhalt | Zustand |
| --- | --- | --- |
| U3A | Entscheidung UI Toolkit, Sichtmodell mit Privatsphäre, menschlicher Sitz, Theme-Grundlagen (Farben, Platten, Symbole, Schriften) | **fertig** |
| U3B | Komponenten, Porträts, Tooltip, alle HUD-Bereiche, Optionen, Partieende | **fertig** |
| U3C | Eingabe und Befehle: Tasten, Kamera-Ziele, Auswahl im Feld, Bereit-Sperre, Planungsvorschau | **fertig** |
| U3D | Prüfung (Teile A–H von `verify_g3`), Spieltest über die echte Oberfläche, Bilder, Leistung | in Arbeit |

Funktionale Referenz ist das G3-HUD aus Godot (`../saumwacht-godot/docs/luneraria/G3-HUD.md`, Commit `1b540f2`). Es wird übertragen, nicht neu erfunden.

## Zu übertragen

- Ancient-Anzeige, Welle und Phase, Gold.
- Drei Lanes mit Bedrohung und Türmen, Teammitglieder.
- Einheitenkarten, Armee.
- Held mit Stufe, Erfahrung, drei Itemslots und Talenten.
- Angriffschampions, nächste Welle, Bossstatus.
- Minimap, Bereit-Zustand, Tooltips, Ereignisse.
- Datenzugang über ein Sichtmodell mit denselben Privatsphäre-Regeln wie `LuneHudModel`.

Die geplanten Helden (`PlannedHeroes`) mit Command-Menü für Ultimates sind im Layout vorzusehen.

Der Bestand in Godot umfasst rund 5.100 Zeilen:
- `lune_hud.gd` (1.058 Zeilen),
- `lune_hud_model.gd` (333),
- 22 Komponenten,
- Theme (`lune_ui_theme.gd`, `forged_style.gd`) und Vektorsymbole (`lune_glyphs.gd`),
- Minimap, Porträt-Cache, Optionen,
- die Verdrahtung in `lune_game.gd` (Befehle, Tasten, Kamera, Auswahl).

Das Hauptmenü (`lune_menu.gd`, mit Netzwerk-Host/Join) ist der Startbildschirm des Spiels und gehört nicht zum HUD.

## Entscheidung: UI Toolkit

Vor Beginn war eine kurze technische Bewertung gefordert, dann **ein** System als Hauptlösung. Gewählt ist **UI Toolkit**; uGUI kommt im HUD nicht vor.

| Kriterium | UI Toolkit | uGUI |
| --- | --- | --- |
| Aufbau wie in Godot (Komponenten im Code, Container) | `VisualElement` und Flexbox entsprechen Godots Box-Containern; Komponenten sind C#-Klassen | GameObjects mit RectTransform und Layout-Gruppen; jede Zeile ein Objekt, Layout-Gruppen teuer beim Neuaufbau |
| Eigenes Zeichnen (Godot `_draw`: Platten, 50 Symbole, Balken, Minimap) | `generateVisualContent` mit `Painter2D` (Pfade, Bögen, konkave Flächen) und eigenen Meshes (Verlauf) | eigene `Graphic`-Klassen; konkave Flächen müsste man selbst triangulieren |
| Skalierung wie Godot (`canvas_items`, `expand`, Basis 1600×960) | `PanelSettings`: Scale With Screen Size, Expand, 1600×960 ergibt bei 16:9 dieselbe logische Fläche 1706×960 | `CanvasScaler` gleichwertig |
| Prüfbarkeit im Batchmodus | Panel rendert in eine RenderTexture beliebiger Größe; Elemente per Name und Pick abfragbar | Canvas über eine Kamera rendern; Abfragen über GameObjects |
| Tooltips, Weltelemente | Laufzeit-Tooltip selbst bauen (Godot hatte ohnehin einen eigenen); Weltbalken sind schon Meshes | eingebaut nur im Editor; Weltraum-Canvas reif |
| Empfehlung in Unity 6 | empfohlenes System für neue Laufzeit-Oberflächen | weiter unterstützt, älterer Ansatz |

**Probe vor der Entscheidung** (`Tests/UI/PlayMode/UiToolkitProbeTests`, Bild `screenshots/u3/00-ui-toolkit-probe.png`):
- Ein Panel rendert im Batchmodus in eine 1920×1080-Textur.
- Die Position stimmt mit Godot überein: 12 logische Pixel ergeben 13,5 Pixel bei 1920×1080.
- Die Platten mit Fasen, Verlauf, Innen- und Kantenlinie entstehen korrekt.
- Alle 50 Symbole zeichnen sich, auch die konkaven (Mondsichel, Turm, Kreuz).
- Die Schriften kommen aus Godots variablen Fonts.

## U3A · Grundlagen

### Sichtmodell und Privatsphäre

Portiert nach `Assets/Luneraria/UI/Model/`, Verhalten wie in Godot:

| Datei | Inhalt |
| --- | --- |
| `LuneHudModel.cs` | einziger Datenzugang des HUD: Phase, eigener Sitz (Gold, Entwurf, Rückgängig, Buchungen), Gebäude, Ancients, Mitspieler, Lanes, Boss, nächste Welle, öffentlicher Digest |
| `LuneLaneThreat.cs` | Lane-Bedrohung RUHIG · UMKÄMPFT · UNTER DRUCK · KRITISCH, nur aus öffentlichem Zustand (Turm-HP, Positionen, Ankündigungen) |
| `LuneStats.cs` | Wertzeilen und Tooltip-Inhalte aus den echten Definitionen (Schaden je Treffer, Tempo, Reichweite, Rüstungsmatrix) |

Die Privatsphäre-Regeln gelten unverändert:
- Gold, Entwurf, Rückgängig und neue Buchungen gibt es nur für den eigenen Sitz.
- Von anderen sieht man Name, Lane, Bereitschaft, Mensch/Bot/offline und den bestätigten Helden.
- Lanes, Gebäude, Boss und Wellen kommen aus öffentlichem Zustand.

Eine Abweichung: Im öffentlichen Digest (Testhilfe) steht beim Boss die öffentliche Claim-Lane. Godot nahm dort auch die private Lane-Wahl des Wählenden auf, sodass der Digest für ihn vom Bild der anderen abweichen konnte.

### Menschlicher Sitz

- `LuneMatchRunner` und `LuneMatchDriver` haben einen menschlichen Sitz bekommen (`HumanSlot`).
- Die Bots planen nur die anderen fünf Sitze. Die Planung wartet auf „Bereit“ des Menschen, wie offline in Godot (`lune_game.gd`), und nach der Abrechnung beginnt sofort die nächste Planung.
- Tempo (1×, 2×, 4×) und Pause wirken nur im Kampf.
- Bot-Partien (`HumanSlot = -1`) laufen unverändert. Die Bildraten-Tests prüfen das mit denselben Fingerabdrücken.

### Theme, Symbole, Schriften

- `Theme/LuneUiTheme.cs`: alle Farben aus `lune_ui_theme.gd` und dem Saumwacht-Menütheme, Zahlenformate (12.000, Dezimalkomma).
- `Theme/LunePlates.cs`: die Platten aus `forged_style.gd` (Fase, Verlauf, Innenlinie, Kante, Schatten, Fokusring).
- `Theme/LuneGlyphs.cs`: alle 50 Symbole aus `lune_glyphs.gd` mit `Painter2D`.
- Schriften: Cantarell und Cinzel als statische SDF-Atlanten (`LuneUiAssetsBuilder`, `Settings/LuneUi.asset`, Lizenz OFL).
  - Unitys Textsystem hat keine Gewichtsachse. FreeType lädt aber die benannten Instanzen der variablen Fonts: Cantarell Regular und Bold, Cinzel Bold.
  - Godots Gewicht 700 und darüber (Versalien, Werte, Titel) passt damit genau.
  - Das Gewicht 560 der Fließtexte hat keine benannte Instanz. Es entsteht aus Regular mit einer 0,25-px-Kontur in der Textfarbe; im Vergleichsbild wirkt das wie Medium.
  - In Cantarell fehlt „★“ (Godot nahm eine Ersatzschrift). Das HUD zeichnet den Stern als Symbol.

### Prüfung U3A

| Test | Ergebnis |
| --- | --- |
| EditMode gesamt | 23/23, davon 12 neue: öffentliches Bild für alle sechs Sitze gleich (Planung und Kampf), fremde Entwürfe (Held, Champion-Buchung) bis zum Kampf unsichtbar, private Boss-Lane-Wahl, Lane-Bedrohung bei Turm-HP und Ankündigungen, Einheitenzahlen je Lane, Bosszustände, nächste Welle gleich der Regelwelle (Runden 1–24), Bereit-Sperre, Zahlenformate, menschlicher Sitz, Bot-Partie unverändert |
| PlayMode-Probe | UI Toolkit rendert im Batchmodus (siehe oben) |

## U3B · Komponenten und Bereiche

Alles liegt unter `Assets/Luneraria/UI/Hud/` und ist aus Godot übertragen:

| Unity | Godot | Inhalt |
| --- | --- | --- |
| `LuneHud.cs` | `lune_hud.gd` | die fünf Bereiche, Synchronisierung (10 Hz Planung, 5 Hz Kampf, Minimap 10 Hz, Ereignisse 4 Hz), UI-Größe (mindestens 1560 × 880 logische Pixel), Ereignis-Erkennung aus öffentlichem Zustand, Tooltips |
| `LuneUi.cs`, `LuneElements.cs` | `lune_ui_theme.gd`, `status_badge.gd`, `hp_bar.gd`, `tower_indicator.gd`, `tab_bar.gd`, `lune_glyph.gd` | Textvarianten, Platten- und Knopfvarianten, Grundelemente |
| `LuneComponents.cs` | `resource_display.gd`, `team_panel.gd`, `unit_card.gd`, `army_chip.gd`, `item_slot.gd`, `event_feed.gd`, `modal_panel.gd` | Gold, Team, Kaufkarten, Armee, Items, Ereignisse, Fenster |
| `LuneLanePanels.cs` | `lane_indicator.gd`, `boss_indicator.gd`, `next_wave_panel.gd` | Lanes, Bossgrotte, nächste Welle |
| `LuneArmyPanels.cs` | `champion_panel.gd`, `unit_detail.gd` | Angriffschampions, ausgewählte Einheit |
| `LuneHeroPanels.cs` | `hero_card.gd`, `hero_detail.gd` | Heldenkarte, Heldenfenster (Anwerben, Werte, Items, Talente) |
| `LuneMinimap.cs` | `lune_minimap.gd`, `lune_minimap_overlay.gd` | Minimap mit eigener Ebene für den Kamerarahmen |
| `LunePortraits.cs` | `portrait_cache.gd`, `portrait_rect.gd` | Porträts aus den echten Modellen, einmal gerendert |
| `LuneTooltip.cs` | `lune_tooltip.gd` | der eine Tooltip |
| `LuneSettingsPanel.cs`, `LunePreferences.cs` | `lune_settings.gd`, `preferences.gd` | Optionen (F1) und gespeicherte Einstellungen |

Die offenen Punkte aus G3 sind umgesetzt:
- **Champion-Etikett:** „1 WELLE“ steht als Band am unteren Porträtrand und verdeckt die Köpfe nicht mehr.
- **Typ-Symbole:** Schadens- und Rüstungstyp stehen als farbige Symbole auf den Einheitenkarten. Die Farben gleichen der Wellenvorschau: Ein Schadenstyp hat die Farbe der Rüstung, gegen die er 130 % trifft (Legion-TD-Prinzip).
- **Armeewert:** Die Summe des Einsatzes steht in der Armeezeile („Wert 185“).
- **Helden auf der Minimap:** kleine Porträts im Goldring statt Punkten, der eigene Held mit weißem Ring (Dota-Prinzip).

Die Heldenkarte hat einen reservierten Befehlsplatz für die Ultimates der geplanten Helden (`PlannedHeroes`, Auslöser `Command`). Er bleibt verborgen, solange keiner dieser Helden spielbar ist.

## U3C · Eingabe und Befehle

`Assets/Luneraria/UI/Game/LuneGame.cs` ist das Gegenstück zur HUD-Seite von `lune_game.gd`.

- **Befehle:** Die Befehle des Menschen laufen über dieselbe Schnittstelle wie die der Bots (`LuneMatch.Submit`). Jeder Befehl meldet sein Ergebnis im HUD zurück.
- **Bereit:** Bereit geht an die Host-Schleife; der Kampf beginnt, sobald alle bereit sind. Nach einem Kampf ist Bereit eine Sekunde lang gesperrt.
- **Tasten wie in G3:**
  - 1–5 kaufen, Leertaste meldet Bereit (im Kampf: Pause), P pausiert.
  - Tab wechselt die Lane, F2–F4 springen zu Top, Mid und Bottom.
  - B, G und H zeigen den eigenen Ancient, die Grotte und den eigenen Helden.
  - R setzt die Kamera auf die eigene Lane zurück.
  - F1 öffnet die Optionen, M schaltet den Ton, F11 das Vollbild, Esc schließt Fenster und Auswahl.
- **Kamera und Maus:**
  - Klicks auf Lanes, Ereignisse, Banner, Bossgrotte und Minimap bewegen die Kamera.
  - Über HUD-Flächen zoomt das Mausrad die Welt nicht.
  - Ein Linksklick im Feld wählt eine eigene Figur (innerhalb von 34 px).
- **Planung:** Die eigene Entwurfsarmee steht in ihrer Formation. Die eigenen Aufstellungsflächen leuchten; Lanes mit eigenen Einheiten sind hervorgehoben.
- **Optionen:** Sie pausieren einen laufenden Kampf offline.
- **Menü:** Ein Hauptmenü gibt es im Unity-Port noch nicht. „Menü“ fragt deshalb nach und beendet das Spiel.

Bot-Partien (Tests, Benchmark) laufen unverändert; der Spielcontroller folgt dem Sitz der laufenden Partie. In der Szene ersetzt der Spielcontroller die U2-Debug-Anzeige.

Die Szenen- und Bibliotheksbauer arbeiten jetzt idempotent:
- Animator-Controller und Post-Processing-Profil werden an Ort und Stelle aktualisiert.
- Vorher erzeugte jeder Szenenbau neue interne IDs in 15 Dateien, obwohl der Inhalt gleich blieb.
- Die Szene selbst entsteht weiter bei jedem Bau neu; Unity vergibt dabei neue Objekt-IDs.
- Zwei Bauten hintereinander ergeben inhaltlich dieselbe Szene. Ersetzt man die IDs durch Platzhalter, sind alle 2840 Objekteinträge gleich; nur ihre Reihenfolge in der Datei ändert sich, weil Unity nach ID sortiert.