重要提示：Cocos2d-x 的现状

在开始之前,有几个非常重要的信息需要了解：

1. Cocos2d-x vs Cocos Creator：Cocos 官方主推的是 Cocos Creator，它是一个可视化编辑器，使用 JavaScript 或 TypeScript 进行开发，极大地提高了开发效率,是游戏开发的主流选择。
2. Cocos2d-x 的定位：传统的 Cocos2d-x 是一个 C++ 引擎，它需要你手动使用 Android Studio 来编译和打包项目，这个过程相对复杂，社区活跃度已远不如 Cocos Creator。
3. 本教程的目标：本教程主要面向那些需要使用 C++ 语言进行开发，或者有特定原因必须使用传统 Cocos2d-x 的开发者，如果您是新手，或者希望快速开发，强烈建议您直接学习 Cocos Creator。

第一部分：环境搭建 (传统 Cocos2d-x)

这是最繁琐但也是最关键的一步，我们将搭建一个完整的 Cocos2d-x 开发环境。

安装前置依赖

• Java Development Kit (JDK): 版本建议 1.8 (Java 8)，许多新版本 Cocos2d-x 对 JDK 11+ 的支持可能有问题。
  • 下载地址：Oracle JDK 8 (需要登录 Oracle 账户)
  • 验证安装：在终端/命令行中输入 java -version。
• Android SDK: Android 开发工具包。
  • 安装 Android Studio (最简单的方式)，它会自动帮你安装和管理 SDK。
  • 在 Android Studio 的 SDK Manager 中，确保安装了以下内容：
    • Android SDK Build-Tools (建议选择最新的稳定版)
    • Android SDK Platform-Tools
    • Android SDK Tools
    • 至少一个 Android SDK Platform (Android 10, API 29)。
• NDK (Native Development Kit): 用于编译 C++ 代码。
  • 在 Android Studio 的 SDK Manager -> SDK Tools 中，勾选 NDK (Side by side) 和 CMake，然后点击 Apply 安装。
  • NDK 的安装路径,后续配置需要用到。
• Apache Ant: 一个用于构建 Java 项目的工具。
  • 下载地址：Apache Ant
  • 下载后解压到一个固定路径（如 C:\ant）。
  • 配置系统环境变量：
    • 新建 ANT_HOME，值为你的 Ant 解压路径。
    • 将 %ANT_HOME%\bin 添加到 Path 变量中。
  • 验证安装：在终端/命令行中输入 ant -version。

安装 Cocos2d-x

1. 下载: 从 Cocos2d-x 的官方 GitHub 仓库下载最新稳定版。v4.0 分支。
2. 解压: 将下载的代码解压到一个不含中文和空格的路径下，D:\cocos2d-x。
3. 设置环境变量:
   • 新建系统环境变量 COCOS2DX_ROOT，值为你的 Cocos2d-x 根目录路径。
   • 将 %COCOS2DX_ROOT%\tools\cocos2d-console\bin 添加到 Path 变量中。
   • 将 %COCOS2DX_ROOT%\prebuilt\win32\bin 添加到 Path 变量中（如果你在 Windows 上开发）。
4. 验证安装: 重新打开一个终端/命令行，输入 cocos -v，如果能显示版本号,说明安装成功。

创建第一个项目

1. 打开终端/命令行,进入你想要创建项目的目录。

2. 运行以下命令：

   cocos new MyFirstGame -p com.mycompany.mygame -l cpp -d D:/MyGameProjects

   • MyFirstGame: 项目名称。
   • -p com.mycompany.mygame: 包名,用于唯一标识你的应用。
   • -l cpp: 语言，我们选择 C++。
   • -d D:/MyGameProjects: 项目创建的目录。

3. 现在你有了一个全新的 Cocos2d-x 项目，进入项目目录 D:/MyGameProjects/MyFirstGame。

   
   （图片来源网络，侵删）

编译并运行到 Android 设备/模拟器

1. 打开 Android Studio。
2. 选择 Open an existing Android Studio project，然后选择你刚刚创建的项目目录：D:/MyGameProjects/MyFirstGame/frameworks/runtime-src/android-project。
3. Android Studio 会自动同步和构建项目,这可能需要一些时间。
4. 连接 Android 设备 或启动 Android 模拟器。
5. 在 Android Studio 顶部工具栏，选择你的设备或模拟器，然后点击绿色的 "Run" 按钮 (▶)。

如果一切顺利，你的第一个 "Hello World" 游戏就会在 Android 设备上运行起来！

第二部分：核心概念与代码示例

Cocos2d-x 的核心概念与其他游戏引擎类似，主要围绕场景、层、精灵和动作。

场景

场景是游戏中的一个“舞台”，是所有游戏元素的容器，一个游戏通常有多个场景，比如主菜单场景、游戏主场景、游戏结束场景等。

创建一个新场景的步骤：

1. 创建场景类: 在 Classes 目录下创建一个新的 C++ 类，继承自 cocos2d::Scene。
2. 创建场景工厂方法: 通常会创建一个静态的 create() 方法来实例化场景和它的层。
3. 切换场景: 使用 Director::getInstance()->replaceScene() 来切换到新场景。

示例代码 (GameScene.h):

#pragma once
#include "cocos2d.h"
class GameScene : public cocos2d::Scene
{
public:
    // 使用 CREATE_FUNC 宏来创建场景实例
    CREATE_FUNC(GameScene);
    // 场景的初始化函数
    virtual bool init() override;
private:
    // 在这里声明你的游戏对象和方法
};

示例代码 (GameScene.cpp):

#include "GameScene.h"
// 场景的初始化
bool GameScene::init()
{
    if ( !Scene::init() )
    {
        return false;
    }
    // 1. 获取可视大小
    auto visibleSize = cocos2d::Director::getInstance()->getVisibleSize();
    cocos2d::Vec2 origin = cocos2d::Director::getInstance()->getVisibleOrigin();
    // 2. 创建一个背景精灵
    auto background = cocos2d::Sprite::create("HelloWorld.png");
    if (background) {
        background->setPosition(cocos2d::Vec2(visibleSize.width / 2 + origin.x, visibleSize.height / 2 + origin.y));
        this->addChild(background, 0);
    }
    // 3. 创建一个可触摸的关闭按钮
    auto closeItem = cocos2d::MenuItemImage::create(
                                           "CloseNormal.png",
                                           "CloseSelected.png",
                                           CC_CALLBACK_1(GameScene::menuCloseCallback, this));
    if (closeItem) {
        closeItem->setPosition(cocos2d::Vec2(origin.x + visibleSize.width - closeItem->getContentSize().width / 2,
                                origin.y + closeItem->getContentSize().height / 2));
        auto menu = cocos2d::Menu::create(closeItem, NULL);
        menu->setPosition(cocos2d::Vec2::ZERO);
        this->addChild(menu, 1);
    }
    return true;
}
// 关闭场景的回调函数
void GameScene::menuCloseCallback(cocos2d::Ref* pSender)
{
    // 结束程序
    cocos2d::Director::getInstance()->end();
#if (CC_TARGET_PLATFORM == CC_PLATFORM_IOS)
    exit(0);
#endif
}

精灵

精灵是游戏中显示图像的基本单位，可以是角色、背景、道具等。

创建和操作精灵：

// 创建一个精灵
auto mySprite = cocos2d::Sprite::create("player.png");
// 设置精灵的位置
mySprite->setPosition(100, 100);
// 将精灵添加到当前场景
this->addChild(mySprite);
// 让精灵旋转
mySprite->runAction(cocos2d::RotateBy::create(2.0f, 360)); // 2秒内旋转360度

动作

动作让精灵“动”起来，Cocos2d-x 提供了丰富的动作类型。

• 瞬时动作: 立即完成。
  • Show(): 显示。
  • Hide(): 隐藏。
  • Place(): 设置位置。
• 延时动作: 在一段时间内完成。
  • MoveTo/MoveBy: 移动到某个位置/从当前位置移动一定距离。
  • RotateTo/RotateBy: 旋转到某个角度/从当前角度旋转一定角度。
  • ScaleTo/ScaleBy: 缩放。
  • FadeIn/FadeOut: 淡入/淡出。
• 复合动作: 将多个动作组合起来。
  • Sequence: 按顺序执行一系列动作。
  • Spawn: 同时执行一系列动作。
  • Repeat: 重复一个动作。
  • RepeatForever: 无限重复一个动作。

示例：一个组合动作

// 创建一个序列动作：先向右移动，然后旋转，最后淡出
auto sequence = cocos2d::Sequence::create(
    cocos2d::MoveBy::create(1.0f, cocos2d::Vec2(100, 0)),
    cocos2d::RotateBy::create(0.5f, 180),
    cocos2d::FadeOut::create(1.0f),
    nullptr
);
// 让精灵执行这个序列动作
mySprite->runAction(sequence);

第三部分：项目结构

了解项目结构有助于你更好地组织代码。

MyFirstGame/
├── assets/              // 资源文件夹 (图片、音频、配置等)
├── frameworks/          // Cocos2d-x 引擎核心代码
│   └── runtime-src/
│       └── android-project/ // Android 项目的入口，用 Android Studio 打开这个
├── proj.android/       // 旧版 Android 项目结构，新版本已整合到 runtime-src/android-project
└── Classes/             // 你的 C++ 游戏逻辑代码
    ├── AppDelegate.cpp  // 应用程序入口，负责创建和切换第一个场景
    ├── AppDelegate.h
    ├── HelloWorldScene.cpp // 默认的场景
    └── HelloWorldScene.h

第四部分：发布 APK

1. 在 Android Studio 中,确保你的项目已经编译成功。
2. 点击顶部菜单的 Build -> Generate Signed Bundle / APK...。
3. 选择 APK，然后点击 Next。
4. 如果是第一次发布：
   • 选择 Create new...。
   • 填写密钥库信息 (Key store path, Password, Alias, Password)。
   • 重要: 请务必妥善保管你的密钥库文件和密码，否则你将无法更新已发布的 App。
   • 点击 OK。
5. 如果已有密钥：
   • 选择 Choose existing... 并选择你的密钥库文件。
6. 选择 release 构建类型，然后点击 Finish。
7. Android Studio 会开始构建，并在 app/build/outputs/apk/release/ 目录下生成一个签名的 APK 文件,这个文件就可以分发给用户安装了。

第五部分：学习资源与总结

官方资源

• Cocos2d-x 官方文档: https://docs.cocos2d-x.org/ (虽然有些过时,但仍然是权威参考)
• Cocos2d-x GitHub 仓库: https://github.com/cocos2d/cocos2d-x
• Cocos 官方网站: https://www.cocos.com/ (主要推广 Cocos Creator)

社区与教程

• Cocos 论坛: https://forum.cocos.org/ (可以搜索历史问题,但新帖子较少)
• 第三方博客和教程: 搜索 "Cocos2d-x Android tutorial" 可以找到一些早期的博客文章,但请注意甄别其时效性。

总结与建议

最终建议：

除非你有非常充分的理由（维护一个古老的 C++ 项目，或者对 C++ 性能有极致追求），否则 请优先选择 Cocos Creator，它能让你将 90% 的精力集中在游戏创意和玩法实现上,而不是耗费在繁琐的环境配置和编译问题上。

希望这份详细的教程能帮助你顺利入门 Cocos2d-x for Android！祝你开发愉快！