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 171 2/28/2025
5.2.0.87-pre 121 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 105 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 133 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 260 8/18/2023
5.1.0.32-pre 227 8/1/2023
5.1.0.31-pre 182 8/1/2023
5.1.0.30-pre 228 7/5/2023
5.1.0.29-pre 170 7/5/2023
5.1.0.28-pre 188 6/29/2023
5.1.0.27-pre 160 6/27/2023
5.1.0.25-pre 203 6/27/2023
5.1.0.24-pre 153 6/27/2023
5.1.0.23-pre 219 6/26/2023
5.1.0.22-pre 183 6/23/2023
5.1.0.21-pre 157 6/21/2023
5.1.0.20-pre 174 6/21/2023
5.1.0.18-pre 164 6/21/2023
5.1.0.17-pre 181 6/16/2023
5.1.0.16-pre 168 6/15/2023
5.1.0.15-pre 197 6/13/2023
5.1.0.14-pre 181 6/6/2023
5.1.0.13-pre 188 6/5/2023
5.1.0.12-pre 183 5/26/2023
5.1.0.11-pre 180 5/25/2023
5.1.0.10-pre 167 5/25/2023
5.1.0.9-pre 175 5/25/2023
5.1.0.8-pre 168 5/24/2023
5.1.0.7-pre 176 5/24/2023
5.1.0.6-pre 176 5/23/2023
5.1.0.5-pre 167 5/22/2023
5.1.0.4-pre 165 5/22/2023
5.1.0.3-pre 166 5/17/2023
5.1.0.2-pre 173 5/14/2023
5.1.0.1-pre 140 5/12/2023
5.1.0-pre 173 5/11/2023
5.0.1.9-pre 177 5/10/2023
5.0.1.8-pre 195 5/9/2023
5.0.1.7 311 5/9/2023
5.0.1.7-pre 166 4/30/2023
5.0.1.6-pre 172 4/25/2023
5.0.1.5-pre 172 4/24/2023
5.0.1.4-pre 193 4/21/2023
5.0.1.3-pre 174 4/21/2023
5.0.1.2-pre 190 4/21/2023
5.0.1.1-pre 193 4/17/2023
5.0.1-pre 189 4/11/2023
5.0.0.2 373 4/4/2023
5.0.0.2-pre 257 3/7/2023
5.0.0.1-pre 215 1/17/2023
5.0.0-pre 213 1/17/2023
4.5.1-pre 214 1/12/2023
4.5.0-pre 209 1/10/2023
4.4.0.3-pre 205 1/4/2023
4.4.0.2-pre 200 1/4/2023
4.4.0.1-pre 188 1/3/2023
4.4.0-pre 203 1/3/2023
4.3.3.1-pre 203 12/21/2022
4.3.3-pre 200 12/7/2022
4.3.2-pre 178 12/6/2022
4.3.1.13 905 10/26/2022
4.3.1.12 980 9/28/2022
4.3.1.12-pre 248 9/23/2022
4.3.1.9-pre 223 9/23/2022
4.3.1.7-pre 236 9/19/2022
4.3.1.6-pre 248 9/12/2022
4.3.1.4-pre 415 8/2/2022
4.3.1.3-pre 244 7/19/2022
4.3.1-pre 277 7/1/2022
4.3.0.1-pre 236 9/20/2022
4.3.0-pre 261 6/9/2022
4.2.0.18-pre 325 5/3/2022
4.2.0.17-pre 245 5/2/2022
4.2.0.16-pre 252 4/29/2022
4.2.0.14-pre 259 4/21/2022
4.2.0.13-pre 278 4/14/2022
4.2.0.12-pre 219 4/13/2022
4.2.0.11-pre 241 4/12/2022
4.2.0.10-pre 247 3/23/2022
4.2.0.2-pre 228 3/22/2022
4.1.4.4-pre 276 3/15/2022
4.1.4.3-pre 263 2/28/2022
4.1.4.2 775 2/7/2022
4.1.4.1 766 2/1/2022
4.1.4.1-pre 245 2/1/2022
4.1.4-pre 284 1/27/2022
4.1.3-pre 234 1/26/2022
4.1.2.5-pre 263 1/26/2022
4.1.2.1 764 1/21/2022
4.1.1.6 804 1/4/2022
4.1.1.4 478 12/15/2021
4.1.1.4-pre 311 10/29/2021
4.1.1.1-pre 327 10/28/2021
4.1.1-pre 368 10/18/2021
4.1.0.5 511 10/14/2021
4.1.0.5-pre 422 10/1/2021
4.1.0.4-pre 302 9/20/2021
4.1.0-pre 308 9/19/2021
4.0.4.2 637 5/23/2021
4.0.4.2-pre 507 5/12/2021
4.0.3 655 4/29/2021
4.0.2 483 4/19/2021
4.0.2-pre 306 4/12/2021
4.0.1 623 3/1/2021
4.0.0.2 684 12/9/2020
4.0.0.1 683 12/4/2020
3.2.2.4 722 10/20/2020
3.2.2.4-pre 389 10/5/2020
3.2.2.3-pre 421 9/23/2020
3.2.2.2-pre 435 9/16/2020
3.2.1-pre 462 8/29/2020
3.2.0.4-pre 394 8/21/2020
3.2.0.3-pre 420 8/20/2020
3.1.0 904 5/27/2020
3.1.0-pre 586 5/20/2020
3.0.0.1-pre 672 4/2/2020
3.0.0-pre 493 4/2/2020
2.2.0.1-pre 530 3/29/2020
2.1.0-pre 521 3/12/2020
2.0.0.1-pre 423 3/6/2020
2.0.0 934 2/21/2020
2.0.0-pre 569 2/22/2020
1.1.0 771 1/29/2020
1.0.0.3 697 1/4/2020
1.0.0.2 696 1/4/2020
1.0.0.1 707 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.