当前位置：首页 > article >正文

Cocos游戏中集成RichTap高品质振动

article 2025/1/5 12:15:56

一. 简介

RichTap是全球领先的全品类设备触感整体解决方案，可帮助设备制造商和游戏、影音、社交互动等内容商，一站式实现多维度、全场景的高品质触觉反馈体验。本文着重介绍RichTap在Cocos项目中的落地方案。

RichTap 提供了多平台的原生SDK（包括Android、iOS、Windows等），丰富的API可以很方便地在各平台上进行振动效果的播放和控制。再看Cocos，它也有好几种方法来扩展接入原生SDK，本文采用了JsbBridge方案，即：使用Cocos封装的JsbBridgeWrapper进行事件派发，通过修改Cocos构建的原生工程（安卓/iOS）集成RichTap SDK，以实现在Cocos项目中表现RichTap高品质振动效果。

以下是分平台集成RichTap的具体步骤。

二. 集成步骤

安卓平台

请首先确认你的Cocos项目已经生成了native工程。可以查看工程目录中是否有native\engine\android目录。如果没有，则在Cocos Creator中构建一个安卓任务。

1. 把RichTap Android SDK库文件xxx.aar复制到工程目录\native\engine\android\app\libs\目录下（没有则新建）

2. 把桥接代码RichtapBridge.java复制到工程目录\native\engine\android\app\src\com\cocos\game\目录下

3. 用Android Studio打开\项目目录\build\android\proj工程，等待Gradle同步完成

4. 打开Gradle Scripts > build.gradle(Module ...)配置文件引入RichTap SDK aar文件

Java
dependencies {
implementation files("libs/xxx.aar")
}

5. 打开工程目录 > java > com.cocos.game > AppActivity，在onCreate函数内添加初始化相关代码

Java
protected void onCreate(Bundle savedInstanceState) {
    super.onCreate(savedInstanceState);
    // 新增的初始化代码
    RichtapBridge.start(this);
    ...
}

iOS平台

请首先确认你的Cocos项目已经生成了native工程。可以查看工程目录中是否有native\engine\ios目录。如果没有，则在Cocos Creator中构建一个iOS任务。

1. 把RichTap iOS SDK库文件RichTapSDK.framework复制到工程目录\native\engine\ios\Frameworks\目录下（没有则新建）

2. 把桥接代码复制到工程目录\native\engine\ios\目录下

3. 打开文件工程目录\native\engine\ios\CMakeLists.txt，编辑cmake配置文件

3.1 在add_executable命令之前添加以下代码

CMake
# 添加所有的桥接程序代码，并追加到CC_PROJ_SOURCES
set(JSB_BRIDGE_SOURCE
    ${CC_PROJECT_DIR}/RichTapBridge.h
    ${CC_PROJECT_DIR}/RichTapBridge.mm
    ${CC_PROJECT_DIR}/MyIOSPlatform.h
    ${CC_PROJECT_DIR}/MyIOSPlatform.mm
    ${CC_PROJECT_DIR}/RichTapManager.h
    ${CC_PROJECT_DIR}/RichTapManager.m
  ${CMAKE_}
)
list(APPEND CC_PROJ_SOURCES ${JSB_BRIDGE_SOURCE})

# 设置 RichTapSDK 的路径
set(RICHTAPSDK_PATH ${CC_PROJECT_DIR}/Frameworks/RichTapSDK.framework)

# 添加 framework 的搜索路径
include_directories(${RICHTAPSDK_PATH}/Headers)
link_directories(${RICHTAPSDK_PATH})

# 添加-ObjC编译选项
set(CMAKE_XCODE_ATTRIBUTE_OTHER_LDFLAGS "-ObjC")

3.2 在add_executable命令之后添加以下代码

CMake
# 链接 RichTapSDK Framework，必须要在add_executable之后链接
target_link_libraries(${EXECUTABLE_NAME} ${RICHTAPSDK_PATH})

4. 打开Cocos Creator重新构建当前iOS项目

5. 使用Xcode打开\项目目录\build\ios\proj工程，打开EXECUTABLE_NAME > Source Files > main.mm文件，注释默认的平台初始化代码，添加RichTap SDK的平台初始化代码

Objective-C
// 注释默认的BasePlatform头文件
// #include "platform/BasePlatform.h"
// 添加MyIOSPlatform头文件
#include "MyIOSPlatform.h"

int main(int argc, const char * argv[]) {
    // 注释BasePlatform初始化代码
    // cc::MyIOSPlatform* platform = new cc::MyIOSPlatform();
    // 添加RichTap SDK的平台初始化代码
    cc::BasePlatform* platform = cc::BasePlatform::getPlatform();
    ...
}

三. 在Cocos项目中调用

把RichTapHaptics文件夹复制到你的Cocos项目的assets目录中，在需要使用的脚本中导入RichTapHaptics类，使用getInstance方法可以获取实例。

JavaScript
import RichTapHaptics from './RichTapHaptics';

// 通过getInstance获取实例即可调用对应的方法
RichTapHaptics.getInstance()...

API说明

下面说明一下RichTapHaptics的各个API，方便开发者调用。

1. 初始化

JavaScript
init(): void

功能：初始化插件，调用振动接口之前必须先初始化，否则无法振动（iOS除外）

参数：无

返回值：无

2. 释放/退出插件

JavaScript
quit(): void

功能：游戏退出时释放RichTap资源

参数：无

返回值：无

3. 获取SDK版本

JavaScript
getSDKVersion(): Promise<string>

功能：获取RichTap SDK的版本号

参数：无

返回值：返回Promise形式的字符串，表示SDK版本号

4. 检查当前设备的RichTap振动能力

JavaScript
isSupportRichTap(): Promise<boolean>

功能：检查当前设备是否支持RichTap高品质振动的能力

参数：无

返回值：返回Promise形式的布尔值，true表示当前设备支持RichTap高品质，false表示不支持

5. 播放振动文件

JavaScript
playHaptic(params: PlayHapticParams): void

功能：播放振动效果文件（以.he为扩展名的文件）

参数：PlayHapticParams 格式见下文

返回值：无

6. 停止振动

JavaScript
stopHaptic(): void

功能：停止所有振动

参数：无

返回值：无

7. 调整振动参数

JavaScript
updateHapticParams(params: UpdateLoopParams): void

功能：在播放过程中动态调整振动效果参数

参数：UpdateLoopParams 格式见下文

返回值：无

8. 播放预置效果

JavaScript
playPrebaked(name: PrebakedEffectName): void

功能：播放RichTap SDK预置效果库中的振动效果

参数：PrebakedEffectName 格式见下文

返回值：无

9. 预置振动效果数据类型

TypeScript
enum PrebakedEffectName {
    RT_CLICK = 10001,
    RT_DOUBLE_CLICK,
    RT_SOFT_CLICK,
    RT_TICK,
    RT_THUD,
    RT_FAILURE,
    RT_SUCCESS,
    RT_RAMP_UP,
    RT_TOGGLE_SWITCH,
    RT_LONG_PRESS,
    RT_VIRTUAL_KEY,
    RT_KEYBOARD_TAP,
    RT_CLOCK_TICK,
    RT_CALENDAR_DATE,
    RT_CONTEXT_CLICK,
    RT_KEYBOARD_RELEASE,
    RT_VIRTUAL_KEY_RELEASE,
    RT_TEXT_HANDLE_MOVE,
    RT_ENTRY_BUMP,
    RT_DRAG_CROSSING,
    RT_GESTURE,
    RT_CONFIRM,
    RT_REJECT,
    RT_BOMB,
    RT_SWORD,
    RT_GUNSHOT,
    RT_SPEED_UP,
    RT_JUMP,
    RT_DRUM,
    RT_COIN_DROP,
    RT_HEARTBEAT,
    RT_PLUCKING,
    RT_DRAWING_ARROW,
    RT_CAMERA_SHUTTER,
    RT_FIREWORKS,
    RT_SNIPER_RIFLE,
    RT_ASSAULT_RIFLE,
    RT_CYMBAL,
    RT_TAMBOURINE,
    RT_FAST_MOVING,
    RT_FLY,
    RT_FOOTSTEP,
    RT_ICE,
  RT_LIGHTNING,
    RT_SPRING,
    RT_SWING,
    RT_WIND,
    RT_VICTORY,
    RT_AWARD,
    RT_GAMEOVER
}

10. 播放振动文件参数数据类型

TypeScript
interface PlayHapticParams {
    he: string
    loop: number
    intensity: number
    interval: number
    frequency: number
}

he：振动效果HE文件内容，是一个JSON字符串

loop：循环次数，取值范围是大于等于-1的整数，-1表示无限循环，0表示只播放一次（不循环）

interval：循环播放情况下相邻两次播放之间的时间间隔，以毫秒为单位

intensity：振动强度缩放值，取值范围是[0, 511]，255表示按HE原有设计强度振动

frequency：变频值，取值范围[-100, 100]，0表示不对HE做变频

11. 调整振动参数数据类型

TypeScript
interface UpdateLoopParams {
    intensity: number
    interval: number
    frequency: number
}

intensity：振动强度缩放值，取值范围是[0, 511]的整数，255表示按HE原有设计强度振动

interval：循环播放情况下相邻两次播放之间的时间间隔，以毫秒为单位，整数

frequency：变频值，取值范围[-100, 100]的整数，0表示不对HE做变频

使用示例

下面通过一个Cocos脚本，演示RichTap SDK的具体使用方法。

TypeScript
import { _decorator, Component, JsonAsset } from 'cc';
import RichTapHaptics from './RichTapUtils'
import { PrebakedEffectName } from './RichTapUtils/type';
const { ccclass, property } = _decorator;

@ccclass('NewComponent')
export class NewComponent extends Component {

    @property(JsonAsset)
    public heJson: JsonAsset | null = null

    start() {
        // 在Script的start中获取SDK版本号并检查是否支持RichTap振动
        RichTapHaptics.getInstance().getSDKVersion()
            .then((res) => {
              console.log(`当前SDK版本号：${res}`);
            })
        RichTapHaptics.getInstance().isSupportRichTap()
            .then((res) => {
                console.log(`是否支持RichTap振动：${res}`);
            })
    }

    // 播放振动效果
    playHaptic () {
        const params = {
            // 获取json文件内容，并转成字符串
            he: JSON.stringify(this.heJson.json),
            loop: 1,
            intensity: 255,
            interval: 0,
            frequency: 0
        }
        RichTapHaptics.getInstance().playHaptic(params)
    }

    // 停止振动
    stopHaptic () {
        RichTapHaptics.getInstance().stopHaptic()
    }

    // 调整振动参数
    updateHapticParams () {
        const params = {
            intensity: 255,
            interval: 0,
            frequency: 0
        }
        RichTapHaptics.getInstance().updateHapticParams(params)
    }

    // 播放预制效果
    playPrebaked () {
        RichTapHaptics.getInstance().playPrebaked(PrebakedEffectName.RT_BOMB)
    }

    // 初始化SDK
    initSDK () {
        RichTapHaptics.getInstance().init()
    }

    // 销毁SDK
    destroySDK () {
        RichTapHaptics.getInstance().quit()
    }

    update(deltaTime: number) {

    }
}