yourpart3/docs/BLENDER_RIGGING_GUIDE.md

# 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)