Skip to content
Dani Alias edited this page Aug 12, 2024 · 61 revisions

Frequently Asked Questions

Q. Why Axmol was born? Why a fork of Cocos2d-x? And, is it different from Cocos Creator?

A. Cocos2d-x has not received updates since 2019, and it has been confirmed that it will no longer receive further updates, as all Cocos resources have been directed to Cocos Creator (a different engine with a visual interface, similar to Unity or Godot). Axmol serves as the solution for those who wish to continue working with Cocos2d-x in an updated manner, compatible with newer hardware, while keeping it open-source.


Q. What are the changes from Cocos2d-x to Axmol Engine?

A. In this Wiki page we prepared a comparison between the two engines. For a full comprehensive list, please check the full list here.


Q. I have a Cocos2d-x project. Can I convert it to Axmol Engine?

A. Of course. We've prepared a Migration Guide in the Wiki for your reference.


Q. I have a SpriteKit project. Can I convert it to Axmol Engine?

A. We've prepared a SpriteKit to Axmol Engine guide in the Wiki for your reference.


Q. Where are CCString, CCDictonary and many other nodes I can't find?

A. They have been deprecated. Please use the Standard Template Library (STL) instead. For more deprecated nodes, please check the Migration Guide - Renamed Types section.


Q. Where are the tutorials for Axmol Engine?

A. We have prepared a comprehensive list in this same wiki: Tutorials.


Q. How can I add images, sounds and data to my game?

A. The location of the resources should be in the folder named "Content", and the build process will take care of copying those resources to the correct place. Do not add Content/ in your paths.

For adding extra folders inside the "Content" folder, you can write the full path when calling the file, or add the new paths with FileUtils::getInstance()->addSearchPath("My Folder").


Q. How can I play sounds and music inside my game?

A. Axmol Engine have AudioEngine as an audio player. Please include "audio/AudioEngine.h" in your files.


Q. I need to save my player settings. What can I do?

A. You can use UserDefaults for that task, as is the easiest solution available. For more tailored solutions, you will need to access the writable path using FileUtils::getWritablePath() in order to save your database. For example, if the settings are stored in a SQLite database, then you could either create the database at runtime in the writable path, or package one with your application (in the Contents folder) and then copy it over to the writable folder when the app first runs.


Q. How can I print to console? printf and log doesn't work.

A. UP TO axmol-2.1.2: Please use AXLOG. It works in a similar way than printf. You will need to convert any std::string with .c_str() for using them with AXLOG.

FOR axmol-2.1.3: Please use AXLOGD/AXLOGI/AXLOGW/AXLOGE. Their format is in the same style than fmtlib or C++20 std::format, and no longer requires converting std::string with .c_str() or std::string_view with .data().

  • Implemented a new logging system API: ax::setLogLevel(ax::LogLevel) and ax::setLogFmtFlag(ax::LogFmtFlag) in order to control logging level, prefix style, or to enable colorful log text.
  • axmol::log was removed. axmol::print and AXLOG are left for compatibility purposes and marked as DEPRECATED.

As an alternative for Windows, inside main.h add #define USE_WIN32_CONSOLE or inside main.cpp uncomment or add this code:

AllocConsole();
freopen("CONIN$", "r", stdin);
freopen("CONOUT$", "w", stdout);
freopen("CONOUT$", "w", stderr);

// since axmol-2.1.3 just use follow code instead above 4 lines, it will create a RAII object of `EmbedConsole` at current function execution line
#include "platform/win32/EmbedConsole.h"

AllocConsole will create a console window every time you launch your game's executable, freopen directs the stdin, stdout, and strerr to the same console window.


Q. What extensions are included with Axmol, and how can I disable the ones I don't need?

A. Axmol Engine include many extensions, like Spine2D or Live2D. Please check our Extensions Wiki page.


Q. How can I add external libraries or frameworks to my project?

A. Please check our Adding External Libraries and Frameworks page.


Q. What kind of memory management uses Axmol?

A. Axmol uses Reference Counting for historical reasons. In this Wiki, there is a comprehensive Memory Management Tutorial available for reference. As of now, there are no current plans to adopt smart pointers, but we are open to proposals.


Q. Axmol is a C++ engine, so why there is a Lua option?

A. You can choose between C++ and Lua when creating a new project. The reason for choosing Lua is because it's a faster way of prototyping and testing ideas, as there are no compilation times. It's as easy as closing and reopening the application. If you want to work simultaneously with Lua and C++ in the same project, you'll need to use toLua (more instructions here).


Q. I'm experimenting some sprite jittering issues, what can I do?

A. You can try to turn on vsync (off by default).

void AppDelegate::initGLContextAttrs()
{
    // set OpenGL context attributes: red, green, blue, alpha, depth, stencil, multisamplesCount
    GLContextAttrs glContextAttrs = {8, 8, 8, 8, 24, 8, 0};
    glContextAttrs.vsync = true;

    GLView::setGLContextAttrs(glContextAttrs);
}

For desktop apps, it can be an option for the user to turn on or off at runtime. Please be aware it adds some overhead, so for games that require very small input lag, it may not be an option.


Q. How to add Axmol as a git submodule?

A. After creating a new project, run the following commands:

git submodule add https://github.com/axmolengine/axmol axmol
git submodule init
git submodule update

This will add the "axmol" folder in your project, and CMake will automatically detect this and use it as part of your project, instead of using the Axmol installation in the environment path. This will still use the tools from the Axmol in the environment path, but if you wish to use the tools within the <project path>/axmol/tools/ path, then you have several options, such as:

Use the axmol command using the local copy, such as <project path>/axmol/tools/console/axmol build ...

or

Add a Powershell script in your local folder (in this example, it would be named axmol.ps1):

$localAxmol = (Join-Path $PSScriptRoot 'axmol/tools/console')

if (Test-Path -Path $localAxmol) {
    $scriptPath = (Join-Path $localAxmol '/axmol.ps1')
    Invoke-Expression "$scriptPath $args"
} else {
    Invoke-Expression "axmol $args"
}

Then in the project path, you the script via ./axmol (the ./ is important, since you want to run the local script). For example: ./axmol build -p win32 -c

If it detects the local axmol folder, then it will use that along with the tools within it rather than the Axmol installation in the environment path. Note that doing this will mean you may not be using the latest version of the tools, since it will utilizing the tools within the local axmol folder in the project.


Q. How can I clean third party prebuilt folders?

A. Please use git clean 3rdparty -dfx


Q. How to switch a third party mirror to gitee?

A. Create an empty file with 1k/.gitee


Q. Why ndk-r23c, and when Axmol will update the Android NDK to the latest?

A. The ndk-r23c version of the Android NDK is the last one that can build Android apps that can run on devices with Android 4.2 and later. The update to the latest version may happen be when we start using the C++23 standard (expected 2026~2029+).


Q. What does the name Axmol stands for?

A. The Axmol word structure is as follows:

  • a: one
  • x: unknown, or comes from Cocos2d-x
  • mol: molecule
  • Pronunciation: /æksmoʊl/
  • Axmol is an engine with various low level capabilities, like molecules in our real world.

Q. How can I contribute with the project or make a donation?

A. Please check our How to Contribute page.


Q. I have a question that is not in the FAQ. What can I do?

A. You can search for more questions in GitHub Discussions. If you can't find it there, please read here some indications about how to make questions.

Clone this wiki locally