You can integrate your .haptic files, exported from Haptics Studio, by dropping them into your Content Drawer in Unreal. This creates a Haptic Clip .uasset file that you can use to play back haptic feedback in your project.

Controlling Haptics

The Haptics SDK provides a high-level API for playing haptic clips. The SDK includes features such as playback priority, looping, and modulation, which allow you to fine-tune the haptic experience. In the context of the Haptics SDK for Unreal, haptics control is achieved through Haptic Clip assets and the Haptics Player Component.

For the complete API, see the MetaXR Haptics Player Component reference. Make sure to select the version you are using from the drop-down menu in the left panel.

The Haptics Player Component

A MetaXR Haptics Player Component is an actor component⁠ that plays back a Haptic Clip on a specific controller (left, right, or both). It has properties such as priority, amplitude, and frequency shift, and can be used to customize the playback experience.

All available functions in the MetaXR Haptics Player Component can be called from Blueprints or C++.

Amplitude

Amplitude refers to the strength or intensity of the vibration. It is a parameter controlling how much force the actuator (the component that generates the haptic feedback) generates through vibrations. When playing back a haptic clip in Unreal, the amplitude of the vibration can be adjusted using the Amplitude property on the Haptics Player Component. You can set it to a specific value or adjust it dynamically at runtime.

Frequency

Frequency refers to the speed at which the actuator vibrates. A higher frequency value results in a faster vibration, while a lower frequency value results in a slower vibration. The frequency of a haptic clip can also be adjusted using the FrequencyShift property on the Haptics Player Component. This allows you to create haptic effects that change frequency over time, such as a vibration that starts slowly and gradually increases in speed. By adjusting these properties, you can create a wide range of haptic effects.

Create a Haptics Player Component

The MetaXR Haptics Player Component is used to play back haptic clips. You can create a Haptics Player Component in two different ways:

Add it as a new component on an Actor: Create a new Blueprint class, go to the Components tab, click Add, and search for Meta XR Haptics Player Component.

Instantiate it with the Spawn Haptics Player Component Blueprint node: In your Blueprint’s Event Graph, right-click and search for Spawn Haptics Player Component.

Add MetaXR Haptics Player Component as a new component on an Actor, or instantiate it with the Spawn Haptics Player Component Blueprint node

To select the .haptic clip that this player will play, you need to set the Haptic Clip property. All your imported clips are displayed.

Control haptic playback

Once you have a Haptics Player Component created, you can call the Play() function to play the haptic clip on the previously defined controller (left, right, or both). You can either let the playback finish on its own, or call Stop() to end playback early. To swap out the clip used by a Haptics Player Component, change the Haptic Clip property and assign a new clip to be played back. The next image contains an example of spawning a Haptics Player Component at runtime and then starting playback.

Example of spawning and playing a MetaXR Haptics Player Component at runtime.

The Play() function can also be called from a previously added Haptics Player Component:

The Play() function can also be called from previously added MetaXR Haptics Player Components.

You can also modify the properties of the Haptics Player Component before calling Play() using the PlayWithInputs() function. This also stores the new values in the component:

You can also modify the properties of the MetaXR Haptics Player Component before calling Play() using the PlayWithInputs() function.

Finally, you can call PlayOnController(), which plays on the specified controller:

Playback priority

Only one Haptics Player Component can trigger vibrations on each controller at a given moment. If you have multiple players set to play on the same controller at the same time, then only the player with the highest priority triggers vibrations. If the players have the same priority, the player started last triggers vibrations. You can set a player’s priority with the Priority property.

When a Haptics Player Component starts playback, it interrupts a currently active player of the same or lower priority. Once the player finishes playback, the player with the next highest priority resumes triggering vibrations.

Loop haptics

Use the bIsLooping property to enable or disable looping of clip playback. You can set this property before or during playback. Looped playback continues indefinitely until you call Stop().

Modulate haptics

To modulate haptics, you can use the Amplitude and FrequencyShift properties. These properties allow you to change the strength or frequency of a vibration during playback. You can set these properties before and during playback. By adjusting these properties multiple times during playback, you can change the amplitude and frequency continuously over time.

Here is an example to illustrate how amplitude and frequency modulation can be used on a Haptics Player Component:

Modulating Amplitude and FrequencyShift based on the thumbstick position.

In this example, the Amplitude and FrequencyShift change based on the thumbstick position.

API documentation

The Haptics SDK is provided in the MetaXRHaptics plugin. You can find additional documentation for the APIs in the public header files of the source code, located at MetaXRHaptics\Source\MetaXRHaptics\Public\.

Error handling

Generally, the Haptics SDK for Unreal uses Unreal’s asserts⁠ to guide you away from unintended uses of its API. Such unintended uses include, for example, exceeding the acceptable range of inputs to a function. In these cases, the execution stops with an appropriate message to help you correct the calling code.

Creative use cases

Spatial effects

A spatial effect in haptics creates the illusion that sound or tactile sensations originate from a specific location in three-dimensional space. This technique enhances the realism of virtual environments or multimedia experiences by making it appear as though the feedback is emanating from a distinct point relative to the user.

Panning

Panning is a method used to distribute a signal across a stereo or multi-channel sound field. It is widely used in audio production to manage the perceived location of a sound source within the stereo field, whether left, right, or anywhere in-between. In haptics, it relates to distributing a haptic effect between the two controllers.

Generative haptics

Generative haptics involves creating haptic effects that are dynamically generated in real-time based on algorithms or user interactions. These haptic patterns are adaptable and evolve according to the context or environment, offering a more responsive and immersive experience.

Implementing spatial effects

Distance-based amplitude

Adjust the amplitude of a haptic clip based on the relative distance between the player character and the object or vibration source. As the distance increases, the amplitude decreases, mimicking the natural decrease in intensity. Example: Imagine a player character walking away from a vibration source, such as a car with its engine idling.

Creating panning effects

Achieve panning effects by playing the same haptic effect on both controllers and independently modulating the amplitude to simulate movement across the stereo field.

Creating variations

Introduce slight variations in amplitude and frequency modulation for repetitive haptic events like footsteps or gunshots to enhance realism.

Generative haptics

For dynamic scenarios requiring high variation, such as a paintbrush moving across a canvas or a foot pressing a car’s accelerator, generate haptic effects by looping a haptic clip with fixed amplitude and frequency, then modulating playback in real-time based on user input.