1. Heriberto Delgado Avatar Heriberto Delgado
  2. My projects
  3. Slip & Frag

Wiki

Clone wiki

Slip & Frag / Build instructions

View History

Build instructions

Slip & Frag is provided as a C++ project, itself a modification of the original C code of the Quake engine, with added constructs from other languages such as Objective C, Java (or Kotlin) used in the platforms that are supported.

Source code for the project is provided here. Details for each supported platform are provided below.

Windows (x64)

A Visual Studio 2022 solution file is provided at the root of the source code folder, called SlipNFrag.sln. The solution contains a single project, located at SlipNFrag-Win64/SlipNFrag-Win64.vcxproj. This is a Win32 project configured to run as a 64-bit application, that does not depend on any other APIs other than the ones that came with a Windows 10 or later machine. (A few uses have reported that this executable, as it is, can also be made to run in a Linux environment properly configured.)

To set up the environment to build, debug and test the project for the first time:

  • Clone or download the latest version of stb (as found in https://github.com/nothings/stb ). Create a stb folder at the root source folder, next to the `SlipNFrag-Win64 folder. Ensure that the "stb_xxx.h" files are located at the root of the stb folder to ensure proper compilation.

  • Open Visual Studio 2022 (or newer), then open the SlipNFrag.sln solution in the top folder.

  • Compile and run the project as usual for Visual Studio to debug or test it.

To generate a Release build of the project, ensure that you selected the Release configuration in the IDE, then right-click on the project file - Publish - Create app packages, and follow the prompts.

MacOS

You will find a project package called SlipNFrag.xcodeproj at the root of the source code folder. Open this package using Xcode 12 or newer. The source files that this project references are in the SlipNFrag-MacOS folder - or, if you intend to build the experimental iOS target, in the SlipNFrag-iOS folder.

The project itself has 3 targets:

  • One with just the source code of the engine and minimal, almost empty porting helper .cpp files (SlipNFrag);

  • One with all the sources required to build the MacOS version (SlipNFrag-MacOS);

  • One with all the sources required to build the experimental iOS version (SlipNFrag-iOS).

To set up the environment to build, debug and test the project for the first time, for either target:

  • Clone or download the latest version of stb (as found in https://github.com/nothings/stb ). Create a stb folder at the root source folder, next to the SlipNFrag-MacOS and SlipNFrag-iOS folders. Ensure that the "stb_xxx.h" files are located at the root of the stb folder to ensure proper compilation.

  • Open Xcode 12 (or newer), then open the SlipNFrag.xcodeproj project in the top folder.

  • Choose your target (MacOS or iOS) from the Target selector at the top of the main Xcode screen.

  • Compile and run the project as usual for Xcode to debug or test it. For MacOS, pressing the Play button at the top of the screen should suffice. For iOS, you will need to setup the Signing configuration of the project with your own Apple Developer account before compiling.

To generate a Release build of either the MacOS or iOS target, ensure that your target's schema has the Build Configuration of its Run settings in Release, instead of Debug, mode. After that, generate an Archive of the project, follow the prompts if required, then Distribute App / Copy App in Organizer.

In the particular case of the MacOS executable, the .dmg file that is used to distribute the project can be generated from the Disk Utility in MacOS. Follow the instructions in "Create a disk image from a folder or connected device" specified here to do so.

Meta Quest/2/3

Setting up the environment to debug, test or create a release of the Meta Quest, Quest 2 and Quest 3 versions involves more steps than the versions above, due to the amount of external components involved in the compile & release process.

There used to be a version intended to be compiled using (back then) the native Oculus Mobile SDK; starting from the announcement from Meta to deprecate this SDK in favor of OpenXR, the old OVR version has been officially removed from the repository, and a new OXR version replaces it.

The Android Studio 4 project (which can be opened with later versions, such as 2023.1.1 for example) for this version can be found at the SlipNFrag-OXR folder from the root of the source code folder. The project itself is a CMake-backed native activity project, configured with special settings that allow it to run in standalone VR headsets such as the Meta Quest/2/3.

The following is the list of components, and their version numbers, required to build the Android project, as of this writing:

  • Android 10.0 (R) API level 34

  • NDK (Side by Side) 26.2.11394342

  • Android SDK Build-Tools 34.0.0

  • OpenXR SDK 1.0.32

  • Oculus OpenXR Mobile SDK 62.0

  • stb (latest version gathered from https://github.com/nothings/stb )

  • Vulkan validation layers 1.3.236.0 (only required for debugging, not for the final build. Also, later versions do not seem to behave well in their respective builds, somehow.)

To set up the environment to build, debug and test the project for the first time:

  • Ensure that your VR headset is in Developer mode, and that it can run applications from Unknown sources. (See Home for details).

  • Download the latest release of the OpenXR SDK (as stated above). Copy the contents of the OpenXR-SDK-release-xxx from the .zip file at the root source folder.

    (If the name of the folder from the OpenXR SDK references a newer version than the specified above, modify the path to the SDK specified in SlipNFrag-XR/app/src/main/cpp/CMakeLists.txt file and change it so it points to the new version.)

  • Download the latest version of the Oculus OpenXR Mobile SDK (as stated above). Copy the ovr_openxr_mobile_sdk_xxx folder from the SDK at the root source folder, next to the OpenXR-SDK-release-xxx folder (thus, they will now be at the same level in the folder structure).

    (Similar to above, if the name of the folder from the Oculus OpenXR Mobile SDK references a newer version, modify the path to the SDK specified in CMakeLists.txt file and change it so it points to the new version.)

  • Clone or download the latest version of stb (as stated above). Create a stb folder at the root source folder, next to the OpenXR-SDK-release-xxx and ovr_openxr_mobile_sdk_xxx folders. Ensure that the "stb_xxx.h" files are located at the root of the stb folder to ensure proper compilation.

  • Open Android Studio 4 (or newer), then open the project in the SlipNFrag-XR folder. Wait for Gradle to finish configuring the environment for the project, and follow the prompts if instructed to do so.

    (Check that your environment has the components described above, with their respective versions.)

  • Locate the Build Variants tab in Android Studio, ensure that you have selected the following:

    • Module: :app
    • Active Build Variant: debug
    • Active ABI: arm64-v8a

  • Ensure that your device is connected and visible in Android Studio (look for mentions of the device name in the top bar of the IDE), and then press the Play button to run & test the project, or the Debug button to debug it.

    IMPORTANT: Be sure to follow the instructions in Home to copy the game assets to your device to be able to play the game as expected.

If you need to enable the Vulkan validation layers for this project:

  • Grab a copy of the Vulkan validation layers (version specified above) and copy it into the root source folder of the project.

  • Ensure that, in the file SlipNFrag-XR/app/src/main/cpp/CMakeLists.txt, the reference to the validation layers folder matches the name of the recently copied layers.

To generate a Release build of the project, in .apk form, do the following:

  • If you haven't done so, create an android.debug.keystore file to sign your app. The file can be generated from the Oculus OpenXR Mobile SDK folder, by doing the following:

    • Windows: from a command prompt, run ovr_openxr_mobile_sdk_xxx\bin\scripts\build\ovrbuild_keystore.py.bat. NOTE: You will need Python properly configured in your system to do this.
    • MacOS and others: open a terminal, and run python3 ./ovr_openxr_mobile_sdk_xxx/bin/scripts/build/ovrbuild_keystore.py.

  • Locate the Build Variants tab in Android Studio, ensure that you have selected the following:

    • Module: :app
    • Active Build Variant: release
    • Active ABI: arm64-v8a

  • From Android Studio, do any of the following:

    • Either, go to Build - Build Bundle(s) / APK(s) - Build APK(s), then follow the prompts;
    • Or, go to Build - Generate Single Bundle / APK, fill whatever data is needed (including the newly generated android.debug.keystore file, keys and passwords) and follow the prompts.

      (Slip & Frag currently supports APK generation using Signature Version V2 - Full APK Signature.)

Support

If you need additional help to perform these steps, see Support for your current options.

Updated