Add 3D character model integration and update dependencies

- Introduced a new CharacterModel3D component for rendering 3D character models in OverviewView. - Updated package.json and package-lock.json to include 'three' library for 3D graphics support. - Enhanced Vite configuration to allow access to external files and ensure proper handling of GLB/GLTF assets. - Improved layout and styling in OverviewView for better visualization of character and avatar.
2026-01-09 13:29:32 +01:00
parent 3722bcf8c8
commit 5ddb099f5a
24 changed files with 1567 additions and 3 deletions
--- a/docs/BLENDER_RIGGING_GUIDE.md
+++ b/docs/BLENDER_RIGGING_GUIDE.md
@@ -0,0 +1,334 @@
+# Blender Rigging-Anleitung für Falukant-Charaktere
+
+Diese Anleitung erklärt, wie du Bones/Gelenke zu deinen 3D-Modellen in Blender hinzufügst, damit sie animiert werden können.
+
+## Voraussetzungen
+
+- Blender (kostenlos, https://www.blender.org/)
+- GLB-Modell von meshy.ai oder anderen Quellen
+
+## Schritt-für-Schritt Anleitung
+
+### 1. Modell in Blender importieren
+
+1. Öffne Blender
+2. Gehe zu `File` → `Import` → `glTF 2.0 (.glb/.gltf)`
+3. Wähle dein Modell aus
+4. Das Modell sollte jetzt in der Szene erscheinen
+
+### 2. Modell vorbereiten
+
+1. Stelle sicher, dass das Modell im **Object Mode** ist (Tab drücken, falls im Edit Mode)
+2. Wähle das Modell aus (Linksklick)
+3. Drücke `Alt + G` um die Position auf (0, 0, 0) zu setzen
+4. Drücke `Alt + R` um die Rotation zurückzusetzen
+5. Drücke `Alt + S` um die Skalierung auf 1 zu setzen
+
+### 3. Rigging (Bones hinzufügen)
+
+#### Option A: Automatisches Rigging mit Rigify (Empfohlen)
+
+1. **Rigify aktivieren:**
+   - Gehe zu `Edit` → `Preferences` (oder `Blender` → `Preferences` auf Mac)
+   - Klicke auf den Tab **"Add-ons"** (links im Fenster)
+   - Im Suchfeld oben rechts tippe: **"rigify"** (ohne Anführungszeichen)
+   - Du solltest "Rigify: Auto-rigging system" sehen
+   - Aktiviere das **Häkchen** neben "Rigify"
+   - Das Add-on ist jetzt aktiviert
+   - Schließe das Preferences-Fenster
+   
+   **Alternative Wege zu Preferences:**
+   - Windows/Linux: `Edit` → `Preferences`
+   - Mac: `Blender` → `Preferences`
+   - Oder: `Ctrl + ,` (Strg + Komma)
+
+2. **Rigify-Rig hinzufügen:**
+   - Stelle sicher, dass du im **Object Mode** bist (Tab drücken, falls im Edit Mode)
+   - Wähle das Modell aus (oder nichts, das Rig wird separat erstellt)
+   - Drücke `Shift + A` (Add Menu)
+   - Wähle **`Armature`** aus
+   - In der Liste siehst du jetzt **`Human (Meta-Rig)`** - klicke darauf
+   - Ein Basis-Rig wird in der Szene erstellt
+   
+   **Falls "Human (Meta-Rig)" nicht erscheint:**
+   - Stelle sicher, dass Rigify aktiviert ist (siehe Schritt 1)
+   - Starte Blender neu, falls nötig
+   - Prüfe, ob du die neueste Blender-Version hast (Rigify ist ab Version 2.8+ verfügbar)
+
+3. **Rig positionieren und anpassen:**
+   
+   **Schritt 1: Rig zum Modell bewegen**
+   - Stelle sicher, dass du im **Object Mode** bist (Tab drücken)
+   - Wähle das **Armature** aus (nicht das Modell)
+   - Drücke `G` (Grab/Move) und bewege das Rig zum Modell
+   - Oder: Drücke `Alt + G` um die Position zurückzusetzen, dann `G` + `X`, `Y` oder `Z` für eine Achse
+   
+   **Schritt 2: Rig skalieren (falls zu groß/klein)**
+   - Wähle das Armature aus
+   - Drücke `S` (Scale) und skaliere das Rig
+   - Oder: `S` + `X`, `Y` oder `Z` für eine Achse
+   - Tipp: Drücke `Shift + X` (oder Y/Z) um diese Achse auszuschließen
+   
+   **Schritt 3: Einzelne Bones anpassen**
+   - Wähle das Armature aus
+   - Wechsle in den **Edit Mode** (Tab)
+   - Wähle einen Bone aus (Linksklick)
+   - Drücke `G` um ihn zu bewegen
+   - Drücke `E` um einen neuen Bone zu extrudieren
+   - Drücke `R` um einen Bone zu rotieren
+   - Drücke `S` um einen Bone zu skalieren
+   
+   **Wichtige Bones zum Anpassen:**
+   - **Root/Spine** - Sollte in der Mitte des Körpers sein (Hüfthöhe)
+   - **Spine1/Spine2** - Entlang der Wirbelsäule
+   - **Neck/Head** - Am Hals und Kopf
+   - **Shoulders** - An den Schultern
+   - **Arms** - Entlang der Arme
+   - **Legs** - Entlang der Beine
+   
+   **Tipp:** Nutze die Zahlenansicht (Numpad) um die Positionen genau zu sehen
+
+4. **Rig generieren:**
+   - Wechsle zurück in den **Object Mode** (Tab drücken)
+   - Wähle das **Meta-Rig (Armature)** aus (nicht das Modell!) - sollte im Outliner blau markiert sein
+   
+   **Methode 1: Rigify-Button in der Toolbar (Einfachste Methode)**
+   - Oben in der Toolbar siehst du den Button **"Rigify"** (neben "Object")
+   - Klicke auf **"Rigify"** → **"Generate Rig"**
+   - Ein vollständiges Rig wird erstellt (dies kann einen Moment dauern)
+   
+   **Methode 2: Properties-Panel (Alternative)**
+   - Im **Properties-Panel** (rechts):
+     - Klicke auf das **Wrench-Icon** (Modifier Properties) in der linken Toolbar
+     - Oder: Klicke auf das **Bone-Icon** (Armature Properties)
+     - Scrolle durch die Tabs, bis du **"Rigify"** oder **"Rigify Generation"** siehst
+     - In diesem Tab findest du den Button **"Generate Rig"**
+   - Klicke auf **"Generate Rig"**
+   
+   **Wichtig:** Nach dem Generieren kannst du das Rig weiter anpassen, aber du musst es im **Pose Mode** tun (nicht Edit Mode)
+   
+   **Die richtigen Tabs im Properties-Panel (von oben nach unten):**
+   - 📐 **Object Properties** (Würfel-Icon) - hier findest du Transform, etc.
+   - 🦴 **Armature Properties** (Bone-Icon) - hier findest du Armature-Einstellungen
+   - 🔧 **Modifier Properties** (Wrench-Icon) - hier sollte der **Rigify-Tab** sein!
+   - 🌍 **World Properties** (Globus-Icon) - NICHT hier suchen!
+   
+   **Falls du den Rigify-Tab nicht siehst:**
+   - Stelle sicher, dass das **Meta-Rig** (nicht ein bereits generiertes Rig) ausgewählt ist
+   - Klicke auf das **Wrench-Icon** (Modifier Properties) in der linken Toolbar
+   - Der Rigify-Tab sollte dort erscheinen
+
+#### Option B: Manuelles Rigging
+
+1. **Armature erstellen:**
+   - Drücke `Shift + A` → `Armature`
+   - Ein Bone wird erstellt
+
+2. **Bones hinzufügen:**
+   - Wechsle in den **Edit Mode** (Tab)
+   - Wähle den Root-Bone aus
+   - Drücke `E` um einen neuen Bone zu extrudieren
+   - Erstelle die wichtigsten Bones:
+     - **Spine/Spine1/Spine2** - Wirbelsäule
+     - **Neck/Head** - Hals und Kopf
+     - **LeftArm/LeftForeArm/LeftHand** - Linker Arm
+     - **RightArm/RightForeArm/RightHand** - Rechter Arm
+     - **LeftUpLeg/LeftLeg/LeftFoot** - Linkes Bein
+     - **RightUpLeg/RightLeg/RightFoot** - Rechtes Bein
+
+3. **Bone-Namen vergeben:**
+   - Wähle jeden Bone aus
+   - Im Properties-Panel (rechts) unter "Bone" kannst du den Namen ändern
+   - **Wichtig:** Verwende diese Namen für die Animation:
+     - `LeftArm`, `RightArm`
+     - `LeftForeArm`, `RightForeArm`
+     - `LeftHand`, `RightHand`
+     - `LeftUpLeg`, `RightUpLeg`
+     - `LeftLeg`, `RightLeg`
+     - `LeftFoot`, `RightFoot`
+     - `Neck`, `Head`
+     - `Spine`, `Spine1`, `Spine2`
+
+### 4. Modell an Bones binden (Skinning)
+
+1. **Beide Objekte auswählen:**
+   - Wähle zuerst das **Mesh** aus
+   - Dann wähle das **Armature** aus (Shift + Linksklick)
+   - Drücke `Ctrl + P` → `With Automatic Weights`
+   - Blender berechnet automatisch, welche Vertices zu welchen Bones gehören
+
+2. **Weights überprüfen:**
+   - Wähle das Mesh aus
+   - Wechsle in den **Weight Paint Mode** (Dropdown oben)
+   - Wähle einen Bone aus (rechts im Properties-Panel)
+   - Rot = vollständig gebunden, Blau = nicht gebunden
+   - Falls nötig, kannst du die Weights manuell anpassen
+
+### 5. Test-Animation erstellen (Optional)
+
+1. **Pose Mode aktivieren:**
+   - Wähle das **generierte Rig** aus (nicht das Meta-Rig!)
+   - Wechsle in den **Pose Mode** (Dropdown oben: "Object Mode" → "Pose Mode")
+   - Oder: `Ctrl + Tab` → "Pose Mode"
+
+2. **Bone auswählen:**
+   - **Wichtig:** Arbeite im **3D-Viewport** (Hauptfenster), nicht nur im Outliner!
+   - **Rigify-Bone-Namen** (nach dem Generieren):
+     - Für **Knie beugen**: `Leg.L (IK)` oder `Leg.L (FK)` (nicht "Tweak"!)
+     - Für **Hand anheben**: `Arm.L (IK)` oder `Arm.L (FK)`
+     - Für **Fuß bewegen**: `Leg.L (IK)` (der Fuß-Controller)
+     - **IK** = Inverse Kinematics (einfacher, empfohlen für Anfänger)
+     - **FK** = Forward Kinematics (mehr Kontrolle)
+     - **Tweak** = Feinabstimmungen (für später, nicht für Hauptanimationen)
+   - Klicke auf einen **Bone** im **3D-Viewport** (nicht im Outliner!)
+   - Der Bone sollte orange/ausgewählt sein und im Viewport sichtbar sein
+   - **Tipp:** Nutze `X-Ray Mode` (Button oben im Viewport) um Bones besser zu sehen
+   - **Tipp:** Im Outliner kannst du Bones finden, aber die Animation machst du im Viewport
+
+3. **Bone animieren:**
+   - Wähle z.B. `hand.L` (linke Hand) aus
+   - Drücke `R` (Rotate) und rotiere den Bone
+   - Oder: `R` + `Z` (um Z-Achse rotieren)
+   - Oder: `R` + `X` (um X-Achse rotieren)
+   - Bewege die Maus → Linksklick zum Bestätigen
+   - **Beispiel für Hand anheben:** `hand.L` → `R` → `Z` → nach oben bewegen
+
+4. **Animation aufnehmen (Timeline):**
+   - Unten siehst du die **Timeline** (falls nicht sichtbar: `Shift + F12` oder `Window` → `Animation` → `Timeline`)
+   - Stelle den Frame auf **1** (Anfang)
+   - Wähle den Bone aus und positioniere ihn in der **Ausgangsposition**
+   - Drücke `I` (Insert Keyframe) → wähle **"Rotation"** (oder "Location" falls bewegt)
+   - Ein Keyframe wird erstellt (gelber Punkt in der Timeline)
+   - Stelle den Frame auf **30** (oder einen anderen Frame)
+   - Rotiere/Bewege den Bone in die **Zielposition** (z.B. Hand nach oben)
+   - Drücke wieder `I` → **"Rotation"** (oder "Location")
+   - Stelle den Frame auf **60** (Rückkehr zur Ausgangsposition)
+   - Rotiere den Bone zurück zur Ausgangsposition
+   - Drücke `I` → **"Rotation"**
+   - Drücke **Play** (Leertaste) um die Animation zu sehen
+
+5. **Animation testen:**
+   - Die Animation sollte jetzt in einer Schleife abgespielt werden
+   - Du kannst weitere Keyframes hinzufügen (Frame 90, 120, etc.)
+   - **Tipp:** Nutze `Alt + A` um die Animation zu stoppen
+
+### 6. Modell exportieren
+
+1. **Beide Objekte auswählen:**
+   - Wähle das **Mesh** aus
+   - Shift + Linksklick auf das **generierte Rig** (nicht das Meta-Rig!)
+
+2. **Exportieren:**
+   - Gehe zu `File` → `Export` → `glTF 2.0 (.glb/.gltf)`
+   - Wähle `.glb` Format
+   - Stelle sicher, dass folgende Optionen aktiviert sind:
+     - ✅ **Include** → **Selected Objects**
+     - ✅ **Transform** → **+Y Up**
+     - ✅ **Geometry** → **Apply Modifiers**
+     - ✅ **Animation** → **Bake Animation** (wichtig für Animationen!)
+     - ✅ **Animation** → **Always Sample Animations** (falls Animationen nicht korrekt exportiert werden)
+   - Klicke auf "Export glTF 2.0"
+
+### 7. Modell testen
+
+1. Kopiere die exportierte `.glb` Datei nach:
+   ```
+   frontend/public/models/3d/falukant/characters/
+   ```
+2. Lade die Seite neu
+3. Die Bones sollten jetzt automatisch erkannt und animiert werden
+4. **Animationen testen:**
+   - Öffne die Browser-Konsole (F12)
+   - Du solltest sehen: `[ThreeScene] Found X animation(s)`
+   - Die Animationen sollten automatisch abgespielt werden
+   - Falls keine Animationen vorhanden sind, werden die Bones trotzdem mit Idle-Animationen bewegt
+
+## Rig anpassen - Detaillierte Anleitung
+
+### Rig nach dem Generieren anpassen
+
+Wenn das Rigify-Rig generiert wurde, aber nicht perfekt passt:
+
+1. **Pose Mode verwenden:**
+   - Wähle das generierte Armature aus
+   - Wechsle in den **Pose Mode** (Dropdown oben, oder Strg+Tab → Pose Mode)
+   - Hier kannst du die Bones bewegen, ohne die Struktur zu zerstören
+
+2. **Rig neu generieren (falls nötig):**
+   - Falls das Rig komplett neu positioniert werden muss:
+   - Lösche das generierte Rig (X → Delete)
+   - Gehe zurück zum Meta-Rig
+   - Passe das Meta-Rig im Edit Mode an
+   - Generiere das Rig erneut
+
+3. **Snap to Mesh (Hilfsmittel):**
+   - Im Edit Mode: `Shift + Tab` um Snap zu aktivieren
+   - Oder: Rechtsklick auf das Snap-Symbol (Magnet) oben
+   - Wähle "Face" oder "Vertex" als Snap-Target
+   - Jetzt werden Bones automatisch am Mesh ausgerichtet
+
+### Häufige Probleme und Lösungen
+
+**Problem: Rig ist zu groß/klein**
+- Lösung: Im Object Mode das Armature auswählen und mit `S` skalieren
+
+**Problem: Rig ist an falscher Position**
+- Lösung: Im Object Mode mit `G` bewegen, oder `Alt + G` zurücksetzen
+
+**Problem: Einzelne Bones passen nicht**
+- Lösung: Im Edit Mode die Bones einzeln anpassen (`G` zum Bewegen)
+
+**Problem: Nach dem Generieren passt es nicht mehr**
+- Lösung: Passe das Meta-Rig an und generiere neu, oder verwende Pose Mode
+
+## Tipps und Tricks
+
+### Bone-Namen für automatische Erkennung
+
+Die Komponente erkennt Bones anhand ihrer Namen. Verwende diese Keywords:
+- `arm` - für Arme
+- `hand` oder `wrist` - für Hände
+- `leg` oder `knee` - für Beine
+- `foot` oder `ankle` - für Füße
+- `shoulder` - für Schultern
+- `elbow` - für Ellbogen
+
+### Einfacheres Rigging mit Mixamo
+
+Alternativ kannst du:
+1. Dein Modell auf [Mixamo](https://www.mixamo.com/) hochladen
+2. Automatisches Rigging durchführen lassen
+3. Das geriggte Modell herunterladen
+4. In Blender importieren und anpassen
+
+### Performance-Optimierung
+
+- Verwende nicht zu viele Bones (max. 50-100 für Charaktere)
+- Entferne unnötige Bones vor dem Export
+- Teste die Animation im Browser, bevor du das finale Modell exportierst
+
+## Troubleshooting
+
+### Bones werden nicht erkannt
+
+- Prüfe die Bone-Namen (müssen `arm`, `hand`, `leg`, etc. enthalten)
+- Stelle sicher, dass das Modell korrekt an die Bones gebunden ist
+- Öffne die Browser-Konsole und prüfe die Logs: `[ThreeScene] Found X bones for animation`
+
+### Modell verformt sich falsch
+
+- Überprüfe die Weights im Weight Paint Mode
+- Passe die Bone-Positionen an
+- Stelle sicher, dass alle Vertices korrekt zugewiesen sind
+
+### Export schlägt fehl
+
+- Stelle sicher, dass beide Objekte (Mesh + Armature) ausgewählt sind
+- Prüfe, ob das Modell im Object Mode ist
+- Versuche es mit einem anderen Export-Format (.gltf statt .glb)
+
+## Weitere Ressourcen
+
+- [Blender Rigging Tutorial](https://www.youtube.com/results?search_query=blender+rigging+tutorial)
+- [Mixamo Auto-Rigging](https://www.mixamo.com/)
+- [Three.js GLTF Animation Guide](https://threejs.org/docs/#manual/en/introduction/Animation-system)