Merge pull request #11127 from peppy/realtime-multiplayer

Add client-side models and interfaces required for multiplayer

osu.Game/Online/Multiplayer/RoomCategory.cs

@@ -6,6 +6,7 @@ namespace osu.Game.Online.Multiplayer
     public enum RoomCategory
     {
         Normal,
-        Spotlight
+        Spotlight,
+        Realtime,
     }
 }

osu.Game/Online/RealtimeMultiplayer/IMultiplayerClient.cs

@@ -0,0 +1,65 @@
+// Copyright (c) ppy Pty Ltd <contact@ppy.sh>. Licensed under the MIT Licence.
+// See the LICENCE file in the repository root for full licence text.
+
+using System.Threading.Tasks;
+
+namespace osu.Game.Online.RealtimeMultiplayer
+{
+    /// <summary>
+    /// An interface defining a multiplayer client instance.
+    /// </summary>
+    public interface IMultiplayerClient
+    {
+        /// <summary>
+        /// Signals that the room has changed state.
+        /// </summary>
+        /// <param name="state">The state of the room.</param>
+        Task RoomStateChanged(MultiplayerRoomState state);
+
+        /// <summary>
+        /// Signals that a user has joined the room.
+        /// </summary>
+        /// <param name="user">The user.</param>
+        Task UserJoined(MultiplayerRoomUser user);
+
+        /// <summary>
+        /// Signals that a user has left the room.
+        /// </summary>
+        /// <param name="user">The user.</param>
+        Task UserLeft(MultiplayerRoomUser user);
+
+        /// <summary>
+        /// Signal that the host of the room has changed.
+        /// </summary>
+        /// <param name="userId">The user ID of the new host.</param>
+        Task HostChanged(long userId);
+
+        /// <summary>
+        /// Signals that the settings for this room have changed.
+        /// </summary>
+        /// <param name="newSettings">The updated room settings.</param>
+        Task SettingsChanged(MultiplayerRoomSettings newSettings);
+
+        /// <summary>
+        /// Signals that a user in this room changed their state.
+        /// </summary>
+        /// <param name="userId">The ID of the user performing a state change.</param>
+        /// <param name="state">The new state of the user.</param>
+        Task UserStateChanged(long userId, MultiplayerUserState state);
+
+        /// <summary>
+        /// Signals that a match is to be started. This will *only* be sent to clients which are to begin loading at this point.
+        /// </summary>
+        Task LoadRequested();
+
+        /// <summary>
+        /// Signals that a match has started. All users in the <see cref="MultiplayerUserState.Loaded"/> state should begin gameplay as soon as possible.
+        /// </summary>
+        Task MatchStarted();
+
+        /// <summary>
+        /// Signals that the match has ended, all players have finished and results are ready to be displayed.
+        /// </summary>
+        Task ResultsReady();
+    }
+}

osu.Game/Online/RealtimeMultiplayer/IMultiplayerLoungeServer.cs

@@ -0,0 +1,20 @@
+// Copyright (c) ppy Pty Ltd <contact@ppy.sh>. Licensed under the MIT Licence.
+// See the LICENCE file in the repository root for full licence text.
+
+using System.Threading.Tasks;
+
+namespace osu.Game.Online.RealtimeMultiplayer
+{
+    /// <summary>
+    /// Interface for an out-of-room multiplayer server.
+    /// </summary>
+    public interface IMultiplayerLoungeServer
+    {
+        /// <summary>
+        /// Request to join a multiplayer room.
+        /// </summary>
+        /// <param name="roomId">The databased room ID.</param>
+        /// <exception cref="InvalidStateException">If the user is already in the requested (or another) room.</exception>
+        Task<MultiplayerRoom> JoinRoom(long roomId);
+    }
+}

osu.Game/Online/RealtimeMultiplayer/IMultiplayerRoomServer.cs

@@ -0,0 +1,51 @@
+// Copyright (c) ppy Pty Ltd <contact@ppy.sh>. Licensed under the MIT Licence.
+// See the LICENCE file in the repository root for full licence text.
+
+using System.Threading.Tasks;
+
+namespace osu.Game.Online.RealtimeMultiplayer
+{
+    /// <summary>
+    /// Interface for an in-room multiplayer server.
+    /// </summary>
+    public interface IMultiplayerRoomServer
+    {
+        /// <summary>
+        /// Request to leave the currently joined room.
+        /// </summary>
+        /// <exception cref="NotJoinedRoomException">If the user is not in a room.</exception>
+        Task LeaveRoom();
+
+        /// <summary>
+        /// Transfer the host of the currently joined room to another user in the room.
+        /// </summary>
+        /// <param name="userId">The new user which is to become host.</param>
+        /// <exception cref="NotHostException">A user other than the current host is attempting to transfer host.</exception>
+        /// <exception cref="NotJoinedRoomException">If the user is not in a room.</exception>
+        Task TransferHost(long userId);
+
+        /// <summary>
+        /// As the host, update the settings of the currently joined room.
+        /// </summary>
+        /// <param name="settings">The new settings to apply.</param>
+        /// <exception cref="NotHostException">A user other than the current host is attempting to transfer host.</exception>
+        /// <exception cref="NotJoinedRoomException">If the user is not in a room.</exception>
+        Task ChangeSettings(MultiplayerRoomSettings settings);
+
+        /// <summary>
+        /// Change the local user state in the currently joined room.
+        /// </summary>
+        /// <param name="newState">The proposed new state.</param>
+        /// <exception cref="InvalidStateChangeException">If the state change requested is not valid, given the previous state or room state.</exception>
+        /// <exception cref="NotJoinedRoomException">If the user is not in a room.</exception>
+        Task ChangeState(MultiplayerUserState newState);
+
+        /// <summary>
+        /// As the host of a room, start the match.
+        /// </summary>
+        /// <exception cref="NotHostException">A user other than the current host is attempting to start the game.</exception>
+        /// <exception cref="NotJoinedRoomException">If the user is not in a room.</exception>
+        /// <exception cref="InvalidStateException">If an attempt to start the game occurs when the game's (or users') state disallows it.</exception>
+        Task StartMatch();
+    }
+}

osu.Game/Online/RealtimeMultiplayer/IMultiplayerServer.cs

@@ -0,0 +1,12 @@
+// Copyright (c) ppy Pty Ltd <contact@ppy.sh>. Licensed under the MIT Licence.
+// See the LICENCE file in the repository root for full licence text.
+
+namespace osu.Game.Online.RealtimeMultiplayer
+{
+    /// <summary>
+    /// An interface defining the multiplayer server instance.
+    /// </summary>
+    public interface IMultiplayerServer : IMultiplayerRoomServer, IMultiplayerLoungeServer
+    {
+    }
+}

osu.Game/Online/RealtimeMultiplayer/InvalidStateChangeException.cs

@@ -0,0 +1,23 @@
+// Copyright (c) ppy Pty Ltd <contact@ppy.sh>. Licensed under the MIT Licence.
+// See the LICENCE file in the repository root for full licence text.
+
+using System;
+using System.Runtime.Serialization;
+using Microsoft.AspNetCore.SignalR;
+
+namespace osu.Game.Online.RealtimeMultiplayer
+{
+    [Serializable]
+    public class InvalidStateChangeException : HubException
+    {
+        public InvalidStateChangeException(MultiplayerUserState oldState, MultiplayerUserState newState)
+            : base($"Cannot change from {oldState} to {newState}")
+        {
+        }
+
+        protected InvalidStateChangeException(SerializationInfo info, StreamingContext context)
+            : base(info, context)
+        {
+        }
+    }
+}

osu.Game/Online/RealtimeMultiplayer/InvalidStateException.cs

@@ -0,0 +1,23 @@
+// Copyright (c) ppy Pty Ltd <contact@ppy.sh>. Licensed under the MIT Licence.
+// See the LICENCE file in the repository root for full licence text.
+
+using System;
+using System.Runtime.Serialization;
+using Microsoft.AspNetCore.SignalR;
+
+namespace osu.Game.Online.RealtimeMultiplayer
+{
+    [Serializable]
+    public class InvalidStateException : HubException
+    {
+        public InvalidStateException(string message)
+            : base(message)
+        {
+        }
+
+        protected InvalidStateException(SerializationInfo info, StreamingContext context)
+            : base(info, context)
+        {
+        }
+    }
+}

osu.Game/Online/RealtimeMultiplayer/MultiplayerRoom.cs

@@ -0,0 +1,76 @@
+// Copyright (c) ppy Pty Ltd <contact@ppy.sh>. Licensed under the MIT Licence.
+// See the LICENCE file in the repository root for full licence text.
+
+#nullable enable
+
+using System;
+using System.Collections.Generic;
+using System.Threading;
+using Newtonsoft.Json;
+using osu.Framework.Allocation;
+
+namespace osu.Game.Online.RealtimeMultiplayer
+{
+    /// <summary>
+    /// A multiplayer room.
+    /// </summary>
+    [Serializable]
+    public class MultiplayerRoom
+    {
+        /// <summary>
+        /// The ID of the room, used for database persistence.
+        /// </summary>
+        public readonly long RoomID;
+
+        /// <summary>
+        /// The current state of the room (ie. whether it is in progress or otherwise).
+        /// </summary>
+        public MultiplayerRoomState State { get; set; }
+
+        /// <summary>
+        /// All currently enforced game settings for this room.
+        /// </summary>
+        public MultiplayerRoomSettings Settings { get; set; } = new MultiplayerRoomSettings();
+
+        /// <summary>
+        /// All users currently in this room.
+        /// </summary>
+        public List<MultiplayerRoomUser> Users { get; set; } = new List<MultiplayerRoomUser>();
+
+        /// <summary>
+        /// The host of this room, in control of changing room settings.
+        /// </summary>
+        public MultiplayerRoomUser? Host { get; set; }
+
+        private object writeLock = new object();
+
+        [JsonConstructor]
+        public MultiplayerRoom(in long roomId)
+        {
+            RoomID = roomId;
+        }
+
+        private object updateLock = new object();
+
+        private ManualResetEventSlim freeForWrite = new ManualResetEventSlim(true);
+
+        /// <summary>
+        /// Request a lock on this room to perform a thread-safe update.
+        /// </summary>
+        public IDisposable LockForUpdate()
+        {
+            // ReSharper disable once InconsistentlySynchronizedField
+            freeForWrite.Wait();
+
+            lock (updateLock)
+            {
+                freeForWrite.Wait();
+                freeForWrite.Reset();
+
+                return new ValueInvokeOnDisposal<MultiplayerRoom>(this, r => freeForWrite.Set());
+            }
+        }
+
+        public override string ToString() => $"RoomID:{RoomID} Host:{Host?.UserID} Users:{Users.Count} State:{State} Settings: [{Settings}]";
+    }
+}

osu.Game/Online/RealtimeMultiplayer/MultiplayerRoomSettings.cs

@@ -0,0 +1,30 @@
+// Copyright (c) ppy Pty Ltd <contact@ppy.sh>. Licensed under the MIT Licence.
+// See the LICENCE file in the repository root for full licence text.
+
+#nullable enable
+
+using System;
+using System.Collections.Generic;
+using System.Linq;
+using JetBrains.Annotations;
+using osu.Game.Online.API;
+
+namespace osu.Game.Online.RealtimeMultiplayer
+{
+    [Serializable]
+    public class MultiplayerRoomSettings : IEquatable<MultiplayerRoomSettings>
+    {
+        public int BeatmapID { get; set; }
+
+        public int RulesetID { get; set; }
+
+        public string Name { get; set; } = "Unnamed room";
+
+        [NotNull]
+        public IEnumerable<APIMod> Mods { get; set; } = Enumerable.Empty<APIMod>();
+
+        public bool Equals(MultiplayerRoomSettings other) => BeatmapID == other.BeatmapID && Mods.SequenceEqual(other.Mods) && RulesetID == other.RulesetID && Name.Equals(other.Name, StringComparison.Ordinal);
+
+        public override string ToString() => $"Name:{Name} Beatmap:{BeatmapID} Mods:{string.Join(',', Mods)} Ruleset:{RulesetID}";
+    }
+}

osu.Game/Online/RealtimeMultiplayer/MultiplayerRoomState.cs

@@ -0,0 +1,33 @@
+// Copyright (c) ppy Pty Ltd <contact@ppy.sh>. Licensed under the MIT Licence.
+// See the LICENCE file in the repository root for full licence text.
+
+#nullable enable
+
+namespace osu.Game.Online.RealtimeMultiplayer
+{
+    /// <summary>
+    /// The current overall state of a realtime multiplayer room.
+    /// </summary>
+    public enum MultiplayerRoomState
+    {
+        /// <summary>
+        /// The room is open and accepting new players.
+        /// </summary>
+        Open,
+
+        /// <summary>
+        /// A game start has been triggered but players have not finished loading.
+        /// </summary>
+        WaitingForLoad,
+
+        /// <summary>
+        /// A game is currently ongoing.
+        /// </summary>
+        Playing,
+
+        /// <summary>
+        /// The room has been disbanded and closed.
+        /// </summary>
+        Closed
+    }
+}

osu.Game/Online/RealtimeMultiplayer/MultiplayerRoomUser.cs

@@ -0,0 +1,44 @@
+// Copyright (c) ppy Pty Ltd <contact@ppy.sh>. Licensed under the MIT Licence.
+// See the LICENCE file in the repository root for full licence text.
+
+#nullable enable
+
+using System;
+using Newtonsoft.Json;
+using osu.Game.Users;
+
+namespace osu.Game.Online.RealtimeMultiplayer
+{
+    [Serializable]
+    public class MultiplayerRoomUser : IEquatable<MultiplayerRoomUser>
+    {
+        public readonly int UserID;
+
+        public MultiplayerUserState State { get; set; } = MultiplayerUserState.Idle;
+
+        public User? User { get; set; }
+
+        [JsonConstructor]
+        public MultiplayerRoomUser(in int userId)
+        {
+            UserID = userId;
+        }
+
+        public bool Equals(MultiplayerRoomUser other)
+        {
+            if (ReferenceEquals(this, other)) return true;
+
+            return UserID == other.UserID;
+        }
+
+        public override bool Equals(object obj)
+        {
+            if (ReferenceEquals(this, obj)) return true;
+            if (obj.GetType() != GetType()) return false;
+
+            return Equals((MultiplayerRoomUser)obj);
+        }
+
+        public override int GetHashCode() => UserID.GetHashCode();
+    }
+}

osu.Game/Online/RealtimeMultiplayer/MultiplayerUserState.cs

@@ -0,0 +1,59 @@
+// Copyright (c) ppy Pty Ltd <contact@ppy.sh>. Licensed under the MIT Licence.
+// See the LICENCE file in the repository root for full licence text.
+
+namespace osu.Game.Online.RealtimeMultiplayer
+{
+    public enum MultiplayerUserState
+    {
+        /// <summary>
+        /// The user is idle and waiting for something to happen (or watching the match but not participating).
+        /// </summary>
+        Idle,
+
+        /// <summary>
+        /// The user has marked themselves as ready to participate and should be considered for the next game start.
+        /// </summary>
+        /// <remarks>
+        /// Clients in this state will receive gameplay channel messages.
+        /// As a client the only thing to look for in this state is a <see cref="IMultiplayerClient.LoadRequested"/> call.
+        /// </remarks>
+        Ready,
+
+        /// <summary>
+        /// The server is waiting for this user to finish loading. This is a reserved state, and is set by the server.
+        /// </summary>
+        /// <remarks>
+        /// All users in <see cref="Ready"/> state when the game start will be transitioned to this state.
+        /// All users in this state need to transition to <see cref="Loaded"/> before the game can start.
+        /// </remarks>
+        WaitingForLoad,
+
+        /// <summary>
+        /// The user's client has marked itself as loaded and ready to begin gameplay.
+        /// </summary>
+        Loaded,
+
+        /// <summary>
+        /// The user is currently playing in a game. This is a reserved state, and is set by the server.
+        /// </summary>
+        /// <remarks>
+        /// Once there are no remaining <see cref="WaitingForLoad"/> users, all users in <see cref="Loaded"/> state will be transitioned to this state.
+        /// At this point the game will start for all users.
+        /// </remarks>
+        Playing,
+
+        /// <summary>
+        /// The user has finished playing and is ready to view results.
+        /// </summary>
+        /// <remarks>
+        /// Once all users transition from <see cref="Playing"/> to this state, the game will end and results will be distributed.
+        /// All users will be transitioned to the <see cref="Results"/> state.
+        /// </remarks>
+        FinishedPlay,
+
+        /// <summary>
+        /// The user is currently viewing results. This is a reserved state, and is set by the server.
+        /// </summary>
+        Results,
+    }
+}

osu.Game/Online/RealtimeMultiplayer/NotHostException.cs

@@ -0,0 +1,23 @@
+// Copyright (c) ppy Pty Ltd <contact@ppy.sh>. Licensed under the MIT Licence.
+// See the LICENCE file in the repository root for full licence text.
+
+using System;
+using System.Runtime.Serialization;
+using Microsoft.AspNetCore.SignalR;
+
+namespace osu.Game.Online.RealtimeMultiplayer
+{
+    [Serializable]
+    public class NotHostException : HubException
+    {
+        public NotHostException()
+            : base("User is attempting to perform a host level operation while not the host")
+        {
+        }
+
+        protected NotHostException(SerializationInfo info, StreamingContext context)
+            : base(info, context)
+        {
+        }
+    }
+}

osu.Game/Online/RealtimeMultiplayer/NotJoinedRoomException.cs

@@ -0,0 +1,23 @@
+// Copyright (c) ppy Pty Ltd <contact@ppy.sh>. Licensed under the MIT Licence.
+// See the LICENCE file in the repository root for full licence text.
+
+using System;
+using System.Runtime.Serialization;
+using Microsoft.AspNetCore.SignalR;
+
+namespace osu.Game.Online.RealtimeMultiplayer
+{
+    [Serializable]
+    public class NotJoinedRoomException : HubException
+    {
+        public NotJoinedRoomException()
+            : base("This user has not yet joined a multiplayer room.")
+        {
+        }
+
+        protected NotJoinedRoomException(SerializationInfo info, StreamingContext context)
+            : base(info, context)
+        {
+        }
+    }
+}