Stormancer.Server.Plugins.Party 4.4.0.3-pre

This is a prerelease version of Stormancer.Server.Plugins.Party.
There is a newer version of this package available.
See the version list below for details.
dotnet add package Stormancer.Server.Plugins.Party --version 4.4.0.3-pre
                    
NuGet\Install-Package Stormancer.Server.Plugins.Party -Version 4.4.0.3-pre
                    
This command is intended to be used within the Package Manager Console in Visual Studio, as it uses the NuGet module's version of Install-Package.
<PackageReference Include="Stormancer.Server.Plugins.Party" Version="4.4.0.3-pre" />
                    
For projects that support PackageReference, copy this XML node into the project file to reference the package.
<PackageVersion Include="Stormancer.Server.Plugins.Party" Version="4.4.0.3-pre" />
                    
Directory.Packages.props
<PackageReference Include="Stormancer.Server.Plugins.Party" />
                    
Project file
For projects that support Central Package Management (CPM), copy this XML node into the solution Directory.Packages.props file to version the package.
paket add Stormancer.Server.Plugins.Party --version 4.4.0.3-pre
                    
#r "nuget: Stormancer.Server.Plugins.Party, 4.4.0.3-pre"
                    
#r directive can be used in F# Interactive and Polyglot Notebooks. Copy this into the interactive tool or source code of the script to reference the package.
#addin nuget:?package=Stormancer.Server.Plugins.Party&version=4.4.0.3-pre&prerelease
                    
Install as a Cake Addin
#tool nuget:?package=Stormancer.Server.Plugins.Party&version=4.4.0.3-pre&prerelease
                    
Install as a Cake Tool

This module adds player parties related features to a Stormancer application. It contains a Server application plugin (the Nuget package), and a C++ client plugin (Party.hpp).

A player party is a group any player can create, which can be joined by other players afterward. A gamefinder is set as part of the party creation parameters and can be changed afterwards. When all members of a party are in the ready state (set by calling PartyApi::updatePlayerStatus), the selected gamefinder is executed, with the current party data (including party settings, member list and member data) as argument.

The party:

  • Maintains on all party members as well as on the server an updated list of the party members
  • Maintain a party leader, with leadership automatically passed to another player in case of leader disconnection
  • Synchronizes custom party settings (expressed as a string). Only the leader can update the party settings.
  • Synchronizes custom data (as a string) for all members. Only the corresponding member can updates its data.
  • Generates invitation codes to enable players to join in a crossplay game.
  • Synchronizes an extensible state, for instance filled by the Gamesession system so that players joining a party already in a gamesession can detect that and join the gamesession.
  • Integrates with the invitation systems of gaming platforms like Steam, PSN, XBoxLive, Nintendo Online and Epic Store to provide a seamless experience for players running the game on the same platform, while retaining crossplay capabilities in the same party.
  • Provides search and filtering capabilities based on Lucene.

The party system uses Stormancer scenes as its core abstraction (a party is a component of a scene). This makes the party system highly scalable and extensible as developers can easily add additional behaviors to a party scene.

Creating a party

client->DependencyResolver.resolve<Stormancer::PartyApi>()->createIfNotJoined().then([]()
{
	...
});

Invitation codes

Customizing invitation codes:

{
	"party":{
		"authorizedInvitationCodeCharacters":"01234567890" // defaults to "23456789ABCDEFGHJKLMNPQRSTUVWXYZ"
		"invitationCodeLength" : 4 //defaults to 6
	}
}

Joining the gamesession your party is in

When joining a party, it's possible to know if it is currently in a gamession, and join this gamesession. If not used by the application, this behavior can be disabled by setting to application configuration value party.enableGameSessionPartyStatus to false.

The following methods of PartyApi enables clients to determine if their party is in a gamesession, and if it's the case, to get a connection token to it that can be consumed by the GameSession client API.

/// <summary>
/// Gets a boolean indicating if the party is currently in a gamesession.
/// </summary>
/// <returns></returns>
virtual bool isInGameSession() = 0;

/// <summary>
/// If the party is in a gamesession, gets a token to connect to it.
/// </summary>
/// <param name="ct"></param>
/// <returns></returns>
virtual pplx::task<std::string> getCurrentGameSessionConnectionToken(pplx::cancellation_token ct = pplx::cancellation_token::none()) = 0;

Once a party is created, the party leader can index it into an a distributed in memory database on the server using Lucene for search. To do that, call UpdatePartySettings and provide a valid json document in the indexedDocument field.

struct PartySettings
{
	std::string gameFinderName;
	std::string customData;
	bool onlyLeaderCanInvite = true;
	bool isJoinable = true;
	std::unordered_map<std::string, std::string> publicServerData; // Not in MSGPACK_DEFINE because cannot be set by the client

	/// <summary>
	/// Json document used to search the party.
	/// </summary>
	/// <remarks>
	/// Must be a valid json object.
	/// The party is not searchable if set to empty or an invalid json object.
	/// The content of the document are indexed using the field paths as keys, with '.' as separator.
	/// 
	/// For example, the following document:
	/// {
	///    "maxPlayers":3,
	///    "gamemode":{
	///      "map":"level3-a",
	///      "extraFooEnabled":true
	///    }
	/// }
	/// 
	/// will be indexed with the following keys:
	/// - "numplayers": 3 (numeric)
	/// - "gamemode.map":"level3-a" (string)
	/// - "gamemode.extraFooEnabled":true (bool)
	/// 
	/// To enable search without filtering, set indexedDocument to an empty json object '{}'.
	/// </remarks>
	std::string indexedDocument;

	MSGPACK_DEFINE(gameFinderName, customData, onlyLeaderCanInvite, isJoinable, indexedDocument);
};

Parties can be searched by calling PartyApi::Search() with a json Stormancer filter as the argument. Only clauses compatible with the Lucene query parser are supported (see Stormancer.Server.Plugins.Queries).

{
	"bool":{
		"must":[
			{
				"term":"numplayers",
				"value":2
			},
			{
				"term":"gamemode.map",
				"value":"level3-a"
			}]
	}

Validating party settings and party member data

Party settings and party member data can be validated by creating a class implementing IPartyEventHandler and the methods OnUpdatingSettings and OnUpdatingPartyMemberData. Both APIs support denying the update and providing an error string sent back to

Customizing ready state changes

Validating setting the player state as ready

The state of a player can be validated when they try setting themselves as ready by implementing IPartyEventHandler.OnUpdatingPlayerReadyState. This method can perform validation and set a custom error string to be sent back to the client in case of failure.

Customizing ready reset.

By default, the ready state resets to NotReady if any of the following conditions are met:

  • The list of players in the party changes.
  • Party settings are updated.
  • The custom data of any party members are updated.

This behavior can be customized through two mechanisms:

  • Party configuration
  • The Party IPartyEventHandler extensibility point.

Note that preventing reset of the ready state also disable automated matchmaking cancellation in all the situations that would have reset it, for instance if a player in the party disconnects while matchmaking is in progress. However as data about the parties are sent to the matchmaker only when matchmaking starts, they may become out of date. Manually resetting the ready state still cancels matchmaking as only automated reset is disabled.

Party Configuration

The list of events the ready state should reset in can be set in the party configuration. ResetPlayerReadyStateMode.None and ResetPlayerReadyStateMode.All are convenient shortcuts. By default, the option is set as `ResetPlayerReadyStateMode.All

public class TestPlugin : IHostPlugin
{
    public void Build(HostPluginBuildContext ctx)
    {
        ctx.HostStarting += (IHost host) =>
        {
            host.ConfigurePlayerParty(p => p.ResetPlayerReadyStateOn(ResetPlayerReadyStateMode.PartySettingsUpdated | ResetPlayerReadyStateMode.PartyMemberDataUpdated | ResetPlayerReadyStateMode.PartyMembersListUpdated));
		}
	}
}

It's also possible to provide a custom lambda to drive the reset logic. For instance :

public class TestPlugin : IHostPlugin
{
    public void Build(HostPluginBuildContext ctx)
    {
        ctx.HostStarting += (IHost host) =>
        {
            var value = ResetPlayerReadyStateMode.All; //Always reset
            host.ConfigurePlayerParty(p => p.ResetPlayerReadyStateOn(ctx =>
            {
                switch (ctx.EventType)
                {
                    case PartyMemberReadyStateResetEventType.PartySettingsUpdated:
                        if ((value & ResetPlayerReadyStateMode.PartySettingsUpdated) != 0)
                        {
                            ctx.ShouldReset = true;
                        }
                        break;
                    case PartyMemberReadyStateResetEventType.PartyMemberDataUpdated:
                        if ((value & ResetPlayerReadyStateMode.PartyMemberDataUpdated) != 0)
                        {
                            ctx.ShouldReset = true;
                        }
                        break;
                    case PartyMemberReadyStateResetEventType.PartyMembersListUpdated:
                        if ((value & ResetPlayerReadyStateMode.PartyMembersListUpdated) != 0)
                        {
                            ctx.ShouldReset = true;
                        }
                        break;
                }
            }));
		}
	}
}
A IPartyEventHandler implementation.

Implement IPartyEventHandler.OnPlayerReadyStateReset in an event handler to control when the the ready state should be reset depending on custom logic.

Product Compatible and additional computed target framework versions.
.NET net6.0 is compatible.  net6.0-android was computed.  net6.0-ios was computed.  net6.0-maccatalyst was computed.  net6.0-macos was computed.  net6.0-tvos was computed.  net6.0-windows was computed.  net7.0 was computed.  net7.0-android was computed.  net7.0-ios was computed.  net7.0-maccatalyst was computed.  net7.0-macos was computed.  net7.0-tvos was computed.  net7.0-windows was computed.  net8.0 was computed.  net8.0-android was computed.  net8.0-browser was computed.  net8.0-ios was computed.  net8.0-maccatalyst was computed.  net8.0-macos was computed.  net8.0-tvos was computed.  net8.0-windows was computed.  net9.0 was computed.  net9.0-android was computed.  net9.0-browser was computed.  net9.0-ios was computed.  net9.0-maccatalyst was computed.  net9.0-macos was computed.  net9.0-tvos was computed.  net9.0-windows was computed.  net10.0 was computed.  net10.0-android was computed.  net10.0-browser was computed.  net10.0-ios was computed.  net10.0-maccatalyst was computed.  net10.0-macos was computed.  net10.0-tvos was computed.  net10.0-windows was computed. 
Compatible target framework(s)
Included target framework(s) (in package)
Learn more about Target Frameworks and .NET Standard.

NuGet packages (5)

Showing the top 5 NuGet packages that depend on Stormancer.Server.Plugins.Party:

Package Downloads
Stormancer.Server.Plugins.Steam

Steam integration for Stormancer server applications.

Stormancer.Server.Plugins.Friends

Provides a friend system to Stormancer applications.

Stormancer.Server.Plugins.Epic

Provides Epic Games integration to Stormancer server applications.

Stormancer.Server.Plugins.PartyMerging

Enables party merging according to customizable algorithms.

Stormancer.Server.Plugins.SampleApp

The core features of the Stormancer sample application in a nuget package.

GitHub repositories

This package is not used by any popular GitHub repositories.

Version Downloads Last Updated
5.2.1.2-pre 217 5/13/2025
5.2.1-pre 157 3/20/2025
5.2.0.87 174 2/28/2025
5.2.0.87-pre 122 11/20/2024
5.2.0.86-pre 194 9/30/2024
5.2.0.85-pre 95 9/30/2024
5.2.0.83-pre 141 9/27/2024
5.2.0.76-pre 129 9/26/2024
5.2.0.75-pre 135 9/26/2024
5.2.0.74-pre 210 9/8/2024
5.2.0.73-pre 109 9/6/2024
5.2.0.71-pre 159 7/29/2024
5.2.0.69-pre 106 7/26/2024
5.2.0.58-pre 114 7/24/2024
5.2.0.57-pre 145 7/9/2024
5.2.0.53-pre 108 7/3/2024
5.2.0.52-pre 114 6/19/2024
5.2.0.51-pre 110 6/18/2024
5.2.0.50-pre 111 6/17/2024
5.2.0.49-pre 106 6/14/2024
5.2.0.45-pre 117 6/10/2024
5.2.0.44-pre 134 5/12/2024
5.2.0.43-pre 91 5/12/2024
5.2.0.42-pre 149 4/22/2024
5.2.0.41-pre 117 4/17/2024
5.2.0.39-pre 124 4/16/2024
5.2.0.38-pre 128 4/8/2024
5.2.0.37-pre 91 4/8/2024
5.2.0.36-pre 160 4/2/2024
5.2.0.35-pre 110 3/14/2024
5.2.0.34-pre 141 3/11/2024
5.2.0.30-pre 113 2/23/2024
5.2.0.29-pre 198 12/12/2023
5.2.0.28-pre 125 12/11/2023
5.2.0.27-pre 137 12/11/2023
5.2.0.26-pre 195 12/1/2023
5.2.0.25-pre 170 11/24/2023
5.2.0.18-pre 188 11/20/2023
5.2.0.15-pre 233 10/27/2023
5.2.0.14-pre 212 10/20/2023
5.2.0.13-pre 166 10/19/2023
5.2.0.12-pre 172 10/18/2023
5.2.0.11-pre 181 10/12/2023
5.2.0.10-pre 158 10/10/2023
5.2.0.8-pre 160 10/5/2023
5.2.0.4-pre 152 10/5/2023
5.2.0.1-pre 165 10/4/2023
5.1.0.33-pre 261 8/18/2023
5.1.0.32-pre 228 8/1/2023
5.1.0.31-pre 183 8/1/2023
5.1.0.30-pre 229 7/5/2023
5.1.0.29-pre 171 7/5/2023
5.1.0.28-pre 189 6/29/2023
5.1.0.27-pre 161 6/27/2023
5.1.0.25-pre 204 6/27/2023
5.1.0.24-pre 154 6/27/2023
5.1.0.23-pre 220 6/26/2023
5.1.0.22-pre 184 6/23/2023
5.1.0.21-pre 158 6/21/2023
5.1.0.20-pre 175 6/21/2023
5.1.0.18-pre 165 6/21/2023
5.1.0.17-pre 182 6/16/2023
5.1.0.16-pre 169 6/15/2023
5.1.0.15-pre 198 6/13/2023
5.1.0.14-pre 182 6/6/2023
5.1.0.13-pre 189 6/5/2023
5.1.0.12-pre 184 5/26/2023
5.1.0.11-pre 181 5/25/2023
5.1.0.10-pre 168 5/25/2023
5.1.0.9-pre 176 5/25/2023
5.1.0.8-pre 169 5/24/2023
5.1.0.7-pre 177 5/24/2023
5.1.0.6-pre 178 5/23/2023
5.1.0.5-pre 168 5/22/2023
5.1.0.4-pre 166 5/22/2023
5.1.0.3-pre 167 5/17/2023
5.1.0.2-pre 174 5/14/2023
5.1.0.1-pre 141 5/12/2023
5.1.0-pre 174 5/11/2023
5.0.1.9-pre 178 5/10/2023
5.0.1.8-pre 196 5/9/2023
5.0.1.7 312 5/9/2023
5.0.1.7-pre 167 4/30/2023
5.0.1.6-pre 173 4/25/2023
5.0.1.5-pre 173 4/24/2023
5.0.1.4-pre 194 4/21/2023
5.0.1.3-pre 175 4/21/2023
5.0.1.2-pre 191 4/21/2023
5.0.1.1-pre 194 4/17/2023
5.0.1-pre 190 4/11/2023
5.0.0.2 374 4/4/2023
5.0.0.2-pre 258 3/7/2023
5.0.0.1-pre 216 1/17/2023
5.0.0-pre 214 1/17/2023
4.5.1-pre 215 1/12/2023
4.5.0-pre 210 1/10/2023
4.4.0.3-pre 206 1/4/2023
4.4.0.2-pre 203 1/4/2023
4.4.0.1-pre 189 1/3/2023
4.4.0-pre 204 1/3/2023
4.3.3.1-pre 204 12/21/2022
4.3.3-pre 201 12/7/2022
4.3.2-pre 179 12/6/2022
4.3.1.13 906 10/26/2022
4.3.1.12 981 9/28/2022
4.3.1.12-pre 249 9/23/2022
4.3.1.9-pre 224 9/23/2022
4.3.1.7-pre 237 9/19/2022
4.3.1.6-pre 249 9/12/2022
4.3.1.4-pre 416 8/2/2022
4.3.1.3-pre 245 7/19/2022
4.3.1-pre 278 7/1/2022
4.3.0.1-pre 237 9/20/2022
4.3.0-pre 262 6/9/2022
4.2.0.18-pre 326 5/3/2022
4.2.0.17-pre 246 5/2/2022
4.2.0.16-pre 253 4/29/2022
4.2.0.14-pre 260 4/21/2022
4.2.0.13-pre 279 4/14/2022
4.2.0.12-pre 220 4/13/2022
4.2.0.11-pre 242 4/12/2022
4.2.0.10-pre 248 3/23/2022
4.2.0.2-pre 229 3/22/2022
4.1.4.4-pre 277 3/15/2022
4.1.4.3-pre 264 2/28/2022
4.1.4.2 776 2/7/2022
4.1.4.1 767 2/1/2022
4.1.4.1-pre 246 2/1/2022
4.1.4-pre 285 1/27/2022
4.1.3-pre 235 1/26/2022
4.1.2.5-pre 264 1/26/2022
4.1.2.1 765 1/21/2022
4.1.1.6 805 1/4/2022
4.1.1.4 479 12/15/2021
4.1.1.4-pre 312 10/29/2021
4.1.1.1-pre 328 10/28/2021
4.1.1-pre 369 10/18/2021
4.1.0.5 512 10/14/2021
4.1.0.5-pre 423 10/1/2021
4.1.0.4-pre 303 9/20/2021
4.1.0-pre 309 9/19/2021
4.0.4.2 638 5/23/2021
4.0.4.2-pre 508 5/12/2021
4.0.3 656 4/29/2021
4.0.2 484 4/19/2021
4.0.2-pre 308 4/12/2021
4.0.1 624 3/1/2021
4.0.0.2 685 12/9/2020
4.0.0.1 684 12/4/2020
3.2.2.4 723 10/20/2020
3.2.2.4-pre 390 10/5/2020
3.2.2.3-pre 422 9/23/2020
3.2.2.2-pre 436 9/16/2020
3.2.1-pre 463 8/29/2020
3.2.0.4-pre 396 8/21/2020
3.2.0.3-pre 422 8/20/2020
3.1.0 906 5/27/2020
3.1.0-pre 588 5/20/2020
3.0.0.1-pre 675 4/2/2020
3.0.0-pre 495 4/2/2020
2.2.0.1-pre 532 3/29/2020
2.1.0-pre 523 3/12/2020
2.0.0.1-pre 425 3/6/2020
2.0.0 936 2/21/2020
2.0.0-pre 571 2/22/2020
1.1.0 773 1/29/2020
1.0.0.3 699 1/4/2020
1.0.0.2 698 1/4/2020
1.0.0.1 709 1/4/2020

Changed
*******
- Remove Dependency to Stormancer.Abstractions.Server because it's implicit.
- Send IndexedDocument as part of party updated events.
- Add configuration and event handler extensibility points to control when ready state is reset, validate ready state changes and user data updates.