Configure Multiplayer Session Templates (Service Configuration)

This topic provides procedures for adding and changing multiplayer session templates in the service configuration for a title.

For more information about session templates, see “JavaScript Object Notation (JSON) Object Reference” in the documentation for the Xbox One XDK or the Xbox One Application Development Kit, depending on your access. This topic is available in the XDK documentation and in the ADK documentation on the Xbox Game Developer (XGD) site.

For an overall introduction to the various elements of the service configuration, see Introducing Service Configuration.

Sections in this topic:

What is a multiplayer session template?

The Xbox multiplayer service allows gamers to create and join sessions, to exchange session messages with other gamers in the same session, and to post the results of their play to the session. (Posting the results cleans up the session, and also updates the leaderboards for all players in the session.)

For example, a multiplayer session could be a single game of chess between two players. Alternatively, it could be a continuing session of an action and adventure title played by a much larger number of players.

For more info about multiplayer session templates, see “Session Templates” under “Xbox Live and Online Services” in the Xbox One XDK documentation.

Create a multiplayer session template

To create a new multiplayer session template

  1. On the Multiplayer & Matchmaking page for the product instance, if the Add New Session dialog box is not already displayed, click New under Session Templates to display it.
  2. In the dialog box, in the following fields, specify the values that you want.
    • Session Name - Enter a name that characterizes the multiplayer session template, and that you will easily remember and recognize.
      The name must be a text string, with a maximum of 128 characters.
    • Contract Version - This value is auto-populated by the system and denotes the current system version of the JSON contract. Do not edit it.
    • Session Template (JSON text) - Specify the JSON data that describes the different attributes associated with a multiplayer session.
  3. When you have all of the fields and values for your new multiplayer session template the way that you want them, click Add Session to create the session template and close the dialog box.

Your new multiplayer session template is now listed on the Multiplayer & Matchmaking page.

Change a multiplayer session template

Important After a title passes Final Certification, existing multiplayer sessions in that title can no longer be changed or deleted.

To make changes to an existing multiplayer session template

  1. On the Multiplayer & Matchmaking page, under Session Templates, click the Edit icon for the session template that you want to make changes to.
  2. In the Edit Session dialog box, make the changes that you want.
  3. When all of the options are the way that you want them, click Save Session.

Delete a multiplayer session template

Important After a title passes Final Certification, existing multiplayer sessions in that title can no longer be changed or deleted.

To delete an existing multiplayer session template

  1. On the Multiplayer & Matchmaking page, under Session Templates, click the Delete icon for the session template that you want to delete.
  2. In the Delete Session dialog box, confirm the deletion by clicking Delete.

    Important Deletion of a session is a permanent action and can’t be undone or reversed.

Set up multiplayer session templates to enable tournaments

To enable tournaments, you will need to set up two multiplayer session templates, one team session template and one game session template. The team session template will have the team capability-it can set team sizes and includes title-specific attributes for teams. The game session template will have the arbitration capability-it sets timer values for match forfeits and includes title-specific attributes for matches.

To set up these templates, you just need to create new session templates by following the steps in this topic, and then modify their Session Template (JSON text) fields appropriately. Below are some examples of team and game session templates.

Example team session template

{
  "constants": {
    "system": {
      "version": 1,
      "maxMembersCount": 1,
      "visibility": "open",
      "inviteProtocol": "game",
      "capabilities": {
        //team capability must be set for session
        "team": true,
        "gameplay": false,
        "userAuthorizationStyle": true,
        "crossPlay": true
      },
      "inviteProtocol": "game",
      "reservedRemovalTimeout": 86400000,
      "inactiveRemovalTimeout": 86400000,
      "readyRemovalTimeout": 86400000,
      "sessionEmptyTimeout": 86400000
    },
    "custom": {

    }
  }
}

Example game session template

{
  "constants": {
    "system": {
      "version": 1,
      "maxMembersCount": 2,
      "visibility": "open",
      "inviteProtocol": "game",
      "capabilities": {
        "connectivity": true,
        "connectionRequiredForActiveMembers": true,
        "gameplay": true,
        "userAuthorizationStyle": true,
        "arbitration": true
      },
      "reservedRemovalTimeout": 86400000,
      "inactiveRemovalTimeout": 86400000,
      "readyRemovalTimeout": 86400000,
      "sessionEmptyTimeout": 86400000,
      //arbitrationTimeout and forefeitTimeout must be set for sessions with arbitration capability; arbitrationTimeout should be greater than the forefeitTimeout
      "arbitration": {
        "arbitrationTimeout": 600000,
        "forfeitTimeout": 300000
      }
    },
    "custom": {
    
    }
  }
}

For more information on tournaments, please refer to Getting Started with Xbox Live Tournaments in the Xbox Live SDK documentation.