yourpart3/frontend/docs/falukant-character-appearance.md

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 alle Bereiche färben. Die Zuordnung erfolgt deshalb über eine eigene UV-Maske: Rot markiert Haare, Grün die Iris, Schwarz unveränderte Bereiche.

Die erste Version verwendete ganze Dreiecke als Markierung. Gerade an Augen waren diese zu grob. Version 2 bemalt stattdessen einzelne Texturpixel. Die Dreiecke, ihre Indizes und die ursprünglichen UV-Koordinaten bleiben unverändert.

Unter /falukant/dev-all-characters öffnet sich standardmäßig die Vorschau Farben und Modellbereiche. Die 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 ausrichten. Das Mausrad zoomt bis zur Nahansicht; die rechte Maustaste verschiebt die Ansicht. Die Editor-Kamera erlaubt auch das genaue Betrachten der Iris, ohne dass die Nah-Clipping-Ebene sie abschneidet.
3. Haare markieren wählen und über die sichtbaren Haarflächen streichen. Zum Erreichen anderer Seiten wieder in den Drehmodus wechseln.
4. Für Iris markieren einen kleinen Pinsel verwenden. Der sichtbare Kreis zeigt die Pinselgröße. Pupille, Augenweiß, Lider und Wimpern aussparen.
5. Markierung entfernen radiert lokal. Alle Markierungen löschen entfernt die gesamte Zuordnung, etwa zum Ersetzen alter dreieckiger Markierungen. Die letzten zehn Pinselstriche bzw. Löschaktionen sind rückgängig machbar.
6. Farben ausprobieren. Die Checkbox zeigt zum Vergleich die Originalfarben. Außerhalb der Maske bleiben Haut und Kleidung unverändert.
7. Das bearbeitete GLB herunterladen und erneut öffnen. Gespeichert wird die Maske mit den ursprünglichen Texturen, nicht die gewählte Vorschaufarbe.

Originaldateien im Asset-Repository werden nicht automatisch überschrieben. Nach Kontrolle die Datei unter dem bisherigen Quellnamen dort 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 keinen _opt-Suffix, da solche Dateien vom Quellmodell-Build übersprungen werden.

Unmarkierte Modelle behalten ihr bisheriges Aussehen. Die vollständige Markierung aller Modellvarianten ist eine einmalige Aufgabe je Modell. Es gibt keine neue Datenbankmigration oder Speicherung pro Spielcharakter.

Schnittstelle für die Anzeige

Character3D und FalukantCharacterVisual akzeptieren ein appearance-Objekt:

<Character3D
  gender="female"
  :age="20"
  :appearance="{ hairColor: '#6b4028', eyeColor: '#438ca7' }"
/>

Nur sechsstellige Hexfarben werden angewendet. Fehlende Werte oder null zeigen die Originaltextur. Farbänderungen benötigen keinen neuen Modell-Download.

Materialien enthalten glTF-extras in dieser Form:

{
  "falukantAppearance": {
    "version": 2,
    "region": "masked",
    "uvSet": 0,
    "maskPng": "data:image/png;base64,..."
  }
}

Die Maske liegt als PNG direkt im GLB. Neue Masken verwenden passend zur Originaltextur 2048×2048 bis 4096×4096 Pixel. Sie wird nicht in die Farbtextur eingebrannt und benötigt keinen eigenen Server-Endpunkt. Die bestehende Draco-/Textur-Optimierung erhält die Material-Extras und verändert die Maske nicht. Beim Laden wird sie als lineare Datentextur ohne Y-Spiegelung interpretiert, passend zu den glTF-UVs. Für die normale Spielanzeige wird sie im Speicher auf höchstens 2048 Pixel Kantenlänge reduziert; im Editor bleibt die gespeicherte Auflösung erhalten. Haar- und Irisfarbe werden darüber im Shader gemischt; auch eingebrannte Farben emissiver Texturen werden berücksichtigt.

Der Pinsel rastert UV-Dreiecke anhand ihrer baryzentrischen Oberflächenpositionen. Damit bleibt seine Größe in der Modelloberfläche konsistent und er kann über UV-Nähte hinweg malen. Er färbt keine ganzen Dreiecke als Ersatz für kleine Pinselstriche. Die Genauigkeit ist durch die Maskenauflösung begrenzt; mehrfach verwendete UV-Bereiche teilen sich auch die Maske.

Rückgängig speichert nur veränderte 64×64-Pixel-Kacheln pro Pinselstrich statt zehn vollständiger Masken. Im Export landen ausschließlich PNG-Daten und Versionsinformationen, keine Shader- oder Undo-Objekte. Die originale Wurzeltransformation und vorhandene Animationen werden übernommen.

Version-1-Materialzuordnungen und die exakten Materialnamen hair, iris, falukant_hair, falukant_iris werden weiterhin geladen. Bestehende grobe Markierungen werden nicht automatisch als Iris erkannt oder korrigiert. Sie lassen sich lokal radieren oder vollständig löschen und pixelgenau neu anlegen. Beim nächsten Export wird das Ergebnis als Version 2 gespeichert.

Spätere altersabhängige Attribute

Ergrauen kann über eine altersabhängige Haarfarbe aufsetzen. Für Wachstum oder Veränderungen der Gesichtsform braucht es Morph-Targets oder austauschbare Geometrie. Die bisherigen unabhängigen Altersmodelle werden durch die Maskierung nicht automatisch zu einem verformbaren Basismodell.

Prüfung

cd frontend
npm run test:character-appearance
npm run build

Regressionstests prüfen kleine Iris-Pinsel auf großen Dreiecken, unveränderte Geometrie, UV-Nähte, unabhängige Farben/Instanzen, lokales Radieren, Rückgängig und Version-1-Kompatibilität. Im Browser wird zusätzlich das vorhandene female_20y.glb in starker Vergrößerung geprüft, mit Maske exportiert, Draco-optimiert und erneut importiert.