This quick video will give you an overview of the Amazon GameCircle API. It will cover why developers should use GameCircle, how Whispersync for Games helps preserve player progress between devices, what experience points / cross-game achievements are, and cover the process for viewing engagement analytics through GameCircle’s Achievement Reports. Whether you are completely new to GameCircle, or have achievements already integrated into the existing gameplay of your app, this video will provide you a quick introduction on how to increase player engagement, improve retention, and enhance the customer experience.

For more information about player profiles and mobile development, see our online documentation:

• GameCircle Achievements, Leaderboards, and Whispersync for Games
• Cross-Platform Solutions for Android, iOS, HTML5, and More
• Mobile Game Development with Amazon

If you followed along from the first part of this series you should be up to speed on how the Unity IDE works. In this post we will dig deeper into the code side of things. I am a big fan of C#, and while Unity Script is useful, eventually you will need a little more flexibility in your code. So, to help you along, I thought it would be valuable to write a quick primer on working with C# in Unity, as well as some of the most common APIs you will be using when we build our game.

Picking a Code Editor

In order to code in Unity you will need to pick an external editor since Unity doesn’t have one built in. By default, Unity ships with MonoBuilder, but you can just as easily switch it out for something a little more robust, such as Visual Studio if you are doing your development on Windows. Simply go into the Edit > Preferences menu and change the path to the external editor.

Once you have picked an editor you like, you are ready to start coding. In this post, I will be showing the code from Visual Studio, but MonoDeveloper will work similarly to Visual Studio but on Windows and Mac.

Data Structures

C# is a strongly typed language and is very similar to Java or ActionScript 3. If you have some background in JavaScript, it should feel familiar as well. Let’s take a look at the basics of the language. To start with, we will look at variables and lists, which are the building blocks of any language. To make a variable, simply declare it, like so:

var name = “Jesse Freeman”;

While C# is a typed language, it supports type inference, meaning that when you declare a variable you don’t always have to define the type. There are a few primitive types you should know about:

string name = “Jesse Freeman”;
int age = 34;
bool alive = true;

When it comes to numbers, you should also understand more complex types, such as Float:

float speed = 4f;

Notice that we use the f suffix for our float. Floats are numbers that contain decimals and are used for more granular positioning within the game world, as well as in the built-in physics engine. Ints are useful for whole numbers where you don’t need to perform calculations that would generate fractions, such as a player’s health. You should always be aware when using Int, Float, or other number types because you may be forced to cast it to a specific type in order to perform the calculation and you may incur a performance penalty. Here is an example:

float example = (float)age * speed;

You can learn more about the different types in the C# reference docs at http://bit.ly/1bwLAKW. The next set of building blocks is Array and List. An Array is collection of multiple variables, usually of the same type.

var stringArray = new string[2];

In C#, Array are fixed meaning you can’t alter their length. You can modify its contents via their position in the Array itself. The position is an id, which represents a unique number for each location in the Array. In C#, arrays start at 0.:

stringArray[0] = “Jesse”;
stringArray[1] = “Freeman”;

You can access values in an Array by their index just like we modified it. Here is how I would create a string with my full name from the above Array:

var name = stringArray[0]+” “+stringArray[1];

Unity also supports Lists as part of the C# library. In order to use this, you will have to import its package (System.Collections.Generic) at the top of your script, which I will show you how to do later on. For now, here is an example of a list:

List<int> listOfInts;

This is what we would call a generic List. The term generic refers to a dynamic type we can assign at runtime. Generics are a core part of the language, and something you should get familiar with as you gain more experience coding in C#. In this example, we can create a list with a type of Int. Now this generic list can contain whole numbers. For performance, you will want to use lists over arrays when you don’t know the exact size of the data and expect to be adding or removing values at runtime. An Array by contrast has a set number of items you can have in it and shouldn’t attempt to modify the length at runtime.

The last data object I want to talk about is a vector. Unity makes use of a Vector3, but now with the addition of the 2D workflow, they now rely on Vector2D a lot more. Here are examples of both:

var v3 = new Vector3(0,0,0);
var v2 = new Vector2(0,0);

Vectors allow you to store 3D or, in this case, 2D points in space so you can access the value of x, y, and z from the vector. Here is an example:

Debug.Log(v3.x); // will output 0

One quick note is that you see I am calling Debug.Log. This will output the value to the console window.

This is similar to most other languages, such as JavaScript’s console.log and ActionScript’s trace. It’s also the first step in debugging your apps if you ever need to see the value of an object or property.

Classes

C# takes full advantage of classes, interfaces, and a host of other ways of packaging up code for reusability. Unity itself is built on a very easy-to-grasp composition system, which it favors over inheritance. Let’s look at how to make a simple class. Go to the Create menu and select a new script.

As you begin to create a new script, you will notice you can select from the three built-in languages. Select C# and call the script HelloWorld.

Unity will stub out the code you need for your class for you. Here is what it will look like:

using UnityEngine;
using System.Collections;

public class HelloWorld : MonoBehaviour {

	// Use this for initialization
	void Start () {
	
	}
	
	// Update is called once per frame
	void Update () {
	
	}
}

As you can see, you won’t need to memorize how to create a class from scratch, so I will simply focus on two main parts of the script: the import block and the methods. By default, each new class extends from MonoBehavior. There are numerous methods you can take advantage of, but we’ll start with the first two: Start and Update.

Let’s go back to our previous example of a generic list. While this isn’t the traditional way of doing a Hello World example, I’ll be able to show off in a little more detail what it is like to import external libraries, create properties on a class, and output that to the console window. To start, look at the top of the class at the import statement and add the following:

using System.Collections.Generic;

Now, just before the Start method, we are going to add a property. Properties are variables that are scoped to the instance of the class itself. That is a fancy way of saying that anything inside a block of code will have access to its contents. Depending on how we declare the property, other classes will have access to it as well. C# supports private and public variable denotations. If you don’t declare one, it will automatically default to private. Add the following property above our Start method:

public List displayText;

Now, in our Start method, add the following:

displayText.Add("Hello");
displayText.Add("World");

Now we need a way to display this text. Add the following to the Update method:

Debug.Log(displayText[0] + “ “ + displayText[1]);

Here you can see we are using the Debug.Log method again, and we are accessing the first and second values of our list. It’s important to note that arrays and lists are 0 based in C# just like Java, AS3, and JS. Now we have a script that will output Hello World to the console tab on each frame, but we don’t have a place to put it. Go back to the Scene and select our camera. From here, scroll down to the bottom of the Inspector panel and select Add Component. Now select our HelloWorld script and it will attach itself to the camera.

Now, if you run the game and look at the Console tab, you will see Hello World outputted on each frame.

While this is a simple example, let’s do something a bit more interesting. Go back into your script and let’s have the camera scroll to the right. The camera is a GameObject just like any other primitive you add to the Scene via the Create menu. All of these GameObjects share some common properties, with position, size, and scale being just a few of them. Also, all of these GameObjects share the same API we are taking advantage of right now, which are the Start and Update methods. Let’s look at how we can programmatically move the camera. To get started, let’s add a new property called:

public float speed = 2f;

Next we’ll want to replace our Hello World Debug.Log call with the following:

transform.Translate(new Vector3(speed, 0, 0) * Time.deltaTime);

As you can see, we have taken the transform position property and are modifying it with a new Vector3 that contains our speed value and is multiplied by the Time.deltaTime. If you simply increased the x position by speed, you are not taking into account any slowdowns in the game itself. By using the delta between each frame, you are able to keep your movement consistent from frame to frame, regardless of dips in the frame rate. This isn’t a magical formula; all it means is that your GameObject will move at the desired distance over time. So if the frame rate drops, movement will look jerky but won’t slow down or speed up as the FPS naturally fluctuates based on other things going on in the game.

If you run the game, you will see the camera move. It will appear like the box that we created earlier is simply scrolling off the left side of the screen. Stop the game and take a look at the camera’s Inspector panel. If you scroll down to the script area, you will see we now have a new input field called Speed we can alter.

This is an important concept in Unity. Basically, any public property on a script can be edited from the IDE in the Inspector window. So, while it’s important to create default values for your properties, just know that you can alter those values on an instance-by-instance basis, and even temporarily at runtime when you are debugging. This is incredibly powerful and something we will be taking advantage of later on. Not only does this work with simple properties, such as Strings, Numbers, and Booleans, but it also works with collections, such as Arrays and Lists.

If you remember back to our first example, we had a list called displayText, which we also made public. You should see it in the Inspector panel as well, but the value is hidden. Simply click on the arrow next to its property name. You can even add new items to it by changing the Size value.

So, at this point, you should have a basic concept of how scripting works in Unity. Everything we covered here will be re-introduced in the following chapter. There is just one last thing I want to cover, which is how to think through scripts for GameObjects.

Composition over Inheritance

If you come from a traditional computer science background or have worked with other object-oriented programming languages before, you may be familiar with the argument on composition over inheritance. One of the cornerstones of OOP languages is the concept of polymorphism. While inheritance plays a large role in game development, Unity strives for the use of composition as much as possible. I consider scripting in Unity to follow the decorator and component design pattern. Each script adds additional functionality to your GameObject, but they are mostly self-contained. While some scripts rely on others to function, as we will see in the game we end up building, we really strive to create small, reusable blocks of code that can be applied to multiple GameObjects. When put together, each of these smaller scripts build up to a greater set of logic that builds up the functionality of each GameObject. While inheritance is possible, I strongly recommend thinking through composition as a means to not only create more modular, self-contained code but to also separate and encapsulate independent game logic. This kind of thinking is critical when it comes to grasping the true power of creating scripts in Unity.

Wrapping Up

By now I am sure you are itching to get into more coding, so start playing around with some of the great tutorials out there on Unity. We’ll continue to add new posts about Unity, especially with working with the new 2D workflow, over the next few months so make sure you keep checking back.

Also, don’t forget that to checkout Amazon’s GameCircle plug-in for Unity to help you integrate cross-platform leaderboards, achievements, and game data synchronization. The plug-in works on iOS, Android, and Fire OS plus with the built-in Whispersync for Games component you can back up all of your user’s game data to the cloud across all three platforms. You can now download it from the Scripting/Integration section of the Unity Asset Store.

Additional Resources

• Introduction to Unity Part 1: Unity’s IDE
• GameCircle - https://developer.amazon.com/appsandservices/apis/engage/gamecircle
• Publishing to Amazon Appstore - https://developer.amazon.com/public/support/submitting-your-app

-Jesse Freeman (@JesseFreeman)

One of the questions we hear frequently from developers is which platform they should target first when building their app. Adrian Barritt, head of development at Barnstrom Games, along with his team asked the same question when planning their app The Chase. The Chase first launched in August of 2013 and was the first app that the team decided to launch in the Amazon Appstore. The app allows a team of four challengers to play against a machine to test their knowledge. When asked why they chose the Amazon Appstore, Adrian said that “the opportunity was huge, and [we] saw similar apps performing really well on the Amazon Appstore”. The team also mentioned that “it doesn’t hurt when you hear good things from others [Square Enix] and how impressed they were with the coverage they received” says Adrian.

Recently, we had the chance to sit down with Adrian to discuss how they got their app to rise to the top of the charts in the UK, and how they view their experience with Amazon Appstore. Here are some of Adrian’s observations:

500% Increase in Sales Upon Launch of Amazon Coins

“Our sales went pretty ballistic when Amazon launched Amazon Coins.” says Adrian. Amazon Coins are generally used by customers to explore and try out new apps. Customers can get Amazon Coins in a variety of ways such as purchasing or earning Coins for free. Developers can really benefit from this since there are a lot of customers waiting to use up their Coins on different apps. Barnstorm Games specifically saw their app benefit from this.

“Our sales went up 10-fold (1000%) for about a week during the Amazon Coins promotion when Amazon gave away a vast amount of Coins to their customers. Even after the promotion we saw a 500% increase in sales from what we used to get.”- Adrian Barritt

Part of Adrian’s strategy is understanding when consumers usually purchase apps. The team made sure that their app would be ready for launch before the holidays. As a result the team saw a “2000% increase on Christmas Day compared to our average sales we usually get per day”. Since then, the team continues to see a consistent increase of 200-300% in sales after the Coins promotion ended and is now consistently ranked among the top 3 apps in the UK.

“We are more than happy with our performance in the Amazon Appstore and our expectations have been exceeded” – Adrian Barritt

Transitioning the App to Google Play with Ease

One of the goals for Barnstorm was to expand their app onto more platforms. Since the team initially built their app on the Kindle Fire, they knew that Android would be a natural transition. So how was the process for transitioning the app over to Android? “The transition for creating an Android version was very easy since Kindle Fire was just designed that way.” says Adrian. You may recall that 75% of Android tablet apps that we tested just work on Kindle Fire with no additional development needed so it’s not surprising that Adrian said that “there was no additional work needed beyond supporting GameCircle and thinking what services to use. Other than that it was very simple.”

“Even though we are on Google Play as well now, the majority of the time the Amazon Appstore still performs better than Google Play in terms of revenue”.

Using GameCircle to increase Engagement

One service that Barnstorm is using to increase customer engagement is the GameCircle API. “With GameCircles’s achievement feature, it’s definitely helped us retain and engage our users” says Adrian. The team uses achievements to mark how well players are performing against others in “The Chase”, which has really improved average session length. After seeing the success with GameCircle, Adrian is currently looking into more services such as Amazon’s Device Messaging API to engage the audience even more by pushing out notifications to them.

Next Step for Barnstorm

The team has a new app that they just released in the Amazon Appstore called Tipping Point. The app is already topping the charts in the UK as well and the team has high hopes for it. Barnstorm also just participated in Amazon’s Free App of the Day program as well, helping them get even more exposure to customers.

Learn more about the tools used by Barnstorm Games

Amazon Coins

GameCircle

Free App of the Day

One Game, Everywhere

Gone are the days where you can make a game and publish it to a single platform and expect to be successful. Like any business that sells consumer products, you need to go where the people are. That means the games you make should run on a multitude of different platforms and accept any number of different input types. There’s also one more catch: your players expect to be able to share their game data across all of these different platforms, especially if they are paying for your game multiple times. With that in mind I have outlined what I call “responsive game design,” which is modeled loosely after some of the core concepts of responsive web design. It’s also a framework that will help you think about enabling your games to scale across multiple platforms.

Applying Responsive Design Concepts To Games

On the web, responsive design is a set of guidelines and best practices that help websites scale from desktop to mobile. Web developers discovered early on that it was too difficult to maintain separate designs for desktop and mobile so this solution allows a site to re-adjust to any resolution based on a set of ideal screen sizes. While responsive design on the web focused solely on adapting a site’s visual design based on common viewports, the notion of responsive game design builds on this concept to include other key aspects you need to consider when making multi-platform games.

Responsive game design can be summed up in the following key requirements:

1. Game graphics and UI support multiple resolutions
2. Game mechanics work across multiple types of input
3. Publish to multiple platforms with the same codebase
4. Saved data is synced across all platforms

While most of these are already best practice for games in general, the collection of them represent a guideline for game designers moving forward to help reach the broadest audience possible.

1. Scaling Game Visuals Across Different Resolutions

If you come from desktop game development this is not going to be a big shock to you since it’s common practice to support multiple-resolutions and varying computer performance. While mobile development is relatively new in this space, over the past few years, mobile device resolutions have tended to normalize around a few key aspect ratios (3:2, 4:3 & 16:9) allowing the same desktop game concepts to be applied:

• Build for aspect ratios not fixed resolutions
• Create simplified, dynamic UI that can adapt to different resolutions
• Have degradable graphics that can adapt to the power of the device

It’s also important to note that optimizing a game’s graphics goes well beyond just the resolution. Each system has different performance so being able to dynamically scale the game’s visual effects across these different platforms is critical as well. Especially when dealing with high pixel density displays, you could actually end up pushing incredibly high resolutions on devices that can’t fully support them. Also you may need to tone down specific special effects on mobile verses desktop or perform special optimizations when going to TV to account for slower display refresh rates. Make sure that you take into account these limitations and plan accordingly.

2. Supporting A Single Control System Across Different Input Types

A single game can support three types of input (mouse + keyboard, controller and touch) based on the device they are on. While thinking through each of these inputs, game designers should consider how their game will work going from desktop to tablet to phone and TV. Will the controls hold up on a system without physical buttons or should the gameplay be simplified a bit to account for the lowest common denominator?

It’s completely possible to have games work with a single input mechanic but a lot of planning and consideration must go into the overall design of the game. Most devices accept a game controller at this point so while not ideal, players can still plug one in if virtual controls are too frustrating. It’s especially important to take into account that not everyone who plays your games will have access to a controller. The Fire TV ships with a remote by default so if you want to capture the largest audience possible you’ll want to make sure you support the remote out of the box. You can still publish a controller only game but keep in mind that each input limitation you place on your game shrinks your potential audience accordingly.

3. Publishing a single game from the same codebase.

For years, developers had leaned on C++ as a cross platform solution to making games that work across multiple platforms. A successful port could be anything above 50% core reusability. I still know developers who build their own game engines that allow them to manually port from platform to platform but that process can be time consuming and if you are a small indie developer, the additional bug testing time may not possible to maintain across all the devices you want to support. That is why it is critical to find a cross publishing solution you feel comfortable with.

The most popular game engine today for indies is Unity 3D. From there other solutions, which grow in complexity, are Unreal Engine, CryEngine. There also some smaller more specialized game engines like GameMaker Studio. If pre-built game frameworks are not your thing, consider some cross compilers like HaXe, Monkey and CocoonJS. Either way there are many options and each will have some kind of impact on your end result or the platforms you can reach so do your research while designing your game.

4. Saving State Across Devices

What good is having a game that can be played on multiple platforms but the player needs to restart their progress every time? A key component to the responsive game design concept is allowing a single game session to extend across different devices allowing your player to start on one platform and continue on another. Imagine being able to play a Fire TV game at home then continuing your game on the go on any mobile device?

Steam was one of the first game publishing platforms to introduce cloud based game saving and since then more companies have offered similar solutions. The biggest issue is that these services are platform specific. For a developer to support different platforms, they would have to roll their own solution. However, built into our GameCircle API is WhisperSync, which can be used to not only have cross platform leaderboards but also sync game data across different mobile devices.

By adding GameCircle’s WhsperSync to your game, you can leverage this to let your players go from mobile (iOS, Android and FireOS) to the Fire TV for the full 10-foot experience then sync their game data back across all of these devices. While GameCircle doesn’t support PC syncing today, being able to have a consistent saved game mechanism for your mobile and Fire TV builds is a huge advantage for your players and a step in the right direction.

Where Do We Go From Here?

While this is just the foundation for a larger concept in game design, it’s up to you as the game designer to help define and shape the future of what gaming on multiple platforms means to the player. At Amazon we are incredibly focused on the customer and we build tools to help you as the developer serve them better. Over the next few years we will see more and more games that reach across platform walls to enable a gamer to pick the device and play style they want and with the correctly designed game, that player will have the same experience no matter where they choose to play your game.

Resources:

• GameCircle https://developer.amazon.com/public/apis/engage/gamecircle
• Amazon Fire TV https://developer.amazon.com/public/solutions/devices/fire-tv
• Publishing to Amazon Appstore https://developer.amazon.com/public/support/submitting-your-app

- Jesse Freeman (@jessefreeman)

Player engagement is the key to success for most mobile games, and Amazon GameCircle is designed to help developers increase engagement through player Achievements, Leaderboards, and game data synchronization. We recently added two new features: (1) expanded player profiles with cross-game experience points, called XP, which allow players to track and share their total play time and (2) GameCircle-created achievements across multiple games, called Badges, which enhance players’ overall GameCircle Profile.  Players will enjoy these features as they offer new reasons to revisit favorites as well as incentives to try new games.

Your GameCircle-enabled game now helps players build their public reputation with their friends and the GameCircle community, an advantage over games without GameCircle enabled. The new GameCircle Badges help new players discover your game and re-engage existing customers as they return to satisfy the requirements associated with your game.

Longer Play Time with Experience Points

If your mobile game integrates GameCircle, then your players will automatically earn Experience Points (XP) for the time they spend playing your game; no changes are required to your code. In addition, each achievement in your game now carries an XP reward from 0 to 100 that you specify, up to a total of 1,500 XP for the entire game. We recommend allocating no more than 1,000 XP when launching a new title, leaving at least 500 XP for future expansion in case you add more achievements later. You can change XP allocation at any time for draft achievements, but once an achievement is published, its corresponding XP value is fixed for good.

By earning experience points through playing your games, a player increases their GameCircle Level compared to their peers. GameCircle Level increases steadily as players earn XP for spending time and unlocking achievements in GameCircle-enabled games. For current players with an existing GameCircle account, Amazon has already given them XP, and the appropriate GameCircle Level, based on the achievements they unlocked in the past. New players joining after today will begin at Level 1.

Integrating GameCircle into your mobile game benefits your players, who automatically receive more XP the longer they play. If you take advantage of the GameCircle Achievements service, your game becomes eligible for cross-game badges which offer even more opportunity for players to advance.

Badges Mean More Discoverability

In addition to Experience Points, GameCircle also includes new support for special Badges. Badges are cross-game achievements awarded by GameCircle. These are earned by completing challenges associated with unlocking specific achievements in select games of similar type or in a particular game genre. Up to three badges can be displayed on the player’s profile so he or she can show off favorites earned so far.

For example, players can earn the Zombie Killer badge for unlocking certain achievements in three zombie-related games. Similarly, the Burning Rubber badge is awarded for unlocking specific objectives in two driving games. At launch, there are close to forty special badges available.

Zombie Killer         Burning Rubber

For players who don’t know your app (but have played similar titles), genre-spanning Badges or Badges connecting similar achievements in other games may serve as an introduction to your product. Existing customers may rediscover your game as they explore Badges in game categories that intere them.

GameCircle: Designed to Increase Engagement

GameCircle has always offered Achievements, Leaderboards, and game data synchronization through Whispersync for Games. With these updates to the player profiles—including Achievement XP, GameCircle Level, and Badges—players can easily track and compare their progress across all GameCircle-enabled games.

GameCircle is designed to increase player engagement, improve retention, and enhance the customer experience when playing mobile games on iOS, Android, or Fire OS. For more information about player profiles mobile development, see our online documentation:

• GameCircle Achievements, Leaderboards, and Whispersync for Games
• Cross-Platform Solutions for Android, iOS, HTML5, and More
• Mobile Game Development with Amazon

-peter (@peterdotgames)

Note: Effective 08-26-2015 Free App of the Day (FAD) has been replaced with Amazon Underground.

Reviving the Classics

DotEmu is a Paris based company that specializes in breathing life into classic games on modern platforms founded by Xavier Liard and Romain Tisserand. After being established in 2007, they quickly made a name for themselves  as a developer with well received ports of games like Square Enix’s Final Fantasy VII and VIII for Steam, SNK Playmore’s titles such as Metal Slug 1,2,3,X and King of Fighters 97. More recently, DotEmu became a publisher as well and released popular brands such as Double Dragon, Another World, R-Type and Raiden. They have been moving to mobile and chose to publish their Android based ports on the Amazon Appstore.

I was a huge fan of these games growing up so getting the chance to find out how DotEmu was finding success on the Amazon Appstore was a personal thrill.

Rising to the Top of the Charts

DotEmu’s first game in the Amazon Appstore, R-Type, quickly reached the number #2 spot on our best-selling apps list. While DotEmu has had similar success on multiple platforms such as iOS, Android, Desktop and more, they said “we consider Amazon as the best alternative to Google Play in terms of revenues for the Android platform.” Now with seven games in the store including Double Dragon Trilogy, Raiden Legacy, Another World and The Last Express they are continuing to release just what classic gamer fans would love.

Screenshot from R-Type on the Kindle Fire

With so many games being released for the Amazon Appstore, DotEmu tackled the problem from the top down. “From a business perspective we needed to make sure all the costs associated to the publishing of our games on Amazon were below the revenues we could expect.” But this all comes down to an important question on how you can manage the time investment for supporting a new platform like Fire OS and maximize the return on investment  (ROI) at launch.

Integrating GameCircle into an Existing Codebase

DotEmu’s Android games are built with Cocos2d-x on top of their own custom technology with features to handle multiple achievement/score API support, controllers support and more. When approaching the way to integrate Amazon’s GameCircle API into their existing codebase, DotEmu took a forward thinking approach. They spent the time upfront to integrate the GameCircle API correctly into their framework. While this integration initially took them two weeks for their game engine, it now takes only a few days per game thanks to the effort they initially invested upfront. With this quicker development time plus an additional 1-2 days of QA time for each new port, DotEmu can now easily bring additional games over to the Amazon Appstore that offer the extra features that GameCircle provides.

After receiving a few thousand purchases per game released on the Amazon Appstore, DotEmu is already seeing a return on their time invested. That means moving forward, any additional release with GameCircle support is immediately profitable after launch given the upfront work the put in early on. But there’s more to being successful in the Amazon Appstore than just the time that goes into integrating our APIs.

Working Closely with Amazon for Launch

Marketing your game in the store makes all the difference and DotEmu took advantage of working with our editorial team to create the biggest impact they could at launch. “Amazon is [a] very efficient [way] to advertise our games to the gamers liking retro games.” said DotEmu. In addition since the team didn’t require much help with the porting process, they were able to focus more on the marketing side things.

The good news is that this sort of help form Amazon isn’t reserved for top publishers. Any developer can apply for our Free App of the Day (FAD) promotion to work directly with us to help promote your game and gain brand awareness once you are accepted into the program.

Premium Pricing Still Works

So how did the team do? According to DotEmu, they “generated between 10.000€ and 50.000€ of net revenue on the Amazon Appstore in total”, all of which came from premium priced apps (as opposed to in-app products or advertising). Of course it helps to have a game with a recognizable brand for customer loyalty but it also depends immensely on the quality of the end product. The experience has been a success for DotEmu as they received a positive return on their investment in getting their first game into the Amazon Appstore.

By taking the time to implement Amazon’s GameCircle APIs in a way that supports future projects they can now release games with deeper integration on the platform and continue to increase their ROI. “The way to be successful with Amazon is to really think about long term business relationship and not to just release one game and pray for results without any support from the Amazon team.” according to DotEmu. This way of thinking is true about any platform, not just ours.

Let Us Help You Succeed

The audience for retro gaming is growing in the Amazon Appstore and with the help of great partners like DotEmu we are helping expand that category and open it up to our user base. We can’t do it without more great games like the ones being produced by DotEmu so keep them coming and take advantage of our platform’s unique APIs such as GameCircle as well as marketing opportunities like FAD to help grow your audience.

Screenshot from Another World on the Kindle Fire.

According to DotEmu “Today getting noticed in the digital world is extremely difficult and we can bet it will be more and more difficult in the future” which is why they also went on to say that “building up a long term business relationship with Amazon is consequently a no-brainer”.

Additional Resources

For more resources on publishing Android games to Fire OS, integrating with GameCircle and the FAD program, check out the links below:

• GameCircle - https://developer.amazon.com/appsandservices/apis/engage/gamecircle
• Free App of Day Program - http://developer.amazon.com/public/resources/promotional-tools/free-app-of-the-day
• Android/Fire OS - https://developer.amazon.com/public/solutions/platforms/android-fireos

- Jesse Freeman (@JesseFreeman)

Founded in 2011 Pixowl, Inc is a mobile games developer headquartered in San Francisco, CA. With the success of its four iOS games, The Sandbox, Greedy Grub, Doodle Grub and Safari Party, Pixowl has made a name for itself in casual mobile games.  Their game, The Sandbox, is a unique world-building and crafting game in 2D with touch controls and access to over 150+ physics elements. Players can craft amazing worlds, create pixel art, chiptune music, electric circuits or just play with physics.

I had a chance to sit down with Sebastien Borget, COO and Co-Founder at Pixowl and ask him about Pixowl’s experiences porting The Sandbox to the Kindle Fire, what type of success Pixowl has seen in the Amazon Appstore, and what it was like implementing many of the APIs available in the Amazon Mobile App SDK.

Betting on the Amazon Appstore pays off

“We have built with Amazon an improved version of The Sandbox which is deeply integrated with Amazon’s GameCircle service for a more seamless experience on Kindle Fire.” – Sebastien, Pixowl

Pixowl was able to submit The Sandbox early on in the Amazon Appstore’s launch.  “We were present at an event organized by Amazon UK to present other developers success stories on the Amazon Appstore.  While it was still in an early stage of maturity we were really impressed by the performance the apps had already seen there. This convinced us we had to be among the early movers and adopt a cross-platform strategy fitted for each partner.  Now, we couldn’t be happier about this decision as the Amazon team has held all of its promises and has been over achieving for us.” recalls Sebastien.

For the Kindle Fire version of The Sandbox, Pixowl decided to integrate Amazon GameCircle allowing a more seamless experience.  GameCircle is a free, cross-platform API from Amazon that provides everything you need to implement achievements, leaderboards, and saved game syncing across any device, regardless of mobile platform. Once you integrate GameCircle, customers can play and interact with other gamers across any mobile device.

“Amazon is proving that Android users could be as engaged with games as on other platforms and made it worth considering alternative distributions models, with  a huge revenue potential.” – Sebastien, Pixowl

“For us, the decision making process was relatively easy. On a business perspective, we wanted to make sure that the platform had enough of our core audience: kids and casual players, from 5 years old to 20+ .  On the technical side, we had to check what level of compatibility with existing Kindle models was, evaluate the adaptations required and make sure we could provide the best game experience on the devices.” says Sebastien.

Quick porting process and easy Amazon Mobile App API integration

Pixowl already had an existing Android version of The Sandbox so moving to the Amazon Appstore was relatively quick.  “The overall porting process took us 2 weeks maximum including development and testing. We are developing in C++ with Cocos2DX and everything worked almost seamlessly.” says Sebastien.

The Sandbox follows the “freemium” monetization model; a free download to all Amazon customers the games utilizes Amazon’s In-App Purchasing API to unlock additional campaigns of level or acquire elements faster.

The API offers a completely Amazon hosted checkout experience to customers and integrates fully with their Amazon account.  They can choose to utilize their 1-Click purchase settings as well as Amazon Coins which now work on both Android and Kindle Fire devices.

According to Pixowl the Amazon Appstore represents 5% of the total downloads volume from all Android marketplaces, but over 20% of their total Android revenues. Some days, it’s could be as high as 50%!   “That’s very close to the performance we’re seeing with Apple iOS!” says Sebastien.

According to Pixowl Amazon is proving that Android users can be as engaged with games as on other platforms.  It made it worth Pixowl considering alternative distributions models, with a huge revenue potential.  “Success is no longer determined just by the amount of downloads, but by their quality. Go for the full experience with Amazon.  It’s really worth it!” says Sebastien.

You can check out The Sandbox in the Amazon Appstore here.  You find out more about the Amazon In-App Purchasing API here and the cross-platform GameCircle API here.

-Dave (@TheDaveDev)

Reaching More Customers and Making More Money Per User

In a previous case study, you heard about the tactics that Big Blue Bubble uses to monetize their free to play (F2P) games. In this study, we’d like to share how June Software increased their app exposure by going from an iOS-only producer to an iOS and Android platform producer, and how their presence in the Amazon Appstore has racked up higher Average Revenue per User (ARPU) than any other app store.

June Software is a small San Francisco based software company founded in 2008. They build casual, arcade games and e-learning games for children. Initially June Software only built games for iOS where they have titles such as Math vs. Zombies and Guess the Movie, which is ranked #3 worldwide and is #1 in Australia.

June + Unity + Amazon Appstore = Less Friction, More Revenue

To grow their customer base, June Software decided to address the Android marketplace. June chose to port their iOS games to Android using Unity. Unity allows them to build their app once and deploy it to multiple app stores, including the Amazon Appstore.

When we asked about their experience on Amazon apps store, June Software Director Products Saurabh Jain said:  “On Amazon, we have seen 2x times the ARPU [we see] from Google Play, and 1.2x [more than] than Apple AppStore. The overall downloads aren’t there yet, but the revenue makes it a very good market for us.”

Increasing Time in Games Increases Potential Income

One effective strategy that Saurabh implemented is that they have integrated Amazon IAP and GameCircle features in their games, which increased potential revenue and player engagement. GameCircle includes features such as leaderboards and achievements that keep players engaged and can increase user session time and session frequency, giving uses more opportunities to make IAP purchases. And it works on Android and iOS. This is exactly what June Software needs for their games available for both platforms.

What can you do?

• To learn more about using Amazon GameCircle in your Unity apps, read this blog post and refer to this documentation.
• To learn more about using Amazon In-App Purchasing in your Unity apps, read this documentation. To see how Mad Menace Games used the Amazon IAP Plug-In for Unity, read this post.
• For additional information on Amazon Unity Plug-ins, read this. 

If you develop apps or games with Unity, you may already be using Amazon’s GameCircle plug-in for Unity to integrate cross-platform leaderboards, achievements, and game data synchronization.  The plug-in works on iOS, Android, and Fire OS, connecting your app to Amazon’s GameCircle service.  Its leaderboards and achievements encourage friendly competition and replay, while its Whispersync for Games component backs up game data to the cloud, improving the customer experience.  With GameCircle, gamers won’t lose their progress if they reset their device or buy a new one.

If you haven’t used the GameCircle plug-in yet, you can now download it from the Scripting/Integration section of the Unity Asset Store.  Accessible directly from within the Unity development environment, the Unity Asset Store makes it fast and convenient to add editor or game functionality through third-party extensions like the GameCircle plug-in.

This official GameCircle plug-in is compatible with iOS and Android phones and tablets, as well as Kindle Fire, Kindle Fire HD, and Kindle Fire HDX devices.  Add the plug-in to your project to access GameCircle leaderboards, achievements, and Whispersync for Games.

In addition, the GameCircle plug-in also works with the Unity Social API, which provides a unified interface to social back-ends such as Game Center and Xbox Live.  Set the active social platform to GameCircle and calls to the Unity Social API will pass through to the GameCircle service in the same way:

#if UNITY_IOS || UNITY_ANDROID
Social.Active = GameCircleSocial.Instance;    
#endif

Since Unity’s Social API is designed to be a generic interface that works across many services, it doesn’t support every feature of every back-end.  GameCircle leaderboards and achievements work seamlessly, for example, but Unity’s Social API provides no hooks for game data synchronization.  To use some advanced features of GameCircle, like Whispersync for Games, simply call the API through the normal GameCircle interface.  It’s easy to use the two APIs side-by-side, and the plug-in includes a sample scene to help you get GameCircle and Unity’s Social API up and running together.

Check out the official GameCircle plug-in in the Unity Asset Store.  It’s easier than ever to get started integrating GameCircle’s leaderboards, achievements, and Whispersync for Games in your Unity-based game for most mobile devices.  You can also visit our developer portal for more detailed information about using GameCircle and Unity together, as well as links to help you call other Amazon services from your Unity projects.

Adobe AIR Native Extensions for the In-App Purchasing and GameCircle APIs are now available for mobile app developers. If you create your mobile games using Adobe’stools, you can now use these extensions to rapidly add both In-App Purchasing for virtual goods and GameCircle for leaderboards, achievements, and Whispersync for Games.

The Adobe Gaming SDK enables developers to package ActionScript code into native apps for Kindle Fire, along with other devices. The Gaming SDK and the Adobe Game Developer tools are designed to help developers create rich,interactive experiences expertly and efficiently, supporting popular features such as hardware-accelerated graphics.

The new AIR Native Extensions are available today for free as part of the Amazon Mobile App SDK. You can download the latest version here. Just follow the simple instructions in the documents to get started. Of course, you’ll also need AIR in order to use the extensions.You can learn more about the Adobe Gaming SDK and Adobe Game Developer Tools  here.

We recently released an update to the Amazon Mobile App SDK that includes improvements to GameCircle and some related components on both Android and iOS. It updates GameCircle’s dependency on the latest version of Amazon Insights, corrects a few bugs, and expands API coverage of the Unity3D plug-in. For all of these reasons, we recommend migrating to the latest SDK when convenient.

Both GameCircle and its Unity3D plug-in now take advantage of the latest version of Insights, part of Amazon’s Analytics service and the piece responsible for generating Achievements Reports. Insights SDK on iOS removed a dependency on CoreTelephony.framework, while the Android version corrected an issue specific to certain device Locales and improved support for other IAP frameworks. In addition, session timeouts now behave more consistently across platforms.

GameCircle initialization has also been optimized on both iOS and Android, and GameCircle now ensures that its Javascript components are updated when migrating to a new version of the SDK. The Unity3D plug-in supports the latest Whispersync for Games syncable type, DeveloperString, which should make it easier to store arbitrary, non-mergeable game data from your Unity3D game. The plug-in also exposes the ability to show the GameCircle sign-in page.

Check out these latest changes to the SDK, and watch this space or future updates. We’re always working to improve performance, usability, and reliability of our services for mobile apps and games.

Amid all the hoopla around GameCircle’s expansion to iOS and a major update to Whispersync for Games, you may not have noticed two other powerful features were also released recently. The GameCircle team quietly added support for bulk creation of leaderboards and achievements on the Mobile App Distribution Portal, as well as the ability to internationalize them in up to eight languages besides US English. Both have been popular feature requests.

Internationalization means that GameCircle will display the title and description of your leaderboard or achievement in the language appropriate to your player’s locale, provided they have specified it in their mobile device settings. You can provide translated descriptions in any or all of these languages:

You enable these alternative versions by selecting them from the Add a Language dropdown list on the Leaderboard or Achievement view for your game. To view your game’s leaderboards, for example, go to the GameCircle configuration page and follow the View link in Leaderboards column.

Adding an additional language is not reversible, but you specify which ones to publish, so there’s no harm done if you change your mind or add the wrong one: simply don’t publish that version of the title and description.

Once you add a language, you will see a new corresponding line item for each leaderboard or achievement, which is independently editable.

Providing alternative versions for each title and description, while straightforward, may become unwieldy when you are translating for a lot of locales, or just have lots of leaderboards or achievements. In fact, as the number of leaderboards and achievements goes up, entering all of the other information required to create them definitely makes manual entry time-consuming.

This is where GameCircle’s new bulk upload facility becomes really handy. Rather than create each achievement individually, for example, you can create a file of comma-separated values (CSV) defining all of your achievements at once. From the list of Achievements for your game, click the Bulk Add Achievements button.

On the page that appears, download a CSV template via the click here link. Open the template and fill in the columns as appropriate, then save it locally. See the Create Multiple Achievements section of Implementing Achievements for more information on each column. You will notice, for example, that there are separate columns for each possible translation of title, locked description, and unlocked description. Icon ids for locked and unlocked versions of the achievement are shared across all languages.

Before you can upload the CSV file defining your achievement (or leaderboard) metadata, however, you must upload the icons it refers to. GameCircle provides an Icon Gallery for this purpose, which allows you to add, delete, and rename icons individually or by dragging and dropping them on a web page. You can view the Icon Gallery for your game from the GameCircle configuration page. See Using the Icon Gallery for more information.

Once the icons have been saved and the CSV file updated to reflect your achievement metadata, you’re ready to upload. Click Choose File and navigate to the file you just edited, and then upload it.

Mobile apps and games distributed through the Amazon Appstore for Android are available in nearly 200 countries worldwide, and now GameCircle allows you to provide title and description translations for several of them. Entering the metadata that defines your achievements and leaderboards also got easier, now that you can upload it as a CSV file. Added in response to developer feedback, these features were designed to complement each other and make working with GameCircle fast and simple.

Amazon GameCircle and the other game services we offer are designed to make mobile game development easier, but knowing where to start may still be difficult. To offer a bit of guidance, I thought it might be worthwhile to take a small, simple game and walk through the process of extending its functionality, one service at a time. Together we’ll gradually add features over the course of several posts, each one focusing on a specific way Amazon services speed development or reduce code complexity. At the end of the series, we’ll have a working game application that shows these services in action and demonstrates how you might incorporate them into other projects.

As the title implies, this post will kick off the series with a look at GameCircle, which supports leaderboards, achievements, and Whispersync for Games, a powerful mechanism to synchronize local and cloud data. Games have been saving progress and celebrating player success since the beginning, so GameCircle seems like a good place to begin our journey.

Prerequisites

Note that this blog series assumes that you are comfortable developing for Android using Java and Eclipse, and that your development environment is set up and working properly with the Android Developer Tools (ADT). Some Amazon services are available only on Kindle Fire, so that will be our target device throughout the series. You must install the Kindle Fire SDK add-ons in order to use those features. For more information, see the Get Started section of Kindle Fire Development Resources.

Importing the Monster Tag Project

Before we begin, we need a simple game that will serve as the base for our experimentation and improvements. Monster Tag displays a horde of monsters and asks the player to tag them as they bounce around the screen. Every time a monster is tagged, it gets startled and speeds off in another direction. The faster a monster is moving when it’s tagged, the more points are awarded to the player.

To import the Monster Tag project into Eclipse, download and extract the source bundle to a convenient location, then choose File | New | Project… from Eclipse’s main menu. Expand Android and select Android Project from Existing Code, then click Next. 

Click Browse… to navigate to the temporary location where you extracted the source code, then click OK. Check Copy projects into workspace and click Finish. 

Once the project has been loaded successfully, you will see it in the Package Explorer:

Launch the application in the debugger for the first time by selecting the MainActivity and choosing Run | Debug As | Android Application from Eclipse’s main menu. You should see a lot of little orange guys flying around, daring to be tagged.

Establishing Trust

We have a basic game application running, but we’re still not ready to integrate GameCircle and use it to track high scores online. The GameCircle service won’t accept connections from just any mobile application—it authenticates requests to ensure they’re coming from trusted apps. Every app or game that wants to access GameCircle (and some other Amazon services) must have an “API key,” which is associated with a security profile for that app. The key tells GameCircle that our app is trustworthy.

To establish a security profile and obtain an API key, we must first let Amazon know about our game, which we do on the Mobile Application Distribution Portal. Sign in or create a developer account there if you don’t already have one. (If you’re creating an account for the first time, you’ll be asked to supply some basic information and agree to some terms and conditions. If you intend to create paid apps, you’ll have to provide some extra info, as well.)

Once you’ve logged in, go to the Apps & Services tab and hover over the Add a New App drop-down, then select Add new Android App. Now we can tell Amazon the details of our game:

Generating a Security Profile

After clicking Save we could add more details, such as pricing, icons, and screenshots, but for now we’ll skip those steps and jump right to creation of a security profile. Follow the Security Profile link that appears under the app title on the next screen, then click the Create a New Security Profile button.

You’ll be asked to name the security profile. Note that you can share security profiles between applications, which we’ll discuss in a later post. For now, we’ll assume only Monster Tag will use this one, so we’ll name it accordingly:

Creating an API Key

Now we have a security profile, but no API key has been associated with it yet. Follow the API Keys link that appears after the profile name, then fill in the required fields and click Generate.

NOTE: What you enter in the signature field, below, will depend on your own development environment; you must supply the MD5 signature of your own debug keystore. You can find information about obtaining this value in the Debug application signature section of Getting Your OAuth Credentials and API Key. Typically this involves using keytool (installed as part of the JDK) from the command line:

keytool -list -v -alias androiddebugkey -keystore /path/to/debug.keystore

You should be asked to supply a password, which is “android” by default (no quotes). Check the output for the MD5 signature, highlighted below:

...

Certificate fingerprints:

         MD5:  D4:81:0C:AA:3D:45:DE:45:59:F2:BE:DE:95:A8:E1:65
         SHA1: A1:DF:DD:0D:89:77:81:24:E0:AF:47:AA:B6:55:B6:14:58:7D:4C:E4
         SHA256: 5:50:7F:6F:43:2C:3E:CD:D6:46:F1:F7:96:F2:ED:DE:E8:DD:3A:53:00
         Signature algorithm name: SHA1withRSA
         Version: 3

Adding an API Key to an Eclipse Project

Generating the API key will result in a long base64-encoded string. This is the magic value we need to include in our project to identify our app as trustworthy.

To add it to the project, create a new file called /assets/api_key.txt and paste in the value. Note that api_key.txt must be located in the /assets subfolder.

Enabling GameCircle Data for a Security Profile

Next, we must indicate that there will be GameCircle data associated with the security profile we just created, and that our Monster Tag game will use it. Go to the GameCircle configuration page, select the security profile we created and click Confirm.

Connect a Security Profile to the App

To connect our game to the correct GameCircle data, go to the My Apps tab of your profile, click the Monster Tag app, then follow the Security Profile link. Click the Monster Tag radio button and confirm the action by selecting Apply Profile on the dialog that appears.

Next Steps

Success! Our app is registered with Amazon, there’s a security profile associated with it, and we generated a corresponding API key and added it to our project. We’re ready to use GameCircle and it’s ready to accept requests from our mobile application.

In the next installment of this series, we’ll use GameCircle’s built-in leaderboard functionality to track high scores and let users compete with each other. Now that we have the app and security bookkeeping out of the way, it will be a cakewalk.

Following up on the second in a series of webinars covering Amazon devices, game services, and mobile applications, here’s a list of questions we collected during and after our presentation on Amazon GameCircle, including Achievements, Leaderboards, and Whispersync for Games.

Does the developer have access to the GameCircle nickname?

Yes, you can call getLocalPlayerProfile(), which returns a structure containing player id and player alias (same as nickname/username). NULL is returned if the player is in guest mode (they have not logged in). Player id is unique for each player.

When updating Achievement Progress can you decrement it as well or does the GameCircleCient hold onto the latest highest progress value?

Achievement progress is strictly increasing, which means updates must be greater than the current value or they’ll be ignored. Note that you can reset achievement data for draft achievements (those that have not yet been published).

With the update, does GameCircle still support Kindle Fire 1?

Yes. The GameCircle system app must be updated to v1.1_1101110, however. This should have been delivered OTA. On KF2, the GC system app should be v2.5.2500310 or greater.

Can leaderboards/achievements be translated?

Not yet, but localization is in development and will be available in a future release.

Is the same game discovery mechanism on Kindle Fire available on all Android devices as well?

The dedicated Games Tab is built in to the games library on Kindle Fire only. It’s not available on other Android devices.

What is the minimum OS supported?

GameCircle supports API level 10 up to API level 16 on all Android devices.

Is GameCircle available internationally?

Yes, GameCircle works internationally. Players in China are limited to Guest mode for now, due to data storage requirements imposed by the Chinese government, but we will address that in a future release.

Is the old version of GameCircle still supported?

Yes, for legacy games. Games that have been published using GameCircle v1.x will continue to work. If you had a game in development when GameCircle v2.0 was released, you can proceed to publish it using the old version. Since the Mobile App Distribution Portal no longer provides direct support for GameCircle v1.x app whitelisting, however, you must contact us to add or update package name/signature pairs. See the Whitelisting Notice on the GameCircle configuration page for more information.

What happened to the FileSync and BlobSync from Whispersync?

We greatly simplified the Whispersync interface to make it easier to integrate and expand auto-resolution of data conflicts. As a result, we dropped support for the blob and multifile sync options. They were complicated to integrate and forced the developer to manually reconcile data on occasion (or to ask the customer to do so). The new Whispersync requires significantly less integration overhead and provides a better customer experience in most cases.

Can I migrate old Whispersync data to the new format?

Yes, there are two methods on the WhispersyncClient that can help in the migration process. migrateVersion1GameData() and unpackVersion1MultiFileGameData() will download and unpack data stored using the previous version, respectively. They’re only meant to be used by games that integrated Whispersync prior to July 1, 2013. See the Javadoc for more info.

Is there any way to integrate game circle in Air apps?

Amazon provided an Adobe Native Extension (ANE) for GameCircle v1.x, but none is yet available for the new version. We are actively researching an upgrade to the existing ANE, but don’t have an official timeline. Check back here or follow @peterdotgames for updates on the availability of a new ANE. In the meantime, you can continue to the existing extension with GameCircle v1.x for games currently in development.

Where can I learn more about Unity plugin for game circle?

Check out the Amazon Unity Plug-Ins page on the Amazon Mobile App Distribution Portal.

Do users need to login with Amazon account username and password to use the game services?

No, GameCircle now supports a Guest Mode for users who don’t want to log in to an Amazon account. In this case, data will not be synchronized to the cloud or across devices.

Is there a good game to play to check out the features?

There are many great games that include GameCircle features, including well-known blockbusters and high-quality indies. In the Amazon Appstore, look for the GameCircle badge to quickly identify games that use Achievements, Leaderboards, or Whispersync for Games.

Don’t miss out next webinar event: How to Integrate Amazon Mobile Ads and Lift Your App Revenues 
on August 15th, 2013 @ 10:00 AM.

Pre-register here!

Save game data in the cloud to protect your customers’ progress and support play from multiple devices

In just a few short years, the explosion in popularity of smart phones and tablets has transformed gaming, as touch controls, geolocation, and micropayments enter the mainstream. Online storage is also becoming more common, as developers adjust to a major challenge of mobile devices: physical durability. Keeping your data in the cloud starts to look mighty attractive compared to keeping it on a device that’s easily misplaced, damaged, or stolen.

Blob storage is a common way to save data online (game data is simply written to the cloud as one big chunk). If two devices update the same data, though, one of the updates must be ignored or overwrite the other. You have to decide which update to keep (based on a timestamp or version number, perhaps), or maybe prompt the user to choose between them. Either way, data is lost.

Because of the overhead involved, many developers don’t even bother with this naïve approach. This is a huge disservice to the player, whose game progress is completely lost if anything happens to his or her mobile device. Whispersync for Games saves game data for you, and works across all Android devices (including Kindle Fire).

Mergeable and Non-mergeable Data

Whispersync was designed to prevent data loss, make developer or player intervention unnecessary when resolving conflicts, and be dead-simple to integrate and use. It doesn’t distinguish between online and local storage, so the programmer doesn’t have to handle separate cases for saving to disk and cloud. It does this by manipulating only mergeable data.

Game data is mergeable if a simple rule can be defined to resolve conflicting values. For example, the rule associated with the best completion time might be, “Take whichever value is smallest.” To keep track of a player’s best score, we might use, “Take whichever value is highest.” In some cases, the most recent value may be the most important, so the appropriate rule would be, “Take whichever value is newest.” These rules apply at a granular level; Whispersync doesn’t treat game data as one big chunk.

Not all game data can be resolved using simple rules, though, in which case we call it non-mergeable. The current state of a chess board, for example, requires a complex tree structure to describe it. Reconciling two versions of the board is more complicated than just choosing the “lowest” or “highest” one.

Describing Game Data Using Syncable Types

Fortunately, a lot of game data is naturally mergeable or can be adjusted to be so. Whispersync offers many different syncable types with several built-in rules to resolve conflicts. They can be used to model simple and complex game data.

• SyncableNumber – A number that is the lowest, highest, or most recent.
• SyncableString – A string that is the most recent.
• SyncableAccumulatingNumber – A number that can be incremented and decremented.
• SyncableNumberList – A list of numbers in ascending, descending, or latest order.
• SyncableStringList – A list of strings ordered by most recent.
• SyncableStringSet – A set of strings.
• GameDataMap – A nested map, allowing hierarchical data.

A global GameDataMap object represents the root storage for your game, storing named values of the types above. Setting a value that doesn’t exist will create it on the fly. The accessor used to retrieve a value determines the conflict resolution strategy that will be associated with it.

  public static final String SKILLS = "skills";
  public static final String TOTAL_TIME = "totalTime";
  public static final String LEVEL_MAP = "levelMap";

  public static final int NUM_LEVELS = 5;
  public static final int MAX_ITEMS = 3;

  public static final String SCORE = "score";
  public static final String STARS = "stars";
  public static final String BEST_SCORES = "bestScores";
  public static final String BEST_TIMES = "bestTimes";

  GameDataMap gameDataMap;

  public void initGameData() {
    gameDataMap = AmazonGamesClient.getWhispersyncClient().getGameData();

    // These will be independent of level.
    gameDataMap.getStringSet(SKILLS);
    gameDataMap.getAccumulatingNumber(TOTAL_TIME);

    // Use nested maps to establish some per-level values.
    for (int i=0; i < NUM_LEVELS; i++) {
      GameDataMap levelMap = gameDataMap.getMap(LEVEL_MAP + i);

      // Each level will have its own copy of these values.
      levelMap.getLatestNumber(SCORE);
      levelMap.getHighestNumber(STARS);
      levelMap.getHighNumberList(BEST_SCORES).setMaxSize(MAX_ITEMS);
      levelMap.getLowNumberList(BEST_TIMES).setMaxSize(MAX_ITEMS);
    }
  }

In the example above, we use initGameData() to establish the structure of the data we’ll synchronize, even though we don’t actually set any values. (It can be helpful to define the data layout in one place like this, even if it’s not strictly required.) The code effectively says,

• There will be a global set of strings called SKILLS. It will track every string added to it (strings may not be removed).
• There will be a global running total of time in the game called TOTAL_TIME. It will accumulate deltas submitted from all devices used by a single player.
• There will be NUM_LEVELS nested maps, each of which will have its own set of values:
  • SCORE will always reflect the last score submitted for that level.
  • STARS will always reflect the maximum stars attained for that level.
  • BEST_SCORES will always list the MAX_ITEMS highest scores for that level.
  • BEST_TIMES will always list the MAX_ITEMS fastest times for that level.

Updating and Retrieving Game Data

Whispersync abstracts all game data persistence, so we can update or retrieve values using simple getters and setters. We don’t have to worry about managing a network connection, saving to disk or the cloud, or reconciling local and online versions of variables we have in memory. When we add to the running total of time played, for example, Whispersync automatically saves the delta to disk and updates the cloud if connected. If the player’s device is currently offline, the update will be queued and delivered later.

  public void updateTotalTime(int timePlayed) {
    SyncableAccumulatingNumber totalTime = gameDataMap.getAccumulatingNumber(TOTAL_TIME);

    // Add the time played to the running total.
    totalTime.increment(timePlayed);

    // Output the new total to the console.
    System.out.println("Total Time Played = " + totalTime.asInt());
  }

Likewise, we can record skills as the player masters them and easily iterate over the set to display the ones learned so far:

  public void learnSkill(String skill) {
    SyncableStringSet skillSet = gameDataMap.getStringSet(SKILLS);

    // Add the new skill to the player's repertoire. Note that this list

    // can only expand; strings cannot be removed.
    skillSet.add(skill);

    // Output all skills to the console.
    for (SyncableStringElement s : skillSet.getValues()) {
      System.out.println("Skill = " + s.getValue());
    }
  }

Updating numbers and number lists is just as straightforward, so persisting all of the player’s progress at the completion of a level can be done in just a few lines:

  public void finishLevel(int level, int score, int stars, int time) {
    GameDataMap levelMap = gameDataMap.getMap(LEVEL_MAP + level);

    // Save the score for this level. Newer values will always overwrite
    // previous scores.
    levelMap.getLatestNumber(SCORE).set(score);

    // Try to set the new maximum stars attained on this level. If the
    // value is less than the current maximum, this call does nothing.
    levelMap.getHighestNumber(STARS).set(stars);

    // Try to add this score to the list of all-time bests. If it's not
    // high enough, this update will be ignored.
    levelMap.getHighNumberList(BEST_SCORES).add(score);

    // Try to add this completion time to the list of all-time bests. If
    // it's not low enough, this update will be ignored.
    levelMap.getLowNumberList(BEST_TIMES).add(time);
    updateTotalTime(time);
  }

The accessors on GameDataMap and Whispersync’s syncable types make it easy to manipulate game data and define how conflicts should be resolved.

Think Mergeable!

Whispersync for Games automatically resolves conflicts for data it can merge, which makes it worthwhile to describe game data using syncable types when possible. Since Whispersync supports high, low, and most recent numbers and number lists; running totals; latest strings and string lists; sets of strings; and nested maps supporting hierarchical structures, a wide range of game data can be modeled.

Thinking about your game data in mergeable terms lets you push a lot of overhead out of your code. Let Whispersync handle the heavy lifting. For more information on integrating Whispersync into your game, see the online documentation.