API reference
API reference
Select your platform
No SDKs available
No versions available

Haptics Class

Extends IDisposable
Low-level API for the XR Haptics SDK runtime.
This class is provided where low-level control of the XR Haptics SDK runtime is required. Most applications probably do not require this class and HapticClipPlayer and HapticClip should be used instead.
In a nutshell, it wraps the C# Native SDK bindings of the Oculus.Haptics.Ffi class to be used by C# abstractions. None of the methods here are thread-safe and should only be called from the main (Unity) thread. Calling these methods from a secondary thread can cause undefined behaviour and memory leaks.

Object Data for protected-static-attrib

static Haptics instance[Get]

Properties

Whether PCM haptics are available and enabled for the current runtime.
PCM haptics allow for high-quality haptic feedback. This property indicates whether PCM haptics are supported by the current runtime and whether they are enabled.
Returns the singleton instance of Haptics: either existing or new.
The Haptics class provides access to haptic feedback functionality. This property returns the singleton instance of Haptics,creating a new instance if one does not already exist.

Protected Functions

The constructor is protected to ensure that a class instance cannot be created directly and all consuming code must go through the Instance property. This design pattern ensures a singleton-like behavior, where only one instance of the Haptics class exists throughout the application.
virtual void Dispose
( bool disposing )

Member Functions

Loads haptic data from a JSON string.
Parameters
clipJson
The UTF-8-encoded JSON string containing haptic data (.haptic format).
Returns
A haptic clip ID if the data is parsed successfully; Ffi.InvalidId otherwise.
Exceptions
FormatException
If the format of the haptic clip data is not valid; or the data is not UTF-8 encoded.
Releases ownership of a loaded haptic clip.
Releasing the clip means that the API no longer maintains a handle to the clip. However resources won't be freed until all clip players that are playing the clip have also been destroyed.
Parameters
clipId
The ID of the haptic clip to be released.
Returns
true if the clip was released successfully; false if the clip was already released or the call was unsuccessful.
Creates a haptic clip player.
To play a haptic clip with a created player, the haptic clip must first be loaded using LoadClip(), assigned to the player using SetHapticPlayerClip(), and finally playback is started using PlayHapticPlayer().
Returns
The player ID, if the player was created successfully; Ffi.InvalidId if something went wrong.
Sets the clip that is used by the given player.
If the player is currently playing, it will stop. Other properties like amplitude, frequency shift, looping and priority are kept.The clip must have been previously loaded by calling LoadClip() (see above).
Parameters
playerId
The ID of the clip player.
clipId
The ID of the haptic clip to be released.
Exceptions
ArgumentException
If the player ID was invalid.
ArgumentException
If the clip ID was invalid.
Starts playback on the player with the specified player ID on the specified controller.
Parameters
playerId
The ID of the clip player to start playback on.
controller
The controller to play on. Can be Left, Right or Both controllers.
Exceptions
ArgumentException
If the player ID was invalid.
ArgumentException
If an invalid controller was selected for playback.
InvalidOperationException
If the player has no clip loaded.
Stops playback that was previously started with PlayHapticPlayer().
Parameters
playerId
The ID of the clip player to stop playback on.
Exceptions
ArgumentException
If the player ID was invalid.
InvalidOperationException
If the player has no clip loaded.
Returns the duration of the loaded haptic clip.
Parameters
clipId
The ID of the haptic clip to be queried for its duration.
Returns
The duration of the haptic clip in seconds if the call was successful; 0.0 otherwise.
Exceptions
ArgumentException
If the clip ID was invalid.
Enables or disables a clip player's loop state.
Parameters
playerId
The ID of the clip player.
enabled
true if the clip player should loop; false to disable looping.
Exceptions
ArgumentException
If the player ID was invalid.
Gets a clip player's loop state (if it loops or not).
Parameters
playerId
The ID of the clip player.
Returns
The current loop state, if getting the state was successful, and the default value of false otherwise.
Exceptions
ArgumentException
If the player ID was invalid.
Sets the clip player's amplitude.
Parameters
playerId
The ID of the clip player.
amplitude
A positive integer value for the amplitude of the clip player. All individual amplitudes within the clip are scaled by this value. Each individual value is clipped to one.
Exceptions
ArgumentException
If the player ID was invalid.
ArgumentException
If the amplitude argument is out of range (has to be non-negative).
Get the clip player's amplitude.
Parameters
playerId
The ID of the clip player.
Returns
The current player amplitude, if getting amplitude was successful; and the default value (1.0) otherwise.
Exceptions
ArgumentException
If the player ID was invalid.
Sets the clip player's frequency shift.
Parameters
playerId
ID of the clip player.
amount
A value between -1.0 and 1.0 (inclusive). Values outside this range will cause an exception.
Exceptions
ArgumentException
If the player ID was invalid.
ArgumentException
If the frequency shift amount is out of range.
Gets the clip player's current frequency shift based on it's player ID.
Parameters
playerId
The ID of the clip player.
Returns
The current player frequency shift if getting frequency shift was successful; the default value (0.0) otherwise.
Exceptions
ArgumentException
If the player ID was invalid.
Sets the clip player's current playback priority value based on its player ID. The priority values range from 0 (high priority) to 255 (low priority), with 128 being the default.
Parameters
playerId
ID of the clip player.
value
A value between 0 and 255 (inclusive). Values outside this range will cause an exception.
Exceptions
ArgumentException
If the player ID was invalid.
ArgumentException
If the priority value is out of range.
Gets the clip player's current playback priority value based on its player ID.
Parameters
playerId
The ID of the clip player.
Returns
The current priority value if successful; the default value (128) otherwise.
Exceptions
ArgumentException
If the player ID was invalid.
Releases a clip player that was previously created with CreateHapticPlayer().
Parameters
playerId
ID of the clip player to be released.
Returns
true if release was successful; false if the player does not exist, was already released, or the call was unsuccessful.
Call this to explicitly release the haptics runtime. This method has the haptics runtime released while ensuring that the garbage collector doesn't kick in., which will also result in any loaded HapticClipPlayers and HapticClips being released from memory.
In general, you shouldn't need to explicitly release the haptics runtime as it is intended to run for the duration of your application and gets released via ~Haptics on shutdown. However, if you have a particular reason to release it explicitly, call Dispose() to do so. If you need to use the haptics runtime again after having released it simply create a new HapticClipPlayer and a new runtime will be instantiated implicitly. summary>Releases the haptics runtime and its associated resources.
Did you find this page helpful?
Thumbs up icon
Thumbs down icon
Nav Logo
Virtual reality / Meta Horizon
Virtual reality / Meta Horizon
Virtual reality / Meta Horizon
English (US)
© 2025 Meta