Very excited to announce the v3.8 version
Highlights and API changes of v3.8
As promised, Cocos2d-x v3.8 have greatly improved the stability and API friendliness. On one side, we continue to improve 3D capacity by providing 3D physics collider, skybox background brush and key frame event callback in Animate3D. On another side, we have refined several core modules, including UI system, AudioEngine, FileUtils, Bindings Generator, etc.
Here is some highlighted improvements:
- 3D Module
- Added 3D physics collider
- Supported setting camera background brushes with color/depth/skybox
- Added key frame event Callback in Animate3D
- Added light map support in Terrain
- UI System
- Reimplemented and enhanced EditBox on Android
- Added ScrollViewBar for displaying a scroll bar at the side of ScrollView (JSB/Lua ready)
- Added RadioButton widget (JSB/Lua ready)
- Added HANYI FullType font support
- AudioEngine
- AudioEngine supported audio preloading
- Bound new AudioEngine in JSB
- FileUtils
- Added a set of file writing APIs: writeStringToFile, writeDataToFile, writeValueMapToFile, writeValueVectorToFile
- Others
- Improved Bindings Generator tool
- Merged JSB test project into cocos2d test project
- framework: Support generate prebuilt libs of engine with debug mode
- console: Supported new portrait projects from templates
Download
Cocos2d-x v3.8 including : C++, Lua & JS
The main features in detail:
3D Module
-
3D physics collider
3D physics collider is a new type of physics object. It can be used as both trigger and collider.
Trigger is a region defined by physics shapes and can get callback when other physics objects enter or leave. Its usage is described in the following code:
//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 };Collider is similar to rigid body, it can give force to the rigid body that collides with it. However, it is static and has better performance than rigid body. It is proper to represent a static scene or objects using collider and dynamic part using rigid body. You can set colliderDes.isTrigger to false when you want to make it collider.
-
Camera background brushes
Different with previous versions, in v3.8, developers can choose to erase the camera’s background with 4 types of brush: none, color, depth, skybox. None brush means do nothing; Color brush erases background using given color and depth; depth brush erases background using given depth; skybox brush erases background using given skybox with 6 texture faces. The default brush is depth brush. The usage of brushes is showing below:
// 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 key frame event callback
Similar to 2d AnimationFrame callback, frame event callback is supported in Animated3D now. It allows developer to set a callback to be invoked when specific frame is played. Sample code:
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); -
Light map support in Terrain
Terrain with light map is supported in v3.8, which means you can add a light map texture baked from other tools to the terrain. The light map texture contains light info, so that the terrain seems to be lighted with several lights. Terrain with light map can be created like this,
//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 System
-
Reimplemented EditBox
The usage of EditBox is the same as before, but we have reimplemented it for Android platform. The use experience is highly improved, important improvements are:
- Display cursor in EditBox
- Support copy, cut, paste and select actions in EditBox
- Support multi-line input, you should set InputMode to
ANYto enable multi-line input - EditBox won’t be masked by the keyboard UI anymore
-
ScrollViewBar
In the previous versions, the ScrollView doesn’t have any visual notification for the current location in view. In v3.8, we have added a scroll bar attached to the ScrollView. You could tweak the the opacity, color, width and the duration for auto hiding the scroll bar. Speical thanks to @neokim.
Usage:
ui::ScrollView* scrollView = ui::ScrollView::create(); scrollView->setScrollBarWidth(4); scrollView->setScrollBarPositionFromCorner(Vec2(2, 2)); scrollView->setScrollBarColor(Color3B::WHITE); this->addChild(scrollView); -
RadioButton widget
RadioButton is a specific type of two-states button that is similar to CheckBox.
Additionally, it can be used together with RadioButtonGroup to interact with other radio buttons.
There is only one RadioButton in checked state at the same time within a RadioButtonGroup. Special thanks to @neokim who have contributed the implementation of this new widget.
Usage:
//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
-
Audio preloading
AudioEngine now supports preload audio files before playing it. For some large audio file, this feature can smooth the audio playing experience in user’s games. Sample code:
//Use it with callback AudioEngine::preload("audio1.mp3",[](bool isSuccess){ //... }); //Use it without callback AudioEngine::preload("audio2.mp3"); -
JSB new AudioEngine
In JSB, the default audio engine was SimpleAudioEngine (renamed to cc.audioEngine). It was the old audio engine provided since v2, and it have some inconvenience like delay time, no event support, etc. So we decided to provide new AudioEngine in JSB, the API remains the same as C++ API, and its usage can be found in its test case.
FileUtils
-
New file writing APIs
In v3.8, we have provided a bunch of file writing APIs in FileUtils. Now you can use very simple APIs to write string, binary data, value map, and value vector into a file in user’s file system. Each API is demonstrated in the following sample code:
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());Besides, you can retrieve the extension (in lower case) of a file with
FileUtils::getFileExtensionAPI.
Others
-
Bindings Generator
In v3.8, we also improved our bindings generator tool, now it’s even more powerful and be able to bind almost all kind of C++ APIs to script. Here is a detailed list about improvement in bindings generator.
- Supported generating auto bindings code for public member variables
- Avoid memory leak of non-Ref classes instance by controlling C++ object memory with JS object
- Made JSB classes automatically extendable if configured in classes_need_extend list
- Improved support for Lambda functions in JS auto bindings
-
JSB test project
In v3.8, JSB test project have been merged into C++ test project. That means cocos2d_js_tests.xcodeproj, cocos2d-js-win32.sln, cocos2d-js-win8.1-universal.sln have been removed. You can find jsb test targets in cocos2d_test.xcodeproj, cocos2d-win32.sln and cocos2d-win8.1-universal.sln.
-
Compile custom framework in debug mode
From v3.7, you was able to generate customized Cocos Framework from cocos2d-x. We have improved this ability in v3.8, now you will be able to generate framework in debug mode. Here is the some documentation about it:
-
Portrait projects support
From v3.8, you can generate portrait oriented games with Cocos Console:
cocos new -l cpp|lua|js --portrait MyPortraitGameMore details can be found in Cocos new command and Cocos Console general documentation
Other changes
- [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
You can also take a look at the full changelog
New APIs
In the above changes, there are some new APIs introduced in v3.8, they are listed here:
-
PageView vertical scroll support
PageView* pageView = PageView::create(); pageView->setContentSize(Size(240.0f, 130.0f)); pageView->setDirection(ui::PageView::Direction::VERTICAL); -
Setter for line width in DrawNode
DrawNode* drawNode = DrawNode::create(); drawNode->setLineWidth(5.0f); -
Bitwise flags of 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); -
Get current frame index in animation
auto action = RepeatForever::create( Animate::create(animation); sprite->runAction(action); sprite->scheduleOnce([=](float){ int index = action->getCurrentFrameIndex(); // ... }, 1.0f, "get-current-frame"); -
File’s extension name getter
std::string extension = FileUtils::getInstance()->getFileExtension("grossini.png"); -
Vibration support
// Virate the device for 0.5 second Device::vibrate(0.5f); -
Remove key pairs from UserDefault
// Remove value referenced by "some key" UserDefault::getInstance()->deleteValueForKey("some key");
The Next Step
In v3.9, we will continue to improve our framework, several important tasks are:
- We are about to provide a script based component system.
- Improve ScrollView, ListView performance in both native and web engine.
- Improve 2D particle system performance.
- Improve web engine renderer logic and performance.
- Support Action inheritance in JSB.
- Remove libcurl dependency on iOS and Android.
The v3.9 milestone tasks (It’s still being reviewing and will be updated)
