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é.