Building

Building the Project

Building is the process of creating executable files so that the game can be played without the Unity Editor. In essence this process will create the .exe- and .apk-files of your app. These can then be distributed way more easy as the whole unity project.

Preparation

"Everything is fine until you hit build, and hell breaks loose"

Don't worry, it isn't that bad! But there are some things you need to be aware of, that may prevent your app from being built or cause other errors. This can be frustrating, especially when everything works in the editor.

Add scenes

This is the first thing you want to check if all scenes have been added to the "Build Settings" (via File > Build Settings... or the shortcut Ctrl + Shift + B). In this dialog, you will find a list of scenes and their index next to them. You might be familiar with them if you have implemented a main menu.
Only these scenes will be added in your final build, so add every scene you need. This can be done by opening the scene in the editor and pressing "Add Open Scenes" in the "Build Settings". This will add the scene to the build and assign a scene index, which can be used to switch to that scene.
Keep in mind that the scene with index 0 will be the one that is loaded on startup.

Check your scripts

Make sure that you are not using any editor-only scripts or functionality in your app. This includes all scripts in any (sub-)folder named "Editor" but also any script using such scripts. Make sure to remove or exclude any usage of the classes/functions. It is not necessary to remove any using-statements to such classes.

To exclude functionality in the built version and make it only available when running the game in the editor, surround the code with the following notation:

    public void MyFunction()
    {
#if UNITY_EDITOR
    // Your editor-only code here
# endif
    }

Bake the Lighting

Before building a project with multiple scenes (e.g., a main menu and a exhibition/experiment scene), the lighting will be darker than in the editor. This is because the lighting of the skybox must be "baked" in the scene. Head to "Window > Rendering > Lighting" and select the "Baked Lightmap" Tab. Press the "Generate Lightmaps" Button at the bottom and wait for its completion. Repeat this step for all the scenes that should be exported.

(Android Only) Add a Keystore

If you are planning on releasing your app to Androids Oculus Store or the App Lap, you will need to sign your app digitally. Unity's Keystore Manager allows you to do exactly that. You will not need to do this for Pc or if you are not planning on releasing your app or only on itch.io!
You will find it under "Edit... > Project Settings > Player". Then locate select the tab with the android symbol and unfold the option "Publishing Settings". Pressing the Button "Keystore Manager..." will open it, where you can create a new certificate to sign your app.
The process should be straightforward, but you'll want to store the certificate at a secure location, if possible, somewhere outside your repository.

Once you've created your certificate, select it and enable "Custom Keystore" back in the "Publishing Settings". Then use the dropdown below to select your certificate and enter your certificate's password. Before every build, this step has to be performed, so for debugging purposes, you may want to disable it!

Export

After completing all the steps above, you are ready to build. This can be done via File > Build Settings....

Here you need to specify the platform you want to target, either "PC, Mac & Linux Standalone" or "Android" (for Quest). If the latter is not available, make sure that you installed Android Support when installing Unity. It can be installed now by going to the "Unity Hub", selecting the "Add Modules" by finding "Gear"-Icon of your Unity version in the section "Installs". Select "Android Build Support" and all submodules, and install them. Then restart your Unity Editor.

Back in the editor, the current build platform is marked with an Unity symbol. It can be changed by selecting another platform, then hitting "Switch Platform" on the bottom right.

Go to "Edit > Project Settings..." and select either "Oculus" or "OpenXR"(for almost everything else) in the "PC" tab from the "XR Plug-ing Management" section depending on your VR headset.

Build Error Handling

• If the export fails, it is usually because the code contains references to some Unity Editor-exclusive code, like UnityEditor.EditorApplication.isPlaying = false;. This can be easily prevented by adding a notation that the code should be excluded when building:

#if UNITY_EDITOR
    UnityEditor.EditorApplication.isPlaying = false;
#endif

• If the app will not build for Quest, be sure to check if the XR-Plugin-Management was set to "OpenXR" Crashes during compiling usually stem from having changed the XR-Plugin-Management in the "Android"-Tab from "OpenXR" to "Oculus" instead of using the "PC"-Tab.
• Another reason might be that you are trying to build (i.e., patch) directly to your oculus device. If your device does not allow data transfer or is not in Developer Mode, this will fail.
• If the app can be built and started but only within a window in the Quest, be sure that in the "Project Settings" under "XR Plug-in Management > OpenXR" the option "Meta Quest Support" is enabled, and all errors have been fixed. (If there is a red circle or a yellow warning sign next to it, double-click it and hit "Fix")
• If the app builds but only runs very laggy it might be because of VSync being enabled. This issue seems to occur in Unity 2021+ builds. Turning VSync off should fix it.