Getting Started with Unity SDK
General
This document provides a guide to integrating custom haptic feedback using the Interhaptics Unity SDK. Haptics can be included through premade components or APIs. Here is the list of available methods:
Articles
- How to Play Haptics
- Simple Haptic Effects: Describe and play simple patterns.
- Advanced Haptic Effects: Modulate the feeling and playback of haptic patterns.
- Play Haptic Effect Assets: Play and define the playback of a .haps assets.
- Haptic Presets: Play haptics effects from a library following Apple guidelines.
- Unity Components: Full control of haptics sources, targets, and playback.
- HapticBodyPart Component
- HapticSource Component
- Intensity Controls
Compatibility
Core SDK
- Razer Sensa™ HD Haptics
- iOS
- Android
- Razer Sensa HD Haptics
- Meta Quest
- OpenXR
- Xinput/GameInput PC Controllers
Platform Extensions for partners
- PlayStation®5
- PlayStation®4
- Nintendo Switch®
Requirements and Set Up
- Unity 2019.4 LTS or higher
To import the Interhaptics SDK into Unity using the Unity Package Manager, follow these steps:
- Open the Unity Package Manager, then click the "+" button in the toolbar. Select "Add package from git URL" from the menu.
- In the text box that appears, enter the URL "https://github.com/Interhaptics/Unity_CoreSDK.git" and click Add.
If the installation is successful, the Interhaptics package will appear in the package list with the git tag.
If you need a previous version you can use the git flags (e.g., https://github.com/Interhaptics/Unity_CoreSDK.git#v1.2.3 -- necessary for the PS5 add-on for example). See platform-specific set up in the documentation.
Interhaptics SDK for Unity is compatible with major audio middleware for games (WWise, FMod).
How to Play Haptics
This section assumes that Interhaptics Core Unity SDK is set up. Interhaptics Core Unity SDK functions are not dependent on the target platform and can be implemented only once for all the target devices.
This section covers the fundamentals and how to trigger haptics. If you do not want to write code, we have premade Unity Components.
To start, include for the Interhaptics.Core namespace to use the haptics functions in your script.
using Interhaptics.Core;
Simple Haptic Effects
1. Play Constant Effect
Play a constant haptic effect. Useful for notifications and learning haptics.
- Use HAR.PlayConstant() to play a haptic effect with constant amplitude.
- Parameters: Amplitude* (between 0 and 1), duration in seconds.
- Usage:
HAR.PlayConstant(1.0, 0.5); // Plays a constant haptic effect with 100% amplitude for 0.5s.
* Amplitude in haptics is like the volume of a sound. It's all about how strong or powerful the vibration feels. Just like turning up the volume makes music louder, increasing the amplitude makes the haptic feedback (the vibrations you feel) stronger.
2. Play Transient*
Play a haptic shock. Use for clicks or rapid effects like machine guns.
- Use HAR.PlayTransient() for rapid haptic feedback based on game events.
- Parameters: Time, Amplitude, Pitch**
- Usage:
HAR.PlayTransient(); // Play a transient effect immediately
HAR.PlayTransient(0.5, 1.0, 1.0); // Play a single transient at 0.5 seconds with the highest pitch. See advanced haptics for pitch explanation. Use 1 to get familiar with it.
* Transients in haptics are sudden changes or spikes in the vibration pattern. Imagine tapping your finger quickly on a table, or a button click. It's a brief, distinct vibration that stands out from a more constant, ongoing vibration pattern.
** See Advanced Haptics for pitch explanation. Use 1.0 to start getting familiar with it.
Advanced Haptic Effects
Understanding Array Structures
Advanced haptic effects are based on parameters coded into array structures. There are two types of array structure:
Amplitude and Pitch* Arrays: Follow a time-value-time-value pattern. Each pair represents a point in time expressed in seconds and its corresponding Amplitude or Pitch expressed between 0 and 1.
Transient Arrays: Use a time-amplitude-pitch-time-amplitude-pitch pattern. Each triplet consists of a time expressed in seconds, an Amplitude value, and a Pitch value. Amplitude and Pitch values are between 0 and 1.
* Pitch is the normalized vibrational frequency between a minimal and maximal frequency. Pitch shapes the feeling of the haptics experience. A low pitch feels rumbly and deep, and a high pitch feels sharp.
1. Simple Haptic Patterns
Modulate the intensity of a vibration with constant pitch. Use this to modulate longer effects like explosion.
- Use HAR.Play() for basic haptic patterns.
- Parameters: Amplitude array, [optional: transient array, intensity, loops, controller side.]
- Usage
HAR.Play(new double[] {0, 1, 1, 0.5, 2, 1}); // plays a vibrations starting at maximum amplitude, decrease at 0.5 at 1 second, and back to 1 at 2 seconds.
2. Play Transients
Plays a pattern of transients. Useful to create rapid patterns like opening a lock.
- Use HAR.PlayTransients() Plays multiple transient haptic effects based on provided triplets of time, amplitude, and pitch.
- Parameters: Transient Array [optional: intensity, loops, controller side]
- Usage:
// A series of transients with decreasing amplitude and constant pitch
double[] transient = {
0.0, 1.0, 0.5,
0.25, 0.75, 0.5,
0.5, 0.5, 0.5,
0.75, 0.25, 0.5
};
HAR.PlayTransients(transient);
3. Complex Patterns
Mix amplitude and transient patterns. Use for example to create an explosion shock with a vibrating tail.
- Combine amplitude and transient arrays with HAR.Play() to play complex haptic patterns. Use the same function used in the basic pattern, and add the Transient array after the Amplitude array.
- Parameters: Amplitude array, transient array [optional: intensity, loops, controller side.]
- Usage:
// Amplitude array as time amplitude pairs
double[] amplitude = {
0.0, 0.5,
2.0, 0.5,
};
// Transients expressed as time amplitude pitch triplets
double[] transient = {
0.5, 1, 0.5,
1.5, 0.75, 0.5
};
HAR.Play(amplitude, transient, 1.0, 1, LateralFlag.Left); //Plays the complex pattern described by the arrays 2 times at intensity one on the left side. See Intensity Controls
4. Parametric Haptic Effects
Mix Amplitude and Transient patterns, and modulate the pitch of the effect. Use to change the feeling of haptics from rumbling to sharp and create variance in the effects.
- Use HAR.PlayAdvanced() to fine-tune Amplitude, Pitch, and Transient parameters.
- Parameters Amplitude array, Pitch array, Transient array, [Optional: Frequency Min/Max*, Intensity, Loops, controller side]
- Usage:
// Amplitude at 0.5 between 0 and 2 seconds
double[] amplitudes = {
1.0, 0.5,
3.0, 0.5
};
// pitch between 0 and 1
double[] pitch = {
1.0, 1.0,
3.0, 0.0
};
HAR.PlayAdvanced(amplitudes, pitch); //Plays a constnt haptic effect with increasing pitch, form rumbly to sharp
*The default value when non-declared of Frequency Min and Frequency Max are respectively 65 and 300 Hz corresponding to the variable frequency range of iPhones.
Usage 2: Increasing and decreasing amplitude with a longer tail. The pitch is swiped from max to min back to max to create a "bomb dive" effect with two ticks. The frequency range is expanded to take advantage of specific controller haptics capabilities like DualSense.
// Amplitude array
double[] amplitudes = {
0.0, 0.0,
1.0, 1.0,
2.0, 0.5,
3.0, 0.25,
4.0, 0.25
};
// pitch array
double[] pitch = {
0.0, 1,
2.0, 0,
4.0, 1
};
// transient array
double[] transients = {
0.5, 1, 0.5,
3.5, 0.5, 0.5
};
double _fmin = 30;
double _fmax = 400;
HAR.PlayAdvanced(amplitudes, pitch, _fmin, _fmax, transients);
Play Haptic Effect Assets
The PlayHapticEffect() method is designed for playing haptic effects defined in a haptic effect asset (haps file). The function allows to specifying the playback details of the haptic feedback included in the haps file, such as its intensity, the side of the controller where the effect should occur, and the number of times the effect should loop.
Haps files have larger expressive capabilities compared to Advanced Haptic Effects as they can mix multiple vibrational patterns and define timelines. Haps flies can be edited with the Haptic Composer
Basic usage:
- Create a script like the one below.
- In the Unity Editor, attach your script to a GameObject.
- Assign your haptic effect asset to the myHapticMaterial field in the Inspector. You can find a library of pre made haptic effects in the Interhaptics SDK\Assets\HapticMaterials folder or create your own using the Haptic Composer app.
- Run/Build your scene.
- The haptic effect should play as defined when the scene starts or when triggered.
using UnityEngine;
using Interhaptics.Core;
public class HapticEffectPlayer : MonoBehaviour
{
public HapticMaterial myHapticMaterial; // Assign this in the Unity Inspector
void Start()
{
// Play the haptic effect on start
PlayMyHapticEffect();
}
void PlayMyHapticEffect()
{
if (myHapticMaterial != null)
{
HAR.PlayHapticEffect(myHapticMaterial);
Debug.Log("Haptic effect played successfully!");
}
else
{
Debug.LogError("Haptic material is not assigned!");
}
}
}
Haptic Presets
- Utilize HapticPreset.Play() to play predefined patterns included in the SDK.
- Be sure to include the Interhaptics.Utils namespace (
using Interhaptics.Utils;) - Parameters: PresetType are based on Apple's Human Interface guidelines. Each of these presets (Selection, Light, Medium, Heavy, Rigid, Soft, Success, Failure, Warning) corresponds to a specific set of haptic parameters that define the tactile sensation. These presets are designed to simplify the process of implementing haptic feedback in simple applications. It allows to easily evoke specific tactile experiences such as a light tap (Light), a more intense vibration (Heavy), or a pattern that suggests success.
using Interhaptics.Utils;
void Start()
{
HapticPreset.Play(HapticPreset.PresetType.Success); // Plays a 'Success' haptic pattern
}
Unity Components
The following chapters will detail the process of configuring the main Unity Components.
The SDK includes sample scenes already set up for Controllers, Mobile, and XR. Check our Tutorials section.
Unity components allow full control of the Interhaptics Engine and should be used if the previous methods are insufficient. They include:
- HapticManager, the process managing haptic playback. (Not required after 1.3.0, mandatory until Core SDK 1.2.3)
- HapticBodyParts, targets to play haptics effects. They are components representing haptic devices or controller sides.
- HapticSources, emitters of haptics effects which can be attached to HapticBodyParts.
- GlobalHapticIntensityController, a component managing overall haptic intensity
Haptic Manager Configuration
SDK Version 1.3.0 and Above (11.2023)
Skip this section and go to Haptic Body Part Component.
Do not add the HapticManager component as it has been changed from a Monobehaviour to a static class from this version to include a set of playback features like runtime intensity management and looping.
SDK Versions up to 1.2.3
Begin by creating an empty GameObject in Unity. Add the HapticManager component to this GameObject to manage haptic feedback. The HapticManager can be configured to persist across different scenes if required.
HapticBodyPart Component
The HapticBodyPart components are vital for assigning and managing haptic feedback to different parts of the controller or targeted haptic device.
- Debug Mode and Target Intensity values can be modified at runtime.
- Target Intensity allows modulating the target haptic intensity. The intensity serves as a gain for a playing haptic effect. Target intensity can be applied to Spatial Haptic Sources during trigger/collision interactions.
Specific configurations
PC Controllers (GameInput / XInput), see image below
- Define Body Parts as Hand, Palm, or Index.
- Set the Side orientation to Left, Right, or Global.
- Attach the HapticBodyPart to the player rig if necessary. For Spatial Haptic Sources, ensure the controller has a Box Collider and Rigidbody with gravity disabled.
Mobile Devices (Android / iOS), see image below
- The Body Part should be set to Hand with the Side set to Global.
OpenXR/Meta Quest VR Controllers, see image below
- Similar setup to PC controllers with appropriate attachment to the XR rig.
PS5 DualSense Controllers, see image below
- The Hand is used as the sole Haptic Body Part.
- Adaptive triggers are managed via stiffness perception.
HapticSource Component
Overview of Haptic Sources
Haptic Sources are the core components within the Interhaptics Unity SDK that generate the sensation of touch or vibration in response to events within the game world. These sources provide a bridge between the virtual interactions and the user's sense of touch, offering a range of options to create a rich haptic experience.
Creating a Haptic Source
To create a haptic source:
- Create a standard GameObject in Unity as the emitter of haptic feedback.
- Assign a HapticSource component to this GameObject.
- Assign a haptic effect file to it either by dragging a haptic effect (haps file) or by checking the Use Streaming Assets and assigning the full path of the haps file inside the StramingAssets folder.
- There are four main types of HapticSource components, each tailored for different haptic feedback scenarios.
HapticSource Types
Each HapticSource component corresponds to a specific type of haptic feedback and is designed for certain interactions within the game:
EventHapticSource
EventHapticSource is used to play haptic effects triggered by discrete events, such as the feeling of pressing a button.
It is typically connected to events within the Unity Inspector and uses the PlayEventVibration() method to activate the effect.
SpatialHapticSource
SpatialHapticSource activates haptic feedback in response to spatial events, such as collisions or objects entering a trigger zone.
ParametricHapticSource
ParametricHapticSurce allows more complex haptic patterns that do not require pre-made haptic effects or advanced programming.
This component can interpret and play haptic effects based on parameters like amplitude and pitch over time for continuous haptics and/or transients.
Haptic Effect Parameters
Define continuous haptic parameters, such as amplitude and pitch over time, to create a range of sensations from subtle to strong.
Adjust transient haptic parameters to simulate sudden impacts or bursts of vibration. This is done by adding triplets of time amplitude pitch in the component.
See the Player Control API methods for examples.
AudioHapticSource
AudioHapticSource helps to synchronize haptic feedback with audio signals It enhances the user's immersion by linking sound with haptics.
AudioHapticSource also integrates an AudioSource component for direct association with audio clips.
Configuring HapticSource Components
Each HapticSource offers a variety of settings that can be configured to suit the needs of the application:
Haptic Effect File
Select a haptic effect from a library of pre-existing haptic files (.haps) or create custom haptic effects using the Haptic Composer app. (Download | Documentation)
Custom effects can be designed from scratch or by importing and converting audio files into haptic patterns within the Haptic Composer.
Additional Configuration Options
Vibration Offset: Delay the start of the haptic effect to align with in-game events.
Source Intensity: Manage the intensity of the haptic feedback, with values adjustable between 0 (no intensity) and 2 (maximum intensity). This setting can be changed in real-time to respond to game dynamics (except on mobile where it is updated at the beginning of a new playback).
Debug Mode: Provides real-time logs in the console for debugging purposes, indicating when haptic feedback starts and stops.
Looping: Determine whether the haptic effect should repeat and set conditions for looping, such as the maximum number of loops or a loop time value. The minimum between the maximum number of loops or the loop time will be taken into account.
Play At Start: Specify if the haptic effect should start immediately when the GameObject containing the Haptic Source becomes active, with special consideration for Spatial Haptic Sources (set as false).
Haptic Body Parts Array: Link the haptic source to specific controller areas defined in the HapticBodyPart settings, such as Palm, Index, or Hand, and determine the target side (left, right, or global) for the effect.
Intensity Controls
The GlobalHapticIntensityController class/component is used for adjusting the intensity of haptic feedback.
This class completes Source Intensity controlling the intensity of haptic sources, and target intensity controlling the haptic intensity of body parts.
GlobalHapticIntensityController integrated into a GameObject provides a centralized system to manage haptic feedback.
Global Intensity Adjustment: Modify the strength of haptic effects throughout the game.
UI Integration: Allow players to customize the haptic intensity to their preference via UI components.
Debugging Support: Provide logs for identifying and resolving issues with haptic feedback.
Pause/Resume Functionality: Enable control over haptic feedback during game interruptions through the public methods StopAllHaptics() and ResumeAllHaptics()
Suspend or keep the haptic playback if the app is not in focus -- check (true by default)
