Turn-Based Game – iOS GameKit Plugin

API Index
Overview
Setup
Initialize
Achievements
Challenges
Leaderboards
Scores
Players
Real-Time Game
Turn-Based Game
 
Before you can use Turn-Based Game Commands in your game, the GameKit Plugin must be setup as well as initialized.
 
Turn-Based Game Commands
Request Register Turn-Based Matchmaker Listener
Request Unregister Turn-Based Matchmaker Listener
GameKit Turn-Based Matchmaker Events
Show Turn-Based Match UI
Request Turn-Based Auto-Matchmaker
Request Invite Friends Turn-Based Matchmaker
Request Accept Turn-Based Match Invite
Request Decline Turn-Based Match Invite
Get Turn-Based Matches
Get Turn-Based Match With MatchID
Request Remove Turn-Based Match
Request Local Player Quit Turn-Based Match
Request Register Turn-Based Listener
GameKit Turn-Based Game Events
Request Unregister Turn-Based Listener
Submit Save Turn-Based Match Data
Submit End Turn With Next Participants
Submit Pull Turn-Based Match
Submit Send Reminder To Participants
Submit Participant Quit In Turn
Submit Participant Quit Out Of Turn
Submit End Match In Turn With Match Data
Submit Send Exchange To Participants
Submit Cancel Exchange To Participants
Submit Reply To Exchange
Submit Save Exchange Merged Match Data
Submit Rematch With Same Opponents
 

Request Register Turn-Based Matchmaker Listener
Comments: Register Game Center Turn-Based matchmaker listener for local player only once for all Turn-Based matchmaking events. Note you need to register the Turn-Based matchmaker listener before you can call any other Turn-Based functions.

Function: request( (string) “registerTurnBasedMatchmakerListener”, (table) { listener= (function) onTurnBasedMatchmakerCallback } )
Param Table Keys: (function) listener – A function to receive callback events.
Callback Events:
Event Name: (string) “gameKitLibrary”
Event Type:
(string) “success” – GameKit success event.
Event Properties:
(string) successDescription – GameKit success description string.

 

Request Unregister Turn-Based Matchmaker Listener
Comments: Unregister Game Center Turn-Based matchmaker listener for local player. Note after you unregister the Turn-Based matchmaker listener your game will not receive anymore Turn-Based matchmaker events and you cannot call any other Turn-Based functions.

Function: request( (string) “unregisterTurnBasedMatchmakerListener” )
Param Table Keys: none
Callback Events: none

 

GameKit Turn-Based Matchmaker Events
Comments: GameKit Turn-Based Matchmaker Events called on local player’s device. Note the Turn-Based matchmaker listener needs to be registered before the local player’s device can receive these events.

Event Name: (string) “gameKitLibrary”
Event Type:
(string) “error” – GameKit error event.
(string) “success” – GameKit success event.
(string) “matchSelected” – Match selected event.
(string) “localPlayerQuit” – Local player quit event.
(string) “matchList” – Match list event.
Event Properties:
(number) errorCode – GameKit GKErrorCode number.
(string) errorDescription – GameKit error description string.
(string) successDescription – GameKit success description string.
(number) participantsCount – Number of turn-based match participants.
(table) match – A turn-based match table uses a store-and-forward approach to share data between the turn-based match participants.
(number) matchesCount – Number of turn-based match tables in the matches array.
(array) matches – An array of turn-based match tables.
Match Table Keys:
(string) creationDate – A date and time string that the match was created.
(string) matchID – A string assigned by Game Center that uniquely identifies the turn-based match.
(number) matchStatus – GameKit GKTurnBasedMatchStatus number.
(string) message – A string message that can be displayed to all players in the match. This property can be changed only by the player who is the current participant.
(number) matchDataMaximumSize – Number of maximum bytes Game Center limits for the match data.
(number) matchDataLength – Number of bytes for the match data.
(string) matchData – A match data string that can contain up to 64 kilobytes or less of data. Your game defines its own format for the string data it transmits and receives over the Game Center network.
(table) currentParticipant – A participant table of the participant whose turn it is to act next. The current participant is the only participant that is allowed to update the match data.
(array) participants – An array of participant tables.
(array) exchanges – An array of exchange tables.
Participant Table Keys:
(string) playerID – A string assigned by Game Center to uniquely identify a player participant.
(number) participantStatus – GameKit GKTurnBasedParticipantStatus number.
(string) lastTurnDate – A date and time string that the participant last took a turn in the game.
(string) timeoutDate – A date and time string that the participant’s turn timed out.
(number) matchOutcome – GameKit GKTurnBasedMatchOutcome number.
Exchange Table Keys:
(string) matchID – A string assigned by Game Center that uniquely identifies the turn-based match.
(string) exchangeID – A string assigned by Game Center that uniquely identifies the turn-based exchange.
(number) exchangeStatus – GameKit GKTurnBasedExchangeStatus number.
(string) message – A localized message string that is pushed to all of the recipients of the exchange.
(string) sendDate – A date and time string that the exchange was sent out.
(string) senderPlayerID – A string assigned by Game Center to uniquely identify a player that sent the exchange.
(string) timeoutDate – A date and time string that the exchange is to stay active before timing out.
(string) completionDate – A date and time string that the exchange was completed.
(array) recipients – An array of participant tables denoting the players the exchange was sent to.
(number) exchangeDataLength – Number of bytes for the exchange data.
(number) exchangeDataMaximumSize – Number of maximum bytes Game Center limits for the exchange data.
(string) exchangeData – An exchange data string that can contain up to 1024 bytes or less of data. Your game defines its own format for the string data it transmits and receives over the Game Center network.
(number) exchangeMaxInitiatedExchangesPerPlayer – A number that limits the number of exchanges the player can have initiated at once.
(array) replies – An array of exchange reply tables.
Reply Table Keys:
(string) recipientPlayerID – A string assigned by Game Center to uniquely identify a player that is replying to the exchange.
(string) message – A localized message string that for the push notification.
(string) replyData – A reply data string that can contain up to 1024 bytes or less of data. Your game defines its own format for the string data it transmits and receives over the Game Center network.

 

Show Turn-Based Match UI
Comments: Show Game Center Turn-Based Match UI. Note the optional param keys, playerGroup and playerAttributes, are not required.

Function: (function) show( (string) “gameCenterTurnBasedMatchUI”, (table) { minPlayers= (number) 2, maxPlayers= (number) 3, defaultNumPlayers= (number) 3, showExistingMatches= (boolean) true, (optional key) playerGroup= (number) 3, (optional key) playerAttributes= (number) 0xFFFF0000 } )
Param Table Keys:
(number) minPlayers – A minimum number of players that may join the match. The minPlayers number must be at least 2.
(number) maxPlayers – A maximum number of players that may join the match. The maxPlayers number is 16 and must be equal or greater than the minPlayers number.
(number) defaultNumPlayers – A default number of players for the match shown in the Game Center Turn-Based Match UI. The local player can choose to override this by adding or removing players in the Match UI.
(boolean) showExistingMatches – A boolean that determines whether the Game Center Turn-Based Match UI shows existing matches. showExistingMatches=true or showExistingMatches=false. true shows turn-based matches that are already in progress and false only offers the ability to create new turn-based matches.
(number) playerGroup (optional key) – A number identifying a subset of players allowed to join the match. Only players whose requests share the same playerGroup value are auto-matched by Game Center. For more information, see playerGroup in the Matchmaking Overview Guide.
(number) playerAttributes (optional key) – A hexadecimal number mask that specifies the role that the local player would like to play in the game. For more information, see playerAttributes in the Matchmaking Overview Guide.
Callback Events:
(string) “error” – GameKit error event.
(string) “matchSelected” – Match selected event.
Event Properties:
(number) errorCode – GameKit GKErrorCode number.
(string) errorDescription – GameKit error description string.
(number) participantsCount – Number of turn-based match participants.
(table) match – A turn-based match table uses a store-and-forward approach to share data between the turn-based match participants.
See GameKit Turn-Based Matchmaker Events for Match Table Keys, Participant Table Keys and Exchange Table Keys.

 

Request Turn-Based Auto-Matchmaker
Comments: Programmatically Turn-Based Auto-Matchmaker for your own custom game auto-match UI. Note the optional param keys, playerGroup and playerAttributes, are not required.

Function: (function) request( (string) “turnBasedAutoMatchmaker”, (table) { minPlayers= (number) 2, maxPlayers= (number) 3, (optional key) playerGroup= (number) 3, (optional key) playerAttributes= (number) 0xFFFF0000 } )
Param Table Keys:
(number) minPlayers – A minimum number of players that may join the match. The minPlayers number must be at least 2.
(number) maxPlayers – A maximum number of players that may join the match. The maxPlayers number is 16 and must be equal or greater than the minPlayers number.
(number) playerGroup (optional key) – A number identifying a subset of players allowed to join the match. Only players whose requests share the same playerGroup value are auto-matched by Game Center. For more information, see playerGroup in the Matchmaking Overview Guide.
(number) playerAttributes (optional key) – A hexadecimal number mask that specifies the role that the local player would like to play in the game. For more information, see playerAttributes in the Matchmaking Overview Guide.
Callback Events:
(string) “error” – GameKit error event.
(string) “matchSelected” – Match selected event.
Event Properties:
(number) errorCode – GameKit GKErrorCode number.
(string) errorDescription – GameKit error description string.
(number) participantsCount – Number of turn-based match participants.
(table) match – A turn-based match table uses a store-and-forward approach to share data between the turn-based match participants.
See GameKit Turn-Based Matchmaker Events for Match Table Keys, Participant Table Keys and Exchange Table Keys.

 

Request Invite Friends Turn-Based Matchmaker
Comments: Programmatically Invite Friends Turn-Based Matchmaker for your own custom game invite friends UI.

Function: request( (string) “inviteFriendsTurnBasedMatchmaker”, (table) { minPlayers= (number) 2, maxPlayers= (number) 3, playerIDs= (table) { (string) “G:2073637149” },
inviteMessage= (string) “Let’s play,friend” } )
Param Table Keys:
(number) minPlayers – A minimum number of players that may join the match. The minPlayers number must be at least 2.
(number) maxPlayers – A maximum number of players that may join the match. The maxPlayers number is 16 and must be equal or greater than the minPlayers number.
(table) playerIDs – An array of 1 or more playerID strings that the invite is to be sent to.
(string) inviteMessage – A string displayed on friend’s device when invited to join a match.
Callback Events:
Event Name: (string) “gameKitLibrary”
Event Type:
(string) “error” – GameKit error event.
(string) “inviteeResponse” – Invitee response event.
(string) “matchSelected” – Match selected event.
Event Properties:
(number) errorCode – GameKit GKErrorCode number.
(string) errorDescription – GameKit error description string.
(number) participantsCount – Number of turn-based match participants.
(table) match – A turn-based match table uses a store-and-forward approach to share data between the turn-based match participants.
See GameKit Turn-Based Matchmaker Events for Match Table Keys, Participant Table Keys and Exchange Table Keys.

 

Request Accept Turn-Based Match Invite
Comments: Programmatically Accept Turn-Based Match Invite for your own custom game accept invite UI.

Function: request( (string) “acceptTurnBasedMatchInvite”, (table) { matchID= (string) “2f6b8abd-9dec-466f-a676-c6add5feb61e” } )
Param Table Keys:
(string) matchID – A string assigned by Game Center that uniquely identifies the turn-based match.
Callback Events:
Event Name: (string) “gameKitLibrary”
Event Type:
(string) “error” – GameKit error event.
(string) “matchSelected” – Match selected event.
Event Properties:
(number) errorCode – GameKit GKErrorCode number.
(string) errorDescription – GameKit error description string.
(number) participantsCount – Number of turn-based match participants.
(table) match – A turn-based match table uses a store-and-forward approach to share data between the turn-based match participants.
See GameKit Turn-Based Matchmaker Events for Match Table Keys, Participant Table Keys and Exchange Table Keys.

 

Request Decline Turn-Based Match Invite
Comments: Programmatically Decline Turn-Based Match Invite for your own custom game decline invite UI.

Function: request( (string) “declineTurnBasedMatchInvite”, (table) { matchID= (string) “2f6b8abd-9dec-466f-a676-c6add5feb61e” } )
Param Table Keys:
(string) matchID – A string assigned by Game Center that uniquely identifies the turn-based match.
Callback Events:
Event Name: (string) “gameKitLibrary”
Event Type:
(string) “error” – GameKit error event.
(string) “success” – GameKit success event.
Event Properties:
(number) errorCode – GameKit GKErrorCode number.
(string) errorDescription – GameKit error description string.
(string) successDescription – GameKit success description string.

 

Get Turn-Based Matches
Comments: Programmatically Get Turn-Based Matches for your own custom game get matches UI.

Function: get( (string) “turnBasedMatches”, (table) { matchStatus= (string) “Open” } )
Param Table Keys:
(string) matchStatus – A filter string used to get turn-based matches on Game Center. matchStatus=”All” or matchStatus=”Open”. “All” will get all matches and “Open” will get only matches that have a GameKit GKTurnBasedMatchStatus of GKTurnBasedMatchStatusOpen or GKTurnBasedMatchStatusMatching.
Callback Events:
Event Name: (string) “gameKitLibrary”
Event Type:
(string) “error” – GameKit error event.
(string) “matchList” – Match list event.
Event Properties:
(number) errorCode – GameKit GKErrorCode number.
(string) errorDescription – GameKit error description string.
(number) matchesCount – Number of turn-based match tables in the matches array.
(array) matches – An array of turn-based match tables.
See GameKit Turn-Based Matchmaker Events for Match Table Keys, Participant Table Keys and Exchange Table Keys.

 

Get Turn-Based Match With MatchID
Comments: Programmatically Get Turn-Based Match With MatchID for your own custom game get match UI.

Function: get( (string) “turnBasedMatchWithMatchID”, (table) { matchID= (string) “2f6b8abd-9dec-466f-a676-c6add5feb61e” } )
Param Table Keys:
(string) matchID – A string assigned by Game Center that uniquely identifies the turn-based match.
Callback Events:
Event Name: (string) “gameKitLibrary”
Event Type:
(string) “error” – GameKit error event.
(string) “matchSelected” – Match selected event.
Event Properties:
(number) errorCode – GameKit GKErrorCode number.
(string) errorDescription – GameKit error description string.
(number) participantsCount – Number of turn-based match participants.
(table) match – A turn-based match table uses a store-and-forward approach to share data between the turn-based match participants.
See GameKit Turn-Based Matchmaker Events for Match Table Keys, Participant Table Keys and Exchange Table Keys.

 

Request Remove Turn-Based Match
Comments: Programmatically Remove Turn-Based Match from Game Center for your own custom game remove match UI. Note that if local player participant status is still GKTurnBasedParticipantStatusActive the match cannot be removed.

Function: request( (string) “removeTurnBasedMatch”, (table) { matchID= (string) “2f6b8abd-9dec-466f-a676-c6add5feb61e” } )

Param Table Keys:
(string) matchID – A string assigned by Game Center that uniquely identifies the turn-based match.
Callback Events:
Event Name: (string) “gameKitLibrary”
Event Type:
(string) “error” – GameKit error event.
(string) “success” – GameKit success event.
Event Properties:
(number) errorCode – GameKit GKErrorCode number.
(string) errorDescription – GameKit error description string.
(string) successDescription – GameKit success description string.

 

Request Local Player Quit Turn-Based Match
Comments: Local Player Quit Turn-Based Match. Resigns the local player from the match. When the local player quits from the Game Center UI the “localPlayerQuit” event is called but Game Center does not apply the quit match outcome to the match so you need to use this method to apply the quit match outcome on Game Center. Note the optional param keys, turnTimeout and messageArguments, are not required.

Function: request( (string) “localPlayerQuitMatchWithOutcome”, (table) { matchID= (string) “2f6b8abd-9dec-466f-a676-c6add5feb61e”, matchOutcome= (number) 1, nextParticipantIndexs= (array) { (number) 2 }, (optional key) turnTimeout= (number) 86400, matchData= (string) “mock-data”, removeMatch= (boolean) true, messageKey= (string) “Local Player Quit %@”, (optional key) messageArguments= (array) { (string) “:(” } } )
Param Table Keys:
(string) matchID – A string assigned by Game Center that uniquely identifies the turn-based match.
(number) matchOutcome – GameKit GKTurnBasedMatchOutcome number.
(array) nextParticipantIndexs – An array of number indexs reflecting the order in which the player participants should act next. Each index number in the array must be one of the index numbers in the match’s participants array.
(number) turnTimeout (optional key) – A number in seconds of time the next player participant has to complete their turn. If the optional turnTimeout Param key is omitted the default turn timeout is one week.
string) matchData – A match data string that can contain up to 64 kilobytes or less of data. Your game defines its own format for the string data it transmits and receives over the Game Center network.
(boolean) removeMatch – A boolean that determines whether to remove the turn-based match from Game Center or not. removeMatch=true or removeMatch=false. true removes match from Game Center and false leaves the match on Game Center.
(string) messageKey – A localized message string to display a message at the end of a turn. The localized messageKey can be formatted with the %@ and %n$@ specifiers. These specifiers use the strings designated in the messageArguments array.
(array) messageArguments (optional key) – An array of strings to be substituted using the format string specifiers in the messageKey. If the optional messageArguments Param key is omitted the messageKey string behaves like the regular message string.
Callback Events:
Event Name: (string) “gameKitLibrary”
Event Type:
(string) “error” – GameKit error event.
(string) “success” – GameKit success event.
Event Properties:
(number) errorCode – GameKit GKErrorCode number.
(string) errorDescription – GameKit error description string.
(string) successDescription – GameKit success description string.

 

Request Register Turn-Based Listener
Comments: Register Game Center Turn-Based game listener for all Turn-Based game events. Note you need to register the Turn-Based listener before you can call any other Turn-Based game functions.

Function: request( (string) “registerTurnBasedListener”, (table) { listener= (function) onTurnBasedGameCallback } )
Param Table Keys: (function) listener – A function to receive callback events.
Callback Events:
Event Name: (string) “gameKitLibrary”
Event Type:
(string) “success” – GameKit success event.
Event Properties:
(string) successDescription – GameKit success description string.

 

GameKit Turn-Based Game Events
Comments: GameKit Turn-Based Game Events called on local player’s device. Note the Turn-Based game listener needs to be registered before the local player’s device can receive these events.
Event Name: (string) “gameKitLibrary”
Event Type:
(string) “error” – GameKit error event.
(string) “success” – GameKit success event.
(string) “matchUpdated” – Match updated event.
(string) “matchEnded” – Match ended event.
(string) “exchangeRequest” – Exchange request event.
(string) “exchangeCanceled” – Exchange canceled event.
(string) “exchangeCompleted” – Exchange completed event.
Event Properties:
(number) errorCode – GameKit GKErrorCode number.
(string) errorDescription – GameKit error description string.
(string) successDescription – GameKit success description string.
(number) participantsCount – Number of turn-based match participants.
(table) match – A turn-based match table uses a store-and-forward approach to share data between the turn-based match participants.
(table) exchange – A turn-based exchange table allows match participants to send exchange data even when they are not the current participant.
Match Table Keys:
(string) creationDate – A date and time string that the match was created.
(string) matchID – A string assigned by Game Center that uniquely identifies the turn-based match.
(number) matchStatus – GameKit GKTurnBasedMatchStatus number.
(string) message – A string message that can be displayed to all players in the match. This property can be changed only by the player who is the current participant.
(number) matchDataMaximumSize – Number of maximum bytes Game Center limits for the match data.
(number) matchDataLength – Number of bytes for the match data.
(string) matchData – A match data string that can contain up to 64 kilobytes or less of data. Your game defines its own format for the string data it transmits and receives over the Game Center network.
(table) currentParticipant – A participant table of the participant whose turn it is to act next. The current participant is the only participant that is allowed to update the match data.
(array) participants – An array of participant tables.
(array) exchanges – An array of exchange tables.
Participant Table Keys:
(string) playerID – A string assigned by Game Center to uniquely identify a player participant.
(number) participantStatus – GameKit GKTurnBasedParticipantStatus number.
(string) lastTurnDate – A date and time string that the participant last took a turn in the game.
(string) timeoutDate – A date and time string that the participant’s turn timed out.
(number) matchOutcome – GameKit GKTurnBasedMatchOutcome number.
Exchange Table Keys:
(string) matchID – A string assigned by Game Center that uniquely identifies the turn-based match.
(string) exchangeID – A string assigned by Game Center that uniquely identifies the turn-based exchange.
(number) exchangeStatus – GameKit GKTurnBasedExchangeStatus number.
(string) message – A localized message string that is pushed to all of the recipients of the exchange.
(string) sendDate – A date and time string that the exchange was sent out.
(string) senderPlayerID – A string assigned by Game Center to uniquely identify a player that sent the exchange.
(string) timeoutDate – A date and time string that the exchange is to stay active before timing out.
(string) completionDate – A date and time string that the exchange was completed.
(array) recipients – An array of participant tables denoting the players the exchange was sent to.
(number) exchangeDataLength – Number of bytes for the exchange data.
(number) exchangeDataMaximumSize – Number of maximum bytes Game Center limits for the exchange data.
(string) exchangeData – An exchange data string that can contain up to 1024 bytes or less of data. Your game defines its own format for the string data it transmits and receives over the Game Center network.
(number) exchangeMaxInitiatedExchangesPerPlayer – A number that limits the number of exchanges the player can have initiated at once.
(array) replies – An array of exchange reply tables.
Reply Table Keys:
(string) recipientPlayerID – A string assigned by Game Center to uniquely identify a player that is replying to the exchange.
(string) message – A localized message string that for the push notification.
(string) replyData – A reply data string that can contain up to 1024 bytes or less of data. Your game defines its own format for the string data it transmits and receives over the Game Center network.

 

Request Unregister Turn-Based Listener
Comments: Unregister Game Center Turn-Based game listener. Note after you unregister the Turn-Based game listener your game will not receive anymore Turn-Based game events and you cannot call any other Turn-Based game functions.

Function: request( (string) “unregisterTurnBasedListener” )
Param Table Keys: none
Callback Events: none

 

Submit Save Turn-Based Match Data
Comments: Submit Save Turn-Based Match Data to Game Center. Update the match data on Game Center without advancing the game to another player participant. Call this when the current participant takes an action in the game that advances the state of the match but does not end the current player’s turn.

Function: (function) submit( (string) “saveCurrentTurnWithMatchData”, (table) { matchID= (string) “2f6b8abd-9dec-466f-a676-c6add5feb61e”, matchData= (string) “mock-data” } )
Param Table Keys:
(string) matchID – A string assigned by Game Center that uniquely identifies the turn-based match.
(string) matchData – A match data string that can contain up to 64 kilobytes or less of data. Your game defines its own format for the string data it transmits and receives over the Game Center network.
Callback Events:
(string) “error” – GameKit error event.
(string) “success” – GameKit success event.
Event Properties:
(number) errorCode – GameKit GKErrorCode number.
(string) errorDescription – GameKit error description string.
(string) successDescription – GameKit success description string.

 

Submit End Turn With Next Participants
Comments: Submit Turn-Based Match Data to Game Center and End Turn With Next Participants. Update the match data on Game Center and advance the game to another player participant. Your game should determine which player participant needs to act next using the nextParticipantIndexs array. Note the optional param keys, turnTimeout and messageArguments, are not required.

Function: (function) submit( (string) “endTurnWithNextParticipants”, (table) { matchID= (string) “2f6b8abd-9dec-466f-a676-c6add5feb61e”, nextParticipantIndexs= (array) { (number) 2, (number) 1 }, (optional key) turnTimeout= (number) 86400, matchData= (string) “mock-data”, messageKey= (string) “Check this %@”, (optional key) messageArguments= (array) { (string) “42” } } )
Param Table Keys:
(string) matchID – A string assigned by Game Center that uniquely identifies the turn-based match.
(array) nextParticipantIndexs – An array of number indexs reflecting the order in which the player participants should act next. Each index number in the array must be one of the index numbers in the match’s participants array. Submit at least 2 or more indexs in nextParticipantIndexs array for turnTimeout to work, otherwise the turn gets stuck on next participant forever or until the next participant takes their turn. Include the local player’s index last in the nextParticipantIndexs array so if the other players all quit the match, the turn will end on the last player to take a turn.
(number) turnTimeout (optional key) – A number in seconds of time the next player participant has to complete their turn. If the optional turnTimeout Param key is omitted the default turn timeout is one week.
(string) matchData – A match data string that can contain up to 64 kilobytes or less of data. Your game defines its own format for the string data it transmits and receives over the Game Center network.
(string) messageKey – A localized message string to display a message at the end of a turn. The localized messageKey can be formatted with the %@ and %n$@ specifiers. These specifiers use the strings designated in the messageArguments array.
(array) messageArguments (optional key) – An array of strings to be substituted using the format string specifiers in the messageKey. If the optional messageArguments Param key is omitted the messageKey string behaves like the regular message string.
Callback Events:
(string) “error” – GameKit error event.
(string) “success” – GameKit success event.
Event Properties:
(number) errorCode – GameKit GKErrorCode number.
(string) errorDescription – GameKit error description string.
(string) successDescription – GameKit success description string.

 

Submit Pull Turn-Based Match
Comments: Submit Pull Turn-Based Match with matchID. The Game Center turn-based match push events can be flakey sometimes. When that is the case you can use this method to pull the latest Game Center match table.

Function: submit( (string) “pullTurnBasedMatch”, (table) { matchID= (string) “2f6b8abd-9dec-466f-a676-c6add5feb61e” } )
Param Table Keys:
(string) matchID – A string assigned by Game Center that uniquely identifies the turn-based match.
Callback Events:
Event Name: (string) “gameKitLibrary”
Event Type:
(string) “error” – GameKit error event.
(string) “matchUpdated” – Match updated event.
Event Properties:
(number) errorCode – GameKit GKErrorCode number.
(string) errorDescription – GameKit error description string.
(number) participantsCount – Number of turn-based match participants.
(table) match – A turn-based match table uses a store-and-forward approach to share data between the turn-based match participants.
See GameKit Turn-Based Matchmaker Events for Match Table Keys, Participant Table Keys and Exchange Table Keys.

 

Submit Send Reminder To Participants
Comments: Submit Send Reminder To one or more game Participants. Note the optional param key, messageArguments, is not required.

Function: (function) submit( (string) “sendReminderToParticipants”, (table) { matchID= (string) “2f6b8abd-9dec-466f-a676-c6add5feb61e”, toParticipantIndexs= (array) { (number) 2 }, messageKey= (string) “It’s been %@ days, make your move.”, (optional key) messageArguments= (array) { (string) “2” } } )
Param Table Keys:
(string) matchID – A string assigned by Game Center that uniquely identifies the turn-based match.
(array) toParticipantIndexs – An array of number indexs of the participants who are to receive the reminder. Each index number in the array must be one of the index numbers in the match’s participants array.
(string) messageKey – A localized message string to display an alert message. The localized messageKey can be formatted with the %@ and %n$@ specifiers. These specifiers use the strings designated in the messageArguments array.
(array) messageArguments (optional key) – An array of strings to be substituted using the format string specifiers in the messageKey. If the optional messageArguments Param key is omitted the messageKey string behaves like the regular message string.
Callback Events:
(string) “error” – GameKit error event.
(string) “success” – GameKit success event.
Event Properties:
(number) errorCode – GameKit GKErrorCode number.
(string) errorDescription – GameKit error description string.
(string) successDescription – GameKit success description string.

 

Submit Participant Quit In Turn
Comments: Submit Participant Quit In Turn. Resigns the current participant from the match without ending the match. Note the optional param keys, turnTimeout and messageArguments, are not required.

Function: (function) submit( (string) “participantQuitInTurnWithOutcome”, (table) { matchID= (string) “2f6b8abd-9dec-466f-a676-c6add5feb61e”, matchOutcome= (number) 1, nextParticipantIndexs= (array) { (number) 2 }, (optional key) turnTimeout= (number) 86400, matchData= (string) “mock-data”, removeMatch= (boolean) false, messageKey= (string) “I Quit %@”, (optional key) messageArguments= (array) { (string) “:)” } } )
Param Table Keys:
(string) matchID – A string assigned by Game Center that uniquely identifies the turn-based match.
(number) matchOutcome – GameKit GKTurnBasedMatchOutcome number.
(array) nextParticipantIndexs – An array of number indexs reflecting the order in which the player participants should act next. Each index number in the array must be one of the index numbers in the match’s participants array.
(number) turnTimeout (optional key) – A number in seconds of time the next player participant has to complete their turn. If the optional turnTimeout Param key is omitted the default turn timeout is one week.
(string) matchData – A match data string that can contain up to 64 kilobytes or less of data. Your game defines its own format for the string data it transmits and receives over the Game Center network.
(boolean) removeMatch – A boolean that determines whether to remove the turn-based match from Game Center or not. removeMatch=true or removeMatch=false. true removes match from Game Center and false leaves the match on Game Center.
(string) messageKey – A localized message string to display an alert message. The localized messageKey can be formatted with the %@ and %n$@ specifiers. These specifiers use the strings designated in the messageArguments array.
(array) messageArguments (optional key) – An array of strings to be substituted using the format string specifiers in the messageKey. If the optional messageArguments Param key is omitted the messageKey string behaves like the regular message string.
Callback Events:
(string) “error” – GameKit error event.
(string) “success” – GameKit success event.
Event Properties:
(number) errorCode – GameKit GKErrorCode number.
(string) errorDescription – GameKit error description string.
(string) successDescription – GameKit success description string.

 

Submit Participant Quit Out Of Turn
Comments: Submit Participant Quit Out Of Turn. Resigns the player participant from the match without ending the match when that player is not the current participant. Note the optional param key, messageArguments, is not required.

Function: (function) submit( (string) “participantQuitOutOfTurnWithOutcome”, (table) { matchID= (string) “2f6b8abd-9dec-466f-a676-c6add5feb61e”, matchOutcome= (number) 1, messageKey= (string) “I’m outtie %@”, (optional key) messageArguments= (array) { (string) “:(” } } )
Param Table Keys:
(string) matchID – A string assigned by Game Center that uniquely identifies the turn-based match.
(number) matchOutcome – GameKit GKTurnBasedMatchOutcome number.
(string) messageKey – A localized message string to display an alert message. The localized messageKey can be formatted with the %@ and %n$@ specifiers. These specifiers use the strings designated in the messageArguments array.
(array) messageArguments (optional key) – An array of strings to be substituted using the format string specifiers in the messageKey. If the optional messageArguments Param key is omitted the messageKey string behaves like the regular message string.
Callback Events:
(string) “error” – GameKit error event.
(string) “success” – GameKit success event.
Event Properties:
(number) errorCode – GameKit GKErrorCode number.
(string) errorDescription – GameKit error description string.
(string) successDescription – GameKit success description string.

 

Submit End Match In Turn With Match Data
Comments: Submit End Turn-Based Match with outcomes In Turn With Match Data. Ends the match while submitting match outcomes with the option to submit all of the scores and achievements. Note the optional param keys, scores, achievements and messageArguments, are not required.

Function: (function) submit( (string) “endMatchInTurnWithMatchData”, (table) { matchID= (string) “2f6b8abd-9dec-466f-a676-c6add5feb61e”, matchData= (string) “mock-data”, outcomes= (array) { (number) 2 }, (optional key) scores= { (table) {playerID= (string) “G:2073637149”, leaderboardID= (string) “com.yourSite.yourGame.defaultLeaderboard”, value= (number) 334, (optional key) context= (number) 42} }, (optional key) achievements= { (table) {playerID= (string) “G:2073637149”, achievementID= (string) “com.yourSite.yourGame.achievement_wow”, percentComplete= (number) 100.00, showsCompletionBanner= (boolean) true} }, messageKey= (string) “Game %@ Over!”, (optional key) messageArguments= (array) { (string) “4” } } )
Param Table Keys:
(string) matchID – A string assigned by Game Center that uniquely identifies the turn-based match.
(string) matchData – A match data string that can contain up to 64 kilobytes or less of data. Your game defines its own format for the string data it transmits and receives over the Game Center network.
(array) outcomes – An array of participants GameKit GKTurnBasedMatchOutcome numbers. The outcome for each participant is aligned to the index of the participants array.
(array) scores (optional key) – An array of score tables containing the final scores for every participant in the match.
(array) achievements (optional key) – An array of achievement tables containing the achievements acquired by each participant in the match.
(string) messageKey – A localized message string to display an alert message. The localized messageKey can be formatted with the %@ and %n$@ specifiers. These specifiers use the strings designated in the messageArguments array.
(array) messageArguments (optional key) – An array of strings to be substituted using the format string specifiers in the messageKey. If the optional messageArguments Param key is omitted the messageKey string behaves like the regular message string.
Score Table Keys:
(string) playerID – A string assigned by Game Center to uniquely identify a player.
(string) leaderboardID – A unique Game Center leaderboard identifier string you created for your game on iTunes Connect.
(number) value – A score number value earned by the local player. You determine how your scores are formatted when you define the leaderboard on iTunes Connect.
(number) context (optional key) – A number value used by your game. The context property is stored and returned to your game, but is otherwise ignored by Game Center. It allows your game to associate an arbitrary 64-bit unsigned integer value with the score data reported to Game Center. You decide how this context value is interpreted by your game.
Achievement Table Keys:
(string) playerID – A string assigned by Game Center to uniquely identify a player.
(string) achievementID – A unique Game Center achievement identifier string you created for your game on iTunes Connect.
(number) percentComplete – A percentage decimal number value between 0.0 and 100.0 of how far the local player has progressed on this achievement.
(boolean) showsCompletionBanner – A boolean value that states whether a notification banner is displayed when the achievement is completed.
Callback Events:
(string) “error” – GameKit error event.
(string) “success” – GameKit success event.
Event Properties:
(number) errorCode – GameKit GKErrorCode number.
(string) errorDescription – GameKit error description string.
(string) successDescription – GameKit success description string.

 

Submit Send Exchange To Participants
Comments: Submit Send Exchange Request To one or more Participants. Note the optional param keys, exchangeTimeout and messageArguments, are not required.

Function: (function) submit( (string) “sendExchangeToParticipants”, (table) { matchID= (string) “2f6b8abd-9dec-466f-a676-c6add5feb61e”, participantIndexs= (array) { (number) 2 }, exchangeData= (string) “mock-exchange-data”, exchangeTimeout= (number) 2700, messageKey= (string) “Wanna swap %@ cards?”, (optional key) messageArguments= (array) { (string) “2” } } )
Param Table Keys:
(string) matchID – A string assigned by Game Center that uniquely identifies the turn-based match.
(array) participantIndexs – An array of number indexs of the player participants who the exchange request should be sent to. Each index number in the array must be one of the index numbers in the match’s participants array.
(string) exchangeData – An exchange data string that can contain up to 1024 bytes or less of data. Your game defines its own format for the string data it transmits and receives over the Game Center network.
(number) exchangeTimeout (optional key) – A number in seconds of time that passes before an exchange time outs. If the optional exchangeTimeout Param key is omitted the default turn timeout is one day.
(string) messageKey – A localized message string to display an alert message. The localized messageKey can be formatted with the %@ and %n$@ specifiers. These specifiers use the strings designated in the messageArguments array.
(array) messageArguments (optional key) – An array of strings to be substituted using the format string specifiers in the messageKey. If the optional messageArguments Param key is omitted the messageKey string behaves like the regular message string.
Callback Events:
(string) “error” – GameKit error event.
(string) “exchangeRequest” – Exchange request event.
Event Properties:
(number) errorCode – GameKit GKErrorCode number.
(string) errorDescription – GameKit error description string.
(table) exchange – An exchange table.
Exchange Table Keys:
(string) matchID – A string assigned by Game Center that uniquely identifies the turn-based match.
(string) exchangeID – A string assigned by Game Center that uniquely identifies the turn-based exchange.
(number) exchangeStatus – GameKit GKTurnBasedExchangeStatus number.
(string) message – A localized message string that is pushed to all of the recipients of the exchange.
(string) sendDate – A date and time string that the exchange was sent out.
(string) senderPlayerID – A string assigned by Game Center to uniquely identify a player that sent the exchange.
(string) timeoutDate – A date and time string that the exchange is to stay active before timing out.
(string) completionDate – A date and time string that the exchange was completed.
(array) recipients – An array of participant tables denoting the players the exchange was sent to.
(number) exchangeDataLength – Number of bytes for the exchange data.
(number) exchangeDataMaximumSize – Number of maximum bytes Game Center limits for the exchange data.
(string) exchangeData – An exchange data string that can contain up to 1024 bytes or less of data. Your game defines its own format for the string data it transmits and receives over the Game Center network.
(number) exchangeMaxInitiatedExchangesPerPlayer – A number that limits the number of exchanges the player can have initiated at once.
(array) replies – An array of exchange reply tables.
Reply Table Keys:
(string) recipientPlayerID – A string assigned by Game Center to uniquely identify a player that is replying to the exchange.
(string) message – A localized message string that for the push notification.
(string) replyData – A reply data string that can contain up to 1024 bytes or less of data. Your game defines its own format for the string data it transmits and receives over the Game Center network.

 

Submit Cancel Exchange To Participants
Comments: Submit Cancel Exchange Request To Participants. Note the optional param key, messageArguments, is not required.

Function: (function) submit( (string) “cancelExchangeToParticipants”, (table) { matchID= (string) “2f6b8abd-9dec-466f-a676-c6add5feb61e”, exchangeID= (string) “d7ca8ce3-3918-4b96-a3cd-feba470849af”, messageKey= (string) “You snooze, you lose %@”, (optional key) messageArguments= (array) { (string) “:P” } } )
Param Table Keys:
(string) matchID – A string assigned by Game Center that uniquely identifies the turn-based match.
(string) exchangeID – A string assigned by Game Center that uniquely identifies the turn-based exchange.
(string) messageKey – A localized message string to display an alert message. The localized messageKey can be formatted with the %@ and %n$@ specifiers. These specifiers use the strings designated in the messageArguments array.
(array) messageArguments (optional key) – An array of strings to be substituted using the format string specifiers in the messageKey. If the optional messageArguments Param key is omitted the messageKey string behaves like the regular message string.
Callback Events:
(string) “error” – GameKit error event.
(string) “success” – GameKit success event.
Event Properties:
(number) errorCode – GameKit GKErrorCode number.
(string) errorDescription – GameKit error description string.
(string) successDescription – GameKit success description string.

 

Submit Reply To Exchange
Comments: Submit Reply To Exchange Request. Note the optional param key, messageArguments, is not required.

Function: (function) submit( (string) “replyToExchange”, (table) { matchID= (string) “2f6b8abd-9dec-466f-a676-c6add5feb61e”, exchangeID= (string) “d7ca8ce3-3918-4b96-a3cd-feba470849af”, exchangeData= (string) “mock-exchange-data”, messageKey= (string) “These %@ are what I give thee.”, (optional key) messageArguments= (array) { (string) “3” } } )
Param Table Keys:
(string) matchID – A string assigned by Game Center that uniquely identifies the turn-based match.
(string) exchangeID – A string assigned by Game Center that uniquely identifies the turn-based exchange.
(string) exchangeData – An exchange data string that can contain up to 1024 bytes or less of data. Your game defines its own format for the string data it transmits and receives over the Game Center network.
(string) messageKey – A localized message string to display an alert message. The localized messageKey can be formatted with the %@ and %n$@ specifiers. These specifiers use the strings designated in the messageArguments array.
(array) messageArguments (optional key) – An array of strings to be substituted using the format string specifiers in the messageKey. If the optional messageArguments Param key is omitted the messageKey string behaves like the regular message string.
Callback Events:
(string) “error” – GameKit error event.
(string) “success” – GameKit success event.
Event Properties:
(number) errorCode – GameKit GKErrorCode number.
(string) errorDescription – GameKit error description string.
(string) successDescription – GameKit success description string.

 

Submit Save Exchange Merged Match Data
Comments: Submit Save Exchange Merged Match Data with resolved exchanges. Saves the merged exchange and match data for the current turn without ending the turn. All completed exchanges must be resolved before ending the current participant’s turn. Note only the current participant can save the exchange merged match data.

Function: (function) submit( (string) “saveMergedMatchDataWithResolvedExchanges”, (table) { matchID= (string) “2f6b8abd-9dec-466f-a676-c6add5feb61e”, mergedMatchData= (string) “mock-merged-data” } )
Param Table Keys:
(string) matchID – A string assigned by Game Center that uniquely identifies the turn-based match.
(string) mergedMatchData – A match data string that can contain up to 64 kilobytes or less of data reflecting the current state for the match.
Callback Events:
(string) “error” – GameKit error event.
(string) “success” – GameKit success event.
Event Properties:
(number) errorCode – GameKit GKErrorCode number.
(string) errorDescription – GameKit error description string.
(string) successDescription – GameKit success description string.

 

Submit Rematch With Same Opponents
Comments: Submit Rematch With Same Opponents. Create a new turn-based match with the same participants as an existing match.

Function: submit( (string) “rematchWithSameOpponents”, (table) { matchID= (string) “2f6b8abd-9dec-466f-a676-c6add5feb61e” } )
Param Table Keys:
(string) matchID – A string assigned by Game Center that uniquely identifies the turn-based match.
Callback Events:
Event Name: (string) “gameKitLibrary”
Event Type:
(string) “error” – GameKit error event.
(string) “matchUpdated” – Match updated event.
Event Properties:
(number) errorCode – GameKit GKErrorCode number.
(string) errorDescription – GameKit error description string.
(number) participantsCount – Number of turn-based match participants.
(table) match – A turn-based match table uses a store-and-forward approach to share data between the turn-based match participants.
See GameKit Turn-Based Matchmaker Events for Match Table Keys, Participant Table Keys and Exchange Table Keys.