Note:
This plugin is in beta.
Testing needs to be complete before it's deemed stable and ready for use.
If you'd like to contribute to the testing process, follow the instructions below to setup and use the plugin,
and report any issues you encounter. Thanks!
This repository contains the source code for the Oculus Mobile Godot plugin. See demo project as an example for how to use the plugin.
This is an Android only plugin that is only supported on the following Oculus Mobile devices:
- Oculus Quest
- Oculus Go
The use of this plugin require Godot 3.2 or later.
- This project is released under a MIT license.
- Please check the Oculus Mobile SDK license for information about the Oculus Mobile SDK used in this project.
After cloning this repository make sure to initialise the submodules with git submodule init
.
When you've pulled a newer version make sure to run git submodule update
.
The project uses cmake
as its primary build system, which you can configure by following the setup instructions
for the Android SDK & NDK.
- Download and setup the Android SDK.
- If using Android Studio, download version 3.5 or higher.
- If using the command line tools, download revision 26.1.1 or higher.
- To ensure you have the latest version, check SDK Manager for updates.
- Add the Android SDK cmake binaries directory to the environment path. The directory can be found under
<android_sdk_location>/cmake/<cmake_version>/bin
.- Ensure that
cmake_version
is greater or equal to version3.6.0
.
- Ensure that
- Download and setup the latest version (version r20 or higher) of the Android NDK.
- Set the environment variable
ANDROID_NDK_HOME
to the Android NDK location.
By default the project is configured to checkout the godot_headers
repo as a submodule under the godot_headers
directory when you run
the git submodule init
and git submodule update
commands.
You can edit the GODOT_HEADERS_DIR
cmake variable in the CMakeLists.txt
build file if you'd like to provide a different source for the Godot headers.
- Download the latest version
(version 1.25.0 or higher) of the Oculus Mobile SDK into the
ovr_sdk_mobile
directory (create the directory if it doesn't exist). - If needed, update the
OVR_ROOT_DIR
cmake variable in the theCMakeLists.txt
build file to point to the Oculus Mobile SDK containing folder.
Note: Ensure you're using the Android SDK's version of cmake
.
In the project root directory:
- Navigate to the
build
directory:cd build
- Run:
cmake -GNinja ..
cmake --build .
Once the build successfully completes, the plugin and its dependencies shared libraries can be found in the
default output location: demo/addons/godot_ovrmobile/libs/<arch>
When exporting the project apk in Godot, the following Android export
Graphics
options should be set:
Xr Mode
must be set toOculus Mobile VR
.Degrees of Freedom
:- If deploying only on Oculus Quest, this must be set to
6DOF
- If deploying on Oculus Go, or on Oculus Go and Oculus Quest,
this must be set to
3DOF and 6DOF
- If deploying only on Oculus Quest, this must be set to
This plugin exposes parts of the Oculus VrApi via GDNative script classes. The actual exported functions can be found in src/config/.
Here is an example of how to use these classes inside GDScript:
onready var ovrTrackingTransform = preload("res://addons/godot_ovrmobile/OvrTrackingTransform.gdns").new()
onready var ovrGuardianSystem = preload("res://addons/godot_ovrmobile/OvrGuardianSystem.gdns").new()
func _process(delta):
print("GetTrackingSpace: " , ovrTrackingTransform.get_tracking_space())
print("GetBoundaryVisible: ", ovrGuardianSystem.get_boundary_visible())
print("GetBoundaryOrientedBoundingBox: ", ovrGuardianSystem.get_boundary_oriented_bounding_box())
There is also a OvrUtility GDNative script class that exposes some utility functions to configure the compositor or query information:
onready var ovrUtilities = preload("res://addons/godot_ovrmobile/OvrUtilities.gdns").new()
func do_something():
# Query the current IPD; return value is in m
print("Current IPD is: %.1fmm" % (ovrUtilities.get_ipd() * 1000.0))
# set a color multiply (also useful for fade to black)
ovrUtilities.set_default_layer_color_scale(Color(1.0, 0.3, 0.4, 1.0));
# query controller acceleration/velocities; return value is Vector3
print(ovrUtilities.get_controller_angular_velocity(1)); # parameter is the controller_id (either 1 or 2)
print(ovrUtilities.get_controller_linear_velocity(1));
print(ovrUtilities.get_controller_angular_acceleration(1));
print(ovrUtilities.get_controller_linear_acceleration(1));
# the same is available for the head:
print(ovrUtilities.get_head_angular_velocity());
print(ovrUtilities.get_head_linear_velocity());
print(ovrUtilities.get_head_angular_acceleration());
print(ovrUtilities.get_head_linear_acceleration());
In addition to the official API above there is the experimental OvrVrApiProxy.gdns
class that exposes partially the low level property setters/getters from the VrApi.h.
This API is to be considered temporary and might be removed in future releases of the plugin. If possible it is recommended to use the offical API described above.
The functions inside the API rely on enum values so there is an convenience class OvrVrApiTypes.gd
that contains the enum values.
In the example below you can see a sample usage of the API. For details of the different enum values and query options
please check the VrApi.h file from the oculus mobile sdk.
onready var ovr_vr_api_proxy = preload("res://addons/godot_ovrmobile/OvrVrApiProxy.gdns").new();
onready var ovr_types = preload("res://addons/godot_ovrmobile/OvrVrApiTypes.gd").new();
func test_property_access():
print("Testing vrapi access:")
print("System property:")
print(" vrapi_get_system_property_int(VRAPI_SYS_PROP_DEVICE_TYPE) = ", ovr_vr_api_proxy.vrapi_get_system_property_int(ovr_types.OvrSystemProperty.VRAPI_SYS_PROP_DEVICE_TYPE));
print(" vrapi_get_system_property_int(VRAPI_SYS_PROP_SUGGESTED_EYE_TEXTURE_WIDTH) = ", ovr_vr_api_proxy.vrapi_get_system_property_int(ovr_types.OvrSystemProperty.VRAPI_SYS_PROP_SUGGESTED_EYE_TEXTURE_WIDTH));
print("Property:")
print(" vrapi_get_property_int(VRAPI_DEVICE_EMULATION_MODE) = ", ovr_vr_api_proxy.vrapi_get_property_int(ovr_types.OvrProperty.VRAPI_DEVICE_EMULATION_MODE));
print(" vrapi_get_property_int(VRAPI_ACTIVE_INPUT_DEVICE_ID) = ", ovr_vr_api_proxy.vrapi_get_property_int(ovr_types.OvrProperty.VRAPI_ACTIVE_INPUT_DEVICE_ID));
print(" vrapi_get_property_int(VRAPI_FOVEATION_LEVEL) = ", ovr_vr_api_proxy.vrapi_get_property_int(ovr_types.OvrProperty.VRAPI_FOVEATION_LEVEL));
ovr_vr_api_proxy.vrapi_set_property_int(ovr_types.OvrProperty.VRAPI_FOVEATION_LEVEL, 3);
print(" vrapi_get_property_int(VRAPI_FOVEATION_LEVEL) = ", ovr_vr_api_proxy.vrapi_get_property_int(ovr_types.OvrProperty.VRAPI_FOVEATION_LEVEL));
print("System Status:")
print(" vrapi_get_system_status_int(VRAPI_SYS_STATUS_MOUNTED) = ", ovr_vr_api_proxy.vrapi_get_system_status_int(ovr_types.OvrSystemStatus.VRAPI_SYS_STATUS_MOUNTED));
print(" vrapi_get_system_status_int(VRAPI_SYS_STATUS_RENDER_LATENCY_MILLISECONDS) = ", ovr_vr_api_proxy.vrapi_get_system_status_int(ovr_types.OvrSystemStatus.VRAPI_SYS_STATUS_RENDER_LATENCY_MILLISECONDS));
print(" vrapi_get_system_status_int(VRAPI_SYS_STATUS_FRONT_BUFFER_SRGB) = ", ovr_vr_api_proxy.vrapi_get_system_status_int(ovr_types.OvrSystemStatus.VRAPI_SYS_STATUS_FRONT_BUFFER_SRGB));