How to Build the Software

[!SUMMARY] This page explains how to:

  • Build the project for various target platforms, including
    • Windows
    • Meta Quest
    • WebGL
    • Linux Dedicated Server
Important

Anywhere Academy uses Unity's build profiles to manage the build settings for individual platforms.

To learn more about build profiles, see Unity's documentation: https://docs.unity3d.com/6000.3/Documentation/Manual/build-profiles.html

This guide contains a step by step guide to build for every targeted platform.

Before building any version of the software, check if the scene list is set up properly.

  1. Open Build Profiles Page (File → Build Profiles)
  2. Find and verify the Scene List

How to Build for Windows

Windows, Meta Quest and the Linux server have scripted builds. The same code runs in the Editor and in CI, so a local build and a pipeline build produce the same output.

  1. In the Editor, choose Tools → Build → Windows (VR)
  2. Confirm the prompt

In order, this:

  1. Switches the platform to Windows and activates the Windows (VR & NonVR) Build Profile
  2. Enables XR initialisation on startup and assigns the OpenXR loader for Standalone
  3. Pins the Standalone scripting backend to IL2CPP
  4. Deletes the contents of Build/Windows/, so no stale file from an earlier build can reach a package
  5. Builds the player
  6. Moves the non-shippable *_BurstDebugInformation_DoNotShip and *_BackUpThisFolder_ButDontShipItWithYourGame folders out of the player directory
Output Location
Player Build/Windows/
Debug and symbol artifacts Build/Build Artifacts/Windows/
Distributable .zip / .msi Dist/

Use Tools → Build → Windows (VR) + Package to also produce the .zip and .msi. Packaging needs PowerShell 7 (pwsh) on PATH; the .msi additionally needs wixl (GNOME msitools), which is only available on Linux, so a Windows developer machine produces the .zip only. Release .msi files come from CI.

Important

The build writes to two tracked files, deliberately and idempotently, so that CI and the Editor cannot silently disagree about how the player is configured:

  • Assets/XR/XRGeneralSettingsPerBuildTarget.asset — XR initialisation and the OpenXR loader. This also means Play Mode will start in VR afterwards.
  • ProjectSettings/ProjectSettings.asset — the Standalone scripting backend.

Commit both once, after the first build.

Caution

The build empties Build/Windows/ before building. This is what makes a build reproducible, but it is a real recursive delete. BuildCommand.AssertSafeToDelete refuses to run if the path is a filesystem root, contains the Unity project, or looks like a Unity project — but check -customBuildPath before pointing it somewhere new.

Note

Windows builds use IL2CPP, not Mono2x. The Windows (VR & NonVR) Build Profile does not override the scripting backend, so before this was pinned the build silently inherited whatever global Player Settings happened to say. Change the ScriptingBackend on BuildCommand.Windows if this ever needs to differ.

The scripts involved:

File Role
Assets/Editor/Build/BuildCommand.cs Everything that must happen inside Unity. Entry point BuildCommand.PerformBuild. Platform differences are described by BuildCommand.Windows / BuildCommand.Quest
Assets/Editor/Build/BuildMenu.cs The Tools → Build menu items
Tools/Build/PackagingCommon.ps1 Helpers shared by the packaging scripts
Tools/Build/Package-Windows.ps1 Produces the .zip and .msi. No Unity dependency
Tools/Packaging/Windows/AnywhereAcademy.wxs Installer authoring
Tools/Build/build-windows.sh The CI entry point

From CI

CI_PROJECT_DIR=$(pwd) \
BUILD_TARGET=StandaloneWindows64 \
BUILD_NAME="Anywhere Academy" \
  Tools/Build/build-windows.sh

The runner image needs xvfb, pwsh, msitools, and a Unity editor with the Windows IL2CPP build support module — building a Windows IL2CPP player from Linux fails without it. On GameCI images that is the windows-il2cpp variant, e.g. unityci/editor:ubuntu-6000.3.8f1-windows-il2cpp-3.

Manually

  1. Open Project Settings (Edit → Project Settings)
  2. Navigate to the XR Plug-in Management tab
  3. Verify that the settings are setup proper for you
  4. Open Build Profiles Page (File → Build Profiles)
  5. Find the Windows (VR & NonVR) Build Profile
  6. Adjust player settings as needed
    1. Version Number
    2. Graphics API
    3. etc.
  7. Hit Switch Platform or Build

How to Build for Meta Quest

Since Meta Quest uses an Android based OS, the Meta Quest (VR) Build Profile is based on Android settings.

  1. In the Editor, choose Tools → Build → Meta Quest (VR)
  2. Confirm the prompt

In order, this:

  1. Switches the platform to Android and activates the Meta Quest (VR) Build Profile
  2. Enables XR initialisation on startup and assigns the OpenXR loader for Android
  3. Pins the Android scripting backend to IL2CPP and forces APK output over App Bundle
  4. Derives AndroidBundleVersionCode from the project version using the mapping below
  5. Configures release signing from environment variables, falling back to the debug keystore locally
  6. Deletes the contents of Build/Android/
  7. Builds the APK
  8. Moves *_BurstDebugInformation_DoNotShip and the *.symbols.zip out of the build directory
Output Location
APK Build/Android/
Debug and symbol artifacts Build/Build Artifacts/Android/
Distributable APK Dist/

Use Tools → Build → Meta Quest (VR) + Package to also publish a versioned copy, e.g. Dist/Anywhere Academy-1.0.4-quest.apk.

Note

Every packaged artifact gets its own checksum file beside it, named <artifact>.sha256.txt — so a file handed to someone individually still carries proof of integrity. The contents are in the format sha256sum -c expects, so on Linux:

sha256sum -c "Anywhere Academy-1.0.4-quest.apk.sha256.txt"

and on Windows, compare against Get-FileHash -Algorithm SHA256 <file>.

Note

The version code mapping is now applied by the build script rather than by hand:

Version $X.Y.Z$ becomes version code $X \cdot 10000 + Y \cdot 100 + Z$.

Example Version 2.5.17 becomes version code 20517.

Bump the version in Player Settings; the version code follows automatically. A stale version code silently prevents a headset from installing the update over an existing build.

Signing

Release signing comes from four environment variables:

Variable Meaning
ANDROID_KEYSTORE_PATH Path to the .keystore file
ANDROID_KEYSTORE_PASS Keystore password
ANDROID_KEYALIAS_NAME Key alias
ANDROID_KEYALIAS_PASS Key alias password

Set all four and the APK is signed for release. Leave them unset and an Editor build falls back to Unity's debug keystore, with a warning.

Caution

A batch mode build with no keystore configured fails outright, and Package-Quest.ps1 refuses to publish a debug-signed APK unless you pass -AllowDebugSigned.

The debug keystore is generated per machine. A debug-signed APK cannot be installed over a release-signed one — the user has to uninstall first and loses their data. This is why it is a hard failure rather than a warning.

Store the keystore as a GitLab CI file variable and the passwords as masked variables. Never commit either. The passwords are only held in memory for the build session; ProjectSettings.asset records just the keystore path and alias name.

From CI

CI_PROJECT_DIR=$(pwd) \
BUILD_TARGET=Android \
BUILD_NAME="Anywhere Academy" \
ANDROID_KEYSTORE_PATH=/secure/anywhere-academy.keystore \
ANDROID_KEYSTORE_PASS=... \
ANDROID_KEYALIAS_NAME=... \
ANDROID_KEYALIAS_PASS=... \
  Tools/Build/build-quest.sh

The runner image needs xvfb, pwsh, and a Unity editor with the Android build support module including OpenJDK and the SDK/NDK — on GameCI, the android variant, e.g. unityci/editor:ubuntu-6000.3.8f1-android-3.

Manually

  1. Open Project Settings (Edit → Project Settings)
  2. Navigate to the XR Plug-in Management tab
  3. Verify that the settings are setup proper for you
  4. Open Build Profiles Page (File → Build Profiles)
  5. Find the Meta Quest (VR) Build Profile
  6. Adjust player settings as needed
    1. Version Number
    2. Bundle Identifier
    3. Graphics API
    4. etc.
  7. Hit Switch Platform or Build

How to Build for WebGL

Unity allows to optimize either build time or performance when building for WebGL. As WebGL should run on devices without GPU and older devices, the web version of Anywhere Academy is optimized for performance. To allow efficient development iteration, there are two build profiles for WebGL in the project: Web (NonVR) and Web Productive (NonVR), with the former being optimized for build time, the latter for performance. Use them as you like.

Caution

The WebGL Build profiles use individual player settings. This requires additional consideration with version numbers and other settings that need to be copied from the global player settings.

  1. Open Build Profiles Page (File → Build Profiles)
  2. Find the correct WebGL Build Profile
  3. Adjust player settings as needed
    1. Version Number
    2. etc.
  4. Hit Switch Platform or Build

How to Build a Dedicated Linux Server

Anywhere Academy uses a headless dedicated Linux server for its multiuser functionalities. Most scenes will not work without being connected to a server.

  1. In the Editor, choose Tools → Build → Linux Server
  2. Confirm the prompt

In order, this:

  1. Switches the platform to Linux with the Dedicated Server subtarget and activates the Linux Server Build Profile
  2. Disables XR and removes all XR loaders
  3. Pins the Server scripting backend to Mono2x
  4. Deletes the contents of Build/Server/
  5. Builds the server, always named Anywhere_Academy.x86_64
  6. Moves the debug output into Build/Build Artifacts/Server/
Output Location
Server Build/Server/
Debug artifacts Build/Build Artifacts/Server/
Distributable .tar.gz Dist/
Important

The output directory and executable name are fixed, not derived from the product name, because Server-Dockerfile hardcodes both:

COPY ./Build/Server /app
RUN chmod +x /app/Anywhere_Academy.x86_64
ENTRYPOINT ["/app/Anywhere_Academy.x86_64"]

Renaming either silently breaks the container image. -customBuildName is accepted but ignored for this platform.

Because the build writes to Build/Server/, create_local_server.ps1 and publish_local_server.ps1 keep working unchanged — run them straight after a build.

Caution

The server build turns XR off for Windows too. XR Plug-in Management is keyed by build target group, and the dedicated server shares BuildTargetGroup.Standalone with the Windows player — there is no separate server entry. The two cannot hold different values at once.

Every build sets what it needs rather than inheriting whatever the last build left behind, so the outcome is always deterministic — but Assets/XR/XRGeneralSettingsPerBuildTarget.asset flips between builds. After a server build, run a Windows build before shipping VR, and expect that file to show up in git status either way.

In CI this is a non-issue, because every job starts from a fresh clone.

Use Tools → Build → Linux Server + Package to also produce Dist/Anywhere Academy-1.0.4-linux-server.tar.gz.

Note

.tar.gz rather than .zip because the zip format cannot record the Unix execute bit on Anywhere_Academy.x86_64.

An archive built on Windows still loses that bit — bsdtar has no Unix permissions to record — and the script warns when this happens. Release archives should come from the Linux CI job, where it is preserved automatically. The Docker image is unaffected either way, since the Dockerfile chmods explicitly.

From CI

CI_PROJECT_DIR=$(pwd) \
BUILD_TARGET=StandaloneLinux64 \
BUILD_NAME="Anywhere Academy" \
  Tools/Build/build-server.sh

The runner image needs xvfb, pwsh, tar, and a Unity editor with Linux build support — Mono2x needs no IL2CPP module, so the base editor image is enough.

Note this script writes to Build/Server, not Builds/$BUILD_TARGET like the Windows and Quest scripts, so that a docker build -f Server-Dockerfile . can run in the same job with no copying.

Manually

  1. Open Build Profiles Page (File → Build Profiles)
  2. Find the Linux Server Build Profile
  3. Adjust global player settings as needed
    1. Version Number
    2. etc.
  4. Hit Switch Platform or Build