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