Session template constants

This topic describes the predefined elements of a multiplayer session template, based on the session template version 107. These elements define settings for a multiplayer session. Contents

system
capabilities
metrics
memberInitialization
peerToPeerRequirements
peerToHostRequirements
measurementServerAddresses
cloudComputePackage (deprecated)
arbitration (deprecated)
broadcastViewerTitleIds
ownershipPolicies

system

System constant	Description	Valid values	Default value
`version`	The version of the session template.	1 - n	none
`maxMembersCount`	The number of total session member slots supported for the multiplayer activity.	1 - 100 for a normal session, 101+ for a large session	100
`visibility`	The visibility state of the session, which indicates if other users can see or join the session.	”private”, “visible”, “open"	"open”
`inviteProtocol`	Setting this constant to “game” enables invitees to receive notification when they’re invited to the session.	”game”, “tournamentgame”, “chat”, “gameparty”	none
`reservedRemovalTimeout`	The time-out for a member reservation, in milliseconds. A value of 0 indicates an immediate time-out. A value of `null` is considered infinite.	0 - n, `null`	30000
`inactiveRemovalTimeout`	The time-out for a member to be considered inactive, in milliseconds. A value of 0 indicates an immediate time-out. A value of `null` is considered infinite.	0 - n, `null`	0
`readyRemovalTimeout`	The time-out for a member to be considered ready, in milliseconds. A value of 0 indicates an immediate time-out. A value of `null` is considered infinite.	0 - n, `null`	180000
`sessionEmptyTimeout`	The time-out for an empty session, in milliseconds. A value of 0 indicates an immediate time-out. A value of `null` is considered infinite.	0 - n, `null`	0
`capabilities`	Specifies the capabilities of the session. For more information, see the capabilities section later in this topic.	Not applicable	Not applicable
`metrics`	Specifies a set of title-defined Quality of Service (QoS) requirements, such as latency and bandwidth speed, that members in the session must satisfy. For more information, see the metrics section later in this topic.	Not applicable	Not applicable
`memberInitialization`	Specifies the time-outs and initialization requirements that are enforced when new members join the session. For more information, see the `memberInitialization` section later in this topic.	Not applicable	Not applicable
`peerToPeerRequirements`	Specifies the network QoS requirements for peer-to-peer mesh connections. For more information, see the peerToPeerRequirements section later in this topic.	Not applicable	Not applicable
`peerToHostRequirements`	Specifies the network QoS requirements for peer-to-host connections. For more information, see the peerToHostRequirements section later in this topic.	Not applicable	Not applicable
`measurementServerAddresses`	Specifies a collection of potential datacenters that are used to determine QoS measurements. For more information, see the measurementServerAddresses section later in this topic.	Not applicable	Not applicable
`cloudComputePackage` (deprecated)	Specifies the properties of the XBOX Live Compute cloud package to allocate. For more information, see the cloudComputePackage section later in this topic.	Not applicable	Not applicable
`arbitration` (deprecated)	Specifies the time-outs for members to submit arbitration results in tournaments. For more information, see the arbitration (deprecated) section later in this topic.	Not applicable	Not applicable
`broadcastViewerTitleIds`	Specifies a list of title IDs that should always have read access to the session. For more information, see the broadcastViewerTitleIds section later in this topic.	Not applicable	Not applicable
`ownershipPolicies`	Specifies the policies relating to session ownership. For more information, see the ownershipPolicies section later in this topic.	Not applicable	Not applicable

Return to the top of this topic.

capabilities

Capabilities are Boolean values that are optionally set in the session template. If no capabilities are needed, an empty capabilities property should be set in the template to prevent capabilities from being specified on session creation, unless the title needs dynamic session capabilities.

Capability	Description	Valid values	Default value
`connectivity`	Indicates if the session supports peer connectivity. If this value is `false`, the session can’t enable any metrics and the session members can’t set `secureDeviceAddress`. This capability can’t be set on large sessions.	`true`, `false`	`false`
`suppressPresenceActivityCheck`	If `true`, turns off presence checks.	`true`, `false`	`false`
`gameplay`	Indicates whether the session represents actual gameplay, as opposed to setup or menu time such as a lobby or matchmaking. If `true`, the session is in gameplay mode.	`true`, `false`	`false`
`large`	Indicates if the session is a large session (more than 100 members). Large sessions aren’t supported for use with Multiplayer Manager.	`true`, `false`	`false`
`connectionRequiredForActiveMembers`	Indicates if a connection is required for a member to be active.	`true`, `false`	`false`
`cloudCompute` (deprecated)	Enables clients to request that a cloud compute instance be allocated on behalf of the session. Deprecated because XBOX Live Compute is no longer available as a service.	`true`, `false`	`false`
`autoPopulateServerCandidates`	Automatically calculate and set `serverConnectionStringCandidates` from `serverMeasurements`. This capability can’t be set on large sessions.	`true`, `false`	`false`
`userAuthorizationStyle`	Indicates if the session supports calls from platforms without strong title identity. This capability can’t be set on large sessions.

Setting the userAuthorizationStyle capability to true causes the session defaults for readRestriction and joinRestriction to local instead of none. This means that titles must use search handles or transfer handles to join a game session. | true, false | false crossPlay | Indicates that the session supports crossplay between Windows PC, XBOX One, or XBOX Series devices. | true, false | true broadcast | Indicates that the session represents a broadcast. The name of the session must be the xuid of the broadcaster. Requires the large capability. | true, false | false team | Indicates that the session represents a tournament team. This capability can’t be set on large or gameplay sessions. | true, false | false arbitration | Indicates that the session must be created by a service principal that adds the arbitration server entry. Requires gameplay but can’t be set on large sessions. | true, false | false hasOwners | Indicates that the session has a security policy based on certain members being owners. | true, false | false searchable | Indicates that the session can be a target session of a search handle. If the userAuthorizationStyle and searchable capabilities are set, hasOwners must also be set. | true, false | false

Example: capabilities

"capabilities": {
    "connectivity": true,  
    "suppressPresenceActivityCheck": true,
    "gameplay": true,
    "large": true,
    "connectionRequiredForActiveMembers": true,
    "cloudCompute": true,
    "autoPopulateServerCandidates": true,
    "userAuthorizationStyle": true,
    "crossPlay": true,  
    "broadcast": true,  
    "team": true,
    "arbitration": true,
    "hasOwners": true,
    "searchable": true  
},

Return to the top of this topic.

metrics

If the metrics properties aren’t specified, they default to the values that are needed to satisfy the QoS requirements. If the metrics properties are specified, the values must be sufficient to satisfy the QoS requirements. This element is only valid if the session has the connectivity capability set.

Metric	Description	Valid values	Default value
`latency`	Indicates if `latencyMaximum` is specified in the session template	`true`, `false`	See this description.
`bandwidthDown`	Indicates if `bandwidthDownMinimum` is specified in the session template	`true`, `false`	See this description.
`bandwidthUp`	Indicates if `bandwidthUpMinimum` is specified in the session template	`true`, `false`	See this description.
`custom`	Indicates if custom metrics are specified in the session template	`true`, `false`	See this description.

Example: metrics

"metrics": {
    "latency": true,
    "bandwidthDown": true,
    "bandwidthUp": true,
    "custom": true
},

Return to the top of this topic.

memberInitialization

If the memberInitialization property is set, the session expects the client system or title to perform initialization following session creation or as new members join the session. The time-outs and initialization stages are automatically tracked by the session, including QoS measurements if any metrics are set. These time-outs override the session’s reservation and ready time-outs for members that have initializationEpisode set. memberInitialization can’t be specified on large sessions.

Element	Description	Valid values	Default value
`joinTimeout`	Indicates the number of milliseconds that a member has to join the session. Reservations of users who fail to join are removed.

NOTE: The default duration is sufficient for normal title execution, but it might lead to join time-outs if a title is being debugged during the Multiplayer Session Directory (MPSD) flow. While debugging, override and increase this default value for the session.| 0 - n | 10000 measurementTimeout | Indicates the number of milliseconds that a session member has to upload measurements. A member that fails to upload measurements is marked with a failure reason of “timeout”. | 0 - n | 30000 evaluationTimeout | Indicates the number of milliseconds that an external evaluation has to upload measurements. | 0 - n | 5000 externalEvaluation | If true, indicates that the title code performs the evaluation of who can join based on QoS measurements. The multiplayer service doesn’t perform any QoS logic, and the title is responsible for advancing the initialization stage. Titles don’t typically need this. | true, false | false membersNeededToStart | The number of members needed to start the session only for initialization episode zero. | 1 - maxMembersCount | 1

Example: memberInitialization

"memberInitialization": {
    "joinTimeout": 10000,
    "measurementTimeout": 30000,
    "evaluationTimeout": 5000,
    "externalEvaluation": false,
    "membersNeededToStart": 1
},

Return to the top of this topic.

peerToPeerRequirements

Peer-to-peer network requirements	Description	Default value
`latencyMaximum`	The maximum latency, in milliseconds, between any two clients	250
`bandwidthMinimum`	The minimum bandwidth, in kilobits per second, between any two clients	10000

Example: peerToPeerRequirements

"peerToPeerRequirements": {
    "latencyMaximum": 250,
    "bandwidthMinimum": 10000
},

Return to the top of this topic.

peerToHostRequirements

Peer-to-host network requirements	Description	Valid values	Default value
`latencyMaximum`	The maximum latency, in milliseconds, for the peer to host connection		250
`bandwidthDownMinimum`	The minimum bandwidth, in kilobits per second, for information sent from the host to the peer		100000
`bandwidthUpMinimum`	The minimum bandwidth, in kilobits per second, for information sent from the peer to the host		1000
`hostSelectionMetric`	Indicates which metric is used to select the host	”bandwidthup”, “bandwidthdown”, “bandwidth”, and “latency"	"latency”

Example: peerToHostRequirements

"peerToHostRequirements": {
    "latencyMaximum": 250,
    "bandwidthDownMinimum": 100000,
    "bandwidthUpMinimum": 1000,
    "hostSelectionMetric": "bandwidthup"
},

Return to the top of this topic.

measurementServerAddresses

The set of potential server connection strings that should be evaluated. The connection strings must be lowercase. measurementServerAddresses can’t be specified on large sessions. The connection strings are defined in the following format. "<server name>": { "secureDeviceAddress": <device address> } where the device address is the base-64-encoded secure device address of the server.

Example: measurementServerAddresses

"measurementServerAddresses": {
    "server farm a": {
        "secureDeviceAddress": "r5Y="
    },
    "datacenter b": {
        "secureDeviceAddress": "rwY="
    }
},

Return to the top of this topic.

cloudComputePackage (deprecated)

This property is deprecated because the XBOX Live Compute service is no longer available and has been discontinued. Specifies the properties of the cloud compute package to allocate. Requires that the cloudCompute capability is set.

Property	Description
`titleId`	Indicates the title ID of the cloud compute package to allocate
`gsiSet`	Indicates the Global Security Infrastructure (GSI) set of the cloud compute package to allocate
`variant`	Indicates the variant of the cloud compute package to allocate

Example: cloudComputePackage

"cloudComputePackage": {
    "titleId": "4567",
    "gsiSet": "128ce92a-45d0-4319-8a7e-bd8e940114ec",
    "variant": "30ebca60-d96e-4629-930b-6957aa6bfbfa"
},

Return to the top of this topic.

arbitration (deprecated)

This property is deprecated because the XBOX Live Compute service is no longer available and has been discontinued. Specifies the time-outs for the arbitration process. Requires that the arbitration capability is set. The arbitration start time is defined in a session in the /servers/arbitration/constants/system/startTime element.

Time-out	Description	Valid values	Default value
`forfeitTimeout`	Indicates the time, in milliseconds, from the arbitration start time.	0 - n	60000
`arbitrationTimeout`	Indicates the time, in milliseconds, from the arbitration start time, that the arbitration result times out. This value can’t be less than the `forfeitTimeout` value.	0 - n	300000

Example: arbitration

"arbitration": {
    "forfeitTimeout": 60000,
    "arbitrationTimeout": 300000
},

Return to the top of this topic.

broadcastViewerTitleIds

Specifies an array of the title IDs of the titles that should always have read access to the broadcast session.

Example: broadcastViewerTitleIds

"broadcastViewerTitleIds" : ["34567", "8910"],

Return to the top of this topic.

ownershipPolicies

Specifies how to handle a session when the last owner leaves the session. Requires that the hasOwners capability is set.

Ownership policy	Description	Valid values	Default value
`migration`	Indicates what happens when the last owner leaves the session. If the migration policy is set to “endsession”, expire the session. If the migration policy is set to “oldest”, select the member with the oldest join time to become the new owner of the session.	”oldest”, “endsession"	"endsession”
`allowNonOwnerInviteHandles`	Indicates invite behavior for session members that aren’t the owner. By default, non-owners can’t send invites for a session.	`true`, `false`	`false`
`nonOwnerModifiableSystemProperties`	A list of system property names that non-owners can modify on sessions with capability `hasOwners` set to `true`.	List of system property names	Not applicable

Example: ownershipPolicies

"ownershipPolicies": {
     "migration": "oldest",
     "allowNonOwnerInviteHandles": true,
     "nonOwnerModifiableSystemProperties": ["joinRestriction", "closed"] 
}

Return to the top of this topic.

XBOX Services

PlayFab

system

capabilities

Example: capabilities

metrics

Example: metrics

memberInitialization

Example: memberInitialization

peerToPeerRequirements

Example: peerToPeerRequirements

peerToHostRequirements

Example: peerToHostRequirements

measurementServerAddresses

Example: measurementServerAddresses

cloudComputePackage (deprecated)

Example: cloudComputePackage

arbitration (deprecated)

Example: arbitration

broadcastViewerTitleIds

Example: broadcastViewerTitleIds

ownershipPolicies

Example: ownershipPolicies

​system

​capabilities

​Example: capabilities

​metrics

​Example: metrics

​memberInitialization

​Example: memberInitialization

​peerToPeerRequirements

​Example: peerToPeerRequirements

​peerToHostRequirements

​Example: peerToHostRequirements

​measurementServerAddresses

​Example: measurementServerAddresses

​cloudComputePackage (deprecated)

​Example: cloudComputePackage

​arbitration (deprecated)

​Example: arbitration

​broadcastViewerTitleIds

​Example: broadcastViewerTitleIds

​ownershipPolicies

​Example: ownershipPolicies

system

capabilities

Example: capabilities

metrics

Example: metrics

memberInitialization

Example: memberInitialization

peerToPeerRequirements

Example: peerToPeerRequirements

peerToHostRequirements

Example: peerToHostRequirements

measurementServerAddresses

Example: measurementServerAddresses

cloudComputePackage (deprecated)

Example: cloudComputePackage

arbitration (deprecated)

Example: arbitration

broadcastViewerTitleIds

Example: broadcastViewerTitleIds

ownershipPolicies

Example: ownershipPolicies