API Reference of GS2-Matchmaking SDK for Game Engine

Model

EzGathering

Gathering

An entity representing a group of game players brought together by matchmaking. It has multiple parameters for matchmaking, and the players are grouped based on the totality of the parameters.

	Type	Require	Default	Limitation	Description
gatheringId	string	✓		~ 1024 chars	Gathering GRN
name	string	✓	UUID	~ 128 chars	Gathering Name
attributeRanges	List<EzAttributeRange>		[]	~ 5 items	Terms and Conditions
capacityOfRoles	List<EzCapacityOfRole>	✓	[]	1 ~ 5 items	List of application limit
allowUserIds	List<string>		[]	~ 100 items	User ID allowed to participate
metadata	string			~ 1024 chars	metadata
expiresAt	long				Gathering expiration date
createdAt	long	✓			Datetime of creation
updatedAt	long	✓			Datetime of last update

EzRatingModel

Rating Model

GS2 uses Glicko-2 as its rating algorithm. Glicko-2 has several parameters, but GS2-Matchmaking aggregates them into a single parameter, volatility, which represents the totality of the parameters. Volatility is a parameter that expresses the magnitude of change; the larger the value, the greater the change in the rating value.

	Type	Require	Default	Limitation	Description
name	string	✓		~ 128 chars	Rating Model Name
metadata	string			~ 128 chars	metadata
volatility	int	✓	100	1 ~ 20000	Magnitude of rate value fluctuation

EzAttributeRange

	Type	Require	Default	Limitation	Description
name	string	✓		~ 128 chars	Attribute Name
min	int	✓	0	~ 2147483646	Minimum attribute values that can participate in the Gathering
max	int	✓	0	~ 2147483646	Maximum value of attributes that can participate in the Gathering

EzCapacityOfRole

	Type	Require	Default	Limitation	Description
roleName	string	✓	“default”	~ 128 chars	Role Name
roleAliases	List<string>		[]	~ 9 items	List of Role Name Aliases
capacity	int	✓		1 ~ 256	Number of applicants
participants	List<EzPlayer>		[]	~ 1000 items	List of Participant Players

EzAttribute

	Type	Require	Default	Limitation	Description
name	string	✓		~ 128 chars	Attribute Name
value	int	✓	0	~ 2147483646	Attribute value

EzPlayer

	Type	Require	Default	Limitation	Description
userId	string	✓		~ 128 chars	User Id
attributes	List<EzAttribute>		[]	~ 5 items	List of Attributes
roleName	string	✓	“default”	~ 128 chars	Role Name
denyUserIds	List<string>		[]	~ 100 items	List of user IDs that are denied participation

EzRating

Rating

An entity that holds the current rating value for each game player.

	Type	Require	Default	Limitation	Description
ratingId	string	✓		~ 1024 chars	Rating GRN
name	string	✓		~ 128 chars	Rating Name
userId	string	✓		~ 128 chars	User Id
rateValue	float	✓	1500.0	~ 65535.0
createdAt	long	✓			Datetime of creation
updatedAt	long	✓			Datetime of last update

EzGameResult

	Type	Require	Default	Limitation	Description
rank	int	✓		~ 2147483646	Rank
userId	string	✓		~ 128 chars	User Id

EzBallot

	Type	Require	Limitation	Description
userId	string	✓	~ 128 chars	User Id
ratingName	string	✓	~ 128 chars	Rating name used for rating calculations
gatheringName	string	✓	~ 128 chars	Name of Gathering to be voted
numberOfPlayer	int	✓	2 ~ 10	Number of participants

EzSignedBallot

	Type	Require	Default	Limitation	Description
body	string	✓		~ 1024 chars	Data for ballot signature targets
signature	string	✓		~ 256 chars	Signature

EzTimeSpan

	Type	Require	Limitation	Description
days	int	✓	~ 365	Number of days from current time
hours	int	✓	~ 24	Hours from current time
minutes	int	✓	~ 60	Minutes from current time

Methods

cancelMatchmaking

Cancel Matchmaking and leave the Gathering in which you are participating.

If matchmaking is completed before leaving the gathering, a NotFoundException (404 error) will be raised and failure will occur.

Request

	Type	Require	Default	Limitation	Description
namespaceName	string	✓		~ 32 chars	Namespace name
gatheringName	string	✓	UUID	~ 128 chars	Gathering Name
accessToken	string	✓		~ 128 chars	User Id

Result

	Type	Description
item	EzGathering	Canceled Gathering

Implementation Example

    var domain = gs2.Matchmaking.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    ).Gathering(
        gatheringName: "gathering-0001"
    );
    var result = await domain.CancelMatchmakingAsync(
    );

    var domain = gs2.Matchmaking.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    ).Gathering(
        gatheringName: "gathering-0001"
    );
    var future = domain.CancelMatchmakingFuture(
    );
    yield return future;
    if (future.Error != null)
    {
        onError.Invoke(future.Error, null);
        yield break;
    }

    const auto Domain = Gs2->Matchmaking->Namespace(
        "namespace-0001" // namespaceName
    )->Me(
        AccessToken
    )->Gathering(
        "gathering-0001" // gatheringName
    );
    const auto Future = Domain->CancelMatchmaking(
    );
    Future->StartSynchronousTask();
    if (Future->GetTask().IsError())
    {
        return false;
    }

createGathering

Create a new Gathering

The user ID for the player’s own player information specified in Player can be omitted. The expiration date of the gathering can be set by specifying “expiresAt”. If no expiration date is used, old gatherings will remain, and when a match is made The user may have left the game. If you use an expiration date, you should prompt the user to recreate the gathering each time the expiration date comes up.

Request

	Type	Require	Default	Limitation	Description
namespaceName	string	✓		~ 32 chars	Namespace name
accessToken	string	✓		~ 128 chars	User Id
player	EzPlayer	✓			Own player information
attributeRanges	List<EzAttributeRange>		[]	~ 5 items	Terms and Conditions
capacityOfRoles	List<EzCapacityOfRole>	✓	[]	1 ~ 5 items	List of application limit
allowUserIds	List<string>		[]	~ 100 items	User ID allowed to participate
expiresAt	long				Gathering expiration date
expiresAtTimeSpan	EzTimeSpan				Time to expiration

Result

	Type	Description
item	EzGathering	Created Gathering

Implementation Example

    var domain = gs2.Matchmaking.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    );
    var result = await domain.CreateGatheringAsync(
        player:     new Gs2.Unity.Gs2Matchmaking.Model.EzPlayer {
                Attributes = new List<Gs2.Unity.Gs2Matchmaking.Model.EzAttribute> {
                new Gs2.Unity.Gs2Matchmaking.Model.EzAttribute {
                    Name = "stage",
                    Value = 1,
                },
                new Gs2.Unity.Gs2Matchmaking.Model.EzAttribute {
                    Name = "level",
                    Value = 10,
                },
            },
            },
        attributeRanges: new Gs2.Unity.Gs2Matchmaking.Model.EzAttributeRange[] {
                new Gs2.Unity.Gs2Matchmaking.Model.EzAttributeRange {
                Name = "stage",
                Min = 1,
                Max = 1,
            },
                new Gs2.Unity.Gs2Matchmaking.Model.EzAttributeRange {
                Name = "level",
                Min = 0,
                Max = 10,
            },
        },
        capacityOfRoles: new Gs2.Unity.Gs2Matchmaking.Model.EzCapacityOfRole[] {
                new Gs2.Unity.Gs2Matchmaking.Model.EzCapacityOfRole {
                RoleName = "default",
                Capacity = 4,
            },
        },
        allowUserIds: null,
        expiresAt: null,
        expiresAtTimeSpan: null
    );
    var item = await result.ModelAsync();

    var domain = gs2.Matchmaking.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    );
    var future = domain.CreateGatheringFuture(
        player:     new Gs2.Unity.Gs2Matchmaking.Model.EzPlayer {
                Attributes = new List<Gs2.Unity.Gs2Matchmaking.Model.EzAttribute> {
                new Gs2.Unity.Gs2Matchmaking.Model.EzAttribute {
                    Name = "stage",
                    Value = 1,
                },
                new Gs2.Unity.Gs2Matchmaking.Model.EzAttribute {
                    Name = "level",
                    Value = 10,
                },
            },
            },
        attributeRanges: new Gs2.Unity.Gs2Matchmaking.Model.EzAttributeRange[] {
                new Gs2.Unity.Gs2Matchmaking.Model.EzAttributeRange {
                Name = "stage",
                Min = 1,
                Max = 1,
            },
                new Gs2.Unity.Gs2Matchmaking.Model.EzAttributeRange {
                Name = "level",
                Min = 0,
                Max = 10,
            },
        },
        capacityOfRoles: new Gs2.Unity.Gs2Matchmaking.Model.EzCapacityOfRole[] {
                new Gs2.Unity.Gs2Matchmaking.Model.EzCapacityOfRole {
                RoleName = "default",
                Capacity = 4,
            },
        },
        allowUserIds: null,
        expiresAt: null,
        expiresAtTimeSpan: null
    );
    yield return future;
    if (future.Error != null)
    {
        onError.Invoke(future.Error, null);
        yield break;
    }
    var future2 = future.Result.Model();
    yield return future2;
    if (future2.Error != null)
    {
        onError.Invoke(future2.Error, null);
        yield break;
    }
    var result = future2.Result;

    const auto Domain = Gs2->Matchmaking->Namespace(
        "namespace-0001" // namespaceName
    )->Me(
        AccessToken
    );
    const auto Future = Domain->CreateGathering(
        MakeShared<Gs2::Matchmaking::Model::FPlayer>()
            ->WithAttributes([]
            {
                const auto v = MakeShared<TArray<TSharedPtr<Gs2::Matchmaking::Model::FAttribute>>>();
                v->Add(MakeShared<Gs2::Matchmaking::Model::FAttribute>()
                    ->WithName(TOptional<FString>("stage"))
                    ->WithValue(TOptional<int32>(1)));
                v->Add(MakeShared<Gs2::Matchmaking::Model::FAttribute>()
                    ->WithName(TOptional<FString>("level"))
                    ->WithValue(TOptional<int32>(10)));
                return v;
            }()),
        []
        {
            const auto v = MakeShared<TArray<TSharedPtr<Gs2::Matchmaking::Model::FAttributeRange>>>();
            v->Add(MakeShared<Gs2::Matchmaking::Model::FAttributeRange>()
                ->WithName(TOptional<FString>("stage"))
                ->WithMin(TOptional<int32>(1))
                ->WithMax(TOptional<int32>(1)));
            v->Add(MakeShared<Gs2::Matchmaking::Model::FAttributeRange>()
                ->WithName(TOptional<FString>("level"))
                ->WithMin(TOptional<int32>(0))
                ->WithMax(TOptional<int32>(10)));
            return v;
        }(), // attributeRanges
        []
        {
            const auto v = MakeShared<TArray<TSharedPtr<Gs2::Matchmaking::Model::FCapacityOfRole>>>();
            v->Add(MakeShared<Gs2::Matchmaking::Model::FCapacityOfRole>()
                ->WithRoleName(TOptional<FString>("default"))
                ->WithCapacity(TOptional<int32>(4)));
            return v;
        }(), // capacityOfRoles
        nullptr, // allowUserIds
        nullptr, // expiresAt
        nullptr // expiresAtTimeSpan
    );
    Future->StartSynchronousTask();
    if (Future->GetTask().IsError())
    {
        return false;
    }

    // obtain changed values / result values
    const auto Future2 = Future->GetTask().Result()->Model();
    Future2->StartSynchronousTask();
    if (!TestFalse(WHAT, Future2->GetTask().IsError())) return false;
    const auto Result = Future2->GetTask().Result();

doMatchmaking

Find and join a gathering that you can participate in among those that already exist.

Search for a certain period of time and return a matchmaking status token if the target is not found. Next time, you can resume the search process from the previous time by submitting a request again with a token to keep the matchmaking status. When all gatherings are searched but there is no gathering to join, null is returned for both the gathering and the token.

Request

	Type	Require	Limitation	Description
namespaceName	string	✓	~ 32 chars	Namespace name
accessToken	string	✓	~ 128 chars	User Id
player	EzPlayer	✓		Own player information
matchmakingContextToken	string		~ 5120 chars	Used to resume search Token that holds matchmaking state

Result

	Type	Description
item	EzGathering	Participated Gatherings
matchmakingContextToken	string	Token that preserves matchmaking status

Implementation Example

    var domain = gs2.Matchmaking.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    );
    var items = await domain.DoMatchmakingAsync(
    ).ToListAsync();

    var domain = gs2.Matchmaking.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    );
    var it = domain.DoMatchmaking(
    );

    while (it.HasNext())
    {
        yield return it.Next();
        if (it.Error != null)
        {
            onError.Invoke(it.Error, null);
            break;
        }
        if (it.Current != null)
        {
            items.Add(it.Current);
        }
        else
        {
            break;
        }
    }

    const auto Domain = Gs2->Matchmaking->Namespace(
        "namespace-0001" // namespaceName
    )->Me(
        AccessToken
    );
    const auto It = Domain->DoMatchmaking( // player
    );
    for (auto Item : *It)
    {

    }

getGathering

Get the latest Gathering status

Request

	Type	Require	Default	Limitation	Description
namespaceName	string	✓		~ 32 chars	Namespace name
gatheringName	string	✓	UUID	~ 128 chars	Gathering Name

Result

	Type	Description
item	EzGathering	Gathering

Implementation Example

    var domain = gs2.Matchmaking.Namespace(
        namespaceName: "namespace-0001"
    ).User(
        userId: "user-0001"
    ).Gathering(
        gatheringName: "gathering-0001"
    );
    var item = await domain.ModelAsync();

    var domain = gs2.Matchmaking.Namespace(
        namespaceName: "namespace-0001"
    ).User(
        userId: "user-0001"
    ).Gathering(
        gatheringName: "gathering-0001"
    );
    var future = domain.Model();
    yield return future;
    var item = future.Result;

    const auto Domain = Gs2->Matchmaking->Namespace(
        "namespace-0001" // namespaceName
    )->User(
        "user-0001" // userId
    )->Gathering(
        "gathering-0001" // gatheringName
    );
    const auto Future = Domain.Model();
    Future->StartSynchronousTask();
    if (Future->GetTask().IsError())
    {
        return false;
    }

Value change event handling

    var domain = gs2.Matchmaking.Namespace(
        namespaceName: "namespace-0001"
    ).User(
        userId: "user-0001"
    ).Gathering(
        gatheringName: "gathering-0001"
    );
    
    // Start event handling
    var callbackId = domain.Subscribe(
        value => {
            // Called when the value changes
            // The "value" is passed the value after the change.
        }
    );

    // Stop event handling
    domain.Unsubscribe(callbackId);

    var domain = gs2.Matchmaking.Namespace(
        namespaceName: "namespace-0001"
    ).User(
        userId: "user-0001"
    ).Gathering(
        gatheringName: "gathering-0001"
    );
    var future = domain.Model();
    yield return future;
    var item = future.Result;

    const auto Domain = Gs2->Matchmaking->Namespace(
        "namespace-0001" // namespaceName
    )->User(
        "user-0001" // userId
    )->Gathering(
        "gathering-0001" // gatheringName
    );
    
    // Start event handling
    const auto CallbackId = Domain->Subscribe(
        [](TSharedPtr<Gs2::Matchmaking::Model::FGathering> value) {
            // Called when the value changes
            // The "value" is passed the value after the change.
        }
    );

    // Stop event handling
    Domain->Unsubscribe(CallbackId);

Warning

This event is called when the value in the local cache that the SDK has is changed.

The local cache will only be changed by executing the SDK’s API, or by executing a stamp sheet via GS2-Distributor with GS2-Gateway notification enabled, or by executing a GS2-JobQueue with GS2-Gateway notification enabled. GS2-Gateway notification enabled.

Therefore, callbacks will not be invoked if the value is changed in any other way.

updateGathering

Change Gathering Application Requirements

Request

	Type	Require	Default	Limitation	Description
namespaceName	string	✓		~ 32 chars	Namespace name
gatheringName	string	✓	UUID	~ 128 chars	Gathering Name
accessToken	string	✓		~ 128 chars	User Id
attributeRanges	List<EzAttributeRange>		[]	~ 5 items	Terms and Conditions

Result

	Type	Description
item	EzGathering	Updated Gathering

Implementation Example

    var domain = gs2.Matchmaking.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    ).Gathering(
        gatheringName: "gathering-0001"
    );
    var result = await domain.UpdateGatheringAsync(
        attributeRanges: new Gs2.Unity.Gs2Matchmaking.Model.EzAttributeRange[] {
                new Gs2.Unity.Gs2Matchmaking.Model.EzAttributeRange {
                Name = "stage",
                Min = 1,
                Max = 1,
            },
                new Gs2.Unity.Gs2Matchmaking.Model.EzAttributeRange {
                Name = "level",
                Min = 0,
                Max = 50,
            },
        }
    );
    var item = await result.ModelAsync();

    var domain = gs2.Matchmaking.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    ).Gathering(
        gatheringName: "gathering-0001"
    );
    var future = domain.UpdateGatheringFuture(
        attributeRanges: new Gs2.Unity.Gs2Matchmaking.Model.EzAttributeRange[] {
                new Gs2.Unity.Gs2Matchmaking.Model.EzAttributeRange {
                Name = "stage",
                Min = 1,
                Max = 1,
            },
                new Gs2.Unity.Gs2Matchmaking.Model.EzAttributeRange {
                Name = "level",
                Min = 0,
                Max = 50,
            },
        }
    );
    yield return future;
    if (future.Error != null)
    {
        onError.Invoke(future.Error, null);
        yield break;
    }
    var future2 = future.Result.Model();
    yield return future2;
    if (future2.Error != null)
    {
        onError.Invoke(future2.Error, null);
        yield break;
    }
    var result = future2.Result;

    const auto Domain = Gs2->Matchmaking->Namespace(
        "namespace-0001" // namespaceName
    )->Me(
        AccessToken
    )->Gathering(
        "gathering-0001" // gatheringName
    );
    const auto Future = Domain->UpdateGathering(
        []
        {
            const auto v = MakeShared<TArray<TSharedPtr<Gs2::Matchmaking::Model::FAttributeRange>>>();
            v->Add(MakeShared<Gs2::Matchmaking::Model::FAttributeRange>()
                ->WithName(TOptional<FString>("stage"))
                ->WithMin(TOptional<int32>(1))
                ->WithMax(TOptional<int32>(1)));
            v->Add(MakeShared<Gs2::Matchmaking::Model::FAttributeRange>()
                ->WithName(TOptional<FString>("level"))
                ->WithMin(TOptional<int32>(0))
                ->WithMax(TOptional<int32>(50)));
            return v;
        }() // attributeRanges
    );
    Future->StartSynchronousTask();
    if (Future->GetTask().IsError())
    {
        return false;
    }

    // obtain changed values / result values
    const auto Future2 = Future->GetTask().Result()->Model();
    Future2->StartSynchronousTask();
    if (!TestFalse(WHAT, Future2->GetTask().IsError())) return false;
    const auto Result = Future2->GetTask().Result();

getRatingModel

Get a rating model by specifying a rating name

Request

	Type	Require	Default	Limitation	Description
namespaceName	string	✓		~ 32 chars	Namespace name
ratingName	string	✓		~ 128 chars	Rating Model Name

Result

	Type	Description
item	EzRatingModel	Rating Model

Implementation Example

    var domain = gs2.Matchmaking.Namespace(
        namespaceName: "namespace-0001"
    ).RatingModel(
        ratingName: "mode1"
    );
    var item = await domain.ModelAsync();

    var domain = gs2.Matchmaking.Namespace(
        namespaceName: "namespace-0001"
    ).RatingModel(
        ratingName: "mode1"
    );
    var future = domain.Model();
    yield return future;
    var item = future.Result;

    const auto Domain = Gs2->Matchmaking->Namespace(
        "namespace-0001" // namespaceName
    )->RatingModel(
        "mode1" // ratingName
    );
    const auto Future = Domain.Model();
    Future->StartSynchronousTask();
    if (Future->GetTask().IsError())
    {
        return false;
    }

Value change event handling

    var domain = gs2.Matchmaking.Namespace(
        namespaceName: "namespace-0001"
    ).RatingModel(
        ratingName: "mode1"
    );
    
    // Start event handling
    var callbackId = domain.Subscribe(
        value => {
            // Called when the value changes
            // The "value" is passed the value after the change.
        }
    );

    // Stop event handling
    domain.Unsubscribe(callbackId);

    var domain = gs2.Matchmaking.Namespace(
        namespaceName: "namespace-0001"
    ).RatingModel(
        ratingName: "mode1"
    );
    var future = domain.Model();
    yield return future;
    var item = future.Result;

    const auto Domain = Gs2->Matchmaking->Namespace(
        "namespace-0001" // namespaceName
    )->RatingModel(
        "mode1" // ratingName
    );
    
    // Start event handling
    const auto CallbackId = Domain->Subscribe(
        [](TSharedPtr<Gs2::Matchmaking::Model::FRatingModel> value) {
            // Called when the value changes
            // The "value" is passed the value after the change.
        }
    );

    // Stop event handling
    Domain->Unsubscribe(CallbackId);

Warning

This event is called when the value in the local cache that the SDK has is changed.

Therefore, callbacks will not be invoked if the value is changed in any other way.

listRatingModels

Get list of rating models

Request

	Type	Require	Default	Limitation	Description
namespaceName	string	✓		~ 32 chars	Namespace name

Result

	Type	Description
items	List<EzRatingModel>	List of Rating Model

Implementation Example

    var domain = gs2.Matchmaking.Namespace(
        namespaceName: "namespace-0001"
    );
    var items = await domain.RatingModelsAsync(
    ).ToListAsync();

    var domain = gs2.Matchmaking.Namespace(
        namespaceName: "namespace-0001"
    );
    var it = domain.RatingModels(
    );
    List<EzRatingModel> items = new List<EzRatingModel>();
    while (it.HasNext())
    {
        yield return it.Next();
        if (it.Error != null)
        {
            onError.Invoke(it.Error, null);
            break;
        }
        if (it.Current != null)
        {
            items.Add(it.Current);
        }
        else
        {
            break;
        }
    }

    const auto Domain = Gs2->Matchmaking->Namespace(
        "namespace-0001" // namespaceName
    );
    const auto It = Domain->RatingModels(
    );
    for (auto Item : *It)
    {

    }

Value change event handling

    var domain = gs2.Matchmaking.Namespace(
        namespaceName: "namespace-0001"
    );
    
    // Start event handling
    var callbackId = domain.SubscribeRatingModels(
        () => {
            // Called when an element of the list changes.
        }
    );

    // Stop event handling
    domain.UnsubscribeRatingModels(callbackId);

    var domain = gs2.Matchmaking.Namespace(
        namespaceName: "namespace-0001"
    );
    var it = domain.RatingModels(
    );
    List<EzRatingModel> items = new List<EzRatingModel>();
    while (it.HasNext())
    {
        yield return it.Next();
        if (it.Error != null)
        {
            onError.Invoke(it.Error, null);
            break;
        }
        if (it.Current != null)
        {
            items.Add(it.Current);
        }
        else
        {
            break;
        }
    }

    const auto Domain = Gs2->Matchmaking->Namespace(
        "namespace-0001" // namespaceName
    );
    
    // Start event handling
    const auto CallbackId = Domain->SubscribeRatingModels(
        []() {
            // Called when an element of the list changes.
        }
    );

    // Stop event handling
    Domain->UnsubscribeRatingModels(CallbackId);

Warning

This event is called when the value in the local cache that the SDK has is changed.

Therefore, callbacks will not be invoked if the value is changed in any other way.

getRating

Get Rating

Request

	Type	Require	Limitation	Description
namespaceName	string	✓	~ 32 chars	Namespace name
accessToken	string	✓	~ 128 chars	User Id
ratingName	string	✓	~ 128 chars	Rating Name

Result

	Type	Description
item	EzRating	Rating

Implementation Example

    var domain = gs2.Matchmaking.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    ).Rating(
        ratingName: "rating-0001"
    );
    var item = await domain.ModelAsync();

    var domain = gs2.Matchmaking.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    ).Rating(
        ratingName: "rating-0001"
    );
    var future = domain.Model();
    yield return future;
    var item = future.Result;

    const auto Domain = Gs2->Matchmaking->Namespace(
        "namespace-0001" // namespaceName
    )->Me(
        AccessToken
    )->Rating(
        "rating-0001" // ratingName
    );
    const auto Future = Domain.Model();
    Future->StartSynchronousTask();
    if (Future->GetTask().IsError())
    {
        return false;
    }

Value change event handling

    var domain = gs2.Matchmaking.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    ).Rating(
        ratingName: "rating-0001"
    );
    
    // Start event handling
    var callbackId = domain.Subscribe(
        value => {
            // Called when the value changes
            // The "value" is passed the value after the change.
        }
    );

    // Stop event handling
    domain.Unsubscribe(callbackId);

    var domain = gs2.Matchmaking.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    ).Rating(
        ratingName: "rating-0001"
    );
    var future = domain.Model();
    yield return future;
    var item = future.Result;

    const auto Domain = Gs2->Matchmaking->Namespace(
        "namespace-0001" // namespaceName
    )->Me(
        AccessToken
    )->Rating(
        "rating-0001" // ratingName
    );
    
    // Start event handling
    const auto CallbackId = Domain->Subscribe(
        [](TSharedPtr<Gs2::Matchmaking::Model::FRating> value) {
            // Called when the value changes
            // The "value" is passed the value after the change.
        }
    );

    // Stop event handling
    Domain->Unsubscribe(CallbackId);

Warning

This event is called when the value in the local cache that the SDK has is changed.

Therefore, callbacks will not be invoked if the value is changed in any other way.

listRatings

Get list of ratings

Request

	Type	Require	Default	Limitation	Description
namespaceName	string	✓		~ 32 chars	Namespace name
accessToken	string	✓		~ 128 chars	User Id
pageToken	string			~ 1024 chars	Token specifying the position from which to start acquiring data
limit	int	✓	30	1 ~ 1000	Number of data acquired

Result

	Type	Description
items	List<EzRating>	List of Rating
nextPageToken	string	Page token to retrieve the rest of the listing

Implementation Example

    var domain = gs2.Matchmaking.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    );
    var items = await domain.RatingsAsync(
    ).ToListAsync();

    var domain = gs2.Matchmaking.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    );
    var it = domain.Ratings(
    );
    List<EzRating> items = new List<EzRating>();
    while (it.HasNext())
    {
        yield return it.Next();
        if (it.Error != null)
        {
            onError.Invoke(it.Error, null);
            break;
        }
        if (it.Current != null)
        {
            items.Add(it.Current);
        }
        else
        {
            break;
        }
    }

    const auto Domain = Gs2->Matchmaking->Namespace(
        "namespace-0001" // namespaceName
    )->Me(
        AccessToken
    );
    const auto It = Domain->Ratings(
    );
    for (auto Item : *It)
    {

    }

Value change event handling

    var domain = gs2.Matchmaking.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    );
    
    // Start event handling
    var callbackId = domain.SubscribeRatings(
        () => {
            // Called when an element of the list changes.
        }
    );

    // Stop event handling
    domain.UnsubscribeRatings(callbackId);

    var domain = gs2.Matchmaking.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    );
    var it = domain.Ratings(
    );
    List<EzRating> items = new List<EzRating>();
    while (it.HasNext())
    {
        yield return it.Next();
        if (it.Error != null)
        {
            onError.Invoke(it.Error, null);
            break;
        }
        if (it.Current != null)
        {
            items.Add(it.Current);
        }
        else
        {
            break;
        }
    }

    const auto Domain = Gs2->Matchmaking->Namespace(
        "namespace-0001" // namespaceName
    )->Me(
        AccessToken
    );
    
    // Start event handling
    const auto CallbackId = Domain->SubscribeRatings(
        []() {
            // Called when an element of the list changes.
        }
    );

    // Stop event handling
    Domain->UnsubscribeRatings(CallbackId);

Warning

This event is called when the value in the local cache that the SDK has is changed.

Therefore, callbacks will not be invoked if the value is changed in any other way.

createVote

Prepare a ballot

Request

	Type	Require	Limitation	Description
namespaceName	string	✓	~ 32 chars	Namespace name
ratingName	string	✓	~ 128 chars	Rating Name
gatheringName	string	✓	~ 128 chars	Gathering Name
accessToken	string	✓	~ 128 chars	User Id

Result

	Type	Description
item	EzBallot	Ballot
body	string	Data to be signed
signature	string	Signature

Implementation Example

    var domain = gs2.Matchmaking.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    ).Ballot(
        ratingName: "rating-0001",
        gatheringName: "gathering-0001",
        numberOfPlayer: 4,
        keyId: "key-0001"
    );
    var item = await domain.ModelAsync();

    var domain = gs2.Matchmaking.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    ).Ballot(
        ratingName: "rating-0001",
        gatheringName: "gathering-0001",
        numberOfPlayer: 4,
        keyId: "key-0001"
    );
    var future = domain.Model();
    yield return future;
    var item = future.Result;

    const auto Domain = Gs2->Matchmaking->Namespace(
        "namespace-0001" // namespaceName
    )->Me(
        AccessToken
    )->Ballot(
        "rating-0001", // ratingName
        "gathering-0001", // gatheringName
        4, // numberOfPlayer
        "key-0001" // keyId
    );
    const auto Future = Domain.Model();
    Future->StartSynchronousTask();
    if (Future->GetTask().IsError())
    {
        return false;
    }

Value change event handling

    var domain = gs2.Matchmaking.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    ).Ballot(
        ratingName: "rating-0001",
        gatheringName: "gathering-0001",
        numberOfPlayer: 4,
        keyId: "key-0001"
    );
    
    // Start event handling
    var callbackId = domain.Subscribe(
        value => {
            // Called when the value changes
            // The "value" is passed the value after the change.
        }
    );

    // Stop event handling
    domain.Unsubscribe(callbackId);

    var domain = gs2.Matchmaking.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    ).Ballot(
        ratingName: "rating-0001",
        gatheringName: "gathering-0001",
        numberOfPlayer: 4,
        keyId: "key-0001"
    );
    var future = domain.Model();
    yield return future;
    var item = future.Result;

    const auto Domain = Gs2->Matchmaking->Namespace(
        "namespace-0001" // namespaceName
    )->Me(
        AccessToken
    )->Ballot(
        "rating-0001", // ratingName
        "gathering-0001", // gatheringName
        4, // numberOfPlayer
        "key-0001" // keyId
    );
    
    // Start event handling
    const auto CallbackId = Domain->Subscribe(
        [](TSharedPtr<Gs2::Matchmaking::Model::FBallot> value) {
            // Called when the value changes
            // The "value" is passed the value after the change.
        }
    );

    // Stop event handling
    Domain->Unsubscribe(CallbackId);

Warning

This event is called when the value in the local cache that the SDK has is changed.

Therefore, callbacks will not be invoked if the value is changed in any other way.

vote

Vote on the results of the matchups.

Voting must take place within 5 minutes of the first vote being cast. This means that the results will not be reflected immediately, but approximately 5 minutes after the start of voting or when all players have cast their votes. If all ballots are not collected within 5 minutes, the result will be determined by a majority vote based on the votes cast at that time. If the number of votes for each result is the same, the result will be discarded (the behavior can be changed by script).

If you want to reflect the result immediately, the representative player of the winning side can collect ballots from each player and call voteMultiple to reflect the result immediately.

Request

	Type	Require	Limitation	Description
namespaceName	string	✓	~ 32 chars	Namespace name
ballotBody	string	✓	~ 1024 chars	Data for ballot signature targets
ballotSignature	string	✓	~ 256 chars	Signature
gameResults	List<EzGameResult>		~ 10 items	List of Results
keyId	string	✓	~ 1024 chars	encryption key GRN

Result

	Type	Description
item	EzBallot	Ballot

Implementation Example

    var domain = gs2.Matchmaking.Namespace(
        namespaceName: "namespace-0001"
    );
    var result = await domain.VoteAsync(
        ballotBody: "ballotBody",
        ballotSignature: "ballotSignature",
        keyId: "key-0001",
        gameResults: new Gs2.Unity.Gs2Matchmaking.Model.EzGameResult[] {
            new Gs2.Unity.Gs2Matchmaking.Model.EzGameResult
                {
                Rank = 1,
                UserId = "user-0001",
            },
            new Gs2.Unity.Gs2Matchmaking.Model.EzGameResult
                {
                Rank = 2,
                UserId = "user-0002",
            },
            new Gs2.Unity.Gs2Matchmaking.Model.EzGameResult
                {
                Rank = 2,
                UserId = "user-0003",
            },
            new Gs2.Unity.Gs2Matchmaking.Model.EzGameResult
                {
                Rank = 3,
                UserId = "user-0004",
            },
        }
    );
    var item = await result.ModelAsync();

    var domain = gs2.Matchmaking.Namespace(
        namespaceName: "namespace-0001"
    );
    var future = domain.VoteFuture(
        ballotBody: "ballotBody",
        ballotSignature: "ballotSignature",
        keyId: "key-0001",
        gameResults: new Gs2.Unity.Gs2Matchmaking.Model.EzGameResult[] {
            new Gs2.Unity.Gs2Matchmaking.Model.EzGameResult
                {
                Rank = 1,
                UserId = "user-0001",
            },
            new Gs2.Unity.Gs2Matchmaking.Model.EzGameResult
                {
                Rank = 2,
                UserId = "user-0002",
            },
            new Gs2.Unity.Gs2Matchmaking.Model.EzGameResult
                {
                Rank = 2,
                UserId = "user-0003",
            },
            new Gs2.Unity.Gs2Matchmaking.Model.EzGameResult
                {
                Rank = 3,
                UserId = "user-0004",
            },
        }
    );
    yield return future;
    if (future.Error != null)
    {
        onError.Invoke(future.Error, null);
        yield break;
    }
    var future2 = future.Result.Model();
    yield return future2;
    if (future2.Error != null)
    {
        onError.Invoke(future2.Error, null);
        yield break;
    }
    var result = future2.Result;

    const auto Domain = Gs2->Matchmaking->Namespace(
        "namespace-0001" // namespaceName
    );
    const auto Future = Domain->Vote(
        "ballotBody",
        "ballotSignature",
        "key-0001",
        []
        {
            const auto v = MakeShared<TArray<TSharedPtr<Gs2::Matchmaking::Model::FGameResult>>>();
            v->Add({'rank': 1, 'userId': 'user-0001'});
            v->Add({'rank': 2, 'userId': 'user-0002'});
            v->Add({'rank': 2, 'userId': 'user-0003'});
            v->Add({'rank': 3, 'userId': 'user-0004'});
            return v;
        }() // gameResults
    );
    Future->StartSynchronousTask();
    if (Future->GetTask().IsError())
    {
        return false;
    }

    // obtain changed values / result values
    const auto Future2 = Future->GetTask().Result()->Model();
    Future2->StartSynchronousTask();
    if (!TestFalse(WHAT, Future2->GetTask().IsError())) return false;
    const auto Result = Future2->GetTask().Result();

voteMultiple

Vote on the results of the matchups together.

The side that wins the game collects the ballots of other players and uses them to vote collectively. We say ’the winning side’ because there is an incentive for the losing side to report that they won, but not vice versa. It is possible that the losing side will not hand in their ballots, but even in that case, if there is a majority of ballots, the results can still be passed.

Request

	Type	Require	Limitation	Description
namespaceName	string	✓	~ 32 chars	Namespace name
signedBallots	List<EzSignedBallot>		~ 10 items	List of Ballot with signatures
gameResults	List<EzGameResult>		~ 10 items	List of Results
keyId	string	✓	~ 1024 chars	encryption key GRN

Result

	Type	Description
item	EzBallot	Ballot

Implementation Example

    var domain = gs2.Matchmaking.Namespace(
        namespaceName: "namespace-0001"
    );
    var result = await domain.VoteMultipleAsync(
        keyId: "key-0001",
        signedBallots: new Gs2.Unity.Gs2Matchmaking.Model.EzSignedBallot[] {
            new Gs2.Unity.Gs2Matchmaking.Model.EzSignedBallot
                {
                Body = "aaa",
                Signature = "bbb",
            },
            new Gs2.Unity.Gs2Matchmaking.Model.EzSignedBallot
                {
                Body = "aaa",
                Signature = "bbb",
            },
            new Gs2.Unity.Gs2Matchmaking.Model.EzSignedBallot
                {
                Body = "aaa",
                Signature = "bbb",
            },
            new Gs2.Unity.Gs2Matchmaking.Model.EzSignedBallot
                {
                Body = "aaa",
                Signature = "bbb",
            },
        },
        gameResults: new Gs2.Unity.Gs2Matchmaking.Model.EzGameResult[] {
            new Gs2.Unity.Gs2Matchmaking.Model.EzGameResult
                {
                Rank = 1,
                UserId = "user-0001",
            },
            new Gs2.Unity.Gs2Matchmaking.Model.EzGameResult
                {
                Rank = 2,
                UserId = "user-0002",
            },
            new Gs2.Unity.Gs2Matchmaking.Model.EzGameResult
                {
                Rank = 2,
                UserId = "user-0003",
            },
            new Gs2.Unity.Gs2Matchmaking.Model.EzGameResult
                {
                Rank = 3,
                UserId = "user-0004",
            },
        }
    );
    var item = await result.ModelAsync();

    var domain = gs2.Matchmaking.Namespace(
        namespaceName: "namespace-0001"
    );
    var future = domain.VoteMultipleFuture(
        keyId: "key-0001",
        signedBallots: new Gs2.Unity.Gs2Matchmaking.Model.EzSignedBallot[] {
            new Gs2.Unity.Gs2Matchmaking.Model.EzSignedBallot
                {
                Body = "aaa",
                Signature = "bbb",
            },
            new Gs2.Unity.Gs2Matchmaking.Model.EzSignedBallot
                {
                Body = "aaa",
                Signature = "bbb",
            },
            new Gs2.Unity.Gs2Matchmaking.Model.EzSignedBallot
                {
                Body = "aaa",
                Signature = "bbb",
            },
            new Gs2.Unity.Gs2Matchmaking.Model.EzSignedBallot
                {
                Body = "aaa",
                Signature = "bbb",
            },
        },
        gameResults: new Gs2.Unity.Gs2Matchmaking.Model.EzGameResult[] {
            new Gs2.Unity.Gs2Matchmaking.Model.EzGameResult
                {
                Rank = 1,
                UserId = "user-0001",
            },
            new Gs2.Unity.Gs2Matchmaking.Model.EzGameResult
                {
                Rank = 2,
                UserId = "user-0002",
            },
            new Gs2.Unity.Gs2Matchmaking.Model.EzGameResult
                {
                Rank = 2,
                UserId = "user-0003",
            },
            new Gs2.Unity.Gs2Matchmaking.Model.EzGameResult
                {
                Rank = 3,
                UserId = "user-0004",
            },
        }
    );
    yield return future;
    if (future.Error != null)
    {
        onError.Invoke(future.Error, null);
        yield break;
    }
    var future2 = future.Result.Model();
    yield return future2;
    if (future2.Error != null)
    {
        onError.Invoke(future2.Error, null);
        yield break;
    }
    var result = future2.Result;

    const auto Domain = Gs2->Matchmaking->Namespace(
        "namespace-0001" // namespaceName
    );
    const auto Future = Domain->VoteMultiple(
        "key-0001",
        []
        {
            const auto v = MakeShared<TArray<TSharedPtr<Gs2::Matchmaking::Model::FSignedBallot>>>();
            v->Add({'body': 'aaa', 'signature': 'bbb'});
            v->Add({'body': 'aaa', 'signature': 'bbb'});
            v->Add({'body': 'aaa', 'signature': 'bbb'});
            v->Add({'body': 'aaa', 'signature': 'bbb'});
            return v;
        }(), // signedBallots
        []
        {
            const auto v = MakeShared<TArray<TSharedPtr<Gs2::Matchmaking::Model::FGameResult>>>();
            v->Add({'rank': 1, 'userId': 'user-0001'});
            v->Add({'rank': 2, 'userId': 'user-0002'});
            v->Add({'rank': 2, 'userId': 'user-0003'});
            v->Add({'rank': 3, 'userId': 'user-0004'});
            return v;
        }() // gameResults
    );
    Future->StartSynchronousTask();
    if (Future->GetTask().IsError())
    {
        return false;
    }

    // obtain changed values / result values
    const auto Future2 = Future->GetTask().Result()->Model();
    Future2->StartSynchronousTask();
    if (!TestFalse(WHAT, Future2->GetTask().IsError())) return false;
    const auto Result = Future2->GetTask().Result();

Event Handler

OnJoinNotification

Notification used when a new participant joins the Gathering

Name	Type	Description
namespaceName	string	Namespace name
gatheringName	string	Gathering Name
joinUserId	string	User Id

Implementation Example

    gs2.Matchmaking.OnJoinNotification += notification =>
    {
        var namespaceName = notification.NamespaceName;
        var gatheringName = notification.GatheringName;
        var joinUserId = notification.JoinUserId;
    };

    gs2.Matchmaking.OnJoinNotification += notification =>
    {
        var namespaceName = notification.NamespaceName;
        var gatheringName = notification.GatheringName;
        var joinUserId = notification.JoinUserId;
    };

    Gs2->Matchmaking->OnJoinNotification().AddLambda([](const auto Notification)
    {
        const auto NamespaceName = Notification->NamespaceNameValue;
        const auto GatheringName = Notification->GatheringNameValue;
        const auto JoinUserId = Notification->JoinUserIdValue;
    });

OnLeaveNotification

Notification used when a participant leaves the Gathering

Name	Type	Description
namespaceName	string	Namespace name
gatheringName	string	Gathering Name
leaveUserId	string	User Id

Implementation Example

    gs2.Matchmaking.OnLeaveNotification += notification =>
    {
        var namespaceName = notification.NamespaceName;
        var gatheringName = notification.GatheringName;
        var leaveUserId = notification.LeaveUserId;
    };

    gs2.Matchmaking.OnLeaveNotification += notification =>
    {
        var namespaceName = notification.NamespaceName;
        var gatheringName = notification.GatheringName;
        var leaveUserId = notification.LeaveUserId;
    };

    Gs2->Matchmaking->OnLeaveNotification().AddLambda([](const auto Notification)
    {
        const auto NamespaceName = Notification->NamespaceNameValue;
        const auto GatheringName = Notification->GatheringNameValue;
        const auto LeaveUserId = Notification->LeaveUserIdValue;
    });

OnCompleteNotification

Notification used when matchmaking is established

Name	Type	Description
namespaceName	string	Namespace name
gatheringName	string	Gathering Name

Implementation Example

    gs2.Matchmaking.OnCompleteNotification += notification =>
    {
        var namespaceName = notification.NamespaceName;
        var gatheringName = notification.GatheringName;
    };

    gs2.Matchmaking.OnCompleteNotification += notification =>
    {
        var namespaceName = notification.NamespaceName;
        var gatheringName = notification.GatheringName;
    };

    Gs2->Matchmaking->OnCompleteNotification().AddLambda([](const auto Notification)
    {
        const auto NamespaceName = Notification->NamespaceNameValue;
        const auto GatheringName = Notification->GatheringNameValue;
    });

OnChangeRatingNotification

Notification used when rating values change

Name	Type	Description
namespaceName	string	Namespace name
ratingName	string	Rating Name
userId	string	User Id
rateValue	float

Implementation Example

    gs2.Matchmaking.OnChangeRatingNotification += notification =>
    {
        var namespaceName = notification.NamespaceName;
        var ratingName = notification.RatingName;
        var userId = notification.UserId;
        var rateValue = notification.RateValue;
    };

    gs2.Matchmaking.OnChangeRatingNotification += notification =>
    {
        var namespaceName = notification.NamespaceName;
        var ratingName = notification.RatingName;
        var userId = notification.UserId;
        var rateValue = notification.RateValue;
    };

    Gs2->Matchmaking->OnChangeRatingNotification().AddLambda([](const auto Notification)
    {
        const auto NamespaceName = Notification->NamespaceNameValue;
        const auto RatingName = Notification->RatingNameValue;
        const auto UserId = Notification->UserIdValue;
        const auto RateValue = Notification->RateValueValue;
    });