LearnCocosTV 6: One Small Script for Man

On February 27, 2012, in LearnCocosTV, by Steffen Itterheim

In this episode of LearnCocosTV I demonstrate how to write and animate a Cocos2D scene with KoboldScript.

KoboldScript is more than just writing the same Cocos2D code but with a scripting language. Most other scripting language bindings for game engines simply translate the game engine’s C/C++/Objective-C API 1:1 (more or less) without introducing new concepts, adding more comfort by simplifying common tasks, or utilizing the powerful features of whatever the scripting language has to offer.

KoboldScript goes three steps further than that – one by tightly integrating the setup of scenes via defining the node properties in a tool-friendly tree structure (Lua table) that you can both write manually or create programmatically using Lua’s built-in features.

Two, by using Statemachines to drive game logic while also providing free Lua scripting via user-specified Lua callback functions. And three, by adding a (MVC-ish) component system with re-usable abilities and behaviors to all Cocos2D nodes.

Unfortunately I ran out of time at the end so I couldn’t even say goodbye. I hope you don’t mind. :)

Episode #6 – One Small Script for Man …

• KoboldScript Demonstration
o How to create Scenes with Sprites, etc
o How Abilities & Behaviors work
• iDevBlogADay: Asynchronous Texture Loading
o Cocos2D Webcam Viewer speedup

LearnCocosTV 5: Pretty State Machine

On February 13, 2012, in LearnCocosTV, by Steffen Itterheim

KoboldScript is coming! KoboldScript brings Lua scripting to Cocos2D and Kobold2D, with Objective-C performance for the StateMachine part and faster-than-Wax performance for the runtime Lua functions.

More details and first looks at some early development scripts in this LearnCocosTV episode. I’ll have something more visual to show in 2-4 weeks.

Episode #5 – Pretty State Machine

• KoboldScript: Lua Scripting for Cocos2D & Kobold2D
o Poll: Which scripting language for Cocos2D?
o iDevBlogADay: Text Editors for Lua
• KoboldScript combines:
o Lua StateMachine generator (full ObjC performance)
o Runtime Lua functions (faster than Wax)

Continue reading »

Tagged with:  

This Kobold2D FAQ article explains the difference between Corona SDK and iPhone Wax library, and evaluates the existing and future options for Lua scripting in Kobold2D.

Continue reading »

Kobold2D Website now online!

On August 28, 2011, in cocos2d, Kobold2D, by Steffen Itterheim

The Kobold2D Website is now online. Go, have a look and let me know what you think.

Here are some pointers to get you started about Kobold2D (in case you haven’t heard) and the Kobold2D website:

 
Not sure what that means? In essence Kobold2D wants to make development with Cocos2D easier and more powerful for you. And in case you’re wondering: yes, Kobold2D is free and open source.
 
Some of the things you should know about Kobold2D:

The Ultimate Cocos2D Project: Startup

On March 12, 2011, in Kobold2D, by Steffen Itterheim

The Ultimate Cocos2D Project is: Kobold2D!

Put simply: Kobold2D is designed to make Cocos2D developers more productive.

Original Post

Time for a weekly update. This time about startup code and configuration. One of the things that I frequently encountered following the development of Cocos2D and working with it, is how any change to the startup code – the main function, the App delegate and the root ViewController – caused issues and headscratching among developers.

I decided it doesn’t need to be this way.

The main() function

A code snippets speaks more than words:

[cc lang=”ObjC”]
int main(int argc, char *argv[])
{
return KKMain(argc, argv, NULL);
}
[/cc]

That’s right, all of the startup code is now part of the project’s source code. You can still do whatever you need to do before and after the call to KKMain (probably nothing, except maybe anti-piracy code). And the third parameter (NULL) to KKMain is reserved for future use, to pass in any configuration parameters if the need arises.

Let’s see what KKMain does:

[cc lang=”ObjC” height=”650″]
int KKMain(int argc, char* argv[], SMainParameters* userParameters)
{
SMainParameters parameters;
initMainParameters(&parameters, userParameters);

#ifdef __IPHONE_OS_VERSION_MAX_ALLOWED
NSAutoreleasePool* pool = [[NSAutoreleasePool alloc] init];
#else
// Mac OS X specific startup code
[MacGLView load_];
#endif

// This makes the CCDirector class known to wax:
[CCDirector class];
// wax setup is sufficient for all intents and purposes
wax_setup();

[KKLua doString:kLuaInitScript];
[KKLua doString:kLuaInitScriptPlatformSpecific];
[KKLua doString:kLuaInitScriptForWax];

// This loads the config.lua file
[KKConfig loadConfigLua];

// run the app with the provided general-purpose AppDelegate which handles a lot of tedious stuff for you
#ifdef __IPHONE_OS_VERSION_MAX_ALLOWED
int retVal = UIApplicationMain(argc, argv, nil, parameters.appDelegateClassName);
[pool release];
#else
int retVal = NSApplicationMain(argc, (const char**)argv);
#endif

return retVal;
}
[/cc]

The usual, really, except that it also initializes Wax and thus Lua for your App as well as providing the necessary startup code for both supported platforms: iOS and Mac OS X. The KKLua class is an Objective-C wrapper around the most imortant Lua functions, most notably it has the doString and doFile methods which allow you to run any Lua code or file containing Lua code.

KKConfig is a class that loads a Lua table and stores it in a NSDictionary for fast access to Lua parameters at runtime. I’ll discuss it in detail another time. The main purpose of KKConfig is to loadConfigLua, which loads the config.lua script returning a table containing startup parameters and making those parameters available to Objective-C.

Config.lua in detail

Let’s have a quick look at an excerpt of the config.lua file. It contains all of the startup parameters a developer using Cocos2D would ever want to tweak in a conveniently editable Lua script:

[cc lang=”Lua” height=”400″]
local config =
{
KKStartupConfig =
{
— load first scene from a class with this name, or from a Lua script with this name with .lua appended
FirstSceneClassName = “GameScene”,

— set the director type, and the fallback in case the first isn’t available
DirectorType = DirectorType.DisplayLink,
DirectorTypeFallback = DirectorType.NSTimer,

MaxFrameRate = 60,
DisplayFPS = YES,
DisplayFPSInAdHocBuilds = NO,

— Render settings
DefaultTexturePixelFormat = TexturePixelFormat.RGB565,
GLViewColorFormat = GLViewColorFormat.RGB565,
GLViewDepthFormat = GLViewDepthFormat.DepthNone,
GLViewPreserveBackBuffer = NO,
GLViewMultiSampling = NO,
GLViewNumberOfSamples = 0,

Enable2DProjection = NO,
EnableRetinaDisplaySupport = YES,

— … and many more settings!
},
}

return config
[/cc]

Since you don’t want to guess what those settings mean, I’ve documented them for you:

Config.lua Parameter Documentation (PDF)

This should also illustrate the kind of documentation I’m striving for. Documentation will be available online. It’s created in a Confluence Wiki with the help of ScreenSteps for more visual, step-by-step documentation.

App Delegate & Root ViewController

You may be wondering how you can modify and tweak the App Delegate and Root ViewController if they’re both part of the distribution, rather than copied into each project? That’s actually very simple: both are regular Objective-C classes, so they can be subclassed and methods overridden as needed.

Both KKAppDelegate and KKRootViewController provide a default implementation which you can tweak with the config.lua parameters. If that shouldn’t be enough, for example if you have to plug in some 3rd party code into the App Delegate, each project will have a subclass of KKAppDelegate and KKRootViewController in which you can override any of the UIApplicationDelegate and UIViewController protocol methods. Usually you would first call the super implementation, unless you want to entirely replace the default behavior.

The KKAppDelegate method calls one specific method called initializationComplete at the end of the delegate method applicationDidFinishLaunching. This allows you to run any custom code right before the first scene is shown. You can use that to call the CCDirector runWithScene method manually, in case you have more than one scene which might be run as first scene depending on certain conditions.

If you set the FirstSceneClassName config.lua setting, the project will first check if there’s a classname.lua file. If so, it will run this Lua script, assuming it contains the implementation of the first scene (more on that some other time). Otherwise it checks if there’s an existing Objective-C class derived from CCScene with that name, and if so allocates and initializes this scene and calls runWithScene for you.

In essence

From your point of view, the execution of the App now starts with the first scene, before that there’s no code that you’ll have to concern yourself with. Any startup configuration tweaks that you need to do can be done comfortably via the config.lua file, and the only setting you’ll need to change is the name of the first scene’s class name or Lua script. In addition you’ll get access to some features out of the box, for example adding iAd banners is now a simple on/off switch.

Moreover, any time there’s a change in Cocos2D’s startup code, or the startup code in any other library (most notably Wax), I can just make those changes for you and release a new version. This isn’t something you need to concern yourself with anymore, and makes upgrading existing projects to new versions of Cocos2D and other libraries even easier.

The Ultimate Cocos2D Project: Libraries

On March 4, 2011, in cocos2d, Kobold2D, by Steffen Itterheim

The Ultimate Cocos2D Project is: Kobold2D!

Put simply: Kobold2D is designed to make Cocos2D developers more productive.

Original Post

Last week I wrote that I’m Building The Ultimate Cocos2D Xcode Project. In today’s weekly update I wanted to give you some more details on the use of libraries in that project.

Cocos3D included

So there happens to be a Cocos3D now. Rather than being part of the Cocos2D distribution, it’s an extension project. Guess what that means? Right, installing Cocos3D means fumbling with the dreaded install-templates.sh script (see this Cocos3D tutorial). Of course the first user reactions were: how do I install it? Installation failed, what am I doing wrong? And so on …

The Ultimate Cocos2D Project wouldn’t be ultimate if it didn’t include Cocos3D out of the box. And unmodified of course, as with all included libraries I want to make it as simple as possible to replace one library version with another. Once you get to half a dozen of included libraries, maintaining them all can become a hassle, so the very least I can do is to make it easy for everyone to upgrade specific libraries.

Obviously: Cocos2D included

Of course Cocos2D is also included as a static library as opposed to cluttering your project with all of its source files. Xcode project references make it very convenient to add external code and keeping it seperate. I’ve described the process in detail in my Cocos2D Xcode Project tutorial but since then I’ve learned a couple more things about how to make this even better.

For example, I no longer include cocos2d-iphone directly, instead there’s a seperate Xcode project in between so that I have full control over build settings (using XCConfig files) and make it possible to build both iOS and Mac OS targets in the same Xcode project. I will also include the current version of Cocos2D in the download because my goal is to make everything work out of the box.

No fumbling with install scripts, no additional downloads necessary, no need to modify any Xcode build settings – including developer certificates and header search paths. Build configurations for Ad Hoc and App Store release builds are also included, which will create .IPA and .ZIP files for you ready for Ad Hoc distribution respectively upload on iTunes Connect.

Popular libraries included

Now let’s get to the juicy part. Early on I realized that Cocos2D users often needed (or wanted) to include other libraries. Some of them have become so popular among the Cocos2D crowd that they could as well be part of the official distribution. Alas, they’re not. That’s a service I want to provide.

Often those libraries require special and non-obvious steps to successfully add them to an existing project. All too often those steps are either undocumented, untested, hard to follow, refer to outdated versions of Xcode, iOS SDK, etc. and generally require technical expertise of project configuration and compiler settings.

This is all taken care of for you. Here’s the list of libraries that are already included in the Ultimate Cocos2D Xcode Project:

That is quite a list. All you need to do to use these libraries is to either enable them in code or merely include the header file and start using them. If you worry that all these libraries will bloat your App, rest assured that Xcode is very clever: if you don’t actually make use of a static library (eg don’t include any of its header files), it will not be linked with your App and not waste any space or performance. I verified that.

Update policy

These are a lot of libraries to keep up to date. I plan to make about 4-8 point releases each year, usually triggered by a major (speak: non-beta) release of Cocos2D. If updating other libraries justifies an update depends on the library’s importance and the significance of the update.

Your libraries

Adding your own libraries to the project will be easy and the process will be documented. This will encourage code-sharing because your library will just work with other user’s project, it only needs to follow a few simple guidelines to become plugin-capable. This opens the door for better and tighter integration of 3rd party code into your projects. Even if you don’t intend to share your code, you’ll still benefit because your code will be easier to re-use and maintain.

Also, if you like you can make a request for a specific library or additional source code that should be included in the project, please leave a comment. I’ll see what I can do. :)

Cocos2D Xcode Project on Github

On November 4, 2010, in cocos2d, tools, Xcode, by Steffen Itterheim

My Cocos2D Xcode project is now on Github. Open-source, free, properly MIT Licensed, includes the rootViewController and supports Cocos2D v0.99.5 rc0.

I’m also working on (with) a greatly enhanced version of the Xcode project. It integrates wax (Lua) and a Game Object Component System that i termed “gocos”. Also comes with a lot more useful convenience classes.

But the big idea is to actually upload (or link within github, if I can figure out if and how that works) all dependent projects into one repository, so that you can download everything at once and it works out of the box. Currently there are 3 projects referenced by cocos2d-project: gocos (let’s call it a library of convenience and gameplay code for Cocos2D), wax (Lua support) and obviously cocos2d-iphone. So everything that’s needed is going to be bundled in one big package, which voids all of the version incompatibility issues.

You can still experiment with different versions of these libraries but in that case I think you know what you’re doing and that issues are to be expected. But being a github repository, you can of course clone and commit changes.

Appetizer

Here’s what I’ve done with Lua. I’m currently using it only as a better plist replacement for settings. It’s better than plist because you can comment on each item, you can sort them easily, you can run functions and algorithms to generate values or load additional data, and in general it’s a lot easier to work with than the plist editor. Here’s a reduced config.lua that is loaded at runtime into a hierarchy of NSDictionary objects:

[cc lang=”lua”]
local config =
{
AccelerometerControls =
{
UpdatesPerSecond = 60, — 60 Hz
Responsiveness = 0.997,
SensitivityX = -2,
SensitivityY = 2,
MaxVelocity = 100,
},
}

return config
[/cc]

And this line of code loads these values and assigns them to the correspondingly named properties of the target class:

[cc lang=”objc”]
[Config loadPropertiesFromKeyPath:@”AccelerometerControls” target:self];
[/cc]

That’s all you need to do to transfer the values from config.lua into a class instance. Huge timesaver! The only drawback is that it currently can’t differentiate between float, int and bool (due to NSNumber), so it currently only supports float properties.

Tagged with:  

Apple removed programming language restrictions

On September 10, 2010, in Mobile Business, by Steffen Itterheim

As summarized by DaringFireball, Apple has loosened their restrictions of section 3.3.1 of its iOS Developer Agreement:

In particular, we are relaxing all restrictions on the development tools used to create iOS apps, as long as the resulting apps do not download any code. This should give developers the flexibility they want, while preserving the security we need.

Previously, the only programming languages allowed to write iOS Apps were C, C++, Objective-C and Javascript. This has now been removed. For cocos2d developers nothing changes, except maybe that you can feel more comfortable embedding a scripting language like Lua into your games. As long as you don’t allow the Lua scripts to be changed by users, or download or otherwise modify/replace bundled Lua scripts. That wasn’t illegal before, however, yet after the change in section 3.3.1 it put a lot of doubt and worry into developers looking into using Lua. So you can now feel much more comfortable using Lua in iOS games, for example by using iPhone Wax.

The removal of these language restrictions is essentially good news for Unity developers (read their statement), and those who wish to develop iOS Apps using a Flash cross-platform compiler and also those using Corona Game Edition, which is entirely Lua-based. And speaking of which, Corona offers developers to purchase Corona SDK and Game Edition at just $99 until only September 15th, after which you’ll have to pay for each product seperately and the price goes up to $249. Just in case you were eye-ing it.

Tagged with: