Cocos2d‐x migration guide

Migration guide

Migrating from Cocos2d-x to Axmol Engine is straightforward. You will need to change the namespace form USING_NS_CC to USING_NS_AX, and check the Renamed Types section in this same page in order to solve the errors that may appear.

For converting Cocos2d-x v4.0 projects to Axmol Engine, it may be convenient to use the axmol-migrate tool to alleviate some workload. Please be aware this is only for convenience, not mandatory, and also older versions of Cocos2d-x (v3.x and older) may not work at all.

This is how it works:

Axmol-migrate tool

For quick fixing the header's includes of your project source code:

1. Clone https://github.com/axmolengine/axmol-migrate
2. Go to folder axmol-migrate and run pwsh ./build.ps1 -xb "'--config', 'Release'"
3. Use axmol-migrate to migrate your project sources folder ./build_x64/bin/Release/axmol-migrate source --fuzzy --source-dir path/to/your/project/sources/folder

Notes: The command line axmol-migrate.exe can fix 99% (or 100% for some projects) of your includes. After executing it, you can manually fix any compile error. The axmol-migrate can compile on Windows, MacOS and Linux.

Renamed Types

All the Cocos2d-x methods that make the same function than the Standard Template Library in modern C++ has been deprecated. For example, for CCString please use std::string instead, etc.

Axmol uses the ax namespace, which replaces the cocos2d namespace.

The <Axmol>/core/cocos2d.h header file is provided for convenience, and contains a number of Cocos2d-x to Axmol mappings for the namespace, existing types and macros. It can be used via #include "cocos2d.h" to ease migration, although it would be best to update the code over time to the Axmol naming for the sake of future compatibility and maintenance of a project.

Classes & Structs

• RngSeed => FastRNG UNDER math/FastRNG.h
• Sprite3D => MeshRenderer UNDER 3d/CCMeshRenderer.h
• Sprite3DMaterial => MeshMaterial UNDER 3d/CCMeshMaterial.h

Functions & Methods

• Director::isDisplayStats() => Director::isStatsDisplay() UNDER base/CCDirector.h

Extensions

If you need to use common extensions, such as Spine, Live2D, FairyGUI, Effekseer etc., then the extensions that are included with the Axmol source can be enabled via cmake options. Refer to this page for more information.

Shaders

Axmol 2.x now utilizes glslcc to compile shaders for each renderer backend (OpenGL, Metal etc.). Use the existing Axmol shaders as a reference in case you need to update your own shaders to the new format. The changes are describe in issue 1279.