Key Concepts

• Maintenance mode is scheduled by an operator on the Game Backend through the LiveOps Dashboard.
• The operator can optionally set an estimated duration for maintenance mode.
• MetaplaySDK.MaintenanceMode can be polled for information on scheduled maintenance events.
• MetaplaySDK.MaintenanceModeChanged event is invoked in-game client whenever a scheduled maintenance event is posted, removed, or changed on the backend.
• Game Backend will automatically go into maintenance mode when the scheduled time arrives or if Backend is shut down for (unscheduled) maintenance.
• When maintenance mode is active, game clients will not be able to connect to the Game Backend - the connections will fail with ConnectionStates.TerminalError.InMaintenance.

Handling of Maintenance Mode in Game Code

Retrieving Current State

MetaplaySDK contains a static member variable, MaintenanceMode, that can be queried to determine whether maintenance mode is currently scheduled on the backend. The MaintenanceMode.Status is NotScheduled no maintenance has been scheduled, Upcoming if a maintenance break has been scheduled but it has not started yet, and Ongoing is the maintenance mode is determined to be currently ongoing. If the maintenance has been scheduled or is ongoing, the MaintenanceMode contains the start time and, optionally, the estimated duration of the upcoming maintenance event. Polling this value is a simple but effective way to be notified when maintenance mode is scheduled on the Game Backend. A more efficient way is to listen out for MetaplaySDK.MaintenanceModeChanged events by attaching an event handler to the event.

Note that MetaplaySDK.MaintenanceMode only contains hints on a scheduled maintenance mode. In addition to the scheduled maintenance, the game can detect ongoing or unscheduled maintenance by observing ConnectionStates.TerminalError.InMaintenance connection error. For more information on Connection errors, see Connection Management.

The recommended way to monitor the state of maintenance mode is to listen for change events and detect when a connection is closed due to InMaintenance error. You should handle the following cases:

• Initial connection fails with InMaintenance error.

  ⇒ Example Handling: Display "Game is in maintenance" message for player. MetaplaySDK.MaintenanceMode will contain information about the maintenance mode.

• Initial connection succeeds and but connection is later lost with InMaintenance error.

  ⇒ Example Handling: Display "Game is in maintenance" message for player. MetaplaySDK.MaintenanceMode will contain information about the maintenance mode.

• MaintenanceModeChanged event is invoked.

  • MetaplaySDK.MaintenanceMode.State is Upcoming An upcoming maintenance break has been scheduled or changed.

    ⇒ Example Handling: show "Maintenance break in N seconds" warning and a countdown timer in the game UI.

    • MetaplaySDK.MaintenanceMode.State is NotScheduled An upcoming maintenance break has been cancelled.

      ⇒ Example Handling: hide the warning in the countdown UI, if any.
      

    • MetaplaySDK.MaintenanceMode.State is Ongoing Maintenance is currently ongoing. This can only happen together with InMaintenance error.

      ⇒ Example Handling: Nothing, we handle this with `InMaintenance` error path above.
      

Example implementation of showing a warning for upcoming maintenance:

// In your gameobject
void Start()
{
    OnMaintenanceModeChanged()
    MetaplaySDK.MaintenanceModeChanged += OnMaintenanceModeChanged;
}

void OnDestroy()
{
    // When gameobject is destroyed, remember to clean up
    MetaplaySDK.MaintenanceModeChanged -= OnMaintenanceModeChanged;
}

void OnMaintenanceModeChanged()
{
    // If NotScheduled, don't show warning
    // If Upcoming, show a warning
    // If Ongoing, the connection error handler will take care of it.

    switch (MetaplaySDK.MaintenanceMode.Status)
    {
        case MetaplaySDK.MaintenanceModeState.ScheduleStatus.NotScheduled:
            warningUI.SetEnabled(false);
            break;

        case MetaplaySDK.MaintenanceModeState.ScheduleStatus.Upcoming:
            warningUI.SetEnabled(true);

            // Due to undefined script running order, we are not guaranteed to
            // get Update() after this one. Update UI manually to have good
            // values on the first frame.
            UpdateUI();
            break;
    }
}

void Update()
{
    if (hasVisibleWarningUI)
        UpdateUI();
}

void UpdateUI()
{
    // If we want to show a countdown, we could update it here.
    // We could also ignore the change listeners and just poll
    // MetaplaySDK.MaintenanceMode value.

    MetaTime now = MetaTime.Now;
    MetaDuration durationToMaintenanceStart = MetaplaySDK.MaintenanceMode.MaintenanceStartAt - now;

    // Note that can be slightly in the past when maintenance is starting, and
    // durationToMaintenanceStart can become negative.
    warningUI.countdownText = durationToMaintenanceStart.ToString();
}

Example implementation of connection error handling:

// Once every frame, preferably after MetaplaySDK.Update()

ConnectionState connectionState = MetaplaySDK.Connection.State;
if (connectionState == ConnectionStatus.Error)
{
    // handle other errors..
    ... else if (connectionState is ConnectionStates.TerminalError.InMaintenance)
    {
        // Show "Ongoing Maintenance" message. Note that this can happen both during
        // the initial loading and during the game session. If game switches a scene
        // when connection completes, the available UI game objects may be different
        // in these cases. You should handle both cases.
        ShowOngoingMaintenanceModeError();

        // Ack the error
        MetaplaySDK.Connection.Close(flushEnqueuedMessages: false);
    }
}

INFO

Protip: You may want to periodically try reconnecting during maintenance mode so that the player automatically rejoins when maintenance mode ends. If you do, then you will want to use a long timeout (say, 60 seconds) between retries so that the server doesn't get overloaded by clients joining at the same time as it comes back online.

Information For Your Players

Inside the game client's MaintenanceMode object you can find fields containing useful information which you may choose to show to the player:

• MaintenanceStartAt - The time at which Maintenance Mode did or will begin, stored as a MetaTime.
• EstimatedMaintenanceOverAt - If EstimatedMaintenanceOverAt is is not null, it contains the estimated time at which maintenance will or should have been over.

INFO

The operator may not always set an estimated time for the duration of maintenance mode, so you should not rely on EstimatedMaintenanceOverAt being available.

Preventing Player Actions

Displaying a warning to your players in the UI is a good start, but it is also advisable to prevent them from starting actions that they may not be able to complete before the maintenance mode activates, eg: starting a new game.

This can easily be achieved with something like the following code:

bool CanStartNewGame()
{
    if (MetaplaySDK.MaintenanceMode.Status == MetaplaySDK.MaintenanceModeState.ScheduleStatus.NotScheduled)
    {
        // No maintenance scheduled - Allow.
        return true;
    }
    else
    {
        // Maintenance is scheduled, but how far away is it?
        // Note that timeUntilMaintenance can become negative since starting maintenance takes a bit time.
        MetaTime now = MetaTime.Now;
        MetaDuration timeUntilMaintenance = MetaplaySDK.MaintenanceMode.MaintenanceStartAt - now;

        // Don't allow new game if backend will go down in 5 minutes or less.
        return timeUntilMaintenance < MetaDuration.FromMinutes(5)
    }
}

INFO

Protip: Remember to make it clear to the player why they are not being allowed to start a new game.