Migrating cocos2dx using migration tool

[PCGEngineer]

Question on axmol-migrate, when I run "./build_x64/bin/Release/axmol-migrate source --fuzzy --source-dir path/to/your/project/sources/folder" and point it to my source folder (called classes) or the project folder or any folder containing my .h and .cpp files, it prints out "axmol-migrate version 1.1.1" but changes no files. Am I missing something obvious?

Some headers like #include "ui/CocosGUI.h" isn't obvious what to replace it with. I also had a ton of cocos2d:: stuff that is littered all over, do I change all those to ax:: . Is there a list somewhere of common things that need to change, the migrating guide just says to change the namespace and that's it, but clearly there is more :)

More questions - in the default axmol hello world, what do I have to change to add spine, it seems to be different than in cocos2d. Do I still need to follow the spine cocos2dx integration direction of modifying the cmakelists.txt prior to building the project and IDE files.

Thanks! Sorry for newbie conversion questions

[rh101]

You haven't mentioned which version of Cocos2d-x your existing project is using.

Question on axmol-migrate, when I run "./build_x64/bin/Release/axmol-migrate source --fuzzy --source-dir path/to/your/project/sources/folder" and point it to my source folder (called classes) or the project folder or any folder containing my .h and .cpp files, it prints out "axmol-migrate version 1.1.1" but changes no files. Am I missing something obvious?

I'm not sure about the migration tool, as I've never used it myself, but migrating over manually is not overly time consuming, although it does depend on which version of Cocos2d-x your project is using.

Axmol is based on Cocos2d-x v4, so if your project was based on that version of Cocos2d-x, then the migration is straightforward.

If your project is based on an older version of Cocos2d-x, such as v3, then the migration may be a little more involved, as it may be if moving from Cocos2d-x v3 to v4. In some cases, it may even make sense to get a project working with Cocos2d-x v4 before migrating over to Axmol, especially if the existing project is not already using cmake.

Some headers like #include "ui/CocosGUI.h" isn't obvious what to replace it with. I also had a ton of cocos2d:: stuff that is littered all over, do I change all those to ax:: .

Opening up "ui/CocosGUI.h" in Cocos2d-x, you will see that it's simply a header that includes all the header files in the ui folder. It's not actually required, since you can simply include the headers you need in your code rather than including everything. If you look through the Axmol source, you would see that it does still exist, in core/ui/CocosGUI.h. It simply includes core/ui/axmol-ui.h, which is the equivalent file that you can use.

For the namespace, replacing cocos2d:: with ax:: is the way to go, but if you prefer to just test things out first, then add an #include "cocos2d.h", which has can be used to map certain cocos2d-x names to the axmol equivalents. One example from that header is namespace cocos2d = ax;, which would allow you to keep the cocos2d:: namespace in your files.

Is there a list somewhere of common things that need to change, the migrating guide just says to change the namespace and that's it, but clearly there is more :)

Check the wiki to see if the info in there can help. If there is any information you think should be added to the wiki in order to ease migration from Cocos2d-x, then put up a post about it here, and someone may be able to address that issue.

More questions - in the default axmol hello world, what do I have to change to add spine, it seems to be different than in cocos2d. Do I still need to follow the spine cocos2dx integration direction of modifying the cmakelists.txt prior to building the project and IDE files.

Spine, along with other extensions, are enabled via cmake, which you can read about on the wiki here. It's already part of the engine source, so you don't need to follow the Esoteric guide on integrating it. Just enable it as per the wiki instructions. Axmol has its own version of the Spine runtime too, which you can find at https://github.com/axmolengine/spine-axmol. The runtimes for Spine v3.6, 3.7, 3.8, 4.0 and 4.1 all work with Axmol, and are located in their respective branch in that repo.

[PCGEngineer]

This is excellent info thank you very much. I would suggest these exact things be added to the wiki, it's fairly sparse on migration. The specific things to manually replace, like using the new cocos2d.h file, replacing cocos2d::, and the list of equivalent header files would be great.

I'm on cocos2dx v4 thankfully

[rh101]

One thing I forgot to mention is regarding shaders. If you use custom shaders, then you'll need to migrate them over as well, since Axmol 2.x now utilizes glslcc to compile shaders for each renderer backend (OpenGL, Metal etc.). Use the existing Axmol shaders as a reference.

[PCGEngineer]

Thanks, this is great. I just have a simple cocos2dx project that uses spine, no shaders. Question on manually migrating - do I need to make a new hello world axmol project and then move my source files into it and change the namespace, or do I literally just change the namespace on my old existing project? How would it repoint to say the axmol spine instead of cocos2dx spine if I leave it in the old folder? Its not updating the cmake file or anything which is manually pointing at cocos2dx spine? I plan to do some experimenting today, make a fresh cocos2dx hello world and try both ways, and then make one with one spine thing and try both ways just to see if I can understand better what it is doing. I finally absorbed what you said above (just change namespace and thats it) so maybe it will be simpler than I am thinking. Having a duplicate cocos2dx.h that points to all the xmol functions instead is awesome, I had been commenting that out and puttting axmol.h in everywhere instead (whoops). I'll post here what I find.

[GamesStudioTwo]

Hi I migrated mine manual it wasn't that hard to do I just made new project and copied over my classes.
changed the #include "cocos2dx.h" to the #include "axmol.h" and change my "using namespace cocos2d" to "using namespace ax" then there was only about 1 to 3 thigs to update per class. It was really quite simple. I spent more time in working out how to use the migration tool with no success. for me it was really ease for me to do it manual. They have done a great job with the comments too to say
deprecated use this instead and then I think it was just right click and change and that was it. I think I only had to change 1 function manual witch was getFileData to a read a file. I'm using Android studio jellyfish. I Wish you Good luck with your migration it is really worth it.

[rh101]

Question on manually migrating - do I need to make a new hello world axmol project and then move my source files into it and change the namespace, or do I literally just change the namespace on my old existing project?

It would be much easier to create a new project in axmol, and merge your code into the new project, but, there are some things you can do to make the process much easier:

1. Create a new axmol project via axmol new etc.
2. Add that newly created project to a source control, such as a local git, svn etc., whatever you feel comfortable in using.
3. Copy all your old source code from the Classes folder in the original project to the Source folder in the axmol project. Allow it to overwrite the new AppDelegate.cpp/.h with your old version (we'll get to this later).
4. Copy all the contents of Resources in the original project to the Content folder of the axmol project.
5. If your original project uses CMake, then this will be probably the toughest part. Use a file comparison tool to compare the original CMakeLists.txt with the new one in the axmol project. If you're not comfortable with CMake, then do not copy anything across unless it is 100% obvious that it needs to be moved across. Basically, if you're not sure, then don't add the changes to the Axmol project just yet.
6. Now, since you have your new project already in source control, use the comparison tool to compare the AppDelegate.cpp and .h that you copied earlier with the one in source control. Remember the one in source control is the Axmol version, so start merging the Axmol changes into your own AppDelegate files. The alternative is that you use the Axmol version and then merge your own changes in, whatever is easier for you.
7. Assuming you're on Windows, it would be easiest to attempt to create a Windows build first, get that working, then sort out Android, iOS etc. later. So, no you run axmol build -p win32 -c -f or axmol -p win32 -c -f (in Axmol v2.1.3, you no longer need the "build" word in there) to create the Visual Studio solution. Fix any errors that may appears during the cmake build process.
8. Once the Visual Studio solution is successfully created, open it up in Visual Studio, and make sure your source files and resources are all visible in the project. If not, fix the problem (it will most likely be something in your CMakeLists.txt, so compare it with the original cocos project CMakeLists.txt). Any time you update the CMakeLists.txt, run axmol -p win32 -c -f again to regenerate the project/solution with the updates.
9. Build your project. Now is when you will fix any errors. If there are errors about missing types etc., and the file with the error already has #include "cocos2d.h", then it means the you need to manually fix whatever the issue is. For a file with an error that does not have #include "cocos2d.h", then add it to the top of that file.
10. At this point you should either have a successful build, or a few issues remaining to sort out, which shouldn't take long to fix.
11. Once the Windows build works, now you can move on to the Android. Now, here do not merge anything from your old cocos proj.android folder with the Axmol one unless you are certain you need to. Open the proj.android folder in Android Studio, and try to build. Address any issues that appear.
12. For MacOS/iOS, the same deal, only merge changes that you know you need to add. Run the axmol build command that is relevant for your MacOS/iOS target, and attempt to build in Xcode. Address any issues you run into.
13. After all of this, you should have a working Axmol build of your project.

How would it repoint to say the axmol spine instead of cocos2dx spine if I leave it in the old folder? Its not updating the cmake file or anything which is manually pointing at cocos2dx spine?

To enable Spine in your axmol project, just add this to the CMakeLists.txt:
set(AX_ENABLE_EXT_SPINE ON CACHE BOOL "Build extension spine" FORCE)

This enables whatever version Axmol has included in the source, which at the time of typing this is v4.1. If you use a different version of Spine, then you have two options. You can either follow the instructions here to use whatever version you need from that repository (Axmol has custom versions of the Spine runtime, so you can't use Esoteric's versions).

The other option is that you disable the Spine in Axmol, via this:
set(AX_ENABLE_EXT_SPINE OFF CACHE BOOL "Build extension spine" FORCE)
Then add this code to CMakeLists.txt to get whatever version of the spine runtime you need and add it directly to your project, which in this example is v3.8:

include(FetchContent)
FetchContent_Declare(
    spine
    GIT_REPOSITORY https://github.com/axmolengine/spine-axmol.git
    GIT_TAG spine38
    GIT_SHALLOW ON
    SOURCE_DIR "${CMAKE_CURRENT_LIST_DIR}/spine"
)
FetchContent_MakeAvailable(spine)

I plan to do some experimenting today, make a fresh cocos2dx hello world and try both ways, and then make one with one spine thing and try both ways just to see if I can understand better what it is doing. I finally absorbed what you said above (just change namespace and thats it) so maybe it will be simpler than I am thinking. Having a duplicate cocos2dx.h that points to all the xmol functions instead is awesome, I had been commenting that out and puttting axmol.h in everywhere instead (whoops). I'll post here what I find.

Personally, I think that updating everything to the Axmol versions is the better option in the long run, but you can do that at your own pace. The cocos2d.h header file is just meant to ease the process.

[PCGEngineer]

New question - all my ref*'s break, did it get renamed in axmol? Am I missing something?

[PCGEngineer]

Also my cc_callbacks in the menuitem images

[rh101]

ax::Ref is now ax::Object, but if for some reason you need to keep using ax::Ref, then add #include cocos2d.h to the top of the source files where you need it, since it has a mapping for the Ref to Object. Same goes for CC prefix macros, they're mapped in cocos2d.h to the AX equivalents.

[PCGEngineer]

Thanks! I'll look look at cocos2d.h more closely

[PCGEngineer]

What namespace do i use for Spine, or how do I include it (everything i can find says its already enabled in axmol). I do see a spine.h way down in extensions/runtime/includes?


Thanks!

[PCGEngineer]

Ah found it
#include <spine/spine-axmol.h>
then namespace spine works

[PCGEngineer]

Hmm it compiles in windows now but in andriod studio is dying on my first .h file with
ld: error: undefined symbol: vtable for SplashScreen
Any thoughts? Google says I'm missing a destructor or have a virtual function but the only virtual function i have is init
#ifndef Splashscreen_SCENE_H
#define Splashscreen_SCENE_H

#include "axmol.h"
#include "SplashScreen2.h"

class SplashScreen : public ax::Scene
{
public:
static ax::Scene* createScene();
virtual ~SplashScreen(){};
virtual bool init();

// a selector callback - if I ever want to add buttons - screen should flash by tho

// void menuCloseCallback(ax::Ref* pSender);

// The scene update loop
//void update(float) override;

// implement the "static create()" method manually
CREATE_FUNC(SplashScreen);

private:

void SwitchToMainMenu(float dt);

ax::Sprite* logo1;   //The splash screen!

// For display tracking
ax::Size visibleSize;
ax::Vec2 origin;

};

[PCGEngineer]

Update - I think this is because I added new .h and .cpp files to the source folder but never told andriod studio. How do I include them in the build files for the project? It's still looking for MainScene.cpp which I am not using anymore so I know it hasn't been updated. Do I have to add my new source files to the cmake or build scripts somehow? When I search files in android SDK I see the original two source files from the project in the compile commands but not my new source files. They do show up in the 'sources' tab on the left though. This is a result of making an axmol hello world and then swapping the source files behind the SDK's back from what I can tell. I can see the wrong files and not my new source files below:

[rh101]

When you add files to your project, the "ZERO_CHECK" project is automatically run to detect any chances, and if changes are detected, the cmake configuration command is run again to update the project files. This sometimes needs to be done manually, which is made easier via the axmol script, for example, axmol build -p win32 -c -f if creating a Visual Studio project.

With Android Studio, the IDE automatically updates, but only if it detects changes. You can try to use the "sync" option, as shown in this screenshot:

If that doesn't work, then the problem may be that you're using GLOB or GLOB_RECURSE in your CMakeLists.txt, which do not allow the cmake to detect any changes. The recommended option is to avoid using GLOB, and add the files explicitly to your CMakeLists.txt, which means cmake will always detect the changes. You can try it out by changing this:

file(GLOB_RECURSE GAME_HEADER
    Source/*.h Source/*.hpp
    )
file(GLOB_RECURSE GAME_SOURCE
    Source/*.cpp Source/*.c
    )

to this:

set(GAME_HEADER
    Source/AppDelegate.h
    Source/MainScene.h
    Source/SplashScreen2.h
)
set(GAME_SOURCE
    Source/AppDelegate.cpp
    Source/MainScene.cpp
    Source/SplashScreen2.cpp
)

or

set(GAME_HEADER)
set(GAME_SOURCE)

list(APPEND GAME_HEADER
    Source/AppDelegate.h
    Source/MainScene.h
    Source/SplashScreen2.h
)
list(APPEND GAME_SOURCE
    Source/AppDelegate.cpp
    Source/MainScene.cpp
    Source/SplashScreen2.cpp
)

[PCGEngineer]

It worked when I changed the cmakelists.txt to explicitly list the input files. Thanks!!

[GamesStudioTwo]

Hi m8 it should work I'm using android studio too. when
I make a new class I have to click BUILD then in the menu click Refresh Linked C++ Projects.
other wise you will have to add all manual try the new method then Refresh Linked C++ Projects.
you should be good to go.