Unreal 가이드

bHaptics의 Unreal SDK 플러그인을 사용하면 Unreal로 제작한 콘텐츠에 햅틱을 구현할 수 있습니다.

1. SDK 플러그인 가져오기
2. 햅틱 앱 연동하기
3. 햅틱 환경 설정하기
4. (선택 사항) C++ 사용 준비하기

---

요구 사항

• 개발 환경
  • OS: Windows 10/11 (x64), macOS (Apple Silicon) (현재 베타)
  • Unreal Engine 5.2 - 5.8
  • bHaptics Player 설치
  • 게임에 대응하는 햅틱 애플리케이션 배포 완료
    • 햅틱 앱의 앱 ID와 API 키
• 런타임 환경
  • OS: Windows 10/11 (x64), Android (VR 헤드셋 전용), PS5
    • 지원 헤드셋: Meta Quest 2/3/3S/Pro, Pico 4/4 Pro/4 Ultra, HTC VIVE Focus 3/Focus Vision/XR Elite
    • 헤드셋에 bHaptics VR Player가 설치되어 있어야 합니다.

노트

5.2 - 5.8 범위를 벗어나는 Unreal Engine 버전 지원이 필요하면 support@bhaptics.com으로 문의해 주세요.

Deprecated Feature

standalone VR 헤드셋에서 bHaptics VR Player 없이 bHaptics 햅틱 기기를 사용하는 것은 지원이 중단되었습니다. 햅틱 기기를 사용하려면 헤드셋에 bHaptics VR Player를 설치하시기 바랍니다.

For macOS

macOS용으로 개발하는 경우, 패키징한 앱이 bHaptics Player에 연결할 수 있도록 macOS 네트워크 Entitlement 섹션을 확인하시기 바랍니다.

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.

SDK 플러그인 가져오기

SDK 플러그인을 Unreal 프로젝트에 가져오는 방법은 Engine Plugin과 Game Plugin 두 가지가 있습니다.

어떤 것을 사용해야 하나요?

두 가지 유형의 플러그인 모두 유사한 기능을 제공하지만, 설치 위치와 적용 범위가 다릅니다.

• Engine Plugin: 엔진 디렉토리에 설치되어, 해당 버전의 UE를 사용하는 모든 프로젝트에서 사용할 수 있습니다.
  • 설치 위치: [Unreal Engine Root Directory]/Engine/Plugins/[Plugin Name]/
• Game Plugin: 프로젝트 폴더 안에 배치되어, 특정 프로젝트에서만 사용할 수 있습니다.
  • 설치 위치: [Project Root Directory]/Plugins/[Plugin Name]/

Fab에서 다운로드하는 플러그인은 engine plugin으로, 미리 컴파일된 Windows 바이너리입니다. macOS나 콘솔 바이너리는 포함하지 않으므로 macOS에서 사용하거나 PS5와 같은 콘솔용으로 패키징할 수 없습니다.

macOS나 콘솔 개발에는 game plugin을 사용하시기 바랍니다. SDK 자체는 플랫폼 중립적입니다 — bHaptics Player와 로컬 네트워크 연결로 통신하므로, 그 소스는 어떤 대상 플랫폼으로도 컴파일됩니다. game plugin은 이 소스를 프로젝트 안에 두어, macOS와 PS5를 포함한 대상 플랫폼에 맞게 프로젝트와 함께 빌드되도록 합니다. 또한 플러그인 소스를 프로젝트에 번들로 포함하는 것은 콘솔 인증 요건에도 부합합니다. game plugin은 Fab을 사용할 수 없는 경우에도 유용합니다.

자세한 내용은 공식 Unreal 문서를 참고하시기 바랍니다.

플러그인 설치하기

Engine Plugin (UE 5.2 - 5.8)

노트

Fab engine plugin은 미리 컴파일된 Windows 바이너리입니다. macOS의 경우 대신 Game Plugin을 사용하시기 바랍니다.

1. Fab에서 bHaptics Plugin을 받습니다.
2. Epic Games Launcher로 이동하여 플러그인을 엔진에 설치합니다.
   1. 왼쪽에서 "Unreal Engine" 탭을 선택합니다.
   2. 상단에서 "Library" 탭을 선택합니다.
   3. "Fab Library"까지 스크롤한 후 "bhaptics"를 검색합니다.
   4. "bHapticsPlugin"을 찾아 "Install to Engine"을 선택합니다.
   5. 사용하려는 게임 엔진 버전을 선택합니다.
   6. "Install"을 선택합니다. 다운로드가 즉시 시작됩니다.
3. Unreal 프로젝트를 열고 Plugins 창으로 이동합니다.
4. 플러그인을 활성화합니다.
   1. "bhaptics"를 검색합니다.
   2. "BhapticsPlugin"을 체크하여 활성화합니다.
   3. 경고가 표시됩니다. "Restart Now"를 누릅니다. (변경 사항이 있다면 먼저 프로젝트를 저장했는지 확인하시기 바랍니다!)
5. 에디터를 재시작한 후 Plugins 창을 다시 열어 "BhapticsPlugin"이 활성화되어 있는지 확인합니다.

Game Plugin (UE 5.2 - 5.8)

경고

시작하기 전에 프로젝트를 백업하시기 바랍니다.

이전에 Fab에서 engine plugin을 설치한 적이 있다면, 진행하기 전에 engine plugin을 제거하시기 바랍니다.

노트

Unreal 프로젝트가 **C++**를 사용한다고 가정합니다. 프로젝트가 Blueprint만 사용하는 경우, C++ 클래스를 생성하고 프로젝트를 빌드한 후 아래 안내를 따라야 합니다.

1. bHaptics Plugin을 다운로드합니다. 압축된 플러그인 파일이 즉시 다운로드됩니다.
2. 다운로드한 zip 파일의 압축을 풉니다. BhapticsPlugin[_VERSION]이라는 이름의 폴더가 생성됩니다.
3. Unreal 프로젝트의 디렉토리로 이동합니다. 그런 다음 BhapticsPlugin[_VERSION] 폴더를 Unreal 프로젝트의 Plugins 폴더에 배치합니다. 경로는 **[YourUEProjectName]/Plugins/BhapticsPlugin**이어야 합니다.
   • 프로젝트에 Plugins 폴더가 없다면 새로 만듭니다.
   • 이 파일들의 위치는 변경되어서는 안 되므로, 올바르게 배치되었는지 확인하시기 바랍니다. 폴더는 다음과 같은 위치에 있어야 합니다.

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

4. [YourUEProjectName].uproject 파일을 마우스 오른쪽 버튼으로 클릭하고 "Generate Visual Studio project files"를 선택하여 [YourUEProjectName].sln 파일을 다시 생성합니다.
5. [YourUEProjectName].sln을 열고 Solution Explorer에서 프로젝트 이름을 마우스 오른쪽 버튼으로 클릭한 후 "Build"를 선택하여 프로젝트 소스를 컴파일합니다.
6. Unreal 프로젝트를 열고 Plugin 설정으로 이동합니다. Haptic 섹션의 "BhapticsPlugin"이 활성화되어 있는지 확인합니다.

햅틱 앱 연동하기

1. Project Settings를 엽니다.
2. bHaptics 플러그인 설정으로 이동합니다.
3. 햅틱 앱의 앱 ID와 API 키를 입력하고 "Link bHaptics" 버튼을 누릅니다. 앱 ID와 API 키는 Portal에서 확인할 수 있습니다.
4. 프로젝트가 bHaptics Developer Portal과 성공적으로 동기화되면, BHAPTICS_SETTINGS_SUCCESS 메시지가 표시됩니다.

햅틱 환경 설정하기

햅틱 관련 함수를 사용하기 전에 햅틱 환경을 설정해야 합니다. 반드시 사용해야 하는 두 가지 주요 함수가 있습니다. 바로 Initialize와 Destroy입니다.

햅틱 환경은 게임이 시작될 때 초기화해야 합니다. 또한 게임이 종료될 때 햅틱 환경을 파괴(Destroy)해야 합니다.

이 함수들은 Blueprint와 C++ 두 가지 방식으로 모두 제공됩니다.

• Blueprint
  • Initialize: "Initialize bHaptics" 노드 호출
  • Destroy: "Destroy bHaptics" 노드 호출
• C++
  • Initialize: UBhapticsSDK2::Initialize() 함수 호출
  • Destroy: UBhapticsSDK2::Destroy() 함수 호출

또한 다음 사항에 유의해야 합니다.

• 초기화는 여러 번 수행해도 됩니다. 효율성 문제가 발생하지 않습니다.
• 프로그램이 종료되는 마지막 레벨에서 반드시 Destroy를 호출해야 하며, 반드시 한 번만 호출해야 합니다. Destroy를 호출하지 않거나 두 번 이상 호출하면 크래시가 발생할 수 있습니다.

일반적인 설정 방법

햅틱 환경을 설정하는 일반적인 방법은 두 가지가 있습니다. 프로젝트 구조와 필요에 따라 둘 중 하나를 선택하시기 바랍니다.

• GameInstance 사용 (권장)
• Level Blueprint 사용

GameInstance 사용

게임 인스턴스는 엔진이 시작될 때 인스턴스화되며 엔진이 종료될 때까지 활성 상태로 유지됩니다.

"Gameplay Framework" — Unreal 문서

1. "GameInstance"를 상속하는 새 Blueprint Class를 생성합니다.
2. 원하는 이름을 지정하고 Event Graph를 엽니다.
3. Event Graph를 설정한 후 컴파일/저장합니다.
   • Initialize: "Event Init" 뒤에 "Initialize bHaptics"를 연결합니다.
   • Destroy: "Event Shutdown" 뒤에 "Destroy bHaptics"를 연결합니다.
4. Project Settings → Project → Maps & Modes로 이동하여 Game Instance Class를 방금 만든 클래스로 설정합니다.

Level Blueprint 사용

1. Level Blueprint를 엽니다.
2. Event Graph를 설정한 후 컴파일/저장합니다.
   • Initialize: "Event BeginPlay" 뒤에 "Initialize bHaptics"를 연결합니다.
   • Destroy: "Event End Play" 뒤에 "Destroy bHaptics"를 연결합니다.

(선택 사항) C++ 사용 준비하기

Unreal 프로젝트에서 C++를 사용하는 경우, 몇 가지 추가 작업이 필요합니다.

1. Source/[YourGameName]/[YourGameName].Build.cs로 이동하여 의존성을 추가합니다.
   Source/[YourGameName]/[YourGameName].Build.cs

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

   노트

   Build.cs 파일을 수정한 후에는 반드시 프로젝트 파일을 다시 생성하고 엔진을 다시 빌드해야 합니다.

   1. 프로젝트 파일 다시 생성하기: 파일 탐색기에서 Unreal 프로젝트로 이동하여 [YourUEProjectName].uproject 파일을 마우스 오른쪽 버튼으로 클릭하고 "Generate Visual Studio Project Files"를 선택합니다.
   2. 엔진 다시 빌드하기: [YourUEProjectName].sln을 열고 Solution Explorer에서 프로젝트 이름을 마우스 오른쪽 버튼으로 클릭한 후 "Rebuild"를 선택합니다.
2. 햅틱 기능을 사용하는 C++ 스크립트에 "BhapticsSDK2.h" 헤더를 포함합니다.

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

macOS 네트워크 Entitlement

macOS 15(Sequoia) 이상에서는 패키징된 앱이 App Sandbox 안에서 실행됩니다. 앱이 네트워크 클라이언트 entitlement를 선언하지 않으면 샌드박스가 모든 네트워크 접근(localhost 연결 포함)을 차단합니다. SDK는 bHaptics Player와 로컬 연결로 통신하므로, 이 entitlement가 없는 macOS 패키지 빌드는 Player에 연결하지 못합니다(샌드박스 deny network 오류로 실패하는 것을 볼 수 있습니다).

macOS용으로 앱을 패키징할 때 com.apple.security.network.client entitlement를 추가하세요. 이는 앱 제작자가 설정하는 부분이며 SDK에 포함되어 있지 않습니다.

더 읽어보기

이제 bHaptics 햅틱 기능을 사용할 준비가 되었습니다! 게임에서 햅틱을 재생하려면 Unreal 레퍼런스를 방문하시기 바랍니다.

문제 해결

• app:mergeDebugResources FAILED

마이그레이션 가이드

• 마이그레이션 가이드 (SDK1 → SDK2)