Wiki

Clone wiki

Slip & Frag / Build instructions

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

A Visual Studio 2019 solution file is provided at the root of the source code folder, called SlipNFrag.sln. The solution contains a single project, located at SlipNFrag-Windows/SlipNFrag-Windows.vcxproj. This is an Universal Windows Platform application, which uses C++/WinRT to allow a closer integration of the C++ code of the engine with the newest Windows ABIs.

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

  • Download a copy of stb_vorbis.c (available here), and copy it into the SlipNFrag-Windows folder.

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

    IMPORTANT: Do not attempt to add stb_vorbis.c, from the previous step, directly into the project - this is not needed, the file is already #included in the engine by default, as if it were a header file.

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

    Most likely, you will find in your first compilation an error saying "Certificate does not match supplied signing thumbprint: ALONGHEXADECIMALSTRING". This happens because your machine does not have the required signing certificate to run Slip & Frag locally. To fix this, locate and open Package.appxmanifest in the project, and in the Packaging tab click on Choose Certificate, and point it to the supplied SlipNFrag-Windows_TemporaryKey.pfx file in the project. Password for that file is "slipnfrag". Otherwise, you can always create a new temporary certificate in that screen, if desired.

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:

  • Download a copy of stb_vorbis.c (as described above), and copy it into either the SlipNFrag-MacOS folder, or the SlipNFrag-iOS folder.

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

    IMPORTANT: Similar to above, do not attempt to add stb_vorbis.c, from the previous step, directly into the project - this is not needed, the file is already #included in the engine by default, as if it were a header file.

  • 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, and follow the prompts if required.

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.

Oculus Quest & Quest 2

Setting up the environment to debug, test or create a release of the Oculus Quest & Quest 2 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 Oculus 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 for this version can be found at OpenXR-SDK/src/SlipNFrag-OXR 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 Oculus Quest & Quest 2.

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 29

  • NDK (Side by Side) 22.1.7171670

  • Android Build tools 31.0.0

  • OpenXR SDK 1.0.19

  • Oculus OpenXR Mobile SDK 33.0.0

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

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 into the OpenXR-SDK folder of the project. Ensure that within the src folder, next to the common and loader subfolders, there is also a SlipNFrag-XR subfolder containing the project files.

  • 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 folder (thus, they will now be at the same level in the folder structure).

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

  • At the end of the file OpenXR-SDK/src/CMakeLists.txt, add the following line:

add_subdirectory(SlipNFrag-XR/app/src/main/cpp)
  • 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 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 OpenXR-SDK/src/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.

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