Guide pour Unreal

Grâce à notre plugin SDK Unreal, vous pouvez implémenter le retour haptique dans votre contenu créé avec Unreal.

1. Importer le plugin SDK
2. Lier l'application haptique
3. Configurer l'environnement haptique
4. (Optionnel) Préparer pour C++

---

Prérequis

• Environnement de développement
  • OS : Windows 10/11 (x64), macOS (Apple Silicon) (actuellement en bêta)
  • Unreal Engine 4.26 - 5.6
  • bHaptics Player installé
  • Application haptique déployée correspondant à votre jeu
    • App ID et API Key de l'application haptique
• Environnement d'exécution
  • 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.

Importer le plugin SDK

Il existe deux façons d'importer le plugin SDK dans votre projet Unreal : Engine Plugin et Game Plugin.

Lequel dois-je utiliser ?

Les deux types de plugins offrent des fonctionnalités similaires, mais leur emplacement d'installation et leur portée diffèrent.

• Engine Plugin : Installé dans le répertoire du moteur, ce qui le rend disponible pour tous les projets utilisant la version installée d'UE.
  • Installé dans [Unreal Engine Root Directory]/Engine/Plugins/[Plugin Name]/
• Game Plugin : Placé dans le dossier de votre projet, ce qui le rend disponible uniquement pour un projet spécifique.
  • Installé dans [Project Root Directory]/Plugins/[Plugin Name]/

Le plugin que vous pouvez télécharger sur Fab est un engine plugin.

Pour le développement console, il est fortement recommandé d'utiliser des game plugins. Cela garantit que tout le code du plugin est intégré à votre projet, ce qui est souvent requis pour la certification console. Les game plugins sont également utiles si vous ne pouvez pas utiliser Fab pour une raison quelconque.

Pour plus d'informations, consultez la documentation Unreal officielle.

Installer le plugin

Engine Plugin (UE 4.26 - 5.6)

1. Obtenez le bHaptics Plugin sur Fab.
2. Allez dans l'Epic Games Launcher pour installer le plugin sur le moteur.
   1. À gauche, sélectionnez l'onglet « Unreal Engine ».
   2. En haut, sélectionnez l'onglet « Library ».
   3. Faites défiler jusqu'à « Fab Library » et recherchez « bhaptics ».
   4. Trouvez « bHapticsPlugin » et sélectionnez « Install to Engine ».
   5. Sélectionnez la version du moteur de jeu que vous souhaitez utiliser.
   6. Sélectionnez « Install ». Le téléchargement commencera immédiatement.
3. Ouvrez le projet Unreal et accédez à la fenêtre Plugins.
4. Activez le plugin.
   1. Recherchez « bhaptics ».
   2. Cochez « BhapticsPlugin » pour l'activer.
   3. Un avertissement apparaîtra. Appuyez sur « Restart Now ». (Assurez-vous d'enregistrer d'abord votre projet si vous avez des modifications !)
5. Après avoir redémarré l'éditeur, rouvrez la fenêtre Plugins et vérifiez que « BhapticsPlugin » est activé.

Game Plugin (UE 4.26 - 5.6)

attention

Sauvegardez votre projet avant de commencer.

Si vous avez précédemment installé l'engine plugin depuis Fab, retirez l'engine plugin avant de poursuivre.

remarque

Ce guide suppose que votre projet Unreal utilise C++. Si le projet n'utilise que des Blueprints, vous devez créer une classe C++ et compiler votre projet avant de suivre ces instructions.

1. Téléchargez le bHaptics Plugin. Les fichiers compressés du plugin se téléchargeront immédiatement.
2. Décompressez les fichiers zip téléchargés. Un dossier nommé BhapticsPlugin[_VERSION] sera créé.
3. Accédez au répertoire de votre projet Unreal. Placez ensuite le dossier BhapticsPlugin[_VERSION] dans le dossier Plugins de votre projet Unreal. Le chemin doit être [YourUEProjectName]/Plugins/BhapticsPlugin.
   • Si le dossier Plugins n'existe pas dans votre projet, créez-en un nouveau.
   • L'emplacement de ces fichiers ne doit pas être modifié, alors assurez-vous qu'ils sont correctement placés. Le dossier doit se trouver à l'emplacement suivant.

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

4. Faites un clic droit sur le fichier [YourUEProjectName].uproject et sélectionnez « Generate Visual Studio project files » pour régénérer le fichier [YourUEProjectName].sln.
5. Ouvrez [YourUEProjectName].sln, faites un clic droit sur le nom du projet dans le Solution Explorer et sélectionnez « Build » pour compiler le source du projet.
6. Ouvrez votre projet Unreal et accédez aux paramètres Plugin. Vérifiez que « BhapticsPlugin » dans la section Haptic est activé.

Lier l'application haptique

1. Ouvrez les Project Settings.
2. Accédez aux paramètres du plugin bHaptics.
3. Saisissez l'App ID et l'API Key de votre application haptique, puis appuyez sur le bouton « Link bHaptics ». L'App ID et l'API Key se trouvent dans le Portal.
4. Si le projet est synchronisé avec succès avec le bHaptics Developer Portal, vous recevrez le message suivant : BHAPTICS_SETTINGS_SUCCESS.

Configurer l'environnement haptique

Avant d'utiliser les fonctions liées à l'haptique, vous devez configurer l'environnement haptique. Il y a deux fonctions principales que vous devez utiliser : Initialize et Destroy.

Vous devez initialiser l'environnement haptique au début du jeu. Vous devez également le détruire à la fin du jeu.

Ces fonctions sont fournies à la fois en Blueprint et en C++.

• Blueprint
  • Initialize : Appelez le nœud « Initialize bHaptics »
  • Destroy : Appelez le nœud « Destroy bHaptics »
• C++
  • Initialize : Invoquez la fonction UBhapticsSDK2::Initialize()
  • Destroy : Invoquez la fonction UBhapticsSDK2::Destroy()

Vous devez également noter que :

• Vous pouvez initialiser plusieurs fois. Cela ne causera aucun problème d'efficacité.
• Vous DEVEZ DÉTRUIRE au dernier niveau où le programme se termine, et vous devez le faire UNE SEULE FOIS. Ne pas détruire ou détruire plus d'une fois peut provoquer des plantages.

Pratiques de configuration courantes

Il existe deux façons courantes de configurer l'environnement haptique. Choisissez l'une ou l'autre en fonction de la structure et des besoins de votre projet.

• Via GameInstance (recommandé)
• Via Level Blueprint

Via GameInstance

La game instance est instanciée au lancement du moteur et reste active jusqu'à l'arrêt du moteur.

« Gameplay Framework » — Documentation Unreal

1. Créez une nouvelle Blueprint Class héritant de « GameInstance ».
2. Nommez-la comme vous le souhaitez et ouvrez son Event Graph.
3. Configurez l'Event Graph, puis compilez/enregistrez.
   • Initialize : Connectez « Initialize bHaptics » après « Event Init ».
   • Destroy : Connectez « Destroy bHaptics » après « Event Shutdown ».
4. Allez dans Project Settings → Project → Maps & Modes et définissez la Game Instance Class sur celle que vous venez de créer.

Via Level Blueprint

1. Ouvrez le Level Blueprint.
2. Configurez l'Event Graph, puis compilez/enregistrez.
   • Initialize : Connectez « Initialize bHaptics » après « Event BeginPlay ».
   • Destroy : Connectez « Destroy bHaptics » après « Event End Play ».

(Optionnel) Préparer pour C++

Si vous utilisez C++ dans votre projet Unreal, certaines étapes supplémentaires sont requises.

1. Accédez à Source/[YourGameName]/[YourGameName].Build.cs et ajoutez la dépendance.
   Source/[YourGameName]/[YourGameName].Build.cs

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

   remarque

   Après avoir modifié le fichier Build.cs, vous devez régénérer les fichiers du projet et recompiler le moteur.

   1. Régénérer les fichiers du projet : Accédez à votre projet Unreal dans l'explorateur de fichiers, faites un clic droit sur le fichier [YourUEProjectName].uproject et sélectionnez « Generate Visual Studio Project Files ».
   2. Recompiler le moteur : Ouvrez [YourUEProjectName].sln, faites un clic droit sur le nom du projet dans le Solution Explorer et sélectionnez « Rebuild ».
2. Incluez l'en-tête "BhapticsSDK2.h" dans votre script C++ qui utilise les fonctionnalités haptiques.

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

Pour aller plus loin

Vous êtes maintenant prêt à utiliser la fonctionnalité haptique de bHaptics ! Consultez notre Référence Unreal pour lire des effets haptiques dans votre jeu.

Dépannage

• app:mergeDebugResources FAILED

Guide de migration

• Guide de migration (SDK1 → SDK2)