extension-googleplaygames: A Haxe repository from Vortelio

#extension-googleplaygames

OpenFL extension for "Google Play Games" on Android.

###Main Features

Achievements (complete, send progress, reveal/unhide, display achievements screen).
Scoreboards (submit scores, display scoreboard).
Login / Init.
Cloud Storage support (for storing progress / scores on google cloud - up to 4KB of data).
Callback events for onCloudComplete (read from cloud) and onCloudConflict (version conflict on cloud).
Callback event for login / init
Automatic conflict resolution (by keeping the newest version by default). You can change that by implementing the onCloudConflict method.
XML Parser to load the ID's from Google's XML resources file.

###Simple use Example

// This example show a simple use case.

import extension.gpg.GooglePlayGames;

class MainClass {

	function new() {
		// first of all... call init on the main method.
		// the boolean parameter is to enable cloud storage service. Note that google and will
		// prompt for that permission to the user the first time.
		GooglePlayGames.init(true);
		// IMPORTANT: If you call init(true) you're enabling Saved Games API, so remember to enable
		// that feature on your google play games console to avoid Runtime Errors.
		// If you don't want to use Saved Games API, just calal GooglePlayGames.init(false);
	}
	
	function login() {
		// to force a login request to the user. This is optional and you may not even call this function
		// at all. Call this just if you want to force the user to login (instead of waiting the user to
		// call displayAchievements or displayScoreboard ...
		GooglePlayGames.login();
	}

	function displayScoreboard() {
		GooglePlayGames.displayScoreboard("your-scoreboard-id"); // to open one specific scoreboard.
		//GooglePlayGames.displayAllScoreboards(); // to show all scoreboards.
	}
	
	function displayAchievements() {
		GooglePlayGames.displayAchievements(); // to display the achievements.
	}

	function submitScoresAndAchievements() {
		GooglePlayGames.setScore("scoreboard-id",234); // to set 234 points on scoreboard (Int data type).
		GooglePlayGames.setScore64("scoreboard-id",234); // to set 234 points on scoreboard (Long data type).
		GooglePlayGames.reveal("achievement-id"); // to make one achievement visible
		GooglePlayGames.setSteps("achievement-id",30); // to set one achievement to progress to 30.
		GooglePlayGames.increment("achievement-id",1); // to increment the progress of one achievement in one.
		GooglePlayGames.unlock("achievement-id"); // to unlock / complete one achievement.

		// Please note that all this functions returns false if the user is not logged into the game.
		// In that case you may want to call "GooglePlayGames.login();"
	}
	
}

###SavedGames API Example

// This example show a simple use case.

import extension.gpg.GooglePlayGames;

class SomeClass {

	function new() {
		GooglePlayGames.onLoadGameComplete=onLoadGameComplete;
		GooglePlayGames.onLoadGameConflict=onLoadGameConflict;
	}
	
	function closeGame(){
		GooglePlayGames.discardAndClose();
	}

	function saveGame(data:String, comment:String="autosave") {
		// Note that google requires that you first open a game before you can modify / save it.
		// So, this will save on last game opened.
		GooglePlayGames.commitAndCloseGame(data,comment);
	}
	
	function loadGame(name:String) {
		GooglePlayGames.loadSavedGame(name);
	}
	
	function onLoadGameComplete(name:String, data:String) {
		trace("Data on saved game: "+name+" is: "+data);
	}

	function onLoadGameConflict(name:String, data:String, conflictData:String) {
		trace("Conflict on saved game: "+name);
	}
	
}

###Login event example

// This example show a simple use case.

import extension.gpg.GooglePlayGames;

class MainClass {

	function new() {
		// first of all... call init on the main method.
		// the boolean parameter is to enable cloud storage service. Note that google and will
		// prompt for that permission to the user the first time.
		// Set up the login result event callback first, always before init()
		GooglePlayGames.onLoginResult = loginCallback;
		GooglePlayGames.init(true);
		// IMPORTANT: If you call init(true) you're enabling Saved Games API, so remember to enable
		// that feature on your google play games console to avoid Runtime Errors.
		// If you don't want to use Saved Games API, just calal GooglePlayGames.init(false);
	}
	
	function login() {
		// to force a login request to the user. This is optional and you may not even call this function
		// at all. Call this just if you want to force the user to login (instead of waiting the user to
		// call displayAchievements or displayScoreboard ...
		GooglePlayGames.login();
	}
	
	function loginCallback(result:Int):Void {
		// The possible returned values are:
		// -1 = failed login
		//  0 = trying to log in
		//  1 = logged in
		// this event is fired several times on differents situations, results vary and must be tested
		// and adapted to your game logic. for example, if you execute init() and login() but the user
		// doesn't login, cancel the operation, it will return: 0 -1 0 -1 , same as if the user is
		// not connected to the internet.
		Lib.trace("Login result = "+result);
	}
	
}

###Get player info and friends example

// This example show a simple use case.

import extension.gpg.GooglePlayGames;
import extension.gpg.Player;

class MainClass {

	function new() {
		GooglePlayGames.onLoadConnectedPlayers = onLoadConnectedPlayers;
		GooglePlayGames.onLoadInvitablePlayers = onLoadInvitablePlayers;
		GooglePlayGames.onLoginResult = loginCallback;
		GooglePlayGames.init(true);
		GooglePlayGames.login();
	}
	
	function loginCallback(result:Int):Void {
		if(result == 1){
			trace("Player ID: "+GooglePlayGames.getPlayerId());
			trace("Player Display Name: "+GooglePlayGames.getPlayerDisplayName());

			// Load invitable friends (people you can invite to play)
			// the boolean parameter (in false here) indicates if you want GPG to clear the players
			// cache. You should only set this to true when the player request a reload manually.
			GooglePlayGames.loadInvitablePlayers(false);

			// Load connected friends (people already connected to your game on GPG)
			// the boolean parameter (in false here) indicates if you want GPG to clear the players
			// cache. You should only set this to true when the player request a reload manually.
			GooglePlayGames.loadConnectedPlayers(false);
		}
	}

	function onLoadInvitablePlayers(players:Array<Player>){
		for(p in players) trace(p.id + ": " + p.name);
		trace("GET "+players.length+" INVITABLE PLAYERS!");
	}

	function onLoadConnectedPlayers(players:Array<Player>){
		for(p in players) trace(p.id + ": " + p.name);
		trace("GET "+players.length+" CONNECTED PLAYERS!");
	}

	
}

###Get player image example

// This example show a simple use case. The method loadPlayerImage retrieves 
// the player image, saves it locally in cache and calls onLoadPlayerImage 
// with the player id and the path of the image as parameters.

//if the id parameter of loadPlayerImage is null, the methods retrieves the image for the current player 

import extension.gpg.GooglePlayGames;
import extension.gpg.Player;

class MainClass {

	function new() {
		GooglePlayGames.onLoadConnectedPlayers = onLoadConnectedPlayers;
		GooglePlayGames.onLoadPlayerImage = onLoadPlayerImage;
		GooglePlayGames.onLoginResult = loginCallback;
		GooglePlayGames.init(true);
		GooglePlayGames.login();
	}
	
	function loginCallback(result:Int):Void {
		if(result == 1){
			GooglePlayGames.loadPlayerImage(null);
			GooglePlayGames.loadConnectedPlayers(false);
		}
	}

	function onLoadPlayerImage(id:String, path:String){
		trace("The path to the image of the player "+id+" is: "+path);
	}

	function onLoadConnectedPlayers(players:Array<Player>){
		for(p in players) loadPlayerImage(p.id);
	}

	
}

###XML Resources parsing example

// This example show a simple use case.

import extension.gpg.GooglePlayGames;

class MainClass {

	function new() {
		// first of all... call init on the main method.
		// the boolean parameter is to enable cloud storage service. Note that google and will
		// prompt for that permission to the user the first time.
		GooglePlayGames.init(true);
		// IMPORTANT: If you call init(true) you're enabling Saved Games API, so remember to enable
		// that feature on your google play games console to avoid Runtime Errors.
		// If you don't want to use Saved Games API, just calal GooglePlayGames.init(false);		
		
		// Google allows you to download an XML file with you IDs related to some alias name.
		// It's a good practice to match your alias from google play games with your alias on game center, to simplify your code.
		var xmlText='......
			     <resources>
				<string name="complete stage 1">CgkI-7SKzbALA2IQAQ</string>
				<string name="kill 100 enemies">CgkI-7SKzbALA2IQBw</string>
				<string name="complete stage 2">CgkI-7SKzbALA2IQAg</string>
			     </resources>';
			     
		GooglePlayGames.loadResourcesFromXML(xmlText);
	}

	function doSomething() {	
		GooglePlayGames.reveal( GooglePlayGames.getID("kill 100 enemies") ); // to use an alias name instead of the ugly ID
	}

}

###Get player score example

// This example show a simple use case whit the method getPlayerScore.
// Explanations whit the methods getCurrentAchievementSteps and
// getAchievementStatus.

import extension.gpg.GooglePlayGames;

class MainClass {

	function new() {
		// first of all... call init on the main method.
		// the boolean parameter is to enable cloud storage service. Note that google and will
		// prompt for that permission to the user the first time.
		// Set up the player score result event callback first, always before init().
		GooglePlayGames.onGetPlayerScore = playerScoreCallback; // Work with Int data type.
		GooglePlayGames.onGetPlayerScore64 = playerScore64Callback; // Work with Long data type.
		GooglePlayGames.init(true);
		// IMPORTANT: If you call init(true) you're enabling Saved Games API, so remember to enable
		// that feature on your google play games console to avoid Runtime Errors.
		// If you don't want to use Saved Games API, just calal GooglePlayGames.init(false);		
	}
	
	function getPlayerScoreFromScoreboard() {
		// Call getPlayerScore passing the idScoreboard.
		// This function returns False if the user is not logged into the game.
		GooglePlayGames.getPlayerScore("your-scoreboard-id"); // Same function for both data types (Int/Long).
	}
	
	function playerScoreCallback(idScoreboard:String, score:Int):Void {
		// This function must be adapted to your game logic.
		Lib.trace("ID Scoreboard: "+ idScoreboard +". Score: "+ score);
	}
	
	function playerScoreCallback64(idScoreboard:String, score:Int64):Void {
		// This function must be adapted to your game logic.
		Lib.trace("ID Scoreboard: "+ idScoreboard +". Score: "+ score);
	}
	
	// Note that, the functions:
	//			* GooglePlayGames.getCurrentAchievementSteps("your-achievement-id")
	//			* GooglePlayGames.getAchievementStatus("your-achievement-id")
	// Works with the same logic. Both must be set up the result event callback first.
	//			* GooglePlayGames.onGetPlayerAchievementStatus = callbackStatus;
	//			* GooglePlayGames.onGetPlayerCurrentSteps = callbackSteps;
	// Both functions returns false if the user is not logged into the game.
	//			* function callbackStatus(idAchievement:String, status:String): Void
	//			* function callbackSteps(idAchievement:String, steps:Int): Void
	
}

###How to Install

To install this library, you can simply get the library from haxelib like this:

haxelib install extension-googleplaygames

Once this is done, you just need to add this to your project.xml

<haxelib name="extension-googleplaygames" />
<setenv name="GOOGLE_PLAY_GAMES_ID" value="32180581421" /> <!-- REPLACE THIS WITH YOUR GOOGLE PLAY GAMES ID! -->

Also, you may need to set android sdk version to 23 or higher (as some versions of google play services requires this:

<android target-sdk-version="23" if="android" />

###Disclaimer

Google is a registered trademark of Google Inc. http://unibrander.com/united-states/140279US/google.html

###License

The MIT License (MIT) - LICENSE.md

Author: Federico Bricker

Vortelio/extension-googleplaygames