您现在的位置是:首页 >技术杂谈 >cocos2d-2.0-rc2-x-2.0.1升级到cocos2dx3.172引擎日志网站首页技术杂谈
cocos2d-2.0-rc2-x-2.0.1升级到cocos2dx3.172引擎日志
将 Cocos2d-x 从 2.0.1 升级到 3.17.2 是一个较大的版本跨越,涉及引擎架构、API 和工具链的显著变化。以下是详细的升级步骤和注意事项:
1.首先,Cocos2d-x从2.x到3.x是一个巨大的升级,架构变化很大,API也有很多不兼容的地方。用户需要了解升级可能带来的工作量,特别是代码层面的修改。备份项目、下载新引擎、查看官方文档和发布说明。然后是新项目的创建,建议用户用3.17.2创建一个新项目,再将旧代码迁移过去,而不是直接替换引擎,这样可能更稳妥。
2.然后是代码迁移,这部分比较复杂。需要提到API的变化,比如CC前缀的移除,例如CCSprite变成Sprite,Cocos2d命名空间的使用。场景创建的差异,2.x使用CCScene,而3.x使用Scene::create()。还有回调函数的改变,比如menu_selector替换为CC_CALLBACK_1。这些具体的例子能帮助用户理解需要修改的地方。
3.资源管理方面,3.x的TextureCache和SpriteFrameCache可能有不同的用法,需要调整。内存管理部分,3.x更倾向于使用智能指针,但用户可能之前使用retain/release,需要适应新的管理方式。
4。构建系统的变化,2.x可能用makefile或旧版VS项目,而3.x转向CMake,用户需要重新配置构建环境,特别是不同平台的指南。第三方库的处理,如果项目依赖了如Box2D、Chipmunk,可能需要更新版本或调整集成方式。
5.迁移步骤中,建议逐步替换代码文件,优先处理基础组件,逐步测试。调试和测试阶段需要频繁编译,解决错误和警告,可能涉及大量API替换。最后是优化和适配,比如处理废弃API,调整UI布局,性能优化。
6.常见问题方面,编译错误可能包括头文件路径、命名空间、链接错误,需要检查路径和库版本。运行时错误可能涉及内存管理、资源加载、回调函数,建议使用调试工具。性能问题可能需要使用分析工具定位。
最后,提供额外资源,如官方迁移指南、社区论坛、示例代码,帮助用户进一步解决问题。同时提醒用户升级过程可能漫长,建议分阶段进行,保持耐心。
需要确保步骤清晰,用户能够一步步跟随,同时提醒关键点和可能遇到的困难。可能用户在实际操作中会遇到各种问题,但教程需要尽可能覆盖主要方面,帮助用户顺利完成升级。
一、准备工作
-
备份项目
- 备份当前
2.0.1
项目的完整代码、资源和配置文件。 - 使用版本控制工具(如 Git)创建独立分支。
- 备份当前
-
下载新引擎
- 从 Cocos2d-x 官方仓库 下载
3.17.2
版本源码。 - 解压并确保新引擎的编译环境(Python 2.7、CMake、NDK 等)已配置。
- 从 Cocos2d-x 官方仓库 下载
-
查阅文档
二、创建新项目
-
生成新项目模板
# 使用 Cocos 命令行工具创建新项目(需安装 cocos2d-console)
cocos new MyProject -p com.yourcompany.myproject -l cpp -d ./new_project
-
目录结构对比
- 3.17.2 的目录结构与 2.x 差异较大:
- 核心代码迁移到
cocos/2d
和cocos/base
。 - 资源管理、UI 组件、物理引擎等模块重构。
- 核心代码迁移到
- 建议将旧项目代码逐步迁移到新项目模板中,而非直接覆盖。
- 3.17.2 的目录结构与 2.x 差异较大:
三、代码迁移
1. API 适配
-
命名空间和类名变化
- 移除
CC
前缀(如CCSprite
→Sprite
,CCLayer
→Layer
)。 - 使用
cocos2d
命名空间:// 旧版本 CCSprite* sprite = CCSprite::create("image.png"); // 新版本 #include "cocos2d.h" using namespace cocos2d; Sprite* sprite = Sprite::create("image.png");
场景和层(Scene/Layer)
-
旧版:
CCScene* scene = CCScene::create(); CCLayer* layer = MyLayer::create(); scene->addChild(layer);
- 移除
新版:
auto scene = Scene::create();
auto layer = MyLayer::create();
scene->addChild(layer);
回调函数
使用 CC_CALLBACK_X
替代 menu_selector
:
// 旧版
menuItem->setTarget(this, menu_selector(MyClass::callback));
// 新版
menuItem->setCallback(CC_CALLBACK_1(MyClass::callback, this));
资源管理
- 纹理和精灵帧
- 旧版使用 `CCText 、、、、、、、、、未完继续更新!有兴趣的小伙伴可以建群互相交流!QQ:1762890
四、环境准备
1.安装依赖工具
- Python 2.7:Cocos2d-x 3.x 的构建工具依赖 Python 2.7。
- CMake:用于跨平台编译(下载地址)。
- NDK(Android开发需安装):建议使用 NDK r16b~r21。
- Java JDK(Android开发需安装):建议 JDK 8。
- Visual Studio(Windows平台):建议 VS 2017 或更高版本。
- Xcode(macOS平台):建议 Xcode 12+。
2.下载 Cocos2d-x 3.17.2
git clone -b v3.17.2 https://github.com/cocos2d/cocos2d-x.git
cd cocos2d-x
git submodule update --init # 下载子模块(如CocosDenshion, external库)
五、创建 Lua 项目
1.安装 Cocos 命令行工具
# 进入Cocos2d-x根目录 cd cocos2d-x # 安装cocos命令行工具 python setup.py # 添加环境变量(根据提示操作)
2.生成新项目
# 语法:cocos new <项目名> -p <包名> -l <语言> -d <输出目录>
cocos new MyLuaGame -p com.yourcompany.myluagame -l lua -d ~/projects
3.项目目录结构
MyLuaGame/
├── frameworks/ # 引擎核心代码和预编译库
├── res/ # 资源文件(图片、音频、配置等)
├── src/ # Lua 脚本 │
├── app/ # 入口脚本和场景管理
│ └── main.lua # 主入口文件
├── CMakeLists.txt # CMake 构建配置
└── runtime-src/ # 各平台原生代码(可选修改)
六、配置 Lua 项目
1.资源文件迁移
- 将旧项目的
Resources/
内容(图片、音频、字体等)复制到新项目的res/
目录 - 修改 Lua 脚本中的资源路径(旧版路径可能需要调整)。
2.Lua 脚本适配
API 变更适配:
-- 旧版 Cocos2d-x 2.x 的写法
local sprite = CCSprite:create("image.png")
self:addChild(sprite)
-- 新版 Cocos2d-x 3.17.2 的写法
local sprite = cc.Sprite:create("image.png")
self:addChild(sprite)
事件系统变更:
-- 旧版触摸事件
layer:registerScriptTouchHandler(function(...) end)
-- 新版事件监听
local listener = cc.EventListenerTouchOneByOne:create()
listener:registerScriptHandler(onTouchBegin, cc.Handler.EVENT_TOUCH_BEGAN)
cc.Director:getInstance():getEventDispatcher():addEventListenerWithSceneGraphPriority(listener, layer)
移除 CEGUI 依赖
Cocos2d-x 3.x 已内置强大的 UI 系统(ccui
模块),需将 CEGUI 的 UI 逻辑迁移到 Cocos UI:
-- 示例:创建一个按钮
local button = ccui.Button:create("button_normal.png", "button_pressed.png")
button:setPosition(cc.p(200, 300))
button:addClickEventListener(function(sender)
print("Button clicked!")
end)
self:addChild(button)
七、构建与运行
1.编译项目
Windows(VS2017+):
cocos compile -p win32 -m debug
Android:
cocos compile -p android -m release --android-studio
iOS:
cocos compile -p ios -m release
2.运行项目
直接使用 Cocos 命令行工具运行:
cocos run -p win32/android/ios
八、调试与优化
1.Lua 调试
使用 VSCode + LuaHelper 插件:
- 配置
.vscode/launch.json
:JSON { "version": "0.2.0", "configurations": [ { "type": "lua", "request": "attach", "name": "Cocos2d-x Debug", "port": 7003, "sourceRoot": "${workspaceFolder}/src" } ] }
- 在代码中插入断点,启动游戏后附加调试器。
2.性能优化
使用 Cocos2d-x 内置的性能分析工具:
lua
cc.Director:getInstance():setDisplayStats(true) -- 显示帧率和性能面板
九、常见问题解决
1.Lua 脚本无法加载
- 检查
res/
目录下的资源路径是否正确。 - 确认
src/main.lua
是入口文件。
2.C++ 与 Lua 绑定错误
清理并重新生成绑定文件:
cd cocos2d-x/tools/tolua
python genbindings.py
3.UI 显示异常
- 确保图片资源格式为 PNG 或 JPG,且尺寸为 2 的幂(如 512x512)。