Multiplayer Status

Introduction

When a player opens the Online menu, a multiplayer status check is performed. This check must succeed, otherwise multiplayer will not function. The status response may also include scheduled maintenance announcements.

MultiplayerCore extends the base game's master server status check. It allows additional fields to be included in the status response from modded master servers. These fields can define configuration values, and specify custom server capabilities. Multiplayer mods can then access this configuration through MultiplayerCore.

Basic Status

URL Structure

Example URL structure (official server status):

https://graph.oculus.com/beat_saber_multiplayer_status?access_token=OC%7C2448060205267927%7C&service_environment=ProductionB

The query parameters are static and provied by the game's network config (NetworkConfigSO). The service environment varies between game versions.

Response

The server status endpoint provides a JSON response:

{
   "data": [
      {
         "minimum_app_version": "1.35.0",
         "status": 0,
         "maintenance_start_time": 0,
         "maintenance_end_time": 0,
         "use_gamelift": true,
         "use_xplatform_auth": true
      }
   ]
}

Fields

JSON Field	Description	Default
minimum_app_version	Minimum game version (without _suffix)	null (skip check)
status	AvailabilityStatus: Online = 0, MaintenanceUpcoming = 1, Offline = 2	0 (Online)
maintenance_start_time	Unix timestamp (UTC) that specifies the start of maintenance window	0 (no maintenance)
maintenance_end_time	Unix timestamp (UTC) that specifies the end of the maintenance window	0 (no maintenance)
user_message	Array of localized messages, only shown in case of active maintenance	null (no custom error)
use_gamelift	(Legacy field) This value is ignored	true
use_xplatform_auth	Feature flag: use cross-platform auth tokens in GameLift requests (as opposed to single use platform tokens)	true

Status Checks

The base game performs the following status checks:

• If the status request fails or no (valid) response is returned, the multiplayer status check will fail with MUR-1 (NetworkUnreachable).
  • MultiplayerCore disables this check; an empty response is considered valid.
• If the status field is set to 2 (Offline), the multiplayer status check will fail with MUR-3 (ServerOffline).
• If minimum_app_version is provided, and the game version is lower than its value, the multiplayer status check will fail with MUR-2 (UpdateRequired).
• If the status field is set to 1 (MaintenanceUpcoming), and both maintenance_start_time and maintenance_end_time are set, and the curent time falls within the maintenance window, the multiplayer status check will fail with MUR-4 (MaintenanceMode).

Extended Status Fields

MultiplayerCore understands various custom fields that may be included in the status response. These fields are all optional, and default to null / false / empty.

JSON Field	Type	MpCore version	Description
required_mods	RequiredMod[]	1.1.0+	🔧 Handled by MultiplayerCore. If defined, and if a mod with a bad version is found, the multiplayer status check fails and MUR-5 is returned.
maximum_app_version	string	1.2.0+	🔧 Handled by MultiplayerCore. If defined, and if the current game version exceeds this version, the multiplayer status check fails and MUR-6 is returned.
use_ssl	bool	1.5.0+	ℹ️ Information only. Indicates whether dedicated server connections should use SSL/TLS. Currently, most modded multiplayer servers do not use encryption.
name	string	1.5.0+	ℹ️ Information only. Master server display name.
description	string	1.5.0+	ℹ️ Information only. Master server display description.
image_url	string	1.5.0+	ℹ️ Information only. Master server display image URL.
max_players	int	1.5.0+	ℹ️ Information only. Maximum player count when creating new lobbies.
supports_pp_modifiers	bool	1.5.0+	ℹ️ Information only. Server capability: per-player modifiers.
supports_pp_difficulties	bool	1.5.0+	ℹ️ Information only. Server capability: per-player difficulties.
supports_pp_maps	bool	1.5.0+	ℹ️ Information only. Server capability: per-player level selection.

RequiredMod

JSON Field	Type	Description
id	string	BSIPA Mod ID
version	string	Minimum version of the mod required, if installed
required	bool	Indicates whether the mod must be installed

Multiplayer Unavailable Reasons (MURs)

A combined overview of all MUR error codes that currently exist:

MUR	Source	Name	Error message
MUR-1	Base game	NetworkUnreachable	Multiplayer Unavailable Check your internet connection and try again
MUR-2	Base game	UpdateRequired	Multiplayer Unavailable Beat Saber update is required
MUR-3	Base game	ServerOffline	Multiplayer Unavailable Server is offline
MUR-4	Base game	MaintenanceMode	Multiplayer Unavailable Maintenance ends at {0}
MUR-5	MultiplayerCore	(requiredMods check)	Multiplayer Unavailable Mod {0} is missing or out of date Please update to version {1} or newer
MUR-6	MultiplayerCore	(maximumAppVersion check)	Multiplayer Unavailable Beat Saber version is too new Maximum version: {0} Current version: {1}