Unity 指南

使用我们的 Unity SDK 插件，您可以将触觉集成到用 Unity 制作的内容中。

1. 导入 SDK 插件
2. 连接触觉应用
3. 添加用于初始化的预制体

---

要求

• 开发环境
  • OS: Windows 10/11 (x64), macOS (Apple Silicon)
  • Unity 2022 及更高版本
  • 已安装 bHaptics Player
  • 已部署与您的游戏对应的触觉应用程序
    • 触觉应用的 App ID 和 API Key
• 运行环境
  • 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.

导入 SDK 插件

在 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 构建错误。

连接触觉应用

1. 在工具栏中，选择 "bHaptics" → "Developer Window"。
2. 输入您从 Portal 获取的 App ID 和 API Key，然后点击 "LINK" 按钮。
   备注

   您可以按 "Forgot your App ID & API Key?" 访问 Portal 并找回相关信息。

3. 认证成功后，应用将显示在 bHaptics Developer Window 中。

在 bHaptics Developer Window 中浏览应用

有多个标签页可供您浏览。

• Home: 查看示例指南以及有关您应用的信息。
• Events: 浏览并播放您从 bHaptics Developer Portal 部署的最新事件。
• Documentation: 浏览有关 SDK 的文档（包括本网站！）。
• Latest Deployed Version: 检查版本或刷新。
  备注

  确保 Portal 中的版本与编辑器中的版本一致；如果不一致，请按刷新图标。

• Unlink: 断开游戏与触觉应用之间的连接。

添加用于初始化的预制体

有一个名为 "[bhaptics]" 的预制体用于初始化触觉环境。在使用与触觉相关的函数之前，它应当被实例化。我们强烈建议将其放置在第一个场景中。

1. 进入您的第一个场景。
2. 在 Project Window 中，进入 "Assets" → "Bhaptics" → "SDK2" → "Prefabs"。
3. 将 "[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 手册。

1. 启用 Android 应用清单覆盖。进入 Project Settings → Player → Android settings(Android 图标) → Publishing Settings → Build → Custom Main Manifest，如果它被禁用则启用它。清单文件的目录如下所示。
2. 打开您的 AndroidManifest.xml 文件，它通常位于 Assets/Plugins/Android/ 目录中。
3. 在清单文件中添加 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>

备注

有关更多信息，请参阅以下资源。

• 在 Unity 中覆盖 Android 应用清单
• 关于 Android 应用清单

危险

如果您启用了 Minify 选项，则应在 Custom Proguard 文件 (proguard-user.txt) 中添加例外。

macOS 网络 Entitlement

在 macOS 15 (Sequoia) 及更高版本上，打包后的应用运行在 App Sandbox 内。除非应用声明网络客户端 entitlement，否则沙盒会阻止所有网络访问（包括对 localhost 的连接）。由于 SDK 通过本地连接与 bHaptics Player 通信，因此没有此 entitlement 的 macOS 打包构建无法连接到 Player（您可能会看到它因 sandbox deny network 错误而失败）。

当您为 macOS 打包应用时，请添加 com.apple.security.network.client entitlement。这由应用开发者配置，不属于 SDK 的一部分。

延伸阅读

现在您已经准备好使用 bHaptics 触觉功能了！访问我们的 Unity References 页面，在您的游戏中播放触觉。

备注

如果您想立即感受触觉，我们提供了一个示例场景，让您可以浏览可进行播放测试的触觉事件。进入 "Assets" → "Bhaptics" → "SDK2" → "Examples" → "Scenes"，打开 "PlayParamSample" 场景。您可以在调整相关参数的同时播放所有触觉事件。

故障排除

• Queries 导致的构建失败

迁移指南

• 迁移指南 (SDK1 → SDK2)
• 迁移指南 (2.0.5 → 最新)