Cocos 2d-x引擎游戏适配FAQ 原创

工程和工具

如何通过命令行构建工程

• 问题描述

希望通过命令行的方式构建工程，用以搭建流水线。

• 解决方案

请参考​​命令行构建服务/应用​​。

如何将手机中的文件发送到电脑

• 问题描述

手机进行了截屏或录屏等，希望将文件传到其他设备上。

• 解决方案

请参考​​HDC使用指导​​的文件相关命令。

另外，DevEco的log模块，提供了设备截屏和日志导出功能，使用非常方便。

cke_213.png

如何在DevEco Studio打开生成的HarmonyOS NEXT工程

• 问题描述

在使用一键构建工具生成HarmonyOS NEXT工程后，怎样找到对应的HarmonyOS NEXT工程并在DevEco Studio中打开。

• 解决方案
• 方式一

将tests/cpp-tests/proj.ohos拖拽到Deveco Studio图标。

cke_214.png

• 方式二

打开DevEco Studio，选择“File > Open”，在游戏工程目录中选中tests/cpp-tests/proj.ohos。

cke_215.png

修改资源文件但相关改动并没有打进HAP包

• 问题描述

修改了资源文件，但是重新打包，没有生效。

• 解决方案1. 检查Cmake中，资源文件从游戏的Resource目录复制到proj.ohos/entry/src/main/resource/rawfile的写法，是否会在检查rawfile目录存在后，就不进行复制操作。

cke_216.png

如果是，需要删除proj.ohos/entry/src/main/resource/rawfile并重新构建。

2. 如果rawfile已体现相关变化，但HAP包仍然没有变化，可能是由于构建执行的时序问题导致，再构建一次即可。

建议对资源文件的改动后，连续构建两次。

如何将资源目录拷贝到可写目录下

• 问题描述

Cocos 2d-x中如何将HarmonyOS NEXT的资源目录rawfile下的指定文件拷贝到可写目录指定位置，以便对文件进行读写。

• 解决方案

HarmonyOS NEXT Rawfile提供操作rawfile目录和rawfile文件的功能，包括打开、遍历、搜索、读取和关闭rawfile。

1. 首先获取可读写路径，然后在可写路径下创建指定的文件夹。

FileUtils::getInstance()->getWritablePath(); // 获取HAP包的可读写路径
FileUtils::getInstance()->createDirectory(writablePath + "res"); // 在可写路径下创建res文件夹

2. 获取指定文件夹下所有文件名。

FileUtils::getInstance()->listFiles(fileDir); // 遍历rawfile中的fileDir文件获取所有文件名

listFiles中调用了底层Rawfile中的以下方法来获取目标目录下的所有文件名：

• OH_ResourceManager_OpenRawDir(const NativeResourceManager *mgr, const char *dirName)：打开rawfile目录。
• OH_ResourceManager_GetRawFileCount (RawDir *rawDir)：获取RawDir中的rawfile数量。
• OH_ResourceManager_GetRawFileName(RawDir *rawDir, int index)：通过索引来获取rawfile文件名称。
• OH_ResourceManager_CloseRawDir(RawDir *rawDir)：关闭已打开的RawDir并释放所有相关联资源。

3. 在Rawfile中按文件名搜索获取文件内容并写入到可读写路径下的文件中。

使用FileUtils中的 getDataFromFile() 获取源文件内容。

使用FileUtils中的 writeDataToFile(data, assetStoragePath) 将文件内容写入目标文件中。

4. 将以上步骤进行封装在FileUtils.cpp中。

void FileUtils::assetsFileCopy(const std::string &fileDir) const
{
    auto utils = FileUtils::getInstance();
    // 获得可写的具体文件路径
    std::string writablePath = utils->getWritablePath();
    std::vector<std::string> list = FileUtils::getInstance()->listFiles(fileDir);
    utils->createDirectory(writablePath + fileDir);
    for (int i = 0; i < list.size(); i++)
    {
        // 获取资源路径
        std::string assetsFilePath = utils->fullPathForFilename(list[i]);
        // 从资源路径拷贝到可写路径下
        if (utils->isFileExist(assetsFilePath))
        {
            auto data = utils->getDataFromFile(assetsFilePath); //读取内容
            std::string assetStoragePath = writablePath + assetsFilePath;
            utils->writeDataToFile(data, assetStoragePath); //写入
        }
        else
        {
            OHOS_LOGD("%{public}s doesn't exist", assetsFilePath.c_str());
        }
    }
}

HarmonyOS NEXT应用安装报错install failed due to grant request permissions failed

• 问题描述

设备连接DevEco studio，安装HarmonyOS NEXT应用失败，且出现如下报错：

error：install failed due to grant request permissions failed.

cke_217.png

• 问题分析

出现该问题的原因是默认应用的等级是normal，只能使用normal等级的权限，但是我们项目使用了system_basic或system_core等级的权限，所以出现该报错。

• 解决方案

针对该问题，建议我们参考​​应用/服务签名-HarmonyOS NEXT应用开发​​申请ACL提权和项目相关配置，即可解决问题。

安装游戏HAP失败，报错signature verification failed due to not trusted app source

• 问题描述

安装HAP包失败，报错signature verification failed due to not trusted app source。

• 可能原因

签名验证失败，应用未做签名或签名异常。

• 解决方案

参考​​使用真机进行调试​​重新签名打包。

安装游戏HAP失败，报错install sign info inconsistent

• 问题描述

安装HAP包失败，报错如下：

cke_218.png

• 可能原因

设备中已经安装了同包名的应用。

• 定位过程

通过如下命令查看系统中所有已安装应用内包名，识别已安装的重包名。

hdc shell bm dump -a

• 解决方案

使用如下命令卸载已安装的重包名应用。

// xxx请替换为已安装的包名
hdc uninstall xxx

编译报错error: no member named ‘VideoPlayer’ in namespace ‘cocos2d::ui’

• 问题描述

编译项目时，Build->Build Hap(s)/Build App(s)->Build App(s)，出现如下报错：

error: no member named ‘VideoPlayer’ in namespace ‘cocos2d::ui’

cke_219.png

该报错表示：cocos2d::ui的命名空间下找不到VideoPlayer。

• 可能原因

VideoPlayer的相关头文件未添加。

• 定位过程

1. 根据报错，可以发现是CocosGUIScene.cpp中使用的UIVideoPlayerTest.h出现了问题。

cke_220.png

2. 使用VS Code搜索UIVideoPlayerTest.h，可以发现CocosGUIScene.cpp中确实使用了UIVideoPlayerTest.h。

cke_221.png

3. 使用VS Code溯源搜索CocosGUIScene.cpp，可以发现CocosGUIScene.cpp是在UIScene.cpp中使用的。

cke_222.png

4. 继续观察UIScene.cpp源文件，没有CocosGUI.h相关的头文件（一般使用GUI控件首先需要加入CocosGUI.h），初步怀疑是在UIScene.h中加入的CocosGUI.h。

cke_223.png

5. 点击UIScene.h，可以看到其有添加CocosGUI.h依赖。

cke_224.png

6. 点击CocosGUI.h，可以看到CocosGUI.h包含了ui下所有相关的头文件了，但是VideoPlayer相关头文件没有加OHOS分支。

cke_225.png

• 解决方案

在CocosGUI.h中添加OHOS分支，将VideoPlayer相关头文件增加进来。

cke_226.png

DevEco Studio编译HAP包失败报错Cannot find module ‘@ohos/hvigor-ohos-plugin’ Require stack

• 问题描述

编译项目时，Build->Build Hap(s)/Build App(s)->Build App(s)，发生如下报错。

ERROR: Cannot find module ‘@ohos/hvigor-ohos-plugin’ Require stack:

cke_227.png

• 可能原因

.hvigor缓存异常。

• 定位过程

报错提示均为.hvigor下的相关文件，初步怀疑.hvigor缓存异常，尝试删除相关文件后重新编译构建。

• 解决方案

1. 删除用户目录下的.hvigor文件。

cke_228.png

2. 删除项目目录下的.hvigor文件。

cke_229.png

3. 重新编译，问题解决。

DevEco Studio签名打包报错BundleName in the project configuration does not match that in the SigningConfigs

• 问题描述

在DevEco Studio中为HarmonyOS NEXT游戏配置签名信息时，出现如下报错信息：

BundleName in the project configuration does not match that in the SigningConfigs，

cke_230.png

• 定位过程

1. 分析报错信息，原因是app.json5文件中的Bundle Name与Signing Configs窗口中的Bundle Name不一致：

• app.json5文件中的包名是com.lianyun.harmOS.huawei，也是当前HarmonyOS NEXT项目的包名。
• Signing Configs窗口中填写的包名是lianyun.harmos.huawei。

2. 在DevEco Studio中打开Signing Configs窗口，将Bundle Name修改为当前HarmonyOS NEXT项目的包名，再次打包仍旧出现同样的提示错误。

cke_231.png

3. 仔细检查Signing Configs窗口中上传的签名证书，发现Profile file(*.p7b)证书和Certpath file(*.cer)证书均与Bundle Name绑定，之前仅修改Bundle Name，但未重新上传相关联的证书文件。

• 解决方案

在Signing Configs窗口除了修改Bundle name，还需重新上传相关联的.p7b和.cer文件。

1. 在DevEco Studio中​​生成证书请求文件（.csr）和密钥库文件（.p12）​​。

2. 在AGC控制台找到当前HarmonyOS NEXT项目后：

• 上传证书请求文件（.csr）​​生成Certpath file(*.cer)证书​​。
• 上传密钥库文件（.p12）​​生成Profile file(*.p7b)证书​​。

3. 在DevEco Studio中的Signing Configs窗口中重新上传当前HarmonyOS NEXT项目的证书文件，即可成功生成签名信息。

Build hap 提示访问npm仓库404

• 问题描述

编译HAP包提示访问npm仓库404。

cke_232.png

• 解决方案

C盘用户文件夹下的.npmrc修改为：

strict-ssl=false
sslVerify=false
registry=https://repo.huaweicloud.com/repository/npm/
@ohos:registry=https://repo.harmonyos.com/npm/

安装游戏HAP包失败，报错dependent module does not exist

• 问题描述

安装HAP包报错依赖模块不存在。

cke_233.png

• 解决方案

hsp是独立打包的，因此在单独安装hap包时，需要设置同时安装HSP，参考​​运行引用HSP的使用方模块​​。

系统能力适配

如何使用RSA、AES、SHA512等加密、验签、哈希等算法

• 问题描述

如何使用RSA、AES、SHA512等加密、验签、哈希等算法。

• 解决方案

请参考​​加解密算法规格​​。

如何实现图片层叠展示

• 问题描述

希望实现图片1上方展示透明背景的图片2。

• 解决方案

请参考​​层叠布局​​。

如何打开相册选择图片

• 问题描述

在上传头像等场景下需要打开本地相册选择图片。

• 解决方案

请使用​​PhotoViewPicker​​。

如何计算MD5

• 问题描述

如何计算字符串的MD5值？是否有提供同步方式？

• 解决方案

请参考​​使用摘要操作​​，如期望提供同步方式，可使用​​三方库crypto-js​​。若输入的字符串中包含中文，务必在生成Uint8Array时，指明使用UTF-8编码方式，示例代码如下：

new Uint8Array(buffer.from(message, 'utf-8').buffer)

是否有类似sharedpreferences的键值存储功能

• 问题描述

是否有类似Android的sharedpreferences键值存储功能？

• 解决方案

请使用​​用户首选项​​。

游戏问题案例

游戏场景渲染比文字慢如何处理

• 问题描述

游戏场景渲染慢，文字已经出现，而场景还没有加载出来。

• 解决方案

纹理格式支持问题，部分压缩格式不支持，需要软解后，GPU才能进行渲染，效率低。通过​​glGetString(GL_EXTENSIONS)​​可以获得HarmonyOS NEXT支持的纹理格式。

以下为根据3.17.2版本获取到的HarmonyOS NEXT对于纹理格式的支持情况，如有未列出格式，请自行根据 glGetString(GL_EXTENSIONS) 进行判断。

渲染发白问题处理

• 问题描述

游戏画面出现渲染发白情况。

• 解决方案

使用线性色彩空间解决渲染画面发白的问题。

EGLint winAttribs[] = {EGL_GL_COLORSPACE_KHR, EGL_GL_COLORSPACE_LINEAR_KHR, EGL_NONE};

游戏上架前自检

JIT能力关闭

• 场景

使用luajit三方库。

• 原因

避免恶意软件通过滥用JIT（RWX) 内存执行任意代码，绕过应用市场审核，达到变脸目的。

• 排查方式

游戏是否在启动后闪退。

• 整改方式

1. jit.off直接关闭JIT编译（推荐）。

2. luajit 三方库中lj_arch.sh文件内的LJ_OS_NOJIT增加HarmonyOS NEXT分支，使平台LJ_OS_NOJIT为1 然后重新编译三方库luajit库。

ohaudio替换

• 原因

OpenSL ES接口，接口定义的可扩展性不足，不再能满足音频系统的能力拓展，因此当前已不再推荐应用开发者继续使用此接口进行音频功能开发，可能存在一些接口能力不足的缺陷。并且延迟较高，需要替换掉。

• 相关说明

请参考​​音频播放开发概述​​。

• 整改方式（非fmod，CRI，wwise游戏）

参考对应引擎版本对比替换掉就可以，可参考​​提交记录​​，找到游戏对应引擎中相关文件再替换。

隐私声明要求

隐私声明需满足如下要求：

操作系统描述需准确，通用版本不遗漏HarmonyOS NEXT（OAID），HarmonyOS NEXT单独版本不使用iOS、安卓等描述。

1.通用版本指App在iOS、安卓、HarmonyOS NEXT共用一份“隐私声明”，此场景要做到对HarmonyOS NEXT不遗漏。具体规则如下:

a. 设备类型/平台类型如果描述iOS、安卓，必须要提HarmonyOS NEXT。

b. 设备唯一标识/ID的情形、权限相关的描述、SDK相关的描述、个人信息相关的描述:如果描述Android ID，应该如实补充描述HarmonyOS NEXT提供的OAID、AAID、ODID或其它设备标识。

2. 单独版本指为HarmonyOS NEXT单独开发的“隐私声明”，不使用iOS、安卓等描述。具体规则如下:

a. 设备类型/平台类型不允许出现安卓、iOS描述。

b. 设备唯一标识/ID的情形、权限相关的描述、SDK相关的描述、个人信息相关的描述:不能描述Android ID等字样，应该如实补充描述HarmonyOS NEXT提供的OAID、AAID、ODID或其它设备标识。

多语言默认配置

• 问题

当前部分游戏多语言配置不合理，手机设置英文时，系统状态显示label等没有意义的词。

• 处理方式

1. 如果配置多语言目录，就要配置正确，配置有意义的词。

2. 或者选择不配置，默认使用base目录下设置兜底显示（系统语言切换英文，可以展示中文，但是不能是没有意义的词）。

• 资源使用

请参考​​资源使用​​。

冷启动图标展示

• 现象

游戏冷启动会有一个应用图标展示。

• 解决方式

1. "startWindowIcon": "$media:startIcon",------配置为白色图标。

2. "startWindowBackground": "$color:start_window_background"--配置为白色（或根据游戏首屏背景色适配）。

息屏

游戏中不操作，到手机设定的熄屏时间后会息屏，建议​​设置屏幕常亮​​。

折叠屏适配

plugin_render.cpp的OnSurfaceChanged函数，会在窗口发生变化时调用，这个函数里，会将新的窗口宽高作为参数，调用AppDelegate.cpp的applicationScreenSizeChanged函数，游戏需要在applicationScreenSizeChanged这个函数里，处理好场景的变化。请参考​​https://gitee.com/Okkkkkkkk/cocos2dx_1/commit/11beb79643af5a3d0ab216673abe71859e67625c​​。

侧滑退出确认

参考如下：

onBackPress() {
    console.log('[LIFECYCLE-Page] onBackPress');
    try {
      promptAction.showDialog({
        title: "提示",
        message: "确认退出游戏吗",
        buttons: [
          {
            text: '取消',
            // Color can be customized
            color: '#000000'
          },
          {
            text: '确认',
            // Color can be customized
            color: '#000000'
          }
        ],
      }).then(data => {
        console.info('showDialog success, click button: ' + data.index);
        if (data.index == 0) {
          console.info('showDialog click button cancel');
          return;
        } else {
          console.info('showDialog click button ok');
          this.processMgr.exit(0);
        }
      })
    } catch (error) {
      console.error(`showDialog args error code is ${error.code}, message is ${error.message}`);
    };
    return true;
  }

 更多问题可关注：

鸿蒙游戏官方网站：​​已有游戏移植-鸿蒙游戏-华为开发者联盟​​

公开课：​​华为开发者学堂​​