cocos2d-x v3.8 发布说明

Table of Contents generated with DocToc

概况
需求
v3.8
下一步计划

概况

完整更新日记

需求

环境需求

Android 2.3 及以上
iOS 5.0 及以上
OS X 10.7 及以上
Windows 7 及以上
Windows Phone 8.1
Linux Ubuntu 14.04 及以上
现代浏览器和 IE 9+ （移动平台只有 iOS 和 Andorid 5.0 支持 WebGL）

编译需求

Xcode 5.1 及以上 (for iOS or Mac)
gcc 4.9 及以上 (for Linux)
ndk-r10c (for Android)
Visual Studio 2013 及以上 (for Windows (win32))
Visual Studio 2013 update4 及以上 (for Windows 8.1 universal Apps)
Visual Studio 2015 RC 及以上和 Windows 10.0 (build 10074 或者更高) (for Windows 10.0 UWP Apps)

如何运行测试例

Cocos Console

在大部分平台上，你可以使用 Cocos Console 命令行工具来运行测试例。

在控制台里：

// 进入 cpp test 文件夹
cd tests/cpp-tests
// 或者进入 js test 文件夹
cd tests/js-tests
// 或者进入 lua test 文件夹
cd tests/lua-tests

// 编译或者运行测试例
cocos compile -p ios|mac|android|win32|win8_1|metro|web -m debug|release
cocos run -p ios|mac|android|win32|win8_1|metro|web -m debug|release

举个例子，如果你想要在 Android 平台上以发布模式运行 cpp test，你可以使用如下命令：

cocos run -p android -m release

Mac OSX & iOS

进入 cocos2d-x/build 文件夹, 打开 cocos2d_test.xcodeproj 或者 cocos2d_js_tests.xcodeproj (JS 测试例，我们将会在v3.8合并这两个项目)
在 Xcode 的 scheme toolbar 选择 iOS 或者 OS X 平台
点击 run 按钮

Android

你可以运行一下示例...

使用命令行：

$ cd cocos2d-x
$ ./setup.py
$ cd build
$ ./android-build.py cpp-empty-test -p 10
$ adb install cocos2d-x/tests/cpp-empty-test/proj.android/bin/CppEmptyTest-debug.apk

然后点击安卓设备上的程序运行测试例，-p 指定了 Android API 等级，cocos2d-x 支持 level10 以上。

使用 Eclipse:

$ cd cocos2d-x
$ ./setup.py
$ cd build
$ ./android-build.py cpp-empty-test -p 10

然后

把 cocos2d-x Android 项目导入 Eclipse 中，导入的路径是 cocos/platform/android
把 cpp-empty-test Android 项目导入 Eclipse 中，导入的路径是 tests/cpp-empty-test/proj.android
编译 cpp-empty-test Android 项目，然后运行即可

Windows

对 win32 项目, 进入 cocos2d-x/build 目录, 然后打开 cocos2d-win32.sln 或者 cocos2d-js-win32.sln
对 win8.1 项目，进入 cocos2d-x/build 目录, 然后打开 cocos2d-win8.1-universal.sln 或者 cocos2d-js-win8.1-universal.sln
对 win 10 项目, 进入 cocos2d-x/build 目录, 然后打开 cocos2d-win10.sln
选择运行目标
点击运行按钮

Linux

$ cd cocos2d-x/build
$ ./install-deps-linux.sh
$ cd ../..

然后

$ mkdir build
$ cd build
$ cmake ../cocos2d-x
$ make -j4

运行

$ cd bin/cpp-empty-test
$ ./cpp-empty-test

如何开始一个新游戏

使用 Cocos Console 来创建一个新游戏：

cocos new -l cpp|js|lua MyGame

v3.8

v3.8亮点及 API 变更

如之前承诺的，Cocos2d-x v3.8 极大地提高了稳定性和 API 的友好性。一方面，我们持续地提升了3D功能，增加了 3D 物理碰撞，天空盒背景刷和 Animate3D 帧回调。另一方面，我们优化了多个内核模块，包括 UI 系统，声音引擎，文件模块，绑定生成器等等。

这里是一些优化的亮点和 API 变更：

3D 模块
- 添加 3D 物理碰撞器
- 支持使用颜色/深度/天空盒设置照相机的背景刷
- 添加 Animate3D 的帧回调事件
- 支持地形的光照纹理
UI 系统
- 重新实现并增强了 Android 上的 EditBox
- 支持 ScrollView 滚动条（JSB/Lua 完成）
- 添加 RadioButton 控件（JSB/Lua 完成）
- 支持汉仪 fulltype 字体
声音引擎
- AudioEngine 支持声音预加载
- 绑定 AudioEngine 到 JSB
FileUtils
- 添加一系列文件写入接口：writeStringToFile, writeDataToFile, writeValueMapToFile, writeValueVectorToFile
其他
- 优化绑定生成工具
- 合并 JSB 测试项目到 cocos2d 测试项目
- 框架：支持生成 debug 模式下的引擎预编译库
- console：支持从模板中创建竖屏项目

下载

Cocos2d-x v3.8 包含 : C++, Lua & JS

细节:

3D 模块

3D 物理碰撞器

3D 物理碰撞器是一种新的物理对象。它同时为触发器和碰撞器所用。

触发器是一块由物理形状定义的区域，当其他物理对象进入或者离开的时候会被回调。使用方法如下：
```
//create a collider using colliderDes
Physics3DColliderDes colliderDes;
colliderDes.shape = Physics3DShape::createSphere(10.0f);
colliderDes.isTrigger = true;
auto collider = Physics3DCollider::create(&colliderDes);
auto component = Physics3DComponent::create(collider);
auto node = Node::create();
addChild(node);
node->addComponent(component);

collider->onTriggerEnter = [=](Physics3DObject *otherObject){
  //some body entering
};
collider->onTriggerExit = [=](Physics3DObject *otherObject){
  //some one leaving
}; 
```
碰撞器和刚体很像，它可以对和它碰撞的刚体产生力的作用。但是它是静态的，而且比起刚体有更好的性能。所以对于静态的场景或者物体可以使用碰撞器，动态的物体可以使用刚体。当你想要让它碰撞的时候可以把 colliderDes.isTrigger 设置成 false。

照相机背景刷

和之前的版本不同，在 v3.8 版本中，开发者可以选择四种类型的背景刷来擦掉照相机的背景：无，颜色，深度，天空盒。无代表什么都不用；颜色刷使用给定的颜色和深度擦除背景；深度刷使用给定深度擦除背景；天空盒使用给定 6 个面的纹理天空盒擦除背景。默认的背景刷是深度背景刷。使用方式如下：

// Using none brush
_camera->setBackgroundBrush(CameraBackgroundBrush::createNoneBrush());
// Using depth brush, clear depth with 1.0
_camera->setBackgroundBrush(CameraBackgroundBrush::createDepthBrush(1.f));
// Using color brush, clear color is (1,0,0,1), depth is 1
_camera->setBackgroundBrush(CameraBackgroundBrush::createColorBrush(Color4F(1.f, 0.f, 0.f, 1.f), 1.f));
// SkyBox brush
_camera->setBackgroundBrush(CameraBackgroundBrush::createSkyboxBrush("Sprite3DTest/skybox/left.jpg", "Sprite3DTest/skybox/right.jpg","Sprite3DTest/skybox/top.jpg", "Sprite3DTest/skybox/bottom.jpg","Sprite3DTest/skybox/front.jpg", "Sprite3DTest/skybox/back.jpg"));

Animate3D 帧回调事件

和 2d 帧动画回调类似，现在 Animate3D 也支持帧回调了。它允许开发者在某一帧设置回调事件，当播放到那一帧的时候事件被调用。使用如下：

auto animation = Animation3D::create(“XX.c3b”);
auto animate = Animate3D::create(animation);
ValueMap valuemap0;//you can add some user data here, it can be used in the frame event callback
//add a callback when frame 275 is played
animate->setKeyFrameUserInfo(275, valuemap0);
        
auto listener = EventListenerCustom::create(Animate3DDisplayedNotification, [&](EventCustom* event)
{
    auto info = (Animate3D::Animate3DDisplayedEventInfo*)event->getUserData();
    
    //frame 275 is played, you can add some code here
    cocos2d::log(“frame %d”, info->frame);
});
Director::getInstance()->getEventDispatcher()->addEventListenerWithFixedPriority(listener, -1);

地形支持光照纹理

v3.8 版本开始支持地形光照纹理。也就是说你可以从其他工具中导出烘焙光照纹理添加到地形上。光照纹理包含光照信息，地形可以有多个光照。使用方式如下：

//create a normal terrain as before
Terrain::DetailMap r(“TerrainTest/dirt.jpg”),g(“TerrainTest/Grass2.jpg”),b(“TerrainTest/road.jpg”),a(“TerrainTest/GreenSkin.jpg”);
Terrain::TerrainData data(“TerrainTest/heightmap16.jpg”,”TerrainTest/alphamap.png”,r,g,b,a);
_terrain = Terrain::create(data,Terrain::CrackFixedType::SKIRT);
_terrain->setLODDistance(3.2f,6.4f,9.6f);
_terrain->setMaxDetailMapAmount(4);
_terrain->setDrawWire(false);
//set light map for the terrain
_terrain->setLightMap(“TerrainTest/Lightmap.png”);

UI 系统

EditBox 重新实现

EditBox 的使用方式和之前一样，但是 Android 平台的 EditBox 已经被重新实现过。使用体验大大提高了。主要的优化如下：
- 支持光标
- 支持拷贝，剪切，黏贴，选择操作
- 支持多行输入，可以通过设置输入模式 ANY 开启多行输入功能
- 不再被键盘 UI 修饰
ScrollView 滚动条

在之前的版本中，ScrollView 没有任何当前位置的可视标记。在 v3.8 版本中，我们给scrollView 添加了滚动条，你可以修改透明度，颜色，宽度和自动隐藏的时间。特别感谢 @neokim。

使用:
```
ui::ScrollView* scrollView = ui::ScrollView::create();
scrollView->setScrollBarWidth(4);
scrollView->setScrollBarPositionFromCorner(Vec2(2, 2));
scrollView->setScrollBarColor(Color3B::WHITE);
this->addChild(scrollView);
```

RadioButton 控件

RadioButton 是一种特殊类型的二态按钮，和 CheckBox 很像。

另外，它可以和 RadioButtonGroup 共用，可以和其他 radio 按钮很方便地交互。

在一个 RadioButtonGroup 中，同一时间只能有一个 RadioButton 处于选中状态，特别感谢 @ neokim 提供了这个新控件的实现。

使用:

//create a RadioButtonGroup
auto radioButtonGroup = RadioButtonGroup::create();
this->addChild(radioButtonGroup);

//create a RadioButton
RadioButton* radioButton1 = RadioButton::create("radio_button_off.png", "radio_button_on.png");
radioButton1->setPosition(Vec2(100,100);
this->addChild(radioButton1);

//create another RadioButton
RadioButton* radioButton2 = RadioButton::create("radio_button_off.png", "radio_button_on.png");
radioButton2->setPosition(Vec2(100,100);
this->addChild(radioButton2);

//add the RadioButtons into RadioButtonGroup
radioButtonGroup->addRadioButton(radioButton1);
radioButtonGroup->addRadioButton(radioButton2);

声音引擎

声音预加载

AudioEngine 先支持播放之前的声音文件预加载。对于一些较大的声音文件，这个特性将会提高用户的游戏体验。使用方式：
```
//Use it with callback
AudioEngine::preload("audio1.mp3",[](bool isSuccess){
    //...
});
//Use it without callback
AudioEngine::preload("audio2.mp3");
```
新声音引擎的 JSB 绑定

在 JSB 中，默认的声音引擎是 SimpleAudioEngine（已改名为 cc.audioEngine）。这是一个从 v2 版本就开始提供的老声音引擎，在一些情况下使用不方便，比如延时，比如事件支持等等。所以我们觉得提供 JSB 上的 AudioEngine，API 仍然和 C++ API 一致，使用方法可以在这里找到：测试例。

FileUtils

新的文件写入 API

在 v3.8 版本中，我们在 FileUtils 提供了一系列的文件写入 API。现在你可以使用很简答的 API 往用户文件系统的文件里写入字符串，二进制数据，键值表，数组。以下的每一个 API 的使用示例：

std::string writablePath = FileUtils::getInstance()->getWritablePath();

// FileUtils::writeStringToFile
std::string writeDataStr = "the string data will be write into a file";
std::string fullPath = writablePath + "writeStringTest.txt";
FileUtils::getInstance()->writeStringToFile(writeDataStr, fullPath.c_str());

// FileUtils::writeDataToFile
std::string writeDataStr = "the binary data will be write into a file";
Data writeData;
writeData.copy((unsigned char *)writeDataStr.c_str(), writeDataStr.size());
std::string fullPath = writablePath + "writeDataTest.txt";
FileUtils::getInstance()->writeDataToFile(writeData, fullPath.c_str()));

// FileUtils::writeValueMapToFile
std::string fullPath = writablePath + "testWriteValueMap.plist";
FileUtils::getInstance()->writeValueMapToFile(valueMap, fullPath.c_str());

// FileUtils::writeValueVectorToFile
std::string fullPath = writablePath + "testWriteValueVector.plist";
FileUtils::getInstance()->writeValueVectorToFile(valueVector, fullPath.c_str());

除此之外，你可以通过 FileUtils::getFileExtension 获取文件扩展名（小写）。

其他

绑定生成工具

在 v3.8 我们优化了绑定生成工具，现在更给力了。而且基本上可以绑定所有的 C++ 接口到脚本上。以下是一些优化细节。
- 支持生成自动绑定公有成员变量
- 避免使用 JS 对象管理非引用类型的 C++ 对象内存泄露
- 支持 classes_need_extend 列表中配置 JSB 类的自动扩展
- 优化 JSB 对 Lambda 函数的自动绑定
JSB 测试例

在 v3.8 中， JSB 测试例被合入到 C++ 测试例中，也就是说 cocos2d_js_tests.xcodeproj，cocos2d-js-win32.sln，cocos2d-js-win8.1-universal.sln 被移除了。你可以在 cocos2d_test.xcodeproj，cocos2d-win32.sln 和 cocos2d-win8.1-universal.sln 中找到 jsb 测试例的 target。
编译 debug 模式的自定义引擎预编译库

从 v3.7 开始，你可以从 cocos2d-x 中生成自定义的 Cocos Framework。在 v3.8 中我们优化了这个功能，现在你可以生成 debug 模式下的 framework。以下是使用文档：
支持竖屏项目

从 v3.8 开始，你使用 Cocos Console 生成竖屏项目：
```
cocos new -l cpp|lua|js --portrait MyPortraitGame
```
更多细节可以参考 Cocos new command 和 Cocos Console general documentation。

其他变更

[NEW] UI: Enhanced ScrollView with easing out scrolling
[NEW] UI: Added PageView vertical scroll support
[NEW] UI: Added PageView::JumpToPage API
[NEW] UI: Added a setter for line width in DrawNode
[NEW] Action: Permitted setting bitwise flags to action
[NEW] Animate: Added Animate's getCurrentFrameIndex function
[NEW] FileUtils: Added FileUtils::getFileExtension for getting file's extension name
[NEW] Device: Added vibrate support to enable vibration for a duration
[NEW] UserDefault: Supported removing key pairs from UserDefault
[NEW] spine: Supported Spine runtime 2.3 (Both native and web engine)
[NEW] console: Moved the framework-compile tools into cocos2d-console
[NEW] network: Upgrade SocketIO support to v1.x
[REFINE] 3D: Supported composite 2D/3D scene by moving UI and camera far away
[REFINE] 3D: Improved Particle3D performance
[REFINE] Label: Supported adding child nodes in Label
[REFINE] UI: Improved Slider's precision
[REFINE] UI: Refined scroll event dispatching for ScrollView
[REFINE] UI: Improved event handling in TextField
[REFINE] Label: Supported auto batch with bitmap font or char map
[REFINE] studio: Added BlendFrame support to Skeleton Animation
[REFINE] studio: Enabled blendfunc cascade to the skin of BoneNode
[REFINE] utils: Made utils::captureScreen saving file in another thread to improve the performance
[REFINE] 3rd party: Update Nibiru SDK to 2.6
[REFINE] JS: Supported new construction for 3d classes in JS
[REFINE] JS: Refine performance for Cocos Studio JSON parser for 2.x
[REFINE] web: Avoid re-bake the content when the parent node's position get changed
[REFINE] web: Solved repeat loading same resource issue when parsing cocos studio project
[REFINE] web: Optimized resources automatic loading in JSON parser
[REFINE] web: Avoid cc.loader resource loading being terminated while encounter errors
[REFINE] web: Suspended the video player when the browser is minimized

你也可以参考完整修改日志。

新的 APIs

以上的变更中，有一些新的 API 在 v3.8 中被引入，如下：

PageView 垂直滚动支持

PageView* pageView = PageView::create();
pageView->setContentSize(Size(240.0f, 130.0f));
pageView->setDirection(ui::PageView::Direction::VERTICAL);

DrawNode 线宽设置

DrawNode* drawNode = DrawNode::create();
drawNode->setLineWidth(5.0f);

action 位标识

enum Flags {
    FRAME = 1,
    COLOR = 2,
    OPACITY = 4,
    POSITION = 8,
    SCALE = 16,
    ROTATION = 32,
    SKEW = 64
};

auto action = RepeatForever::create(Sequence::create(FadeTo::create( 0.1f, 155), TintTo::create(0.1f, 255,0,0), nullptr));
// Since opacity and color will be modified in this action, it can be flagged as opacity and color action
action->setFlags(Flags::OPACITY|Flags::COLOR);

auto action2 = RepeatForever::create(Sequence::create(MoveBy::create(0.3f, Vec2(5, 0)), nullptr));
// Since position will be modified in this action, it can be flagged as position action
action->setFlags(Flags::POSITION);

获取动画当前帧索引

auto action = RepeatForever::create( Animate::create(animation);
sprite->runAction(action);
sprite->scheduleOnce([=](float){
    int index = action->getCurrentFrameIndex();
    // ...
}, 1.0f, "get-current-frame");

文件扩展名获取

std::string extension = FileUtils::getInstance()->getFileExtension("grossini.png");

震动支持

// Virate the device for 0.5 second
Device::vibrate(0.5f);

从 UserDefault 移除键值对

// Remove value referenced by "some key"
UserDefault::getInstance()->deleteValueForKey("some key");

下一步计划

在 v3.9 中，我们会持续优化引擎框架，目前有如下几项重要任务：

我们考虑提供一套基于脚本的组件系统
优化 native 和 web 引擎的 ScrollView，ListView 性能。
优化 2D 粒子系统的性能。
优化 web 引擎的渲染逻辑和性能。
支持 JSB 的 Action 继承机制。
移除 Android 和 iOS 对 libcurl 的依赖。

v3.9 里程碑（一直在审查和更新之中）

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

cocos2d-x_v3.8_release_notes.md

cocos2d-x_v3.8_release_notes.md

cocos2d-x v3.8 发布说明

概况

需求

环境需求

编译需求

如何运行测试例

Cocos Console

Mac OSX & iOS

Android

Windows

Linux

如何开始一个新游戏

v3.8

v3.8亮点及 API 变更

下载

细节:

3D 模块

UI 系统

声音引擎

FileUtils

其他

其他变更

新的 APIs

下一步计划

Files

cocos2d-x_v3.8_release_notes.md

Latest commit

History

cocos2d-x_v3.8_release_notes.md

File metadata and controls

cocos2d-x v3.8 发布说明

概况

需求

环境需求

编译需求

如何运行测试例

Cocos Console

Mac OSX & iOS

Android

Windows

Linux

如何开始一个新游戏

v3.8

v3.8亮点及 API 变更

下载

细节:

3D 模块

UI 系统

声音引擎

FileUtils

其他

其他变更

新的 APIs

下一步计划