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);

Play the haptic event. It is the most basic way to call a haptic event. It has the lowest overhead of any haptic event-calling function.

Parameters

string eventId: Name of haptic event which you want to play.

Returns

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

Example

using Bhaptics.SDK2;

public class Example : MonoBehaviour
{
    private void OnShoot()
    {
        // Assume the event name is "shootpistol"
        BhapticsLibrary.Play(BhapticsEvent.SHOOTPISTOL);
        // or
        BhapticsLibrary.Play("shootpistol");
    }
}

PlayParam

public static int PlayParam(string eventId, float intensity, float duration, float angleX, float offsetY);

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.

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)
        );
    }
}

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.

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
        );
    }
}

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.

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

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: [1 - 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.

Example

using Bhaptics.SDK2;

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

        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
);

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 must have six elements, and at least one element is required to work.

Parameters

PositionType positionType: Type of haptic device.

Value Device Same as…
PositionType.GloveL TactGlove(Left) 8
PositionType.GloveR TactGlove(Right) 9
int[] motorValues: An array consisting of six elements, each representing the intensity of a motor. The array must have a length of six, as there are six motors in one TactGlove. Valid range for each value in the array is: [1 - 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
GlovePlayTime[] playTimeValues: An array consisting of six elements, 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	Device	Same as…
`PositionType.GloveL`	TactGlove(Left)	`8`
`PositionType.GloveR`	TactGlove(Right)	`9`

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

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 consisting of six elements, 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`

Returns

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

Example

using Bhaptics.SDK2;

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

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

        GloveShapeValue[] shapeValues = new GloveShapeValue[6] {
            GloveShapeValue.Constant, GloveShapeValue.Decreasing, 
            GloveShapeValue.Increasing, 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.

Frame 82.png

Parameters

int position: Type of haptic device.

Value	Device	Same as…
`0`	TactSuit	`PositionType.Vest`
`1`	Tactosy for Arms(Left)	`PositionType.ForearmL`
`2`	Tactosy for Arms(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: [1 - 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.

Example

using Bhaptics.SDK2;

/* Assumption:
    - For TactSuit
    - 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.

References​

Static Functions — Play Event-driven Haptic​

Play​

Parameters​

Returns​

Example​

PlayParam​

Parameters​

Returns​

Example​

PlayLoop​

Parameters​

Returns​

Example​

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​

References

Static Functions — Play Event-driven Haptic

Play

Parameters

Returns

Example

PlayParam

Parameters

Returns

Example

PlayLoop

Parameters

Returns

Example

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