ipin-vr/ondevice/README.md

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

# 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

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

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.