We are updating Cocos2d-x Documentations, need your suggestions

cocos2d-x C++
#1

Hello Everyone
I am cocos2d-iphone user since 2010. I know cocos2d-iphone is an awesome engine. Its easy to use API style makes the engine super easy to learn and use , especially for beginner game developers, even non-game developers can learn cocos2d quickly.

This situation are changing due to the rapid development of cocos2d-x family. And there are more and more people are using cocos2d-x for their next big game. And at a very long time, the cocos2d community lacks documentation extreamly, as we all know that the documents are very important for new comers.

So I am trying to keep the Wiki system update to date. Now the http://cocos2d-x.org/wiki has been improved a little bit.

Here is my plan:

1.Clean all the out-dated docs to the “deprecated section”.
2.Rearrange all the wiki pages to make it more easier for developers to view.
3.Move all the documentations from https://github.com/chukong/cocos-docs/blob/master/catalog/en.md to the wiki. Because the wiki system can be searched with Google.
4.Add some external tutorials and learning resources.
5.(IMPORTANT)I will constantly keep all the document up to date.
6. If you had already written some great cocos2d-x tutorials, please let me know. I will add them to the wiki system and give a link back to your blog.

The old wiki system contains a huge amount of document, so I need you(the awesome cocos2d-x developers) to help me to do the job together. It will make a difference.:slight_smile:

If you find any documentation which are out-dated, please leave a message in the thread. I will try to update it.

Update:I have moved all the doc from Doc in Github to our wiki system. But there are still some docs are marked with ugly TBD. We should get rid of them.

Here I want to craft a developer friendly guides for new cocos2d-x developers.

Here is the catalog:

1. Introduction

####What is Cocos2d-X?
####What changed with Cocos2d-X 3.0
####What should we choose between v2.x and v3.x?

2. Setup

####Installing Eclipse(Xcode, Visual Studio), JDK, NDK, ADT, python2.7, ant

####Installing Cocos2d-X
Installing on Windows
Installing on Linux
Installing on Mac
Engine directory structure overview

####Samples
How to run test-cpp/tests-lua on IOS
How to run test-cpp/tests-lua on Android
How to run test-cpp/tests-lua on WP8

###3. Installing Cocos-console

Create New Project

How to create new project with cocos-console on Windows
How to create new project with cocos-console on Linux
How to create new project with cocos-console on MacOS

Build and Run

How to build and run projects created by cocos-console on Windows
How to build and run projects created by cocos-console on Linux
How to build and run projects created by cocos-console on MacOS

###4. Your First Game with Cocos2d-x
The project directory structure
How to construct a game with cocos2d-x

###5. Basics
In this section, we will cover some basic and very important ideas of cocos2d-x. Such as:
(1)The scene graph architecture,
(2)the coordination system and the difference between the screen coordination and OpenGL coordination.
(3)basic Action,
(4) Schedulers and game loop
(5) Menu system
(6)UI controls
(7) Event Handling - touch, keyboard,custom,accelometer etc
(8) sprites and sprite animations.
(9)audio system
(10)physics and collide detection
(11)how to save and load game data

###6. Scripting( Lua binding vs javascript binding)
How to use binding generates to generate lua&js bindings?
How to manually bind c++ to js and lua and how to call js&lua function in c++.
Lua binding debugging Vs javascript bindding debugging

###7. Memory Management Guide
Memory management guide for c++ developers
Memory management guide for lua developers
Memory management guide for javascript developers

###8. Tutorials
In this section, all the great tutorials(both written and video tutorials are included) are gathered here.

###9. Advanced topics.
(this section may focus on some small topics,one topic a document, it should be well organized by their titles.)
(1)How to use render texture? How to save screenshot.
(2)How to adapt various kinds of device resolution
(3)How to use http to communicate with your sever
(4)How to use third party libraries. For example:sqlite
(5)How to use camera to achieve awesome following effects.
(6)How to use new render to draw your own opengl commands.
(7)How to deal with memory warning and memory optimization
(8)How to subclass your own action?
(9)How to integrate third party SDKs? Such as facebook, twitter, admob, flurry etc.

###10. Miscellaneous
How to migrate from v2.x to v3.x
The release note of all version
etc.

###11. Cocos2D-X FAQ
Every new cocos2d-x comers should read this section before asking for help in the forum.

Does the above catalog looks more clearer? I hope you could supplement it. If it’s ok, I will try to organize the wiki page to be the same as we proposed.

Thanks for reading.

#2

@owen

Thanks so much for doing this!

Outdated in GUI docs: UILayer
We’ve dropped it in beta2.

#3

@owen
Hi, I would rather like to use the Python Sphinx and the ReadTheDocs service for documentions writting. They have actually been the standard in python world. Such as DjangoProject, and so on.

  1. Sphinx has a version concept built-in. It will solve the problem that wiki or documention’s version maybe out date.
  2. The wiki system why not use MediaWiki? It has a change log or diffrence feature！
  3. Official tutorials or books will be highly appreciated.
  4. Our documention system can be better. Everyone of developers could benefit from the new document system, then more and more user as we konw. And it’s easier for each of us to participate in.
#4

@jonah1nine

Thanks, I will check it.

#5

@mic

Thanks for your suggestions.

Both Sphinx, ReadTheDocs or MediaWiki are good enough document writing system, but I think recently I should focus more on the content creation, rather than changing the way which we have been used to do things.

The current wiki system we are using is sufficient for basic document writing.
Could you edit a existing wiki page of our site now?

#6

Always need a document for updating existing project from previous version whenever there is a new release (either dirty/complete). Actually, I have seek for same help before (http://www.cocos2d-x.org/forums/6/topics/43859?r=43953#message-43953)

It is understandable that there are many changes on the API and may not be able to fully documented all migration steps. But somehow we need to get the right direction first before we could help ourselves.

#7

@winipcfg

I totally agree, we should write one. I will add it to my todo list.

#8

@owen

Firstly, thank you for trying to undertake the effort of updating the Wiki on this site, since it is in terrible state. I’ve written a few issues in the forum directly addressing it to Ricardo Quesada & team to bring some sanity to the Cocos2D-X documentation. There are pages with just TBD note for years now. I have yet to hear back from anyone from the engine team.

Cocos2D-X is a great engine but the lack of clear and complete documentation and tutorials from the engine development team who have insight what exactly is going on with the engine has left many developers frustrated.

I have done Cocos2D-X development but I’ve spent days/weeks initially just trying to “Get Started”, and then struggling to understand the API and develop games. Seeing that things have barely changed I have started using Unity3D to do game development.

Here is the reasoning behind my decision and I hope the Cocos2D-X team will read and seriously start to figure out how to make the learning experience better.

  • As a Cocos2D-X developer, I’ve wasted tonnes of my time waiving through forums, un-commented sample test code, badly documented API, Cocos2D-X forum to find information that should have been provided on the Wiki in the first place.
  • Once I moved to Unity3D, it only took me a fraction of time to get the development environment setup and do what I want to do, develop apps!

Unity3D now provides great 2D development support with integrated tools to quickly develop apps and not waste my time fighting to understand how things work under the hood just so I could do what I really want to do in the first place is develop great apps.

I would recommend to look at Unity3D’s site to see how well everything is organized and documented. Unity3D is now free to develop and deploy apps across multiple platforms. To sum things up, developers need to bring apps to market quickly and whatever tools will help support that business model will get the audience.

#9

The docs here are definitely a major issue. I’ve used a number of different docs and like mic mentions, I too am partial to Python’s docs and layout, though you need not actually use Sphinx.

The location of the docs: “Learn” at the top should be changed to “Docs” or “Documentation” to reflect what developers expect to look for. A drop down menu would be nice, else a landing page for the Documentation that links to the API pages, Doc pages, and any other Tutorials.

It should be clear which Docs to use. There seems to be currently two different sets of documentation: the Wiki and the Docs tab/Github. The Wiki should probably be removed and the content converted over to the GitHub/Docs tab. The Docs should be consistently updated to reflect the GitHub changes (which they may already be).

There should be a clear way to contribute. The best way would be by contributing to the GitHub docs https://github.com/chukong/cocos-docs which probably should have the owner changed so that its owned by the user cocos2d rather than chukong.

The Docs catalog (index/organization) should also be reorganized. It was difficult to look through to find the doc I needed, and there seems to be a lot of duplication. The Chinese docs should be kept separate from the English ones because it’s difficult to navigate the GitHub seeing all the docs which don’t have English versions.

The Docs on the Docs tab/GitHub should be switched over to use Doxygen/Codeview. There aren’t so many docs in cocos-docs that it would be impossible to switch, and it would make maintenance easier. It can still have its own separate area from the API reference, but I think a consistent system is important going forward.

Once the Docs are organized and ordered, it will be easier to solicit contributions as well.

#10

@owen
Hey, no offense, suggest again!

I am reading your blog these days. Thanks for your articles!

Actually, I have bought a book 《Cocos2D-x 权威指南(2013-04)满硕泉》. But, there is another Book for Cocos2d-x 3.0 supporting wanted. If we don’t write it, there will be someone at last.

The index or navigation, which can be found easily for beginners, is the most important aspect of a document. I do suggest more tools than content, because a newbie in C++ and Cocos2D-x am I. Just as @odie5533 says, these tool can perfectly solve the problem of document version control! Sphinx seprate the different version, and wiki can be remove because Shpinx keep the lasest one!

Now tutorails of Cocos2d-x are here and there. Everyone would write a tutoial series
, but little occurs in Python or Django’s docs. Maybe we have not provide a good way to understand Cocos2D-x for them.

Contributions, a good programmer who masters in cocos2D may not proper in writing. Writers know everything of the engine, but readers not. Here is one document 过渡 (Transitions). It must be human but machine translates or writes. However, if don’t watch some demo code from other site and Cocos source test code, I won’t know what he says.

I joined two QQ group of cocos2d*. There are always ones cry that “Help! how to… blah blah blah”. We had better describe the relations between cocos2d* and mobile platforms. What is cross compile, native code, etc. Also, should give a big advice to those who never read docs.

If there is nice docs, the forum’s questions will be less. It’s v3.0, have a nice beginning no matter what the community chose!

#11

i would love to help out more, but it’s difficult to see how.

for a while i was contributing to the github docs (mainly helping to edit the english versions), but if you are now deprecating that, i have no idea how to contribute. the wiki is read-only.

i agree with @odie5533: the organization of the documentation is pretty poor.

also, perhaps there should be someone whose MAIN responsibility is the documentation. i get the feeling that the people who are currently responsible for documentation have too many other responsibilities that are deemed higher priority.

#12

I can’t help write but I can help proof-read and check for grammatical errors (very important!) once the docs are up.

#13

@rram
Thank you rram. The document of cocos2d-x is really terrible. We are trying to solve the problem. Now it’s an beginning that we will try to change this situation and be more friendly to the community.

#16

@odie5533

“The docs here are definitely a major issue. I’ve used a number of different docs and like mic mentions, I too am partial to Python’s docs and layout, though you need not actually use Sphinx.”

  • For the migration of document system, the current situation may be not allowed. Because we have done many effort to let wiki page to support markdown. Now the wiki system is more easy to use and maintain.

“The location of the docs: “Learn” at the top should be changed to “Docs” or “Documentation” to reflect what developers expect to look for. A drop down menu would be nice, else a landing page for the Documentation that links to the API pages, Doc pages, and any other Tutorials.”

  • I will discuss the idea with others and then decide whether to change or not.

For all of your remaining suggestions, could we craft a new tutorial like or an community driven book catalog? Then everyone could benefit from reading this book.

Thanks again for your thoughtful suggestions.

#17

@mic

Yeah, we have many documents now. But they are not systematic and well organized. I should propose a new cocos2d-x 3.0 guide catalog.

I will do this asap.

Thanks a lot.

#18

@lance_gray

Thank you. Since both my colleagues and me are not native speakers, your help will be valuable.

#19

@mic @bunnyhero @odie5533 @rram

Hi guys, I have made a sample catalog, could you please give some suggestions to me?

I update the topic in the first floor.

#21

@owen

So going forward, no more GitHub/Docs tab? And only the Wiki and Api tabs? I seriously think you should consider somehow integrating things into Doxygen or Codeview so that the docs are consistent. Otherwise, at the least, the Layout/CSS of the Wiki should be improved a bit: there are huge headers filling the screen than should be shrunk down or removed, and also there’s a big empty header on the left above the catalog listing.

Also, I’m in the #cocos2d IRC a lot if you want to brainstorm about the docs.

For organizing it, perhaps:

(1) Introduction
What is Cocos2d-X?
What changed with Cocos2d-X 3.0
Installing Cocos2d-X

  • Installing on Windows
  • Installing on Linux
  • Installing on Mac

Cocos Console

(2) Starting
Starting a new project
File organization
Your first game
The Vital Functions (covering a selection of topics from the many modules)

(3) 2D Graphics

(4) Audio

(5) Data Structures

(6) Debugging
etc.
Plugin System

Compiling
Compiling for Windows
Compiling for Web
Compiling for Android
Compiling for iOS

#22

http://www.openfl.org/documentation/

I like how OpenFL did their docs. It’s clean and sequential. It’s also cool that it has a “Setup” doc for every possible platform they support. Maybe we could use it as reference.

#24

@lance_gray

Thanks, I will read it.