How do I add image, sound, or data files to my new Axmol project?

[FHBlah]

Hi folks, I've created a new Axmol project. To do so, I used the documentation found here:

 https://github.com/axmolengine/axmol/blob/dev/docs/DevSetup.md#creating-a-new-project.

I created the project with the following command template:

 axmol new -p YOUR.UNIQUE.ID -d PROJECT_PATH -l [cpp|lua] [--portrait] PROJECT_NAME

and then built it for iOS using:

 axmol build -p ios -a arm64 -c.

I then opened the generated Xcode project, compiled it, and successfully ran it on my iPhone. Now, I'd like to add an image file to the project and display it as a Sprite but I'm not sure how. First, some background.

I've been a fan of the Cocos engine for a long time. To give you an idea, I published the Musical Meter suite of apps for iOS using the original Cocos2d engine. These past years, I've been immersed in the creation of a Cocos2d-x 4.0 project. When I surfaced to research ad solutions and found the Cocos2d-x community all but abandoned, you can imagine how happy I was to discover the Axmol fork and its beautiful contributors. My plan is to generate a clean Axmol project, move my source and resource files to it, and tweak until functional. The problem is that my Sprite::create("image.png") function can't seem to find the image file.

With my Cocos2d-x project for Mac, I just had to drag the image file into my Xcode project and run. With my iOS project, I had to run cmake ../.. from the proj.ios_mac/ios folder to add the new resource and then run. What's the process in Axmol? I've been through the github and Discord discussions and it was mentioned that you had to run either Axmol or cmake first but I don't know what parameters I should use. I tried rerunning the Axmol build command and a variety of cmake options but my create function always returns null. Are Axmol and cmake interchangeable? Can you go back and forth between methods?

In my Cocos project, I keep my .png's in the res folder and I have sub-folders for audio and data files. I would inform the engine about this with the following code:

FileUtils::getInstance()->addSearchPath("res");
FileUtils::getInstance()->addSearchPath("res/audio");
FileUtils::getInstance()->addSearchPath("res/data");
FileUtils::getInstance()->addSearchPath("res/translation");

Is this still a good idea? If someone could enlighten me as to the correct process, I'd really appreciate it. I expect the solution is simple given my history of overlooking the obvious. Thanks.

[rh101]

In my Cocos project, I keep my .png's in the res folder and I have sub-folders for audio and data files. I would inform the engine about this with the following code:

This is most likely the issue. The location of the resources should be in the folder named "Contents", and the build process will take care of copying those resources to the correct place.

If you need an example of the file structure required, then the axmol/tests/cpp-tests project is one project you can refer to.

Regarding the search paths, this is what you would end up with:

FileUtils::getInstance()->addSearchPath("audio");
FileUtils::getInstance()->addSearchPath("data");
FileUtils::getInstance()->addSearchPath("translation");

The root folder is already in the search path, so no need to add that. One suggestion regarding the above search path additions though is that it may be better not to do this, which means you would prefix the resources you need. For example:

AudioEngine::play2d("audio/file.mp3", loopEnabled, volume);

The reason why is to avoid filename clashes, where the file that exists in the first path checked is the one that is returned. If, for example, you have a file named "audio/file.mp3" and "data/file.mp3", then given this:

FileUtils::getInstance()->addSearchPath("audio");
FileUtils::getInstance()->addSearchPath("data");

The file that is used would be the one in "audio", not the one in "data", since "audio" is higher up in the search list. Prefixing allows you to explicitly choose which file you want.

There is an added benefit to doing this too. Let's say you offer downloadable content, or some kind of quick fixes to resources, without forcing users to download the entire application again. These would go into the writable folder, and as an example. let's say you create a folder named "dlc" in the writable folder. You then add this "dlc" path to the search list, but at the front of the list:

FileUtils::getInstance()->addSearchPath("dlc", true); // front = true

What you can now do is place any kind of downloadable content in the "dlc" path, such as "dlc/audio/file.mp3". Given that this path is at the front of the list, any time you refer to that file, such as with the following:

AudioEngine::play2d("audio/file.mp3", loopEnabled, volume);

It will use the one in the "dlc" folder instead of the one bundled in your app.

There are many uses to this, such as temporary file replacements for specific periods of the year, like a file for a specific holiday, and after that holiday is over, you would delete the "dlc" file associated with it, and your application would simply use the original resource again.

I hope that helps.

[FHBlah]

Ok, I see how the artwork in axmol/tests/cpp-tests is stored in the "Images" sub-folder and prefixed accordingly in the code:

 Sprite::create("Images/grossini_dance_atlas.png", Rect(x, y, 85, 121));

I'll use this model from now on.

Thanks for your response, rh101. Speaking for all the developers you've helped over the years, I just want to say that I admire and appreciate the work you've put into the continuation of this great game engine.

[rh101]

Thanks for your response, rh101. Speaking for all the developers you've helped over the years, I just want to say that I admire and appreciate the work you've put into the continuation of this great game engine

It's all really thanks to @halx99, for forking cocos2d-x and all the effort put into maintaining this project, and I'm supporting it because, I too, think it's a great game engine. The way I see it is that the more people who use it, the better it is for all involved; we want the engine to be around for as long as possible. :)

[FHBlah]

halx99 is my hero.

[rh101]

Are Axmol and cmake interchangeable? Can you go back and forth between methods?

They are unrelated. CMake is the build system for Axmol, so everything related to the project should be done via CMake (such as in the CMakeLists.txt file). You should never manually add any resources, source, etc. to your generated project file (xcode/visual studio etc.). Anything you want to add must go into the CMakeLists.txt.

Also, the generated build files should not be checked into any source control either, since they can be re-generate them at any time via CMake.

[FHBlah]

I'm afraid I'm still missing a piece of the puzzle, probably due to my lack of experience with CMake. In order to simplify the problem, I had moved my image file into the Content folder itself, right next to HelloWorld.png. In MainScene.cpp, I created my sprite using similar code to that used to create the HelloWorld sprite. I didn't see a need to modify CMakeLists.txt as the image file should be picked up in "content_folder". I guess my question is, once the image file is in the Content folder, I should open my Terminal, navigate to which directory, and type which command and parameters (probably CMake something something). Should I then build and run my app through Xcode or should I be doing everything using Axmol? Your patience is appreciated.

[rh101]

Any time you update source code or resources, just re-run the same command again that was initially used to generate the project build files (the axmol build ... or cmake -B .... etc.). This will re-generate the project files with references to the updated resources/source etc.. For resource updates, this is more important on platforms other than Windows, where the generated project files will contain a reference to each of the resource files, in order to copy them across to the output in post-build events etc..

Once the new project files are updated, re-open the project in the IDE and re-build it.

In cases where you change any cached option within the CMakeLists.txt, then the [build_dir]/CMakeCache.txt would need to be deleted prior to re-running the build command. otherwise the cached setting will not change.

[FHBlah]

Thanks for your instructions. After some experimenting, here's what I've found:

I build a new project using "axmol new -p com.companyname.hello7 -d ~/Documents/AxmolProjects -l cpp Hello7". I add an image file (Image01.png) in the Contents folder of the newly created axmol project. I build the project file using "axmol build -p ios -a arm64". I open the newly created project file in Xcode. I can see Image01.png in the project navigator under the Resources folder along with HelloWorld.png and the rest. If I write code to generate and display a sprite using this image, it compiles and runs on my iPhone and the sprite is displayed successfully.

So far so good. Now, using Finder, I add a second image file (Image02.png) to the Contents folder of my axmol project. I close the project and Xcode. I rebuild the project using "axmol build -p ios -a arm64". I open the project file in Xcode. I still see Image01.png in the project navigator under the Resources folder but not Image02.png. Any code that references this second image fails for obvious reasons. In short, after the initial axmol build, subsequent builds don't seem to recognize new content. Could it be my environment?

MacBook Air, 15-inch, M2, 2023
Chip: Apple M2
Memory: 8 GB
macOS: Sonoma 14.2.1
Xcode: Version 15.1
axmol-2.1.1
cmake version 3.28.1
PowerShell 7.4.1
Python 2.7.18

Also, during the axmol build process, I see the following messages:
-- AX_ENABLE_VLC_MEDIA=OFF
-- Performing Test AX_HAVE_SSE2_SWITCH
-- Performing Test AX_HAVE_SSE2_SWITCH - Failed
-- Performing Test AX_HAVE_AVX2_INTRINSICS
-- Performing Test AX_HAVE_AVX2_INTRINSICS - Failed
-- Performing Test AX_HAVE_SSE42_INTRINSICS
-- Performing Test AX_HAVE_SSE42_INTRINSICS - Failed
-- Performing Test AX_HAVE_SSE41_INTRINSICS
-- Performing Test AX_HAVE_SSE41_INTRINSICS - Failed
-- Performing Test AX_HAVE_SSE2_INTRINSICS
-- Performing Test AX_HAVE_SSE2_INTRINSICS - Failed
-- Looking for arm_neon.h
-- Looking for arm_neon.h - found
-- Performing Test AX_HAVE_NEON_INTRINSICS

I didn't think this was related but thought I'd mention it just in case.

If you need additional information or require me to perform any kind of tests to help resolve this issue, just say the word. I'm keen to get to the bottom of this and start publishing axmol powered games! Thanks.

[rh101]

Try axmol build -p ios -a arm64 -c -f

The -c is to just create the project files, but not actually compile/build anything. The -f is to force it to recreate the project files, because what most likely happened is that it detected no change in the source code, so it didn't actually recreate anything; it doesn't check if resources have changed. Sorry, I should have mentioned this earlier.

Once that is done, open the project up in Xcode, and check if you can see the updated resources. Also, it's fine if you keep the project open in Xcode while you recreate it via the axmol build command. As soon as the project files are recreated, Xcode automatically detects the change and reloads the project.

[FHBlah]

That did the trick. I'm thinking the "-f" option should be added to the "axmol build -h" documentation for... well, people like me. :-)

Thanks very much for your time, rh101.