2024.9

Updates

* New Session Playtime metrics functions are available. Please see
  `MetricsSessionStartAsync`, `MetricsSessionEndAsync` and related
  functions for details about this feature.
** Please note that Session Metrics are a premium feature. Please speak
to your mod.io contact for more information.
* Documentation Updates
* NativeSDK updated to 2024.9.1

Bugfixes

* Added new define to work around binary incompatibility issue caused by
  MSVC's STL implementation adding a new constexpr constructor for
  std::mutex

Doc/asset-support-for-mods.adoc

@@ -0,0 +1,117 @@
+== Overview
+
+The main factor for supporting assets is dependency: only dependencies to the project's content are allowed, but not engine's dependency. When trying to package any asset that has engine dependency, it will fail.
+
+Some assets have internal dependencies which can't be bypassed without modifying the engine's source code. For example, when trying to create a directional light or point light in the level, you'll have an `EmptyActor` dependency to the engine - packaging of that asset and consequently the whole mod will fail. Therefore, you should generally avoid using any engine's assets dependency (except for very basic ones, such as dependency to `AActor` class), and instead create your own classes in your project and implement the necessary functionality there, and allow the mod to use those classes instead of the engine's ones.
+
+== Supported Asset Types
+
+=== Allowed Actors In Levels
+
+These actors, including custom actors derived from them and saved in the project or mod, can be placed in levels without causing packaging issues in the mod:
+
+1. `AStaticMeshActor`
+2. `APlayerStart`
+3. `APawn`
+   * `ACharacter`
+   * `ADefaultPawn`
+   * All other derived actors
+4. `ABrush` & `AVolume`
+   * `AKillZVolume`
+   * `ABlockingVolume`
+   * `AAudioVolume`
+   * `ACullDistanceVolume`
+   * `APostProcessVolume`
+   * All other derived actors
+5. `ADecalActor`
+6. `AInfo`
+   * `AVolumetricCloud`
+   * `AExponentialHeightFog`
+   * Other supported derived actors
+7. `ATriggerBase`
+   * `ATriggerBox`
+   * `ATriggerCapsule`
+   * `ATriggerSphere`
+   * All other derived actors
+
+=== Allowed Components in Actors
+
+These components, including custom components derived from them and saved in the project or mod, can be placed in actors without causing packaging issues in the mod:
+
+1. `USceneComponent`
+   * `UPrimitiveComponent`
+     * `UTextRenderComponent`
+     * `UArrowComponent`
+     * `UShapeComponent` (collisions)
+       * `UBoxComponent`
+       * `UCapsuleComponent`
+       * `USphereComponent`
+     * `UMeshComponent`
+       * `UStaticMeshComponent`
+       * `UWidgetComponent`
+       * All other derived components
+   * `UCameraComponent`
+   * `UChildActorComponent`
+   * `UText3DComponent`
+   * Other supported derived components
+2. `UWidgetComponent`
+3. `UCameraComponent`
+4. `UDecalComponent`
+5. `UMovementComponent`
+   * `UPawnMovementComponent`
+   * `UCharacterMovementComponent`
+   * All other derived components
+- All other derived components
+
+== Unsupported Asset Types
+
+=== Prohibited Actors in Levels
+
+These actors, including custom actors derived from them and saved in the project or mod, should not be placed in levels as they will likely cause packaging issues in the mod:
+
+1. `ALight`
+   * `ADirectionalLight`
+   * `APointLight`
+   * `ARectLight`
+   * `ASpotLight`
+2. `AInfo`
+   * `ASkyLight`
+   * `ASkyAtmosphere`
+   * Other unsupported derived actors
+3. `ASkyAtmosphere`
+4. `ATextRenderActor`
+   * Other unsupported derived actors
+
+=== Prohibited Components in Actors
+
+These components, including custom components derived from them and saved in the project or mod, should not be placed in actors as they will likely cause packaging issues in the mod:
+
+1. `USceneComponent`
+   * `ULightComponentBase`
+     * `UDirectionalLightComponent`
+     * `ULightComponent`
+     * `ULocalLightComponent`
+     * `UPointLightComponent`
+     * `URectLightComponent`
+     * `USkyLightComponent`
+     * `USpotLightComponent`
+   * `USynthComponent`
+   * `UAudioComponent`
+   * Other unsupported derived components
+
+== Asset Support in Packages (UPackage)
+
+Generally, all possible asset types are supported to be included in the plugin after the packaging. The tested ones are listed below, but any other assets without dependency on the engine are supported as well, such as manually created ones in the mod itself:
+
+* Actor
+* Pawn
+* Character
+* Actor Component
+* Scene Component
+* Level
+* Material
+* Widget
+* Texture
+* Sound Wave
+* Static Mesh
+* Skeletal Mesh

Doc/getting-started.adoc

@@ -1324,3 +1324,147 @@ void UModioManager::OnGetUserDelegationTokenCallback(FModioErrorCode ErrorCode,
 ----
 
 ====
+=== Metrics Play Sessions
+
+The mod.io SDK supports all of the mod.io metrics features, allowing you to start a metrics play sesion, keeping that session alive via a heartbeat (automatically called, or manually handled) and then ending that session. Metric sessions allow you to track which mods your players interact with most frequently. Visit https://docs.mod.io/metrics/ for an overview of the mod.io metrics system.
+
+NOTE: Running metrics play sessions is a premium feature. If you are interested in mod.io premium features, please contact [email protected].
+
+The Metrics session functionality is all accessible through the `modiosdk.h`, as well as suplemented with a global Metrics Service to manage session data, accessed via `Modio::Detail::Services::GetGlobalService<Modio::Detail::MetricsService>()`
+
+Metrics based on the platform and portal, are transparently taken care of with no additional consideration needed when using the SDK.
+
+==== Initialization
+
+The mod.io metrics features are enabled as part of generating a Metrics Secret Key your API settings in your game dashboard, e.g. https://mod.io/g/<game-name>/admin/api-key. Once this key has been generated, you need to pass it in as an ExtendedInitializationParameters entry in your InitializeOptions when Initializing the mod.io SDK, e.g.:
+
+[source,cpp]
+----
+FModioInitializeOptions initializeOptions;
+initializeOptions.ExtendedInitializationParameters.Add("MetricsSecretKey", "00000000-1111-2222-3333-444444444444");
+----
+
+Failing to set up the Metrics Secret Key will result in a `Modio::MetricsError::SessionNotInitialized`` error being returned when using the metrics functionality.
+
+Additionally, ensure that you have set the appropriate Portal when initializing the SDK to track metrics sessions fro the appropriate portal you are using - for instance, on Steam, you must initialize with Modio::Portal::Steam.
+
+==== Starting a Metrics Session
+
+You can call <<MetricsSessionStartAsync>> to start a new session tracking the usage of mods in the context of your game. You'll notice that `MetricsSessionStartAsync` takes a <<MetricsSessionParams>> object as its parameter. This contains an optional Session Id, as well as a required vector of mods to track.
+
+NOTE: If a Session Id is not provided, a random one will be created for you.
+
+.Blueprint Example
+[%collapsible]
+====
+
+image::img/metrics_session_start_1.png[]
+
+NOTE: Use the `SetSessionId` node if you want to associate your own Id with this session.
+
+image::img/metrics_session_start_2.png[]
+
+====
+
+.C++ Example
+[%collapsible]
+====
+
+[source,cpp]
+----
+FModioMetricsSessionParams Params = FModioMetricsSessionParams(ModIds);
+
+void UModioManager::MetricsSessionStart(const FModioMetricsSessionParams& Params)
+{
+	GEngine->GetEngineSubsystem<UModioSubsystem>()->MetricsSessionStartAsync(
+		Params, FOnErrorOnlyDelegateFast::CreateUObject(this, &UModioManager::MetricsSessionStartCallback));
+}
+----
+====
+
+The Metrics Session Params accepts an optional Session Id in the form of a `Modio::Guid` which you may want to use to associate the new session with any supplementary telemetry you are gathering in your game.
+
+==== Metrics heartbeat
+
+To ensure that the session is kept alive, a heartbeat is required to be submitted at most every 5 minutes. We recommend doing this a bit earlier than the threshold to ensure you do not miss the window.
+
+There are two methods provided to control the behaviour of the heart beat, <<MetricsSessionSendHeartbeatOnceAsync>> which you can call at your desired precision, as well as a single call and forget <<MetricsSessionSendHeartbeatAtIntervalAsync>> with a desired interval.
+
+Calling `MetricsSessionSendHeartbeatOnceAsync` will submit a single heartbeat, and return an error code if something went wrong. If no error has occured, the heartbeat has been successfully sent.
+
+.Blueprint Example
+[%collapsible]
+====
+
+image::img/metrics_session_heartbeat.png[]
+
+====
+
+.C++ Example
+[%collapsible]
+====
+
+[source,cpp]
+----
+void UModioManager::MetricsSessionHeartbeat()
+{
+	GEngine->GetEngineSubsystem<UModioSubsystem>()->MetricsSessionSendHeartbeatOnceAsync(
+		FOnErrorOnlyDelegateFast::CreateUObject(this, &UModioManager::MetricsSessionHeartbeatCallback));
+}
+----
+====
+
+Calling `MetricsSessionSendHeartbeatAtIntervalAsync` requires a parameter with the desired interval frequency in seconds. An error code will be returned if something went wrong, otherwise you will receive a false-y error if the interval loop has been shut down successfully (such as ending a session).
+
+.Blueprint Example
+[%collapsible]
+====
+
+image::img/metrics_session_heartbeat_interval.png[]
+
+====
+
+.C++ Example
+[%collapsible]
+====
+
+[source,cpp]
+----
+const FModioUnsigned64 IntervalSeconds(150);
+
+void UModioManager::MetricsSessionHeartbeat(const FModioUnsigned64& IntervalSeconds)
+{
+	GEngine->GetEngineSubsystem<UModioSubsystem>()->MetricsSessionSendHeartbeatAtIntervalAsync(
+		IntervalSeconds, 
+		FOnErrorOnlyDelegateFast::CreateUObject(this, &UModioManager::MetricsSessionHeartbeatCallback));
+}
+----
+====
+
+==== Ending a Metrics Session
+
+To complete a session, for example when finishing a match, or quitting out of your game, you can call <<MetricsSessionEndAsync>>.
+As with the other calls, you will receive an error if anything has gone wrong, otherwise the operation successfully completed.
+
+.Blueprint Example
+[%collapsible]
+====
+
+image::img/metrics_session_end.png[]
+
+====
+
+.C++ Example
+[%collapsible]
+====
+
+[source,cpp]
+----
+void UModioManager::MetricsSessionHeartbeat()
+{
+	GEngine->GetEngineSubsystem<UModioSubsystem>()->MetricsSessionEndAsync(
+
+		FOnErrorOnlyDelegateFast::CreateUObject(this, &UModioManager::MetricsSessionHeartbeatCallback));
+}
+----
+====

README.adoc

@@ -25,9 +25,10 @@ The mod.io plugin is generally maintained to support the 3 most recent versions
 |UE4.26 | 2023.11
 |UE4.27 | 2023.11
 |UE5.0 | 2023.11
-|UE5.1 | Current
+|UE5.1 | 2024.6
 |UE5.2 | Current
 |UE5.3 | Current
+|UE5.4 | Current
 |===
 
 ### Platform compatability
@@ -109,7 +110,7 @@ To begin using the Plugin, either from Blueprint or from C++, please read our ht
 
 === User Interface
 
-The plugin ships with a fully functional UI, featuring mod browsing, searching and collection management. If you want to use the UI in the game, you can read the link:Doc/ui5-documentation.adoc[UI Documentation]
+mod.io also provides a separate plugin for building an in-game UI. This includes a template for mod browsing, searching, collection management etc, as well as a set of components for customizing or building your own in-game UI. You can download that from the  https://github.com/modio/modio-ue-component-ui[Component UI Repository].
 
 === Profiling
 

Source/Modio/Modio.Build.cs

@@ -474,6 +474,12 @@ private void AddCommonDefinitions()
             PrivateDefinitions.Add("MODIO_UNREAL_PROFILING_SUPPORT=1");
         }
 
+		// This define is a recommendation from Microsoft for issues that are caused by mutex's constructor to not being constexpr
+		// Not using this can cause crashes in the std::mutex constructor under some circumstances where there are build-time and
+		// runtime stl version mismatches.
+	    // More information: https://github.com/microsoft/STL/wiki/Changelog#vs-2022-1710
+        PrivateDefinitions.Add("_DISABLE_CONSTEXPR_MUTEX_CONSTRUCTOR");
+
         // Enable Unreal-specific headers in the native SDK
         PrivateDefinitions.Add("MODIO_PLATFORM_UNREAL");
         // Disable header-only mode

Source/Modio/Private/Internal/ModioConvert.cpp

@@ -9,6 +9,8 @@
  */
 
 #include "Internal/ModioConvert.h"
+
+#include "Convert/Optional.h"
 #include "Types/ModioUnsigned64.h"
 
 std::string ToModio(const FString& String)
@@ -342,6 +344,24 @@ Modio::EntitlementParams ToModio(const FModioEntitlementParams& InParams)
 	return Params;
 }
 
+Modio::MetricsSessionParams ToModio(const FModioMetricsSessionParams& InParams)
+{
+	Modio::MetricsSessionParams Params;
+	Params.SessionId = ToModioOptional<Modio::Guid>(InParams.SessionId);
+	Params.ModIds = ToModio(InParams.ModIds);
+	return Params;
+}
+
+Modio::Guid ToModio(const FModioGuid& In)
+{
+	if (In.IsValid())
+	{
+		return Modio::Guid(TCHAR_TO_UTF8(*In.ToString()));
+	}
+
+	return Modio::Guid::InvalidGuid();
+}
+
 FModioModID ToUnreal(Modio::ModID Value)
 {
 	return FModioModID(Value);