Loading and Saving Game Data on the iPhone / iPod Touch

There is no doubt that if you are new to iPhone / iPod Touch programming and development, and you've gotten your code to work great on Windows and / or OS X, you may be tearing your hair out when you determine that it just isn't saving on the actual iPhone / iPod Touch. There are a number of reasons here... but if you've come to this conclusion, then chances are you were also trying to save out a file to the device and finding it isn't working. The reason for that is you need to use special engine-level code to determine the location of the app directory, as you cannot save anywhere else on the device for security reasons.

So, there are a number of ways that you can store data on the iPhone / iPod Touch. You can store it as a file - which needs to be in the Documents directory, or you can save it in NSUserDefaults.

To you Windows programmers, NSUserDefaults is much like the registry - you can save data in keys and load it back when you need it. Much like the registry, you probably would not want to save the entire contents of War and Peace to a key, but it should give you more than enough to store a decent amount of game state data - in most cases, it should be the only save option you need.

So enough of my prattle - let's move on with the actual resource here, shall we?

In the engine code for iTGB, open up /platformiPhone/iPhoneFileio.mm and find a nice place to add in the following block of code (and make sure you do not add it inside the #if defined(TORQUE_DEBUG) section of code or else this will only work while you are in debug mode!)

//----------------------------------------------------------------------------
// Loading and Saving of data to the NSUserDefaults on the iPhone / iPod Touch
// Resource by Dave Calabrese of Gaslight Studios
//  - This resource gives some huge credit to those who helped me to get this
//    to work in the first place. Those people are:
//     - Bret Patterson
//     - Ronny Bangsund
//     - Marc Schaerer
//	 - Brandon of iCodeBlog and his post on saving and retrieving data from NSUserDefaults

void saveGameDataToDevice(const char* dataString)
{
	NSUserDefaults *prefs = [NSUserDefaults standardUserDefaults];
	NSString *convertedString = [[NSString alloc] initWithUTF8String:dataString];	
	[prefs setObject:convertedString forKey:@"mySaveGameData"];
	[prefs synchronize];
}

static const char* loadGameDataFromDevice(void)
{
	NSUserDefaults *prefs = [NSUserDefaults standardUserDefaults];
	NSString *myString = [prefs stringForKey:@"mySaveGameData"];
	return [myString UTF8String];
}

ConsoleFunction(saveGameDataToDevice, void, 2, 2, "(string) Save's the game data to a key defined in the Objective-C engine code.")
{
	//Con::printf("@@@ Engine acquired save data: %s",argv[1]); //Uncomment this to see the data being saved.
	saveGameDataToDevice( argv[1] );
}

ConsoleFunction(LoadGameDataFromDevice, const char*, 1, 1, "Load the game data from a key defined in the Objective-C engine code.")
{
	const char* result = loadGameDataFromDevice();
	return result;
}

What this will do is expose 2 functions to the TorqueScript:
<previouslySavedData> = loadGameDataFromDevice();
saveGameDataToDevice(<dataToSave>);

Those should be pretty self explanatory what they do. All you then need to do is integrate the two functions into your TorqueScript and create a single string of data that you send in to save, and parse out when you retrieve it!

The only other thing you need to do now is define the name of the key that you are going to save your data at. This should be rather unique to make sure you are not overwriting the data from another app: so something like 'mySaveGameData' is bad - which is exactly what the key in this code says! So, before you compile, go up into the Load and Save functions in the engine and change 'mySaveGameData' in the two places its found (once in each function) to something very unique (such as "awesomeTGBGameWithFeralKittens".... or something better).

And there you have it! Saving game data in NSUserDefaults!

This resource could not have been done without the following people who helped me as I struggled through my first few days with Objective-C and Cocoa programming:

- Bret Patterson
- Ronny Bangsund
- Marc Schaerer
- Brandon of iCodeBlog and his post on saving and retrieving data from NSUserDefaults

If you happen to see them somewhere, buy them a beer. Or several - they are quite the awesome people.

Feel free to improve upon this code and expand on it!