- [Misc API Changes](#user-content-misc-api-changes)
- [ccTypes.h](#user-content-cctypesh)
- [deprecated functions and global variables](#user-content-deprecated-functions-and--global-variables)
- [Changes in the Lua bindings](#user-content-changes-in-the-lua-bindings)
- [Use bindings-generator tool for lua binding](#user-content-use-bindings-generator-tool-for-lua-binding)
- [Bind the classes with namespace to lua](#user-content-bind-the-classes-with-namespace-to-lua)
- [Use ScriptHandlerMgr to manage the register and unregister of Lua function](#user-content-use-scripthandlermgr-to-manage-the-register-and-unregister-of-lua-function)
- [Misc API changes](#user-content-misc-api-changes-1)
- [Use cc、ccs、ccui gl and sp as module name](#user-content-use-ccccsccui-gl-and-sp-as-module-name)
Please refer to [ReadMe](../README.md). And there is a [document](https://github.com/chukong/cocos-docs/blob/master/manual/framework/native/getting-started/v3.0/how-to-start-a-new-game/en.md) for it.
*`CCDictionary` is replaced by `cocos2d::Map<>`, [usage](https://github.com/cocos2d/cocos-docs/blob/master/manual/framework/native/data-structure/v3/map/en.md)
*`CCArray` is replaced by `cocos2d::Vector<>`, [usage](https://github.com/cocos2d/cocos-docs/blob/master/manual/framework/native/data-structure/v3/vector/en.md)
*`CCBool`, `CCFLoat`, `CCDouble` are replaced with `cocos2d::Value`, [usage](https://github.com/cocos2d/cocos-docs/blob/master/manual/framework/native/data-structure/v3/value/en.md)
*`CallFunc` can be created with an `std::function<void()>`
*`CallFuncN` can be created with an `std::function<void(Node*)>`
*`CallFuncND` and `CallFuncO` were removed since it can be created with simulated with `CallFuncN` and `CallFunc`. See ActionsTest.cpp for more examples
*`MenuItem` supports `std::function<void(Node*)>` as callbacks
Constants and enums that started with `k`, and that usually were defined as `int` or as simple `enum` where replaced with strongly typed enums ( `enum class` ) to prevent collisions and type errors.
Because the name `Object` is confused, so rename it to `Ref`, and remove functions that are not related with reference count. All classes that inherit from `Object` now inherit from `Ref`.
The way currently cocos2d-x v2.2 does rendering is OK but it is difficult to optimize, difficult to add new functionality and difficult to port to new platforms.
So cocos2d-x v3.0 has a new renderer that is more performing, elegant, scalable, flexible but still simple to use and to understand. Also existing cocos2d-x users will find the new API familiar and they will feel immediately comfortable with, without having to bother about what’s changed or what's new under the hood.
- It has been decoupled from the Scene Graph. The `draw()` method, instead of "drawing" it sends a `RenderCommand` to the `Renderer`, and `Renderer` is responsible for drawing the queued `RenderCommand` commands.
-`QuadCommands` (used by `Sprite` and `ParticleSystem` objects) will be automatically batched.
-`CustomCommand` objects allow the user to use custom OpenGL code, using a API similar to v2.2
-`GroupCommand` objects allow to have "stacks" in the Renderer with different OpenGL values.
- Auto-culling for `Sprite` objects (although, technically, Auto-culling is not performed in `Renderer` code, but in the `Sprite` code)
- Global Z ordering (local Z ordering is still supported)
For detailed information, please read the following doc: [Renderer Specification document](https://docs.google.com/document/d/17zjC55vbP_PYTftTZEuvqXuMb9PbYNxRFu0EGTULPK8/edit)
Auto-batching means that the `Renderer` will package "multiple draw calls" in just one "big draw call" (AKA batch). In order to group "draw calls" certain conditions are needed:
- It only works with `QuadCommand` commands (used by Sprite and ParticleSystem objects)
- The `QuadCommands` must share the same Material ID: same Texture ID, same GLProgram and same blending function
- The `QuadCommands` must consecutive
If those conditions are met, the `Renderer` will create create a batch (one draw call) with all those `QuadCommand` objects.
In case you are unfamiliar with the OpenGL best practices, batching is very important to have decent speed in your games. The less batches (draw calls) the more performance your game is going to be.
For the moment auto-culling is only implemented on `Sprite` objects.
When the method `Sprite::draw()` is called, it will check if the `Sprite` is outside the screen. If so, it won't send the `QuadCommand` command to the `Renderer`, and thus, it will gain some performance.
A new method called `setGlobalZOrder()` / `getGlobalZOrder()` was added to `Node`, and the old methods `setZOrder()` / `getZOrder()` were renamed to `setLocalZOrder()` / `getLocalZOrder()`.
`globalZOrder` receives a `float` (and not an `int`) as argument. And this value is used to sort the `RenderCommand` objects in the `Renderer`. Lower values have higher priority over higher values. That means that a Node with a `globalZOrder` of `-10` is going to be drawn BEFORE a Node with `globalZOrder` of `10`.
In v2.2 the recommended way to have good performance was to parent `Sprite` objects to a `SpriteBatchNode` object.
Although the performance was (is still) very good by using `SpriteBatchNode` objects, they had (still have) some limitations like:
-`Sprite` objects can only have `Sprite` objects as children (if not, cocos2d-x will raise an Assert)
- You cannot add a `ParticleSystem` as a child of `Sprite`, when the `Sprite` is parented to a `SpriteBatchNode`
- As a consequence of that, you cannot use `ParallaxNode` with `Sprites` parented to `SpriteBatchNode`
- All `Sprite` objects must share the same TextureId (if not, cocos2d-x will raise an Assert)
-`Sprite` objects use the `SpriteBatchNode`'s blending function and shader.
And although v3.0 still supports `SpriteBatchNode` (with the same features and limitations), we no longer encourage its usage. Instead, we recommend to use `Sprite` objects without parenting them to a `SpriteBatchNode`.
But in order to have a very good performance in v3.0, you have to make sure that your `Sprite` objects:
- Share the same TextureId (place them in a spritesheet, like if you were using a `SpriteBatchNode`)
- Make sure all of them use the same shader and blending function (like if you were using a `SpriteBatchNode`)
If you do so, the `Sprites` will perform almost as fast as to using `SpriteBatchNode`... (about 10% slower on old devices. On newer devices the difference is almost imperceptible)
The big differences between v2.2 and v3.0 are:
-`Sprite` objects can have different Texture IDs.
-`Sprite` objects can have any kind of `Node` as children, including `ParticleSystem`.
-`Sprite` objects can have different blending functions and use different shaders.
But if you do that, the `Renderer` might not be able to batch all its children (less performant). But the game will keep running, without raising any Assert.
__To summarize__:
- Keep putting all your sprites in a big spritesheet
- Use the same Blending Function (just use the default one)
- Use the same Shader (just use the default one)
- And don't parent your sprites to a `SpriteBatchNode`
Only use `SpriteBatchNode` as the last resort, when you really need an extra (although minor) boost in performance (and you are OK with its limitations).
Detail information of `EventDispatcher` can refer to [this document](https://github.com/cocos2d/cocos-docs/blob/master/manual/framework/native/input/event-dispatcher/en.md).
In v3.0, we integrate physics engine into cocos2d-x based on [Chipmunk2D](https://chipmunk-physics.net/). By using this feature, you can create physics based games without understanding physics engine.
More detail information of this feature, please refer to [this document](https://github.com/cocos2d/cocos-docs/blob/master/manual/framework/native/physics/physics-integration/en.md)
Remove *cc* prefix for structure names in ccTypes.h, move global functions into static member functions, and move global constants into const static member variables.
In previous, the lua binding can not bind classes that have the same class name but different namespaces. In order to resolve this issue, now the metatable name of a class is changed. For example, `CCNode` will be changed to `cc.Node`. This modification will affect some APIs as follows:
When we want to add register and unregister functions of Lua function for class, we need to change the declarative and defined files and then bind to Lua.
The `XMLHttpRequest` and `physics` are in the `cc` module, the `spine` is in the `sp` module, and the `OpenGL` is in the `gl` module. Related test cases located in:
