Class BhapticsLibrary

class BhapticsLibrary contains the functions for using haptic devices from bHaptics.

References

Path: Assets\Bhaptics\SDK2\Scripts\Core\Plugins\BhapticsLibrary.cs

Static Functions — Play Event-driven Haptic

Play the haptic patterns bound to specific haptic event made from Designer/Portal. We highly recommend to use these functions.

Play

public static int Play(string eventId, int startMillis = 0, float intensity = 1f, float duration = 1.0f, float angleX = 0.0f, float offsetY = 0.0f);

Play haptic event, with adjusting the strength, duration, and direction of the haptic.

Parameters

string eventId: Name of haptic event which you want to play.
int startMillis: Playback start position in milliseconds. The first startMillis milliseconds of the event are skipped (this is a start offset, not a delay before playback). The default is 0. Windows/macOS/Android only.
float intensity: The haptic intensity is multiplied by this value.
float duration: The haptic duration is multiplied by this value.
float angleX: Rotate haptic counterclockwise around the global Vector3.up. Valid range is: [0.0f - 360.0f]
float offsetY: Move haptic up or down. Valid range is: [-0.5f - 0.5f]

Returns

Request ID. You can use the request ID to stop the haptic. It returns -1 if the return fails.

However, when connected to the Hub, failed calls do not return -1 because the Hub does not provide a return value.

Example

using Bhaptics.SDK2;

public class Example : MonoBehaviour
{
    private void OnShoot()
    {
        // Assume the event name is "shootpistol"

        // BASIC USAGE
        BhapticsLibrary.Play(BhapticsEvent.SHOOTPISTOL);
        // or
        BhapticsLibrary.Play("shootpistol");

        // ADVANCED USAGE
        BhapticsLibrary.Play(
            BhapticsEvent.SHOOTPISTOL, // Haptic name
            0,      // Playback start position (millisecond)
            1.0f,   // Haptic intensity
            1.0f,   // Haptic duration
            20.0f,  // Rotate haptic around global Vector3.up (0f - 360f)
            0.3f    // Move haptic up or down (-0.5f - 0.5f)
        );
    }
}

PlayParam

public static int PlayParam(string eventId, float intensity = 1.0f, float duration = 1.0f, float angleX = 0.0f, float offsetY = 0.0f);

Play haptic event, with adjusting the strength, duration, and direction of the haptic.

Parameters

string eventId: Name of haptic event which you want to play.
float intensity: The haptic intensity is multiplied by this value.
float duration: The haptic duration is multiplied by this value.
float angleX: Rotate haptic counterclockwise around the global Vector3.up. Valid range is: [0.0f - 360.0f]
float offsetY: Move haptic up or down. Valid range is: [-0.5f - 0.5f]

Returns

Request ID. You can use the request ID to stop the haptic. It returns -1 if the return fails.

However, when connected to the Hub, failed calls do not return -1 because the Hub does not provide a return value.

Example

using Bhaptics.SDK2;

public class Example : MonoBehaviour
{
    private void OnShoot()
    {
        BhapticsLibrary.PlayParam(
            BhapticsEvent.SHOOTPISTOL, // Haptic name
            1.0f,   // Haptic intensity
            1.0f,   // Haptic duration
            20.0f,  // Rotate haptic around global Vector3.up (0f - 360f)
            0.3f    // Move haptic up or down (-0.5f - 0.5f)
        );
    }
}

PlayAngle

public static int PlayAngle(string eventId, float angleX, float offsetY);

Play haptic event, with adjusting the direction of the haptic. This is a convenience wrapper around PlayParam with intensity and duration fixed at 1.0f.

Parameters

string eventId: Name of haptic event which you want to play.
float angleX: Rotate haptic counterclockwise around the global Vector3.up. Valid range is: [0.0f - 360.0f]
float offsetY: Move haptic up or down. Valid range is: [-0.5f - 0.5f]

Returns

Request ID. You can use the request ID to stop the haptic. It returns -1 if the return fails.

However, when connected to the Hub, failed calls do not return -1 because the Hub does not provide a return value.

PlayLoop

public static int PlayLoop(
    string eventId,
    float intensity = 1.0f,
    float duration = 1.0f,
    float angleX = 0.0f,
    float offsetY = 0.0f,
    int interval = 200,
    int maxCount = 999999
);

Play the haptic repeatedly. Additionally, like the function PlayHapticWithOption, you can adjust the strength, duration, and direction of the haptic.

Parameters

string eventId: Name of haptic event which you want to play.
float intensity: The haptic intensity is multiplied by this value.
float duration: The haptic duration is multiplied by this value.
float angleX: Rotate haptic counterclockwise around the global Vector3.up. Valid range is: [0.0f - 360.0f]
float offsetY: Move haptic up or down. Valid range is: [-0.5f - 0.5f]
int interval: The time interval between loops, measured in milliseconds.
int maxCount: The number of loops.

Returns

Request ID. You can use the request ID to stop the haptic. It returns -1 if the return fails.

However, when connected to the Hub, failed calls do not return -1 because the Hub does not provide a return value.

Example

using Bhaptics.SDK2;

public class Example : MonoBehaviour
{
    private void OnShoot()
    {
        BhapticsLibrary.PlayLoop(
            BhapticsEvent.SHOOTPISTOL, // Haptic name
            1.0f,   // Haptic intensity
            1.0f,   // Haptic duration
            20.0f,  // Rotate haptic around global Vector3.up (0f - 360f)
            0.3f,   // Move haptic up or down (-0.5f - 0.5f)
            200,    // Loop interval time (millisecond)
            999999  // Loop count
        );
    }
}

PlayLoopOnly

public static int PlayLoopOnly(string eventId, int interval = 200, int maxCount = 999999);

Play the haptic repeatedly. This is a convenience wrapper around PlayLoop with intensity and duration fixed at 1.0f and no directional adjustment.

Parameters

string eventId: Name of haptic event which you want to play.
int interval: The time interval between loops, measured in milliseconds.
int maxCount: The number of loops.

Returns

Request ID. You can use the request ID to stop the haptic. It returns -1 if the return fails.

However, when connected to the Hub, failed calls do not return -1 because the Hub does not provide a return value.

Static Functions — Play Haptic Directly

If you want to play haptics without creating a new event, use these functions.

PlayMotors

public static int PlayMotors(int position, int[] motors, int durationMillis);

Play haptic feedback on the specific haptic actuator. You can use this function without creating an event.

Parameters

int position: Type of haptic device. For more information, please refer here.

Value	Device	Same as...	Motors Count
`0`	TactSuit Pro	`PositionType.Vest`	32
`1`	TactSleeve(Left)	`PositionType.ForearmL`	3
`2`	TactSleeve(Right)	`PositionType.ForearmR`	3
`3`	TactVisor	`PositionType.Head`	4
`4`	Tactosy for Hands(Left)	`PositionType.HandL`	3
`5`	Tactosy for Hands(Right)	`PositionType.HandR`	3
`6`	Tactosy for Feet(Left)	`PositionType.FootL`	3
`7`	Tactosy for Feet(Right)	`PositionType.FootR`	3
`8`	TactGlove(Left)	`PositionType.GloveL`	8
`9`	TactGlove(Right)	`PositionType.GloveR`	8

int[] motors: Assign the length of the array by the number of motors for device. Values in the array means motors' intensity. Valid range for each value in the array is: [0 - 100]
int durationMillis: The duration of haptic, measured in millisecond. Greater than or equal to 100 is recommended.

Returns

Request ID. You can use the request ID to stop the haptic. It returns -1 if the return fails.

However, when connected to the Hub, failed calls do not return -1 because the Hub does not provide a return value.

Example

using Bhaptics.SDK2;

public class Example : MonoBehaviour
{
    private void OnCall()
    {
        // TactSuit Pro has 32 motors, so length of array should be 32 too.
        int[] MotorValueArray = new int[] {
            50, 40, 30, 20, 10, 50, 40, 30,
            50, 40, 30, 20, 10, 50, 40, 30,
            50, 40, 30, 20, 10, 50, 40, 30,
            50, 40, 30, 20, 10, 50, 40, 30,
        };

        BhapticsLibrary.PlayMotors(
            (int)PositionType.Vest, // Device type
            MotorValueArray,        // Haptic intensities
            500                     // Haptic duration (millisecond)
        );
    }
}

PlayWaveform

public static int PlayWaveform(
    PositionType positionType,
    int[] motorValues,
    GlovePlayTime[] playTimeValues,
    GloveShapeValue[] shapeValues,
    int frequency = 80,
    int repeatCount = 0
);

TactGlove Only. Play haptics in TactGlove. Unlike using PlayMotors, you can finely adjust haptic duration and vibration intensity changes. This allows for even finer expression of haptic feedback.

Each array (motorValues, playTimeValues, shapeValues) must have six elements for TactGlove DK2 or eight elements for TactGlove DK3, and all three arrays must have the same length. Any other length returns -1.

Parameters

PositionType positionType: Type of haptic device.

Value Device Same as…
PositionType.GloveL TactGlove(Left) 8
PositionType.GloveR TactGlove(Right) 9

Value	Device	Same as…
`PositionType.GloveL`	TactGlove(Left)	`8`
`PositionType.GloveR`	TactGlove(Right)	`9`

int[] motorValues: An array representing the intensity of each motor. Its length must match the number of motors in the TactGlove: six (TactGlove DK2) or eight (TactGlove DK3). The palm motors at array indices 6 and 7 (in the table below) exist on DK3 only. Valid range for each value in the array is: [0 - 100]

Array Index	Motor is positioned at…
`0`	Tip of the thumb
`1`	Tip of the index finger
`2`	Tip of the middle finger
`3`	Tip of the ring finger
`4`	Tip of the little finger
`5`	On the wrist
`6`	On the palm (thumb side)
`7`	On the palm (little finger side)

GlovePlayTime[] playTimeValues: An array with the same length as motorValues (six for DK2, eight for DK3), each representing a time interval for actuation, with time defined using GlovePlayTime enums.

Value Duration Same as…
GlovePlayTime.None None 0
GlovePlayTime.FiveMS 5ms 1
GlovePlayTime.TenMS 10ms 2
GlovePlayTime.TwentyMS 20ms 4
GlovePlayTime.ThirtyMS 30ms 6
GlovePlayTime.FortyMS 40ms 8

Value	Duration	Same as…
`GlovePlayTime.None`	None	`0`
`GlovePlayTime.FiveMS`	5ms	`1`
`GlovePlayTime.TenMS`	10ms	`2`
`GlovePlayTime.TwentyMS`	20ms	`4`
`GlovePlayTime.ThirtyMS`	30ms	`6`
`GlovePlayTime.FortyMS`	40ms	`8`

GloveShapeValue[] shapeValues: An array with the same length as motorValues (six for DK2, eight for DK3), each representing the forms of haptic intensity changes over time, specified by the GloveShapeValue enums.

Value	Waveform	Same as…
`GloveShapeValue.Constant`	Constant intensity for the duration	`0`
`GloveShapeValue.Decreasing`	Starts at the specified intensity and decreases by half	`1`
`GloveShapeValue.Increasing`	Starts at half of the specified intensity and increases to the specified one.	`2`

[TactGlove DK3] On the DK3 glove, the wrist actuator (array index 5) is a voice-coil motor (VCM) and does not reflect shapeValues. The other seven motors apply the waveform shape the same as on DK2 gloves.

int frequency: [TactGlove DK3 only] Vibration frequency in Hz of the DK3 glove's own actuators. The default is 80. This affects only the DK3 glove itself and does not change the operating frequency of any other connected device. It has no effect on DK2 gloves or on the universal (non-Windows/macOS) path. Windows/macOS only.
int repeatCount: Number of times to repeat the waveform, from 1. 0 plays it once. Windows/macOS only.

Returns

Request ID. You can use the request ID to stop the haptic. It returns -1 if the return fails.

However, when connected to the Hub, failed calls do not return -1 because the Hub does not provide a return value.

Example

using Bhaptics.SDK2;

public class TestHaptic : MonoBehaviour
{
    public void OnCall()
    {
        int[] motorValues = new int[8] { 50, 80, 100, 0, 0, 0, 0, 0 };

        GlovePlayTime[] playTimeValues = new GlovePlayTime[8] {
            GlovePlayTime.FiveMS, GlovePlayTime.TwentyMS,
            GlovePlayTime.ThirtyMS, GlovePlayTime.None,
            GlovePlayTime.None, GlovePlayTime.None,
            GlovePlayTime.None, GlovePlayTime.None
        };

        GloveShapeValue[] shapeValues = new GloveShapeValue[8] {
            GloveShapeValue.Constant, GloveShapeValue.Decreasing,
            GloveShapeValue.Increasing, GloveShapeValue.Constant,
            GloveShapeValue.Constant, GloveShapeValue.Constant,
            GloveShapeValue.Constant, GloveShapeValue.Constant
        };

        BhapticsLibrary.PlayWaveform(
            PositionType.GloveL,    // Device Type
            motorValues,            // Intensities
            playTimeValues,         // Intervals
            shapeValues             // Intensity changing forms
        );
    }
}

PlayPath

public static int PlayPath(
    int position,
    float[] xValues,
    float[] yValues,
    int[] intensityValues,
    int duration
);

Play haptic around specific coordinates. Unlike PlayMotors function, which specifies the haptic intensity for each haptic actuator individually, this method specify the haptic intensity for particular coordinates.

When specifying haptic position, PlayMotors offers discrete control, while PlayPath is more continuous. PlayMotors assigns intensity to individual actuators, whereas PlayPath allows intensity specification for specific coordinates (between 0 and 1 for both X and Y axis), causing nearby actuators to vibrate accordingly.

You can put multiple coordinates with multiple intensities. Note that all actuators around these coordinates in the array will activate simultaneously (at the same time), not sequentially. Moreover, the size of all arrays must be the same.

By continuously calling this function while gradually changing the values, you can achieve the effect of a moving haptic point.

[TactGlove DK3] PlayPath does not drive the wrist voice-coil motor (VCM) on a DK3 glove.

Frame 82.png

Parameters

int position: Type of haptic device.

Value	Device	Same as...
`0`	TactSuit Pro	`PositionType.Vest`
`1`	TactSleeve(Left)	`PositionType.ForearmL`
`2`	TactSleeve(Right)	`PositionType.ForearmR`
`3`	TactVisor	`PositionType.Head`
`4`	Tactosy for Hands(Left)	`PositionType.HandL`
`5`	Tactosy for Hands(Right)	`PositionType.HandR`
`6`	Tactosy for Feet(Left)	`PositionType.FootL`
`7`	Tactosy for Feet(Right)	`PositionType.FootR`
`8`	TactGlove(Left)	`PositionType.GloveL`
`9`	TactGlove(Right)	`PositionType.GloveR`

float[] xValues: Assign X coordinate. Valid range for each value in the array is: [0.0f - 1.0f]
float[] yValues: Assign Y coordinate. Valid range for each value in the array is: [0.0f - 1.0f]
int[] intensityValues: Assign the length of the array by the number of coordinate. Values in the array means coordinates' intensity. Valid range for each value in the array is: [0 - 100]
int duration: The duration of haptic, measured in millisecond. Greater than or equal to 100 is recommended.

Returns

Request ID. You can use the request ID to stop the haptic. It returns -1 if the return fails.

However, when connected to the Hub, failed calls do not return -1 because the Hub does not provide a return value.

Example

using Bhaptics.SDK2;

/* Assumption:
    - For TactSuit Pro
    - Coordinate with Intensity
    - (X: 0.1, Y: 0.2) Intensity 40
    - (X: 0.3, Y: 0.4) Intensity 80
    - (X: 0.5, Y: 0.6) Intensity 10
  - Duration 500ms(=0.5 second)
*/
public class TestHaptic : MonoBehaviour
{
    public void OnCall()
    {
        BhapticsLibrary.PlayPath(
            (int)PositionType.Vest,           // Device type
            new float[] { 0.1f, 0.3f, 0.5f }, // X Coordinates
            new float[] { 0.2f, 0.4f, 0.6f }, // Y Coordinates
            new int[] { 40, 80, 10 },         // Intensities
            500                               // Duration
        );
    }
}

Static Functions — Others

using Bhaptics.SDK2;

public class TestHaptic : MonoBehaviour
{
    public void OnCall()
    {
        int requestID = BhapticsLibrary.Play("TestHaptic");

        if (BhapticsLibrary.IsPlayingByEventId("TestHaptic"))
        {
            BhapticsLibrary.StopByEventId("TestHaptic");
        }

        if (BhapticsLibrary.IsPlayingByRequestId(requestID))
        {
            BhapticsLibrary.StopInt(requestID);
        }

        if (BhapticsLibrary.IsPlaying())
        {
            BhapticsLibrary.StopAll();
        }
    }
}

StopByEventId

public static bool StopByEventId(string eventId)

Stop the haptic event by Event ID. Returns whether the stop was successful.

StopInt

public static bool StopInt(int requestId)

Stop the Haptic Event by using the Request ID from the return of the function that executes the haptic. Returns whether the stop was successful.

StopAll

public static bool StopAll()

Stops all haptic currently playing. Returns whether the stop was successful.

IsPlaying

public static bool IsPlaying()

Check if any haptic is currently playing.

IsPlayingByEventId

public static bool IsPlayingByEventId(string eventId)

Check if the haptic event for this Event ID is currently playing.

IsPlayingByRequestId

public static bool IsPlayingByRequestId(int requestId)

Check if the haptic event for this Request ID is currently playing.

PauseByEventId

public static void PauseByEventId(string eventId)

Pauses an active haptic event. Use PauseByEventId(string eventId) to pause a specific haptic event. The paused event can later be resumed using ResumeByEventId(string eventId).

ResumeByEventId

public static void ResumeByEventId(string eventId)

Resumes a paused haptic event. Use ResumeByEventId(string eventId) to resume playback from the position it was paused at.

References​

Static Functions — Play Event-driven Haptic​

Play​

Parameters​

Returns​

Example​

PlayParam​

Parameters​

Returns​

Example​

PlayAngle​

Parameters​

Returns​

PlayLoop​

Parameters​

Returns​

Example​

PlayLoopOnly​

Parameters​

Returns​

Static Functions — Play Haptic Directly​

PlayMotors​

Parameters​

Returns​

Example​

PlayWaveform​

Parameters​

Returns​

Example​

PlayPath​

Parameters​

Returns​

Example​

Static Functions — Others​

StopByEventId​

StopInt​

StopAll​

IsPlaying​

IsPlayingByEventId​

IsPlayingByRequestId​

PauseByEventId​

ResumeByEventId​

References

Static Functions — Play Event-driven Haptic

Play

Parameters

Returns

Example

PlayParam

Parameters

Returns

Example

PlayAngle

Parameters

Returns

PlayLoop

Parameters

Returns

Example

PlayLoopOnly

Parameters

Returns

Static Functions — Play Haptic Directly

PlayMotors

Parameters

Returns

Example

PlayWaveform

Parameters

Returns

Example

PlayPath

Parameters

Returns

Example

Static Functions — Others

StopByEventId

StopInt

StopAll

IsPlaying

IsPlayingByEventId

IsPlayingByRequestId

PauseByEventId

ResumeByEventId