Digital Arts & Sciences Programs | Digital Worlds Institute | University of Florida
The J4Q project demonstrates how to create Virtual Reality apps for Meta Quest headsets as Native Android applications using Java in Android Studio. This project can be used as a setup for learning how to develop from scratch a basic game engine for Virtual Reality in Java. It can also be used along with a structured curriculum for teaching various topics related to game engine development such as: 3D Transformations using Matrices and Vectors, 3D geometry using triangular mesh, Animation loop, Shaders using GLSL, Controller input, Vibration feedback, and many other topics.
If you use this library please cite the paper, in which we introduced J4Q: Barmpoutis, A., Guo, W. and Said, I., 2023. Developing Mini VR Game Engines as an Engaging Learning Method for Digital Arts & Sciences. 13th IEEE Integrated STEM Education Conference, pp. 33-36. https://doi.org/10.1109/ISEC57711.2023.10402239
🥈 This paper won the Best Paper Award (2nd place) in the 13th IEEE Integrated STEM Education Conference at Johns Hopkins University, on March 11, 2023.
The project contains several sample VR apps located inside the J4Q_46.0/JavaForQuest/Projects
folder.
- 🔭 EndlessUniverse: A full-scale demo of the J4Q API
- ⏳ Sandbox: An empty project for you to start experimenting
- ⏳SandboxPhone: If you don't have a headset this template can help you develop and test J4Q apps on a phone or Android emulator.
- 🔷 HelloPolygon: An introduction on how to create 3D objects
- 🎨 HelloTexture: An example on how to map textures onto 3D geometry
- ♾️ HelloNormals: A tutorial on how to encode surface normal vectors
- 🎞️ HelloAnimation: An example on how to create simple animations
- 🔧 HelloObjectMaker: A simple API for composing 3D objects using primitive shapes
- 💬 HelloObjectClass: An example on how to define 3D objects as classes using object-oriented programming
- 🖲️ OBJViewer: This app demonstrates how to open a 3D model from an OBJ-formatted file
- 🎮 HelloControllers: A tutorial on VR controllers and how to use their input (pose, buttons, squeezes, joysticks) and output (vibration)
The following instructions will guide you step by step on how to setup and run J4Q in your system. The instructions include details for the following steps:
- Installation of required software.
- Configuration of headset.
- Opening in Android studio the project file:
J4Q_46.0/JavaForQuest/Projects/EndlessUniverse/build.gradle
You need to install the following software to be able to compile Android apps for Meta Quest headsets:
- Android Studio: https://developer.android.com/studio
- Open the SDK Manager of Android Studio and install the SDK Platform 8.0 (Oreo) API Level 26
- In the SDK Manager of Android Studio, go to the SDK Tools tab and check the box
Show Package Details
and install: 1) NDK (25.2.9519653), 2) CMake (3.22.1)
- Update the headset to the latest firmware and software by going to Quick Settings (where the time and battery status is shown) -> Settings -> Software Update
- Enable Developer Mode by using the Meta Quest app
- There are many Android studio projects inside the folder
J4Q_46.0/JavaForQuest/Projects
. Select a project and open in Android Studio the filebuilde.gradle
located inside the project folder. For example for the EndlessUniverse project open the file:J4Q_46.0/JavaForQuest/Projects/EndlessUniverse/build.gradle
- If there are errors during the build process, follow our troubleshooting guide at the end of this document.
- Connect your Quest headset to your development computer using the charging cable.
- In the headset accept the pop-up permission dialog.
- When the name of your headset device appears in the device list in the toolbar of Android Studio, click on the Run button to compile the project and install it on your headset.
- Test the J4Q Demo app in your headset.
- In general, you can find and run the app in your Quest headset in your Library in the category 'Unknown Sources'.
- Android Studio Giraffe | 2022.3.1 Patch 1
- Android SDK Platform 8.0 (Oreo) API Level 26
- Java 1.8 BellSoft Liberica version 1.8.0_345
- Gradle 6.1.1
- NDK 25.2.9519653
- CMake 3.22.1
- Operating Systems used for development: MacOS 13.4.1 Ventura, MacOS 12.5 Monterey (M2 chip), MacOS 11.7.1 Big Sur (Intel chip), Windows 10, Windows 11
- Meta Quest 1 & 2 (Testing systems)
Usually the error message is: Unsupported Java. Your build is currently configured to use Java ... and Gradle 6.1.1.
- Go to File -> Project Structure -> SDK Location and click on the
Gradle Settings
. - Set Gradle JDK to 1.8
- File -> Invalidate Caches and click on
Invalidate and Restart
.
The error message could also appear in other variations such as: Gradle sync failed: NDK Not Configured
- Verify that you have completed the prerequisite installation and particulraly the installation of NDK.
- Open the file
JavaForQuest/Projects/<Project Name>/local.properties
which was automatically generated and must contain the parameterssdk.dir
andndk.dir
. - If the file does not contain
ndk.dir
you can edit the text and append a line with the path to your NDK. For example:ndk.dir=...some path.../Android/sdk/ndk/25.2.9519653
. - Then, copy the
local.properties
file and paste it in theJ4Q_46.0
folder. DO NOT FORGET THIS STEP! - Finally, try again by clicking on the
try again
button on top of the text editor, when viewing the local.properties file.
Execution failed for task ':JavaForQuest:Projects:EndlessUniverse:genDebugKeystore'. Process 'command python3' finished with non-zero exit value 1
- This error appears if the file
JavaForQuest/Projects/<Project Name>/android.debug.keystore
is missing, possibly because it was automatically removed when performing Build -> Clean Project or Build -> Rebuild Project. - An easy way to fix this is to copy the file
JavaForQuest/keystore/android.debug.keystore
into the folderJavaForQuest/Projects/EndlessUniverse
and then re-run.
Otherwise, a more lengthy solution is to open a command line terminal and go into the folder JavaForQuest\Projects\<Project Name>
and run the command python3 ../../../bin/scripts/build/ovrbuild_keystore.py
. This step requires prior installation of python3 as well as setting the system variables ANDROID_NDK_HOME
and ANDROID_HOME
.
In MacOS it is helpful if you set Android Studio as a Developer Tool.
- To do that, first enable Developer Mode by opening the Terminal and typing
spctl developer-mode enable-terminal
. - Then in System Preferences go to Security & Privacy and in the Privacy Tab, go to the option Developer Tools and add Android Studio.
- This project was created using the Oculus OpenXR Mobile SDK 46.0 https://developer.oculus.com/downloads/package/oculus-openxr-mobile-sdk/
- Special thanks to Angelos Barmpoutis, Ines Said, and Wenbin Guo for their contributions to this project.
- We would like to thank the University of Florida for supporting the development of this project.
Barmpoutis, A., Guo, W. and Said, I., 2023. Developing Mini VR Game Engines as an Engaging Learning Method for Digital Arts & Sciences. 13th IEEE Integrated STEM Education Conference, pp. 33-36. https://doi.org/10.1109/ISEC57711.2023.10402239