API Index
Overview
Setup
Initialize
Achievements
Challenges
Leaderboards
Scores
Players
Real-Time Game
Turn-Based Game
Before you can use Players Commands in your game, the GameKit Plugin must be setup as well as initialized.
Players Commands
Get Player Photo
Get Max Number Of Recipients In Friend Request
Show Friend Request UI
Get Friends
Get Players With PlayerIDs
Send Game Center Notification Banner
Get Player Photo
Comments: Get Game Center Player Photo.
Function: (function) get( (string) “playerPhoto”, (table) { playerID= (string) “G:9125286970”, photoSize= (string) “Normal”, listener= (function) onPlayerCallback } )
Param Table Keys:
(string) playerID – A string assigned by Game Center to uniquely identify a player.
(string) photoSize – A photo size string of the player’s photo to get on Game Center. photoSize=”Small” or photoSize=”Normal”. “Small” will get player’s small sized photo and “Normal” will get player’s normal sized photo.
(function) listener – A function to receive callback events.
Callback Events:
Event Name: (string) “gameKitLibrary”
Event Type:
(string) “error” – GameKit error event.
(string) “playerPhoto” – Player photo event.
Event Properties:
(number) errorCode – GameKit GKErrorCode number.
(string) errorDescription – GameKit error description string.
(number) scoresCount – Number of score tables in the scores array.
(string) playerID – A string assigned by Game Center to uniquely identify a player.
(display object) photo – A photo to display for the player.
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 |
local playerPhoto = nil -- mock data mockFriendPlayerID = "G:9125286970" local function onPlayerCallback( event ) if( event.type == "error" ) then print( 'onPlayerCallback event.errorCode = ' .. tostring(event.errorCode) ) print( 'onPlayerCallback event.errorDescription = ' .. event.errorDescription ) elseif( event.type == "playerPhoto" ) then print( 'onPlayerCallback playerID = ' .. event.playerID ) playerPhoto = event.photo playerPhoto.x = display.contentCenterX playerPhoto.y = display.contentCenterY end return true end gameKit.get( "playerPhoto", { playerID=mockFriendPlayerID, photoSize="Small", listener=onPlayerCallback } ) |
Get Max Number Of Recipients In Friend Request
Comments: Get Game Center max number of recipients in Friend Request.
Function: (function) get( (string) “maxNumberOfRecipientsInFriendRequest”, (table) { listener= (function) onPlayerCallback } )
Param Table Keys: (function) listener – A function to receive callback events.
Callback Events:
Event Name: (string) “gameKitLibrary”
Event Type: (string) “friendRequestMaxRecipients” – Friend request max recipients event.
Event Properties: (number) maxNumber – The maximum number of recipients permitted in a single friend request.
|
1 2 3 4 5 6 7 8 9 10 |
local function onPlayerCallback( event ) if( event.type == "friendRequestMaxRecipients" ) then print( 'onPlayerCallback event.maxNumber = ' .. tostring(event.maxNumber) ) end return true end gameKit.get( "maxNumberOfRecipientsInFriendRequest", { listener=onPlayerCallback } ) |
Show Friend Request UI
Comments: Show Game Center Friend Request UI. Note the optional Param table keys, playerIDs and emailAddresses. You can use either playerIDs or emailAddresses or neither for your friend request but not both in the same request.
Function: (function) show( (string) “gameCenterFriendRequestUI”, (table) { message=”wanna be my friend?”, (optional key) playerIDs= (table) { (string) “G:965594188” }, (optional key) emailAddresses= (table) { (string) “friendOne@freemail.com” } } )
Param Table Keys:
(string) message – A message string to send with your friend requests.
(table) playerIDs (optional key) – An array of 1 or more playerID strings of players to send friend requests.
(table) emailAddresses (optional key) – An array of 1 or more email address strings of players to send friend requests.
Callback Events: none
|
1 2 3 4 5 6 7 8 9 10 11 12 13 |
-- mock data mockFriendOnePlayerID = "G:965594188" mockFriendTwoPlayerID = "G:9125286970" mockFriendOneEmail = "friendOne@freemail.com" mockFriendTwoEmail = "friendTwo@freemail.com" gameKit.show( "gameCenterFriendRequestUI", { message="wanna be my friend?" } ) -- or gameKit.show( "gameCenterFriendRequestUI", { message="Friend me :)", playerIDs= { mockFriendOnePlayerID, mockFriendTwoPlayerID } } ) -- or gameKit.show( "gameCenterFriendRequestUI", { message="lets be friends", emailAddresses= { mockFriendOneEmail, mockFriendTwoEmail } } ) |
Get Friends
Comments: Get Game Center Friends.
Function: (function) get( (string) “friends”, (table) { listener= (function) onPlayerCallback } )
Param Table Keys: (function) listener – A function to receive callback events.
Callback Events:
Event Name: (string) “gameKitLibrary”
Event Type:
(string) “error” – GameKit error event.
(string) “friendList” – Friend list event.
Event Properties:
(number) friendsCount – Number of friend tables in the friends array.
(array) friends – Array of friend tables.
Friend Table Keys:
(string) playerID – A string assigned by Game Center to uniquely identify a player.
(string) alias – A string chosen by the player to identify themselves to other players. A player’s alias is used when a player is not a friend of the local player. Typically, you never display the alias string directly in your user interface. Instead use the displayName.
(string) displayName – A string to display the name for the player. If the player is a friend of the local player, then the display name is the actual name of the player. If the player is not a friend, then the display name is the player’s alias.
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 |
local function onPlayerCallback( event ) if( event.type == "error" ) then print( 'onPlayerCallback event.errorCode = ' .. tostring(event.errorCode) ) print( 'onPlayerCallback event.errorDescription = ' .. event.errorDescription ) elseif( event.type == "friendList" ) then for i = 1, event.friendsCount do print( 'onPlayerCallback friend ' .. tostring(i) .. ' playerID = ' .. event.friends[i].playerID ) print( 'onPlayerCallback friend ' .. tostring(i) .. ' alias = ' .. event.friends[i].alias ) print( 'onPlayerCallback friend ' .. tostring(i) .. ' displayName = ' .. event.friends[i].displayName ) end end return true end gameKit.get( "friends", { listener= onPlayerCallback } ) |
Get Players With PlayerIDs
Comments: Get Game Center Players with PlayerIDs.
Function: (function) get( (string) “playersWithPlayerIDs”, (table) { playerIDs= (table) { (string) “G:2073637149” }, listener= (function) onPlayerCallback } )
Param Table Keys:
(table) playerIDs – An array of 1 or more playerID strings.
(function) listener – A function to receive callback events.
Callback Events:
Event Name: (string) “gameKitLibrary”
Event Type:
(string) “error” – GameKit error event.
(string) “playerList” – Player list event.
Event Properties:
(number) playersCount – Number of player tables in the players array.
(array) players – Array of player tables.
Player Table Keys:
(string) playerID – A string assigned by Game Center to uniquely identify a player.
(string) alias – A string chosen by the player to identify themselves to other players. A player’s alias is used when a player is not a friend of the local player. Typically, you never display the alias string directly in your user interface. Instead use the displayName.
(string) displayName – A string to display the name for the player. If the player is a friend of the local player, then the display name is the actual name of the player. If the player is not a friend, then the display name is the player’s alias.
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 |
-- mock data, get real playerIDs from Game Center mockPlayerOneID = "G:2073637149" mockPlayerTwoID = "G:9125286970" local function onPlayerCallback( event ) if( event.type == "error" ) then print( 'onPlayerCallback event.errorCode = ' .. tostring(event.errorCode) ) print( 'onPlayerCallback event.errorDescription = ' .. event.errorDescription ) elseif( event.type == "playerList" ) then for i = 1, event.playersCount do print( 'onPlayerCallback player ' .. tostring(i) .. ' playerID = ' .. event.players[i].playerID ) print( 'onPlayerCallback player ' .. tostring(i) .. ' alias = ' .. event.players[i].alias ) print( 'onPlayerCallback player ' .. tostring(i) .. ' displayName = ' .. event.players[i].displayName ) end end return true end gameKit.get( "playersWithPlayerIDs", { playerIDs={ mockPlayerOneID, mockPlayerTwoID }, listener= onPlayerCallback } ) |
Send Game Center Notification Banner
Comments: Send Game Center Notification Banner to local player’s device.
Function: (function) send( (string) “gameCenterNotificationBanner”, (table) { title= (string) “Game Notification”, message= (string) “This is a notification!”, duration= (number) 10.50, listener= (function) onCallback } )
Param Table Keys:
(string) title – A string title of the notification banner.
(string) message – A string message that is to be displayed to the local player.
(number) duration – A number in seconds of time that the banner should be displayed to the local player.
(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.
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 |
-- mock data mockTitle = "Your Game Notification Title" mockMessage = "This is a notification message!" local function onCallback( event ) if( event.type == "success" ) then print( 'onCallback event.successDescription = ' .. event.successDescription ) end return true end gameKit.send( "gameCenterNotificationBanner", { title=mockTitle, message=mockMessage, duration=10.50, listener=onCallback } ) |