https://github.com/cjhanson/Objective-C-Optimized-Singleton

That singleton macro can be easily used in any exiting Objective-C class and to do the serialization and de-serialization process you can still use the +alloc and -initWithCoder: methods if you so wish.

@Mustafa: you're welcome. I'm glad (and amused) to see this is still helpful to some people.

Just wanted to send my thanks to @clain and to @NatWeiss for their code samples - they were exactly what I needed to get going with my Game State code.

-m

Oh and LEVEL CREATION!!! Thats got to be the one thing that im having the most difficulty with - dealing with SVG files (cause i dont want tilemap styled levels) to easily create multiple levels effectively and efficiently without having to roll my own solution.

(IT WOULD BE AWESOME if this was part of the cocos2d framework in fact i think ill post it)

Any chance the presentation that was the original starting point of this thread can be found online anywhere?

Personally, the issues that I have faced are the following:

- Cocos2d Game Architecture best practices
- How to best logically divide layers (HUD, Touch, Player, Level, etc), and how to get layers to communicate with one another (im using boolean switches which I KNOW is not the best way to do it but is simply the easiest lol
- Moving from proof of concept (that you can build from a simple tutorial) to a full game -
- The steps you should take in architecting and designing your game for future extensibility and so you dont have to refactor your code if you want to add new features.

Would LOVE to begin a wiki holding all of the insights that I have gotten just by reading this thread

This isn't cocos specific, but I do wish I had thought about it prior to the start of my project. I use one coordinate system to represent a linear non-manipulated grid (such as a tiled map, or non-isometric representation), and another for the screen displayed coordinates. Thus any transformations need only go from one coordinate system to the other, rather than copying complicated code or having inconsistencies.

I use UV for the pre-transformed, and XY for the screen display, so it becomes easy to know which I am dealing with by naming my properties: UVPosition and XYPosition, or similar.

@PhilM thank you! That was what we needed.

Here's the implementation of @Clain's suggestions above. How does it look? Any "best practices" suggestions?

In particular, do I need to have @synchronized() around my saveState method?

Is there a difference between @synchronized([GameState class]) and @synchronized(self)?

Am I retaining and releasing the savePath and currentLevel correctly?

GameState.h:

#import "Import.h"

@interface GameState : NSObject <NSCoding>
	{
		NSString* currentLevel;
		CGFloat health,maxHealth,strength,dexterity;
		int swordLevel;
		BOOL terminating;
	}

	@property (copy) NSString* currentLevel;
	@property CGFloat health,maxHealth,strength,dexterity;
	@property int swordLevel;
	@property BOOL terminating;

	+(GameState*) get;
	+(void) purge;
	+(void) loadState;
	+(void) saveState;
	+(NSString*) makeSavePath;

	-(void) clear;

@end

GameState.m:

#import "Import.h"

static GameState* singleton = nil;

@implementation GameState

	@synthesize currentLevel,health,maxHealth,strength,dexterity,swordLevel;

	+(GameState*) get
	{
		@synchronized(self)
		{
			// create our single instance
			if(singleton == nil)
				singleton = [[self alloc] init];
		}
		return singleton;
	}

	+(id) alloc
	{
		@synchronized(self)
		{
			// assert that we are the only instance
			NSAssert(singleton == nil, @"There can only be one GameState");
			return [super alloc];
		}
		return nil;
	}

	+(void) purge
	{
		@synchronized(self)
		{
			[singleton release];
		}
	}

	+(void) loadState
	{
		@synchronized(self)
		{
			// release any existing instance
			[singleton release];

			// load our data
			NSString* savePath = [self makeSavePath];
			singleton = [[NSKeyedUnarchiver unarchiveObjectWithFile:savePath] retain];
			[savePath release];

			// couldn't load?
			if(singleton == nil)
			{
				NSLog(@"Couldn't load game state, so initialized with defaults");
				[self get];
			}

			NSLog(@"Loaded game state %@", singleton);
		}
	}

	+(void) saveState
	{
		// save our data
		NSString* savePath = [self makeSavePath];
		[NSKeyedArchiver archiveRootObject:[GameState get] toFile:savePath];
		[savePath release];

		NSLog(@"Saved game state %@ to file %@", singleton, savePath);
	}

	+(NSString*) makeSavePath
	{
		// make save path from our document's directory
		NSArray* paths = NSSearchPathForDirectoriesInDomains(NSDocumentDirectory, NSUserDomainMask, YES);
		NSString* documentsDirectory = [paths objectAtIndex:0];
		NSString* savePath = [documentsDirectory stringByAppendingPathComponent:@"savefile.sav"];
		[savePath retain];
		return savePath;
	}

	-(id) init
	{
		self = [super init];
		if( self != nil )
		{
			[self clear];
			NSLog(@"gameState init %@", self);
		}
		return self;
	}

	-(void) dealloc
	{
		[currentLevel release];
		[super dealloc];
	}

	-(NSString*) description
	{
		return [NSString stringWithFormat:@"level=%@, health=%.1f, maxHealth=%.1f, strength=%.1f, dexterity=%.1f, swordLevel=%d",
			currentLevel, health, maxHealth, strength, dexterity, swordLevel];
	}

	-(void) clear
	{
		// erase all data
		[currentLevel release];
		currentLevel = nil;

		health = maxHealth = 100.0f;
		strength = 6.0f;
		dexterity = 5.0f;
		swordLevel = 0;

		terminating = NO;
	}

	-(id) initWithCoder:(NSCoder*)coder
	{
		self = [super init];
		if( self != nil )
		{
			// decode data
			currentLevel = [[coder decodeObjectForKey:@"currentLevel"] retain];
			health = [coder decodeFloatForKey:@"health"];
			maxHealth = [coder decodeFloatForKey:@"maxHealth"];
			strength = [coder decodeFloatForKey:@"strength"];
			dexterity = [coder decodeFloatForKey:@"dexterity"];
			swordLevel = [coder decodeIntForKey:@"swordLevel"];
			terminating = NO;
		}
		return self;
	}

	-(void) encodeWithCoder:(NSCoder*)coder
	{
		// encode data
		[coder encodeObject:currentLevel forKey:@"currentLevel"];
		[coder encodeFloat:health forKey:@"health"];
		[coder encodeFloat:maxHealth forKey:@"maxHealth"];
		[coder encodeFloat:strength forKey:@"strength"];
		[coder encodeFloat:dexterity forKey:@"dexterity"];
		[coder encodeInt:swordLevel forKey:@"swordLevel"];
	}

@end

I think you need to provide the full path.

This is what I pass to archiveRootObject to save to the apps document directory (the only one thats writable from your app I believe):

NSArray *paths = NSSearchPathForDirectoriesInDomains(NSDocumentDirectory, NSUserDomainMask, YES);
NSString *documentsDirectory = [paths objectAtIndex:0];
NSString *fullPath = [documentsDirectory stringByAppendingPathComponent:@"savefile.sav"];

Hi. I've implemented a singleton class similar to @Clain's. Though, I'm having trouble using the NSKeyedUnarchiver's unarchiveObjectWithFile method. I don't know what file name and/or path to use. I've tried:
[NSKeyedUnarchiver unarchiveObjectWithFile:@"savefile.sav"]
and
[NSKeyedUnarchiver unarchiveObjectWithFile:[CCFileUtils fullPathFromRelativePath:@"savefile.sav"]]
and
[NSKeyedUnarchiver unarchiveObjectWithFile:[CCFileUtils fullPathFromRelativePath:@"./savefile.sav"]]
and I've even tried creating a "savefile.plist" in my bundle's resources and using that.

All of these attempts return nil except in the case of loading my bundle's "savefile.plist" which always returns the original plist file, even after I have encoded and saved the data back to it.

What am I doing wrong?

Will do, thanks Codemattic. I'd love to get this figured out as well :)

"I figured that since NSValue conforms to NSCoder" yes - it really seems like it should! But Im looking at the CAAdditions specifically sayd it conforms to NSCoding:

http://developer.apple.com/IPhone/library/documentation/GraphicsImaging/Reference/NSValue_CA_additions/Introduction/Introduction.html

"I don't know how it would fit into this scenario, but there is a
-(CGPoint) encodeWithCGPoint:forKey"

I dont see how you can use that since your CGPoint is inside an NSArray.

@eshirt, if you want to continue this discussion, could you please start a new thread in "everything else"? This has become off-topic for this thread and for this group. Id fork it, but I dont know how without deleting the previous messages, so feel free to start a new thread in "everything else" regarding serializing CGPoints. It would be a good thing to figure out actually since Riq plans for adding serializing to cocos and CGPoints will have to be a part of that. Thanks!

I don't know how it would fit into this scenario, but there is a

-(CGPoint) encodeWithCGPoint:forKey

method declared in UIGeometry that should be useful, but how would I use that in my encoder method?

Could I iterate through the array in that method and encode each point individually then save those? Obviously, I'd then have to create a new array in my decode to hold all the points. That doesn't seem like the most efficient way to do this, but would that work?

Hmm, I guess I'm just confused then. I figured that since NSValue conforms to NSCoder, it's additions would.

I've searched everywhere for solutions and this was actually the recommended solution on another forum. The people there didn't seem to have any trouble getting it to work, but maybe their circumstances were different.

Unless anyone else has a better way, then I guess I'll have to start working on subclassing CGPoint to make it conform. Any ideas how this would affect (if at all) any usage of ccp() in my code?

you know what I have just noticed - NSValue UIGeometry Additions Reference doesnt say it conforms to NSCoding!

http://developer.apple.com/iphone/library/documentation/UIKit/Reference/NSValue_UIKit_Additions/Reference/Reference.html

D'oh!

sorry - i mistyped. that's what I get for trying to make my code generic in the forums :)

It's actually defined in the header as an ivar. when i set it, it looks like this:

myArray = [blah blah blah]

I've got about 8 other BOOL and Int values that get declared and encoded in the same way, and those work fine. It's something about having CGPoints in this array that's getting me stuck.

hmm, I've just saved CGPoints as 2 separate floats in the past when using NSCoding (mainly because I didn't know about the valueWithCGPoint method).

If for whatever reason an NSValue with valueWithCGPoint can't be NScoded, perhaps creating a simple custom CGPoint class that extends from NSObject & conforms to NSCoding would do? Not ideal, but might be workable...

in your -init myArray is a temporary variable. In -encodeWithCoder: where does it get the myArray variable, where is that defined?

Sorry, I thought the code I put in was enough. Here's a more complete description:

-(id) init {
// normal init stuff
NSArray *myArray = [[NSArray alloc] initWithObjects:[NSValue ValueWithCGPoint:CGPointMake(0, 280)], [NSValue valueWithCGPoint: CGPointMake(0, 245)], nil];

-(void)encodeWithCoder:(NSCoder *)coder {
// this line is where the debugger throws a fit
[coder encodeObject:myArray forKey:@"myArray"];

Here's the line from the console:

[NSKeyedArchiver encodeValueOfObjCType:at:]: this archiver cannot encode structs.

Obviously, encodeObject:forKey, when called on an Array goes and tries to archive each item in the array. I think that's where it calls encodeValueOfObjCType:at: But it should work, right? Since I converted the CGPoints into NSValues?

show us the line of code where you get the error!

So, NSCoding is working great for NSStrings, BOOLs and ints. Thanks again for the help! I'm having an issue now with encoding an array filled with points.

My basic need is to store CGPoints (about 20 at a time). Naturally, I'd want to store them in an NSArray, and since I want to save that info, encode/decode with NSCoder. CGPoint is a struct that doesn't conform to NSCoder. NSValue does conform to NSCoder, so what I've done is something like this:

`NSArray *array = [[NSArray alloc] initWIthObjects:[NSValue valueWithCGPoint: CGPointMake(0,0), etc, nil];

Then when I try to use encodeObject:forKey: on it, the compiler gives me an error: "[NSKeyedArchiver encodeValueOfObjCType:at:]: this archiver cannot encode structs"

Any ideas?

Got it THANKS! :) I knew it had to be a retain that I missed in there. I just retained my Strings and all is well.

GIve a man a fish, he eats for a day - teach a man to fish, he'll finally understand memory management. :)

@eshirt - decodeObjectForKey returns an autoreleased object. BOOL and int aren't objects so they don't need to be retained. Ringing any bells?

Sorry to revive an old thread, but I'm trying to do save game data using Clain's advice. So far, it's working great, but I'm getting an unexpected crash when trying to access a decoded NSString value.

In my GameData singleton class, I have declared a NSString *player. On a new game, it's set to nil. Upon choosing a player, it's set to the appropriate string value. That all works fine. When I load the game up a second time, some of the game data is showing up just fine. But every time I try to display that string value, it crashes.

Here's what I have in my encodeWithCoder method:
[coder encodeObject:player forKey:@"homeTeam"];

And my initWithCoder method:
player = [coder decodeObjectForKey:@"playerName"];

Then in my GameLayer:

GameData *myGame = [GameData sharedData];
Label *playerName = [Label labelWithString:myGame.player fontName:@"Helvetica" fontSize:48];
playerName.position = ccp(240, 200);
[self addChild:playerName z:5];

That's where I get my crash. I am able to successfully retrieve int and BOOL values from my GameData file, but the string seems to be the problem...

Any suggestions?

I'll give it a go! Thanks for the quick response. (other suggestions welcomed, too.)

If you use cocos2d as a static lib, you can flip between versions very easily, although any api changes will need to be done to your own code as normal.

I followed this tutorial some time ago, and its made updating a breeze:
http://www.clintharris.net/2009/iphone-app-shared-libraries/

Not sure if any of the current templates take this into account.

Forgive me... I'm an old guy... and I did look around here before posting. The biggest problem I have is that I don't understand how to update a project to a new version of Cocos2D. I just took a working project and replaced the existing files with the 8.2beta... and promptly go about 6000 errors.... Lots of "can't find Support/soemthingorother... but near as I can tell, somethingorother is right where it ought to be.

Obviously/surely this is trivial... but I sure can't figure it out. After mucking about for several hours; looking in the forums (and apparently missing it) I've simply got to ask: what am I missing here?

How (preferably in simple terms) do I set up a project so that when (say) 8.2 final comes out, I'm not faced with a nightmare?

Sorry to be such a newb... but I guess one has to start somewhere

Conforming to the NSCoding protocol just means that you define the initWithCoder and encodeWithCoder methods in your class. You don't have to encode all your properties/variables. You can encode and decode whatever you want in order to recreate your object correctly in the initWithCoder method. What you want to do with your chipmunk stuff seems to be the way to go.

@Clain: Thanks for that mini tutorial! I have one question:

If I had subclassed the Sprite class to make a BubbleSprite containing the index, color and captured variables as well as the TextureNode code to draw itself, I wouldn't have been able to save the game like that because the cocos classes don't conform to the NSCoding protocol.

If you had your Buble class like this:

@interface Bubble : NSObject <NSCoding> {
int index, color;
BOOL captured;
Sprite * sprite;
}

But your encodewithcoder remained the same, would it work?
I mean, do i have to encode/decode ALL of the properties of a class to make it conform to NSCoding?

In my game i have some class with a chipmunk body and shape, i would like to encode it, obviously i can't encode the shape/body, but i could encode the integers/floats, image path string, etc. to recreate it.

Thanks!

Hey Phil, thanks for your feedback. I agree, there are always new ideas coming along during development. A GDD can never be totally complete and accurate. However, when you discuss new ideas with other people working on the project (especially the graphics artists and level designers), it's important to explain them how these changes would affect the code and/or how much time it would take to integrate them. Sometimes you have to reject new ideas in order to meet the deadline. You can also keep them in mind for a future update. If you're close to releasing your game, you probably don't want to add new features, see this interesting article on the Valve Developer Community's wiki.

Back to today's topic : the Singleton design pattern. I briefly talked about it in this post. In fact, I don't have much to add ;) I don't do unit tests in my game programs so I don't really care about singletons possibly breaking them. Global state can be tricky and that's why you need to know what you're doing. By the way, an interesting discussion on the Singleton controversy can be found here : google-singleton-detector/wiki/WhySingletonsAreControversial (read the comments as well).

As Phil said about singletons : "I've found them very useful, as long as you plan out what you want them to store in the first place". Agreed. And if you followed the steps I described in my previous post on this thread, you should be able to determine what needs to be made global (in general, it's what needs to be accessed from different places in the code). I'm not going to paste the code to create a Singleton class since it's been done more than once on this forum (and the old google one) and you can always look at the following cocos classes which are all singletons : Director, TextureMgr, TouchDispatcher, ActionManager, SimpleAudioEngine, Scheduler. Instead, I'm going to talk about how I used the singleton pattern to both hold my global variables during the game and manage save and load stuff.

But before that, please read this thread : Component based entity systems. The topic has been quickly hijacked by ob1 and slipster216. It turned into a very interesting discussion around MVC and NSCoding. Worth reading !

.
.
.

Alright ! Let me explain how I wrote the save/load functions in the following game : Dr Bubbles (this links to the cocos2d games announcement forum).

My singleton code is in the GameState class. In this singleton instance, I put all the global variables needed for the game. For example : level, shotsLeft, score, currentColor, bonusX2 and bubbles (of course, there are a lot more but let's keep it simple). If you read the Component based entity systems thread, these variables represent my model in the MVC pattern (though it's not really MVC, as ob1 pointed out in that thread). This model is all I need to resume a game. So I want the singleton instance to be serializable to easily save and load games. To achieve that, you have it conform to the NSCoding protocol. This what my GameState.h file looks like :

@interface GameState : NSObject <NSCoding> {
    int level, shotsLeft, score, currentColor;
    BOOL bonusX2;
    NSMutableArray *bubbles;
}

Of course, every variable is defined as a property (eg. @property BOOL bonusX2;). I then define a bunch of methods. The relevant one regarding the singleton pattern is :

+(GameState *)gameState;

Since I want to be able to recreate the singleton from a saved file, I also have this method :

+(void)loadGameStateFromFile:(NSString *)file;

In my GameState.m file, I have all the @synthesize statements for my variable. I have the regular + (GameState *)gameState { ... } and +(id)alloc { ... } functions for the singleton pattern. The singleton instance is defined as usual : static GameState *_gameState = nil;

And the loadGameStateFromFile :

+(void)loadGameStateFromFile:(NSString *)file {
    @synchronized([GameState class]) {
        [_gameState release];
        _gameState = [[NSKeyedUnarchiver unarchiveObjectWithFile:file] retain];
    }
}

I then have the - (void) dealloc { ... } and - (id) init { ... } methods. In init, I initialize my variables with default values. In dealloc I release what needs to be released (in my case, I release the bubbles array). What's more interesting is the 2 methods of the NSCoding protocol :

- (void) encodeWithCoder:(NSCoder *)coder {
    [coder encodeInt:level forKey:@"level"];
    [coder encodeInt:shotsLeft forKey:@"shotsLeft"];
    [coder encodeInt:score forKey:@"score"];
    [coder encodeInt:currentColor forKey:@"curColor"];
    [coder encodeBool:bonusX2 forKey:@"bonusX2"];
    [coder encodeObject:bubbles forKey:@"bubblesArray"];
}
- (id) initWithCoder:(NSCoder *)coder {
    self = [super init];
    level = [coder decodeIntForKey:@"level"];
    shotsLeft = [coder decodeIntForKey:@"shotsLeft"];
    score = [coder decodeIntForKey:@"score"];
    currentColor = [coder decodeIntForKey:@"curColor"];
    bonusX2 = [coder decodeBoolForKey:@"bonusX2"];
    bubbles = [[coder decodeObjectForKey:@"bubblesArray"] retain];
    return self;
}

Important :
My bubbles array contains objects of type Bubble. This Bubble class needs to conform to the NSCoding protocol, otherwise the above function won't be able to serialize the array. For example, in Bubble.h :

@interface Bubble : NSObject <NSCoding> {
    int index, color;
    BOOL captured;
}
@property int index, color;
@property BOOL captured;
@end

And in Bubble.m :

@implementation Bubble

@synthesize index, color, captured;

- (void) encodeWithCoder:(NSCoder *)coder {
    [coder encodeInt:index forKey:@"index"];
    [coder encodeInt:color forKey:@"color"];
    [coder encodeBool:captured forKey:@"captured"];
}
- (id) initWithCoder:(NSCoder *)coder {
    self = [super init];
    index = [coder decodeIntForKey:@"index"];
    color = [coder decodeIntForKey:@"color"];
    captured = [coder decodeBoolForKey:@"captured"];
    return self;
}

To save the GameState, when the application is about to terminate, you just do :

[NSKeyedArchiver archiveRootObject:[GameState gameState] toFile:file];

And when the app is launched again, you check if the saved file exists, and if it does, you do :

[GameState loadGameStateFromFile:file];

And that's it. It works very well for a game like Dr Bubbles because it's easy to dissociate the bubble sprite from the bubble data. If I had subclassed the Sprite class to make a BubbleSprite containing the index, color and captured variables as well as the TextureNode code to draw itself, I wouldn't have been able to save the game like that because the cocos classes don't conform to the NSCoding protocol.

Hi Clain, nice post, thanks.

Would be interested to also hear your views on singletons, as there does seem to be a mixed reaction to their usefulness and whether they should be used at all by some users here. I've found them very useful, as long as you plan out what you want them to store in the first place, otherwise (in my first few attempts at using them), they quickly grew cluttered and hard to maintain (I tried to put everything inc. the kitchen sink at first).

Agree with your building small dedicated test applications. Since starting out using cocos2d (my first real attempt at developing any games more than as simple flash pong some years ago), I've built alot of little prototype apps to test certain features and learn the language and platform, whilst experimenting with various game ideas.

When I tried to initially build something more in depth, that combined a few different concepts, it soon grew into a mess. So I instead started from scratch again, put pen to paper with my designer, tried to get the rough key elements laid out on paper, and this process really helped us start to visualize how the game could be structured.

My main issue since then, and I presume this happens to a lot of newbie game developers, is your game idea can evolve, and as it evolves, you try and shoe horn in the extra features. Which if not thought out carefully (e.g. you want to experiment with new feature XYZ), you get it working, but its not extensible, or structured well, and can lead to spaghetti code. But when I started that app, I didn't think that idea would be feasible, or just hadn't thought about going down that route, so hadn't planned for it.

I know, I know, a good game design doc at the start is the ideal situation, but when your starting out, its hard to judge what you'll be able to physically pull off, so its hard to plan. At least thats what I found out.

After months of learning, and a couple of titles almost ready to ship, hopefully in the next 4 to 8 weeks, I feel more confident about starting future projects in a much more structured way. Just as I would do for my web dev work I do by day...