Some rant with API changes between "big" releases

cocos2d-x C++
#1

Hi all, I’m currently doing a job: move my game project which based on cocos2d-x-1.x to 2.x, and met tons of issues with API changes.

I’m not sure which clever head had made this decision to change lots of API. But it caused me lots of trouble. My project has about 200,000 - 300,000 lines of code. I’ve suddenly realized there’s a blackhole to make this job done.

It’s not only simply like “find & replace”, it also has lots of issue caused by different usage of API.

For example, 2.x even changed usage of CCDictionary, CCMutableDictionary was deprecated. That means I have to change ALL code using CCMutableDictionary to CCDictionary. Thanks to the new CCDICT_FOREACH macro, I have to rewrite EVERY code visiting a dictionary not used this macro. It’s not a great deal… let me see… only 300 - 400 places has to change. Thank you clever heads!

When I read changes in cocos3.x yesterday, I’ve found a fact that these clever heads don’t even care about their users. They are just interested with these new technologies. Compatibility with previous versions? Go to hell! And they don’t want old users to move to their newest releases easily. So users have to learn their genius inventions. That makes me remind Microsoft’s API. Well, you know what I mean.

In all, you clever heads should provide a solution to these old users that they can move to your new engine easily. You guys release a “big” version annually, old games not die that quick. “Don’t break user spaces” should be #1 concern in my opinion. Nobody want to re-write tons of code after engine upgrade.

#2

There is difference between API and typical framework. API designed for stability and scalability, but programmer should limit it usage as much as possible: you can see this inside cocos2dx sources, all calls to OpenAL or SDL incapsulated in one file. Framework designed to be used everywhere in app, and any API change makes easier writing new apps. Cocos2dx is more framework than API, so it often changes.

>In all, you clever heads should provide a solution to these old users that they can move to your new engine easily.
Cocos2dx 3.0 has CCDeprecated.h header for this (included to cocos2d.h). Qt library have another approach: in version 4 it provides special module qt3support that emulates behavior of Qt3 classes, so programmer needs to do only search&replace to port app from Qt3 to Qt4. Also there is utility that helps to port code from Qt3 to Qt4+qt3support, and from Qt4 to Qt5.

Also, can you please write detailed post about obstacles in porting from 1.x to 2.x?

#3

Hi Sergey:

Unfortunately I’m still trapped inside my job and don’t know how much issue still remains. Maybe I can provide some solution after my job’s done.

As far as I know, there’s 2 major issues:

  1. Deprecation of CCMutableDictionary & CCMutableArray
  2. Move OpenGL ES 1.0 to 2.0, also many API rewritten, that makes me re-implement some base-level engine code which I modified before.
#4

Any ideas how the “clever heads” should evolve the framework and satisfy everyone? It’s not so easy to implement new features and pull tons of deprecated stuff.
Moreover, in the world of software development it’s quite typical for major versions to be not fully compatible with each other.

#5

dot squid wrote:

Any ideas how the “clever heads” should evolve the framework and satisfy everyone? It’s not so easy to implement new features and pull tons of deprecated stuff.
Moreover, in the world of software development it’s quite typical for major versions to be not fully compatible with each other.

Dot:

I’m not asking for a 100% compatibility. But honestly, I can’t understand why change the most basic data structure like CCMutableDictionary. For hash table’s speed? I have to say it’s totally not a good idea.

First, hash table(uthash) makes debug much more difficult. You can try this yourself, make a random NULL pointer(or released object) in a big dictionary, and try to find out which one. The native C++ vector was supported by XCode’s visual LLDB environment, you can read every elements in your dictionary easily. But with uthash? You don’t know anything if something goes wrong. Forgive my ignorance, if anyone has any idea of how to debug CCDictionary easily, please share it.

Second, because of the deprecation of CCMutableArray, implementation of CCFileUtils::dictionaryWithContentsOfFile() also changed. Let’s see another example under iOS:

Before:

// the value is a array
if ([value isKindOfClass:[NSArray class]]) {
CCMutableArray<CCObject*> pArray = new CCMutableArray<CCObject>;
for {
static_addItemToCCArray;
}
pDict~~>setObject;
pArray~~>release;
return;
}
After:
// the value is a array
if {
CCArray*pArray = new CCArray();
pArray~~>init;
for {
addItemToCCArray;
}
pDict~~>setObject(pArray, pKey.c_str());
pArray->release();
return;
}

See the difference? EVERY element in dictionary before as CCMutableArray have to be changed to CCArray. This is the tricky part, since tons of code was implemented using CCMutableArray. So I have 2 choices: 1. Change every pieces of code related before, change CCMutableArray to CCArray, which means at least 10K lines of code should be rewritten, and hundreds of bugs made. 2. Implement a “dictionaryWithContentsOfFile” method like old times, which seems nice and easy, but also caused codes ugly, confused to other developers.

What I’ve mentioned before was just a piece of iceberg. Let’s just imagine if Apple decided to change the usage of NSDictionary without providing any method to compatible with old codes. I’m pretty sure their forum will be crowded with angry developers next morning. So that’s why I have to say it’s not a good idea, old users are already in hell.

#6

Solution of your problems is quite simple, though radical: don’t upgrade to the newest major version in the middle of development. Start using the new major version for the new project only.

#7

You will be sad to learn that after you upgrade to 2.x you need to upgrade to 3.x soon after.

#8

dot squid wrote:

Solution of your problems is quite simple, though radical: don’t upgrade to the newest major version in the middle of development. Start using the new major version for the new project only.

+1

Maintaining backwards compatibility is really only important if the underlying framework can change independently from your application (like if cocos2d-x was a DLL instead of a static library). However, it isn’t and can’t without explicit actions from the developer such as yourself. As Dot said, you pick your framework and work within that major version for that release.

#9

I agree, the best course of action is to not upgrade in the middle of a project without a compelling reason (where benefit outweighs cost).

#10

Shuaiying Hou wrote:

Hi all, I’m currently doing a job: move my game project which based on cocos2d-x-1.x to 2.x, and met tons of issues with API changes.
>
I’m not sure which clever head had made this decision to change lots of API. But it caused me lots of trouble. My project has about 200,000 - 300,000 lines of code. I’ve suddenly realized there’s a blackhole to make this job done.

Yeah, I hate upgrading to the new version, it always takes 8+ hours minimum, the tedious pain is similar to when I do my taxes.

It’s not only simply like “find & replace”, it also has lots of issue caused by different usage of API.
>
For example, 2.x even changed usage of CCDictionary, CCMutableDictionary was deprecated.

Yeah, that one hurt a lot! Have to agree, there was no need to remove CCMutableDictionary. If those in power want to add a new faster class that’s fine, just don’t remove the old version please!

And on top of that CCArray caused me so many memory leak problems (I’m sure it is buggy) I ended up writing my own class.

So users have to learn their genius inventions. That makes me remind Microsoft’s API. Well, you know what I mean.

I worked with MS API’s for 15 years, I can’t remember having many problems with API changes, they were always really simple changes.

In all, you clever heads should provide a solution to these old users that they can move to your new engine easily.

That isn’t the cocos2d-x way.

The very limited documentation (test sample) and the occasional long lasting bugs, and the upgrading problems, make me often consider moving to another engine. One day….

And another problem is occasionally you HAVE to upgrade. I did from 1 to 2 to get the design resolution thing to work on Android. Then from 2 to 2.1.4 to fix a sound problem on Android. But now my iOS is still on the older 2.0.4 as the even newer design-resolution system on 2.1.4 breaks my iOS version.

I’m not looking forward to upgrading to v3 and will put it off as long as I can.

I like ranting too :slight_smile:

#11

The design resolution thing is kicking my butt. Does anyone have some documentation about it? I cannot get CCB and Tilemaps to work together :frowning:

#12

I worked with MS API’s for 15 years, I can’t remember having many problems with API changes
Microsoft’s API functionality and interface are in DLLs which can change independently of your application, so in that instance it makes sense to maintain backwards compatibility. Cocos2d-x is statically linked and compiled into your application, whichever version you want is what you get. It has more freedom to allow changes with major releases.

#13

Gav GMTDev wrote:

I’m not looking forward to upgrading to v3 and will put it off as long as I can.
>
I like ranting too :slight_smile:

IMHO, there’s no way you can upgrade from v2 to v3 since memory management was changed, tons of memory leak issue will occur in your old project.

I have to take back my words with Microsoft’s API since I’m not a experienced Windows developer. Sorry Mr. Steven! :slight_smile:

#14

If what you are saying about v2 and v3 is true, that sucks very much for everyone.

The leadership on the project will move on to v3 and stop fixing bugs in v2.

Everyone who’s been a user for long enough to have production v2 code is stuck.

Less support, more bugs, no patches :frowning:

#15

That’s why it is called v2.0, v3.0

#16

Dont mean to sound rude, but then this is an Open Source Project. The people working to fix these bugs and add new features do so on their own time and they dont get paid for it(most of the time, their effort isn’t even appreciated) . They do it for the love of programming and making life simpler for other people . No one is stopping anyone from moving onto other Framework(s) / SDK (s) that are better (but one has to pay for).
I know the pain that is caused in upgrading the version of cocos2dx, having done so myself for many of my projects.

Instead of ranting on the forums and passing sarcastic comments, help these people make cocos2dx better.

#17

The Devil wrote:

Dont mean to sound rude, but then this is an Open Source Project. The people working to fix these bugs and add new features do so on their own time….

You should google CocoaChina and games like their Fishing Joy, the main people behind Cocos2d-x are doing just fine…. or should I change that to amazingly well… its really very cool, go read about it now.

But you are correct, Cocos2D-X is free to use and is in my opinion the best 2D engine out there (free or paid), I recommend it to anyone who cares to ask (and some who don’t). Inconveniences caused by things like the changes in new releases is nothing compared to the man hours put in by the developers and the worth of the engine to the people who get to use it (us).

#18

The official provides a guide about V2 migration:

http://www.cocos2d-x.org/projects/cocos2d-x/wiki/Cocos2d-x_v20_migration_guide

But only API changes was listed, usage changes were not included.

For example:

@ Moved CCFileUtils::dictionaryWithContentsOfFile to CCDictionary::dictionaryWithContentsOfFile, added CCArray::arrayWithContentsOfFile method.@

If you only changed API according to document it will be a big mistake, since this API returned an CCDictionary instance without calling autorelease() before, but called autorelease() after. So you have to check this very carefully. Same story happened at CCDictionary::createWithDictionary. Since lower version like V1 & V2 is/will out of maintenance, you have to upgrade to higher version sometimes. Different usage of API make things much more complicated.

Like Ricardo says in http://www.cocos2d-x.org/boards/6/topics/30253, V3 will not be forward compatible. I’m not sure the future of games using V2. Will they died soon due to lack of engine maintenance? I believe this will be most of our developer’s concern.

I appreciate all efforts and hard-working that cocos2d-x team has made. Hopefully API stability should be concerned after V3 to make engine upgrade easier.

#19

Finally I made it! After 2 months of hard working!