champions-of-luneraria/docs/port/U5-VISUAL.md

# U5 · Visuelle Neuausrichtung

Stand: 7. Oktober 2026 · **Vertical Slice fertig** (`2c1686b`), Kartenqualität entschieden und umgesetzt (**Weg 2 Stufen** = `7fa038a`), **U5.3** Gebäude, Boss und Ringborke auf PBR, Bildfehler aus U5 behoben (siehe [U5.3](#u53--gebäude-boss-ringborke-und-bildbefund)).

U5 ist die eigentliche Begründung für den Unity-Wechsel. Ziel ist stilisierter Realismus wie Dota 2 und aktuelle MOBAs: PBR-Oberflächen, ausgeformte Details, glaubwürdige Proportionen. Die Silhouetten bleiben klar und aus der Draufsicht auch bei über 100 Einheiten lesbar.

## Vorgaben des Projektinhabers (1. Oktober 2026)

- **Reihenfolge unverändert:** erst U3 (HUD) und U4 (Netzwerk), dann U5. Die Modelle werden nicht vorgezogen.
- **Stil:** stilisierter Realismus wie Dota 2 und aktuelle MOBAs. Dazu gehören PBR-Oberflächen, ausgeformte Details und glaubwürdige Proportionen. Die Silhouetten bleiben klar und aus der Draufsicht auch bei über 100 Einheiten lesbar.
- **Umfang:** Einheiten, Gebäude und Umgebung, also die ganze Welt, nicht nur eine repräsentative Gruppe.
- **Weg:** Die Quelle bleiben Blender-Generatoren im Repository mit reproduzierbarem FBX-Export und den U2A-Prüfungen. Dazu kommen gebackene PBR-Texturen (Albedo, Normal, Rauigkeit/Metall, AO).
- **Grenze:** Figuren mit handmodellierter Anatomie, Gesichtern und Haaren entstehen nicht prozedural. Sie brauchen Sculpts von Künstlern oder lizenzierte Asset-Bibliotheken. Downloads dafür gibt es nur nach Freigabe und Lizenzprüfung.

## Vertical Slice

Eine repräsentative Mid-Lane, auf Zielqualität gebracht:
- beide Teamrichtungen, zwei Türme, mindestens ein Ancient sichtbar,
- Fluss/Wasser, Vegetation, Felsen,
- mehrere normale Einheiten, ein Held, ein Angriffschampion,
- die Bossgrotte in sichtbarer Nähe, Kampf-VFX.

Nur diese Zone trägt die Zielqualität:
- Terrain, Wege, PBR-Materialien, Vegetation,
- Beleuchtung, Schatten, Himmel, Nebel, Wasser,
- Decals, Partikel, VFX, Color Grading.

## Umsetzung

### U5A · Gebackene PBR-Texturen

`tools/blender/bake_pbr.py` (Aufruf `sh tools/blender/bake_pbr.sh`) backt sechs nahtlose Sätze in Blender 5.2 (Cycles, 1 Sample, Emission des Musters; Torus-Mapping für Kantenfluss):

| Satz | Verwendung |
| --- | --- |
| `limestone` | Kluft-Stein, Pflaster, Klippen |
| `soil` | Erdreich, Wege |
| `bark` | Rinde, Baumstämme |
| `leaf` | Laub, Vegetation |
| `rock` | Felsen, geschichteter Stein |
| `water` | Flusswellen |

Jeder Satz liegt in `Assets/Luneraria/Art/Textures/`:
- `<name>-albedo-2k.png` — Grundfarbe
- `<name>-normal-2k.png` — Tangentialraum-Normal aus dem Höhenfeld (Sobel)
- `<name>-orm-2k.png` — R AO, G Rauigkeit, B Metall (Unity-ORM)

### U5B · Surface-Shader und Materialien

`Luneraria/Surface` trägt seit U5 die PBR-Karten:
- `_AlbedoMap`, `_NormalMap`, `_OrmMap` triplanar wie der Steinsatz,
- ORM steuert Rauigkeit, Metall und AO der PBR-Auswertung,
- die Welt-Modi (Terrain, Stein, Pflaster, Erde, Rinde, Laub, Wasser) behalten ihr Godot-Aussehen auf dem PBR-Satz,
- weiße Kontur-Höhenrelief (`_Relief`) bleibt als zusätzliche Schicht.

`LuneMaterialFactory` bindet je Oberfläche den passenden Satz (`PbrForMode`), `LN_Rock` den Felsensatz.

### U5C · Mid-Lane Umgebung und Licht

- **Nebel:** `ExponentialSquared`, Dichte 0,0085, Farbe `6a7f96` — Luftfeuchte des Tals.
- **Schatten:** Bias 0,02, NormalBias 0,35, Nahebene 0,2 — scharfe Kanten an Türmen und Felsen.
- **Post:** ACES, Bloom 0,62 / Threshold 1,15, Kontrast 14, Sättigung 16, Weißabgleich +8/−4, Vignette 0,18.
- **Himmel:** prozedural, Tint `2a3d58`, Atmosphäre 0,8, Reflexionen aus dem Himmel.

### U5D · Kampf-VFX und Nachweis

- **Trefferblitz** (`LuneUnitView.HitFlashGlow`): der Kern-HitFlash (0,18 s) und der Angriffs-Flash färben die Figur über einen `MaterialPropertyBlock` (warm beim Angriff, weißglühend beim Treffer); die geteilten Team-Materialien bleiben unangetastet.
- **Turmblitze** (`LuneMatchView.SyncBolts`): dreipunktiger Funke mit Bogen zur Kamera, Breitenkurve (Mündung → Kern → Spitze), Farbverlauf der Teamfarbe, Überblendung über 0,25 s.

## Nachweis

| Beleg | Ort |
| --- | --- |
| Mid-Lane Übersicht, Türme, Ancient, Grotte, Weitwinkel | `screenshots/u5/mid-lane-*.png` |
| Godot G3 Vorher | `../saumwacht-godot/docs/luneraria/screenshots/g3/vorher-1920x1080/` |
| Godot G3 Zwischenstand | `../saumwacht-godot/docs/luneraria/screenshots/g3/zwischenstand-1920x1080/` |
| U3 Motive (HUD über der Karte) | `screenshots/u3/motive-1920x1080/` |
| U2 Weltbilder (Vor-U5-Materialien) | `screenshots/u2b/` |
| Leistung | `logs/u5/player-benchmark-macos.json` |
| U5.3: alle drei Lanes, Rand, Weitwinkel (Editor) | `screenshots/u5.3/*-lane-*.jpg`, `edge-mountains.jpg`, `lane-and-edge.jpg` |
| U5.3: Kampf mit Einheiten, Held und Boss (14 Schlüsselmomente des Vertical Function Test) | `screenshots/u5.3/01-…14-*.jpg`; dieselben Momente vor U5: `screenshots/u2a-batch/` |
| U5.3: die 14 G3-Motive mit HUD | `screenshots/u5.3/motive/` |

Die Kamera der `u5/mid-lane-*`-Bilder folgt der Lage der G3-Motive (Turm, Ancient, Grotte); die Beleuchtung ist bewusst eigenständig gestimmt, nicht pixelgleich nachgebaut.

## Leistung

**Player** (macOS, Mono, Release; Apple M5, Metal; 1920 × 1080 im Fenster, VSync aus): Seed 9 in Runde 21, Spieltempo 1×, gemessen ab 10 s Kampf mit `LuneBenchmark`.

| Ansicht | Einheiten | fps (Mittel) | Bildzeit Median | p95 | Sim | Views | UI | Hauptthread |
| --- | ---: | ---: | ---: | ---: | ---: | ---: | ---: | --- |
| ganze Karte (Zoom 64) | 116 | 132 | 5,11 ms | 19,38 ms | 0,116 | 0,257 | 0,088 | 3,15 / 4,31 ms |
| Mid-Lane nah (Zoom 22) | 63 | 182 | 4,22 ms | 12,90 ms | 0,056 | 0,365 | 0,077 | 2,70 / 3,57 ms |

Gegenüber U3 (169 / 218 fps) kostet der PBR-Satz mit Normals, ORM und Nebel etwa 20–25 % Bildrate. Die Mid-Lane bleibt über 120 fps; die Karte über 100 fps. Metal liefert weiter keine GPU-Zeitstempel. Der nächste Hebel sind LOD und Material-Atlanten (U2-Folgerung), nicht die Dreiecke.

Rohdaten: `logs/u5/player-benchmark-macos.json`. Befehle siehe [U2-WORLD.md](U2-WORLD.md#leistung).

## Abnahme U5 (Vertical Slice)

| Vorgabe | Stand |
| --- | --- |
| Stil stilisierter Realismus (PBR, Details, Proportionen, klare Silhouetten) | erfüllt im Slice: PBR-Sätze, Normal- und ORM-Maps, Hit- und Angriffs-Flash, Turmfunke |
| Blender-Generatoren + reproduzierbarer Export + U2A-Prüfungen | erfüllt: `bake_pbr.py` (nahtlos, Torus-Mapping), bestehende FBX-Pipeline unverändert |
| Gebackene PBR-Texturen (Albedo, Normal, Rauigkeit/Metall, AO) | erfüllt: 6 Sätze × Albedo/Normal/ORM |
| Umfang Einheiten, Gebäude, Umgebung | Slice bringt die Mid-Lane (Terrain, Wege, PBR, Vegetation, Licht, Nebel, Wasser, VFX) auf Zielqualität; die übrige Karte behält den U2-Stand |
| Grenze: keine prozeduralen Gesichter/Haare/Anatomie | eingehalten — die Figuren behalten ihre Generatoren-Modelle; Sculpts bleiben vorbehalten |
| Vertical Slice: beide Richtungen, zwei Türme, Ancient, Fluss, Vegetation, Felsen, Einheiten, Held, Champion, Grotte, Kampf-VFX | erfüllt (siehe `screenshots/u5/`) |
| Vorher/Nachher gegenüber Godot G3 | erfüllt: `u5/` neben `g3/vorher-*` und `g3/zwischenstand-*`; Kamera bewusst vergleichbar, Licht eigenständig |
| Leistung gemessen | erfüllt (133 / 180 fps mit Stufen) |
| Erst danach über die ganze Karte entscheiden | entschieden: **Weg 2 (Stufen)**, umgesetzt |

## Entscheidung für die ganze Karte: Weg 2 (Stufen)

Am 2. Oktober 2026 fiel die Entscheidung des Projektinhabers: **Zielqualität entlang der Lanes, einfachere Randzonen.** Die Alternativen „Gleichziehen“ (PBR überall) und „Drosseln“ (PBR aus ab einer Schwelle) sind damit abgelehnt; „Drosseln“ bleibt als spätere Einstellung denkbar, ist aber nicht vorgesehen.

### Umsetzung

| Baustein | Ort | Inhalt |
| --- | --- | --- |
| `LuneZones` | `Assets/Luneraria/Editor/World/LuneZones.cs` | Korridor um die Lanes (22 m um eine Mittellinie, ein Gebäude oder die Grotte). `NearLane` entscheidet die Stufe eines Punkts |
| `_Quality` | `Assets/Luneraria/Shaders/LuneSurface.shader` | 1 = Lane-Stufe (Albedo, Normal, ORM triplanar), 0 = Randstufe (Farbe + Steinschicht, keine PBR-Maps, flaches PBR wie U2) |
| Materialstufen | `LuneMaterialFactory` | `Spec.Quality`; Randmaterialien binden keine PBR-Sätze. `TerrainEdge.mat` trägt die umgebenden Berge |
| Szenenaufbau | `LuneWorldBuilder.ApplyTier` | Jeder Weltknoten jenseits des Korridors bekommt `_Quality` 0 über einen `MaterialPropertyBlock`; der innere Boden bleibt Lane-Stufe, die Berge `TerrainEdge` |
| Nachweis | `screenshots/u5/edge-mountains.png`, `lane-and-edge.png` | Randstufe (Berge) und der Übergang Lane → Rand in einem Bild |

Gebäude (Türme, Ancients, Grotte), Einheiten, Wege, Wasser und der innere Boden bleiben unverrückt auf Zielqualität. Die Randstufe spart die neun triplanaren Map-Samples (Albedo, Normal, ORM) und behält Farbe, Vertex-Tönung, Steinschicht und Emission — also das U2-Aussehen der Berge.

### Leistung mit Stufen

| Ansicht | Einheiten | fps (Mittel) | Bildzeit Median | p95 | Sim | Views | UI |
| --- | ---: | ---: | ---: | ---: | ---: | ---: | ---: |
| ganze Karte (Zoom 64) | 116 | 133 | 5,05 ms | 19,33 ms | 0,119 | 0,249 | 0,086 |
| Mid-Lane nah (Zoom 22) | 63 | 180 | 4,21 ms | 13,17 ms | 0,055 | 0.353 | 0,078 |

Die Zahlen liegen auf dem Niveau des Slices (132 / 182 fps): die beiden Messfenster sehen den Korridor, also die Lane-Stufe. Die Ersparnis der Randstufe zeigt sich in Weitwinkeln und am Rand (siehe `lane-and-edge.png`), nicht in diesen Fenstern. Für die übrige Karte ist Weg 2 die Vorgabe: hohe Qualität wo gespielt wird, einfache Materialien in den Bergen und an der Kluft.

Rohdaten: `logs/u5/player-benchmark-stufen.json` (Vergleich Slice: `logs/u5/player-benchmark-macos.json`).

## Bekannte Grenzen

- **Stufen statt flächiger Zielqualität:** Der Korridor um die Lanes (22 m) trägt die vollen PBR-Sätze; Berge, Kluft und ferner Hintergrund behalten Farbe + Steinschicht. Die Grenze ist bewusst hart (MaterialPropertyBlock je Knoten), kein weicher Verlauf.
- **Figuren** behalten die prozeduralen Generatoren-Modelle. Anatomie, Gesichter und Haare brauchen Künstler-Sculpts oder lizenzierte Bibliotheken (Freigabe und Lizenzprüfung vorbehalten).
- **Decals und Partikel** (Staub, Trefferfunken, Fußspuren) sind nicht Teil des Slice; der Hit- und Angriffs-Flash sowie der Turmfunke tragen die Kampflesbarkeit.
- **LOD und Draw Calls** sind nicht gemessen (Development-Player/Profiler); die U2-Folgerung bleibt offen.
- **Water Refraction / SSR** ist nicht gesetzt; der Fluss arbeitet mit Normals, Rauigkeit und Fresnel.
- **Godot G3** hat ein eigenes Lichtkonzept; die Bilder sind lagevergleichbar, nicht beleuchtungsgleich.
- **Einheitenmodelle** sind noch nicht auf Zielqualität; sie folgen erst, wenn die Umgebung steht.

## U5.3 · Gebäude, Boss, Ringborke und Bildbefund

Stand 7. Oktober 2026, Zweig `luneraria/u5.3` (`07fa457`).

### Umfang

- **Fünf neue PBR-Sätze** aus `bake_pbr.py`: `metal`, `cloth`, `hide`, `bone`, `wood`.
  - Gebunden an `LN_Metal_*`, `LN_Cloth_Team`, `LN_Wood` (Türme, Ancients, Grotte) und `LN_Boss_*` (Schlundkrone).
  - Die 70 Einheitenmodelle tragen ihre importierten Materialien und sind nicht betroffen.
- **Ringborke-Rinde** (`RB_Bark`) auf ihren eigenen UVs mit dem 4k-Satz aus der U2-Übergabe. Die Rauigkeitskarte wird zu ORM gepackt (`ringborke-cut-orm-4k.png`), die Normalen liegen im Tangentenraum des Meshes. Das ist der Pilot für Figuren mit eigenen Texturen.
- **Aufnahmen** aller drei Lanes, dazu zum ersten Mal Kampfbilder mit Einheiten. Die U5-Bilder zeigten keine Einheiten, weil sie im Editor ohne laufende Partie entstanden.

### Befund: U5 war halb so hell und ohne Grün

Beim Weiterbauen fiel auf: Seit U5 war die Welt dunkel und graublau. Gemessen mit `tools/port/png_stats.py`; Werte zwischen 0 und 1, Grün ist der Anteil der Pixel mit grünem Farbton:

| Bild | Helligkeit | Sättigung | Grün |
| --- | ---: | ---: | ---: |
| Godot G3, Kampf Mid (`g3/zwischenstand-1920x1080/09`, Feldausschnitt) | 0,50 | 0,51 | 27 % |
| U3, Kampf Mid (`u3/motive-1920x1080/09`, Feldausschnitt) | 0,45 | 0,33 | 27 % |
| U5.2, Mid-Lane Übersicht (`u5/mid-lane-overview.png`) | 0,27 | 0,22 | 0 % |
| U5.2, Mid-Lane Türme | 0,22 | 0,13 | 2 % |
| U5.2, Mid-Lane Weitwinkel | 0,34 | 0,26 | 0 % |
| **U5.3**, Mid-Lane Übersicht | **0,41** | **0,31** | **31 %** |
| **U5.3**, Mid-Lane Türme | **0,44** | **0,36** | **39 %** |
| **U5.3**, Mid-Lane Weitwinkel | **0,40** | **0,24** | **29 %** |

Im Spieltest vom 7. Oktober (Stand U5.2, `u3/spieltest/`) waren zusätzlich die Armeen im Nahkampf weiß und der Boss gelb.

Ursachen und Korrekturen:

| Befund | Korrektur |
| --- | --- |
| **Doppelte Einfärbung.** Der Shader multiplizierte die Godot-Farben mit den farbigen PBR-Albedos. Deren Mittel liegt linear bei 0,03–0,4; der Rasen wurde mit etwa 0,05 multipliziert und war fast schwarz. Was man sah, war vor allem die Nebelfarbe | Der Shader teilt jede Albedo durch ihren gemessenen Mittelwert (`_AlbedoMean`). Die Godot-Farbe bleibt der Durchschnitt, die Karte liefert nur Struktur. Rauigkeit wird ebenso um den Materialwert verteilt (`_OrmMean`), wo das Material eine eigene Rauigkeit hat. Der Fluss hat wieder die Godot-Farben |
| **Datenkarten als Farbe importiert.** Normal- und ORM-Karten liefen durch die sRGB-Umrechnung. Normalen kippten, Verdeckung wurde dunkler, Rauigkeit glänzender | `LuneMaterialFactory.Map`: Normalkarten importieren als Normalkarte, ORM linear, Albedo als sRGB. Die Einstellungen stehen in den `.meta`-Dateien |
| **Regenstreifen.** `bake_pbr.py` verzerrte jedes Muster 10:1 (zwei Torus-Radien); Stein, Erde, Laub und Wasser zeigten senkrechte Striche | Sätze ohne Maserung mit einem Radius (`isotropic()`, flächengleich, gleiche mittlere Strukturgröße): `limestone`, `soil`, `leaf`, `water`, `metal`, `cloth`, `hide`, `bone` neu gebacken. Rinde, Holz und Gesteinsschichten behalten ihre Maserung |
| **Treffer-Flash bleichte.** U5D setzte für alle Materialien einer Figur dieselbe fast weiße Grundfarbe und eine starke Emission. Im Nahkampf greift fast jede Figur an oder wird getroffen; die Armeen waren weiß, der Boss gelb, seine Kristalle verloren die Teamfarbe | Ein Block je Materialplatz: Der Flash tönt die eigene Grundfarbe zu 30 % und legt 0,15 auf die eigene Emission. 16 Stufen; unveränderte Stufen überspringen die Blöcke |
| **Nebel verschleierte die Karte.** Dichte 0,0085 legte in der Kartenansicht (Zoom 64–70, 70–90 m) 35–50 % Nebelfarbe über alles. Das widerspricht der Vorgabe „aus der Draufsicht auch bei über 100 Einheiten lesbar“ | Dichte 0,0045, dort 10–15 %. Farbe und Art unverändert |
| **Ringborke-Rinde im Weltmodus.** Der angefangene Stand nutzte den Rindenmodus mit Weltkoordinaten-Riefen; die wären über die laufende Figur gewandert. Die Normalen hingen an einem festen Hilfsvektor | `RB_Bark` im Grundmodus ohne Vertexfarben, Normalen im Mikktspace des Meshes (Tangenten im Shader) |

Kampfbilder gegenüber dem Stand vor U5 (`u2a-batch/`, dieselben Momente):

| Moment | vor U5 | U5.3 |
| --- | --- | --- |
| 02 Runde 1, Kampf Mid | 0,43 / 0,34 / 36 % | 0,42 / 0,33 / 36 % |
| 06 Held kämpft | 0,44 / 0,34 / 33 % | 0,43 / 0,35 / 33 % |
| 11 Welle 21, Übersicht | 0,39 / 0,33 / 34 % | 0,41 / 0,17 / 22 % |

Werte jeweils Helligkeit / Sättigung / Grün. In der Übersicht kostet der verbliebene Nebel Sättigung; die Nähe ist auf dem Stand vor U5, jetzt mit PBR-Struktur.

### Prüfung

| Test | Ergebnis |
| --- | --- |
| EditMode | 29/29 |
| PlayMode | 13/13 (5 Werkzeuge `Explicit`), Verify A–I 718/0 |
| Fingerabdrücke | Seed 2 `DCE95C96556F3A1A`, Seed 9 ab Runde 21 `7B8E43AEFC0D60C5`, unverändert |
| Kern | unverändert, die Darstellung liest nur; Kerntests .NET 457/457 |

Ein PlayMode-Lauf am 7. Oktober fiel aus der Zeit: Bei einer Rechnerlast um 21 erreichte die Seed-2-Partie des Vertical Function Test in seiner Grenze von 900 s nur 2.429 von 12.690 Schritten, ein Vergleich war so nicht möglich. Seed 9 stimmte im selben Lauf. Der wiederholte Lauf war vollständig grün (313 s).

### Leistung

Am 7. Oktober lief der Mac mit mehr Hintergrundlast als am 2. Oktober (iOS-Simulatoren, Last um 9). Deshalb ist U5.3 abwechselnd mit einem U5.2-Player (`1b31f9b`) unter denselben Bedingungen gemessen, je drei Läufe:

| Ansicht | fps U5.2 / U5.3 | Hauptthread U5.2 / U5.3 | Render-Thread U5.2 / U5.3 | Views U5.2 / U5.3 |
| --- | ---: | ---: | ---: | ---: |
| ganze Karte (Zoom 64), 116 Einheiten | 93,8 / 91,4 | 3,92 / 3,94 ms | 5,39 / 5,41 ms | 0,32 / 0,34 ms |
| Mid-Lane nah (Zoom 22), 63 Einheiten | 125,3 / 124,9 | 3,42 / 3,11 ms | 4,30 / 3,97 ms | 0,42 / 0,36 ms |

Kein messbarer Unterschied; die Abweichungen liegen in der Streuung der Läufe. Die Treffer-Flashes kosten in der Mid-Lane weniger als in U5.2, weil unveränderte Stufen keine Blöcke setzen. Eine erste Runde vor dieser Einsparung ergab ebenfalls Gleichstand (U5.2 115/161, U5.3 117/162 fps). Die absoluten Werte liegen unter denen vom 2. Oktober (133/180 fps), weil der Rechner stärker belastet war; die Last schwankte auch zwischen den Runden.

Rohdaten: `logs/u5.3/player-benchmark-u52-run*.json` und `player-benchmark-u53-run*.json`.

### Bilder

- `screenshots/u5.3/` als JPEG (Qualität 90), um das Repository klein zu halten.
- Editor-Aufnahmen: `mid-lane-*`, `top-lane-*`, `bot-lane-*`, `edge-mountains`, `lane-and-edge`.
- Kampfbilder: `01-runde1-aufmarsch` bis `14-welle-ende`.
- Die 14 G3-Motive mit HUD: `motive/`.
- Die U5-Bilder in `screenshots/u5/` bleiben als Stand vor dem Befund.

### Bekannte Grenzen U5.3

- **Einheitenmodelle** (70) behalten ihre importierten Materialien. U5.3 bringt Gebäude, Boss und Ringborkes Rinde auf PBR. Ringborkes übrige Materialplätze (Moos, Blätter, Schnittholz …) sind unverändert.
- **Sättigung** liegt mit 0,31–0,36 in der Nähe auf U3-Niveau, unter Godot G3 (0,51). ACES-Tonemapping und Nebel nehmen Farbe; eine Farbabstimmung wäre eine Entscheidung zum Look, kein Fehler.
- **Randstufe** unverändert (Farbe + Steinschicht).
- **Decals, Partikel, LOD** weiter offen.