본문으로 건너뛰기

Unreal 가이드

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

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

요구 사항​

  • 개발 환경
    • OS: Windows 10/11 (x64), macOS (Apple Silicon) (현재 베타)
    • Unreal Engine 4.26 - 5.6
    • bHaptics Player 설치
    • 게임에 대응하는 햅틱 애플리케이션 배포 완료
      • 햅틱 앱의 앱 ID와 API 키
  • 런타임 환경
    • 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.

Check app ID, API key at the settings tab in Portal

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입니다.

콘솔 개발의 경우 game plugin 사용을 강력히 권장합니다. 이렇게 하면 모든 플러그인 코드가 프로젝트와 함께 번들로 묶이며, 이는 콘솔 인증에 필요한 경우가 많습니다. 또한 어떤 이유로 Fab을 사용할 수 없는 경우에도 game plugin이 유용합니다.

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

플러그인 설치하기​

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

햅틱 앱 연동하기​

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

햅틱 환경 설정하기​

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

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

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

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

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

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

일반적인 설정 방법​

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

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

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

"Gameplay Framework" — Unreal 문서

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

(선택 사항) 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();
    }

더 읽어보기​

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

문제 해결​

마이그레이션 가이드​