OpenXRActionMap in Godot – Complete Guide

Diving into the world of virtual reality and augmented reality can be both exhilarating and daunting. As developers, we need to work with complex and sophisticated systems that make our immersive experiences feel natural and intuitive. This is where understanding and leveraging OpenXRActionMap in Godot 4 becomes crucial. This tutorial promises to guide you through understanding the OpenXRActionMap class, highlighting its significance, and demonstrating through simple yet engaging examples how you can use it to your advantage. Whether you are at the beginning of your development journey or a seasoned coder, there’s something here for everyone to grasp and enhance their skill set.

What is OpenXRActionMap?

OpenXRActionMap is a core component in the Godot engine that plays a vital role for developers focusing on XR (Extended Reality) projects. It’s a resource class specifically designed for the OpenXR module, which acts as an intermediary between various types of XR controller inputs/outputs and the named actions within your game. It’s akin to Godot’s own Input map system but tailored for the extended capabilities and requirements of XR environments.

What is it for?

In essence, the OpenXRActionMap is utilized to bind controller interactions to actions in your Godot 4 project. It is used to suggest bindings to the XR runtime, which has the responsibility to finalize these bindings, ensuring compatibility with current and future XR hardware. This level of abstraction provides a mapping system that is flexible and user-oriented, allowing for extensive customization and adaptability to various interaction profiles.

Why Should I Learn It?

Grasping the OpenXRActionMap is a game-changer for developers working on XR projects because:

  • Future-proofing: By using an action map, you allow the XR runtime to adapt your game to new hardware, effectively future-proofing your project.
  • User-Centric Design: It provides the end-user with options to customize their experience by remapping controls to suit their preferences or specific hardware setups.
  • Consistency Across Devices: It ensures that your application can deliver a consistent experience across an array of devices, a significant factor in the fragmented XR device market.

This control system is pivotal in creating an immersive and responsive user experience, and learning it can elevate the quality of your XR applications to new heights.

CTA Small Image

Setting Up an OpenXR Action Map

Before we dive into the examples, ensure you have Godot 4 with XR capabilities configured.

To begin setting up an OpenXR action map, we need to define actions and bindings. Actions are the fundamental user intentions like “grab”, “move”, or “shoot”, while bindings connect physical control movements or button presses to these actions.

var action_map =

func _ready():
    action_map.register_action("grab", OpenXRAction.HAND_POSE)
    action_map.register_action("teleport", OpenXRAction.POSE)

This snippet initializes a new OpenXR action map and registers two actions: “grab” and “teleport”. We specify the type of action given the context; for instance, `HAND_POSE` for grab actions and `POSE` for teleportation.

Bind Device Inputs to Actions

Next, we need to bind device inputs to these actions. This step is crucial as it enables the XR runtime to recognize the inputs corresponding to each action.

# Define action bindings for a generic controller
# Right Hand
action_map.add_action_binding("grab", "/user/hand/right/input/grip/value")
action_map.add_action_binding("teleport", "/user/hand/right/input/trigger/value")

# Left Hand
action_map.add_action_binding("grab", "/user/hand/left/input/grip/value")
action_map.add_action_binding("teleport", "/user/hand/left/input/trigger/value")

Here, we’re assigning the “grab” and “teleport” actions to the grip and trigger values on both the left and right hand controllers. These XR-agnostic paths cater to a variety of devices.

Suggesting Controller Bindings

After defining actions and their device inputs, we should suggest these bindings to the XR system to establish a default setup.

func _ready():
    # ... previous code ...

This code suggests the interaction profile “khr/simple_controller”, which corresponds to a basic controller setup. Consult the OpenXR specification for a list of available interaction profiles.

Activating the Action Map

Once the actions and bindings are in place, we need to activate the action map within the XR runtime to start recognizing actions.

func _ready():
    # ... previous code ...

Adding the action map to the `OpenXRServer` makes it active. It’s recommended to do this in the `_ready()` function to ensure all actions are available when the game starts.

Handling Actions in Gameplay

Lastly, we’ll need to handle the actions within our game logic. For that, we can connect signals or poll the state within the process loop.

# Connect 'grab' action signal
func _ready():
    # ... previous code ...
    action_map.connect("action_state_changed", self, "_on_Action_state_changed")

func _on_Action_state_changed(action_name, is_active):
   match action_name:
           if is_active:
               print("Grab action initiated")
               # Handle grab logic
               print("Grab action released")
               # Handle release logic
           # Handle teleport logic

The example demonstrates handling the “grab” action’s change in state. When an action is initiated or released, appropriate gameplay logic is triggered.

By following these steps, we’ve set up a robust framework for managing controller inputs through OpenXRActionMap, forming the foundation for responsive and adaptive XR applications. Coming up, we’ll delve deeper into advanced configurations and interactions, guaranteeing a seamless experience for end-users across a plethora of devices.Let’s advance our understanding of the OpenXRActionMap class by exploring more sophisticated scenarios and code examples.

Advanced Controller Bindings

We’ll start by expanding our action bindings with more intricate controller features, like analog sticks and touchpads.

// Bindings for stick movement on a generic controller
action_map.add_action_binding("move", "/user/hand/right/input/thumbstick")
action_map.add_action_binding("look", "/user/hand/left/input/thumbstick")

// Bindings for a button press on a controller
action_map.add_action_binding("jump", "/user/hand/right/input/button/a/click")
action_map.add_action_binding("crouch", "/user/hand/left/input/button/b/click")

Here, “move” is bound to the right thumbstick’s movement, and “look” to the left thumbstick. “jump” and “crouch” actions are linked to specific buttons through their click input paths.

Handling Analog Input

In XR, analog inputs like thumbsticks return more than just an active/inactive state—you also get a range of values. Handling these requires polling their states within the `_process` loop.

func _process(delta):
    var move_vec2 = action_map.get_action_strength("move")
    var look_vec2 = action_map.get_action_strength("look")

    if move_vec2.length() > 0: 
        print("Moving with vector: ", move_vec2)
        # Handle move logic with move_vec2 values

    if look_vec2.length() > 0:
        print("Looking with vector: ", look_vec2)
        # Handle look logic with look_vec2 values

The `get_action_strength` method gives us a `Vector2` strength value representing the thumbstick’s tilt in two dimensions.

Triggering Haptic Feedback

Haptic feedback is an integral part of immersive experiences. By using our OpenXRActionMap, we can activate haptic feedback on the controller in response to certain gameplay events.

// Trigger haptic feedback on the right controller when 'jump' action is performed
func _on_Action_state_changed(action_name, is_active):
    match action_name:
            if is_active:
                action_map.apply_haptic_feedback("/user/hand/right/output/haptic", 0.5, 1.0, 1000.0)

When the “jump” action is detected, the `apply_haptic_feedback` function sends a vibration to the right controller.

Stopping Haptic Feedback

There might be scenarios where you need to stop the haptic feedback, for example, when an action is completed or interrupted.

// To stop the haptic feedback, we can call the stop_haptic_feedback function
func _on_Action_state_changed(action_name, is_active):
    match action_name:
            if not is_active:
                print("Stopped Jumping")

Here, stopping the haptic feedback as soon as the “jump” action is released ensures the haptics properly reflect the user’s actions.

Listening to Controller Pose Changes

In XR development, tracking the position and orientation (pose) of controllers is vital to many applications.

// Connect a signal to receive changes in the pose of the controller
action_map.connect("pose_action_state_changed", self, "_on_Pose_action_state_changed")

func _on_Pose_action_state_changed(action_name, transform, velocity, angular_velocity):
    if action_name == "teleport":
        print("Controller pose changed to:", transform, "With velocity:", velocity, "And angular velocity:", angular_velocity)

Using the `pose_action_state_changed` signal, we receive updates with the new transform and velocity data whenever the “teleport” action’s pose changes.

Updating the Action Map during Runtime

At times, it’s necessary to modify the action map during runtime, like adding or removing actions and bindings based on in-game events.

// Add a new action and binding at runtime
func add_runtime_action(action_name, action_type, binding):
    action_map.register_action(action_name, action_type)
    action_map.add_action_binding(action_name, binding)

// Example usage:
add_runtime_action("shoot", OpenXRAction.POSE, "/user/hand/right/input/trigger/value")

In this function, we’re dynamically registering a new “shoot” action and binding the trigger input on the right controller to it.

By incorporating these advanced techniques into your toolbox, you’ll be well-equipped to create immersive and responsive VR/AR applications with Godot 4. The OpenXRActionMap class is a powerful ally in managing inputs across a wide range of XR devices, providing a seamless and intuitive user experience. Keep exploring, building, and innovating – and you’ll push the boundaries of what’s possible in XR development.Expanding on the capabilities of OpenXRActionMap allows for an increase in interactivity within your XR projects. We’ll now explore additional functionalities and examples to harness the full potential of user inputs in Godot 4.

Complex Action Combinations

Sometimes, you need to recognize when multiple controls are used together. For example, a “sprint” action may require pushing a thumbstick while holding a button.

// Define a 'sprint' action
action_map.register_action("sprint", OpenXRAction.POSE)

// Bind the sprint action to a combination of thumbstick forward and grip hold
action_map.add_action_binding("sprint", "/user/hand/right/input/grip/value")
action_map.add_action_binding("sprint", "/user/hand/right/input/thumbstick/y")

func _process(delta):
    var thumbstick_y = action_map.get_action_strength("sprint").y
    var grip_value = action_map.get_action_strength("sprint").x

    if thumbstick_y > 0.8 && grip_value > 0.8: 
        # Implement sprint logic here

In this example, sprinting is triggered when both the y-axis of the thumbstick and the grip strength pass a certain threshold. You can adjust these values to fine-tune the sprinting action’s sensitivity.

Gesture Recognition

XR experiences can be enhanced by recognizing user gestures. Here we’ll demonstrate how to use OpenXRActionMap to recognize a simple swipe gesture on a touchpad.

// Register a 'swipe' action
action_map.register_action("swipe", OpenXRAction.POSE)

// Bind the swipe action to a touchpad axis
action_map.add_action_binding("swipe", "/user/hand/right/input/trackpad/x")

var last_trackpad_x_value = 0.0

func _process(delta):
    var current_trackpad_x_value = action_map.get_action_strength("swipe").x
    var delta_x_value = current_trackpad_x_value - last_trackpad_x_value
    last_trackpad_x_value = current_trackpad_x_value

    if delta_x_value > 0.5:
        print("Swiped right")
        # Handle right swipe gesture
    elif delta_x_value < -0.5:
        print("Swiped left")
        # Handle left swipe gesture

Tracking the change in the x-axis value of the trackpad determines the direction of the swipe. Gesture thresholds can be adjusted for sensitivity.

Dynamic Binding Adjustments

Throughout gameplay, you may find the need to dynamically adjust bindings, such as when switching interaction modes or user preferences.

// Function to update binding for the 'move' action
func update_move_binding(new_binding):
    action_map.remove_action_binding("move", "/user/hand/right/input/thumbstick")
    action_map.add_action_binding("move", new_binding)

// Example usage:

Removing the thumbstick binding for “move” and replacing it with a trackpad input allows for flexible user customization.

Accessing Current Controller State

Gathering information on the current state of the controller can be essential for certain gameplay mechanics or UI interactions.

// Function to check if the controller is currently vibrating
func is_controller_vibrating(hand_path):
    return action_map.is_haptic_running(hand_path)

// Example usage:
var right_hand_vibrating = is_controller_vibrating("/user/hand/right/output/haptic")
print("Right hand is vibrating: ", right_hand_vibrating)

Using the `is_haptic_running` method, we can determine if haptic feedback is currently active on a specified controller.

Resetting the Action Map

In some cases, such as when loading a new level or resetting the interaction context, you may want to reset the action map to its default state.

// Function to clear all actions and start fresh
func reset_action_map():

// Example usage:
// Now reconfigure the action map as needed

The `clear_actions` method removes all actions and bindings, giving you a clean slate.

By integrating these examples into your XR projects in Godot 4, you are equipped to create a more interactive and immersive environment. As you continue to experiment with the OpenXRActionMap, keep in mind the user experience—robust input systems are not only versatile but also intuitive for the end user. Being able to dynamically adapt to your user’s needs will set your XR application apart, making it as accessible and enjoyable as possible.

Continuing Your XR Development Journey with Godot

Embarking on the path of XR development can be a thrilling adventure, and diving into OpenXRActionMap in Godot 4 is just the beginning. As you continue to explore the diverse landscape of game development, we encourage you to further your learning with our comprehensive Godot Game Development Mini-Degree. Offering a plethora of courses designed to bolster your development skills, our Mini-Degree is perfect for both newcomers eager to craft their first game and seasoned developers aspiring to refine their expertise.

Our curriculum spans various facets of game creation, from the essentials of 2D and 3D design to advanced gameplay mechanics and control systems—ensuring a well-rounded educational experience. Godot’s supportive and passionate community, alongside its open-source and free-to-use nature, makes it a prime choice for developers of all levels.

For those keen to explore a broader range of Godot topics, our collection of Godot courses awaits you. With Zenva, you can tailor your education to your interests and needs, learn at your own pace, and build a portfolio that showcases your abilities. Continue your journey, unlock new potentials, and transform your passion into creation with Zenva’s extensive learning resources.


Mastering OpenXRActionMap and delving into the nuances of XR development with Godot 4 are significant milestones in any developer’s journey. Embark on the creation of intuitive and interactive experiences that captivate your audience. Whether you aim to pioneer innovative games or contribute to the ever-expanding XR ecosystem, the knowledge and skills you’ve gathered here are invaluable assets.

Keep the momentum going and level up your game development prowess with our Godot Game Development Mini-Degree. Let each lesson propel you forward, and each project you undertake sharpen your mastery. At Zenva, we’re excited to see the worlds you’ll create and the experiences you’ll bring to life. The next chapter of your developer story is just waiting to be written!

Python Blog Image

FINAL DAYS: Unlock coding courses in Unity, Godot, Unreal, Python and more.