Cocos 2d-x and Cocos Studio poor documentation

Cocos 2d-x and Cocos Studio poor documentation
0.0 0


Well I dont want to sound like arrogant person bashing about anything. I understand that cocos2dx and it is tools are free and are quite capable,but surprisingly they using them is not quite fun or even steeping curve. Rather it is kind of horrendous.
Well for start , the tutorial and documentation sucks. Well sucks is kind of sugar coating.For starters there is no good manual. The only thing that can count as manual is Programming Guide , but that is only helpful for users are just getting starting into Cocos2dX. Without manual you have to second guess like. ok so I want to do this step , so maybe if i search in documentation then i could find something relating to it. Issue with this is that it is kind of hit and trial method , sometimes it may work other times it may not.
Now documentation in itself is not very nice. There are still some methods you see here or there which have not even a single line of documentation. Though mostly have one line or two explanation. Well sorry but this is quite sufficient. I am not expecting spoon feeding , but still documentation is quite rough.
Second of all examples are there (though quite less) , but rather than teaching we are just given zip files of the final outcomes. So to learn you would have to dig even deeper.
Even online wiki is plagued with outdated information.
Now developers have created tools like cocos studio for graphic designing tools , I appreciated the whole thing. They actually understood that they need to give some GUI tool for graphic designers who are not developers. But without proper video tutorials(sorry but text tutorials dont work for graphics, maybe personal opinion). I mean the way i have worked is that if I am not able to understand basics of tool(rather than doing something sophisticated) i expect some video tutorial who actually tell me ‘Ok to do this do that , this button does that , or something like that’ . But sadly coocs studio has no tutorial. Even as i pointed earlier the wiki is outdated. The official wiki, how do you expect people to learn when offical docs are wrong and virtually there is no way for you to learn anything. For e.g. I have downloaded latest cocos studio (which i guess have merged earlier 4 components into 1 , if i am wrong please let me know)
Animation Editor

I am aware that whole suite is free(I am actually thankful to developers) unlike Unity and other game development software. I totally understand but We can not leverage it against hiding the short comings. Honestly if you ask me , i would ask Cocos devs to focus on these areas rather than adding new features as we as Game developers would be more productive if we know how to actually use the tools
P.S. I apologize if any statement is wrong , please let me know. Also any tutorials for Cocos Studio (regarding Animation) also let me know


Thank you for taking the time to write this. We appreciate any and all feedback that we receive.

Let me address some of your points.

  1. We do have the Programmers Guide as you mentioned. This should get users started on how things are structured.

  2. We have an API Reference as you also mentioned. Yes, there are many functions that aren’t well documented. We work to fix this but yes we do need to do better here.

  3. Cocos2d-x definitely requires you to have some programmer knowledge and the ability to think about concepts when you are coding. We don’t quite do as much hand holding as other engines might. This, IMHO, makes us the engine as basic or as advanced as the programmer wants, skill level depending. If you are the type of developer that wants to whip out quick 1-2-3 games and not understand the engine and concepts behind why your game works then cocos2d-x might not be the best choice here. We just aren’t this type of engine.

  4. We don’t do video tutorials, usually. Why? I think we just can’t teach every little piece in a video. Then if someone watched the video they would also want the code along with it to download. We would have a lot of videos and they take time to make. We don’t really teach programming nor game concepts. We do provide excellent examples (as you also mentioned) but you do need to be able to read someone else code and understand what they wrote. This is an obstacle for any programmer, good, bad, etc. We still try to do our best.

  5. As you mentioned we are a free, open-sourced engine. This is to your advantage and ours!. You can help us. You can surely provide pull requests to help improve most any aspect of the engine. Documentation included! It is simple to get started.

  6. This forums is simply a great place. If you are struggling, come here and ask. We do our best to answer. There are so many users here that are happy to answer questions. It helps you and it helps everyone stay fresh on knowledge.

Stick with us!


@slackmoehrle-Thanks mate for quick replying.
Let me address your points one by one

  1. I agree that we have Programmers guide ,which i actually think does quite a good job. My mentioning of that was not to pick any fault but rather telling you that of need exists that we need to have good strong manual as well, because if we have a look that manual , it actually covers a lot of basic things in short book(Again Kudos to that). Lack of manual as I said that requires dev to look into source code generated documentation which is kind of hit and miss way to do it.
    2.I have programmer experience and i actually like the coding way , it gives you quite power but I need to know how to do it , which actually goes back to my Manual reason. I must know where to look in order to accomplish.Right?
    3.I think you got me wrong at that part , Video tutorials should not be for teaching exhaustive things that Cocos Studio should do but rather showing you how to do basics.By basics i mean how to add frame , scene or how to loop. Just this small things. I know that these things are quite basic. But think again shall designer need to ponder and scratch his head for doing simple things. I repeat sir , simple small things but no sophisticated. Well I am not expecting you guys to teach programming or game concepts.
    Whole notion of this topic if i may summarize is that Cocos devs SHOULD have documentation in a manner that teaches basics steps.
    Still thanks for replying @slackmoehrle


I’m actually a level designer by trade and I didn’t have too much trouble figuring things out. I guess its just personal preference, but I would much rather look at a bit of example code (ie cpp-tests) than read documentation.


this is true for @prespondek. First I follow along basic tutorial with cocos2d-x. And then my learning steps is always looking at simulation compiled by cpp-tests(interaction and animation).I look for what I really need, copy-paste the source code, tweak its parameters to see what kind of flexibility I got and built from there. I don’t think there’s better way to do that. Video tutorials can only give you so much and you still won’t reach the level that simulation can give.


Speaking as someone who has complained about the documentation in the past, I can only say how much better it is since the new Programmers Guide has been started.

It can be very difficult finding out how to do some things - but there are people doing tutorials out there - and the sample source code shows a lot of the simple stuff.

I disagree about video tutorials - they are, IMHO, the scourge of the earth - I hate video tutorials with an absolute passion! (So, yes, it is a personal thing :smile: )

I think with the (very) rapid development of cocos2d-x, things got a bit slap-dash for a while. Now the releases seem to be a little less frequent, and the documentation is improving in leaps and bounds.

As @slackmoehrle says - you too can help out, as you work out how to do things, spot errors or places things could be improved, you have the ability to improve them!

What I would like to see in the long term is a place where well-edited tutorials could live, a bit like Ray Wenderlich’s cocos2d site. the discussions around those tutorials kept them relevant - and I still occasionally refer back to them even now!


Well, if I may jump on the complaints wagon as well… (which I’d rather not, but hey, sleep deprivation lowers inhibitions as much as alcohol, so here I go…)

There’s still not a single resource online (or at least not one that I’ve managed to found) that teaches how to actually use stuff you build in Cocos Studio with Cocos2d-js. I’ve seen many people asking this in many places, yet no one knows the answer (if I had I’d already posted it, it’s really starting to bother me that this tool exists and yet no one seems to be able to use it because of such a thing).


Have to seen Sonar Learning docs ?
Click on topic from left side and code snippet is available for both i.e. C++ & JS


While I was able to figure out Cocos Studio in a relatively short time, I think the community would appreciate a better documentations.


@prespondek-Hmm level designer , so you design levels with help of cocos studio or just simply writing code?
@GulperEeL-thanks this is the way i am doing it myself.
@Maxxx- Thing is with videos is that there is less ambiguity (of course you can never beat books). But normally tutorials as in how to write 4X4 matrix multiplication or something like that reading the code will do the trick , but when we talk about using the tool , 1 picture(or video per-se) means 1000 words(cliche!! i know). Then again as we both have pointed out it is personal thing
@ZippoLag-this is precisely i as talking about. We should empower more on learning things as i may build rocket that can go to mars and back but without documentation i may end up firing up someone else’s ass(or mine)
@smitpatel88-They have not done on Cocos Studio except for very very basic.


Nope, I had no idea those existed (and trust me, I’ve searched a lot).

Here, this is pretty much what people need to know the most: xD


couldn’t agree more. You’ll be spending days just trying to set it up :slight_smile: This tool is made for the founders themselves obviously.


This is an unfair comment. You spent days because you were following old documentation. Granted this is sort of a catch-22. You asked for help on the forums and I responded to every post you made. Had you posted when you first ran into trouble you would not have spent days and then came here posting rants.

If you really feel the docs are poor, get involved. Send in PR’s. Then you can help users when they ask rather than posting an unfair rant in a year old topic.


I’ve been noticing this community problem ever since. And I did get involved. I tried to make tutorials before, this being one:


We’ll all know that cocos2d-x is not few clicks setup and ready to work like Unity or Corona, etc. But I guess, we never picked Cocos2d-x for this reason but other things. I rem. in March 2014, I picked up this engine and took me 1 month to set it up and I was a beginner in C++ too at that time. And I also remember your user name ‘reya…’ from the very beginning.

While steps are given good enough to setup in programmer’s guide. I guess, your pain can be related to versions mismatch of NDK with Cocos2d-x which is common thing I noticed on forums.

But I guess, it can be resolved in Cocos Creator which will be the new tool :slight_smile:
And as we all know C++ support is also being added. So, would be cool I guess.

One thing I agree, that there aren’t even enough books like Unity has a ton of books for every level of expertise. It’s mainly because not good documentation since beginning. It also attributed to the fact that whatever cocos2d-x books, we’ve in market, they’ all cover mainly same topics(except 2 books which covers different topic but intersection of topics is majorly same) because who are experts in cocos2d-x, doesn’t have time to write book and those who did aren’t ‘mostly(not all)’ expert enough to understand the engine in deep without complete documentation, hence they all didn’t cover intermediate to advance or advance topics at all. [English books]

But AFAIK, Cocos creator guide is being updated regularly, so again, this will be resolved once decent enough version of creator is out.


I remember you too brah! :smiley: just a bit frustrated. I really like Cocos2d-x, I’m just annoyed cause I can’t use it. I was able to develop games when I was using MacBook. But now I’m in Windows10.


Your setup should be examined.

There are more Android developers here than iOS and a lot of folks here use Windows. Cocos2d-x works on Windows to do Android development (and using a variety of tools, Android Studio, command-line, Eclipse, Visual Studio).


Haha… Same thing… I used to work on Windows, have setup ready on that. Stopped game programming since 1 yr as I was learning some little bit art work and got a job.

After restarting game programming, I used Corona as part of competition and done the game in very limited time. But as I prefer cocos2d-x APIs more, I set it up in mac from scratch and it took me 3 days to get everything working on eclipse, mainly because I started with Android Studio which I realized that it’s studio’s fault that it doesn’t support C++ well enough. :smiley:
Bu effectively it took me less than a day to setup using programmer’s guide and finding compatible cocos2d-x. Yeah, I understand, it’s still not like few clicks and done like Unity/Corona.

And I am working for my 1st to be published game :smiley:
And I’ll be awaiting cocos creator C++.


Oh good luck mate. So you’re using Eclipse instead of Android Studio?


Yeah, using eclipse gives me auto complete. I am less of a C++(more of a web developer) and it would be struggle for me to find things to make auto complete work if it really exists and there isn’t any guide right now to get it easily. And since, I work on my games only in my spare time, it will be a heavy toll for me to keep and keep searching things for things which I should have goten by default.

Moreover, we have to keep 2 windows of Android studio opened(last used 1.5 months back), one for building(Java view) and one for editing classes(C++ view). Can’t do it in same window.
Yes, gradle build was faster than usual build, though. But I can’t afford to trade off with above things.
Android Studio will have better support for working with C++ in coming future and then I’ll switch to Android Studio, hopefully, autocomplete will exist.

[But I prefer C++ for my game developement instead of JS :D. In fact, I started working on C++ through Cocos2d-x as I already knew C and Java]

I just read one of your threads regarding build fail. I didn’t read exactly the error, neither I would understand it :smiley: :smiley:
If you haven’t then I would suggest to use real device to test things atleast for initial setup because because of x86 armeabi armeabi-7a mips, etc exists and you won’t know what for to build.
So, keep it simple, architecture should be armeabi 7a would always work on real device.
And x86 would always work on emulator(genymotion atleast). If you’ve given both armeabi 7a and x86 then build will take time and this .apk will work on both device and emulators.