mergGK

mergGK is an iOS external that adds GameKit/Game Center commands and functions to LiveCode. The Game Center Programming Guide contains additional useful information.

Documentation

function mergGKIsGameCenterAvailable

Returns boolean

Authenticating The Local Player

command mergGKAuthenticateLocalPlayer

Authenticate the local player. This command will allow the user to login and/or create a new Game Center account.

message mergGKLocalPlayerAuthenticated

Sent to the control that called mergGKAuthenticateLocalPlayer whenever a new local player is authenticated. The logged in player in Game Center may be changed if the user closes or suspends your app. Your app should be prepared to handle multiple states for different users based on the player id. In a multi-tasking app this message may be sent more than once.

message mergGKLocalPlayerAuthenticated // Sent to the control that called mergGKAuthenticateLocalPlayer whenever a new local player is authenticated. The logged in player in Game Center may be changed if the user closes or suspends your app. Your app should be prepared to handle multiple states for different users based on the player id. In a multi-tasking app this message may be sent more than once. pPlayerID,pPlayerAlias,pPlayerDisplayName,pPlayerUnderAge

Parameters:

  • pPlayerID - the ID for the local player.
  • pPlayerAlias - the alias for the local player.
  • pPlayerDisplayName - the display name for the local player.
  • pPlayerUnderAge - true if the player is under age.

Code sample

on preOpenStack
  if the environment = "mobile" then
     mergGKAuthenticateLocalPlayer
  end if
end preOpenStack
 
on mergGKLocalPlayerAuthenticated pPlayerID,pPlayerAlias,pPlayerDisplayName
  -- load state for this player
end mergGKLocalPlayerAuthenticated

Working With Players

command mergGKLoadFriends

Request a list of the local player's friends.

message mergGKFriends

Sent to the control that called mergGKGetFriends.

message mergGKFriends // Sent to the control that called mergGKGetFriends. pLocalPlayerFriendIDs

Parameters:

  • pLocalPlayerFriendIDs - a return separated list of player IDs of players that are friends of the local player.

command mergGKLoadPlayers pPlayerIDs

Request the details of a list of players

Parameters:

  • pPlayerIDs - a return delimited list of player IDs

message mergGKPlayers

Sent to the control that called mergGKGetPlayers.

message mergGKPlayers // Sent to the control that called mergGKGetPlayers. pPlayers

Parameters:

  • pPlayers - a return tab and return delimited list of:|player ID|alias|is friend - true if the player is a friend of the local player|display name.

Code sample

on loadFriends
  if the environment = "mobile" then
     mergGKGetFriends
  end if
end loadFriends
 
on mergGKFriends pLocalPlayerFriendIDs
  mergGKLoadPlayers pLocalPlayerFriendIDs
end mergGKFriends
 
on mergGKPlayers pPlayers
  -- show the display name in a list etc
end mergGKPlayers

Leaderboards

command mergGKPostScore pCategory,pScore,[pSetDefaultLeaderboard],[pContext]

Your game should create the score object and report the score to Game Center immediately after the score is earned. This sets the date and time accurately and ensures that the score is reported correctly. If for some reason the score could not be reported because of a network error, Game Kit automatically resends the data when the network becomes available.

Parameters:

  • pCategory - The leaderboard ID for the leaderboard.
  • pScore - The score to report.
  • pSetDefaultLeaderboard - (optional with "false" default) The default leaderboard is set when you create your leaderboards in iTunes Connect. However, the default leaderboard is a per-player setting also; as a player plays your game you can update the default leaderboard shown to that player.
    • true
    • false
  • pContext - (optional with 0 default) Although the score and formatting system allows you to create interesting leaderboards, you may want to extend the leaderboard system to include other information specific to your game. You do this using score contexts. A score has a context property that holds a 64-bit integer. The value stored in this property is stored along with the score. Game Center doesn’t use this value at all, nor does it affect score formatting. Your game is free to use this integer to store whatever information you want.
    • You can use the context property to store flags that provide additional content. For example, in a racing game, you might use the flags to store what kind of car the person completed the track with. Then, in your own custom leaderboard user interface, you could display the appropriate car image next to each score.
    • You could record the user’s actions and other data into a file. You then design your game engine to be able to replay the contents of that file. You store the file on your own server and use the context field as an index to reference the file. Your custom leaderboard user interface can then offer the ability to see exactly how someone earned the score.
    • You could implement the replay directly into your gameplay. For example, in the hypothetical racing game, you use a player’s replay file to display a phantom car for the current player to race against.

command mergGKShowLeaderboard pCategory,[pTimeScope]

Present the Game Center leaderboad modal dialog.

Parameters:

  • pCategory - The leaderboard ID for the leaderboard.
  • pTimeScope - (optional with "all time" default) The time scope of the request. One of:
    • today
    • week
    • all time

command mergGKLoadScores pCategory,[pTimeScope],[pPlayerScope],[pFrom],[pTo],[pPlayerIDs]

Get a leaderboard of scores. Use this command to create a custom leaderboard within your app rather than use the Game Center modal. You could for example, use the list of player IDs from mergGKFriends to create a friends only list.

Parameters:

  • pCategory - The leaderboard ID for the leaderboard.
  • pTimeScope - (optional with "all time" default) The time scope of the request. One of:
    • today
    • week
    • all time
  • pPlayerScope - (optional with "global" default) The player scope of the request. One of:
    • today
    • week
    • all time
  • pFrom - (optional with 1 default) The first score in the range to return.
  • pTo - (optional with 10 default) The last score in the range to return.
  • pPlayerIDs - (optional with "" default) A return separated list of player id's if you would like the scores reported on only those players.

message mergGKScores

Sent to the control that called mergGKGetScores.

message mergGKScores // Sent to the control that called mergGKGetScores. pScores

Parameters:

  • pScores - a return tab and return delimited list of:|player ID|category|value|context|date in long seconds format|rank|formatted value

Achievements

command mergGKPostAchievement pAchievement,pPercentComplete,[pShowBanner]

Your game should report progress to Game Center whenever the player makes progress towards completing an achievement. By storing progress information in Game Center, the Game Center app can display the player’s progress towards the achievement. If a player has multiple devices, your game on another device can retrieve the player’s progress towards achievements. Your game reports the player’s progress by using a floating-point percentage, from 0.0 to 100.0, that represents how much of the achievement the player has completed. You decide how that percentage is calculated and when it changes. For example, if the player earns an achievement simply for discovering a location in your game, then you would simply report the achievement as 100 percent complete the first time you report progress to Game Center. On the other hand, for an achievement like “Capture 10 pirates”, your reporting mechanism increments by 10 percent each time the player captures a pirate.

When you report progress to Game Center, two things happen:

  • If the achievement was previously hidden, it is revealed to the player. The achievement is revealed even if your player has made no actual progress on the achievement (a percentage of 0.0).
  • If the reported value is higher than the previous value reported for the achievement, the value on Game Center is updated to the new value. Players never lose progress on achievements.
  • When the progress reaches 100 percent, the achievement is marked completed, and both the image and completed description appear when the player views the achievements screen.

Parameters:

  • pAchievement - The achievement identifier.
  • pPercentComplete - The percentage complete between 0 and 100 percent.
  • pShowBanner - (optional with "true" default) If false the Game Center banner will not be shown to the user when they comlete the achievement.
    • true
    • false

command mergGKShowAchievements

Present the Game Center achievement modal dialog.

command mergGKLoadAchievements

Get the local player's achievements.

message mergGKAchievements

Sent to the control that called mergGKLoadAchievements.

message mergGKAchievements // Sent to the control that called mergGKLoadAchievements. pAchievements

Parameters:

  • pAchievements - a return tab and return delimited list of:|achievement identifier|achievement percent complete

Challenges

command mergGKLoadChallenges

Achievements and leaderboards both allow players to measure their progress playing your game. But it is also common for players to want to test their progress against each other. It is more important to beat a friend’s score than to merely achieve a decent score! Game Center embraces this idea in the form of challenges. Players on Game Center can challenge other Game Center members to beat earned scores or achievements. Challenges represent a different style of multiplayer experience where players compete against each other indirectly.

When a challenge is issued by one player to another, a push notification is sent to the challenged player. The player can accept or refuse the challenge. If the player accepts the challenge, the challenge is placed on a list of challenges associated with that player. Later, if the player beats the challenge, Game Center notifies both the challenged player and the challenger that the challenge is complete.

Game Center supports two kinds of challenges:

  • A score challenge is issued based on a leaderboard score previously earned by the challenger. The challenge is completed when the challenged player earns a better score. When the challenged player beats a score challenge, Game Center automatically issues a new score challenge to the original challenger. Score challenges continue to pass back and forth between the two players as they work to beat each other’s scores.
  • An achievement challenge is issued from an achievement that the challenger has already completed. The challenge is completed when the challenged player completes the achievement.

message mergGKChallenges

Sent to the control that called mergGKLoadChallenges.

message mergGKChallenges // Sent to the control that called mergGKLoadChallenges. pScoreChallenges,pAchievementChallenges

Parameters:

  • pScoreChallenges - a return tab and return delimited list of:|issuing player id|issue date in long seconds format|leaderboard category identifier|score value|score context
  • pAchievementChallenges - a return tab and return delimited list of:|issuing player id|issue date in long seconds format|achievement identifier|percent complete

message mergGKScoreChallenge

Sent when the player clicks on a Game Center banner to select a score challenge.

message mergGKScoreChallenge // Sent when the player clicks on a Game Center banner to select a score challenge. pIssuingPlayerID,pIssueDate,pCategoryID,pValue,pContext

Parameters:

  • pIssuingPlayerID - the player id of the player issuing the challenge
  • pIssueDate - the date the challenge was issued in long seconds format
  • pCategoryID - the leaderboard category identifier of the score
  • pValue - the value of the score
  • pContext - the context of the score

message mergGKAchievementChallenge

Sent when the player clicks on a Game Center banner to select a score challenge.

message mergGKAchievementChallenge // Sent when the player clicks on a Game Center banner to select a score challenge. pIssuingPlayerID,pIssueDate,pAchievementID,pPercentComplete

Parameters:

  • pIssuingPlayerID - the player id of the player issuing the challenge
  • pIssueDate - the date the challenge was issued in long seconds format
  • pAchievementID - the achievement identifier
  • pPercentComplete - the percentage completion of the achievement that the local player needs to achieve to complete the challenge

General

command mergGKShowBanner pTitle,pMessage

Allows your game to display a notification banner that displays text to the player. The behavior of this banner is identical to other banners used by Game Kit.

Parameters:

  • pTitle - the title of the banner to display
  • pMessage - a secondary message to be displayed

message mergGKBannerShown

Sent to the object that requested the banner be shown after it is shown.

message mergGKBannerShown // Sent to the object that requested the banner be shown after it is shown.

Peer To Peer

command mergGKStartPeer

Register as a peer in the GameKit peer-to-peer session

command mergGKSendToPeers pPeers,pData

Send data to other peers

Parameters:

  • pPeers - a list of peer id's with one per line
  • pData - data to send to the peer

command mergGKSendToAllPeers pData

Send data to all peers

Parameters:

  • pData - data to send to the peer

message mergGKDataReceived

Sent to the control that called mergGKStartPeer when a peer sends some data.

message mergGKDataReceived // Sent to the control that called mergGKStartPeer when a peer sends some data. pPeerID,pData

Parameters:

  • pPeerID - a peer id of the peer sending the data
  • pData - the data sent from the peer

command mergGKConnectToPeer pPeer

Connect to a peer

Parameters:

  • pPeer - a peer id

command mergGKStopPeer

Stop the peer-to-peer session

function mergGKGetPeers pConnectionState

Get a list of peers with specified connection state.

Parameters:

  • pConnectionState - One of:
    • available
    • unavailable
    • connected
    • disconnectd
    • connecting

Returns peer id's with one per line

function mergGKDisplayNameForPeer pPeer

Get the display name for a peer

Parameters:

  • pPeer - a peer id

Returns the display name

message mergGKPeerChangedState

Sent to the control that called mergGKStartPeer when a peer changes state.

message mergGKPeerChangedState // Sent to the control that called mergGKStartPeer when a peer changes state. pPeerID,pState

Parameters:

  • pPeerID - a peer id
  • pState - a peer state. One of:|Available|Connected|Connecting|Unavailable|Disconnected

message mergGKConnectionWithPeerFailed

Sent to the control that called mergGKStartPeer when a connection to a peer fails.

message mergGKConnectionWithPeerFailed // Sent to the control that called mergGKStartPeer when a connection to a peer fails. pPeerID,pError

Parameters:

  • pPeerID - a peer id
  • pError - an error description

message mergGKSessionFailed

Sent to the control that called mergGKStartPeer when a session fails.

message mergGKSessionFailed // Sent to the control that called mergGKStartPeer when a session fails. pError

Parameters:

  • pError - an error description