2013-08-07 06:07:42 +08:00
< img src = "http://www.cocos2d-x.org/attachments/801/cocos2dx_portrait.png" width = 200 >
cocos2d-x
=========
2018-01-17 14:34:05 +08:00
|Win32|Others|
| ----|------|
[![Build status ](https://ci.appveyor.com/api/projects/status/nlgirox464j6ldg5/branch/v3?svg=true )](https://ci.appveyor.com/project/minggo/cocos2d-x/branch/v3)|[![Build Status](https://travis-ci.org/cocos2d/cocos2d-x.svg?branch=v3)](https://travis-ci.org/cocos2d/cocos2d-x)
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++.
2017-09-21 16:52:41 +08:00
It works on iOS, Android, 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
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-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]
2018-03-08 16:08:13 +08:00
Using CMake
--------------------------------
Now Cocos2d-x support another project build method, it's CMake! CMake have great benefits when cross-platform compiling. The most sample way to use is:
$ cd cocos2d-x
$ mkdir cmake-build & & cd cmake-build
$ cmake ..
2015-07-16 16:53:43 +08:00
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 )
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
------------------
2018-01-16 13:47:21 +08:00
* Mac OS X 10.7+, Xcode 8+
2013-11-06 18:07:03 +08:00
* or Ubuntu 12.10+, CMake 2.6+
2018-01-16 13:47:21 +08:00
* or Windows 7+, VS 2015
2014-03-14 23:12:01 +08:00
* Python 2.7.5
2018-01-16 13:47:21 +08:00
* NDK r16+ is required to build Android games
2017-09-21 16:52:41 +08:00
* Android Studio 2.3.3+ to build Android games(tested with 2.3.3)
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
--------------------
2018-01-19 16:55:38 +08:00
* iOS 8.0+ for iPhone / iPad games
2017-09-21 16:52:41 +08:00
* Android 2.3.3+ for Android
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
* For Android
2013-08-07 11:18:19 +08:00
```
2013-10-30 18:27:56 +08:00
$ cd cocos2d-x/build
2017-09-22 17:39:31 +08:00
$ python ./android-build.py cpp-empty-test -p 14
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
```
2017-09-22 17:39:31 +08:00
Then click item on Android device to run tests. Available value of `-p` is the API level, cocos2d-x supports from level 14.
2016-08-04 16:51:19 +08:00
2018-03-08 16:08:13 +08:00
* [Detail CMake Guide ](cmake/README.md )
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"