Guía para Unreal

Con nuestro Unreal SDK Plugin, puede implementar la retroalimentación háptica en el contenido creado con Unreal.

1. Importar el SDK Plugin
2. Vincular la haptic app
3. Configurar el entorno háptico
4. (Opcional) Preparación para C++

---

Requisitos

• Entorno de desarrollo
  • OS: Windows 10/11 (x64), macOS (Apple Silicon) (actualmente en Beta)
  • Unreal Engine 4.26 - 5.6
  • bHaptics Player instalado
  • Aplicación háptica correspondiente a su juego, desplegada
    • App ID y API Key de la haptic app
• Entorno de ejecución
  • OS: Windows 10/11 (x64), Meta Horizon OS, PS5

About haptic application

You can create and manage haptic apps in Developer Portal, a web-based tool.

If you're unfamiliar with haptic apps or haven't created one yet, please follow the Portal guide before proceeding.

Before linking a haptic app to your game project, make sure the haptic app meets the following requirements:

• At least one haptic event must be created.
• API Key must be generated.
  • There is no API Key by default. To generate one, go to the "API Key" tab and click "New" button.
• Haptic app must be deployed
  • If you see "Deploy Now" button in the upper right corner, click it to deploy your haptic app. Otherwise, if you can see "Up to date", it means that the latest haptic app has already been deployed.

Also, link process requires App ID and API Key. Go to the "Settings" tab, and check the App ID and API Key.

Importar el SDK Plugin

Hay dos formas de importar el plugin del SDK en su proyecto de Unreal: Engine Plugin y Game Plugin.

¿Cuál debería usar?

Ambos tipos de plugins ofrecen una funcionalidad similar, pero su ubicación de instalación y su alcance son diferentes.

• Engine Plugin: Se instala en el directorio del motor, quedando disponible para todos los proyectos que usen la versión instalada de UE.
  • Se instala en [Unreal Engine Root Directory]/Engine/Plugins/[Plugin Name]/
• Game Plugin: Se coloca dentro de la carpeta de su proyecto, quedando disponible únicamente para un proyecto específico.
  • Se instala en [Project Root Directory]/Plugins/[Plugin Name]/

El plugin que puede descargar desde Fab es un engine plugin.

Para el desarrollo en consola, se recomienda encarecidamente usar game plugins. Esto garantiza que todo el código del plugin se empaquete junto con su proyecto, lo cual suele ser obligatorio para la certificación de consola. Los game plugins también son útiles si por alguna razón no puede usar Fab.

Para más información, consulte la documentación oficial de Unreal.

Instalar el plugin

Engine Plugin (UE 4.26 - 5.6)

1. Obtenga el bHaptics Plugin desde Fab.
2. Vaya a Epic Games Launcher para instalar el plugin en el motor.
   1. A la izquierda, seleccione la pestaña "Unreal Engine".
   2. En la parte superior, seleccione la pestaña "Library".
   3. Desplácese hasta "Fab Library" y busque "bhaptics".
   4. Encuentre "bHapticsPlugin" y seleccione "Install to Engine".
   5. Seleccione la versión del motor de juego que desea usar.
   6. Seleccione "Install". La descarga comenzará inmediatamente.
3. Abra el proyecto de Unreal y vaya a la ventana Plugins.
4. Active el plugin.
   1. Busque "bhaptics".
   2. Marque "BhapticsPlugin" para activarlo.
   3. Aparecerá una advertencia. Pulse "Restart Now". (¡Asegúrese de guardar primero su proyecto si tiene cambios!)
5. Tras reiniciar el editor, abra de nuevo la ventana Plugins y compruebe que "BhapticsPlugin" está habilitado.

Game Plugin (UE 4.26 - 5.6)

aviso

Haga una copia de seguridad de su proyecto antes de comenzar.

Si anteriormente instaló el engine plugin desde Fab, elimine el engine plugin antes de continuar.

nota

Se asume que su proyecto de Unreal usa C++. Si el proyecto solo usa Blueprints, debe crear una clase de C++ y compilar su proyecto antes de seguir estas instrucciones.

1. Descargue el bHaptics Plugin. Los archivos comprimidos del plugin se descargarán inmediatamente.
2. Descomprima los archivos zip descargados. Se creará una carpeta con el nombre BhapticsPlugin[_VERSION].
3. Vaya al directorio de su proyecto de Unreal. A continuación, coloque la carpeta BhapticsPlugin[_VERSION] en la carpeta Plugins de su proyecto de Unreal. La ruta debe ser [YourUEProjectName]/Plugins/BhapticsPlugin.
   • Si la carpeta Plugins no existe en su proyecto, cree una nueva.
   • La ubicación de estos archivos no debe cambiarse, así que asegúrese de que se coloquen correctamente. La carpeta debe ubicarse de la siguiente manera.

     [YourUEProjectName]
     ├── Binaries
     ├── Config
     ├── Plugins
     │   └── BhapticsPlugin_VERSION
     │       ├── BhapticsPlugin.uplugin
     │       └── (...)
     ├── (...)
     ├── [YourUEProjectName].sln
     └── [YourUEProjectName].uproject

4. Haga clic con el botón derecho en el archivo [YourUEProjectName].uproject y seleccione "Generate Visual Studio project files" para regenerar el archivo [YourUEProjectName].sln.
5. Abra [YourUEProjectName].sln, haga clic con el botón derecho en el nombre del proyecto en el Solution Explorer y seleccione "Build" para compilar el código fuente del proyecto.
6. Abra su proyecto de Unreal y vaya a la configuración de Plugin. Compruebe que "BhapticsPlugin" en la sección Haptic está habilitado.

Vincular la haptic app

1. Abra Project Settings.
2. Vaya a la configuración del plugin de bHaptics.
3. Introduzca el App ID y la API Key de su haptic app, y pulse el botón "Link bHaptics". El App ID y la API key se pueden encontrar en Portal.
4. Si el proyecto se sincroniza correctamente con bHaptics Developer Portal, recibirá el siguiente mensaje BHAPTICS_SETTINGS_SUCCESS.

Configurar el entorno háptico

Antes de usar las funciones relacionadas con la háptica, debe configurar el entorno háptico. Hay dos funciones principales que debe usar: Initialize y Destroy.

Debe inicializar el entorno háptico al comienzo del juego. También debe destruirlo cuando el juego termina.

Estas funciones se proporcionan tanto para Blueprint como para C++.

• Blueprint
  • Initialize: Llame al nodo "Initialize bHaptics"
  • Destroy: Llame al nodo "Destroy bHaptics"
• C++
  • Initialize: Invoque la función UBhapticsSDK2::Initialize()
  • Destroy: Invoque la función UBhapticsSDK2::Destroy()

Además, debe tener en cuenta lo siguiente:

• Puede inicializar varias veces. Esto no causará ningún problema de eficiencia.
• DEBE LLAMAR A DESTROY en el último nivel donde finaliza el programa, y debe hacerlo SOLO UNA VEZ. Puede provocar fallos si no llama a destroy o si lo llama más de una vez.

Prácticas habituales de configuración

Hay dos formas habituales de configurar el entorno háptico. Elija una de ellas según la estructura y las necesidades de su proyecto.

• Mediante GameInstance (Recomendado)
• Mediante Level Blueprint

Mediante GameInstance

La game instance se instancia al iniciar el motor y permanece activa hasta que el motor se apaga.

"Gameplay Framework" — documentación de Unreal

1. Cree una nueva Blueprint Class que herede de "GameInstance".
2. Asígnele el nombre que desee y abra su Event Graph.
3. Configure el Event Graph y compile/guarde.
   • Initialize: Conecte "Initialize bHaptics" después de "Event Init".
   • Destroy: Conecte "Destroy bHaptics" después de "Event Shutdown".
4. Vaya a Project Settings → Project → Maps & Modes y establezca Game Instance Class como la que acaba de crear.

Mediante Level Blueprint

1. Abra el Level Blueprint.
2. Configure el Event Graph y compile/guarde.
   • Initialize: Conecte "Initialize bHaptics" después de "Event BeginPlay".
   • Destroy: Conecte "Destroy bHaptics" después de "Event End Play".

(Opcional) Preparación para C++

Si usa C++ en su proyecto de Unreal, hay algunos procesos adicionales obligatorios.

1. Vaya a Source/[YourGameName]/[YourGameName].Build.cs y añada la dependencia.
   Source/[YourGameName]/[YourGameName].Build.cs

   // Add Dependency
   
   PrivateDependencyModuleNames.Add("BhapticsPlugin");
   
   // Or Using AddRange
   
   PrivateDependencyModuleNames.AddRange(new string[] { "BhapticsPlugin" });

   nota

   Después de modificar el archivo Build.cs, debe regenerar los archivos del proyecto y recompilar el motor.

   1. Regenerar los archivos del proyecto: Vaya a su proyecto de Unreal en el explorador de archivos, haga clic con el botón derecho en el archivo [YourUEProjectName].uproject y seleccione "Generate Visual Studio Project Files".
   2. Recompilar el motor: Abra [YourUEProjectName].sln, haga clic con el botón derecho en el nombre del proyecto en el Solution Explorer y seleccione "Rebuild".
2. Incluya el header "BhapticsSDK2.h" en el script de C++ que use las funciones hápticas.

   #include "CppGameModeBase.h"
   #include "BhapticsSDK2.h"
   
   void CppGameModeBase::BeginPlay()
   {
       Super::BeginPlay();
   
       UBhapticsSDK2::Initialize();
   }

Lecturas adicionales

¡Ya está listo para usar la función háptica de bHaptics! Visite nuestra Referencia de Unreal para reproducir hápticos en su juego.

Solución de problemas

• app:mergeDebugResources FAILED

Guía de migración

• Guía de migración (SDK1 → SDK2)