breakpilot-pwa/breakpilot-drive/README.md

# Breakpilot Drive - Unity Lernspiel

Ein Endless Runner Lernspiel fuer Kinder der Klassen 2-6 mit Quiz-Integration.

## Uebersicht

- **Video-Version**: Visuelles 3D-Spiel mit 3-Spur-Steuerung
- **Audio-Version**: Barrierefreier Hoerspiel-Modus mit raeumlichem Audio
- **Quiz-Integration**: Hybrid-Modus mit schnellen visuellen Fragen UND Denkpausen

## Schnellstart (Docker)

```bash
# Game-Container starten (mit Backend)
docker-compose --profile game up -d

# Nur das Backend starten (fuer API-Tests)
docker-compose up backend -d

# Game oeffnen
open http://localhost:3001
```

## Unity Projekt erstellen

### Voraussetzungen

- Unity 2022.3 LTS oder neuer
- WebGL Build Support Modul installiert

### Neues Projekt erstellen

```bash
# Unity Hub oeffnen und neues 3D Projekt erstellen
# Projektname: BreakpilotDrive
# Speicherort: /path/to/breakpilot-pwa/breakpilot-drive/Unity/
```

### Empfohlene Projektstruktur

```
Unity/
├── Assets/
│   ├── Scripts/
│   │   ├── Core/
│   │   │   ├── GameManager.cs          # Spielzustand, Score
│   │   │   ├── DifficultyManager.cs    # Schwierigkeitsanpassung
│   │   │   └── AudioManager.cs         # Sound-Verwaltung
│   │   ├── Player/
│   │   │   ├── PlayerController.cs     # 3-Spur-Bewegung
│   │   │   └── PlayerInput.cs          # Touch/Keyboard Input
│   │   ├── Track/
│   │   │   ├── TrackGenerator.cs       # Endlose Strecke
│   │   │   ├── ObstacleSpawner.cs      # Hindernisse
│   │   │   └── VisualTrigger.cs        # Quiz-Trigger (Bruecke, etc.)
│   │   ├── Quiz/
│   │   │   ├── QuizManager.cs          # Quick/Pause-Modus
│   │   │   ├── QuestionDisplay.cs      # UI fuer Fragen
│   │   │   └── QuizAudio.cs            # TTS fuer Audio-Version
│   │   ├── Network/
│   │   │   ├── BreakpilotAPI.cs        # REST API Client
│   │   │   └── OfflineCache.cs         # Lokaler Fragen-Cache
│   │   └── UI/
│   │       ├── MainMenu.cs             # Startbildschirm
│   │       ├── GameHUD.cs              # Score, Leben
│   │       └── QuizOverlay.cs          # Frage-Anzeige
│   ├── Prefabs/
│   │   ├── Player/
│   │   │   └── Car.prefab              # Spieler-Auto
│   │   ├── Obstacles/
│   │   │   ├── Rock.prefab
│   │   │   └── Barrier.prefab
│   │   ├── Items/
│   │   │   ├── Star.prefab
│   │   │   ├── Coin.prefab
│   │   │   └── Shield.prefab
│   │   └── VisualTriggers/
│   │       ├── Bridge.prefab           # Loest Quick-Quiz aus
│   │       ├── House.prefab
│   │       └── Tree.prefab
│   ├── Audio/
│   │   ├── Music/
│   │   │   └── GameLoop.mp3
│   │   ├── SFX/
│   │   │   ├── Coin.wav
│   │   │   ├── Crash.wav
│   │   │   └── Correct.wav
│   │   └── Voice/
│   │       └── (TTS-generiert)
│   ├── Scenes/
│   │   ├── MainMenu.unity
│   │   ├── Game_Video.unity
│   │   └── Game_Audio.unity
│   └── WebGLTemplates/
│       └── Breakpilot/
│           └── index.html              # Custom WebGL Template
├── Packages/
│   └── manifest.json
└── ProjectSettings/
    └── ProjectSettings.asset
```

## API-Endpunkte

Das Backend stellt folgende Endpunkte bereit:

### Lernniveau
```
GET /api/game/learning-level/{user_id}
→ { overall_level: 1-5, math_level, german_level, english_level }
```

### Schwierigkeit
```
GET /api/game/difficulty/{level}
→ { lane_speed, obstacle_frequency, question_complexity, answer_time }
```

### Quiz-Fragen
```
GET /api/game/quiz/questions?difficulty=3&count=10&mode=quick
→ [{ id, question_text, options, correct_index, visual_trigger, time_limit_seconds }]

GET /api/game/quiz/questions?difficulty=3&count=5&mode=pause
→ [{ id, question_text, options, correct_index }]
```

### Visuelle Trigger
```
GET /api/game/quiz/visual-triggers
→ [{ trigger: "bridge", question_count: 2, difficulties: [1,2] }]
```

### Session speichern
```
POST /api/game/session
{ user_id, game_mode, duration_seconds, score, questions_answered, questions_correct }
→ { session_id, status, new_level? }
```

## WebGL Build erstellen

1. Unity oeffnen → File → Build Settings
2. Platform: WebGL auswaehlen
3. Player Settings:
   - Compression Format: Gzip
   - Decompression Fallback: Aktiviert
   - WebGL Template: Breakpilot (custom)
4. Build → Zielordner: `breakpilot-drive/Build/`

Nach dem Build:
```bash
# Docker Container neu bauen
docker-compose --profile game build breakpilot-drive

# Container starten
docker-compose --profile game up -d breakpilot-drive
```

## Quiz-Modus Implementierung

### Quick Mode (waehrend der Fahrt)

```csharp
// Wenn Spieler sich einem VisualTrigger naehert
public class VisualTrigger : MonoBehaviour
{
    public string triggerType; // "bridge", "tree", etc.

    void OnTriggerEnter(Collider other)
    {
        if (other.CompareTag("Player"))
        {
            // Frage anzeigen, Spiel laeuft weiter
            QuizManager.Instance.ShowQuickQuestion(triggerType);
        }
    }
}
```

### Pause Mode (Spiel pausiert)

```csharp
// Alle X Meter/Punkte eine Denkaufgabe
public class QuizManager : MonoBehaviour
{
    public void ShowPauseQuestion()
    {
        Time.timeScale = 0; // Spiel pausieren
        // Komplexe Frage anzeigen
        // Nach Antwort: Time.timeScale = 1;
    }
}
```

## Entwicklungs-Workflow

1. **Lokal entwickeln**: Unity Editor mit Play-Modus
2. **API testen**: `docker-compose up backend -d`
3. **WebGL testen**: Build erstellen, Container starten
4. **Commit**: Git-Aenderungen committen (ohne Build-Artefakte)

## Bekannte Einschraenkungen

- Unity WebGL unterstuetzt kein natives Audio-Recording (fuer Sprachsteuerung)
- Mobile Browser haben unterschiedliche Touch-Implementierungen
- WASM-Dateien koennen gross werden (>50MB) - Kompression wichtig

## Ressourcen

- [Unity WebGL Doku](https://docs.unity3d.com/Manual/webgl.html)
- [UnityWebRequest](https://docs.unity3d.com/ScriptReference/Networking.UnityWebRequest.html)
- [Breakpilot Drive Plan](../docs/breakpilot-drive-plan.md)