Class UBhapticsSDK2
Hereda de UBlueprintFunctionLibrary
La clase UBhapticsSDK2 contiene las funciones para usar dispositivos hápticos de bHaptics.
Referencias
| Module | BhapticsPlugin |
| Header | Engine\Plugins\Marketplace\BhapticsPlugin\Source\BhapticsPlugin\Public\BhapticsSDK2.h |
| Include | #include "BhapticsSDK2.h" |
Funciones estáticas — Reproducir háptica basada en eventos
Reproduce los patrones hápticos vinculados a eventos hápticos específicos creados desde Designer/Portal. Se recomienda encarecidamente utilizar estas funciones.
PlayHaptic
static int PlayHaptic(FString eventId);
Reproduce el evento háptico. Es la forma más básica de invocar un evento háptico. Tiene la menor sobrecarga de todas las funciones de invocación de eventos hápticos.
Parámetros
FString eventId: Nombre del evento háptico que desea reproducir.
Retorno
Request ID. Puede usar el Request ID para detener la háptica. Devuelve -1 si la llamada falla.
Sin embargo, cuando está conectado al Hub, las llamadas fallidas no devuelven -1 porque el Hub no proporciona un valor de retorno.
Ejemplo
#include "BhapticsSDK2.h"
void AExample::Shoot()
{
// Assuming the event name is "shootpistol"
UBhapticsSDK2::PlayHaptic("shootpistol");
}
PlayHapticWithOption
static int PlayHapticWithOption(FString eventId, float intensity = 1.0f, float duration = 1.0f, float angleX = 0.0f, float offsetY = 0.0f);
Reproduce el evento háptico ajustando la intensidad, la duración y la dirección de la háptica.
Parámetros
FString eventId: Nombre del evento háptico que desea reproducir.float intensity: La Intensity háptica se multiplica por este valor.float duration: La Duration háptica se multiplica por este valor.float angleX: Gira la háptica en sentido antihorario alrededor delVector3.upglobal. Rango válido: [0.0f-360.0f]float offsetY: Mueve la háptica hacia arriba o hacia abajo. Rango válido: [-0.5f-0.5f]
Retorno
Request ID. Puede usar el Request ID para detener la háptica. Devuelve -1 si la llamada falla.
Sin embargo, cuando está conectado al Hub, las llamadas fallidas no devuelven -1 porque el Hub no proporciona un valor de retorno.
Ejemplo
#include "BhapticsSDK2.h"
void AExample::Shoot()
{
UBhapticsSDK2::PlayHapticWithOption(
"shootpistol", // Haptic name
1.0f, // Haptic intensity
1.0f, // Haptic duration
0.0f, // Rotate haptic around global Vector3.up (0f - 360f)
0.0f // Move haptic up or down (-0.5f - 0.5f)
);
}
PlayWithStartTime
static int PlayWithStartTime(FString eventId, int startMillis = 0, float intensity = 1.0f, float duration = 1.0f, float angleX = 0.0f, float offsetY = 0.0f);
Reproduce el evento háptico ajustando la intensidad, la duración y la dirección de la háptica.
Parámetros
FString eventId: Nombre del evento háptico que desea reproducir.int startMillis: Posición de inicio de la reproducción en milisegundos. Los primerosstartMillismilisegundos del evento se omiten (esto es un Offset de inicio, no un retraso antes de la reproducción). El valor predeterminado es0. Solo Windows/macOS/Android.float intensity: La Intensity háptica se multiplica por este valor.float duration: La Duration háptica se multiplica por este valor.float angleX: Gira la háptica en sentido antihorario alrededor delVector3.upglobal. Rango válido: [0.0f-360.0f]float offsetY: Mueve la háptica hacia arriba o hacia abajo. Rango válido: [-0.5f-0.5f]
Retorno
Request ID. Puede usar el Request ID para detener la háptica. Devuelve -1 si la llamada falla.
Sin embargo, cuando está conectado al Hub, las llamadas fallidas no devuelven -1 porque el Hub no proporciona un valor de retorno.
Ejemplo
#include "BhapticsSDK2.h"
void AExample::Shoot()
{
UBhapticsSDK2::PlayWithStartTime(
"shootpistol", // Haptic name
0, // Playback start position (millisecond)
1.0f, // Haptic intensity
1.0f, // Haptic duration
0.0f, // Rotate haptic around global Vector3.up (0f - 360f)
0.0f // Move haptic up or down (-0.5f - 0.5f)
);
}
PlayLoop
static int PlayLoop(FString eventId, float intensity = 1.0f, float duration = 1.0f, float angleX = 0.0f, float offsetY = 0.0f, int interval = 200, int maxCount = 999999);
Reproduce la háptica de forma repetida. Además, al igual que la función PlayHapticWithOption, puede ajustar la intensidad, la duración y la dirección de la háptica.
Parámetros
FString eventId: Nombre del evento háptico que desea reproducir.float intensity: La Intensity háptica se multiplica por este valor.float duration: La Duration háptica se multiplica por este valor.float angleX: Gira la háptica en sentido antihorario alrededor delVector3.upglobal. Rango válido: [0.0f-360.0f]float offsetY: Mueve la háptica hacia arriba o hacia abajo. Rango válido: [-0.5f-0.5f]int interval: Intervalo de tiempo entre bucles, medido en milisegundos.int maxCount: Número de bucles.
Retorno
Request ID. Puede usar el Request ID para detener la háptica. Devuelve -1 si la llamada falla.
Sin embargo, cuando está conectado al Hub, las llamadas fallidas no devuelven -1 porque el Hub no proporciona un valor de retorno.
Ejemplo
#include "BhapticsSDK2.h"
void AExample::Shoot()
{
UBhapticsSDK2::PlayLoop(
"shootpistol", // Haptic name
1.0f, // Haptic intensity
1.0f, // Haptic duration
0.0f, // Rotate haptic around global Vector3.up (0f - 360f)
0.0f, // Move haptic up or down (-0.5f - 0.5f)
200, // Loop interval time (millisecond)
999999 // Loop count
);
}
Funciones estáticas — Reproducir háptica directamente
Si desea reproducir háptica sin crear un nuevo evento, use estas funciones.
PlayDot
static int PlayDot(int position, TArray<int> motorValues, float seconds = 0.5f);
Reproduce retroalimentación háptica en el actuador háptico específico. Puede usar esta función sin crear un evento.
Parámetros
int position: Tipo de dispositivo háptico. Para obtener más información, consulte aquí.Valor Dispositivo Equivale a... Número de motores 0TactSuit Pro EBhapticsDevicePosition::Vest32 1TactSleeve(Left) EBhapticsDevicePosition::ForearmL3 2TactSleeve(Right) EBhapticsDevicePosition::ForearmR3 3TactVisor EBhapticsDevicePosition::Head4 4Tactosy for Hands(Left) EBhapticsDevicePosition::HandL3 5Tactosy for Hands(Right) EBhapticsDevicePosition::HandR3 6Tactosy for Feet(Left) EBhapticsDevicePosition::FootL3 7Tactosy for Feet(Right) EBhapticsDevicePosition::FootR3 8TactGlove(Left) EBhapticsDevicePosition::GloveL8 9TactGlove(Right) EBhapticsDevicePosition::GloveR8 TArray<int> motorValues: Asigne la longitud del array según el número de motores del dispositivo. Los valores del array representan la Intensity de los motores. Rango válido para cada valor del array: [0-100]float seconds: La Duration de la háptica, medida en segundos. Se recomienda un valor mayor o igual a0.1f.
Retorno
Request ID. Puede usar el Request ID para detener la háptica. Devuelve -1 si la llamada falla.
Sin embargo, cuando está conectado al Hub, las llamadas fallidas no devuelven -1 porque el Hub no proporciona un valor de retorno.
Ejemplo
#include "BhapticsSDK2.h"
void AExample::Shoot()
{
// TactSuit Pro has 32 motors, so length of array should be 32 too.
TArray<int> MotorValueArray = TArray<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};
UBhapticsSDK2::PlayDot(
(int)EBhapticsDevicePosition::Vest, // Device type
MotorValueArray, // Haptic intensities
0.5f // Haptic duration (second)
);
}
PlayPath
static int PlayPath(int position, TArray<float> x, TArray<float> y, TArray<int> motorValues, float seconds = 0.5);
Reproduce háptica alrededor de coordenadas específicas. A diferencia de la función PlayDot, que especifica la Intensity háptica para cada actuador háptico individualmente, este método especifica la Intensity háptica para coordenadas particulares.
Al especificar la posición háptica, PlayDot ofrece un control discreto, mientras que PlayPath es más continuo. PlayDot asigna Intensity a actuadores individuales, mientras que PlayPath asigna Intensity a coordenadas específicas (entre 0 y 1 tanto para el eje X como para el Y), lo que hace que los actuadores cercanos vibren en consecuencia.
Puede incluir múltiples coordenadas con múltiples intensidades en el array. Tenga en cuenta que todos los actuadores alrededor de estas coordenadas en el array se activarán simultáneamente (al mismo tiempo), no secuencialmente. Además, el tamaño de todos los arrays debe ser el mismo.
Al llamar a esta función de forma continua mientras se cambian gradualmente los valores, se puede lograr el efecto de un punto háptico en movimiento.
[TactGlove DK3] PlayPath no activa el motor de bobina de voz (VCM) de la muñeca en un guante DK3.

Parámetros
int position: Tipo de dispositivo háptico.Valor Dispositivo Equivale a... 0TactSuit Pro EBhapticsDevicePosition::Vest1TactSleeve(Left) EBhapticsDevicePosition::ForearmL2TactSleeve(Right) EBhapticsDevicePosition::ForearmR3TactVisor EBhapticsDevicePosition::Head4Tactosy for Hands(Left) EBhapticsDevicePosition::HandL5Tactosy for Hands(Right) EBhapticsDevicePosition::HandR6Tactosy for Feet(Left) EBhapticsDevicePosition::FootL7Tactosy for Feet(Right) EBhapticsDevicePosition::FootR8TactGlove(Left) EBhapticsDevicePosition::GloveL9TactGlove(Right) EBhapticsDevicePosition::GloveRTArray<float> x: Asigne la coordenada X. Rango válido para cada valor del array: [0.0f-1.0f]TArray<float> y: Asigne la coordenada Y. Rango válido para cada valor del array: [0.0f-1.0f]TArray<int> motorValues: Asigne la longitud del array según el número de coordenadas. Los valores del array representan la Intensity de las coordenadas. Rango válido para cada valor del array: [0-100]float seconds: La Duration de la háptica, medida en segundos. Se recomienda un valor mayor o igual a0.1f.
Retorno
Request ID. Puede usar el Request ID para detener la háptica. Devuelve -1 si la llamada falla.
Sin embargo, cuando está conectado al Hub, las llamadas fallidas no devuelven -1 porque el Hub no proporciona un valor de retorno.
Ejemplo
#include "BhapticsSDK2.h"
/* 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 0.5 second
*/
void AExample::Shoot()
{
UBhapticsSDK2::PlayPath(
(int)EBhapticsDevicePosition::Vest, // Device Type
TArray<float>{0.1f, 0.3f, 0.5f}, // X Coordinates
TArray<float>{0.2f, 0.4f, 0.6f}, // Y Coordinates
TArray<int>{40, 80, 10}, // Intensities
0.5f // Duration
);
}
PlayWaveform
static int PlayWaveform(int position, TArray<int> motorIntensities, TArray<EBhapticsGlovePlayTime> playTimeValues, TArray<EBhapticsGloveShapeValue> shapeValues, int frequency = 80, int repeatCount = 0);
Solo TactGlove. Reproduce háptica en TactGlove. A diferencia de usar PlayDot, puede ajustar con precisión la Duration háptica y los cambios de Intensity de vibración. Esto permite una expresión aún más detallada de la retroalimentación háptica.
Cada array (motorIntensities, playTimeValues, shapeValues) debe tener seis elementos para TactGlove DK2 u ocho elementos para TactGlove DK3, y los tres arrays deben tener la misma longitud. Cualquier otra longitud devuelve -1.
Parámetros
-
int position: Tipo de dispositivo háptico.Valor Dispositivo Equivale a… 8TactGlove(Left) EBhapticsDevicePosition::GloveL9TactGlove(Right) EBhapticsDevicePosition::GloveR -
TArray<int> motorIntensities: Un array que representa la Intensity de cada motor. Su longitud debe coincidir con el número de motores del TactGlove: seis (TactGlove DK2) u ocho (TactGlove DK3). Los motores de la palma en los índices de array6y7(en la tabla siguiente) solo existen en el DK3. Rango válido para cada valor del array: [0-100]Índice del array El motor está ubicado en… 0Punta del pulgar 1Punta del índice 2Punta del dedo medio 3Punta del dedo anular 4Punta del meñique 5En la muñeca 6En la palma (lado del pulgar) 7En la palma (lado del meñique) -
TArray<EBhapticsGlovePlayTime> playTimeValues: Un array con la misma longitud quemotorIntensities(seis para DK2, ocho para DK3), donde cada elemento representa un intervalo de tiempo de actuación, con el tiempo definido mediante los enumsEBhapticsGlovePlayTime.Valor Duration Equivale a… EBhapticsGlovePlayTime::NoneNinguna 0EBhapticsGlovePlayTime::FiveMS5ms 1EBhapticsGlovePlayTime::TenMS10ms 2EBhapticsGlovePlayTime::TwentyMS20ms 4EBhapticsGlovePlayTime::ThirtyMS30ms 6EBhapticsGlovePlayTime::FortyMS40ms 8 -
TArray<EBhapticsGloveShapeValue> shapeValues: Un array con la misma longitud quemotorIntensities(seis para DK2, ocho para DK3), donde cada elemento representa la forma de los cambios de Intensity háptica a lo largo del tiempo, especificada por los enumsEBhapticsGloveShapeValue.Valor Forma de onda Equivale a… EBhapticsGloveShapeValue::ConstantIntensity constante durante la Duration 0EBhapticsGloveShapeValue::DecreasingComienza con la Intensity especificada y disminuye a la mitad 1EBhapticsGloveShapeValue::IncreasingComienza con la mitad de la Intensity especificada y aumenta hasta la Intensity especificada. 2[TactGlove DK3] En el guante DK3, el actuador de la muñeca (índice de array
5) es un motor de bobina de voz (VCM) y no refleja losshapeValues. Los otros siete motores aplican la forma de onda de la misma manera que en los guantes DK2. -
int frequency: [Solo TactGlove DK3] Frecuencia de vibración en Hz de los actuadores propios del guante DK3. El valor predeterminado es80. Esto afecta únicamente al propio guante DK3 y no cambia la frecuencia de operación de ningún otro dispositivo conectado. No tiene efecto en guantes DK2 ni en la ruta universal (non-Windows/macOS). Solo Windows/macOS. -
int repeatCount: Número de veces que se repite la forma de onda, a partir de1.0la reproduce una vez. Solo Windows/macOS.
Retorno
Request ID. Puede usar el Request ID para detener la háptica. Devuelve -1 si la llamada falla.
Sin embargo, cuando está conectado al Hub, las llamadas fallidas no devuelven -1 porque el Hub no proporciona un valor de retorno.
Ejemplo
#include "BhapticsSDK2.h"
void AExample::Shoot()
{
TArray<int> GloveMotorValue = TArray<int>{50, 50, 50, 50, 50, 50, 50, 50};
TArray<EBhapticsGlovePlayTime> GlovePlayTime = {
EBhapticsGlovePlayTime::FiveMS, EBhapticsGlovePlayTime::TenMS,
EBhapticsGlovePlayTime::TwentyMS, EBhapticsGlovePlayTime::ThirtyMS,
EBhapticsGlovePlayTime::FortyMS, EBhapticsGlovePlayTime::None,
EBhapticsGlovePlayTime::None, EBhapticsGlovePlayTime::None};
TArray<EBhapticsGloveShapeValue> GloveShapeValue = {
EBhapticsGloveShapeValue::Constant, EBhapticsGloveShapeValue::Decreasing,
EBhapticsGloveShapeValue::Increasing, EBhapticsGloveShapeValue::Constant,
EBhapticsGloveShapeValue::Decreasing, EBhapticsGloveShapeValue::Increasing,
EBhapticsGloveShapeValue::Constant, EBhapticsGloveShapeValue::Constant};
UBhapticsSDK2::PlayWaveform(
(int)EBhapticsDevicePosition::GloveL, // Device Type
GloveMotorValue, // Intensities
GlovePlayTime, // Intervals
GloveShapeValue // Intensity changing forms
);
}
Funciones estáticas — Otras
StopHapticByEventId
static bool StopHapticByEventId(FString eventId);
Detiene el evento háptico por Event ID. Devuelve si la detención fue exitosa.
#include "BhapticsSDK2.h"
void AExample::Example()
{
UBhapticsSDK2::StopHapticByEventId("eventID");
}
StopHapticByRequestId
static bool StopHapticByRequestId(int requestId);
Detiene el evento háptico usando el Request ID devuelto por la función que ejecuta la háptica. Devuelve si la detención fue exitosa.
#include "BhapticsSDK2.h"
void AExample::Example()
{
int RequestID = UBhapticsSDK2::PlayHaptic("eventID");
UBhapticsSDK2::StopHapticByRequestId(RequestID);
}
StopHaptic
static bool StopHaptic();
Detiene toda la háptica que se esté reproduciendo actualmente. Devuelve si la detención fue exitosa.
#include "BhapticsSDK2.h"
void AExample::Example()
{
UBhapticsSDK2::PlayHaptic("bangbang");
UBhapticsSDK2::PlayHaptic("eventID");
UBhapticsSDK2::PlayHaptic("explosion");
UBhapticsSDK2::StopHaptic();
}
PauseHapticByEventId
static void PauseHapticByEventId(FString eventId);
Pausa el evento háptico por Event ID. La posición de reproducción se mantiene para poder continuarla más tarde con ResumeHapticByEventId.
#include "BhapticsSDK2.h"
void AExample::Example()
{
UBhapticsSDK2::PauseHapticByEventId("eventID");
}
ResumeHapticByEventId
static void ResumeHapticByEventId(FString eventId);
Reanuda un evento háptico previamente pausado con PauseHapticByEventId, continuando desde la posición donde se pausó.
#include "BhapticsSDK2.h"
void AExample::Example()
{
UBhapticsSDK2::ResumeHapticByEventId("eventID");
}
IsPlaying
static bool IsPlaying();
Comprueba si la háptica se está reproduciendo.
#include "BhapticsSDK2.h"
void AExample::Example()
{
if (UBhapticsSDK2::IsPlaying())
{
StopHaptic();
}
}
IsPlayingByEventId
static bool IsPlayingByEventId(FString eventId);
Comprueba si el evento háptico con este Event ID se está reproduciendo.
#include "BhapticsSDK2.h"
void AExample::Example()
{
UBhapticsSDK2::PlayHaptic("eventID");
if (UBhapticsSDK2::IsPlayingByEventId("eventID"))
{
UBhapticsSDK2::StopHapticByEventId("eventID");
}
}
IsPlayingByRequestId
static bool IsPlayingByRequestId(int requestId);
Comprueba si el evento háptico con este Request ID se está reproduciendo.
#include "BhapticsSDK2.h"
void AExample::Example()
{
int RequestID = UBhapticsSDK2::PlayHaptic("eventID");
if (UBhapticsSDK2::IsPlayingByRequestId(RequestID))
{
UBhapticsSDK2::StopHapticByRequestId(RequestID);
}
}
Initialize
static void Initialize();
Inicializa el entorno háptico. Esta función debe llamarse antes de usar las funciones relacionadas con la háptica.
Ping
static void Ping(FBhapticsDevice device);
Envía retroalimentación háptica simple a un dispositivo determinado.
PingAll
static void PingAll();
Envía retroalimentación háptica simple a todos los dispositivos conectados.
Destroy
static void Destroy();
Destruye el entorno háptico. Esta función debe llamarse cuando el juego finaliza, y debe llamarse UNA SOLA VEZ.
GetBhapticsDevices
static TArray<FBhapticsDevice> GetBhapticsDevices();
Obtiene un array con la información de los dispositivos hápticos conectados.
IsBhapticsAvailable
static bool IsBhapticsAvailable();
Comprueba si el entorno háptico está inicializado y listo para usar las funciones relacionadas con la háptica.
ProjectToVest
static FBhapticsRotationOption ProjectToVest(
FVector ContactLocation,
UPrimitiveComponent* PlayerComponent,
float HalfHeight = 0
);
Función auxiliar para calcular los valores de Offset (ángulo y altura) de un punto de contacto de colisión dado respecto al jugador. Estos valores de Offset pueden usarse en PlayHapticWithOption y PlayLoop, que permiten ajustar la posición háptica.
Esta función asume que la dirección frontal se alinea con la parte delantera del chaleco, y la posición del jugador se considera el origen.
Consulte el ejemplo a continuación para obtener información detallada.
Parámetros
FVector ContactLocation: Punto de contacto en coordenadas globales.UPrimitiveComponent* PlayerComponent: Referencia al componente primitivo adjunto al jugador.float HalfHeight: La mitad de la altura real del jugador, medida en centímetros.
Ejemplo
Supongamos que implementamos la háptica cuando el jugador recibe un disparo en un juego de VR. El patrón háptico correspondiente a este evento sería una retroalimentación háptica corta e intensa en el centro frontal del TactSuit. Para mejorar el realismo, sería ideal variar la altura y el ángulo de la retroalimentación háptica según el lugar donde el jugador recibe el disparo.
Las funciones PlayHapticWithOption y PlayLoop permiten ajustar la altura y el ángulo del patrón háptico. Estas funciones toman valores de ángulo (OffsetAngleX) y altura (OffsetY) para el ajuste háptico.
La función ProjectToVest calcula los valores de ángulo y altura en función del lugar donde el jugador recibe el disparo, la información de transformación del jugador y la altura del usuario. Estos valores se encapsulan en la estructura FBhapticsRotationOption y se devuelven.
-08a69024da438d538cc3301a1ecab27f.png)
#include "BhapticsSDK2.h"
void AExample::HitByBullet()
{
APawn *PlayerPawn = UGameplayStatics::GetPlayerPawn(GetWorld(), 0);
UPrimitiveComponent *PlayerComponent = Cast<UPrimitiveComponent>(PlayerPawn->GetRootComponent());
FVector ContactLocation = USomewhere::GetContactLocationSomehow();
float HalfHeight = YourActualHeight / 2;
FBhapticsRotationOption result = UBhapticsSDK2::ProjectToVest(ContactLocation, PlayerComponent, HalfHeight);
UBhapticsSDK2::PlayHapticWithOption("hit_by_bullet", 1.0f, 1.0f, result.OffsetAngleX, result.OffsetY);
}
ProjectToVestLocation
static FBhapticsRotationOption ProjectToVestLocation(FVector ContactLocation, FVector PlayerLocation, FRotator PlayerRotation);
Función auxiliar para calcular valores de Offset a partir de una ubicación de contacto e información de transformación del jugador. Es similar a ProjectToVest, pero solo calcula el Offset de ángulo (OffsetAngleX). La altura (OffsetY) siempre será 0.
Parámetros
FVector ContactLocation: Punto de contacto en coordenadas globales.FVector PlayerLocation: Ubicación del jugador.FRotator PlayerRotation: Rotation del jugador.
CustomProjectToVest
static FBhapticsRotationOption CustomProjectToVest(FVector ContactLocation, UPrimitiveComponent* PlayerComponent, float HalfHeight = 0, FVector UpVector = FVector::ZeroVector, FVector ForwardVector = FVector::ZeroVector);
Función auxiliar para calcular valores de Offset a partir de una colisión. Realiza la misma función que ProjectToVest, pero permite cambiar los vectores Forward y Up.
FVector ContactLocation: Punto de contacto en coordenadas globales.UPrimitiveComponent* PlayerComponent: Referencia al componente primitivo adjunto al jugador.float HalfHeight: La mitad de la altura real del jugador, medida en centímetros.FVector UpVector: Vector de dirección hacia arriba de referencia para el cálculo del Offset.FVector ForwardVector: Vector de dirección hacia adelante de referencia para el cálculo del Offset.