gameNetwork.show()

Type Function
Library gameNetwork.*
Revision Current Public Release (2017.3068)
Keywords gameNetwork, Game Center
See also gameNetwork.init()
gameNetwork.request()

Overview

Displays the requested game network information to the user.

Syntax

gameNetwork.show( command [, params ] )
command (required)

String. String value as supported by Game Center.

  • "leaderboards"
  • "achievements"
  • "friendRequest"
  • "matches"
  • "createMatch"
params (optional)

Table. Table of parameters allowed by Game Center — see the next section for details.

Parameter Reference

Depending on the specified command parameter, the contents of the params table will vary.

Listener Function

For all calls to gameNetwork.show(), the params table supports a listener key with its value as a callback function to monitor the call result, for example:

gameNetwork.show( "achievements", { listener=showAchievements } )

Achievements

For the command parameter of "achievements", this function shows the player's completed achievements for the app.

gameNetwork.show( "achievements", { listener=showAchievements } )

Leaderboards

For the command parameter of "leaderboards", "leaderboard" is an optional key in the params table which in turn accepts another table. This table may contain the following optional keys:

  • "category" — The leaderboard to show.
gameNetwork.show( "leaderboards",
    {
        leaderboard = {
            category = "com.appledts.EasyTapList"
        },
        listener = showLeaders
    }
)

Friend Request

For the command parameter of "friendRequest", the params table may contain the following optional keys:

  • message — String value which pre-populates the message field with custom text.

  • playerIDs — Array of strings of Game Center player IDs representing the players you want to send a friend request to.

  • emailAddresses — Array of strings representing email addresses of players you want to send a friend request to.

local parameters = {
    message = "Be my friend please",
    playerIDs = { "G:194669300", "G:1435127232" },
    emailAddresses = { "me@me.com" },
    listener = requestFriends
}
gameNetwork.show( "friendRequest", parameters )

Note that the total number of player IDs and email addresses must not exceed the Game Center maximum limit or the OS will throw an exception. You can read this limit by calling gameNetwork.request( "loadFriendRequestMaxNumberOfRecipients" ).

Matches

For the command parameter of "matches", this function shows the current/active matches and allows the player to create a new match from the same interface screen. The following keys are accepted in the params table:

  • minPlayers — Number which specifies the minimum number of players in a multiplayer game.

  • maxPlayers — Number which specifies the maximum number of players in a multiplayer game.

  • playerGroup — An arbitrary number used to auto-match only players whose match request shares the same number. Setting this property to 0 allows the player to be auto-matched into any waiting match.

  • playerAttributes — Mask that specifies the role that the local player would like to play in the game.

local parameters = {
    minPlayers = 2,
    maxPlayers = 3,
    playerGroup = 0,
    playerAttributes = { 1, 4, 6 },
    listener = showMatches
}
gameNetwork.show( "matches", parameters )

Create Match

For the command parameter of "createMatch", this function shows the Game Center interface screen which allows players to create/manage a match. The following keys are accepted in the params table:

  • playerIDs — Optional array of strings representing the player IDs of people to initially invite to the match.

  • minPlayers — Optional value for the minimum number of players required in the match.

  • maxPlayers — Optional value for the maximum number of players allowed in the match.

  • playerGroup — An arbitrary number used to auto-match only players whose match request shares the same number. Setting this property to 0 allows the player to be auto-matched into any waiting match.

  • playerAttributes — Mask that specifies the role that the local player would like to play in the game.

  • inviteMessage — Custom invitation message for the match.

local parameters = {
    playerIDs = { "w4o98y3498hg349h", "wrighfq547hg543" },
    minPlayers = 2,
    maxPlayers = 3,
    playerGroup = 0,
    playerAttributes = { 1, 4, 6 },
    inviteMessage = "Hi, please join our match!",
    listener = createNewMatch
}
gameNetwork.show( "createMatch", parameters )

Example

local function onGameNetworkPopupDismissed( event )
    -- Game Center popup was closed
    for k,v in pairs( event ) do
        print( k,v )
    end
end

-- Display a leaderboard
gameNetwork.show( "leaderboards",
    {
        leaderboard = {
            category = "com.appledts.EasyTapList"
        },
        listener = onGameNetworkPopupDismissed
    }
)

-- Display the player's achievements
gameNetwork.show( "achievements", { listener=onGameNetworkPopupDismissed } )

-- Display a friend request popup
local friendRequestParams = {
    message = "Let's match up in Game Center!",
    playerIDs = { "G:194669300", "G:1435127232" },
    emailAddresses = { "me@me.com" },
    listener = onGameNetworkPopupDismissed
}
gameNetwork.show( "friendRequest", friendRequestParams )

-- Display a popup which shows the current/active matches AND allows the player to create a new match
local matchesParams = {
    minPlayers = 2,
    maxPlayers = 3,
    listener = onGameNetworkPopupDismissed
}
gameNetwork.show( "matches", matchesParams )

-- Display a popup which lets the user create a new match and invite other players
local createMatchParams = {
    playerIDs = { "w4o98y3498hg349h", "wrighfq547hg543" },
    minPlayers = 2,
    maxPlayers = 3,
    inviteMessage = "Hi, please join our match!",
    listener = onGameNetworkPopupDismissed
}
gameNetwork.show( "createMatch", createMatchParams )