2022-12-17 16:32:20 +08:00
< p align = "center" > < a href = "https://axmolengine.github.io/axmol" target = "_blank" rel = "noopener noreferrer" > < img width = "160" src = "docs/logo.png" alt = "axmol logo" > < / a > < / p >
2023-03-25 11:18:21 +08:00
# Axmol Engine
2021-12-31 12:12:40 +08:00
2023-03-25 08:37:51 +08:00
## A Multi-platform Engine for Desktop, XBOX (UWP) and Mobile games. (A radical fork of Cocos2d-x-4.0)
2022-10-01 16:24:52 +08:00
[](https://github.com/axmolengine/axmol/releases)
[](https://github.com/axmolengine/axmol/blob/master/LICENSE)
[](https://www.codacy.com/gh/axmolengine/axmol/dashboard?utm_source=github.com& utm_medium=referral& utm_content=axmolengine/axmol& utm_campaign=Badge_Grade)
[](https://github.com/axmolengine/axmol/pulls)
2020-11-15 17:56:03 +08:00
2022-10-01 16:24:52 +08:00
2023-03-11 23:34:10 +08:00
2023-03-25 11:18:21 +08:00
**[简体中文](README_CN.md)**
2023-03-25 08:37:51 +08:00
2023-03-11 23:34:10 +08:00
## Supported Platforms
2023-03-25 08:37:51 +08:00
2023-03-11 23:34:10 +08:00
| Build | Status (github) |
|-------|-----------------|
2023-04-02 16:04:19 +08:00
| Windows Desktop|[](https://github.com/axmolengine/axmol/actions/workflows/windows.yml)|
| Windows Desktop(Clang)|[](https://github.com/axmolengine/axmol/actions/workflows/windows-clang.yml)|
| Windows UWP|[](https://github.com/axmolengine/axmol/actions/workflows/winuwp.yml)|
2023-03-11 23:34:10 +08:00
| Android | [](https://github.com/axmolengine/axmol/actions?query=workflow%3Aandroid)|
| iOS |[](https://github.com/axmolengine/axmol/actions?query=workflow%3Aios)|
| tvOS |[](https://github.com/axmolengine/axmol/actions?query=workflow%3Atvos)|
| Linux |[](https://github.com/axmolengine/axmol/actions?query=workflow%3Alinux)|
| macOS |[](https://github.com/axmolengine/axmol/actions?query=workflow%3Aosx)|
2023-04-01 16:07:55 +08:00
## Reimplemented VideoPlayer(VideoTexture) based on Redesigned MediaEngine
| Platform | MediaEngine | Video Compress Format | Video Pixel Format | Backend |
|-----------------------|-------------------|-----------------------|----------------------|--------------------|
| Windows Desktop | complete | H264, HEVC, VP90 | YUY2, NV12, RGB32 | IMFMediaSession |
| Windows UWP | complete | H264, HEVC, VP90 | BGR32 | IMFMediaEngine |
2023-04-02 01:51:36 +08:00
| Apple macOS | complete | H264, HEVC(hvc1) | NV12, BGR32 | AVFoundation |
| Apple tvOS | complete | H264, HEVC(hvc1) | NV12, BGR32 | AVFoundation |
| Apple iOS | in progress | H264, HEVC(hvc1) | NV12, BGR32 | AVFoundation |
2023-04-01 16:07:55 +08:00
| Android | planned | H264 | RGB32 | |
2021-06-08 22:52:31 +08:00
2022-12-20 11:31:52 +08:00
### View code with vscode online
2022-10-01 16:24:52 +08:00
- [](https://github1s.com/axmolengine/axmol)
- [](https://vscode.dev/github/axmolengine/axmol)
2022-08-18 09:13:09 +08:00
### Thirdparty
2022-12-20 11:31:52 +08:00
- All thirdparty prebuilt libs are built from < https: // github . com / axmolengine / buildware > via github actions automatically.
2020-08-04 16:48:47 +08:00
2022-02-10 14:22:41 +08:00
### Highlighted Features
2022-12-20 11:31:52 +08:00
2023-03-11 23:08:08 +08:00
- Windows UWP support, refer to: https://github.com/axmolengine/axmol/pull/1108
2022-12-20 11:31:52 +08:00
- Add apple M1, android x64 support, contributed by @pietpukkel
- Improve windows workflow, support linking with engine prebuilt libs, read [windows workflow guide ](https://github.com/axmolengine/axmol/issues/564 )
- Windows video player support (based on microsoft media foundation)
- Windows x64 build support
- Reimplement HttpClient based on yasio for concorrent http requests processing.
- ['Upstream-Version-License' ](thirdparty/README.md ) Third-party
- Third-party license overview for easier publishing of your commercial apps based on axmol framework.
- Some links to third party libs which support axmol too.
- ['Upstream-Version-License' ](extensions/README.md ) Extensions
- Extensions license overview for easier publishing of your commercial apps based on axmol framework.
- Spine-3.8 support
- ```FairyGUI``` support
- DragonBones support
- Live2D support
- **ImGui integrated, easy to write game embedded tools, very easy to use, read [ImGui ](extensions/ImGui/README.md ) for more info**
- Refactor AudioEngine, OpenAL for all platforms
- [OpenAL Soft ](https://github.com/kcat/openal-soft ), pass -DAX_USE_ALSOFT=ON to cmake to force enabling it
- [OpenAL.framework ](https://opensource.apple.com/tarballs/OpenAL ), if no ```AX_USE_ALSOFT``` option specified, cmake script will choose it on osx/ios/tvos, even though it was marked as deprecated, but still available.
- Refactor UserDefault with [mio ](https://github.com/mandreyel/mio )
- Modularize all optional extensions, move from engine core folder to an extensions folder
- Implement all .wav formats supported by ```OpenAL Soft```, such as MS-ADPCM, ADPCM, ...
- Use a modern GL loader ```Glad```
- Google [angle ](https://github.com/google/angle ) renderer backend support
- C++ 17/20
- IOS/TVOS SDK 9.0 as minimal deployment
- Use fast pugixml
- Use [curl ](https://github.com/curl/curl ) for transferring data with URL syntax
- Use SAX parser for all plist files
- ASTC 4x4/6x6/8x8 support (if hardware decoding is not supported, then software decoding is used)
- ETC2 RGB/RGBA support (if hardware decoding is not supported, then software decoding is used)
- Supported 2D physics engines (see also [APPENDIX.md ](APPENDIX.md )):
- Box2D
- Box2D-optimized
- Chipmunk2D
- Supported 3D physics engines:
- Bullet Physics SDK
2019-11-25 10:22:58 +08:00
2022-02-24 17:57:08 +08:00
[Read Full changes since cocos2d-x-4.0 ](CHANGELOG )
2022-10-01 16:24:52 +08:00
Open [APPENDIX.md ](APPENDIX.md ) for additional information and see [Milestones ](https://github.com/axmolengine/axmol/milestones ) for planed features too.
2020-11-19 13:48:12 +08:00
2020-11-19 14:18:00 +08:00
### Quick Start
2020-11-19 14:34:08 +08:00
#### Common Requirement [Python](https://www.python.org/downloads/)
2022-12-20 11:31:52 +08:00
2023-02-13 17:52:05 +08:00
- Python-3.7+
2020-08-05 18:31:24 +08:00
2020-10-22 16:58:56 +08:00
#### Prerequisites
2022-12-20 11:31:52 +08:00
2022-11-27 22:57:06 +08:00
1. Enter `axmol` root directory
2. Run `python setup.py` , restart the console after it has finished for environment variables to take effect
#### Creating A New Project
2022-12-20 11:31:52 +08:00
2023-03-10 22:11:17 +08:00
Using a console window, an example of a command to generate a new project is as follows:
2022-11-27 22:57:06 +08:00
2023-03-10 22:11:17 +08:00
```axmol new -p YOUR.UNIQUE.ID -d PROJECT_PATH -l [cpp|lua] [--portrait] PROJECT_NAME```
Type `axmol new --help` at the command line for more options you can pass to `axmol new`
2022-11-27 22:57:06 +08:00
Examples:
- Cpp: `axmol new -p org.axmol.hellocpp -d D:\dev\projects\ -l cpp --portrait HelloCpp`
- Lua: `axmol new -p org.axmol.hellolua -d D:\dev\projects\ -l lua --portrait HelloLua`
2020-10-22 16:58:56 +08:00
2021-11-23 20:16:36 +08:00
#### Windows (64/32 bit Visual Studio 2019/2022)
2022-12-20 11:31:52 +08:00
2022-10-11 10:40:39 +08:00
1. Install [CMake ](https://cmake.org/ ) 3.22.1+
2022-02-10 03:15:53 +08:00
2. Install Visual Studio 2019/2022 (it's recommended that you only use these versions)
2022-11-27 22:57:06 +08:00
3. Create a new project as shown [here ](#creating-a-new-project )
4. In a console window, navigate into the root directory of the project you created in the previous step
5. Generate the relevant Visual Studio project using the cmake command:
```cmake -S SOURCE_DIR -B BUILD_DIR -G VISUAL_STUDIO_VERSION_STRING -A [Win32|x64]```
2022-12-20 11:31:52 +08:00
2022-11-27 22:57:06 +08:00
For example, say `SOURCE_DIR` is the current path `"."` , and `BUILD_DIR` (out-of-source build directory) is named `"build"` :
a) C++ 20:
- for 32 bit Visual Studio 2019:
```cmake -S . -B build -G "Visual Studio 16 2019" -A Win32```
- for 64 bit Visual Studio 2019:
```cmake -S . -B build -G "Visual Studio 16 2019" -A x64```
- for 32 bit Visual Studio 2022:
```cmake -S . -B build -G "Visual Studio 17 2022" -A Win32```
- for 64 bit Visual Studio 2022:
```cmake -S . -B build -G "Visual Studio 17 2022" -A x64```
2022-12-20 11:31:52 +08:00
2022-11-27 22:57:06 +08:00
b) C++17
2022-12-20 11:31:52 +08:00
- add `-DCMAKE_CXX_STANDARD=17` for C++17 on your command line like:
cmake -S . -B build `-DCMAKE_CXX_STANDARD=17` -G "Visual Studio 17 2022" -A x64
2023-03-11 22:10:18 +08:00
2022-11-27 22:57:06 +08:00
6. Use Visual Studio to open the newly created solution file. For example, `./build/ProjectName.sln`
2023-03-11 22:10:18 +08:00
#### Windows UWP (Visual Studio 2022), because microsoft limit, only support C++17
2023-03-14 08:24:27 +08:00
```cmake -B build_uwp -DCMAKE_SYSTEM_NAME=WindowsStore "-DCMAKE_SYSTEM_VERSION=10.0" "-DAX_VS_DEPLOYMENT_TARGET=10.0.17763.0"```
2023-03-11 22:10:18 +08:00
2023-04-28 07:02:33 +08:00
##### Creating the Visual Studio solution for all axmol test projects (Win/UWP)
2022-12-20 11:31:52 +08:00
2023-04-28 07:02:33 +08:00
- Perform steps 1.-6. or the Windows UWP step above (if not done)
7. Open the solution (".\build\axmol.sln" or ".\build_uwp\axmol.sln") in Visual Studio and build any of the test projects via the IDE.
2022-12-20 11:31:52 +08:00
2022-07-06 23:27:15 +08:00
#### Improve 'Visual Studio' workflow, support linking with engine prebuilt libs
2022-12-20 11:31:52 +08:00
2022-10-01 16:24:52 +08:00
See [windows workflow guide ](https://github.com/axmolengine/axmol/issues/564 )
2021-09-17 16:11:45 +08:00
2020-08-04 11:23:36 +08:00
#### Android
2022-08-06 19:29:04 +08:00
##### With Android Studio
2022-12-20 11:31:52 +08:00
2022-01-28 12:47:05 +08:00
1. Install Android Studio 2021.1.1+
2022-11-27 22:57:06 +08:00
2. When starting Android Studio for the first time, it will guide you to install the SDK and other tools, so ensure that you do install them.
3. Start Android and choose [Open an existing Android Studio Project] and select your project. For example, the existing cpp-test project located in ```axmol\tests\cpp-tests\proj.android```
2022-02-10 03:15:53 +08:00
4. Start Android Studio and Open [Tools][SDKManager], then switch to ```SDK Tools```, check the ```Show Package Details```, choose the following tools and click the button ```Apply``` to install them:
2022-12-20 11:31:52 +08:00
- Android SDK Platform 33
2023-04-20 08:54:24 +08:00
- Android Gradle Plugin (AGP) 7.4.2
2022-12-20 11:31:52 +08:00
- Android SDK Build-Tools 30.0.3 match with AGP, refer to: < https: // developer . android . com / studio / releases / gradle-plugin >
2023-04-20 08:54:24 +08:00
- Gradle 8.1
2022-12-20 11:31:52 +08:00
- NDK r23c+
- CMake 3.22.1+
2022-02-10 03:15:53 +08:00
5. Wait for ```Gradle sync``` finish.
2022-12-20 11:31:52 +08:00
6. Note: If you use non-sdk provided CMake edition, you will need to download ```ninja``` from < https: // github . com / ninja-build / ninja / releases > , and copy ```ninja.exe``` to cmake's bin directory
2022-08-06 19:29:04 +08:00
##### Without Android Studio
2022-12-20 11:31:52 +08:00
2023-04-20 08:54:24 +08:00
1. Download command-tools from < https: // developer . android . com / studio # command-tools > , for example: https://dl.google.com/android/repository/commandlinetools-win-9477386_latest.zip
2022-08-06 19:29:04 +08:00
2. Install Android devtools (for example in windows)
2022-12-20 11:31:52 +08:00
2022-08-06 19:29:04 +08:00
```bat
# unzip command-tools at D:\dev\adt\
# Install android devtools
cd D:\dev\adt\
mkdir sdk
.\cmdline-tools\bin\sdkmanager.bat --verbose --sdk_root=D:\dev\adt\sdk "platform-tools" "cmdline-tools;latest" "platforms;android-33" "build-tools;30.0.3" "cmake;3.22.1" "ndk;23.2.8568313"
set ANDROID_HOME=D:\dev\adt\sdk
# Goto xxx\proj.android
.\gradlew.bat assembleRelease -PPROP_BUILD_TYPE=cmake -PPROP_APP_ABI=arm64-v8a --parallel --info
```
2020-02-07 17:17:50 +08:00
2022-09-05 14:13:52 +08:00
#### iOS, tvOS and macOS
2022-12-20 11:31:52 +08:00
2022-06-17 22:16:55 +08:00
1. Ensure xcode12+ & [cmake3.21+ ](https://github.com/Kitware/CMake/releases ) are installed, install cmake command line support: ```sudo "/Applications/CMake.app/Contents/bin/cmake-gui" --install```
2022-11-27 22:57:06 +08:00
2. Create a new project as shown [here ](#creating-a-new-project )
3. In a console window, navigate into the root directory of the project you created in the previous step
2022-12-20 11:31:52 +08:00
4. Execute the following command
2022-11-27 22:57:06 +08:00
```sudo xcode-select -switch /Applications/Xcode.app/Contents/Developer```
5. Generate the relevant xcode project using one of the following commands:
2022-08-18 09:13:09 +08:00
- for ios arm64:
2022-09-05 14:13:52 +08:00
```cmake -S . -B build -GXcode -DCMAKE_TOOLCHAIN_FILE=$AX_ROOT/cmake/ios.toolchain.cmake -DPLATFORM=OS64```
- for ios armv7,arm64 combined:
```cmake -S . -B build -GXcode -DCMAKE_TOOLCHAIN_FILE=$AX_ROOT/cmake/ios.toolchain.cmake -DPLATFORM=OS```
2022-08-18 09:13:09 +08:00
- for ios simulator x86_64:
2022-09-05 14:13:52 +08:00
```cmake -S . -B build -GXcode -DCMAKE_TOOLCHAIN_FILE=$AX_ROOT/cmake/ios.toolchain.cmake -DPLATFORM=SIMULATOR64```
- for tvos arm64:
```cmake -S . -B build -GXcode -DCMAKE_TOOLCHAIN_FILE=$AX_ROOT/cmake/ios.toolchain.cmake -DPLATFORM=TVOS```
- for tvos simulator x86_64:
```cmake -S . -B build -GXcode -DCMAKE_TOOLCHAIN_FILE=$AX_ROOT/cmake/ios.toolchain.cmake -DPLATFORM=SIMULATOR_TVOS```
2022-08-18 09:13:09 +08:00
- for macos x86_64(Intel)
2022-09-05 14:13:52 +08:00
```cmake -S . -B build -GXcode -DCMAKE_OSX_ARCHITECTURES=x86_64```
2022-08-18 09:13:09 +08:00
- for macos arm64(M1)
2022-09-05 14:13:52 +08:00
```cmake -S . -B build -GXcode -DCMAKE_OSX_ARCHITECTURES=arm64```
2020-08-24 16:26:12 +08:00
2022-11-27 22:57:06 +08:00
6. After cmake finishes generating, you can open the xcode project at ```build``` folder and run cpp-tests or other test targets.
7. Notes
2022-09-05 14:13:52 +08:00
- **The code signing is required to run the ios/tvos app on your device, just change the bundle identifier until the auto manage signing is solved**
2023-03-14 08:24:27 +08:00
- **axmol only provides aarm64, x86_64 prebuilt libraries for ios/tvos**
2020-07-21 23:06:01 +08:00
2020-08-04 11:23:36 +08:00
### Reference links
2022-12-20 11:31:52 +08:00
- Official Cocos2d-x Repo: < https: // github . com / cocos2d / cocos2d-x >
2023-03-08 08:10:49 +08:00
- [Some interesting related projects based on axmol ](https://github.com/axmolengine/axmol/discussions/694 )
- [Axmols contributing guide ](https://github.com/axmolengine/axmol/discussions/411 )
2021-08-27 15:47:40 +08:00
2022-10-01 16:24:52 +08:00
### The axmol Active Stats
2022-11-08 23:28:15 +08:00
