vr-app/docs/01-phase0-setup-unity.md

# Phase 0 — Setup Unity pour Meta Quest, à partir de zéro

> Écrit pour quelqu'un qui n'a **jamais ouvert Unity**. Chaque chemin de menu est donné en entier.
>
> ⚠️ **Unity n'est pas installé sur cette machine** (vérifié le 2026-08-31, toujours vrai). Je ne
> peux donc rien compiler ni tester : ce guide est vérifié sur la doc et l'expérience du SDK, pas
> par une exécution. **Compte 2 à 4 allers-retours** sur les versions de packages Meta, qui bougent
> vite d'une release à l'autre.
>
> ⚠️ Les numéros de version ci-dessous sont ceux que je connais. **Avant d'installer, ouvre la page
> de compatibilité Meta** (`developers.meta.com` → Unity → *Requirements*) et prends la version
> d'Unity qui y est marquée recommandée. Si elle diffère, c'est elle qui gagne, pas ce document.

---

## Ce que je peux produire, et ce que tu dois cliquer

| Je peux générer en fichier | Tu dois le faire à la main dans l'éditeur |
|---|---|
| `Packages/manifest.json` (la liste des packages) | Installer Unity Hub et Unity |
| Tous les scripts C# (`Assets/Scripts/**`) | Créer le projet (le template) |
| Un script d'éditeur qui **construit la scène par code** | Le premier clic sur *Build And Run* |
| `.gitignore` Unity | Activer le mode développeur sur le casque |
| Les fichiers de configuration texte lisibles (`.asmdef`, JSON) | Les cases de **Project Settings** (voir §5) |
| — | Les cases de **XR Plug-in Management** (§6) |

**Pourquoi je ne génère pas les `ProjectSettings/*.asset` ni les `.unity`** : c'est du YAML Unity
avec des GUID et des `fileID` internes. Écrit à la main, ça produit un projet qui *s'ouvre* mais
dont un réglage sur deux est silencieusement faux — le pire des cas, parce que ça ne plante pas.
Les réglages se font à l'écran, une fois, en 15 minutes. La **scène**, en revanche, je peux la
construire par code via un script d'éditeur (`[MenuItem]`) : c'est lisible, versionnable et
rejouable.

---

## 1. Installer Unity Hub et Unity

1. Télécharge **Unity Hub** : `unity.com/download`. C'est le lanceur ; Unity lui-même s'installe
   depuis lui.
2. Crée un compte Unity (gratuit) et prends la licence **Personal** dans le Hub :
   *Hub → icône compte (haut droite) → Manage licenses → Add → Get a free personal license*.
3. Dans le Hub : **Installs → Install Editor**.
4. Choisis une version **LTS** — au moment d'écrire, la ligne recommandée par Meta est **Unity 6
   LTS (6000.0.x)**. Prends la dernière `6000.0.xxf1` de la liste LTS.
   > Pourquoi LTS : support 2 ans, et surtout c'est la seule ligne que Meta teste. Une version
   > `.a`/`.b` (alpha/beta) te fera perdre des journées sur des bugs qui ne sont pas les tiens.

### Modules à cocher — c'est l'écran à ne pas rater

À l'écran *Add modules*, coche :

- ☑️ **Android Build Support** — et **déplie-le**, les deux sous-modules ne sont pas cochés par
  défaut selon les versions :
  - ☑️ **OpenJDK**
  - ☑️ **Android SDK & NDK Tools**
- ☑️ *Documentation* (optionnel, pratique hors ligne)

Ne coche pas iOS, WebGL, Linux : c'est des Go pour rien.

> **Si tu oublies un sous-module** : *Hub → Installs → ⚙️ sur la version → Add modules*. Rien
> n'est perdu, mais Unity te dira « No Android module loaded » sans expliquer lequel manque.

---

## 2. Créer le projet

1. **Hub → Projects → New project**.
2. Template : **3D (Built-In Render Pipeline)** ou **Universal 3D (URP)** ?
   → **URP**. Meta recommande URP pour Quest : le *Forward+* et le rendu mono-passe stéréo y sont
   optimisés, et l'essentiel de la doc Meta récente le suppose. Prends **Universal 3D**.
3. Nom du projet : `MyInfoMateVR`.
4. Emplacement : `…/GITEA/vr-app/unity/`.
5. **Create project.** Premier lancement : 2 à 5 minutes.

> Tu obtiens un dossier avec `Assets/`, `Packages/`, `ProjectSettings/`, `Library/`.
> **`Library/` ne se versionne jamais** — c'est du cache, plusieurs Go. Le `.gitignore` s'en charge.

---

## 3. Le `.gitignore` (je le génère)

Fichier à créer à la racine de `vr-app/` — voir `../.gitignore` une fois généré. L'essentiel :
`Library/`, `Temp/`, `Obj/`, `Build/`, `Logs/`, `UserSettings/`, `*.csproj`, `*.sln`.

⚠️ **Git LFS** : les `.glb`, `.fbx`, `.png` et `.mp4` sont des binaires lourds. Si le repo doit un
jour contenir des assets, active LFS **avant** le premier commit d'un binaire — après, c'est une
réécriture d'historique.

---

## 4. Les packages (je génère `Packages/manifest.json`)

Trois familles :

### 4.1 XR — installés par l'éditeur

- `com.unity.xr.openxr` — **OpenXR Plugin**, la couche standard.
- `com.unity.xr.interaction.toolkit` — optionnel si tu utilises l'Interaction SDK de Meta.

*Window → Package Manager → Unity Registry → chercher « OpenXR Plugin » → Install.*

### 4.2 Meta XR SDK — le point qui bouge le plus

Meta distribue son SDK de deux façons selon les versions : par l'**Asset Store** (« Meta XR
All-in-One SDK ») ou par un **registre npm** déclaré dans `manifest.json`. Les packages qui comptent :

| Package | Rôle |
|---|---|
| `com.meta.xr.sdk.core` | **Meta XR Core SDK** — obligatoire : caméra, tracking, passthrough |
| `com.meta.xr.sdk.interaction.ovr` | **Interaction SDK** — raycast contrôleur *et* hand tracking |
| `com.meta.xr.sdk.all` | le méta-paquet qui tire tout (plus lourd) |

**Ce que tu dois faire à la main la première fois** :
*Window → Asset Store → chercher « Meta XR All-in-One SDK » → Add to My Assets → Open in Unity →
Package Manager → My Assets → Download → Import.*

Puis Unity affiche un assistant **Meta XR Project Setup Tool** (*Edit → Project Settings → Meta XR*)
qui liste les réglages non conformes avec un bouton **Fix** / **Fix All**. ➡️ **Utilise-le.** Il
applique la moitié du §5 tout seul, et il est à jour du SDK installé — donc plus fiable que ce
document.

### 4.3 glTF — le cœur du pipeline

Ajoutés par *Window → Package Manager → **+** (haut gauche) → Add package by name…* :

| Nom exact à coller | Rôle |
|---|---|
| `com.unity.cloud.gltfast` | **glTFast** — chargement de `.glb` **au runtime** |
| `com.unity.cloud.ktx` | support **KTX2 / Basis Universal** des textures |
| `com.unity.cloud.draco` | géométrie compressée **Draco** |
| `com.unity.meshopt.decompress` | géométrie compressée **Meshopt** |

> Les trois derniers sont **des dépendances optionnelles de glTFast** : sans eux, un GLB compressé
> se charge en erreur silencieuse (mesh vide, texture rose). C'est exactement le genre de panne qui
> coûte une demi-journée — installe-les tout de suite, même si les premiers GLB ne sont pas compressés.

---

## 5. Configurer le build Android pour Quest — écran par écran

> Fais d'abord tourner le **Meta XR Project Setup Tool** (§4.2), puis vérifie ce qui suit. Ce que
> l'outil corrige, tu n'as pas à le refaire.

### 5.1 Passer la plateforme en Android

*File → Build Profiles* (Unity 6 ; **File → Build Settings** avant Unity 6)
→ sélectionne **Android** → **Switch Platform**.
⏱️ Le premier switch réimporte tous les assets : **5 à 20 minutes**. C'est normal, ne l'interromps pas.

Dans le même écran : **Texture Compression → ASTC**.

### 5.2 Player Settings

*Edit → Project Settings → Player*, onglet Android (l'icône robot) :

| Section | Réglage | Valeur |
|---|---|---|
| *Other Settings → Rendering* | **Color Space** | **Linear** |
| | **Auto Graphics API** | ❌ décoché |
| | **Graphics APIs** | **Vulkan uniquement** — supprime `OpenGLES3` de la liste |
| | **Multithreaded Rendering** | ☑️ |
| *Other Settings → Identification* | **Package Name** | `be.unov.myinfomate.vr` (jamais le `com.DefaultCompany` par défaut) |
| | **Minimum API Level** | **32** (Android 12L) — exigé par Horizon OS récent |
| | **Target API Level** | la plus haute proposée (34+) |
| *Other Settings → Configuration* | **Scripting Backend** | **IL2CPP** (Mono ne produit pas d'APK Quest valide) |
| | **Target Architectures** | ☑️ **ARM64** seulement — décoche ARMv7 |
| | **Active Input Handling** | **Both** — le plus sûr : l'`OVRInput` de Meta est en legacy, le reste de l'écosystème en new Input System |
| *Resolution and Presentation* | **Default Orientation** | **Landscape Left** |
| *Publishing Settings* | **Custom Main Manifest** | ☑️ si tu dois ajouter des permissions à la main |

### 5.3 Quality

*Edit → Project Settings → Quality* : garde **un seul** niveau pour Android, et mets-y :
**Anti Aliasing = 4x Multi Sampling** (le MSAA est quasi gratuit sur le GPU mobile du Quest, et
c'est ce qui fait la différence entre « propre » et « ça scintille »), **Shadows = Hard Shadows Only**
ou aucune.

---

## 6. XR Plug-in Management

*Edit → Project Settings → **XR Plug-in Management*** :

1. S'il propose **Install XR Plug-in Management**, clique.
2. Choisis l'onglet **Android** (l'icône robot) — ⚠️ **pas** l'onglet PC. C'est l'erreur n°1 :
   tout configurer sur PC et obtenir un APK sans VR.
3. ☑️ **OpenXR**
4. Sous **OpenXR** (sous-entrée du menu de gauche), onglet Android :
   - **Enabled Interaction Profiles** → **+** → **Oculus Touch Controller Profile**
   - **OpenXR Feature Groups** → ☑️ **Meta Quest** (ou *Meta Quest Support* selon la version)
5. Un triangle jaune ⚠️ à côté d'un réglage est **cliquable** : il ouvre un correcteur automatique.
   Aucun triangle ne doit rester avant de builder.

---

## 7. Activer le mode développeur sur le casque

À faire une seule fois, mais dans cet ordre — l'étape 1 est celle qu'on oublie :

1. **Crée une organisation développeur** : `developers.meta.com` → connecte-toi avec le compte Meta
   **du casque** → *Create organization*. Sans organisation, le toggle de l'étape 3 n'apparaît pas.
2. Application **Meta Horizon** sur le téléphone → **Devices** (ou *Appareils*) → sélectionne le
   casque → assure-toi qu'il est **connecté**.
3. → **Headset settings** → **Developer mode** → ☑️.
4. **Redémarre le casque.**
5. Branche le casque en USB-C au PC. **Mets le casque sur la tête** : une popup *« Autoriser le
   débogage USB ? »* apparaît **dans le casque**, pas sur le PC. Coche *Toujours autoriser* et
   accepte. Tant que ce n'est pas fait, `adb devices` affiche `unauthorized`.
6. Vérifie côté PC :
   ```
   adb devices
   ```
   `adb` se trouve dans le SDK Android installé par Unity :
   `C:\Program Files\Unity\Hub\Editor\<version>\Editor\Data\PlaybackEngines\AndroidPlayer\SDK\platform-tools\`
   Ajoute ce dossier au `PATH`, tu t'en serviras tous les jours.

> **Alternative confortable** : **Meta Quest Developer Hub (MQDH)**, l'outil desktop de Meta. Il
> gère l'appairage, l'installation d'APK par glisser-déposer, la capture vidéo de ce que voit le
> casque (précieux pour montrer une démo à un client) et les logs. Recommandé.

---

## 8. Hello World VR — le seul test qui compte

**But** : voir une scène en stéréo dans le casque et bouger la tête. Rien d'autre. Tant que ça ne
marche pas, tout le reste est théorique.

### Ce que tu fais à la main

1. *File → New Scene → Basic (URP)* → sauvegarde en `Assets/Scenes/Hello.unity`.
2. Supprime la **Main Camera** de la hiérarchie (le rig VR apporte la sienne).
3. Ajoute le rig : *menu **Meta** → Tools → **Building Blocks*** → glisse **Camera Rig** dans la
   scène. (Si le menu Meta n'existe pas, le SDK n'est pas importé — retour au §4.2.)
4. Clic droit dans la hiérarchie → *3D Object → Cube*, place-le à `Position (0, 1.5, 2)`,
   `Scale (0.3, 0.3, 0.3)`. C'est ton repère visuel.
5. *File → Build Profiles* → vérifie que `Assets/Scenes/Hello.unity` est **dans la liste des scènes**
   et cochée (bouton *Add Open Scenes* si elle n'y est pas).
6. Casque branché et autorisé → **Build And Run**.
7. Premier build : **10 à 30 minutes** (IL2CPP compile tout le code natif). Les suivants : 1 à 3 min.

### Critère de validation

Le cube est devant toi, en relief, et il reste **immobile dans l'espace** quand tu bouges la tête
(pas collé au regard). Si le cube suit ta tête, le rig n'est pas correctement en place.

### Panne la plus fréquente

| Symptôme | Cause |
|---|---|
| L'app s'ouvre en écran plat flottant, pas en VR | XR Plug-in Management configuré sur l'onglet **PC** au lieu d'**Android** (§6.2) |
| `adb: device unauthorized` | La popup d'autorisation n'a pas été acceptée **dans le casque** (§7.5) |
| Build échoue sur « No Android module » | Sous-modules OpenJDK / SDK-NDK non cochés (§1) |
| Écran noir au lancement | Graphics API : OpenGLES3 encore présent avant Vulkan (§5.2) |
| Tout est rose | Shader non compatible URP — l'objet vient d'un import Built-In |

---

## 9. Étape suivante immédiate

Une fois le cube visible, **la vraie étape 1 du projet** (cahier des charges §PHASE 3) :

1. Un monde Marble généré **à la main** sur le site de World Labs, exporté en **mesh GLB**.
2. Ce GLB posé dans `Assets/StreamingAssets/` et chargé **au runtime par glTFast** — pas glissé dans
   la scène comme un asset d'éditeur. C'est toute la différence : le chargement runtime est ce qui
   permettra plus tard de télécharger un monde depuis le manager sans rebuild.
3. Un second GLB de personnage posé dedans, à l'échelle, avec un idle.
4. Vu dans le casque.

Aucun backend n'est nécessaire pour ces quatre points — c'est ce qui les rend faisables tout de
suite, en parallèle de tout le reste. Les scripts C# de chargement, je les génère quand tu me dis
que le cube est passé.