CCDirector Refactoring and un-singletoning

[andykorth]

CCDirector Refactoring:

The primary goal behind this pull request is to un-singleton the CCDirector. This allows for better scene control, better testability, and clearer separation of platform specific code. CCViews own the reference to the CCDirector, and CCDirectors manage and own individual CCScenes.

Most of the credit goes to Oleg and Scott. Thanks!

Sorry, this is a huge pull request. I was initially breaking it down into smaller commits, but found each one depended on the previous. This pull request is going out now to prevent even larger ones from happening in the future. While this refactoring is not entirely complete, the project is currently working and usable. iOS unit tests, iOS testbed, and Mac has been recently tested. Oleg is working on Android.

Highlights of changes

• CCDirector is no longer a singleton, but the current director is accessible, similar to how CCRenderer is accessible.
• CCView is a common protocol to each platforms view implementation.
• CCScenes have a clearer relationship with directors.
• CCActions were refactored to reflect the possibility that they were added to nodes that haven't yet been added to a scene
  ** CCActionManager is removed and merged into CCScheduler. There was a lot of common functionality there without any common code.
  ** Merging these classes unified pausing behavior.
  ** Pretty big performance improvements both for actions and scheduled timers. (calling update on nodes, etc)
• Refactor scene changing methods. Use presentScene exclusively to change scenes, whether it's the first scene or not.

Areas of continued development:

• Running CCActions in the fixed update loop.
• Queuing scheduled timers on nodes that haven't been added to a scene
• Fixing up test like the package manager tests (testability without a view, etc)
• ContentScale moving out of director.
• Stats label
• Application lifecycle changes w/ director.

Ultimately, there are too many people working on highly related code for these changes not to live in a commonly accessible place. Even if these changes aren't super stable, the alternative is people writing large amount of code independently and having huge merge conflicts at the end. I'm not sure what exactly the stability expectations are of the "develop" branch, but that would come at the cost of regular integration and conflicts.

[rkachowski]

I would recommend renaming this, as having a method startRunLoop along with the attached warning that states "don't call this to start the loop" is pretty counter intuitive

[andykorth]

Ah. I think that warning means the user should never call this method. Honestly it should be in a private header.

It is the method that starts the main loop, but the user is supposed to present a scene, which internally calls this.

The only situations when the user may want to start and stop the run loop is- when a mobile app is suspended (as a lifecycle event), or if they are moving in and out of a cocos2d game within something like a UIKit-based app.

"startAnimation" was a very confusing name, I thought it had something to do with CCAnimations, etc. I'm open to other suggestions, other than "startRunLoop". But is this problem fixed if I just correct the comments and move these to a private header?

[rkachowski]

Yeah a private header would hide this from a user and fixing the comment would make more sense.

[rkachowski]

My main concern is that the currentDirector calls rely on an implicit state existing that isn't directly clear to the end user, where operations will tend to fail if bind/unbind isn't called around calls when the user attempts to interact with the director.

[andykorth]

@NickyWeber Good question. While in theory it can be done, I think real benefits occur in situations like: UIKit apps that run some cocos2d content inside a mostly Cocoa app, which they might navigate away from and back to. Support for multiple views is mostly just a side benefit of un-singletoning the CCDirector.

[slembcke]

Right. It's actually quite difficult, and extremely poorly documented on how to use Cocos2D within a larger application, even if you only want one Cocos view at a time. This does come up pretty often.

One of the benefits of SpriteKit is that it works in a regular UIKit/AppKit way. A SKView is just another view that you can create and destroy as you please. I can't count the number of times I've read comments about how this is a killer SK feature. Cocos2D was designed to control the entire app, and doesn't like to share.

Think about the way Cocos2D integrates with SB. You have a single document view that is open for the entire duration of the app. Lots of shared state when you close one project and open another. No possible support for having two projects open at once. SB is designed around these limitations.

@rkachowski
We should be able to cover all of the entry points pretty easily for anybody using Cocos in a traditional way (one director/view for the entire app's lifecycle). We'll need to document how currentDirector works for the people that want to do more, but it's not more complicated than other contexts (GL, CoreAnimation, etc). I agree that contexts are annoying, and prefer APIs without them, but I don't have an alternative that makes it possible to extend the functionality and still remain backwards compatible.