2013-08-07 06:07:42 +08:00
< img src = "http://www.cocos2d-x.org/attachments/801/cocos2dx_portrait.png" width = 200 >
cocos2d-x
=========
2015-04-16 18:20:02 +08:00
| |iOS|Mac|Linux|Win32|Android|Win8.1-Universal|
| ----|----|----- | ---|----|------|---|
2015-09-04 09:43:45 +08:00
|v3|[![Build Status](http://45.56.80.45:8080/buildStatus/icon?job=daily-build-v3/node=ios)](http://45.56.80.45:8080/job/daily-build-v3/node=ios)|[![Build Status](http://45.56.80.45:8080/buildStatus/icon?job=daily-build-v3/node=mac)](http://45.56.80.45:8080/job/daily-build-v3/node=mac)|[![Build Status](http://45.56.80.45:8080/buildStatus/icon?job=daily-build-v3/node=linux)](http://45.56.80.45:8080/job/daily-build-v3/node=linux)|[![Build Status](http://45.56.80.45:8080/buildStatus/icon?job=daily-build-v3/node=win32_bak)](http://45.56.80.45:8080/job/daily-build-v3/node=win32_bak)|[![Build Status](http://45.56.80.45:8080/buildStatus/icon?job=daily-build-v3/node=android)](http://45.56.80.45:8080/job/daily-build-v3/node=android)|[![Build Status](http://45.56.80.45:8080/buildStatus/icon?job=daily-build-v3/node=windows-universal_bak)](http://45.56.80.45:8080/job/daily-build-v3/node=windows-universal_bak)|
2015-03-24 13:47:12 +08:00
2013-08-07 06:07:42 +08:00
[cocos2d-x][1] is a multi-platform framework for building 2d games, interactive books, demos and other graphical applications.
It is based on [cocos2d-iphone][2], but instead of using Objective-C, it uses C++.
2016-08-04 16:51:19 +08:00
It works on iOS, Android, Tizen, Windows Phone and Store Apps, OS X, Windows, Linux and Web platforms.
2013-08-07 06:07:42 +08:00
2015-07-28 17:31:14 +08:00
**Cocos2d-x Framework Architecture**:
![](docs/framework_architecture.jpg "")
2013-08-07 06:07:42 +08:00
cocos2d-x is:
* Fast
* Free
* Easy to use
2016-01-19 23:06:10 +08:00
* Community supported
2013-08-07 06:07:42 +08:00
2014-05-16 15:15:06 +08:00
Git user attention
-----------------------
2015-06-07 19:29:32 +08:00
1. Clone the repo from GitHub.
2014-09-18 01:36:00 +08:00
2015-06-07 19:29:32 +08:00
$ git clone https://github.com/cocos2d/cocos2d-x.git
2014-09-13 01:01:48 +08:00
2. After cloning the repo, please execute `download-deps.py` to download and install dependencies.
2014-05-16 15:15:06 +08:00
$ cd cocos2d-x
2015-06-11 06:49:05 +08:00
cocos2d-x $ python download-deps.py
2013-08-07 06:07:42 +08:00
2014-09-13 01:01:48 +08:00
3. After running `download-deps.py` .
2014-09-18 01:36:00 +08:00
2015-06-11 06:49:05 +08:00
cocos2d-x $ git submodule update --init
2013-08-07 06:07:42 +08:00
2015-07-16 16:53:43 +08:00
Download stable versions
-----------------------
2015-07-16 23:32:18 +08:00
* [Cocos2d-x stable versions ](http://www.cocos2d-x.org/download )
* [Cocos2d-JS Lite version ](http://www.cocos2d-x.org/filecenter/jsbuilder )
2015-07-16 16:53:43 +08:00
2013-08-07 06:07:42 +08:00
How to start a new game
-----------------------
2013-09-29 10:54:46 +08:00
1. Download the code from [cocos2d download site][4]
2014-03-06 14:44:33 +08:00
2. Run `setup.py`
3. Run the `cocos` script
2013-08-07 06:07:42 +08:00
Example:
2014-03-06 14:44:33 +08:00
$ cd cocos2d-x
$ ./setup.py
$ source FILE_TO_SAVE_SYSTEM_VARIABLE
2014-04-21 11:37:35 +08:00
$ cocos new MyGame -p com.your_company.mygame -l cpp -d NEW_PROJECTS_DIR
$ cd NEW_PROJECTS_DIR/MyGame
2013-08-07 06:07:42 +08:00
2015-07-16 16:53:43 +08:00
You can also create a JS project or Lua project with `-l js` or `-l lua` .
2014-08-05 18:03:21 +08:00
### Build and run a new project for Android ###
2014-01-07 14:09:05 +08:00
2014-03-24 23:28:03 +08:00
$ cocos run -p android -j 4
2014-01-07 14:09:05 +08:00
2014-08-05 18:03:21 +08:00
### Build and run a new project for iOS ###
2014-01-07 14:09:05 +08:00
2014-03-14 14:50:16 +08:00
$ cocos run -p ios
2015-04-16 18:20:02 +08:00
2014-08-05 18:03:21 +08:00
### Build and run a new project for OSX ###
2014-03-14 22:45:29 +08:00
$ cocos run -p mac
2014-01-07 14:09:05 +08:00
2016-08-04 16:51:19 +08:00
### Build and run a new project for Tizen ###
2017-04-05 15:49:42 +08:00
The cocos command line tools doesn't support Tizen on Windows yet, you have to use Tizen IDE to do the build.
2016-08-04 16:51:19 +08:00
Please refer to this [guide ](http://cocos2d-x.org/docs/installation/Tizen/index.html ).
2014-08-05 18:03:21 +08:00
### Build and run a new project for Linux ###
2014-01-07 14:09:05 +08:00
2015-07-16 16:53:43 +08:00
If you never run cocos2d-x on Linux, you need to install all dependencies by the
2014-01-07 14:09:05 +08:00
script in **cocos2d/build/install-deps-linux.sh**
2014-03-14 14:50:16 +08:00
$ cd cocos2d-x/build
2014-01-07 14:09:05 +08:00
$ ./install-deps-linux.sh
Then
2014-04-21 11:37:35 +08:00
$ cd NEW_PROJECTS_DIR/MyGame
2014-03-14 23:56:25 +08:00
$ cocos run -p linux
2015-04-16 18:20:02 +08:00
2014-01-07 16:25:37 +08:00
Run
2014-03-14 14:50:16 +08:00
$ bin/MyGame
2014-01-07 14:09:05 +08:00
2014-03-14 14:50:16 +08:00
### Build and run new project for win32 ###
2014-01-07 14:09:05 +08:00
2014-03-14 14:50:16 +08:00
$ cocos run -p win32
2014-01-07 14:09:05 +08:00
2015-06-20 00:08:57 +08:00
### Build and run new project for Windows 8.1/10.0 and Windows Phone 8.1/10.0 ###
2014-12-11 12:52:29 +08:00
2015-04-16 01:23:49 +08:00
$ cocos new MyGame -p com.your_company.mygame -l cpp -d projects
2014-12-11 12:52:29 +08:00
2015-06-20 00:08:57 +08:00
* Visual Studio 2013 Update 4 or later is required for Windows 8.1 Universal Apps
2015-09-12 18:16:10 +08:00
* Visual Studio 2015 (Release version) and Windows 10.0 (Release version) are required for Windows 10.0 Universal Windows Platform (UWP) Apps. RC versions of Visual Studio and Windows 10 are no longer supported.
2015-06-20 00:08:57 +08:00
Starting with Cocos2d-x v3.3, you can create Windows 8.1 Universal Apps (Windows Store and Windows Phone 8.1).
2015-08-21 02:13:17 +08:00
Starting with Cocos2d-x v3.8 you can create Windows 10.0 UWP Apps (Windows Store and Windows Phone 10.0).
2015-06-20 00:08:57 +08:00
Starting with Cocos2d-x v3.6 there will no longer be support for Windows Phone 8.0.
2015-04-16 01:23:49 +08:00
2016-01-19 23:06:10 +08:00
See more info on how to install and create games on Windows RT (Windows and Windows Phone 8.1) at http://msopentech.github.io/cocos2d-x/
2013-08-07 06:07:42 +08:00
2015-07-16 16:53:43 +08:00
### Build and run new project for web ###
Only JS project can be published to web platforms, so you will need to create a JS project first:
$ cocos new -l js WebGame
Then you can run your game in a web browser:
$ cocos run -p web
Or you can publish your game to `publish/html5/` folder:
$ cocos run -p web -m release [--advanced]
Documentations and samples
-------------
2016-04-06 04:17:52 +08:00
* [All Docs in a single place! ](http://cocos2d-x.org/docs/ )
* [Online API Reference ](http://cocos2d-x.org/docs/api-ref/index.html ) _Note that Cocos2d-x, Cocos2d-JS and Cocos Creator have different API set_
* [Programmers Guide ](http://cocos2d-x.org/docs/programmers-guide/2/index.html )
2015-07-16 16:53:43 +08:00
* [Latest Release Note ](https://github.com/cocos2d/cocos2d-x/blob/v3/docs/RELEASE_NOTES.md )
* [Changelog ](https://github.com/cocos2d/cocos2d-x/blob/v3/CHANGELOG )
* [Cocos2d sample games ](https://github.com/cocos2d/cocos2d-x-samples ) _More samples will be added in v3.8_
2015-04-16 01:23:49 +08:00
2013-08-07 06:07:42 +08:00
Main features
-------------
* Scene management (workflow)
* Transitions between scenes
* Sprites and Sprite Sheets
* Effects: Lens, Ripple, Waves, Liquid, etc.
* Actions (behaviours):
2016-07-07 22:59:57 +08:00
* Transformation Actions: Move, Rotate, Scale, Fade, Tint, etc.
2013-08-07 06:07:42 +08:00
* Composable actions: Sequence, Spawn, Repeat, Reverse
* Ease Actions: Exp, Sin, Cubic, Elastic, etc.
* Misc actions: CallFunc, OrbitCamera, Follow, Tween
* Basic menus and buttons
* Integrated with physics engines: [Box2d][5] and [Chipmunk][6]
* Particle system
* Skeleton Animations: [Spine][7] and Armature support
* Fonts:
* Fast font rendering using Fixed and Variable width fonts
* Support for .ttf fonts
* Tile Map support: Orthogonal, Isometric and Hexagonal
* Parallax scrolling
* Motion Streak
* Render To Texture
* Touch/Accelerometer on mobile devices
2014-01-07 14:09:05 +08:00
* Touch/Mouse/Keyboard on desktop
2013-08-07 06:07:42 +08:00
* Sound Engine support (CocosDenshion library) based on OpenAL
* Integrated Slow motion/Fast forward
* Fast and compressed textures: PVR compressed and uncompressed textures, ETC1 compressed textures, and more
2014-08-05 18:03:21 +08:00
* Resolution Independent
2013-08-07 06:07:42 +08:00
* Language: C++, with Lua and JavaScript bindings
2014-08-05 18:03:21 +08:00
* Open Source Commercial Friendly(MIT): Compatible with open and closed source projects
2013-08-07 06:07:42 +08:00
* OpenGL ES 2.0 (mobile) / OpenGL 2.1 (desktop) based
Build Requirements
------------------
2016-08-04 09:49:23 +08:00
* Mac OS X 10.7+, Xcode 7+
2013-11-06 18:07:03 +08:00
* or Ubuntu 12.10+, CMake 2.6+
2015-05-05 16:11:26 +08:00
* or Windows 7+, VS 2013+
2014-03-14 23:12:01 +08:00
* Python 2.7.5
2016-07-06 14:38:10 +08:00
* NDK r11+ is required to build Android games
2017-03-16 14:14:43 +08:00
* Android Studio 2.3+ bo build Android games
2016-08-04 16:51:19 +08:00
* Tizen SDK 2.3+ is required to build Tizen games
2015-08-21 02:13:17 +08:00
* Windows Phone/Store 10.0 VS 2015
2015-07-16 16:53:43 +08:00
* JRE or JDK 1.6+ is required for web publishing
2013-08-07 06:07:42 +08:00
Runtime Requirements
--------------------
2016-08-04 14:02:40 +08:00
* iOS 7.0+ for iPhone / iPad games
2016-07-06 14:38:10 +08:00
* Android 2.3.3+ for Android games
2016-08-04 16:51:19 +08:00
* Tizen 2.3+ or 2.4+ for Tizen games
2015-06-20 00:08:57 +08:00
* Windows 10.0 for Windows Phone/Store 10.0 games
2016-08-04 14:02:40 +08:00
* OS X v10.9+ for Mac games
2013-08-07 06:07:42 +08:00
* Windows 7+ for Win games
2015-07-16 16:53:43 +08:00
* Modern browsers and IE 9+ for web games
2013-08-07 06:07:42 +08:00
Running Tests
--------------------
Select the test you want from Xcode Scheme chooser.
2015-07-16 16:53:43 +08:00
* Cocos Console
```
// Enter cpp test folder
cd tests/cpp-tests
// Or enter js test folder
cd tests/js-tests
// Or enter lua test folder
cd tests/lua-tests
// Compile or run test case
cocos compile -p ios|mac|android|win32|win8_1|metro|web -m debug|release
cocos run -p ios|mac|android|win32|win8_1|metro|web -m debug|release
```
2013-08-07 06:07:42 +08:00
* For OS X / iOS
```
2013-10-30 18:27:56 +08:00
$ cd cocos2d-x/build
2015-03-31 14:34:22 +08:00
$ open cocos2d_tests.xcodeproj
2013-08-07 06:07:42 +08:00
```
* For Linux
```
2013-11-11 15:56:15 +08:00
$ cd cocos2d-x/build
2013-11-11 17:36:23 +08:00
$ ./install-deps-linux.sh
$ cmake ..
$ make
2014-01-07 16:25:37 +08:00
```
Run Samples
```
2014-03-14 14:50:16 +08:00
$ bin/cpp-empty-test/cpp-empty-test
2014-01-07 16:25:37 +08:00
or
2014-03-14 14:50:16 +08:00
$ bin/lua-empty-test/lua-empty-test
2013-08-07 06:07:42 +08:00
```
2014-01-07 14:09:05 +08:00
You may meet building errors when building libGLFW.so. It is because libGL.so directs to an error target,
you should make it to direct to a correct one. `install-deps-linux.sh` only has to be run once.
2013-11-11 15:56:15 +08:00
2013-08-07 06:07:42 +08:00
* For Windows
2015-05-20 13:55:23 +08:00
Open the `cocos2d-x/build/cocos2d-win32.sln`
2013-08-07 06:07:42 +08:00
2015-04-16 01:23:49 +08:00
* For Windows 8.1 Universal Apps (Phone and Store)
Open the `cocos2d-x/build/cocos2d-win8.1-universal.sln`
2015-08-22 04:14:01 +08:00
* For Windows 10.0 Universal Windows Platform (UWP) Apps (Phone and Store)
Open the `cocos2d-x/build/cocos2d-win10.sln`
2013-08-07 06:07:42 +08:00
* For Android
2013-08-07 11:18:19 +08:00
```
2013-10-30 18:27:56 +08:00
$ cd cocos2d-x/build
2014-03-14 14:50:16 +08:00
$ python ./android-build.py cpp-empty-test -p 10
2014-12-27 09:17:26 +08:00
$ adb install ../tests/cpp-empty-test/proj.android/bin/CppEmptyTest-debug.apk
2013-08-07 11:18:19 +08:00
```
2014-03-14 15:01:11 +08:00
Then click item on Android device to run tests. Available value of `-p` is the API level, cocos2d-x supports from level 10.
2016-08-04 16:51:19 +08:00
* For Tizen
Please refer to this [guide ](http://cocos2d-x.org/docs/installation/Tizen/index.html ).
2015-12-05 04:27:51 +08:00
Learning Resources
--------------------------------
2016-04-06 04:17:52 +08:00
* [Programmers Guide ](http://cocos2d-x.org/docs/programmers-guide/2/index.html )
2015-12-05 04:27:51 +08:00
* [Sonar Systems Videos ](https://www.youtube.com/user/sonarsystemslimited/search?query=cocos2d-x )
* [Android Fundamentals ](https://developer.android.com/guide/components/fundamentals.html )
* [Make School Tutorials ](https://www.makeschool.com/tutorials/ )
* [Games From Scratch ](http://www.gamefromscratch.com/page/Cocos2d-x-CPP-Game-Programming-Tutorial-Series.aspx )
* [Cocos2d sample games ](https://github.com/cocos2d/cocos2d-x-samples )
Spreading the word!
--------------------------------
You can help us spread the word about cocos2d-x! We would surely appreciate it!
* Talk about us on Facebook! Our [Facebook Page ](https://www.facebook.com/cocos2dx/ )
* Tweet, Tweet! Our [Twitter ](https://twitter.com/cocos2dx )
* Read our [Blog ](http://blog.cocos2d-x.org/ ) and promote it on your social media.
* Become a [Regional Coordinator ](http://discuss.cocos2d-x.org/t/we-need-regional-coordinators/24104 )
2016-03-15 22:41:35 +08:00
See what we are planning!
--------------------------------
You can see exactly what we are planning to do with the Cocos family of products.
* [Cocos2d-x roadmap ](https://trello.com/b/Np6obnuE/cocos2d-x-roadmap )
2015-12-05 04:27:51 +08:00
Where to get help
--------------------------------
* [Forums ](http://discuss.cocos2d-x.org )
* [Bug Tracker ](https://github.com/cocos2d/cocos2d-x/issues )
* IRC. We are in [Freenode ](https://webchat.freenode.net/ ) in the _#cocos2d_ channel
* `cpp-tests` project. This project is our basis for testing. Use this project to
learn how we implement the functionality of the engine. This project is located in
__cocos2d-x_root/build.__
2016-04-06 04:17:52 +08:00
* [API Reference ](http://cocos2d-x.org/docs/api-ref/index.html ).
2015-12-05 04:27:51 +08:00
* [Latest Release Note ](https://github.com/cocos2d/cocos2d-x/blob/v3/docs/RELEASE_NOTES.md )
* [Changelog ](https://github.com/cocos2d/cocos2d-x/blob/v3/CHANGELOG )
2013-08-07 06:07:42 +08:00
Contributing to the Project
--------------------------------
2016-01-19 23:06:10 +08:00
Cocos2d-x is licensed under the [MIT License ](https://opensource.org/licenses/MIT ). We welcome participation!
2016-01-05 03:48:40 +08:00
2013-08-07 06:07:42 +08:00
Did you find a bug? Do you have feature request? Do you want to merge a feature?
* [contributing to cocos2d-x][8]
Contact us
----------
2016-04-06 04:17:52 +08:00
* Forum: [http://discuss.cocos2d-x.org][9]
2013-08-07 06:07:42 +08:00
* Twitter: [http://www.twitter.com/cocos2dx][10]
* Weibo: [http://t.sina.com.cn/cocos2dx][11]
* IRC: [https://webchat.freenode.net/][12] (#cocos2d and #cocos2d -x channels)
[1]: http://www.cocos2d-x.org "cocos2d-x"
[2]: http://www.cocos2d-iphone.org "cocos2d for iPhone"
[3]: http://www.cocos2d-x.org/projects/cocos2d-x/wiki/Download
2013-09-29 10:54:46 +08:00
[4]: http://www.cocos2d-x.org/download/version#Cocos2d-x
2013-08-07 06:07:42 +08:00
[5]: http://www.box2d.org "Box2D"
[6]: http://www.chipmunk-physics.net "Chipmunk2D"
[7]: http://esotericsoftware.com/ "http://esotericsoftware.com/"
2015-09-21 22:30:37 +08:00
[8]: https://github.com/cocos2d/cocos2d-x/blob/v3/CONTRIBUTING.md
2016-04-06 04:17:52 +08:00
[9]: http://discuss.cocos2d-x.org "http://discuss.cocos2d-x.org"
2013-08-07 06:07:42 +08:00
[10]: http://www.twitter.com/cocos2dx "http://www.twitter.com/cocos2dx"
[11]: http://t.sina.com.cn/cocos2dx "http://t.sina.com.cn/cocos2dx"
2013-08-07 06:14:48 +08:00
[12]: https://webchat.freenode.net/ "https://webchat.freenode.net/"