GamerSafe: GamerSafe Developer's Guide

GamerSafe Developer's Guide

Overview

Gamersafe is an ActionScript 3 framework to make your Flash games more engaging and more profitable. It's not automatically effective, though. The actual software integration is very simple, but you'll need to give the design integration some serious thought. I'll go over several examples of each feature in their relevant sections. Consider how each of these features may be applicable to your game, and how you'd want to encourage the player to use them. If you have any questions or ideas, don't hesitate to email me.

If you'd rather jump right into code, download the sample application. It's a test console I wrote for my own use, but you can see how most of the GamerSafe systems work in there. It was written in Flash Builder 3, but it also imports just fine into FlashDevelop

Getting Started

Before you can start integrating GamerSafe into your game, you'll need to register as a developer on GamerSafe.com and create a new game. The GamerSafe developer website is where you'll configure many of your games' GamerSafe features, such as Items, Achievements, and Leaderboards. You'll also set important revenue sharing data here. Note that when you first create your game on GamerSafe.com, it's not immediately going to be publicly linked on the website. It doesn't ever have to be shown on our website, if you don't want it to (though having it publicly on GamerSafe.com will get you some extra views from our most rabid fanbase.). We only ask for a game URL so that we can later review the game before activating it.

When your game is done, it needs to be approved before the GamerSafe API turns on. GamerSafe will review your game primarily for quality, but also for content. We generally frown on explicit nudity, hate speech, and excessive gore.

How it Works

After you register your game on GamerSafe.com, download the GamerSafe API file. This file is automatically generated for each game, with an embedded passcode and hash seed for your game. Note that there is no SWC or FLA to embed in your game. All you need to do is add this one ActionScript class called GamerSafe, and it will handle everything for you from there. The GamerSafe class is a singleton pattern which loads a GamerSafe SWF from our web server whenever you create it. Afterwards, you can interact with it through the GamerSafe.api static property from anywhere in your code.

This procedure allows us to keep updating the GamerSafe library without requiring you to download new libraries and rebuild your application whenever we change anything. Refinements to existing features go out seamlessly and immediately with no work on your part. When we add new features, all you have to do is download a new GamerSafe.as file from the website to get at the new interfaces. The GamerSafe library is smaller than 150kB at the time of writing, and does not grow quickly. It should load almost instantly for you and your players

The Constants File

After you set up your achievements and scoreboards and items on the website, you will probably find it handy to download a constants file. This is just a simple ActionScript class that provides constants for all the GamerSafe objects you've created. Otherwise, you'd have to write down their ID numbers and embed them in your code, which is hard to maintain. Compare:

showScoreboard(GamerSafeConstants::SCOREBOARD_LEVEL1);
vs
showScoreboard(1921);

You should download a fresh version of this constants file whenever you edit your game objects on the website. View the file in any text editor to see the names of all your objects.

Testing with GamerSafe

Before a GamerSafe game is approved, it is in "test" mode and can't be logged into with actual GamerSafe accounts. The developer (and sponsors and distributors) can log in only with test accounts. You can make as many test accounts as you like on our website; we automatically make some for you to get you started. All test accounts have names like "TEST12345_abcdef". You can view all of your existing test accounts from the test accounts page. Test accounts are created with 10000 GamerPoints and 10000 GamerGold so that the microtransaction features can be tested. As soon as the game is approved and activated, only proper GamerSafe player accounts can play the game, and when people spend GamerGold in the game, you get paid.

Scoreboards

One of the most popular and simplest features of GamerSafe are the Scoreboards. Players can record their high scores and see how they compare with everyone else that has played the game over a given day, month, or all time. You can create and configure multiple boards for each game, and set their sort order and whether you'd like them displayed as a plain integer or a time. You could have one leaderboard for "Fastest time on Level 3" and another for "Highest Score on Level 3". Set up as many as you like.

When you want to submit a score to the scoreboard, this is all you need to do:

protected function onShowHighscore():void {
	GamerSafe.api.showScoreSubmit(myScore, extra, showAsTime, scoreboardID);
}

This function will cause a dialog to pop up showing their score. If the user is logged in to GamerSafe, their user name is pre-populated. If they aren't logged in, they can enter a name here. In either case, they can choose to cancel and not record their score. They can also look through the top scoreboards.

If you want more control, you can create your own score recording system. Use the GamerSafe.api.saveToScoreboard() function. Use showScoreboard() and closeScoreboard() to show scoreboards. If your game is smaller than usual (about 500x400), our default scoreboard may look funny; try the showSmallScoreSubmit() and showSmallScoreboard() functions instead. We've tried to make the methods of GamerSafe as obvious and self-documenting as possible, but you should always consult the API reference documentation if you're not sure what a function does.

Achievements

It has become very popular to record when a player does something notable in a game. These are usually called Achievements or Trophies or Challenges or what have you. They are another method to encourage a player to keep playing your game. You can set up GamerSafe achievements on the developer section of the website. Each game can have as many achievements as you like, and they can hand out a total of 1000 GamerPoints per game. We'll discuss GamerPoints and GamerGold in the Microtransactions section, below.

All achievements have a title, an icon, and a description. These should be fairly self-explanatory. The icon graphics are hosted on GamerSafe.com, so you don't need to worry about hosting them yourself or embedding them in the game. After configuring your achievements, your code just calls the GamerSafe.api.bestowAchievement() function with the ID of the achievement the player just attained. This will cause a small graphic to appear in the foreground of the game for a few seconds, showing the name, icon, and description of the achievement without interrupting gameplay. Players that aren't currently logged into GamerSafe when they gain an achievement are still shown this graphic, but it isn't saved. If the player later registers with GamerSafe during the game session, the achievement is saved.

You can award achievements for just about anything, but there are a few typical categories:

Introductory Achievements - it's often a good idea to put in a few achievements for doing relatively simple things like finishing the first level or getting a powerup for the first time. This gets the player used to getting achievements and is usually their first interaction with GamerSafe.
Completion Achievements - for completing a given level, defeating a challenging boss, or finishing the game. If there are multiple achievements for finishing the game, some players will play it all the way through again.
Challenge Achievements - for doing something not entirely necessary to finish the game, but entertaining or adding extra difficulty. Perhaps "beat a level without getting hit" or "counter 100 attacks" or "finish your opponent with the Ultimate Atomic Buster"

Saved Games

When your players return to your game after an absence, they don't usually want to start over fresh, and this is how you can keep track of their progress between sessions. The GamerSafe.api.savedGame property is just a public String. You can write whatever you want into it, up to 10k. The data is immediately sent to the GamerSafe server... there's no other function to call. This variable only works if the player is logged in with a GamerSafe account, so you'll want to check it from the onLogin handler. In the example below, we assume that creationComplete() is being called by your game when the program is ready to go, and saveTheGame() is the function you call when you want to save the game.

protected function creationComplete():void {
	// tell it what function to call when a user logs into GamerSafe
	GamerSafe.api.onLogin = onLogin;
}

protected function onLogin(e:Event = null):void {
	// now that they've logged in, you can check the savedGame variable
	// to see what their old saved-game was!
	var savedGame:String = GamerSafe.api.savedGame;
}

protected function saveTheGame():void {
	// just assign any string to the savedGame variable, and if the user
	// is logged in, it will be saved to the GamerSafe server automatically
	// a common technique is to smash very complex objects into a string.
	// serializeGameState() would be a function you write that sticks all
	// important game data into one string.
	GamerSafe.api.savedGame = serializeGameState();
}

If you need more complex data storage features, check out the LevelVault API

Items and Microtransactions

Microtransactions allow players to spend real money in your game. You define a set of virtual items that players can purchase from the GamerSafe Shop screen in your game. These can be any number of things. Usually, you sell in-game items, like the equipment in Gib Fest or the mech parts in Mechanical Commando 2. Some developers sell items that act like a special game-specific currency, like Them Coconuts or GunBot do. Alternately, you can sell "unlockables" like extra game modes or playable characters. TrapMaster lets you buy an expansion pack with more playable monsters and levels. Demolition Dude lets you purchase access to an in-game level editor that utilizes our LevelVault feature. Async Racing sells new cars to race in, as well as credits used to publish user-created racetracks. The Search For Wondla is an interesting case, as it was produced to promote a book by the same name. It utilized the GamerSafe Shop to sell wallpapers, a screen saver, and an excerpt of the book.

When setting the price for your virtual items, keep in mind that there are two currencies available in GamerSafe - GamerGold and GamerPoints. GamerPoints are rewarded from gameplay, through Achievements. GamerGold is purchased and represents hard currency. Usually, through a few introductory Achievements a player will attain enough GamerPoints to purchase an item from the store, where they can see what else is available in the store. It is important to design your interface in such a way that it easily directs users to the GamerSafe Shop if you want microtransactions to be successful. Use the GamerSafe.api.showShop() function if you want the full Shop UI to pop up. You can also use GamerSafe.api.purchaseItemInterface() to allow a user to quickly buy a specific item without showing the full shop GUI screen.

Note that GamerPoints can be carried between games, so if a player tries out the demo Shooting Game and attains a few hundred GamerPoints, they can then go spend those in any other GamerSafe game. This is an effective retention mechanism: because those points act like a currency for all GamerSafe games, players will often keep playing your game "just a bit longer" in order to earn more achievements and extra GamerPoints.

Keep in mind that if a player has played a lot of GamerSafe games in the past, they may show up to your game with enough GamerPoints to buy many items from your shop immediately. That's a good thing (because players who buy lots of items, whether with GamerPoints or GamerGold, feel more "ownership" of the game and won't leave as quickly), but it may mean you need to plan the prices for your items accordingly: you can't rely on the player only having GamerPoints earned from your game.

Shop Items are organized into categories. This is useful in case you only want to show certain items at certain points in game progression. It also serves to organize the items in the store. You can hide and show categories of items in the shop with the GamerSafe.api.setShopCategoryVisible() method. For instance, if you have a traditional fantasy role-playing game with lots of shopkeepers and you want each shopkeeper to offer items of a particular type, you could categorize your GamerSafe items into weapons, armors, and potions, and show only the appropriate category at each shopkeeper.

Not all GamerSafe items need to be "for sale": You can also bestow free items with the appropriately named method GamerSafe.api.bestowFreeItem().

It is possible to configure an item to be "consumable", meaning that it can be used up by the player and be bought multiple times. Airborne did this with success, and this is generally how secondary currencies work - the user purchases a consumable item that is immediately consumed and converted to the secondary currency. There are some practical restrictions on what can be consumed: for performance reasons you wouldn't want something as small as a single bullet to be a consumable; instead, your consumable item would be a "box of 500 bullets" that gives the player 500 individual bullets. See GamerSafe.api.consumeItem() for more details about how to organize your consumables.

Facebook Messages

GamerSafe has features that utilize the Facebook social networking site to help developers draw new players into their games. They're easy to add in and encourage GamerSafe registrations as well.

The first thing you can do is ask the player to connect. Use GamerSafe.api.facebookConnect to prompt your players to log into Facebook. They shouldn't have to do this every time. You can tell if your player is logged into Facebook by handling the GamerSafe.api.onFacebookConnected event.

One of the most useful things players can do in your game with Facebook is to invite their friends to play your game. This can be done through our Friends List interface. Use GamerSafe.api.showFriendsPanel() to invite a player to select some friends they'd like to write a message to. Once the friends are chosen, the Publisher panel is displayed, and the user can write a message that will appear on their friends' Facebook walls.

Before you do this, you should configure an attachment for the message. This attachment appears on the Publisher panel, so the user won't be surprised when they view the message later on Facebook. This attachment is important because it lets you invite players to your game with an image and a link. You can use GamerSafe.api.facebookConfigureAttachment() to set up this information. Here's an example:

protected function onFacebookConnected():void {
	GamerSafe.api.facebookConfigureAttachment(
		// the title of our attachment. it will be a link to our game.
		"BlastoTron 9000", 
		
		// the caption, or sub-title of the attachment
		"Vaporize XenoPirates in BlastoTron 9000!", 
		
		// the main text of our attachment
		"BlastoTron 9000 is the awesomest game in the history of video "+
		"games! Customize and upgrade your robo-ninja battlecruiser as "+ 
		"you hunt down the dreaded XenoPirates!",
		
		// a link to your game or website
		"http://www.gamersafe.com/", 
		
		// the URL of an image to show 
		"https://www.gamersafe.com/icons/261_a83hkyz3_1283202484.png"); 
}

Here's how that will look in the Publisher panel:

And on Facebook:

Anyone that clicks on the attachment title or the icon is sent directly to your game via the URL from facebookConfigureAttachment(). Gunbot successfully combined these Facebook features with the LevelVault to reward players that recruit their friends, and that's what social networking is all about.

LevelVault

For simple stand-alone games, the savedGame variable is all you need. But if you want cutting-edge data sharing, storage, and management, you'll want to use the LevelVault API.

It earned the name "Level Vault" because it's very good at storing and retrieving user-created game levels, with lots of bells and whistles like ratings, abuse reporting, and various searching and indexing options.

But user-created content can take many forms, and the low-level features allow you to do a great many database-manipulation tasks without needing your own server - all LevelVault data is stored on the GamerSafe servers.

How powerful is LevelVault? Some advanced developers are even using it to create concurrent multiplayer games. And we're constantly adding more features to make it more powerful.

LevelVault is a fairly complicated system, so it has it's own manual. The sample application connects to LevelVault and does some basic operations, so that might be a good place to look first to get a quick idea of how LV works.