# ondevice — składanie projektu Unity (PoC-1, Meta Quest 3)

Skrypty C# w `Scripts/` są gotowe do podpięcia. Poniżej lista ręcznych kroków
w Unity Editorze (nie da się ich wygenerować plikami). Odpowiada §5 z `docs/ONDEVICE.md`.

---

## 0. Wymagania wstępne

| Narzędzie | Wersja |
|---|---|
| Unity | 2022 LTS (6000.x) lub 2023 LTS |
| Android Build Support + OpenJDK | przez Unity Hub |
| Meta XR SDK | aktualny (via Package Manager → Add by git URL) |
| sherpa-onnx Unity plugin | patrz krok 4 |
| TextMeshPro | com.unity.textmeshpro (wbudowany w Unity) |

---

## 1. Nowy projekt Unity

1. Utwórz projekt **3D (URP)** lub **3D (Built-in)**.
2. Otwórz **Edit → Project Settings → Player → Android**:
   - Target Architecture: **ARM64**
   - Minimum API: **29** (Quest 3)
   - Target API: **32** (lub latest)
3. Otwórz **Edit → Project Settings → XR Plug-in Management → Android**:
   - Zaznacz **OpenXR**
   - W zakładce OpenXR dodaj **Meta Quest feature set**
4. Otwórz **Edit → Project Settings → XR Plug-in Management → OpenXR**:
   - Zaznacz **Meta Quest Support** i **Hand Tracking Subsystem** (opcjonalnie).

---

## 2. Meta XR SDK — passthrough

1. W **Package Manager** dodaj Meta XR SDK:
   ```
   https://npm.developer.oculus.com   (scope: com.meta.xr)
   ```
   Zainstaluj: **Meta XR All-in-One SDK** lub minimum **Meta XR Core SDK**.
2. Utwórz scenę z **OVRCameraRig** (lub użyj prefabu z SDK).
3. Na `OVRManager` włącz **Passthrough Support = Required**.
4. Dodaj komponent **OVRPassthroughLayer** do kamery (Type: Underlay).

---

## 3. Bank poleceń — generowanie i import

```bash
# W repo ipin-vr (Python):
python -m ipin_vr export --per-level 300 --out commands.json --seed 42
```

Następnie:
1. Utwórz katalog **Assets/StreamingAssets/** (jeśli nie istnieje).
2. Skopiuj `commands.json` do **Assets/StreamingAssets/commands.json**.

---

## 4. sherpa-onnx — instalacja wtyczki i modelu głosu

### 4a. Wtyczka

Wybierz jedną z opcji:

**Opcja A — ręczne .aar/.dll z wydania sherpa-onnx:**
1. Pobierz z https://github.com/k2-fsa/sherpa-onnx/releases pliki dla Unity
   (szukaj `unity-*` w Assets danego wydania).
2. Umieść `.dll` (Windows/Editor) i `.aar` (Android) w `Assets/Plugins/`.

**Opcja B — pakiet UPM (community):**
```
https://github.com/EitanWong/com.eitan.sherpa-onnx-unity.git
```
Dodaj przez **Package Manager → Add package from git URL**.

### 4b. Model głosu polskiego

1. Pobierz `vits-piper-pl_PL-gosia-medium.tar.bz2` z:
   https://github.com/k2-fsa/sherpa-onnx/releases/tag/tts-models
2. Rozpakuj — otrzymasz katalog `vits-piper-pl_PL-gosia-medium/` zawierający:
   - `pl_PL-gosia-medium.onnx`
   - `tokens.txt`
   - `espeak-ng-data/` (katalog)
3. Skopiuj cały katalog do **Assets/StreamingAssets/**:
   ```
   Assets/StreamingAssets/
     commands.json
     vits-piper-pl_PL-gosia-medium/
       pl_PL-gosia-medium.onnx
       tokens.txt
       espeak-ng-data/
   ```

### 4c. Aktywacja silnika TTS w kodzie

Po zainstalowaniu wtyczki odkomentuj bloki oznaczone `[SHERPA]` w `TtsManager.cs`:
- `using SherpaOnnx;` (lub odpowiednia przestrzeń nazw wtyczki)
- blok konfiguracji `OfflineTtsConfig` w `InitCoroutine`
- blok `_tts.Generate(...)` w `SpeakCoroutine`

**Uwaga na espeak-ng-data:** Weryfikuj, czy Twoja wtyczka kopiuje `espeak-ng-data`
automatycznie ze StreamingAssets. Jeśli nie — spakuj katalog jako `.zip` i rozpakowuj
w `TtsManager.EnsureEspeakData()`.

---

## 5. Scena — podpinanie skryptów

### 5a. Obiekty w hierarchii

```
Scene
├── OVRCameraRig          ← z Meta XR SDK
│   └── CenterEyeAnchor
├── SessionManager        ← pusty GameObject
│   ├── CommandBank.cs
│   ├── TtsManager.cs
│   └── SessionController.cs
└── Canvas (World Space)  ← panel UI
    ├── LoadingPanel
    │   └── TMP_Text "Ładowanie..."
    └── SessionPanel
        ├── TMP_Text "CommandText"  ← główny tekst polecenia
        ├── Button "Next"           ← trigger "następne"
        └── LevelButtons
            ├── Button "L1"
            ├── Button "L2"
            └── Button "L3"
```

### 5b. Inspector — SessionController

| Pole | Przypisz |
|---|---|
| Command Bank | GameObject SessionManager → CommandBank |
| Tts Manager | GameObject SessionManager → TtsManager |
| Command Text | TMP_Text CommandText |
| Loading Panel | GameObject LoadingPanel |
| Session Panel | GameObject SessionPanel |
| Next Button | Button Next |
| Start Level | 1 |

### 5c. Przyciski poziomu — OnClick

Każdy przycisk L1/L2/L3:
- Cel: SessionManager → SessionController
- Funkcja: `SetLevel(1)` / `SetLevel(2)` / `SetLevel(3)`

### 5d. TMP_Text — czcionka z polskimi znakami

Domyślna czcionka TMP może nie zawierać wszystkich polskich znaków. Aby to naprawić:
1. Pobierz czcionkę z polskim zestawem (np. Noto Sans Regular).
2. Utwórz **TMP Font Asset** (**Window → TextMeshPro → Font Asset Creator**),
   zaznaczając znaki Latin Extended-A i Latin Supplement.
3. Przypisz nowy Font Asset do komponentu TMP_Text.

---

## 6. Build i sideload na Quest 3

```bash
# W Unity Editor:
# File → Build Settings → Android → Switch Platform
# Player Settings → Package Name: com.twojanazwa.ipinvr
# File → Build And Run   (upewnij się, że Quest 3 podłączony przez USB + tryb dev)
```

Lub zbuduj APK i sideloaduj ręcznie:
```bash
adb install -r ipin-vr.apk
```

---

## 7. Pomiar wydajności (cel PoC-1)

Po uruchomieniu na Queście zbierz metryki wg §7 z `docs/ONDEVICE.md`:
- **OVR Metrics Tool** (sideload z Meta) — FPS, CPU/GPU load, RAM
- **adb logcat** — `lowmemorykiller`, błędy sherpa-onnx
- **Perfetto** — latencja TTS od wywołania `Speak()` do pierwszego dźwięku

Metryki docelowe: PSS < 5,75 GiB, FPS stable 72/90, latencja TTS < 1 s.

---

## 8. Sanity check bez Unity (zalecane najpierw)

Zanim zaczniesz budować projekt, przetestuj głos na telefonie z Androidem:
1. Pobierz oficjalne APK TTS ze strony sherpa-onnx.
2. Sideloaduj i sprawdź jakość polskiego głosu `gosia-medium`.
3. Dopiero potem wchodź w pełny projekt Unity.