Cocos2d-x Android 开发完整教程

本教程将涵盖从环境搭建、项目创建、编写代码到最终在 Android 设备上运行的全过程。

目录

1. 第一部分：环境准备

   • 1 安装 Java Development Kit (JDK)
   • 2 安装 Android Studio
   • 3 安装 Cocos2d-x Creator
   • 4 配置环境变量
   • 5 验证安装

2. 第二部分：创建你的第一个项目

   • 1 使用 Cocos Creator 创建项目
   • 2 构建生成 Android 工程
   • 3 在 Android Studio 中打开项目

3. 第三部分：理解项目结构

   • 1 Cocos Creator 侧 (assets 目录)
   • 2 Android Studio 侧 (proj.android-studio 目录)

4. 第四部分：编写代码与运行

   
   （图片来源网络，侵删）
   • 1 修改游戏逻辑 (在 Cocos Creator 中)
   • 2 同步代码到 Android 工程
   • 3 在 Android Studio 中编译并运行
   • 4 调试技巧

5. 第五部分：深入与进阶

   • 1 使用 C++ 编写游戏逻辑
   • 2 资源管理
   • 3 处理输入事件 (触摸、键盘)

6. 第六部分：常见问题与资源

第一部分：环境准备

在开始之前,你需要安装以下软件。

1 安装 Java Development Kit (JDK)

Cocos2d-x 使用 C++ 和 Java，因此需要 JDK。

• 下载: 访问 Oracle 官网或 Adoptium (Eclipse Temurin) 下载 JDK 8 或更高版本，Adoptium 是一个很好的开源选择。
• 安装: 运行安装程序，记住安装路径（C:\Program Files\Java\jdk-11）。
• 配置环境变量:
  1. 右键“此电脑” -> “属性” -> “高级系统设置” -> “环境变量”。
  2. 在“系统变量”中，新建 JAVA_HOME，变量值为你的 JDK 安装路径。
  3. 找到 Path 变量，点击“编辑”，新建一条 %JAVA_HOME%\bin。

2 安装 Android Studio

这是 Google 官方的 Android 开发 IDE。

• 下载: 访问 Android Studio 官网 下载并安装。
• 安装: 按照向导完成安装，在安装过程中，它会自动安装 Android SDK 和模拟器,你可以选择默认配置。
• 配置: 首次启动时，确保已安装最新的 Android SDK Platform-Tools 和构建工具。

3 安装 Cocos2d-x Creator

这是一个可视化的游戏编辑器，你将在其中设计游戏场景、编写脚本（TypeScript/JavaScript）。

• 下载: 访问 Cocos 官网 下载并安装 Cocos Creator。
• 安装: 解压并运行 CocosCreator.exe 即可。

4 配置环境变量

Cocos2d-x 的命令行工具需要这些变量才能正常工作。

1. 在“环境变量”中，新建 ANDROID_SDK_ROOT，变量值为你的 Android SDK 安装路径（C:\Users\YourUser\AppData\Local\Android\Sdk）。
2. 再次编辑 Path 变量，添加以下两条路径：
   • %ANDROID_SDK_ROOT%\platform-tools
   • %ANDROID_SDK_ROOT%\tools

5 验证安装

打开一个新的命令行窗口（CMD 或 PowerShell）,输入以下命令：

java -version
adb version
cocos -v

如果都显示了版本信息,说明环境配置成功。

第二部分：创建你的第一个项目

1 使用 Cocos Creator 创建项目

1. 打开 Cocos Creator。
2. 在欢迎界面点击“新建项目”，选择“空项目”模板，给你的项目起个名字（如 MyFirstGame），然后点击“创建”。
3. 项目创建后，你会看到一个空白的场景，在右侧的“层级管理器”中，右键点击，选择“创建 -> 2D对象 -> Sprite”。
4. 在“资源管理器”中，将一张图片（如 assets/resources/textures/hello.png）拖拽到新创建的 Sprite 节点上,这样它就能在场景中显示出来了。
5. 点击顶部菜单的“文件 -> 保存场景”，将场景保存为 main.scene。

2 构建生成 Android 工程

1. 在 Cocos Creator 主界面，点击顶部菜单的“项目 -> 构建发布”。
2. 在弹出的“构建发布”面板中：
   • 选择平台：Android。
   • 检查“构建选项”，确保 NDK 和 Android SDK 路径正确（Cocos Creator 通常能自动检测）。
   • 点击“构建”按钮。
3. Cocos Creator 会在你的项目目录下生成一个 build 文件夹，里面包含一个 android 子文件夹，这就是我们需要的原生 Android 工程。

3 在 Android Studio 中打开项目

1. 打开 Android Studio。
2. 选择“打开项目”，然后导航到你的项目目录，选择 build/android 文件夹，点击“OK”。
3. Android Studio 会自动同步 Gradle 依赖，这可能需要几分钟时间,等待完成即可。

第三部分：理解项目结构

了解两个关键目录的区别非常重要。

1 Cocos Creator 侧 (assets 目录)

这是你的和逻辑中心。

• scene/: 存放你的游戏场景文件（.scene）。
• scripts/: 存放你用 TypeScript/JavaScript 编写的游戏脚本。
• resources/: 存放游戏运行时需要动态加载的资源（图片、音频等）。注意：这个目录下的文件才会被打包进游戏。

2 Android Studio 侧 (proj.android-studio 目录)

这是平台相关的工程，负责将你的游戏打包成 APK 并运行在 Android 上。

• app/src/main/java/: 存放 Java/Kotlin 的 Android 平台适配代码,你通常不需要修改这里的代码。
• app/src/main/assets/: 这是最重要的链接！ 这个目录下的内容就是 Cocos Creator 中 assets 目录的完整拷贝,你的游戏脚本和资源都在这里。
• app/libs/: 包含了 Cocos2d-x 的核心库（.jar, .so 文件）。
• CMakeLists.txt: C++ 构建配置文件。
• build.gradle: Android 项目的构建脚本。

第四部分：编写代码与运行

1 修改游戏逻辑 (在 Cocos Creator 中)

让我们让那个 Sprite 动起来。

1. 在 Cocos Creator 中，选中刚才创建的 Sprite 节点。

2. 在右侧的“属性检查器”中，点击“添加组件 -> 自定义脚本 -> 新脚本”。

3. 给脚本起个名字，Moving.ts，然后点击“创建”。

4. 双击打开 Moving.ts 脚本,编写以下代码：

   import { _decorator, Component, Node, Vec3 } from 'cc';
   const { ccclass, property } = _decorator;
   @ccclass('Moving')
   export class Moving extends Component {
       // 定义一个速度向量
       @property(Vec3)
       speed: Vec3 = new Vec3(100, 0, 0); // 每秒向右移动100个像素
       start() {
           // 游戏开始时调用
           console.log("Moving script started!");
       }
       update(deltaTime: number) {
           // 每帧调用
           // deltaTime: 距离上一帧的时间（秒）
           let pos = this.node.position;
           pos.x += this.speed.x * deltaTime;
           this.node.position = pos;
       }
   }

5. 保存脚本，回到场景，确保 Sprite 节点已经挂载了这个 Moving 组件。

2 同步代码到 Android 工程

在 Cocos Creator 中，点击顶部菜单的“项目 -> 构建发布”，再次构建一次 Android 工程，这会把最新的脚本和资源同步到 build/android/app/src/main/assets 目录下。

3 在 Android Studio 中编译并运行

1. 在 Android Studio 顶部工具栏，选择一个模拟器（需要提前在 Android Studio 的 AVD Manager 中创建）或一个连接的 Android 设备。
2. 点击绿色的“运行”按钮（一个三角形图标）。
3. Android Studio 会编译项目并启动应用，如果一切顺利,你将在模拟器或设备上看到一个向右移动的方块。

4 调试技巧

• 日志输出: 在 Cocos Creator 中 console.log() 的内容，可以在 Android Studio 的 Logcat 窗口中查看，在 Logcat 中，你可以通过选择你的应用包名和日志级别（如 Info）来过滤日志。
• 断点调试: 你也可以在 Cocos Creator 生成的 TypeScript 代码上设置断点，进行调试（但相对复杂，通常在 Android Studio 中主要查看原生层的日志）。

第五部分：深入与进阶

1 使用 C++ 编写游戏逻辑

虽然 Cocos Creator 主要使用 TypeScript，但 Cocos2d-x 的核心是 C++，你可以通过以下方式使用 C++：

1. 在 Cocos Creator 中创建一个 C++ 组件。
2. 构建项目后，Android Studio 中会出现对应的 C++ 源文件（.cpp 和 .h）。
3. 你可以在这些文件中编写高性能的游戏逻辑，例如物理计算、AI 等。

2 资源管理

• 预加载: 在游戏开始时，使用 resources.load() 预加载关键资源,避免在游戏过程中出现卡顿。
• 图集: 将大量小图片打包成一张大图（图集），可以显著减少渲染调用,提升性能。
• 资源释放: 当不再需要资源时，使用 resources.release() 释放内存,防止内存泄漏。

3 处理输入事件

• 触摸事件: 在脚本中，你可以监听 node.on(Node.EventType.TOUCH_START, ...) 等事件来处理用户的触摸操作。
• 键盘事件: 可以通过 systemEvent.on(SystemEvent.EventType.KEY_DOWN, ...) 来监听键盘输入。

第六部分：常见问题与资源

常见问题

1. 问题: adb: command not found 或 adb 版本不匹配。

   • 解决: 检查 Path 环境变量是否正确配置了 %ANDROID_SDK_ROOT%\platform-tools,重启命令行窗口再试。

2. 问题: Android Studio 同步 Gradle 失败。

   • 解决: 检查网络连接，确保 Android Studio 和 Android SDK 已更新到最新版本，有时可能是代理问题,尝试关闭代理。

3. 问题: 游戏在 Android 设备上黑屏或崩溃。

   • 解决:
     • 查看 Logcat 中的错误日志,这是最直接的线索。
     • 检查 AndroidManifest.xml 中的权限配置。
     • 确保资源路径正确,没有拼写错误。

学习资源

• 官方文档: Cocos Creator 用户手册 是最权威、最全面的资料。
• 官方示例: Cocos Creator 自带了许多示例项目,学习它们是快速上手的最佳途径。
• 社区论坛: Cocos 官方论坛 是提问和交流的好地方。
• 视频教程: Bilibili、YouTube 上有大量由社区创作者制作的 Cocos2d-x/Cocos Creator 教程。

希望这份详细的教程能帮助你顺利开启 Cocos2d-x Android 游戏开发之旅！祝你编码愉快！