对于刚接触鸿蒙（HarmonyOS）和CryEngine的新手来说，环境搭建是最关键的第一步。本文将以鸿蒙4.0系统（以HUAWEI MatePad Pro为例）为平台，手把手教你从0到1完成CryEngine开发环境搭建，并实现第一个3D旋转立方体项目。代码、命令、操作截图（文字描述）均适配新手，避免复杂术语，一步步跟着做即可！

一、前置准备：硬件与软件清单
硬件要求（新手友好型）

主设备：鸿蒙系统平板/手机（推荐HUAWEI MatePad Pro 13.2英寸，性能足够运行CryEngine基础项目）。

辅助工具：一台Windows电脑（用于下载引擎包，鸿蒙平板可通过“远程桌面”连接电脑操作，或直接用平板浏览器下载）。
软件与依赖（鸿蒙系统已内置部分工具）

类别 工具/依赖 说明
开发工具 DevEco Studio 4.0+ 鸿蒙官方IDE，用于后续项目管理（非必须，但推荐）。
引擎源码 CryEngine 5.1 Source 新手推荐稳定版，官网可下载（https://www.cryengine.com/）。
系统依赖 GCC、CMake、OpenGL库 编译CryEngine必需，鸿蒙基于Linux内核，终端可直接安装。

二、环境搭建：从下载到运行CryEngine编辑器

步骤1：下载CryEngine源码（鸿蒙平板操作）
打开鸿蒙平板的“浏览器”（如华为浏览器），访问https://www.cryengine.com/。

点击顶部导航栏的“Get Started”→“Download Source”，选择“CryEngine 5.1 Source”（约15GB，耐心等待下载完成）。

下载完成后，通过“文件管理”应用将压缩包移动到内部存储/CryEngine目录（避免中文路径，否则编译报错）。

步骤2：安装系统依赖（鸿蒙终端操作）

鸿蒙系统基于Linux内核，可通过“终端”安装编译所需的工具。打开平板的“终端”应用（若没有，在应用市场搜索“终端模拟器”安装），执行以下命令：

更新系统包列表（类似Windows的“更新软件源”）

sudo apt update

安装GCC编译器（编译C++代码必需）

sudo apt install build-essential -y

安装CMake（CryEngine用CMake生成编译脚本）

sudo apt install cmake -y

安装OpenGL开发库（3D渲染核心依赖）

sudo apt install libgl1-mesa-dev -y

安装FreeType字体库（游戏中文本渲染必需）

sudo apt install libfreetype6-dev -y

提示：输入命令后，终端会提示输入“用户密码”（鸿蒙平板的锁屏密码），输入后按回车继续。

步骤3：配置CryEngine环境变量（关键！）

环境变量是告诉系统“CryEngine在哪里”的关键。我们需要创建一个配置文件，让系统自动识别引擎路径。
在终端中，进入CryEngine源码目录（假设你将压缩包解压到内部存储/CryEngine）：

  cd /storage/emulated/0/CryEngine  # 替换为你的实际解压路径

创建环境变量配置文件cryenv.sh：

  nano cryenv.sh  # 用nano文本编辑器新建文件（按Ctrl+X退出，Y保存）

在文件中输入以下内容（注意替换路径为你的实际路径）：

  # 设置CryEngine根目录（解压后的文件夹路径）

export CRYENGINE_ROOT=/storage/emulated/0/CryEngine

将引擎二进制目录加入系统PATH（编译后生成的可执行文件路径）

export PATH=CRYENGINE_ROOT/bin/linux-x64:PATH

保存后，让环境变量生效：

  source cryenv.sh  # 执行配置文件

步骤4：编译CryEngine源码（首次耗时较长，耐心等待）

CryEngine需要编译源码才能运行编辑器，首次编译约需30分钟（取决于平板性能）。
进入引擎的代码目录：

  cd $CRYENGINE_ROOT/Code  # 进入源码根目录

生成编译脚本（使用CMake）：

  mkdir Build && cd Build  # 创建并进入Build目录（存放编译文件）

cmake … -DCMAKE_BUILD_TYPE=Release -G “Unix Makefiles” # 生成Makefile

开始编译（-j4表示用4核CPU加速，平板通常4核）：

  make -j4  # 编译完成会提示“Build completed”

步骤5：验证安装——运行CryEngine编辑器

编译完成后，直接在终端运行编辑器：
$CRYENGINE_ROOT/Tools/CryEngine/CryEditor.sh # 启动CryEngine编辑器

若成功弹出CryEngine编辑器界面（默认加载“Sandbox”项目，界面类似3D建模软件），则环境搭建成功！

三、新手第一个项目：让立方体旋转起来

现在，我们用CryEngine创建一个简单3D场景，包含一个会旋转的立方体。

步骤1：新建CryEngine项目
在CryEngine编辑器中，点击顶部菜单“File”→“New Project”（新建项目）。

选择“Empty Project”（空项目），命名为MyFirst3DProject（项目名可自定义）。

选择项目存储路径（推荐/storage/emulated/0/CryEngine/Projects，与引擎同目录）。

步骤2：创建3D场景与立方体
在编辑器主界面，点击左侧“Entities”面板（实体面板）的“+”按钮，选择“Add Entity”（添加实体）。

在场景中点击空白处，生成一个名为NewEntity的实体（类似3D世界中的一个“物体”）。

选中NewEntity，点击右侧“Components”面板（组件面板）的“Add Component”（添加组件）→“Model”（模型组件）。

步骤3：编写Lua脚本控制立方体旋转

CryEngine支持Lua（轻量级脚本语言）和C++开发，新手推荐Lua（语法简单，易上手）。

3.1 创建脚本文件

在项目目录MyFirst3DProject/Scripts下新建文件RotateCube.lua，用记事本（或鸿蒙的“文本编辑器”）打开，输入以下代码：

– RotateCube.lua：控制立方体旋转的脚本
RotateCube = {
Init = function(self)
– 初始化时调用，仅执行一次
self.Cube = nil – 存储立方体实体的引用
end,

OnActivate = function(self)
    -- 实体激活时调用（类似“开始”按钮）
    -- 获取场景中名为“Cube”的实体（后续我们会重命名）
    self.Cube = Entity.GetByName("Cube")
    if self.Cube then
        -- 注册每帧更新事件（游戏每秒约60帧，每帧触发一次）
        self.Tick = function()
            -- 获取当前旋转角度（x,y,z轴）
            local rotation = self.Cube:GetRotation()
            -- 绕Y轴（垂直轴）旋转，每次增加0.01弧度（约0.57度）
            rotation.y = rotation.y + 0.01
            -- 设置新的旋转角度
            self.Cube:SetRotation(rotation)
        end
    else
        print("错误：未找到名为'Cube'的实体！")  -- 控制台输出错误提示
    end
end

3.2 关联脚本与实体
回到编辑器，选中场景中的NewEntity实体。

在右侧“Components”面板，点击“Add Component”→“Script”（脚本组件）。

在“Script File”下拉菜单中选择RotateCube.lua（即我们刚创建的脚本）。

选中NewEntity实体，在顶部属性面板的“Name”字段中，将实体名称改为Cube（与脚本中Entity.GetByName(“Cube”)一致）。

步骤4：运行项目，查看效果
点击编辑器顶部的“Play”按钮（▶️图标），选择“Simulate”模式（模拟运行，无需打包）。

若立方体开始缓慢旋转（绕Y轴转动），则代码生效！

四、常见问题与解决（新手必看）

问题1：编译CryEngine时提示“GL/gl.h not found”

原因：缺少OpenGL开发库，导致引擎无法编译图形渲染模块。
解决：在终端执行以下命令安装OpenGL库，然后重新编译：
sudo apt install libgl1-mesa-dev -y

问题2：运行CryEngine编辑器时卡在启动界面

原因：鸿蒙系统的GPU驱动未完全启用，或引擎渲染模式不兼容。
解决：
进入鸿蒙“设置”→“关于设备”→“开发者选项”，开启“GPU加速”（部分平板需重启生效）。

编辑引擎配置文件$CRYENGINE_ROOT/Code/Engine/Config/DefaultEngine.ini，添加以下内容：

  [Renderer]

r_GraphicsAPI=D3D11 # 尝试切换为DirectX 11（若鸿蒙支持）

问题3：Lua脚本报错“Entity.GetByName is nil”

原因：实体名称拼写错误，或脚本在实体未加载时执行。
解决：
检查实体名称是否为Cube（与脚本中的Entity.GetByName(“Cube”)完全一致，区分大小写）。

将脚本的OnActivate函数改为Init函数（确保实体初始化时立即执行）。