Ergänze 3D-Vorschau zur individuellen Haar- und Augenfarbe

frontend/docs/falukant-character-appearance.md

@@ -0,0 +1,104 @@
+# Individuelle Augen- und Haarfarben
+
+## Bestehende Modelle vorbereiten
+
+Die vorhandenen Meshy-GLBs enthalten ein gemeinsames Mesh und Material für Haut,
+Kleidung, Haare und Augen. Eine Änderung der allgemeinen Materialfarbe würde
+deshalb die gesamte Figur färben. Die Bereiche müssen einmal pro Modell
+zugeordnet werden; die Geometrie wird dabei nicht anhand von Farbähnlichkeiten
+automatisch geraten.
+
+Unter `/falukant/dev-all-characters` öffnet sich jetzt standardmäßig die
+Vorschau **Farben und Modellbereiche**. Die bisherige Altersübersicht bleibt
+über **Alle Altersmodelle** erreichbar.
+
+1. Geschlecht/Alter wählen oder eine lokale GLB-Datei öffnen. Für die Bearbeitung
+   möglichst die Quelldatei aus `YourPart3Assets/models-src/3d/falukant/characters`
+   statt eines bereits reduzierten Laufzeitmodells verwenden.
+2. In **Drehen / Zoom** das Modell ausrichten. Das Mausrad zoomt, die rechte
+   Maustaste verschiebt die Ansicht.
+3. **Haare markieren** wählen und sichtbare Haarflächen überstreichen. Zum
+   Erreichen weiterer Seiten wieder in den Drehmodus wechseln.
+4. Für **Iris markieren** nahe heranzoomen und einen kleinen Pinsel verwenden.
+   Augenweiß, Pupillen, Lider und Wimpern aussparen.
+5. Mit **Markierung entfernen** Bereiche auf ihre ursprüngliche Textur
+   zurücksetzen. Die letzten zehn Pinselstriche lassen sich rückgängig machen.
+6. Augen-/Haarfarbe ändern und die Zuordnung prüfen. Die Checkbox zeigt zum
+   Vergleich die Originalfarben. Haut und Kleidung werden nicht eingefärbt.
+7. Das bearbeitete GLB herunterladen und erneut öffnen, um die Zuordnung zu
+   kontrollieren. Exportiert werden die Materialbereiche mit ihren ursprünglichen
+   Texturen, nicht die gewählten Vorschaufarben.
+
+Die Originaldateien im Asset-Repository werden vom Editor nicht überschrieben.
+Nach Kontrolle die heruntergeladene Datei unter dem bisherigen Quellnamen im
+Asset-Repository ablegen, z. B. `female_20y.glb`, und das Asset-Repository committen.
+Die bestehende Pipeline `npm run build-runtime-models -- --assets-dir
+../YourPart3Assets --category characters` erstellt daraus die optimierten GLBs.
+Die Exportdatei erhält bewusst keinen `_opt`-Suffix, da solche Dateien vom
+Quellmodell-Build übersprungen werden.
+
+Noch nicht markierte Modelle behalten ihr bisheriges Aussehen. Diese Änderung
+ersetzt nicht automatisch alle bestehenden GLBs. Es gibt keine neue
+Datenbankmigration oder Speicherung pro Spielcharakter.
+
+## Schnittstelle für die Anzeige
+
+`Character3D` und `FalukantCharacterVisual` akzeptieren ein `appearance`-Objekt:
+
+```vue
+<Character3D
+  gender="female"
+  :age="20"
+  :appearance="{ hairColor: '#6b4028', eyeColor: '#438ca7' }"
+/>
+```
+
+Nur sechsstellige Hexfarben werden angewendet. `null` oder ein fehlender Wert
+zeigt für den jeweiligen Bereich die Originaltextur. Farbänderungen benötigen
+keinen erneuten Download und keine neue Modellinstanz.
+
+Materialien enthalten glTF-`extras` in dieser Form:
+
+```json
+{
+  "falukantAppearance": {
+    "version": 1,
+    "region": "hair",
+    "source": "material-0"
+  }
+}
+```
+
+Bereiche sind `body`, `hair` und `iris`. `source` ordnet die Bereiche dem
+ursprünglichen Material zu. Alternativ werden für extern vorbereitete Modelle
+die exakten Materialnamen `hair`, `iris`, `falukant_hair` und `falukant_iris`
+erkannt. Die Standardmaterialien und Texturkoordinaten bleiben erhalten.
+Der Pinsel teilt Dreiecke in Materialgruppen; die Genauigkeit hängt deshalb
+von der vorhandenen Geometrie ab. Sehr grobe Augenbereiche benötigen eine
+feinere Geometrie oder eine spätere Texturmaskierung.
+
+Die Farbanpassung erhält Helligkeitsdetails und berücksichtigt auch eingebrannte
+Farben in emissiven Texturen. Shader-Uniforms werden pro Material gehalten und
+nicht als Laufzeitobjekte in das GLB geschrieben. Der Export stellt die originale
+Wurzeltransformation wieder her und übernimmt vorhandene Animationen.
+
+## Spätere altersabhängige Attribute
+
+Ergrauen kann später über eine altersabhängige Haarfarbe auf derselben
+Schnittstelle aufsetzen. Für Wachstum oder Veränderungen der Gesichtsform
+braucht es gezielt vorbereitete Morph-Targets oder austauschbare Geometrie.
+Die bisherigen voneinander unabhängigen Altersmodelle werden durch die
+Farbzuordnung nicht automatisch zu einem verformbaren Basismodell.
+
+## Prüfung
+
+```sh
+cd frontend
+npm run test:character-appearance
+npm run build
+```
+
+Zusätzlich wurde ein vorhandenes `female_20y.glb` im Browser geladen, mit Haar-
+und Irisbereichen versehen, exportiert, mit der bestehenden Draco-/Simplify-
+Pipeline optimiert und erneut importiert. Beide Bereiche und ihre glTF-Metadaten
+blieben erhalten. Die vollständige Markierung aller Modellvarianten steht noch aus.