Guide for Unreal

Using our Unreal SDK Plugin, you can implement the haptic into your content made with Unreal.

1. Import SDK Plugin
2. Link the Haptic App
3. Set Up Haptic Environment
4. (Optional) Prepare for C++

---

Requirements

• Development Environment
  • OS: Windows 10/11 (x64), macOS (Apple Silicon) (currently on Beta)
  • Unreal Engine 4.26 - 5.6
  • bHaptics Player installed
  • Deployed haptic application corresponding to your game
    • App ID and API Key of the haptic app
• Runtime Environment
  • 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.

Import SDK Plugin

There are two ways to import the SDK plugin into your Unreal project: Engine Plugin, and Game Plugin

Which one should I use?

Both types of plugins can provide similar functionality, but their installation location and scope are different.

• Engine Plugin: Installed in the engine directory, making it available to all projects that use the installed version of UE.
  • Installed at [Unreal Engine Root Directory]/Engine/Plugins/[Plugin Name]/
• Game Plugin: Placed inside your project's folder, making it available only to a specific project.
  • Installed at [Project Root Directory]/Plugins/[Plugin Name]/

The plugin you can download from Fab is an engine plugin.

For console development, it is highly recommended to use game plugins. This ensures all plugin codes are bundled with your project, which is often required for console certification. Game plugins are also useful if you cannot use Fab for some reason.

For more information, refer to the official Unreal Documentation.

Install the Plugin

Engine Plugin (UE 4.26 - 5.6)

1. Get bHaptics Plugin from Fab.
2. Go to Epic Games Launcher to install plugin to engine.
   1. At the left, Select "Unreal Engine" tab.
   2. At the top, Select "Library" tab.
   3. Scroll down to "Fab Library", and search "bhaptics".
   4. Find "bHapticsPlugin", and select "Install to Engine".
   5. Select your game engine version you want to use.
   6. Select "Install". The download will begin immediately.
3. Open the Unreal Project and go to the Plugins window.
4. Activate the plugin.
   1. Search "bhaptics".
   2. Check "BhapticsPlugin" to activate.
   3. The warning will appear. Press "Restart Now". (Make sure you save your project first if you have any changes!)
5. After restarting the editor, open the Plugins window again, and check that "BhapticsPlugin" is enabled.

Game Plugin (UE 4.26 - 5.6)

warning

Back up your project before you start.

If you previously installed the engine plugin from Fab, remove the engine plugin before proceeding.

note

It assumes that your Unreal project is using C++. If the project only uses Blueprints, you must create a C++ class and build your project before following these instructions.

1. Download the bHaptics Plugin, The zipped plugin files will download immediately.
2. Unzip the downloaded zip files. The folder named BhapticsPlugin[_VERSION] will be created.
3. Go to the directory of your Unreal project. Then, place the BhapticsPlugin[_VERSION] folder in the Plugins folder of your Unreal project. The path should be [YourUEProjectName]/Plugins/BhapticsPlugin.
   • If the Plugins folder doesn't exist in your project, create a new one.
   • The location of these files must not be changed, so ensure they are placed correctly. The folder should be located as follows.

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

4. Right-click the [YourUEProjectName].uproject file and select "Generate Visual Studio project files" to regenerate the [YourUEProjectName].sln file.
5. Open [YourUEProjectName].sln, right-click the project name in the Solution Explorer, and select "Build" to compile the project source.
6. Open your Unreal project, and go to Plugin settings. Check that "BhapticsPlugin" in Haptic section is enabled.

Link the Haptic App

1. Open the Project Settings.
2. Go to bHaptics plugin settings.
3. Put the App ID, API Key of your haptic app, and press "Link bHaptics" button. App ID and API key can be found in Portal.
4. If the project is successfully synchronized with bHaptics Developer portal, you will receive following message BHAPTICS_SETTINGS_SUCCESS.

Set Up Haptic Environment

Before using haptic-related functions, you must set up the haptic environment. There are two main functions you must use: Initialize and Destroy.

You should initialize the haptic environment at the beginning of the game. You should also destroy it when the game ends.

Both Blueprint and C++ methods are provided for these functions.

• Blueprint
  • Initialize: Call "Initialize bHaptics" Node
  • Destroy: Call "Destroy bHaptics" Node
• C++
  • Initialize: Invoke UBhapticsSDK2::Initialize() Function
  • Destroy: Invoke UBhapticsSDK2::Destroy() Function

Also, you must notice that:

• You can initialize multiple times. This will not cause any efficiency problems.
• You MUST DESTROY at the last level where the program ends, and you must do it ONLY ONCE. It can cause crashes if you don't destroy or destroy more than once.

Common Setup Practices

There are two common ways to set up the haptic environment. Choose either one based on your project structure and needs.

• Via GameInstance (Recommended)
• Via Level Blueprint

Via GameInstance

The game instance is instantiated on engine launch and remains active until the engine shuts down.

"Gameplay Framework" — Unreal Documentation

1. Create new Blueprint Class inherit from "GameInstance".
2. Name it as you want, and open its Event Graph.
3. Setup the Event Graph, and compile/save.
   • Initialize: Connect "Initialize bHaptics" after "Event Init".
   • Destroy: Connect "Destroy bHaptics" after "Event Shutdown".
4. Go to Project Settings → Project → Maps & Modes, and set Game Instance Class as what you've just made.

Via Level Blueprint

1. Open the Level Blueprint.
2. Setup the Event Graph, and compile/save.
   • Initialize: Connect "Initialize bHaptics" after "Event BeginPlay".
   • Destroy: Connect "Destroy bHaptics" after "Event End Play".

(Optional) Prepare for C++

If you're using C++ in your Unreal project, there are some additional required processes.

1. Move to Source/[YourGameName]/[YourGameName].Build.cs and add dependency.
   Source/[YourGameName]/[YourGameName].Build.cs

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

   note

   After you modify the Build.cs file, you must regenerate the project files, and rebuild the engine.

   1. Regenerate the project files: Go to your Unreal project in the file explorer, right-click the [YourUEProjectName].uproject file, and select "Generate Visual Studio Project Files".
   2. Rebuild the engine: Open [YourUEProjectName].sln, right-click the project name in the Solution Explorer, and select "Rebuild".
2. Include "BhapticsSDK2.h" header in your C++ script which uses the haptic features.

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

Further Reading

You're now ready to use the bHaptics haptic feature! Visit our Unreal Reference to play haptics in your game.

Troubleshooting

• app:mergeDebugResources FAILED

Migration Guide

• Migration Guide (SDK1 → SDK2)