Unity 가이드

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

SDK 플러그인 가져오기
햅틱 앱 연동하기
초기화를 위한 프리팹 추가하기

요구 사항

개발 환경
- OS: Windows 10/11 (x64), macOS (Apple Silicon)
- Unity 2022 이상
- bHaptics Player 설치
- 게임에 대응하는 배포된 햅틱 애플리케이션
  - 햅틱 앱의 앱 ID와 API 키
실행 환경
- OS: Windows 10/11 (x64), macOS (Apple Silicon), 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가 설치되어 있어야 합니다.

노트

2022보다 이전 Unity 버전 지원이 필요하면 support@bhaptics.com으로 문의해 주세요.

지원 중단된 기능

스탠드얼론 VR 헤드셋에서 헤드셋에 bHaptics VR Player를 설치하지 않고 bHaptics 햅틱 기기를 사용하는 방식은 지원이 중단되었습니다. 햅틱 기기를 사용하려면 헤드셋에 bHaptics VR Player를 설치하세요.

macOS 및 Android의 경우

macOS와 Android용으로 개발하는 경우, bHaptics SDK를 사용하기 위한 추가 요구 사항이 필요합니다. 다음 섹션을 확인하세요.

Android의 경우 Android Manifest 업데이트 섹션을 확인하세요.
macOS의 경우 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.

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

SDK 플러그인 가져오기

Unity AssetStore의 bHaptics Haptic Plugin

Unity Asset Store에서 bHaptics Haptic Plugin을 받아 Unity 프로젝트에 패키지를 가져옵니다.

Unity 패키지를 Unity 프로젝트로 가져오는 방법에 대한 자세한 내용은 공식 Unity 문서를 참고하세요.

이전 버전에서 업데이트하는 경우

이전 버전의 Unity 패키지를 사용하고 있었다면, 업데이트 후 다음 레거시 Android 라이브러리 파일을 삭제하세요 — 각 .aar 파일을 그에 대응하는 .meta 파일과 함께 삭제하세요:

bhaptics_ble.aar / bhaptics_ble.aar.meta
bhaptics_commons.aar / bhaptics_commons.aar.meta
bhaptics_core.aar / bhaptics_core.aar.meta

이 파일들은 현재 패키지에서 더 이상 사용되지 않으며, 라이브러리 중복으로 인한 Android 빌드 오류를 일으킬 수 있습니다.

햅틱 앱 연동하기

툴바에서 "bHaptics" → "Developer Window"를 선택합니다.
Portal에서 발급받은 앱 ID와 API 키를 입력한 후 "LINK" 버튼을 클릭합니다.
노트
"Forgot your App ID & API Key?"를 눌러 Portal에 방문하여 해당 정보를 확인할 수 있습니다.
인증에 성공하면 bHaptics Developer Window에 애플리케이션이 표시됩니다.

bHaptics Developer Window에서 앱 살펴보기

bHaptics Developer Window

여러 탭을 살펴볼 수 있습니다.

Home: 샘플 가이드와 애플리케이션 정보를 확인합니다.
Events: bHaptics Developer Portal에서 배포한 최신 이벤트를 살펴보고 재생합니다.
Documentation: SDK 관련 문서(이 사이트 포함!)를 살펴봅니다.
Latest Deployed Version: 버전을 확인하거나 새로 고칩니다.
노트
Portal의 버전과 에디터의 버전이 일치하는지 확인하고, 일치하지 않으면 새로 고침 아이콘을 누르세요.
Unlink: 게임과 햅틱 앱의 연결을 해제합니다.

초기화를 위한 프리팹 추가하기

햅틱 환경을 초기화하기 위한 "[bhaptics]"라는 이름의 프리팹이 있습니다. 햅틱 관련 함수를 사용하기 전에 인스턴스화되어야 합니다. 첫 번째 씬에 배치하는 것을 강력히 권장합니다.

프리팹 초기화

첫 번째 씬으로 이동합니다.
Project Window에서 "Assets" → "Bhaptics" → "SDK2" → "Prefabs"로 이동합니다.
"[bhaptics]" 프리팹을 씬에 추가합니다.

이 프리팹의 컴포넌트는 DontDestroyOnLoad와 함께 일반적인 Unity 싱글톤 패턴을 사용합니다. 첫 번째 씬에만 배치하면 되지만, 중복 인스턴스는 자동으로 제거되므로 여러 곳에 배치해도 괜찮습니다.

Android Manifest 업데이트

스탠드얼론 헤드셋(Android)용으로 빌드할 때는 AndroidManifest.xml 파일 업데이트가 필수입니다. Android는 Target API Level 30부터 패키지 가시성을 제한하므로, 아래 매니페스트 항목이 없으면 게임이 bHaptics VR Player(com.bhaptics.player 패키지)를 감지할 수 없습니다.

노트

프로젝트의 Android Target API Level을 확인하려면 Project Settings → Player → Android settings(Android 아이콘) → Other Settings → Identification → Target API Level로 이동하세요. 자세한 내용은 Unity 매뉴얼을 참고하세요. Untitled

Android 앱 매니페스트 재정의를 활성화합니다. Project Settings → Player → Android settings(Android 아이콘) → Publishing Settings → Build → Custom Main Manifest로 이동한 후, 비활성화되어 있다면 활성화합니다. 매니페스트 파일의 디렉터리는 아래와 같습니다.
일반적으로 Assets/Plugins/Android/ 디렉터리에 있는 AndroidManifest.xml 파일을 엽니다.

매니페스트 파일에 queries 요소를 추가합니다.

<queries>
    <package android:name="com.bhaptics.player" />
</queries>

과정이 완료되면 매니페스트 파일은 다음과 같은 모습이어야 합니다.

<?xml version="1.0" encoding="utf-8"?>
<manifest
    xmlns:android="http://schemas.android.com/apk/res/android"
    package="com.unity3d.player"
    xmlns:tools="http://schemas.android.com/tools">

    <application>
        <activity android:name="com.unity3d.player.UnityPlayerActivity"
            android:theme="@style/UnityThemeSelector">
            <intent-filter>
                <action android:name="android.intent.action.MAIN" />
                <category android:name="android.intent.category.LAUNCHER" />
            </intent-filter>
            <meta-data android:name="unityplayer.UnityActivity" android:value="true" />
        </activity>
    </application>

    <queries>
        <package android:name="com.bhaptics.player" />
    </queries>
</manifest>

노트

자세한 내용은 다음 자료를 참고하세요.

위험

Minify 옵션을 활성화한 경우, Custom Proguard 파일(proguard-user.txt)에 예외를 추가해야 합니다.

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 햅틱 기능을 사용할 준비가 되었습니다! 게임에서 햅틱을 재생하려면 Unity References 페이지를 방문하세요.

노트

지금 바로 햅틱을 느껴보고 싶다면, 플레이테스트할 수 있는 햅틱 이벤트를 살펴볼 수 있는 샘플 씬을 제공합니다. "Assets" → "Bhaptics" → "SDK2" → "Examples" → "Scenes"로 이동하여 "PlayParamSample" 씬을 여세요. 관련 파라미터를 조절하면서 모든 햅틱 이벤트를 재생해 볼 수 있습니다.

문제 해결

Queries로 인한 빌드 실패

요구 사항​

SDK 플러그인 가져오기​

햅틱 앱 연동하기​

bHaptics Developer Window에서 앱 살펴보기​

초기화를 위한 프리팹 추가하기​

Android Manifest 업데이트​

macOS 네트워크 Entitlement​

더 읽어보기​

문제 해결​

마이그레이션 가이드​