This is the Unity Meta Quest setup article, and I'll be honest with you: it's not glamorous. Nobody ever finished a VR game and said "The best part was configuring Android modules." (Well, maybe some - who knows) Skip a step here, and you'll spend an evening staring at a build error that has nothing to do with your actual game. Been there. Don't recommend it. It's frustrating as hell!
So let's do this once, do it right, and never think about it again.
The Big Picture First
Before I go over all the details, here's pretty much the whole path from "fresh computer" to "app running on a headset":
Unity Hub → Android Modules → Developer Account → Developer Mode → USB Connection → Project Settings → Build
Seven stops, and each one depends on the one before it, which is exactly why a single missed step makes everything after it fail in confusing ways. Let's go over them in order.
Step 1: Pick The Right Unity Version
Meta's current Unity setup guides points you to Unity 6.1 or later. That's the version I'd start with for a brand new project.
Why does the version matter so much? Because Meta's SDKs are built against specific Unity versions, and the further you stray from what they recommend, the more you'll bump into odd bugs that nobody else on the internet has seen. Starting a new project? Use a recent supported version. Opening an old project? Check Meta's documentation before you upgrade anything, because upgrades and VR packages don't always get along.
Install it through Unity Hub, and keep going, because the install isn't done yet.
Step 2: Add The Android Build Modules (Yes, Android)
This is the one that surprises people. Quest headsets run on Android, so Unity builds your game as an Android app. That means you need the Android modules installed, even if you've never touched mobile development in your life.
In Unity Hub, find your editor version, open Manage → Add Modules, and tick the following:
- Android Build Support
- Android SDK & NDK Tools
- OpenJDK (usually listed alongside the other two)
(If you accidentally skipped this when installing Unity originally, don't worry. You can add modules to an existing install at any time. And if your build later fails with errors mentioning the SDK, NDK, or JDK, this is the first place to look.)
Step 3: Get A Meta Developer Account
To put your own apps on your own headset, you need to be a registered Meta developer. Head to the Meta developer site, sign in with the same Meta account you use on your headset, and complete the verification and developer organization setup it asks for.
Don't skip the verification part! Developer Mode in the next step depends on it, and it's the most common reason the toggle simply doesn't show up. You'll also use this dashboard later to create an App ID, which some features need and which you'll definitely need for publishing.
Step 4: Turn On Developer Mode On Your Headset
Developer Mode is what lets your headset accept apps that didn't come from the store. You enable it from the Meta Horizon mobile app on your phone (the app that used to be called the Meta Quest app):
Phone App → Your Headset → Headset Settings → Developer Mode → Toggle On
Then restart the headset. Menu names move around between app updates, so if yours looks a bit different, look for the Developer Mode option under your headset's settings.
While you're in there, keep your headset on the same Meta account as your developer account. A mismatch here is a classic "why is there no toggle" situation.
Step 5: Install Meta Quest Developer Hub (Optional But Nice)
Meta Quest Developer Hub, or MQDH, is a desktop app that makes your life easier. You can use it to manage your device, install builds, grab screenshots and recordings, and check that your headset is connected. It can even help you generate a starter Unity project.
It's technically optional. I'd install it anyway, because "is my headset actually connected?" is a question you'll ask a lot, and MQDH answers it at a glance.
One Windows-specific heads up: if your computer doesn't recognize the headset, you may need the Google USB driver for ADB to work properly. More on ADB in a second.
Step 6: Configure Your Unity Project
Now for the actual Unity side. Create a new 3D project, then work through this list:
- Switch the build platform. Go to File → Build Profiles. If you see a Meta Quest platform, select it. If you don't, select Android.
- Install the Meta XR SDK. Add Meta's XR package through the Package Manager. We'll cover what's inside it in Part 3, so for now, just get it installed.
- Enable OpenXR. Open Project Settings → XR Plug-in Management, switch to the Android tab, and tick OpenXR. This is where Unity learns that it's making a VR app.
- Run the Project Setup Tool. Meta's SDK includes a tool that checks your project for problems. Open it from the Meta menu in the Unity Editor and click Fix All, then Apply All.
That last one is the real hero. The Project Setup Tool spots misconfigured settings (graphics API, color space, and the like) and fixes them in a click. Skipping it is the number one reason new Quest projects behave strangely, so treat it as mandatory.
Tick "Switch the build platform" off that list and you'll notice something: Unity will take a while to reimport your assets. That's normal. Go grab a coffee.
Step 7: Connect Your Headset And Check It With ADB
Plug your headset into your computer with a USB cable, then put the headset on. You should see a prompt asking whether to allow USB debugging. Accept it, and tick the option to always allow it from this computer, unless you enjoy seeing that prompt forever.
To check that your computer can actually see the headset, use ADB (Android Debug Bridge). It's a command line tool that talks to Android devices. Open a terminal and run:
adb devicesYou should see your headset listed with the word device next to it. If it says unauthorized, put the headset on and accept the prompt. If nothing shows up at all, skip down to the troubleshooting list below.
Later on, you can also install a built app manually with ADB, which is handy for testing:
adb install -r path/to/YourGame.apkThe -r flag just means "replace the existing install," which saves you from uninstalling every time.
The "Why Won't It Build" Troubleshooting List
Something went wrong? Check these first. They cover most of the problems people run into:
- Headset doesn't show up in ADB: Try a different cable. Plenty of USB cables only charge and can't transfer data. Also confirm Developer Mode is on and you accepted the USB debugging prompt.
- No Developer Mode toggle in the phone app: Your Meta account probably isn't verified as a developer yet, or the headset is on a different account.
- SDK, NDK, or JDK errors during the build: The Android modules from Step 2 are missing or incomplete. Reinstall them through Unity Hub.
- Red items in the Project Setup Tool: Click Fix All and Apply All, then check again. Some items need a manual change, and the tool tells you which.
- The app launches but you get a black screen or no VR: Make sure OpenXR is enabled on the Android tab of XR Plug-in Management, not just the desktop tab. Yes, they're separate. Yes, that one gets everybody.
- No Meta Quest platform in Build Profiles: Not a problem. Use Android.
Bookmark this section. I'm only half joking.
Quick Recap
If you've followed along, here's what you should have:
Recent Unity Version + Android Modules + Verified Developer Account + Developer Mode On + ADB Seeing Your Headset + OpenXR Enabled + Project Setup Tool Clean
If all of that is checked off, congratulations. You've survived the most tedious part of the entire series, and it only gets more fun from here.
What's Next
In Part 3, we dive into the Meta XR SDK itself. It comes in a handful of packages with names that sound like a bowl of alphabet soup, so we'll sort out what each one does and what the camera rig is actually doing for you.
See you in Part 3!
No comments:
Post a Comment