cocos2dx-3.0 Wishlist

cocos2d-x C++
#1

As started on the shared_ptr thread here are some ideas on how I would change the structure of the cocos2d library:

Project Structure

At the moment the library is a huge repository containing everything including test and sample apps (which I do not need when developing my own project). Also the library contains the project as the subfolder. However the library is a dependency of the application and therefore should reside in a sub-folder of the application:

MyApplicationProject
 |
 |-Classes (contains the application source files)
 |-Resources (contains the application resources)
 |-Libraries (contains dependencies to third party code)
      |
      |- cocos2dx (contains the source and resources from the cocos2dx library)
      |- CocosDenshion (contains the source and resources from the Cocosdeshion library)
      |- box2d
      |-

With this setup I can more easily manage dependencies and repositories for each third party library I am using.

Platform specific code in cocos2dx

At the moment the platform folder is quite a mess, and some platforms need various files that should not be added to other (CCImage.cpp for example)
So we may define different subsystems, which get included by a specific platform. Each of these subsystems may provide different backends (which contain the actual code, and may be platform dependant or used by serveral platforms):

So for example we have a WindowToolkit which should be responsible for managing the windowing system and forwarding user input to cocos2dx:

WindowToolkit
 |
 |- IWindowToolkit.h (provides the interface for all window toolkit backens)
 |- WindowToolkit.cpp (contains a singleton which forwards access to the actual backend that is used)

A window toolkit backend, then implements the protocol for a specific or multiple platforms. For example glfw or SDL coud be used on all PC platforms, so it would make much more sens to share this code, then to write three different implementations for managing the window system.

WindowToolkitGLFW
 |
 |-WindowToolkitGLFW.h
 |-WindowToolkitGLFW.cpp (include the implementation for the window toolkit interface by using the GLFW library)
 |-platform
     |-Linux
     |    |- WindowToolkitGLFWLinux.h/.cpp (includes linux specific implementation details if required)
     |    |- libraries
     |         |- libGLFW.a (dependency library, required by the glfw implementation)
     |
     |-Windows
     |-MacOSX

Each platform can now define which toolkit backend it wants to use. Multiple platforms could share implementations of a specific toolkit.
When implementing a new platform, I need to verify that there are backends available for all required subsystems.

Some other examples are:
Playing sounds using OpenAL (can be used on all PC platforms and iOS)
Font rendering using libfreetype (possible on PC platforms, a library may be compiled for the mobile platforms)

Implementing this may also make the next point easier (not sure if this is planned)

Integrate an abstraction layer for the rendering API

For the game code it should not matter that much if it gets rendered on Direct3D or OpenGL. So it might be a goog idea to integrate an abstraction layer for the most commonly used operations. Which may allow unifying the WinRT and default branch of cocos2d.

Implement multi-threaded rendering

We should at least to try to put the game rendering code to a different thread. This may significantly speed up the performance of the engine:
* scene graph is generated on the main thread, once the frame is calculated, the scene graph is given to the renderer thread.
* renderer thread takes the scene graph and starts rendering
* the main thread can immediatly continue, calculating the next frame, we don’t need to wait until glSwapBuffers() will finish (which may take quite some time depending on the implementation of the graphics driver)
* as an optimization, the main thread should now use the same objects for generating the scene graph, If an object has changed, it should perform a copy-on-write (i.e creating a new rendering object and put it in the scene graph)

What are your thoughts on any of these issues?
Feel free to add further issues to the list.

#2

Project Structure
Really hope to revise current structure.
Also suggested that when we create new win32 project from template, the project should be able to locate at another folder instead of under cocos2d folder

Implement multi-threaded rendering
Please consider entity/component system to separate the main loop and rendering workflow.
For example, a CCLayer is an Entity that have UpdatableComponent and DrawableComponent. UpdatableComponent updates for game logic while DrawableComponent draws the graphic. Then they could be separated and run in two threads

(EDITED)
Please also evaluate physics abstraction layer in the future (http://www.adrianboeing.com/pal/index.html)
It is BSD license

#3

Thanks @Andre Rudlaff

  • Project Structure
    Which library should be contained in Libraries? If we want to create a project that has the same folder structure as HelloCpp, it is hard to do with template, especially IDE settings.
    Now cocos2d-x has a tool in tools/project-creator/create_project.py. It can create a project with all needed codes, but hard to customize.
    Any suggestions?
  • Platform special code in cocos2dx
    Yep, some platforms may share some codes, but not all platforms can share the same codes. Especially mix using objective-c and c++, should change the file to .mm.
    These all make codes in platforms mess. We also want to simplify it.
    Do you have any idea?
  • About multi-threaded rendering
    Please refer to this thread.
#4

Andre Rudlaff wrote:

As started on the shared_ptr thread here are some ideas on how I would change the structure of the cocos2d library:
>
h3. Project Structure

Agreed. We need to improve it.
One of my concerts in having the proj.linux, proj.ios, etc, inside the library folder is that we cannot include the “original” github repositories since we have to modify them by adding the compile subdirectories. Also, it is not obvious that the Makefile / make projects are there. Perhaps we should have a sort of “make” or “build” directory.

Also, in the iOS / Mac world, it is easier to have one or two big xcodeprojects (one for all the libraries, and another one for the game) than having 4 or 5 different xcode projects.

h3. Platform specific code in cocos2dx

Playing sounds using OpenAL (can be used on all PC platforms and iOS)
Font rendering using libfreetype (possible on PC platforms, a library may be compiled for the mobile platforms)

a)
Should use libfreetype, libpng, libjpeg for all the supported platforms ?

b)
or should we use systems libraries ? (current approach).

if a), then portability and maintainability are going to be much easier.
if b), game is going to take less resources (libraries are already part of the OS), and perhaps it is going to be a bit faster.

Perhaps we should migrate to a).

h3. Integrate an abstraction layer for the rendering API

Agreed.

h3. Implement multi-threaded rendering

Agreed.

What are your thoughts on any of these issues?
Feel free to add further issues to the list.

Thanks for your feedback.

#5

If wishful thinking is allowed, I think a more extensive sound/music api than SimpleAudioEngine would be nice. One that supports things like seeking, seamless looping, etc.

#6

Sam Borenstein wrote:

If wishful thinking is allowed, I think a more extensive sound/music api than SimpleAudioEngine would be nice. One that supports things like seeking, seamless looping, etc.

I think the iOS / Mac versions have more features.
But the Win32 / Android versions only implement limited functionality.

Yes, probable we need a more powerful API that is portable across all platforms.

Should we use OpenAL as the foundation layer ? (I think we are currently using it)
Is someone using OpenSL ES? How portable is it ?

#7

I do really like the suggestions above
For handling customization of generating projects with that script, could you parse a block of JSON with completely optional properties (if a property doesn’t exist, fall back to default)?

Some little things that seem unintuitive to me:
* const char* all over instead of std::string (is the overhead that bad? strings are much nicer to handle for dev, less subtle bugs esp. during string concatenation. can get the size a lot easier)
* const-correctness not enforced all the time (makes it harder for long-term maintenance)
* macros everywhere. Is this a legacy thing? i thought this was considered a bad/outdated practice

#8

Ricardo Quesada wrote:

Sam Borenstein wrote:
> If wishful thinking is allowed, I think a more extensive sound/music api than SimpleAudioEngine would be nice. One that supports things like seeking, seamless looping, etc.
>
I think the iOS / Mac versions have more features.
But the Win32 / Android versions only implement limited functionality.
>
Yes, probable we need a more powerful API that is portable across all platforms.
>
Should we use OpenAL as the foundation layer ? (I think we are currently using it)
Is someone using OpenSL ES? How portable is it ?

OpenSL ES is a requirement for some bogus Java implementation on some Android devices (Galaxy S2 Gingerbread for instance is flawed).

#9

Ricardo Quesada wrote:

Andre Rudlaff wrote:
> As started on the shared_ptr thread here are some ideas on how I would change the structure of the cocos2d library:
>
> h3. Project Structure
>
Agreed. We need to improve it.
One of my concerts in having the proj.linux, proj.ios, etc, inside the library folder is that we cannot include the “original” github repositories since we have to modify them by adding the compile subdirectories. Also, it is not obvious that the Makefile / make projects are there. Perhaps we should have a sort of “make” or “build” directory.
>
Also, in the iOS / Mac world, it is easier to have one or two big xcodeprojects (one for all the libraries, and another one for the game) than having 4 or 5 different xcode projects.

Actually I would prefer having most of the library code in one single project. At least cocos2dx and CocosDenshion. At them moment I must modify the compiler settings or the cocos project itself (i.e. something within its repository) to change some of the preprocessor macros (e.g. something simple like turning on CCLOG macros).

I may be able to write a small tool that keeps track of managing the various project files:
You specify which folders/files should be included for each platform, define preprocessor defines c, cpp and linker flags and the tool would create an XCode/Eclipse/Visual Studio or Android makefile from this description.
I’ve already done something similar for XCode and Eclipse project files, so it should be possible.
The tool might be a small QT or Java application.
These generated project files could then reside somewhere in a build, make or projects directory of my project repository and no longer within the cocos2d repo.

> h3. Platform specific code in cocos2dx
I would strongly vote for a) if it is possible. We should share as much code between platforms as possible. Otherwise we may need to fix/implement 3 different versions of a word wrapping algorithm, 5 different versions of accessing the sound system… (I remembered fixing some font rendering issues in cocos2dx 1.0, and had to modify the code 4 times to make it work on each platform).

And it may depend on the platform if using the system API’s is really faster/more efficient. Especially on Android calling through JNI each time may be quite costly.

OpenAL could be used on all platforms except Android (I do not know about BlackBerry, Bada or Windows Phone). However even if the soundbackend is switched, we should write an abstraction layer that takes as much logic away from the sound backend as possible.
The backen should be as dumb as having only:
init() - load resources if they are not already loaded, resouce caching is again handled by the abstraction layer
play()
pause()
resume()
stop()

Plus you should be able to set some states on a player object:

  • should the sound be looped when finished
  • volume of the sound
  • stereo panning
  • callback when a sound has been finished
#10

Andre Rudlaff wrote:

I may be able to write a small tool that keeps track of managing the various project files:
You specify which folders/files should be included for each platform, define preprocessor defines c, cpp and linker flags and the tool would create an XCode/Eclipse/Visual Studio or Android makefile from this description.
I’ve already done something similar for XCode and Eclipse project files, so it should be possible.
The tool might be a small QT or Java application.
These generated project files could then reside somewhere in a build, make or projects directory of my project repository and no longer within the cocos2d repo.
>

Agree with custom tool idea. In April I’ve wrote QtCreator plugin which parses xcodeproj and shows files tree / imports parser settings for libclang (i.e build settings important to parse C/C++/ObjC files correctly). Later I’ve wrote tool that generates Android.mk, but it was not cool, for example, it generated Android.mk from scratch each time, but clang’s Rewriter approach is smarter: it just accumulates set of “patches”, where each patch is singe replacement for original text file, described by captured range and new text string; then Rewriter applies whole set of patches simultaneously.

I’m going to continue work after Jule, 15 and publish code at the end of this month. You eclipse project files updater can be helpful for further development.

Note that xcodeproj format is property list with set of objects and it is extensible either with custom objects or without them. And AFAIK XCode doesn’t destroy custom objects, it preserves these objects and just doesn’t use in own logic model.

#11

Andre Rudlaff wrote:

And it may depend on the platform if using the system API’s is really faster/more efficient. Especially on Android calling through JNI each time may be quite costly.
OpenAL is laggy on Android. OpenSL has same lags as Java-based SoundPool, but buggy implementations on some devices.
OpenAL could be used on all platforms except Android (I do not know about BlackBerry, Bada or Windows Phone). However even if the soundbackend is switched, we should write an abstraction layer that takes as much logic away from the sound backend as possible.
It can be used on blackberry, PR3010 uses single OpenAL backend for 4 platforms, and iOS/OSX/Emscrippten/Win32 can be united with this code later.
Plus you should be able to set some states on a player object:

  • should the sound be looped when finished
  • volume of the sound
  • stereo panning
  • callback when a sound has been finished
    Stereo and single effect volume, as well as pitch (playback rate), implemented in PR3010. Sound looping exists for long time. Callback on sound playback finish still not implemented.

PR 3010: https://github.com/cocos2d/cocos2d-x/pull/3010

#12

Andre Rudlaff wrote:

Actually I would prefer having most of the library code in one single project. At least cocos2dx and CocosDenshion. At them moment I must modify the compiler settings or the cocos project itself (i.e. something within its repository) to change some of the preprocessor macros (e.g. something simple like turning on CCLOG macros).

working on this. I have just submitted a pull request for the Mac project. iOS update coming soon:

I’ve already done something similar for XCode and Eclipse project files, so it should be possible.
The tool might be a small QT or Java application.
These generated project files could then reside somewhere in a build, make or projects directory of my project repository and no longer within the cocos2d repo.

sounds good!

> > h3. Platform specific code in cocos2dx
I would strongly vote for a) if it is possible. We should share as much code between platforms as possible. Otherwise we may need to fix/implement 3 different versions of a word wrapping algorithm, 5 different versions of accessing the sound system… (I remembered fixing some font rendering issues in cocos2dx 1.0, and had to modify the code 4 times to make it work on each platform).

thanks. option a) looks the correct way to do multiplatform stuff.

OpenAL could be used on all platforms except Android (I do not know about BlackBerry, Bada or Windows Phone). However even if the soundbackend is switched, we should write an abstraction layer that takes as much logic away from the sound backend as possible.

yes. the only thing that we should keep in mind here, is that our API should use the hardware playback whenever it is available.
thanks.

#13

Sergey Shambir wrote:

Stereo and single effect volume, as well as pitch (playback rate), implemented in PR3010. Sound looping exists for long time. Callback on sound playback finish still not implemented.
>
PR 3010: https://github.com/cocos2d/cocos2d-x/pull/3010

thanks. it looks very promising!

#14

What do you think of RTTI?

#15

Extended and improved debugging can be useful too. I can give overview of some possible improvements:

  • On android and tizen (maybe somewhere else) each log entry have tag. We can add CCLog version that allows to customize tag, and maybe add few macros where __FILE__ and __LINE__ or __PRETTY_FUNCTION__ (__FUNCTION__ on Microsoft compiler) passed as tag.
  • API to print stack traces on normal execution, i.e such stack trace marks some dangerous place in code that can have logic error. I’ve implemented and tested stack tracer for Linux, iOS, android (should work on OSX and blackberry too), see [1]
  • Extended information in debug mode disabled in release builds, for example, Sprite can keep human-readable name of resource from which this Sprite created. Ex: file: resource.png or frame: yellow_monster_head.

[1] http://paste.ubuntu.com/5838441/

#16

Finally, this is just what i want.

I think these changes are going to be great, what an amazing community cocos2d has!

I entity feature is music to my ears, i’m also wondering if you will be making cocos2dx more unit testable? it would be nice to have an easy way of quickly testing out some logic.

If at all possible i would like to see an improvement with the way we save game state. It would be nice to see the back of CCUserDefault (is this an objective c pattern?) and instead have a better abstraction that just handled saving for you depending on the device your using, with more user defined options.

Maybe add one that allowed XML,Json or SQLLite with some overridden methods for extensibility. just a thoughts

Thanks

#17

My number one item for the wishlist would be use of a common library to manage the window/opengl side of things. At the moment, linux uses GLFW, which is great, as it’s got easy hooks for keyboard and joystick support (both of which I need for my current project). But win32 and mac use platform specific code, which GLFW could do, and provide easy access to the keyboard and joystick events (which I could use even if cocos2d-x didn’t provide code for!).

#18

One of my concerts in having the proj.linux, proj.ios, etc, inside the library folder is that we cannot include the “original” github repositories since we have to modify them by adding the compile subdirectories. Also, it is not obvious that the Makefile / make projects are there. Perhaps we should have a sort of “make” or “build” directory.

cocos2d-x is very stable and promising game toolkit, AFAIC 3.0 should primary concern stability and all debuging done with quoted subject solved.

It’s the step now very close to have one Makefile file in root of the project which would be responsible for all firststep checking of installing and possible run default build. In the means of marketing some 30 seconds videos could be made from screen captured clicking on simple makeall or makeall.bat with run on default platform (choosing from IOS/Android/… list of succesfull built subproject).

Average user know how to google after he actually see installed and running c++ game platform on his comp. :slight_smile: Even experts may give up if something last for quit long.

#19

i wish blur options in node