[OF-1784] feat: Adding MultiplayerSystem

This adds a multiplayey system where we can put functionality from the chs multiplayer service api. We may want to make other system abstractions in the future, as this api contains a lot of different functionality. For now, only the functions needed for testing leader election have been implemented

Author: MAG-mv

Library/include/CSP/Systems/Multiplayer/MultiplayerSystem.h

@@ -0,0 +1,89 @@
+/*
+ * Copyright 2025 Magnopus LLC
+
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+#pragma once
+
+#include "CSP/CSPCommon.h"
+#include "CSP/Systems/Multiplayer/Scope.h"
+#include "CSP/Systems/Multiplayer/ScopeLeader.h"
+#include "CSP/Systems/SystemBase.h"
+
+#include <memory>
+
+namespace csp::services
+{
+
+class ApiBase;
+
+} // namespace csp::services
+
+namespace csp::web
+{
+
+class WebClient;
+
+} // namespace csp::web
+
+namespace csp::systems
+{
+
+/// @ingroup Multiplayer System
+/// @brief Public facing system that allows interfacing with Magnopus Connected Services' multiplayer api.
+/// Offers methods for managing realtime state via REST calls.
+class CSP_API CSP_NO_DISPOSE MultiplayerSystem : public SystemBase
+{
+public:
+    CSP_NO_EXPORT MultiplayerSystem(csp::web::WebClient* WebClient, csp::common::LogSystem& LogSystem);
+    MultiplayerSystem(); // This constructor is only provided to appease the wrapper generator and should not be used
+    ~MultiplayerSystem();
+
+    /// @brief Gets all scopes associated with the given space id.
+    /// @param SpaceId const csp::common::String& : The id of the space we want to get scopes for.
+    /// @param Callback csp::systems::ScopesResultCallback : Callback when asynchronous task finishes.
+    /// @pre Must already have entered the space of the SpaceId parameter.
+    CSP_ASYNC_RESULT void GetScopesBySpace(const csp::common::String& SpaceId, ScopesResultCallback Callback);
+
+    /// @brief Updates Data on a scope
+    /// @param ScopeId const csp::common::String& : The id of the scope we want to update.
+    /// @param Scope const csp::systems::Scope& : Scope containing new values for the given id.
+    /// @param Callback csp::systems::ScopesResultCallback : Callback when asynchronous task finishes.
+    /// @pre Must already have entered the space of the SpaceId parameter.
+    CSP_ASYNC_RESULT void UpdateScopeById(const csp::common::String& ScopeId, const csp::systems::Scope& Scope, ScopeResultCallback Callback);
+
+    /// @brief Gets details about a scope leader.
+    /// @param ScopeId const csp::common::String& : The id of the scope we want to get scope leader details about.
+    /// @param Callback csp::systems::ScopesResultCallback : Callback when asynchronous task finishes.
+    /// @pre "ManagedLeaderElection" should be set to true on the scope, otherwise this function will fail with a EResultCode::Failed response.
+    /// @pre Must already have entered the space of the SpaceId parameter.
+    CSP_ASYNC_RESULT void GetScopeLeader(const csp::common::String& ScopeId, ScopeLeaderResultCallback Callback);
+
+    /// @brief Starts leader election for the given scope.
+    /// This should not need to be called outside of testing, as leader election is done automatically.
+    /// @param ScopeId const csp::common::String& : The id of the scope we want to start leader election for.
+    /// @param UserIdsToExclude const csp::common::Optional<csp::common::Array<csp::common::String>>& : A list of user ids we don't want to consider
+    /// for election.
+    /// @param Callback csp::systems::ScopesResultCallback : Callback when asynchronous task finishes.
+    /// @pre "ManagedLeaderElection" should be set to true on the scope, otherwise this function will fail with a EResultCode::Failed response.
+    /// @pre Must already have entered the space of the SpaceId parameter.
+    CSP_ASYNC_RESULT void PerformLeaderElectionInScope(const csp::common::String& ScopeId,
+        const csp::common::Optional<csp::common::Array<csp::common::String>>& UserIdsToExclude, NullResultCallback Callback);
+
+private:
+    csp::services::ApiBase* ScopeLeaderApi;
+    csp::services::ApiBase* ScopesApi;
+};
+
+}

Library/include/CSP/Systems/Multiplayer/Scope.h

@@ -0,0 +1,124 @@
+/*
+ * Copyright 2025 Magnopus LLC
+
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+#pragma once
+
+#include "CSP/CSPCommon.h"
+#include "CSP/Systems/SystemsResult.h"
+#include "CSP/Systems/WebService.h"
+
+#include <functional>
+
+namespace csp::services
+{
+
+CSP_START_IGNORE
+template <typename T, typename U, typename V, typename W> class ApiResponseHandler;
+CSP_END_IGNORE
+
+} // namespace csp::services
+
+namespace csp::services::generated::multiplayerservice
+{
+class ScopeDto;
+}
+
+namespace csp::systems
+{
+
+/// @ingroup Multiplayer System
+/// @brief Enum representing the scopes pub/sub model type
+/// Object: used in object scopes, each object is published to its own channel, and
+/// client subscribes to the channels of only the objects they can see
+/// Global: used in global scopes, all objects are published to a single channel,
+/// client subscribes to the channel and can see everything in the channel/scope
+enum class PubSubModelType
+{
+    Object,
+    Global
+};
+
+/// @ingroup Multiplayer System
+/// @brief Data representation for a scope in a space.
+/// Scopes represent different channels in a space which objects can exist in.
+/// This allows csp/mcs to only reason about objects in specific scopes.
+class CSP_API Scope
+{
+public:
+    csp::common::String Id;
+    csp::common::String ReferenceId;
+    csp::common::String ReferenceType;
+    csp::common::String Name;
+    PubSubModelType PubSubType = PubSubModelType::Global;
+    double SolveRadius = 0.0;
+    bool ManagedLeaderElection = false;
+};
+
+void DtoToScope(const csp::services::generated::multiplayerservice::ScopeDto& Dto, csp::systems::Scope& ScopeLeader);
+
+/// @ingroup Multiplayer System
+/// @brief Contains details about an async operation which returns a scope.
+/// If the ResultCode is successful, this will contain a valid scope.
+class CSP_API ScopeResult : public ResultBase
+{
+    /** @cond DO_NOT_DOCUMENT */
+    CSP_START_IGNORE
+    template <typename T, typename U, typename V, typename W> friend class csp::services::ApiResponseHandler;
+    CSP_END_IGNORE
+    /** @endcond */
+
+public:
+    /// @brief Returns the scope if this result is successful.
+    /// @return const Scope& : The scope retrieved by this result.
+    const Scope& GetScope() const;
+
+private:
+    ScopeResult(void*) {};
+
+    void OnResponse(const csp::services::ApiResponseBase* ApiResponse) override;
+
+    Scope Scope;
+};
+
+typedef std::function<void(const ScopeResult& Result)> ScopeResultCallback;
+
+/// @ingroup Multiplayer System
+/// @brief Contains details about an async operation which returns an array of scopes.
+/// If the ResultCode is successful, this will contain a valid array of scopes.
+class CSP_API ScopesResult : public ResultBase
+{
+    /** @cond DO_NOT_DOCUMENT */
+    CSP_START_IGNORE
+    template <typename T, typename U, typename V, typename W> friend class csp::services::ApiResponseHandler;
+    CSP_END_IGNORE
+    /** @endcond */
+
+public:
+    /// @brief Returns the an array of scopes if this result is successful.
+    /// @return const csp::common::Array<Scope>& : The array of scopes retrieved by this result.
+    const csp::common::Array<Scope>& GetScopes() const;
+
+private:
+    ScopesResult(void*) {};
+
+    void OnResponse(const csp::services::ApiResponseBase* ApiResponse) override;
+
+    csp::common::Array<Scope> Scopes;
+};
+
+typedef std::function<void(const ScopesResult& Result)> ScopesResultCallback;
+
+}

Library/include/CSP/Systems/Multiplayer/ScopeLeader.h

@@ -0,0 +1,81 @@
+/*
+ * Copyright 2025 Magnopus LLC
+
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+#pragma once
+
+#include "CSP/CSPCommon.h"
+#include "CSP/Systems/SystemsResult.h"
+#include "CSP/Systems/WebService.h"
+
+#include <functional>
+
+namespace csp::services
+{
+
+CSP_START_IGNORE
+template <typename T, typename U, typename V, typename W> class ApiResponseHandler;
+CSP_END_IGNORE
+
+} // namespace csp::services
+
+namespace csp::services::generated::multiplayerservice
+{
+class ScopeLeaderDto;
+}
+
+namespace csp::systems
+{
+
+/// @ingroup Multiplayer System
+/// @brief Data representation for a scope leader.
+/// A scope leader represents a user which owns a specific scope in a space.
+/// The scope leader will run scripts and other operations for the scope.
+class CSP_API ScopeLeader
+{
+public:
+    csp::common::String ScopeId;
+    csp::common::String ScopeLeaderUserId;
+    bool ElectionInProgress = false;
+};
+
+void DtoToScopeLeader(const csp::services::generated::multiplayerservice::ScopeLeaderDto& Dto, csp::systems::ScopeLeader& ScopeLeader);
+
+/// @ingroup Multiplayer System
+/// @brief Contains details about an async operation which returns a scope leader.
+/// If the ResultCode is successful, this will contain a valid scope leader.
+class CSP_API ScopeLeaderResult : public ResultBase
+{
+    /** @cond DO_NOT_DOCUMENT */
+    CSP_START_IGNORE
+    template <typename T, typename U, typename V, typename W> friend class csp::services::ApiResponseHandler;
+    CSP_END_IGNORE
+    /** @endcond */
+
+public:
+    /// @brief Returns the scope leader if this result is successful.
+    /// @return const ScopeLeader& : The scope leader retrieved by this result.
+    const ScopeLeader& GetScopeLeader() const;
+
+private:
+    ScopeLeaderResult(void*) {};
+
+    void OnResponse(const csp::services::ApiResponseBase* ApiResponse) override;
+
+    ScopeLeader Leader;
+};
+
+typedef std::function<void(const ScopeLeaderResult& Result)> ScopeLeaderResultCallback;
+}

Library/include/CSP/Systems/SystemsManager.h

@@ -53,6 +53,7 @@ class HotspotSequenceSystem;
 class ConversationSystemInternal;
 class AnalyticsSystem;
 class ExternalServiceProxySystem;
+class MultiplayerSystem;
 
 } // namespace csp::systems
 
@@ -169,6 +170,8 @@ class CSP_API SystemsManager
     /// @return ExternalServiceProxySystem : pointer to the external services proxy system class.
     ExternalServiceProxySystem* GetExternalServicesProxySystem();
 
+    MultiplayerSystem* GetMultiplayerSystem();
+
     csp::multiplayer::MultiplayerConnection* GetMultiplayerConnection();
 
     csp::multiplayer::NetworkEventBus* GetEventBus();
@@ -220,6 +223,7 @@ class CSP_API SystemsManager
     ConversationSystemInternal* ConversationSystem;
     AnalyticsSystem* AnalyticsSystem;
     ExternalServiceProxySystem* ExternalServiceProxySystem;
+    MultiplayerSystem* MultiplayerSystem;
 };
 
 } // namespace csp::systems

Library/src/ExplicitTypes.cpp

@@ -25,6 +25,7 @@
 #include "CSP/Systems/Assets/Asset.h"
 #include "CSP/Systems/Assets/AssetCollection.h"
 #include "CSP/Systems/Assets/GLTFMaterial.h"
+#include "CSP/Systems/Multiplayer/Scope.h"
 #include "CSP/Systems/Spaces/Site.h"
 #include "CSP/Systems/Spaces/Space.h"
 #include "CSP/Systems/Spaces/UserRoles.h"
@@ -62,6 +63,7 @@ template class CSP_API csp::common::Array<csp::systems::Site>;
 template class CSP_API csp::common::Array<csp::systems::Space>;
 template class CSP_API csp::common::Array<csp::systems::UserRoleInfo>;
 template class CSP_API csp::common::Array<csp::systems::Material*>;
+template class CSP_API csp::common::Array<csp::systems::Scope>;
 
 // csp::common::List
 template class CSP_API csp::common::List<csp::common::String>;