Match Making

Matchmaking (multiplayer) for Xbox Live and UWP requires a bit of configuration, partly via a configuration file which defines what network connections you are going to use, and partly via setup of session templates and matchmaking hoppers on the Xbox Developer Portal. GameMaker Studio 2 supports this through the use of the UWP target and permits you to do the following:

• Create a multiplayer session
• Find (and/or join) a multiplayer session
• Be notified when relevant players join or leave a session, as well as receive their network connection details
• Be notified when the session host migrates to a different user
• Get a list of users in the session
• Leave a session

Xbox Live network connectivity relies on something called a Secure Device Association, which is basically a contract defining exactly how the device connects to other devices and what sort of data it is able to communicate using that connection. These are configured using a file which you need to include in your project. You can find an example of this file here. The main important points in the file are the protocol and port numbers for each socket description, as these must match what you actually set up in code.

Once you have created this network manifest file, it should be added to the project as an included file. Then, inside the UWP Game Options, in the Xbox One General tab, it should be selected in the "Included File for Network Config Manifest" combo box.

To create a multiplayer session, you need to specify what Session Template is going to be used. These session templates are defined on the XDP, but an example is shown below:

Session Name: MatchSession
Contract Version: 107
Session Template (JSON text):
    {
    "constants": {
        "system": {
            "version": 1,
            "maxMembersCount": 12,
            "capabilities": {
            },
            "memberInitialization": {
                "externalEvaluation": false,
                "membersNeededToStart": 1
                }
            },
        "custom": {}
        }
    }

A description of the fields can be found in "Session Overview" in the XDK help file. Note that we currently don't support setting session parameters dynamically from GameMaker Studio 2.

Along with the session template, a matchmaking hopper must also be set up to allow the session to be found (this is also done on the XDP). Hoppers are used to define rules which are used when matching players. As with session parameters, we don't currently support setting hopper parameters dynamically from GameMaker: Studio. See the "SmartMatch Matchmaking Configuration" section in the XDK help file for further details.

The following functions are available for XboxLive matchmaking (note that you will also need to use the GameMaker Studio 2 Networking Functions for the connections etc...):

• xboxlive_matchmaking_start
• xboxlive_matchmaking_stop
• xboxlive_matchmaking_create
• xboxlive_matchmaking_find
• xboxlive_matchmaking_session_get_users
• xboxlive_matchmaking_join_session
• xboxlive_matchmaking_session_leave

GameMaker Studio 2 provides an extra set of matchmaking functions for you to use to invite other players on the network to join a session, or for you to accept an invitation to join someone else's session. The functions available are:

• xboxlive_matchmaking_send_invites
• xboxlive_matchmaking_set_joinable_session
• xboxlive_matchmaking_join_invite

When the player accepts an invitation from another player, one of two things happens:

• If your game is currently running, you will receive a Social Asynchronous Event with async_load DS map containing the following keys/values:
  • "id" - This will be set to MATCHMAKING_INVITATION.
  • "invitation_id" - This is the unique session ID value
  • "invitation_host" - This is the unique session ID value for the session host
  You should save the ID and Host values then leave any sessions you need to, and call the function xboxlive_matchmaking_join_invite(), passing in as arguments the invitation ID and invitation host values in a Step event.
• If your game is not currently running, it will be started by the OS. You will receive the same type of Social Asynchronous Event with the same keys set as those listed above. Save them to variables, then connect to Xbox Live matchmaking and finally call xboxlive_matchmaking_join_invite().

Once you have called xboxlive_matchmaking_join_invite() the user will attempt to join the session and you will receive Asynchronous Social Events as if you had called xboxlive_matchmaking_find() on this session.