Adding Achievements to Your Corona Game or App Using OpenFeint & Papaya Mobile

Introduction

Achievements within games can help give incentives for players to learn how to play, give them confirmation they’re on the right track, and reward their accomplishments. They can also reward experimental behavior, create engagement for challenging or secret achievements, and can even create games within games. To paraphrase Jesse Schell, you can create the meta game, experiences that exist on top of other experiences.

Using one of the games I’m creating, this article will show you all the steps you need to do, plus Lua code, to get achievements in your Corona app or game via OpenFeint and Papaya Mobile. Additionally, I’ll cover mocking Achievements, as well as how to write code that’ll work for both OpenFeint & Papaya Mobile, and having them work offline.

Short Version

Log into OpenFeint.com (Login at the bottom):

Click the Features Tab:

Click “Achievements”:

Click “Add Achievement” button:

Fill our your achievement details and click the “Save Achievement” button:

Find your achievement in the list and copy the ID to the clipboard:

Implement in code:

gameNetwork.request("unlockAchievement", 1269182)

Done!

Start Anew?

If you don’t have an OpenFeint and/or Papaya Mobile account, there are a few steps you need to do first. You do not have to be complete with your game yet. OpenFeint & Papaya Mobile membership do not cost money.

1. Get an OpenFeint Developer Account.
2. Get a Papaya Mobile Developer Account.
3. Register your Game with OpenFeint.
4. Register your Game with Papaya Mobile.
5. Copy your OpenFeint and/or Papaya Mobile secret info into your code.

The above takes like 5 minutes; it’s really easy. Both have great CMS’.

Remember, you cannot currently use both OpenFeint and Papaya in Corona, only one or the other. Here’s an example that initializes one or the other:

local mode = "papaya"
if mode == "papaya" then
	gameNetwork.init("papaya", "secrectCodeHere")
elseif mode == "openfeint" then
	gameNetwork.init("openfeint",
			"SecretCode",
			"SecretCodeHereToo",
			"JesterXL: Invaded Skies",
			"YetAnotherCode")
end

Other Notes

Beyond having to choose which service to use, you should make that gameNetwork.init() call as soon as possible. It’s an asynchronous call, and you have no way of knowing in code if it worked; there is no callback function (here be race conditions).

The user will see a message like so on the bottom if gameNetwork.init() worked for OpenFeint:

When a user unlocks an achievement, you’ll see the achievement icon, name, and how many points it was worth:

If they haven’t logged into OpenFeint yet, or the phone doesn’t remember their credentials, it may say a number instead of a name, like mine says “JesterXL”. Your game/app should provide a button to login to OpenFeint/PapayaMobile. Remember, you can also go directly to certain areas as well such as leader boards and high scores.

Logging In

If the user hasn’t signed up or isn’t logged in yet, they’ll see a screen like this when they do:

Once logged in:

And the achievements screen:

Caveats

Although I haven’t confirmed this with my own research of statistics, I have heard that user logins with non-insanely popular games are low. Really low. This means that many most users of your games do not log into these services. Additionally, you do not have access to the emails OpenFeint & Papaya Mobile are collecting. These can be valuable for both accurate analytics, as well as present & future marketing opportunities.

This also places a burden on you as a game developer to assume the user may not wish to login. You thus need to provide scores & achievements (assuming your supporting the bare minimum of both Android & iOS) as an option in your game/app design and not force it upon the user. At the same time you want to encourage users to do so for the social aspects & rewards so need to make it easy for them to do so.

From a coding perspective, you have a few challenges as well. First, as mentioned before, you don’t know if a gameNetwork.init() succeeded or failed. You also cannot “get” data from the services to know what the user’s high scores are, nor what achievements have currently been attained. OpenFeint for iOS has the ability to upload and download arbitrary blobs to get around this, but it doesn’t work on Android, and Papaya Mobile has no such equivalent. Finally, the user see’s none of these features if they do not log in… which cheapens the experience at the cost of your hard work integrating them. Worse, at the time of this writing, you can’t even test these features in the simulator, only on an actual device.

I’m intentionally ignoring the fact that you need to sync high scores & achievement info between both services if you intend to support both (as I found it easy to do so).

Mocking Achievements

I created a project called Corona Mock for gameNetwork on Github. I got so frustrated I couldn’t test my achievements on the simulator. I was as also concerned that if users never logged in, all my work would be for naught. I wanted a fallback GUI that’d work without a server, yet the same code would work for either gameNetwork as well as offline. Here’s a video of it in action working in the simulator:

I’ll show some code below that allows you to mock or “fake” achievements in the Simulator. It solves the following problems:

1. You can test your code as you develop vs. having to deploy to a device every time. For achievements that require complexity to reach, this is a great time saver.
2. You can write the same achievement code and it’ll work on either OpenFeint, Papaya Mobile, or whatever other services arrive in the future.
3. You can optionally add better designs and use as your own achievement system if the user chooses not to sign up/login to OpenFeint/Papaya Mobile.

#3 is key here. While #1 ensures you don’t go nuts, and #2 helps life be better, you want to ensure the user still has a good experience when they don’t opt-in to the above services.

There are 3 things I recommend for mocking achievements.

• Create a constants variable to hold your achievements
• Create an Achievements class to wrap the gameNetwork calls, hold game state on what achievements are unlocked, and save state when your game/app exits.
• Create service classes to save score & achievement game state by reading/writing your Lua tables to JSON to/from the device

Constants

Here are 4 achievements in a constants file:

constants.achievements 							= {

	liftOff 		= {pid = 683, oid = 1269172, image = "achievement_Lift_Off.png", name="Lift Off", unlocked = false},
	firstBlood 		= {pid = 684, oid = 1269182, image = "achievement_First_Blood.png", name="First Blood", unlocked = false},
	dogFighter 		= {pid = 685, oid = 1269192, image = "achievement_Dogfighter.png", name="Dogfighter", unlocked = false},
	veteranPilot 		= {pid = 686, oid = 1269202, image = "achievement_Veteran_Pilot.png", name="Veteran Pilot", unlocked = false},
	zeeMissile		= {pid = -1,  oid = 1272282, image = nil, name="Zee Missile, It Does Nuffing!", unlocked = false}
}

Notice a few things. First, we designate the name of the achievement as the key in the table using camel-case. So, the “First Blood” achievement, we’ll refer to in Lua as constants.achievements.firstBlood. Also, the pid and oid; those are the “Papaya Mobile Achievement ID” and “OpenFeint Achievement ID”; same achievement, just different id depending on the service you’re using. The image is the same image you’ve uploaded to the OpenFeint and/or Papaya Mobile services, you’re just packaging it with your game as well just in case. The name is the nicely formatted name you’ll show the user. Finally, the unlocked variable means if the user has unlocked that achievement yet or not.

Cool, so now that you have your achievements defined. If the id’s ever change, or you decide to name it something else, your code doesn’t have to change because it’ll just reference the achievement table name. Let’s use them.

Achievements Wrapper

For a short example, you can see check out the Corona Mock for gameNetwork example project I have on Github. Otherwise, you can see the full, in-progress class in one of my games, but for now, I just want to show you 1 function in particular:

function AchievementsProxy:unlock(achievementVO)
	if achievementVO.unlocked == true then
		return true
	end

	achievementVO.unlocked = true

	if self.useMock == true then
		self.mock:showAchievement(achievementVO.image, achievementVO.name)
		return true
	end

	local idFieldName
	if self.mode == "openfeint" then
		idFieldName = "oid"
	elseif self.mode == "papayamobile" then
		idFieldName = "pid"
	end

	gameNetwork.request("unlockAchievement", achievementVO[idFieldName])
end

The achievementVO in this case is one of your achievements in your constants. Anywhere in your game/app you can call this Singleton function and unlock an achievement, whether mocking or on the device. Notice:

• if the achievement is already unlocked, it aborts the function call
• it unlocks the achievement
• if you’re mocking achievements, it’ll show a fake OpenFeint/Papaya Mobile GUI so you can test in the simulator and see what gameNetwork.init() is called as well as when achievements are unlocked.
• it determines what service your using and finds the appropriate id to send and makes the unlock achievement call

While useMock is true when running in the simulator and false when running on a device, you’re welcome to set true at any time. I’m just detecting the platform in the beginning and setting the value like so:

local platform = system.getInfo("platformName")
if platform == "Android" or platform == "iPhone OS" then
	AchievementsProxy.useMock = false
else
	AchievementsProxy.useMock = true
end

You can then litter your code with calls to the AchievementProxy singleton class, knowing it’ll work whether your in the simulator, or not, and optionally if the user has signed into a gameNetwork or not, like so:

AchievementsProxy:unlock(constants.achievements.veteranPilot)

Loading and Saving Game State

That’s all well and good, but when happens when the user quits your game and starts back up again? The constants are the same. No memory of what achievements were unlocked are actually saved. If the user logs into OpenFeint/Papaya Mobile, sure, their servers take care of all that… but what if the user never does? How do you make sure the user’s progress is remembered?

Adding this method to be called at the end of AchievementsProxy’ init method:

function AchievementsProxy:loadAchievements()
	local savedAchievements = LoadAchievementsService:new("savedAchievements.json")
	if savedAchievements == nil then
		return false
	end
	for savedAchievementName,savedAchievement in pairs(savedAchievements) do
		self.achievements[savedAchievementName] = savedAchievement.unlocked
	end
end

This function loads JSON from the phone, parses it into an achievements object (exactly like what’s in your constants file), and updates whether it’s been unlocked or not.

When you’re game/app shuts down, make sure to save them out, like so:

function AchievementsProxy:saveAchievements()
	SaveAchievementsService:new("savedAchievements.json", self.achievements)
end

All these service classes do is read & write JSON (a text format) to your phone. Johnathan Beebe has a good tutorial on working with JSON in a blog post that I basically copied most of my code from so nothing fancy here. The LoadAchievementsService class is just a wrapper around the function Jonathan gave:

require "json"

LoadLevelService = {}
LoadLevelService.loader = nil

function LoadLevelService:new(jsonFileName)

	local loader

	if LoadLevelService.loader == nil then
		LoadLevelService.loader = {}

		loader = LoadLevelService.loader

		-- jsonFile() loads json file & returns contents as a string
		function loader:jsonFile( filename, base )
			-- set default base dir if none specified
			if not base then base = system.ResourceDirectory; end

			-- create a file path for corona i/o
			local path = system.pathForFile( filename, base )

			-- will hold contents of file
			local contents

			-- io.open opens a file at path. returns nil if no file found
			local file = io.open( path, "r" )
			if file then
			   -- read all contents of file into a string
			   contents = file:read( "*a" )
			   io.close( file )	-- close the file after using it
			end

			return contents
		end
	else
		loader = LoadLevelService.loader
	end

	local jsonString = loader:jsonFile(jsonFileName)
	local level = json.decode(jsonString)

	return level
end

return LoadLevelService

I’ll leave the SaveAchievementsService class as a reader exercise.

Application State

That’s it. As you can see upon loading, you load the current state of the game from a saved JSON file on the phone, if any. Any time the user unlocks an achievement, it’ll update the achievement’s unlocked property to true. When the game/app ends, it’ll save that state to the phone in a JSON text file. When the game/app boots back up, it’ll read that file, update the in RAM achievements to what they were when the user last used it.

This ensures if the user does choose to sign up/log into OpenFeint/Papaya Mobile, they still get a good user experience using your achievements. You’ll just need to make a better design for my Mocking class, and perhaps make a list screen that shows the current achievements they’ve unlocked.

Flash Developer?

OpenFeint, Papaya Mobile, Urban Airship, and others clearly don’t care about Flash, doesn’t even seem on their radar. While Adobe is making a big gaming push as of late with their gaming center and recent Flash Player 11 features, these services don’t even offer API’s to easily use them. I even remember OpenFeint about a year ago have a private beta for their REST API… which I can no longer find anywhere.

We’ll have to wait for some enterprising dev to wire them up and expose them via Native Extensions.

I do know SuperRewards has some form of Flash and API support.

Anyway, if you’re a Flash Dev and feeling left out, check out Scoreoid; it was made for Flash.

Conclusions

Achievements add guidance, are a progress indicator, and allow recognition. Their an incentive for learning, confirmation the player is on the right track, and reward accomplishment. While services like OpenFeint & Papaya Mobile make it easy to create & code them in your Corona SDK game or app, based on the metrics I’ve heard, you should remember while you should make it easy for users to sign in, don’t force it upon them. With a little abstraction you can ensure achievements still work in your game and only optionally use those services if your user wishes to do so while reducing the amount of work you need to do.

Achievement Unlocked: You read this whole thing.