Skip to main content

OpenHarmony 平台支持：全局指导手册

December 25, 2026About 5 minUnreal EngineOpenHarmony平台移植

OpenHarmony 平台支持：全局指导手册

本手册旨在系统地指导如何在UE5.6中添加 OpenHarmony 平台的支持。整个流程遵循Epic Games推荐的平台扩展架构，并特别针对OpenHarmony的Hvigor构建系统和原生ArkNative API进行定制。

阶段一：环境准备与架构搭建

此阶段旨在建立必要的基础开发环境和源代码管理。

1.1 获取UE5.6的源码

从内部引擎源码仓库中获取UE5.6的源码：

P4 Server: <your-perforce-server>:1666

1.2 安装HarmonyOS开发环境

从华为鸿蒙官网下载DevEco Studio 集成开发环境，当前使用的版本是OpenHarmony NEXT 6.0 Release版本。

1.3 创建平台目录

在UE源码目录 Engine/Platforms/ 下创建 OpenHarmony 目录，作为所有平台特定代码的根目录。

此目录将包含平台特定的头文件、源文件、配置和构建脚本。

1.4 参考现有实现

UE4 友方项目中Harmony的支持参考：

目录内容补充说明
Build​entry\src\main\etsHarmony工程模版配置信息，方便直接进行修改
ConfigHarmony平台相关的.ini配置Harmony平台编译的配置参数信息
PluginsCompression, Media, DeviceProfile, Permission, WebBrowser, Audio, PhysXHarmony平台的扩展支持（权限、设备信息、媒体、音频接口等） 理想情况下都应内聚到Platforms/OpenHarmony/Source/Runtime/... 目录下。
ShadersLandScapeVertexFactory, Platform.ushHarmony平台特定的着色器定义，用于定义平台特定的宏和着色器模型支持。
Source/Developer引擎扩展Harmony平台 针对Engine/Source/Devloper的扩展
Source/ProgramsAutomationTool, UnrealBuildToolHarmony平台 构建流程的核心依赖
Source/RuntimeApplicationCore, Core, Engine, OpenGLDrv, RHI, Render ...Harmony平台 针对Engine 运行时核心底层代码的扩展
Source/ThirdParty三方库三方库依赖

UE5 其他平台支持参考：

  • 参考 Engine/Platforms/Android 和 UnrealBuildTool/Platforms/Android 的结构和代码，将其作为实现蓝本。
    • Harmony Os的实现早期和Android类似，友方项目也是基于Android作为参考进行的修改。
  • 参考 Switch2, PS5的平台支持，作为额外参考。

阶段二：构建系统与SDK集成 (Unreal Build Tool 扩展)

此阶段的目标是让UE的构建系统（Unreal Build Tool, UBT）能够识别OpenHarmony作为一个目标平台，并调用华为的Hvigor工具链进行编译和打包。

2.1 实现UBT扩展模块

在 OpenHarmony\Source\Programs\UnrealBuildTool 下创建以下关键C#类文件：

// 相关细节会在UBT扩展的详细文档中展开
OpenHarmonyExports.cs 
OpenHarmonyPlatformSDK.cs
OpenHarmonyProjectGenerator.cs  (用于生成IDE项目文件，如DevEco Studio可识别的配置)
OpenHarmonyToolChain.cs         (定义编译器/链接器设置，使用Hvigor工具链)
UEBuildOpenHarmony.cs           (定义编译目标规则)
UEDeployOpenHarmony.cs          (实现HAP打包和部署逻辑)
  • 确保所有这些类都在 UnrealBuildTool 命名空间内，UBT会自动识别并加载它们到UBT的Platform目录下。

2.2 对接SDK/NDK工具链

  • 添加 UnrealTargetPlatform的新平台支持
  • 添加 OpenHarmonyTargetRules
  • 在 OpenHarmonyToolChain 中实现构建工具链的支持，确保UE构建流程能够驱动OpenHarmony的原生编译器和链接器。
    • OpenHarmony使用Hvigor构建系统，与Android的Gradle有本质区别，必须实现定制化的对接逻辑。
  • 实现HAP包（HarmonyOS Application Package）的生成、签名等支持。

2.4 配置Engine.ini文件

在OpenHarmony/Config 中添加特定于OpenHarmony的配置，例如 DefaultOpenHarmonyEngine.ini，用于管理平台特定设置，如默认图形API（Vulkan）。

阶段三：核心引擎功能实现 (Runtime API对接)

此阶段是移植的核心工作，涉及将UE引擎底层的抽象层替换为OpenHarmony的原生C/C++ API (ArkNative)。

3.1 系统抽象层（HAL）对接

  • 在 Engine/Platforms/OpenHarmony/ 目录下实现文件I/O、内存管理、多线程、时间管理等基础系统功能的OpenHarmony原生实现。
  • 需要避免AOSP依赖： OpenHarmony NEXT 6.0 已完全移除AOSP兼容层，所有底层调用必须使用OpenHarmony的原生C/C++ API。

3.2 渲染接口（RHI）实现

  • 适配UE5的RHI（Rendering Hardware Interface）到OpenHarmony支持的Vulkan API。管理渲染上下文的创建、交换链和命令缓冲区的处理。
  • 确保着色器编译器能够生成与OpenHarmony GPU架构兼容的SPIR-V或特定格式的着色器代码。
  • 密切关注华为提供的游戏引擎集成视频和文档，特别是关于图形和系统底层API的部分。

3.3 输入与事件处理

  • 实现触摸输入、传感器、键盘/手柄输入事件的捕获，并将其正确注入到UE的输入系统中。
  • 需要监听OpenHarmony的事件回调机制，并将其桥接到UE的通用输入处理框架。

3.4 第三方库兼容性检查

  • 确保所有UE依赖的第三方库（例如SQLite、zlib）都能在OpenHarmony的ARM64架构上交叉编译和链接。
  • 物理引擎注意： UE5已默认使用 Chaos 物理引擎，请确保Chaos相关模块能够顺利编译。

阶段四：插件、服务与测试

此阶段涉及集成OpenHarmony特有的系统服务，并进行全面的测试与验证。

4.1 集成系统级服务插件

  • 实现权限管理（Permission）、媒体播放（MediaPlayer）、设备信息（Device Profile）等服务的原生接口。
  • 考虑华为HMS Core的集成，例如应用内支付、联机对战服务、数据分析等，这些都需要通过特定的HarmonyOS SDK来调用。
  • 隐私合规： OpenHarmony对隐私和权限管理有严格要求，插件实现必须符合其规范。参考 华为隐私合规指南。

4.2 自动化与调试支持

  • 扩展 AutomationTool 以简化打包部署流程。确保可以在DevEco Studio或其他调试器中进行断点调试。
  • 最终的自动化打包流程应集成到 DevEco Studio 的环境中，使用其CLI工具进行最终的构建和签名，以确保与官方工具链一致。

4.3 最终测试与验证

  • 从一个最小化UE项目（如空白模板）开始测试。
  • 重点关注启动崩溃、图形初始化失败、输入无响应等早期关键问题。

4.4 HAP打包与模拟器运行

  • 确保成功生成HAP包，并能在DevEco Studio模拟器和华为真机设备上成功安装和启动应用
  • 真机测试是必不可少的，模拟器可能无法完全复现所有硬件相关的问题。

‍