Access Keys:
Skip to content (Access Key - 0)

Kobold2D™ Documentation

The All-In-One, Ready-To-Go development solution for cocos2d-iphone developers. Open source, ARC enabled, for iOS & Mac OS.

Switch to: Japanese Documentation

Level Up!

The Learn Cocos2D Book

Line-Drawing Game Starterkit

Excellent template code for creating your own Line-Drawing game, similar to popular titles such as Flight Control, Harbor Master, and Pirate Bay.

The iPhone RPG Engine

Rapidly create your own RPG or action-adventure game with this complete starter kit. Includes an ebook, game source code and a royalty-free art package.


This guide explains by example how an existing Cocos2D project can be converted to a Kobold2D project. In this step by step guide the project ParticleEffects03 from the Learn Cocos2D book will be migrated to Kobold2D.

This is a general guide to explain the process of converting an existing Cocos2D project to Kobold2D. This guide can not offer a solution to every possibly required change to successfully migrate every project. Each project is different and may require custom modifications or experience issues not outlined in this guide. Please use the Kobold2D Forum if you need additional help on migrating a project to Kobold2D.

If your project is nearing completion it may be better to finish that project as is. You won't benefit much from converting an almost complete project to Kobold2D and you risk running into subtle and time-consuming issues that might delay the project's release. Instead just start your next project straight as a Kobold2D project.
As you migrate from your Cocos2D project to a Kobold2D project, be aware that the third party libraries provided by Kobold2D (including but not limited to: cocos2d-iphone, cocos3d, Box2D, Chipmunk, etc) may be of a different version. Be prepared to adapt your code accordingly.

Create a Kobold2D Project

The first step is to create a new Kobold2D project from one of the templates. It is recommended to use the Empty-Project template (screenshot pictures the Hello Kobold2D template) even if your project uses a physics engine. All Kobold2D project templates are already setup for both physics engines.

The new project is named _Particle-Effects-Template_ because the goal is to turn it into a Kobold2D template project. You should use an appropriate name for your new project.

Cleanup the new Kobold2D Project

There are a few files which won't be needed by your project, depending on which project you use as a starting point. Hence the recommendation to pick a simple project, preferably the Empty-Project template.

For example classes like the HelloWorldScene class and several resource files (Pow.caf, ship.png, ship-hd.png) will not be needed in your converted project.

Keep config.lua
Do not delete the file config.lua! Kobold2D projects require it.

When removing unneeded source code and resource files you will want to Delete these files to also remove them from the file system:

Add your project's source code

Select the Projectfiles group, right-click or option-click to bring up the menu. Then select Add Files to "projectname".... This will bring up the following Add Files dialog:

Locate your original project's source code files. Be sure to select all of your source code, but only the source code that you wrote.

In particular, make sure you do not include the following files:
  • GameConfig.h
  • (ProjectName)AppDelegate.*
  • RootViewController.*
  • main.m
  • (ProjectName)_Prefix.pch
  • any library source code, such as: cocos2d, box2d, chipmunk, etc. source code files
In case you accidentally added one of the above files you should select and delete them from the Kobold2D project. Just make sure you delete those you added and not the ones that may have already existed in the Kobold2D project.

Before clicking Add make sure you've selected the checkbox Copy items into destination group's folder (if needed) and the corresponding targets that you want to support (if in doubt select both).

Add your project's resource files

Now select the Resources group and option-click or right-click. Once again select Add Files to "ProjectName"... to bring up the Add Files dialog again, this time for adding your project's resource files:

Select the resource files that are unique to your project, eg the ones that you created and added.

Do not include the standard resource files! In particular, make sure you do not include the following files:
  • Info.plist
  • Default.png, Icon.png or any variant (Default@2x.png, Icon@2x.png, etc.)
In case you accidentally added one of the above files you should select and delete them from the Kobold2D project. Just make sure you delete those you added and not the ones that may have already existed in the Kobold2D project.

If you have modified any of the default resource files above, make a note (preferably not a mental note as you'll likely forget - you are human, right?). That note should read:
Remember to copy my project's modified standard resource files over the ones provided in the Kobold2D project, using Finder.
Also remember to check the Info.plist file for any modifications/additions that I need to copy from my original project to the new Kobold2D project's Info.plist file.

About Info.plist
You should be aware that the Hello Kobold2D project contains two Info.plist files, one for iOS apps and one for Mac OS X apps. If you plan to support both platforms you may need to modify both. If you don't, make sure you modify the correct one. Platform-specific resource files are located in the Projectfiles-iOS respectively Projectfiles-Mac folders.

Before clicking Add make sure the Add Files settings are correct. The checkbox Copy items into destination group's folder (if needed) must be checked as well as the corresponding targets that you want to support (if in doubt select both).

Modify the config.lua

Now open the file config.lua in the new Kobold2D project. You will find it in the Projectfiles/Resources group. The above screenshot gives you hints as to what you may want to or need to change.

At the very least you will have to change the FirstSceneClassName parameter to the name of the CCScene or CCLayer class that Kobold2D should load as the very first scene. You may also want to verify that the initial device orientation and autorotation match those of the Cocos2D project.

FirstSceneClassName is a class name, not file name!
Note that this parameter should indicate the class name, not the file name. In the case of the particles project the file names of the first scene was HelloWorldScene.h respectively .m but the class was actually called just HelloWorld.
Do not remove entries from config.lua which are seemingly unneeded. Kobold2D may rely on those, and you may later want to be able to change some of these settings without having to look them up in the Kobold2D documentation.
If you are unsure which settings were used by your Cocos2D project, have a look at that project's AppDelegate.m and GameConfig.h files. If you don't remember making any changes to these files the defaults provided by Kobold2D should work fine. If you do encounter strange issues in the Kobold2D version of your project, such as multi-touch not working or performance degradation, it is most likely caused by different startup settings. Please refer to the Config.lua Settings Reference for more information.

Changes to your "first scene" class

If you allow Kobold2D to run your first scene via the config.lua setting FirstSceneClassName then the standard class method provided by Cocos2D project templates, namely the method +(id) scene is no longer being called. If the scene method contains just the default code adding a layer to the scene, you will probably not notice a difference. But if you have custom code in that method, you have these options:

  1. rename the method from (id) scene to (id) node in the implementation and interface
  2. you can also move the +(id) scene code to layer's init method
  3. call your first scene manually in the AppDelegate method -(void) initializationComplete

Option #1 is the simplest solution. It should work in most cases flawlessly. But if not you might want to try the other options.

Option #2 is usually trivial, if all you did in the scene method was adding more layers. Those layers can also be added in the init method of the same class. If that class is itself a layer, try adding the new layers to [self.parent addChild:myLayer] instead of directly to self (the HelloWorld class in this case).

Option #3 is also trivial and simply overrides Kobold2D's way of running the first scene by reverting to the old-school, Cocos2D way to launch the first scene. The code added to the AppDelegate class would look similar to this and ensures that the +(id) scene method is called as usual:

Other Alterations

Some projects may require additional changes or manually migrating code. That is where you should carefully test each step in the "migratory process" and where we'll find it difficult to provide support, as every project is different. But feel free to ask for help in the Kobold2D Forum.

Take Small Steps
If you have to tread unpaved territory when migrating your project it helps to first get your project up and running, if incomplete. Then migrate custom code step-by-step in small bunches to the Kobold2D project, if necessary commenting out some code to make it work. Always test each step. Repeat this process to slowly but surely and consciously get closer to the final, working project.

Migrating AppDelegate & RootViewController changes

In particular if you have modified the AppDelegate or RootViewController classes you will have to migrate these changes step by step to the Kobold2D project. Just be sure to call the super implementations for any overridden methods in those classes, as Kobold2D implements default AppDelegate and RootViewController classes which perform default operations, such as properly enabling and performing autorotation based on the config.lua settings.

Migrating Default Resources

Remember the non-mental notes you should keep? Now is the time to compare the Info.plist files of the two projects and merging any changes to the ones in the Kobold2D project.

Likewise, any modified default image (Default.png, Icon.png) you should now simply copy over the existing ones in the Kobold2D project's Resources folders, using Finder. You can then verify in Xcode by selecting these files that they have been correctly updated.

Migrating a third party library not provided by Kobold2D

This depends on how you've added that library to your project. If it was, like Cocos2D, simply added to your project by dropping the library's source code files to your project's target, you can just treat that library's code as if it were your own.

If the code is compiled as a static library you may have to add that particular target (or one for each supported platform) to your Kobold2D project.

Let us know!
If you think the library you're using would be great to have in Kobold2D, and provided that library is free to distribute and open source, you might want to request that library being added to Kobold2D. You can do so in the Kobold2D Forum.

Warnings and errors that weren't there before

Migrating code to a Kobold2D project can give you warnings or errors that weren't there before. It's possible that the code still works but isn't 100% conforming to good coding practices. For example, the Xcode default build settings will not warn you about possibly undeclared selectors, instead your app will just crash while it is running. Kobold2D has this warning enabled by default, and also turns all warnings into errors since warnings should be taken serious.

The simplest fix is to find the offending compiler warning setting and to turn it off (or on) in your project's build settings. But you might want to take the opportunity and check if the new warnings/errors indicate potential bugs in your project.

Removing unsupported platforms

If your project does not support a particular platform, be it iOS or Mac, then you may want to remove:

  • the platform's target
  • the platform's build scheme
  • platform-specific resource files (see Projectfiles-iOS respectively Projectfiles-Mac)
You may want to consider keeping the unnecessary platform specific targets if there's even a slight possibility that you might want to go cross-platform eventually. Adding a platform specific target back in isn't as straightforward as it may seem.

Labels:
None
Enter labels to add to this page:
Please wait 
Looking for a label? Just start typing.
Adaptavist Theme Builder Powered by Atlassian Confluence