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.