API

Work-in-progress - This document is incomplete, very condensed, and liable to change often.

This is an early primer on Freebird's API for using VR events. Very condensed for now. And it doesn't include any info about the UI api or pointer events.

Conceptually, there are two "things" you can add listeners to: root and Object.

Well, there's a third thing as well, called Node (which represents the UI inside VR, for e.g. the main menu, sub-menu etc), but that's not covered in this doc right now.

root can be considered as the empty space around you. Object is any object in the scene, like mesh.

You can add these event listeners to either root or Object: * trigger_main_start, trigger_main_press, trigger_main_end * trigger_alt_start, trigger_alt_press, trigger_alt_end * trigger_both_start, trigger_both_press, trigger_both_end // when both triggers are pressed simultaneously

squeeze_main_start, squeeze_main_press, squeeze_main_end
squeeze_alt_start, squeeze_alt_press, squeeze_alt_end
squeeze_both_start, squeeze_both_press, squeeze_both_end // when both squeeze buttons are pressed simultaneously
drag_start, drag, drag_end // when the main trigger or squeeze presses and drags beyond a threshold
click // when the main trigger is pressed and released without moving

Drag is also used for world navigation, by listening for drag events on the root object, i.e. empty space.

These events can only be bound on the root object: * joystick_x_main_press // when the main joystick is pushed horizontally * joystick_y_main_press // when the main joystick is pushed vertically * joystick_x_alt_press // when the alt joystick is pushed horizontally * joystick_y_alt_press // when the alt joystick is pushed vertically

button_a_main_start, button_a_main_press, button_a_main_end
button_b_main_start, button_b_main_press, button_b_main_end
button_a_alt_start, button_a_alt_press, button_a_alt_end
button_b_alt_start, button_b_alt_press, button_b_alt_end

Example

Open a Text Editor panel in Blender next to the 3D Viewport.
Please press Start VR to start Freebird.
Create a new text file in the Text Editor panel (from step 1), and paste this. Finally, press the "Run" button in Blender's Text Editor (looks like a Play button)

import bpy

from bl_xr import root

def on_btn_press(self, event_name, event):
    print("Pressed the controller button! You can do something here, like setting a weight")

# this registers a callback when the upper button (B or Y) is pressed on the alternate controller
root.add_event_listener("button_b_alt_start", on_btn_press)

This will run the code in the on_btn_press function, when the upper button (B or Y) is pressed on the alternate controller.

import bpy

from bl_xr import root

def on_joystick_push(self, event_name, event):
    print("Main joystick pushed:", event.value)  # event.value will be continuous numbers from -1 (down) to 1 (up)

# this registers a callback for when the joystick is pushed up/down (i.e. vertically) on the alternate controller
root.add_event_listener("joystick_y_main_press", on_joystick_push)

event.value will be continuous numbers from -1 (down) to 1 (up), for e.g. 0.2 if the joystick is pushed forward 20%, or -0.5 if the joystick is pushed down 50%

joystick_x_main_press // when the main joystick is pushed horizontally
joystick_y_main_press // when the main joystick is pushed vertically
joystick_x_alt_press // when the alt joystick is pushed horizontally
joystick_y_alt_press // when the alt joystick is pushed vertically

In the case of horizontal joysticks (e.g. joystick_x_main_press or joystick_x_alt_press), positive numbers indicate moving right, and negative is for left

But joystick_x_alt_press is already bound to Freebird's undo/redo system, so it's probably best to avoid listening to that one

API

Example

See also