(Single-Threaded) Latent Functions in C++

I’ve been recently considering conversion of one object oriented Unreal Script like language code into C++ to improve its run-time performance. And while most of the features of the language seemed easy to transform from one to another there was one that wasn’t trivial to do: latent functions.

Now, just to make sure: by latent functions here I mean functions that might take a long time to finish and this is not because they’re heavy functions but because they might need to wait for something. The best example of such function is Sleep().

My goal was to support execution of multiple such functions on a single thread without having to block i.e. whenever the function needs to wait for something it should get paused and it should be possible to resume it later at any time. Pseudo-code sample:

int MyFunction( float a )
    [...]               // Some code
    Sleep( 1 second );  // Wait 1 second
    [...]               // Some code
    Sleep( 2 seconds ); // Wait 2 seconds
    [...]               // Some code


call.Call( MyFunction, 10.0f ); // Call MyFunction with a == 10.0f
while ( !call.IsDone() ) // While not finished
    call.Advance();      // Keep resuming
    [...]                // Other code
result = call.GetResult(); // Done! Now get the result

What I ended up with is a very small library that makes implementing latent functions in C++ a bit easier to write (and read!). My implementation is based on an idea described in Coroutines in C but goes beyond what’s presented there in that it:

  • allows for arbitrarily nested latent function calls
  • doesn’t require programmer to access parameters or local variables via context struct (makes the code look a lot more like ‘normal’ code)
  • fully supports canceling latent call without memory leaks; this is achieved by storing individual parameters and local variables along with their destructor functions

But the main trick stays the same and is the fact that individual ‘case’ blocks can be placed anywhere inside of the ‘switch’ block which allows us to jump pretty much anywhere in the function body – almost like goto instruction. In particular, using this language feature, we can jump to where we left off previously and resume code execution.

The only major limitation of this implementation, and one I’d love to be able to solve but I’m afraid there’s no solution for it in pure C++, is that one can’t place latent function calls returning non-void value inside of an expression, e.g. inside an ‘if’ condition. This is because it’s impossible to use switch-case (or goto) to jump to inside of an expression.

Check out LatentLib on github and let me know what you think. But please keep in mind that it hasn’t been implemented with high performance in mind (separate dynamic memory allocation per variable and stack frame) but more so to present the general concept.

Posted in game engine, general programming, scripting languages | Tagged , | 4 Comments

Rainbow Hero – my new game

After some very long and slow, mostly after hours, development I have finally released my new puzzle game – Rainbow Hero:

The game is an old-school type of game as far as mechanics with some painterly stylized graphics and a fairy tale style audio.

     game7game8     game4

One of my primary gameplay inspirations for Rainbow Hero was Stone Age – a game released for PC DOS in 1992. I remember when I played it with my father on my old good Intel 486. Years later, I played it again with my wife. Both times it was a lot of fun. Clever, often seemingly impossible, puzzles and lots of cool ideas.

stone-age_1  stone-age_11

Another inspiration was Lasermania – game released in 1990 for Amiga. I liked the general idea of reflecting lasers but I considered the game prohibitive as far as difficulty level. Even though I am a patient kind of gamer and I love solving puzzles, I got stuck on some of the very first levels and didn’t want to continue.

VXPzeTt    lasermania_l09_s

There’s a couple more inspirations including general pushover mechanic as well as some totally original ones. I’ve always loved playing puzzle games and I guess with Rainbow Hero it is my attempt at gathering together some of the most interesting puzzles that could be applied to grid based levels and putting them together into a game.

Sokoban    02_sokoban-1988_29

One of the cool things that I am particularly happy with is time rewind feature that simply lets you go back in time – either when you get stuck or just want to try different approach. This isn’t anything new – games such as Braid use this a lot (and not just for purely time rewind) – but it makes the game a lot more player friendly.


Time rewind in action

In fact, it was pretty straightforward to do code wise. All I had to do was to store game state for each frame. Then, with ‘rewind’ button pressed, the game gets continually restored from past states. A little bit of work went into optimizing memory usage, so that the game state is small enough I can safely store hours of gameplay.

If you’re into serious puzzle solving Rainbow Hero might be the game for you. It is already available on Steam and directly via game website. And if you happen to play the game I’d love to hear what you have to say about it.

Posted in general programming, indie game development, puzzle game | 1 Comment

Preventing players from getting stuck in puzzle games

I’ve been developing my puzzle game Rainbow Hero (to be released soon on PC) for a while now and while doing so I designed a lot of puzzle levels. It was fun but it was also great opportunity for me to learn about good and bad ways to design puzzles.


Rainbow Hero artwork.

Now I’ve just came across an article that talks specifically about that. If you’re into designing puzzles you should totally give it a go: How Are Puzzle Games Designed?. It’s great read and I couldn’t agree more with anything there but I’d like to add a couple of my own tips on one particular topic of how to prevent players from getting stuck (and as a result stop playing the game).

It is very challenging to make a puzzle game that would appeal to many players – both casual and hardcore ones. Making puzzles too easy or too difficult might easily break the game for many. But there’s some ways that can make the game fun for casual players without lowering difficulty level too much thus offering challenge for hardcore players as well.

Here’s my tips:

1) Provide alternative puzzles. Don’t let your game unlock exactly one puzzle after completing another. Make it unlock 2 or more so as to always give a choice to the player. There might be other ways to it but the main idea stays the same – never leave the player with one (or too few) puzzles left.

2) Don’t require player to solve all puzzles in order to solve “the big puzzle” (be it game chapter/world or some other part of the game).

I bet you, as a developer, would much prefer to have lots of players who completed the game even if that means solving only 50% of all puzzles rather than have lots of players who got stuck after completing 10% of the game and never played it again.

3) If the game makes it possible to get into non-obviously unrecoverable states (totally easy in a game such as e.g. sokoban) provide undo or time rewind option. Actually provide it even if it’s obviously unrecoverable because the player might have made a tiny mistake (e.g. pressed the wrong button) and would otherwise have to replay the whole level and start solving the puzzle from scratch.


Time rewind in action in Braid.

Some puzzle games, such as Braid or Time Ducks, have even made time rewind feature their core mechanic.

Posted in indie game development, puzzle game | Tagged | Leave a comment

Tiny2D – my open source 2D game engine

Today I have finally managed to open source my after hours project called Tiny2D.

It’s development started roughly 4 months ago as I decided to resurrect an old puzzle game I did 5 years ago but never got to finish it. I wanted to port it quickly to new engine (previously used my own tech) that would work well on desktop and mobile platforms and I wanted to improve some of the things too.

Also, having done a couple of 2D game prototypes recently I really wanted something easy to use. Something that would translate my gameplay ideas into working game with as little effort as possible. Minimum code, maximum effect.

And now, here it is – Tiny2D is the fruit of my work, mostly developed while my wife was putting my baby to sleep. It is very simple to use and – as the name suggests – tiny library.

Currently Tiny2D only supports Windows and Android but since it’s using SDL under the hood (and implementing Tiny2D on top of other libs – e.g. Marmalade – would be trivial) it should be easily portable to other platforms such as Linux, MacOS or iOS.

Here’s current list of features:
* Textures (png, jpg and more)
* Materials with Techniques and (GLSL) Shaders
* Animated Sprites
* Particle Effects
* Render Targets
* Several built-in Post-Processing Filters
* Asynchronous Resource Loading
* Virtual Resolution Rendering
* True Type Fonts
* Audio (wav, ogg, mp3 and more)
* Input (keyboard, mouse, touchpad)
* Files
* Localization
* Multithreaded Job System
* Timer
* Random Numbers

For more details head over to Tiny2D project homepage or check it out on GitHub.

Curious why I made yet another 2D game engine?

a) Because I haven’t found any 2D game engine with as simple, yet powerful, interface. I consider Unity or Marmalade too complex for rapid prototyping, DragonFireSDK far too limited (btw, here is my comparison of Marmalade, DragonFireSDK and Unity) and I prefer C++ from Lua, so LÖVE is out of question too. Sure, there’s many other game engines, but I haven’t found one that would fully satisfy my needs.

b) For fun. After all I really enjoy coding 🙂

Posted in Uncategorized | 5 Comments

Binding C++ with Lua, Squirrel, Game Monkey and Ocaml

This isn’t anything new I did recently but I thought it’s worth putting up on my blog anyway. I was once interested how easy it is to implement binding between C++ and several popular, mostly scripting, languages.

If you search on the internet there’s heaps of libraries that make the process of binding of various scripting languages with C++ easier – check out this for lua or this for Squirrel binding options.

So, why did I make another one? The first reason was I wanted to learn more about scripting languages and the second one was I wanted the same interface for use with all languages.

C++ library

The result of all that is my MultiScript library that:

  • allows script code to access C++ classes and functions and
  • allows C++ code to access script functions

The library has a very simple C++ interface with 4 different implementations for the following languages:

The interface itself consists of:

  • ScriptContext – responsible for maintaining script execution context; registers classes and functions
  • ScriptStack – used to handle function calls including pushing and popping values on stack
  • ScriptObject – base C++ class for objects to be visible from script
  • ClassDesc, FunctionDesc etc. – helper structs used to describe classes and functions to be registered

The library comes with a simple test project that runs test programs for all languages and prints out their output along with some statistics. The source code of all these languages is included.


Ocaml binding implementation deserves separate paragraph or two as it wasn’t as straightforward as I had hoped originally and I ended up modifying source code of the Ocaml VM (virtual machine) so I could easily load-from-string and run multiple times a chunk of Ocaml code as well as dynamically register C++ functions with Ocaml runtime. Apparently Ocaml VM wasn’t meant to be used as an embedded scripting language the way Lua is.

Binding C++ classes would most likely require a lot more work to get done, so I gave up on that. All of the modifications are clearly marked with “msawitus” in the comments.

In order to be able to run Ocaml tests you have to install Ocaml binary distribution from Inria download site. It is necessary to compile (not execute) Ocaml code.


Implementation for both Lua and Squirrel are very similar – after all Squirrel is heavily based on Lua. Getting my head around Lua concepts required a little bit of effort at first but it was straightforward after all. Game Monkey binding was straightforward to do from the very beginning, even without docs and Ocaml was a bit of trial and error experimentation.

I should also point out that this was just an experimental project and it’s nowhere near production quality code. But it’s probably worth looking at if you’re wondering which scripting language to choose for your next project.

Project source code is hosted here.

Posted in Uncategorized | 2 Comments

Naive #include Optimizer for C++

Here’s my simple and really basic utility written in C# that optimizes Visual Studio project by removing redundant #include lines where possible. Why having redundant #includes is so bad? The answer is simple – it can severely slow down the compilation process.

Download: Source and Binary

Example usage:

NaiveIncludeOptimizer.exe “C:/Program Files (x86)/Microsoft Visual Studio 11.0/Common7/IDE/devenv.exe” “C:/my_project/my_project.sln” “Debug” “C:/my_project/src”

Example output:

Optimizing Main.cpp...
    Redundant #include External.h
    Redundant #include Misc.h
Optimizing Misc.cpp...
    Redundant #include Common.h
    Redundant #include API.h
    Redundant #include Defines.h

The way it works is very brute force (hence the “Naive” in the name) meaning it tests every #include individually to see if the solution would still build if it was removed. So, yes, that means larger projects may even take days to process! But in the end it does work (mostly – see below when it doesn’t).

Be careful because it does modify the source code. But while doing so, it always creates a backup copy. Bonus feature is that it is capable of resuming from where it stopped last time.

Also, please note that it only optimizes .cpp files. Optimizing .h files would obviously take a lot longer!

I should also point out that the proper way of doing this would be implementing full blown C++ preprocessor that would include:

* removing redundant #includes

* adding forward declares where possible

* making sure that the actual code generated does not change (my solution may result in some undesired program “optimizations” – e.g. by removing #include “my_new_operators.h” the definition of your new/delete operators might change but the project would still build successfully)

It’s obviously a lot more work but fortunately that’s exactly how Google’s Include-What-You-Use is meant to work. I haven’t tried it but it looks neat.

Posted in c++, general programming | Leave a comment

The end of my indie game devevelopment adventure

As of today some of my games on some of the platforms are no longer available and the reason I pulled them is simply because they don’t make enough profit.

Monstaaa! is not available anymore on any of the platforms. In fact I have just recently sold the IP to other developer. Hopefully they bring the second life to the game!

Meanwhile, Puzzled Rabbit for Android, Blackberry PlayBookXBLIG and PC is still available.


Apparently indie game development, in particular on mobile platforms, is really tough these days. The way I see things is that iOS / Android gold rush is gone and it’s now incredibly difficult to compete when you’re a small developer because in order to succeed you not only need an exceptionally good, original and polished game but you also need to be visible on the market. And that takes a lot of hard work, talent and some luck too.

Finally I have to say that I am really glad I tried indie game development as I would otherwise not fully understand why it is so difficult and would probably regret not having tried it. I have also learned a lot and had a really good time while it lasted. If you want to learn more about my 10 month long indie adventure have a look at my past blog posts and try to learn something from it.

iOS and Android game development on Windows

Monstaaa! for iOS – the first announcement

Monstaaa! development summary – part 1

Monstaaa! development summary – part 2

How I sold 22 copies of my game in 3 weeks on Android

Posted in Uncategorized | 5 Comments

Practical C++ RTTI for games

There’s at least few popular approaches to C++ based RTTI (aka Run-Time Type Information) implementation in games. The goal of this post is to discuss strengths and weaknesses of major ones.

But before that let’s have a look at some of the most common uses of RTTI in games. In fact they are not much, if at all, different from any other, non-game related, project.

(a) Run-time type checking and instancing.

Being able to check what’s the actual class of an object is often useful functionality for gameplay programmers:

bool Object::InstanceOf(Class* _class) const;

Another useful feature is ability to instantiate an object knowing its class name:

Class* ClassManager::FindClassByName(const char* className);

Object* Class::CreateInstance();

To implement above basic RTTI functionality, we’re usually required to derive all of our game classes from some base Object class. Supporting multi-inheritance is possible but typically avoided because in most cases it’s just not needed but would make things a lot more complex otherwise.

Reality Prime’s dev blog shows basic implementation of such RTTI system.

(b) Automatic serialization of objects and their attributes.

Instead of implementing custom Read() / Write() methods for each class where every property is manually processed, we can now (with RTTI system in place) implement generic Read() and Write() methods that will work for all classes. Alternatively we can write single Serialize(Serializer&) method that would either read or write (or do other things) depending on implementation of Serializer.

But while this feature sounds great it has one serious downside – very limited support for data versioning. Imagine one day you decide to change some ‘int m_Name‘ attribute into ‘String m_Name‘ attribute. How would you want your game to load the old data and convert into new format? Would you want to perform some kind of ‘offline’ conversion by running hacked version of the game over all of the data? If so, you’d have to do so for all of the relevant game data files at once. In a big team working on a game that is obviously a challenge because the person performing conversion must assure no one else has got any important local changes on their PC.

Or even worse, suppose your game has already been released and there’s tons of content (e.g. levels, quests, puzzles) created by the community. Simply changing the format of the data expected by an updated game executable would break all of that content unless you provide way to convert from the old format into new one.

To some extent this upgrade process can be automated as demonstrated by Insomniacs (unfortunately, to my knowledge, the actual explanation of that can only be found in GDC slides or articles in paid magazines). Their system of lazy upgrade script evaluation assures that every asset you get from asset database is always in latest format.

Having said all that I should point out that some projects don’t need robust data versioning at all and therefore may well benefit from automatic serialization. This is especially true for small projects without support for community created content.

(c) Game editor integration

Another great benefit of RTTI is that it allows class attributes to be automatically exposed for editing within some kind of visual editor. This feature may require additional editor specific attributes to control how each particular type shall be edited. For example you may want to have nice color selection control instead of having to manually type in individual RGB values; or you may want to limit min and max values of fog intensity by 0..1 range, etc.

This best works with WYSIWYG game editors which for the purpose of editing use the same C++ classes as the ones used in the game. There’s no need for intermediate communication layer and every editing action changes the game object directly. As with anything, this has some advantages (mainly easier and cleaner implementation) as well as disadvantages (less efficient and editor-polluted run-time code).

Manual serialization

A well known example of an engine that supports features listed in all above points is Unreal Engine 3. As for the automatic serialization, it only does so for Unreal Script classes. For their C++ classes they use more “manual” method which does make a lot of sense because it allows for a flexible data format versioning. Here’s sample code that demonstrates mentioned “manual” method:

// Deserializes instance of Dog class
void Dog::Read(Reader& reader)
    // Deserializes all base class attributes

    // Read name value
    reader >> m_Name;

    // Read color value; only if data has it (old version didn't)
    if (reader.GetDataVersion() >= ENGINE_VER_DOG_ADDED_COLOR)
        reader >> m_Color;

    // Read height value; only if data has it (old version didn't)
    if (reader.GetDataVersion() >= ENGINE_VER_DOG_ADDED_HEIGHT)
        reader >> m_Height;

Implementing automatic serialization that would handle all kinds of data versioning correctly is not possible simply because it’s only programmers who know how data changes between versions. The major limitations of the automatic serialization are as follows:

  • only simple type conversion handled correctly (e.g. int into float)
  • name changes cause new property to be added and the old one to be removed (thus losing the data)

On the other hand, by manually handling data upgrades, one has full control over data conversion.

Type information generation methods.

We now know why RTTI might be useful. But how do we create it? Again, there’s at least a couple of ways – from manual intrusive macro/template based ones to automatic offline ones.

(a) Manual intrusive macro/template based method.

One very popular way of creating RTTI in C++ is by adding a couple of special macros and functions to every class. This may look something like this:

Header file:

// Sample Dog class
class Dog : public Animal
         // Tells RTTI that Dog inherits from Animal
         // Also defines some helper functions
    int m_Height;    // Dog height
    String m_Name;   // Dog name

Source file:

// Function declared in RTTI_DECLARE_CLASS macro
// Adds all attributes to class RTTI
void Dog::RTTI_InitAttributes()
    // Initializes m_Height attribute; figures out type using templates

    // Initializes m_Name attribute; figures out type using templates

The actual initialization of each class is best done manually – something like this:

void InitMyClasses()

To keep things short I’m going to skip implementation of RTTI_DECLARE_CLASS and RTTI_INIT_ATTRIBUTE macros. The nice thing about attribute registration is that using C++ template specialization it’s totally possible to automatically deduce type from a variable – this is useful because it means you can initialize all attributes with call to the same RTTI_INIT_ATTRIBUTE macro.

The major downside of this approach is that the programmer needs to maintain an up-to-date RTTI initialization code. With the help of automatic attribute type deduction and some C++ macro magic, this can be made safe and less inconvenient but it’s still not perfect.

(b) Automatic – parser based.

One totally different approach to building RTTI information is by generating it offline and storing it in a file which is then loaded by run-time. There’s plenty of C++ code parsers available (e.g. Wave or GCCXML) available which you could use but there’s still some coding required in order to extract selected types for RTTI purposes. You’d also need to integrate C++ parsing step with your project building, so it wouldn’t need to be done manually.

One issue with this approach is that the RTTI data generated during preprocessing step might potentially differ between project configurations / platforms. But since gameplay code is typically platform and configuration independent this is probably a very minor issue.

The nice thing about this approach is that, provided parser can extract comments attached to particular class or attribute, it’s possible to use comment based custom annotation language on a per class or attribute basis. This can be useful in a couple of different scenarios including when you want to mark some attributes as serializable or when you’d like RTTI for a specific C++ class not to be generated at all. Annotation technique is something that is widely used in other languages such as Java or C#.

(c) Automatic – debug info based.

Yet another approach to building RTTI information is by extracting it straight from debugging information files such PDB on Windows as described on Maciej Sinilo’s dev blog. It is a very similar method to the one presented before but one small advantage of it is one doesn’t need to implement an additional parsing step themself which, depending on how easy parses integration is, might save a lot of work.


As it often happens, there’s no best solution that would fit all projects. Every game is different and there’s games that don’t need RTTI at all.

For larger game projects with heaps of gameplay editing involved I’m leaning towards Unreal Engine 3 approach i.e. manual RTTI including manual serialization on the C++ side and automatic RTTI with automatic serialization on the scripting side (assuming there is one). Many popular scripting languages already have full reflection support in place which makes things easier there.

For projects where WYSIWYG editing isn’t priority, full blown RTTI system with attribute level information may not be necessary at all. Even more so with projects where in-place serialization (one block of memory used for multiple objects) is being done making it mostly redundant to maintain any kind of attribute information at run-time.

Posted in game engine, general programming | 4 Comments

How I sold 22 copies of my game in 3 weeks on Android

To check previous article in the series click here.

Free on Android, paid on iOS

It’s been 3 weeks since Monstaaa! release on Android via Google Play, so I thought it’s high time I share some more statistics. In fact they’ve been rather shocking – in a negative way, unfortunately – when it comes to the actual revenues given great reviews (average around 4/5), very positive general feedback, high ratings from users (average around 4.5/5) and higher than with iOS number of downloads (over 10k). Apparently, Android turned out to be a very tough market for Monstaaa!

Keep in mind though that unlike iOS version which is paid at $0.99, Android version is Free with $0.99 in-app purchase that unlocks full game. According to my statistics, Android version has been played on more devices than iOS version and yet the sales have been roughly 50 times lower! Part of the reason for that surely was the fact that iOS version has been featured for one week by Apple themselves in New & Noteworthy (only Australia and New Zealand though!) whereas Android version hasn’t been mentioned anywhere at Google Play. Besides iOS version had a lot more reviews on gaming portals – probably result of me pushing a bit more with marketing when iOS version came out.

The thinking behind making the game free on Android was that Android users are, supposedly, less likely to pay up front without trying an app first. That was my guess at least. With Android release I also wanted to experiment with a different than pure paid app model.

Android statistics

Okay, so, let’s have a look at some actual Android numbers now.

Total number of installations/devices: 11135 (1599 installations via Google Play)
Total number of users who finished all 8 levels in free version: 2281 (20.5% of all users – not too bad!)

Total number of different device types: 1133 (seems a lot to me!)
And here’s more detailed breakdown of the device types:

Quite a fragmented market, isn’t it? As you can see, the most popular Android device so far has been Samsung Galaxy II (791 devices), then MI-One Plus (410 devices; popular in China), then Samsung Galaxy Ace (347 devices).

Here I shall also point out that even though the game is officially only available via Google Play, over 80% of all downloads have been made through other portals – this is quite common in the world of Android. Since the game is free, this doesn’t hurt at all (as opposed to paid apps which are just being pirated this way). That’s all based on the stats I get to see from within Google Play admin panel itself compared with my own stats collected from the game directly.

Let’s now have a look at the number of users and new users per hour over last 3 weeks:

Clearly, the game had its popularity peak at the end of the first week. Since then there’s been gradual decrease in both, users and new users counts. The peak in downloads most likely corresponds with some, very positive, reviews from iDroidPlay and AndroidZoom as well as “App of the Day” featuring by the latter.

Android and iOS sales

If you read the title of this post you already know – the full game has been purchased exactly 22 times! That’s right! With over 10k downloads, there have only been 22 purchases made on Google Play.

And with iOS, even though things look much better there, sales are still far from satisfying. Over first 2 months the game still hasn’t even reached $1k in net revenues with no more than $5 a day being made nowadays. With 7 months worth of development, even for a single developer, this obviously won’t pay the bills. Well, it won’t even cover basic out of pocket development costs!


What’s the reasons for such poor Android sales? Too many levels in free versions? Too high difficulty level? Lack of additional in-app purchases / items in game? Oversaturated market when it comes to physics based puzzle games? Should it be made paid like on iOS? Or is it just lack of luck? I really wish I knew and I’d be really glad to hear others’ opinions!

Sometimes I feel like the more I try to understand things, the worse the actual results are. At least with Android that is the case. And probably the most confusing for me is the fact that the game had many really good reviews and has been mentioned but a number of prominent gaming portals or blogs. No review to this date (except for one) points out any significant flaws with Monstaaa! which I think suggests there isn’t any obvious issue there. In fact most of reviews highlight the good things about the game – things like good graphics and audio, fun game-play or well done tilt controls.

Here’s few game reviews if you want to check them yourself:
148 Apps

Ironically, if the reviews were bad it would have been much easier for me to understand the problem! 😉

And it’s even more confusing when you realize that over 20% of all users complete the whole demo version – this I believe is quite a large percentage. And yet, only less than 1.0% of these users unlock the full game.


But let’s not be too pessimistic! How many game devs succeed with their first or second game? Of course it’s a dream of every developer that their first game is success big enough so they can comfortably work on another one but one has to be realistic and the reality is that only very few succeed straight away.

My experiment with indie game development hasn’t worked out financially so far but I didn’t even spend a year on it and, fortunately, I also didn’t spend too much money on it. By making and releasing two games I learned a lot about mobile game development and I do plan to try again in some future! In the “meantime” I’m going back to more stable life joining one Electronic Arts studio in Melbourne which I’m sure will be another exciting chapter on my game development adventure!

Posted in android, indie game development, ios, mobile game development | 29 Comments

Robust iCloud implementation for games

For my second iOS game Monstaaa! I wanted to take advantage of the new iOS 5 feature iCloud and use it to store savegames – play on one device, then later continue on another one. Pretty basic iCloud usage scenario and so, you might think I should easily find some relevant tutorials or sample code on the internet. Well, not quite so easily…

The best resource I found was the following series of tutorials: Beginning iCloud in iOS 5. It is does explain well the basics of iCloud usage but unfortunately it doesn’t go as far as implementing iCloud conflict resolution – something that is strictly required if you’re seriously considering using iCloud for your game. Besides, Apple doesn’t make it easy for you either to understand how one is supposed to implement it.

The small library that I implemented handles all that is needed for a simple game savegame i.e. creation & writing to iCloud file, reading from iCloud file and, very importantly, iCloud file conflict resolution. The library has been implemented as an extension for Marmalade SDK (cross platform mobile development SDK) but if you don’t use it, don’t worry, it is fairly trivial to make it stand-alone library.

The library has C++ interface but the majority of the code is in Objective-C. You can get it from github: https://github.com/macieks/s3eIOSiCloud If you just want to see the _code_ or don’t use Marmalade SDK check these source and header files.

The basic idea behind the library is you store your savegame both locally (on the device) and remotely (in iCloud). The reason we always store local savegame version is quite obvious – if an app fails to connect to iCloud for any reason, you won’t just lose the progress. Once iCloud becomes available again, we then connect back to it and, optionally, resolve conflicts that occurred in the meantime due to savegames done on other devices.

The library notifies the app whenever it has successfully read the file or whenever conflict has been detected. It’s then up to the app to resolve the conflicts and merge remote with local savegame. The callback in both cases is exactly the same – the app is given the data (i.e. void* data and int size) to merge with and that’s it. The actual merging operation is application specific – every game will merge differently. And just to make sure everything is well explained here, what I mean by merging is making one out of two different savegames. Let’s say the player has completed levels 1,2,3 on their iPhone and levels 2,4,5 on their iPad – the resulting merged savegame should contain information about levels 1,2,3,4,5 being completed.

Here’s quick intro on how to use the code. MySaveGame struct represents sample savegame with boolean values indicating which levels have been completed and MyMergeFunc is the merge callback registered with the library.

#include "s3eIOSiCloud.h"

#define NUM_LEVELS 100

struct MySaveGame
	bool m_completedLevels[NUM_LEVELS];

MySaveGame localSaveGame;

int MyMergeFunc(void* systemData, void*)
	s3eIOSiCloudDataToMergeWith* data =
            (s3eIOSiCloudDataToMergeWith*) systemData;
        MySaveGame* remoteSaveGame = (MySaveGame*) data->m_data;

	// Merge remote and local savegames

        for (int i = 0; i < NUM_LEVELS; i++)
             if (remoteSaveGame->m_completedLevels[i])
                localSaveGame.m_completedLevels[i] = true;

	// Store savegame locally (fopen / fwrite / fclose)

	bool savedLocally = [...]

	// Return success or failure to iCloud library

	return savedLocally ? 0 : 1;

The callback gets the data to merge with, performs app specific merging operation and then stores the savegame locally.

Let’s now initialize iCloud for “my_save_game.txt” file:

s3eIOSiCloudRegister(S3E_IOSICLOUD_CALLBACK_MERGE, MyMergeFunc,0);
s3eIOSiCloudStart("my_save_game.txt", S3E_TRUE);

The code above registers merge callback, then starts iCloud service for a specific file.

To make sure read and write operations are being retried internally, simply do this every frame:


And finally, to store savegame in iCloud do this:

s3eIOSiCloudWrite(&localSaveGame, sizeof(MySaveGame));

Now, as I said, if you want to use the code but you don’t use Marmalade you should easily be able to get rid of Marmalade specific code – mostly message logging and callback handling. There’s no heavy Marmalade dependencies anywhere.

Finally, to make you feel better about the library I’m just going to say that it’s been already successfully used by two of my iOS games – Monstaaa! and Puzzled Rabbit.

Posted in game engine, ios, mobile game development | 10 Comments