Game Kit by Vitapoly

Product Description

The FULL native iOS Game Kit framework is now available to you as an AIR Native Extension, including real-time and turn-based Game Center matches.

The iOS Game Kit native extension allows your game to setup real-time Game Center matches for up to 4 players, send and receive custom data between players, and enable voice chat during gameplay! It also allows your game to integrate turn-based matches for up to 16 players. This ANE also includes the commonly used leaderboard and achievements. All of this comes in an easy high-level API, with a low-level API to ALL native Game Kit calls in case you need to use advanced functionalities.

Important Note: This ANE supports iOS, and implements the FULL iOS Game Kit framework.

Requires iOS 6.0 SDK to build, but it can be used with iOS 4.3 and up
on devices.

What’s New in Version 1.3:

- Handling turn-based accept invitation event. It is set as the current match now.
- Added TurnBasedMatchesController.setCurrentMatch().
- Added TurnBasedMatch.saveTurn().
- Added TurnBasedMatch.isLocalPlayerInMatch.
- TurnBasedMatch.isNewMatch checks whether matchData is empty instead of the first participant’s lastTurnDate.
- Fixed other bugs in TurnBasedMatch.
- Better documentation for events in ASDocs.

What’s New in Version 1.2:

- Added showExistingMatches argument to TurnBasedMatchesController.startMatch().
- Added TurnBasedMatchesController.setGKTurnBasedMatchAsCurrentMatch();

What’s New in Version 1.1:

- LOCAL_PLAYER_NOT_AUTHENTICATED_EVENT event is changed to an ErrorEvent with description and code.
- GameKit.reportScore() dispatches SCORE_REPORTED_EVENT and SCORE_NOT_REPORTED_EVENT events.
- GameKit.reportAchievement() dispatches ACHIEVEMENT_REPORTED_EVENT and ACHIEVEMENT_NOT_REPORTED_EVENT events.
- TurnBasedMatchesController.advanceTurn(), quitDuringTurn(), and endMatch() take an optional message argument.
- ASDoc shows documentation for deprecated methods.
- Fixed bugs and stability issues.

Tweet

Set up Game Center in iTunesConnect

1. Login to iTunesConnect at https://itunesconnect.apple.com.
2. Create a new app or edit an existing app.
3. Click on Manage Game Center on the top right side.
4. Enable Game Center. Click Done.
5. Click View Details for Current Version.
6. Enable Game Center.
7. Edit Leaderboards, Achievements, and Multiplayer Compatibility appropriately.

Basic Uses of the Native Extension

1. Add the ANE to the project and package for iOS
2. Point to the iOS 6.0+ SDK in Package Configurations: Example:

/Applications/Xcode.app/Contents/Developer/Platforms/iPhoneOS.platform/Developer/SDKs/iPhoneOS6.0.sdk/

3. If you are using other ANEs by vitapoly, click on Hide ANE-Library-Symbols.
4. Make sure your app.xml file and Debug Configurations has matching application ID as the one you entered in iTunes Connect.
5. Check if the ANE is supported on the current platform:

var supported:Boolean = GameKit.isSupported;

6. Create or get the singleton:

var gamekit:GameKit = new GameKit();

or

var gamekit:GameKit = GameKit.instance;

7. Authenticate the local player, but listen to the events first:

gamekit.addEventListener(GameKit.LOCAL_PLAYER_AUTHENTICATED_EVENT, function(e:Event):void {
    trace("LOCAL_PLAYER_AUTHENTICATED_EVENT");
});

gamekit.addEventListener(GameKit.LOCAL_PLAYER_NOT_AUTHENTICATED_EVENT, function(e:ErrorEvent):void {
    trace("LOCAL_PLAYER_NOT_AUTHENTICATED_EVENT: " + e.text);

    // don’t allow to proceed if no single player
    // or just disable multiplayer interface
    disableMultiplayer(); // implement your own
});

gamekit.authenticateLocalPlayer();

8. Get info about local player after successful authentication:

var localPlayer:LocalPlayer = gamekit.localPlayer;
trace(localPlayer.displayName);

// load friends with a completion callback function
localPlayer.loadFriends(function(friends:Array):void {
    // localPlayer.friends property is now loaded
    for each (var friend:Player in localPlayer.friends)
        trace("friend: " + friend.displayName);
});

9. Show native Game Center interface for iOS 6.0 and later:

gamekit.showGameCenter();

10. Show native Game Center Leaderboard interface:

gamekit.showLeaderboard("leaderboardID");

11. Report score to Game Center Leaderboard:

gamekit.reportScore("leaderboardID", score);

12. Show native Game Center Achievements interface:

gamekit.showAchievements();

13. Report achievement progress to Game Center:

gamekit.reportAchievement("achievementID", progress);

Game Center Real-Time Matches

1. Initialize the RealTimeMatchesController, but listen to events first:

gamekit.realTimeMatchesController.addEventListener(RealTimeMatchesController.MATCH_MAKER_FAILED_EVENT, function(e:ErrorEvent):void {
    trace("MATCH_MAKER_FAILED_EVENT: " + e.errorID + ", " + e.text);
});

gamekit.realTimeMatchesController.addEventListener(RealTimeMatchesController.MATCH_MAKER_CANCELLED_EVENT, function(e:Event):void {
    trace("MATCH_MAKER_CANCELLED_EVENT");
});

gamekit.realTimeMatchesController.addEventListener(RealTimeMatchesController.MATCH_MAKER_FOUND_MATCH_EVENT, function(e:MatchEvent):void {
    trace("MATCH_MAKER_FOUND_MATCH_EVENT: " + JSON.stringify(e));

    match = e.match; // save the match somewhere
    // or use gamekit.realTimeMatchesController.currentMatch

    // start game if not expecting anymore players to join
    if (match.expectedPlayerCount == 0)
        startGame(); // implement your own
});

gamekit.realTimeMatchesController.addEventListener(RealTimeMatchesController.INVITE_ACCEPTED_EVENT, function(e:Event):void {
    trace("INVITE_ACCEPTED_EVENT: " + JSON.stringify(e));

    //  accepted an invite from another player, clean up current game and show new game
});

gamekit.realTimeMatchesController.addEventListener(RealTimeMatchesController.INVITE_PLAYERS_EVENT, function(e:InvitePlayersEvent):void {
    trace("INVITE_PLAYERS_EVENT: " + JSON.stringify(e));

    // launched from Game Center, bring up match making interface with the array of invited players
    gamekit.realTimeMatchesController.startMatch(2, 4, 0, 0, e.playersToInvite);
});

gamekit.realTimeMatchesController.init();

2. Start a real-time match:

// bring up native match making interface for a match with 2 to 4 players
gamekit.realTimeMatchesController.startMatch(2, 4);

3. Send data to other players during game:

var data:ByteArray = new ByteArray();
data.writeUTFBytes("hello");

// send a reliable packet to all players
match.sendDataToAll(data, true);

// send an unreliable packet to the match's first player
match.sendData(match.players[0], data, false);

4. Receive data from other players:

match.addEventListener(RealTimeMatch.RECEIVED_DATA_EVENT, function(e:DataReceivedEvent):void {
    trace("RealTimeMatch.RECEIVED_DATA_EVENT from " + e.player.playerID + ": " + e.data.toString());
});

5. Start a voice chat with other players:

var chat:VoiceChat = match.getVoiceChat("all");

// join the voice chat so the player can hear other players
chat.join();

// set talk to true so other players can hear this player
chat.talk = true;

// leave a chat some time later
chat.leave();

6. Disconnect and properly dispose the match:

match.disconnect();
match.dispose(); // releases the native match object
match = null;

Game Center Turn-Based Matches

1. Initialize the TurnBasedMatchesController, but listen to events first:

gamekit.turnBasedMatchesController.addEventListener(TurnBasedMatchesController.MATCH_MAKER_FAILED_EVENT, function(e:ErrorEvent):void {
    trace("MATCH_MAKER_FAILED_EVENT: " + e.errorID + ", " + e.text);
});

gamekit.turnBasedMatchesController.addEventListener(TurnBasedMatchesController.MATCH_MAKER_CANCELLED_EVENT, function(e:Event):void {
    trace("MATCH_MAKER_CANCELLED_EVENT");
});

gamekit.turnBasedMatchesController.addEventListener(TurnBasedMatchesController.MY_TURN_EVENT, function(e:MatchEvent):void {
    trace("MY_TURN_EVENT: " + JSON.stringify(e));

    if (e.turnBasedMatch.isNewMatch)
        startGame(); // local player just started the game, so show new game  
    else if (e.turnBasedMatch.isCurrentMatch)
        takeTurn(); // it's the currently displaying match, so the local player take the turn
    else
        showMsg("It's your turn for another match: " + e.turnBasedMatch.matchID);
});

gamekit.turnBasedMatchesController.addEventListener(TurnBasedMatchesController.NOT_MY_TURN_EVENT, function(e:MatchEvent):void {
    trace("NOT_MY_TURN_EVENT: " + JSON.stringify(e));

    if (e.turnBasedMatch.isCurrentMatch)
        displayGame(); // not the player's turn, just show it
    else
        showMsg("It's someone else's turn for another match: " + e.turnBasedMatch.matchID);
});

gamekit.turnBasedMatchesController.addEventListener(TurnBasedMatchesController.MATCH_ENDED_EVENT, function(e:MatchEvent):void {
    trace("MATCH_ENDED_EVENT: " + JSON.stringify(e));

    if (e.turnBasedMatch.isCurrentMatch)
        displayGame(); // just show the end game
    else
        showMsg("Another match ended: " + e.turnBasedMatch.matchID);
});

gamekit.turnBasedMatchesController.addEventListener(TurnBasedMatchesController.PLAYER_QUIT_EVENT, function(e:MatchEvent):void {
    trace("PLAYER_QUIT_EVENT: " + JSON.stringify(e));

    // the player quit a match from match making interface
    // quit it with a lost outcome
    showMsg("player quit match: " + e.turnBasedMatch.matchID);
    e.turnBasedMatch.quitDuringTurn(GKTurnBasedMatchOutcome.GKTurnBasedMatchOutcomeLost, e.turnBasedMatch.matchData);
});

gamekit.turnBasedMatchesController.addEventListener(TurnBasedMatchesController.INVITE_PLAYERS_EVENT, function(e:InvitePlayersEvent):void {
    trace("INVITE_PLAYERS_EVENT: " + JSON.stringify(e));

    // invited players from Game Center, bring up match making interface with the array of invited players
    gamekit.turnBasedMatchesController.startMatch(2, 2, e.playersToInvite);
});

gamekit.turnBasedMatchesController.init();

2. Start or join a turn-based match:

// bring up native match making interface for a match with 2 to 12 players
gamekit.turnBasedMatchesController.startMatch(2, 12);

3. Get match data:

var data:ByteArray = gamekit.turnBasedMatchesController.currentMatch.matchData;

// deserialize the data and display the match
showGame(data);

4. Advance turn when it’s the local player’s turn:

// serialize the entire game's data into a byte array
var data:ByteArray = serializeGameData();
var message:String = getMatchMessage(); // optional

gamekit.turnBasedMatchesController.currentMatch.advanceTurn(data, message);

5. You can also listen to other success and error completion events in TurnBasedMatch.
6. Set a player’s match outcome:

// set the first player to won
gamekit.turnBasedMatchesController.currentMatch.participants[0].matchOutcome = GKTurnBasedMatchOutcome.GKTurnBasedMatchOutcomeWon;

7. End a match:

// serialize the final game's data into a byte array
var data:ByteArray = serializeFinalGameData();
var message:String = getFinalMatchMessage(); // optional

// make sure all participants have an outcome first
gamekit.turnBasedMatchesController.currentMatch.participants[0].matchOutcome = GKTurnBasedMatchOutcome.GKTurnBasedMatchOutcomeWon;
gamekit.turnBasedMatchesController.currentMatch.participants[1].matchOutcome = GKTurnBasedMatchOutcome.GKTurnBasedMatchOutcomeLost;
…

// end it
gamekit.turnBasedMatchesController.currentMatch.endMatch(data, message);

Tweet