GS2-Ranking2 SDK for Game Engine API Reference
Model
EzGlobalRankingData
Global Ranking
Represents a ranked entry in the global ranking for a specific season. Contains the user’s score, 0-based index (sorted position), and 1-based rank (which accounts for ties). The rank is calculated as index + 1.
| Type | Condition | Required | Default | Value Limits | Description | |
|---|---|---|---|---|---|---|
| rankingName | string | ✓ | ~ 128 chars | Global Ranking Model name Global Ranking Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). | ||
| season | long | ✓ | 0 ~ 9223372036854775805 | Season The season number corresponding to the GS2-Schedule event repeat count. Increments with each new ranking period. | ||
| userId | string | ✓ | ~ 128 chars | User ID | ||
| index | int | 0 ~ 2147483646 | Index The 0-based unique sorted position of this entry in the ranking. Unlike rank, index is always unique even when scores are tied. Used for index-based reward calculation. | |||
| rank | int | 0 ~ 2147483646 | Rank The 1-based ranking position. Players with the same score share the same rank. Calculated as index + 1. Used for rank-based reward calculation. | |||
| score | long | ✓ | 0 ~ 9223372036854775805 | Score | ||
| metadata | string | ~ 512 chars | Metadata Arbitrary values can be set in the metadata. Since they do not affect GS2’s behavior, they can be used to store information used in the game. | |||
| updatedAt | long | * | Now | Datetime of last update Unix time, milliseconds * Set automatically by the server |
EzGlobalRankingReceivedReward
Global Ranking Reward Received History
It is possible to set rewards for global ranking positions. To set rewards, set the ranking threshold and reward details.
| Type | Condition | Required | Default | Value Limits | Description | |
|---|---|---|---|---|---|---|
| rankingName | string | ✓ | ~ 128 chars | Global Ranking Model name Global Ranking Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). | ||
| season | long | ✓ | 0 ~ 9223372036854775805 | Season The season number corresponding to the GS2-Schedule event repeat count. Increments with each new ranking period. | ||
| userId | string | ✓ | ~ 128 chars | User ID | ||
| receivedAt | long | * | Now | Datetime of creation Unix time, milliseconds * Set automatically by the server |
EzGlobalRankingScore
Global Ranking Score
Stores a user’s submitted score for a global ranking in a specific season. When the sum mode is enabled, multiple submitted scores are accumulated.
| Type | Condition | Required | Default | Value Limits | Description | |
|---|---|---|---|---|---|---|
| rankingName | string | ✓ | ~ 128 chars | Global Ranking Model name Global Ranking Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). | ||
| season | long | ✓ | 0 ~ 9223372036854775805 | Season The season number corresponding to the GS2-Schedule event repeat count. Increments with each new ranking period. | ||
| userId | string | ✓ | ~ 128 chars | User ID | ||
| score | long | ✓ | 0 ~ 9223372036854775805 | Score The score value submitted by the user. Must be within the range defined by the ranking model’s minimumValue and maximumValue settings. | ||
| metadata | string | ~ 512 chars | Metadata Arbitrary values can be set in the metadata. Since they do not affect GS2’s behavior, they can be used to store information used in the game. | |||
| updatedAt | long | * | Now | Datetime of last update Unix time, milliseconds * Set automatically by the server |
EzClusterRankingData
Cluster Ranking
Represents a ranked entry in a cluster ranking for a specific season and cluster. Contains the user’s score, 0-based index, and 1-based rank within the cluster.
| Type | Condition | Required | Default | Value Limits | Description | |
|---|---|---|---|---|---|---|
| rankingName | string | ✓ | ~ 128 chars | Cluster Ranking Model name Cluster Ranking Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). | ||
| clusterName | string | ✓ | ~ 1024 chars | Cluster Name The name of the cluster (guild, gathering, or group) that this season belongs to. | ||
| season | long | ✓ | 0 ~ 9223372036854775805 | Season The season number corresponding to the GS2-Schedule event repeat count. | ||
| userId | string | ✓ | ~ 128 chars | User ID | ||
| index | int | 0 ~ 2147483646 | Index The 0-based unique sorted position within the cluster ranking. Always unique even when scores are tied. | |||
| rank | int | 0 ~ 2147483646 | Rank The 1-based ranking position within the cluster. Players with the same score share the same rank. Calculated as index + 1. | |||
| score | long | ✓ | 0 ~ 9223372036854775805 | Score | ||
| metadata | string | ~ 512 chars | Metadata Arbitrary values can be set in the metadata. Since they do not affect GS2’s behavior, they can be used to store information used in the game. | |||
| updatedAt | long | * | Now | Datetime of last update Unix time, milliseconds * Set automatically by the server |
EzClusterRankingReceivedReward
Cluster Ranking Reward Received History
You can set rewards according to the cluster ranking. To set rewards, set the ranking threshold and reward details.
| Type | Condition | Required | Default | Value Limits | Description | |
|---|---|---|---|---|---|---|
| rankingName | string | ✓ | ~ 128 chars | Cluster Ranking Model name Cluster Ranking Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). | ||
| clusterName | string | ✓ | ~ 1024 chars | Cluster Name The name of the cluster for which the ranking reward was received. | ||
| season | long | ✓ | 0 ~ 9223372036854775805 | Season The season number corresponding to the GS2-Schedule event repeat count. | ||
| userId | string | ✓ | ~ 128 chars | User ID | ||
| receivedAt | long | * | Now | Datetime of creation Unix time, milliseconds * Set automatically by the server |
EzClusterRankingScore
Cluster Ranking Score
Stores a user’s submitted score for a cluster ranking in a specific season and cluster. The user’s cluster membership is verified based on the cluster type setting before the score is accepted.
| Type | Condition | Required | Default | Value Limits | Description | |
|---|---|---|---|---|---|---|
| rankingName | string | ✓ | ~ 128 chars | Cluster Ranking Model name Cluster Ranking Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). | ||
| clusterName | string | ✓ | ~ 1024 chars | Cluster Name The name of the cluster (guild, gathering, or arbitrary group) that this score belongs to. Verified against the cluster type setting to ensure the user is a member. | ||
| season | long | ✓ | 0 ~ 9223372036854775805 | Season The season number corresponding to the GS2-Schedule event repeat count. | ||
| userId | string | ✓ | ~ 128 chars | User ID | ||
| score | long | ✓ | 0 ~ 9223372036854775805 | Score The score value submitted by the user within this cluster. | ||
| metadata | string | ~ 512 chars | Metadata Arbitrary values can be set in the metadata. Since they do not affect GS2’s behavior, they can be used to store information used in the game. | |||
| updatedAt | long | * | Now | Datetime of last update Unix time, milliseconds * Set automatically by the server |
EzSubscribeRankingData
Subscribe Ranking
Represents a ranked entry in a user’s personalized subscribe ranking for a specific season. Contains scores from subscribed users, ranked among the user’s friend list. Each entry includes the scorer’s user ID to identify who achieved the score.
| Type | Condition | Required | Default | Value Limits | Description | |
|---|---|---|---|---|---|---|
| rankingName | string | ✓ | ~ 128 chars | Subscribe Ranking Model name Subscribe Ranking Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). | ||
| season | long | ✓ | 0 ~ 9223372036854775805 | Season The season number corresponding to the GS2-Schedule event repeat count. | ||
| scorerUserId | string | ✓ | ~ 128 chars | Scorer User ID The user ID of the player who achieved this score. In a subscribe ranking, entries come from subscribed users, so this field identifies which friend’s score this entry represents. | ||
| index | int | 0 ~ 2147483646 | Index The 0-based unique sorted position within the subscribe ranking. | |||
| rank | int | 0 ~ 2147483646 | Rank The 1-based ranking position within the subscribe ranking. Calculated as index + 1. | |||
| score | long | ✓ | 0 ~ 9223372036854775805 | Score | ||
| metadata | string | ~ 512 chars | Metadata Arbitrary values can be set in the metadata. Since they do not affect GS2’s behavior, they can be used to store information used in the game. | |||
| updatedAt | long | * | Now | Datetime of last update Unix time, milliseconds * Set automatically by the server |
EzSubscribeRankingScore
Subscribe Ranking Score
Stores a user’s submitted score for a subscribe ranking in a specific season. This score is visible to users who have subscribed to this user, forming their personalized friend ranking.
| Type | Condition | Required | Default | Value Limits | Description | |
|---|---|---|---|---|---|---|
| rankingName | string | ✓ | ~ 128 chars | Subscribe Ranking Model name Subscribe Ranking Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). | ||
| season | long | ✓ | 0 ~ 9223372036854775805 | Season The season number corresponding to the GS2-Schedule event repeat count. | ||
| userId | string | ✓ | ~ 128 chars | User ID | ||
| score | long | ✓ | 0 ~ 9223372036854775805 | Score | ||
| metadata | string | ~ 512 chars | Metadata Arbitrary values can be set in the metadata. Since they do not affect GS2’s behavior, they can be used to store information used in the game. | |||
| updatedAt | long | * | Now | Datetime of last update Unix time, milliseconds * Set automatically by the server |
EzSubscribeUser
Subscribed User Information
Represents a subscription relationship between two users for the subscribe ranking.
| Type | Condition | Required | Default | Value Limits | Description | |
|---|---|---|---|---|---|---|
| rankingName | string | ✓ | ~ 128 chars | Subscribe Ranking Model name Subscribe Ranking Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). | ||
| userId | string | ✓ | ~ 128 chars | User ID | ||
| targetUserId | string | ✓ | ~ 128 chars | Subscribe Target User ID The user ID of the player being subscribed to. This player’s scores will be included in the subscriber’s personalized ranking. |
EzGlobalRankingModel
Global Ranking Model
The global ranking is a model that allows you to create a ranking that targets all players. You can display the top 1000 rankings.
By associating it with the repeat event of GS2-Schedule, you can reset the ranking according to the number of repetitions.
| Type | Condition | Required | Default | Value Limits | Description | |
|---|---|---|---|---|---|---|
| globalRankingModelId | string | * | ~ 1024 chars | Global Ranking GRN * Set automatically by the server | ||
| name | string | ✓ | ~ 128 chars | Global Ranking Model name Global Ranking Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). | ||
| metadata | string | ~ 1024 chars | Metadata Arbitrary values can be set in the metadata. Since they do not affect GS2’s behavior, they can be used to store information used in the game. | |||
| rankingRewards | List<EzRankingReward> | {entryPeriodEventId} != null | * | [] | 0 ~ 100 items | Ranking Rewards List of rewards granted based on ranking position at the end of each season. Only available when an entry period event is configured. Each reward defines a rank threshold and the acquire actions to execute. |
| entryPeriodEventId | string | ~ 1024 chars | Entry Period Event GRN GS2-Schedule event GRN that defines the period during which scores can be submitted. When linked to a repeating event, the ranking resets with each repeat cycle, enabling seasonal rankings. | |||
| accessPeriodEventId | string | ~ 1024 chars | Access Period Event GRN GS2-Schedule event GRN that defines the period during which ranking results can be viewed and rewards can be claimed. Typically set to the interval between score entry periods. |
EzClusterRankingModel
Cluster Ranking Model
The cluster ranking model enables rankings for players within guilds or gatherings. You can display the top 1000 rankings.
By associating it with the repeat event of GS2-Schedule, you can reset the ranking according to the number of repetitions.
| Type | Condition | Required | Default | Value Limits | Description | |||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| clusterRankingModelId | string | * | ~ 1024 chars | Cluster Ranking GRN * Set automatically by the server | ||||||||||
| name | string | ✓ | ~ 128 chars | Cluster Ranking Model name Cluster Ranking Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). | ||||||||||
| metadata | string | ~ 1024 chars | Metadata Arbitrary values can be set in the metadata. Since they do not affect GS2’s behavior, they can be used to store information used in the game. | |||||||||||
| clusterType | String Enum enum { “Raw”, “Gs2Guild::Guild”, “Gs2Matchmaking::SeasonGathering” } | ✓ | Cluster Type Defines the type of group (cluster) used for ranking segmentation. “Raw” allows arbitrary cluster names without membership verification, “Gs2Guild::Guild” verifies the user belongs to a GS2-Guild guild, and “Gs2Matchmaking::SeasonGathering” verifies membership in a GS2-Matchmaking season gathering.
| |||||||||||
| rankingRewards | List<EzRankingReward> | {entryPeriodEventId} != null | * | [] | 0 ~ 100 items | Ranking Rewards List of rewards granted based on ranking position at the end of each season. Only available when an entry period event is configured. | ||||||||
| entryPeriodEventId | string | ~ 1024 chars | Entry Period Event GRN GS2-Schedule event GRN that defines the period during which scores can be submitted. When linked to a repeating event, the ranking resets with each repeat cycle, enabling seasonal rankings. | |||||||||||
| accessPeriodEventId | string | ~ 1024 chars | Access Period Event GRN GS2-Schedule event GRN that defines the period during which ranking results can be viewed and rewards can be claimed. |
EzSubscribeRankingModel
Subscribe Ranking Model
A model that aggregates scores of other players that the user has subscribed to and creates a ranking.
| Type | Condition | Required | Default | Value Limits | Description | |
|---|---|---|---|---|---|---|
| subscribeRankingModelId | string | * | ~ 1024 chars | Subscribe Ranking GRN * Set automatically by the server | ||
| name | string | ✓ | ~ 128 chars | Subscribe Ranking Model name Subscribe Ranking Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). | ||
| metadata | string | ~ 1024 chars | Metadata Arbitrary values can be set in the metadata. Since they do not affect GS2’s behavior, they can be used to store information used in the game. | |||
| entryPeriodEventId | string | ~ 1024 chars | Entry Period Event GRN GS2-Schedule event GRN that defines the period during which scores can be submitted. When linked to a repeating event, the ranking resets with each repeat cycle, enabling seasonal rankings. | |||
| accessPeriodEventId | string | ~ 1024 chars | Access Period Event GRN GS2-Schedule event GRN that defines the period during which ranking results can be viewed. |
EzRankingReward
Ranking Reward
Set the rewards that can be received during the reference period when the score registration period is set in the ranking. If the repeat setting is enabled, the most recently ended period ranking will be the target for receiving rewards.
| Type | Condition | Required | Default | Value Limits | Description | |
|---|---|---|---|---|---|---|
| thresholdRank | int | ✓ | 1 ~ 1001 | Rank Threshold The rank threshold for this reward tier. Players whose rank (or index, depending on rewardCalculationIndex setting) is at or above this threshold receive this reward. Set to 1001 to define rewards for unranked players (those outside the top 1000). | ||
| metadata | string | ~ 1024 chars | Metadata Arbitrary values can be set in the metadata. Since they do not affect GS2’s behavior, they can be used to store information used in the game. | |||
| acquireActions | List<EzAcquireAction> | [] | 0 ~ 100 items | Acquire Actions List of acquire actions executed when the player claims this ranking reward. These define the actual items, currency, or other resources granted as the reward for achieving this rank threshold. |
EzAcquireAction
Acquire Action
EzConfig
Configuration
Set values to be applied to transaction variables
| Type | Condition | Required | Default | Value Limits | Description | |
|---|---|---|---|---|---|---|
| key | string | ✓ | ~ 64 chars | Name | ||
| value | string | ~ 51200 chars | Value |
EzVerifyActionResult
Verify Action execution result
EzConsumeActionResult
Consume Action execution result
EzAcquireActionResult
Acquire Action execution result
EzTransactionResult
Transaction execution results
Result of a transaction executed using the server-side automatic transaction execution feature
| Type | Condition | Required | Default | Value Limits | Description | |
|---|---|---|---|---|---|---|
| transactionId | string | ✓ | 36 ~ 36 chars | Transaction ID | ||
| verifyResults | List<EzVerifyActionResult> | 0 ~ 10 items | List of verify action execution results | |||
| consumeResults | List<EzConsumeActionResult> | [] | 0 ~ 10 items | List of Consume Action execution results | ||
| acquireResults | List<EzAcquireActionResult> | [] | 0 ~ 100 items | List of Acquire Action execution results |
Methods
getGlobalRankingRank
Get the player’s own rank in a global ranking
Retrieves the player’s own ranking entry, including their rank position and score. Use this to display the player’s position on the leaderboard — for example, showing “Your rank: #42 (15,000 pts)” at the top of the ranking screen, or “You are ranked #42 out of 10,000 players”.
Request
| Type | Condition | Required | Default | Value Limits | Description | |
|---|---|---|---|---|---|---|
| namespaceName | string | ✓ | ~ 128 chars | Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). | ||
| rankingName | string | ✓ | ~ 128 chars | Global Ranking Model name Global Ranking Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). | ||
| season | long | 0 ~ 9223372036854775805 | Season | |||
| gameSession | GameSession | ✓ | GameSession |
Result
| Type | Description | |
|---|---|---|
| item | EzGlobalRankingData | Global Ranking |
Implementation Example
var domain = gs2.Ranking2.Namespace(
namespaceName: "namespace-0001"
).GlobalRankingModel(
rankingName: "ranking-0001"
).GlobalRankingSeason(
season: null,
gameSession: GameSession
);
var result = await domain.GetGlobalRankingRankAsync(
);
var item = await result.ModelAsync(); var domain = gs2.Ranking2.Namespace(
namespaceName: "namespace-0001"
).GlobalRankingModel(
rankingName: "ranking-0001"
).GlobalRankingSeason(
season: null,
userId: "user-0001"
);
var future = domain.GetGlobalRankingRankFuture(
);
yield return future;
if (future.Error != null)
{
onError.Invoke(future.Error, null);
yield break;
}
var future2 = future.Result.ModelFuture();
yield return future2;
if (future2.Error != null)
{
onError.Invoke(future2.Error, null);
yield break;
}
var result = future2.Result; const auto Domain = Gs2->Ranking2->Namespace(
"namespace-0001" // namespaceName
)->GlobalRankingModel(
"ranking-0001" // rankingName
)->GlobalRankingSeason(
nullptr, // season
"user-0001" // userId
);
const auto Future = Domain->GetGlobalRankingRank(
);
Future->StartSynchronousTask();
if (Future->GetTask().IsError())
{
return false;
}
// obtain changed values / result values
const auto Future2 = Future->GetTask().Result()->Model();
Future2->StartSynchronousTask();
if (Future2->GetTask().IsError())
{
return Future2->GetTask().Error();
}
const auto Result = Future2->GetTask().Result();listGlobalRankings
Get the global ranking leaderboard
Retrieves the global ranking leaderboard entries, showing players ranked by their scores. Each entry includes the player’s user ID, score, rank position, and any attached metadata. Use this to display the leaderboard — for example, showing “1st: Alice (25,000 pts), 2nd: Bob (22,500 pts), 3rd: Charlie (20,000 pts)” on a ranking screen.
Request
| Type | Condition | Required | Default | Value Limits | Description | |
|---|---|---|---|---|---|---|
| namespaceName | string | ✓ | ~ 128 chars | Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). | ||
| rankingName | string | ✓ | ~ 128 chars | Global Ranking Model name Global Ranking Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). | ||
| season | long | 0 ~ 9223372036854775805 | Season | |||
| gameSession | GameSession | ✓ | GameSession | |||
| pageToken | string | ~ 1024 chars | Token specifying the position from which to start acquiring data | |||
| limit | int | 30 | 1 ~ 1000 | Number of data items to retrieve |
Result
| Type | Description | |
|---|---|---|
| items | List<EzGlobalRankingData> | List of Global Rankings |
| nextPageToken | string | Page token to retrieve the rest of the listing |
Implementation Example
var domain = gs2.Ranking2.Namespace(
namespaceName: "namespace-0001"
).GlobalRankingModel(
rankingName: "ranking-0001"
).GlobalRankingSeason(
season: null,
userId: "user-0001"
);
var items = await domain.GlobalRankingsAsync(
).ToListAsync(); var domain = gs2.Ranking2.Namespace(
namespaceName: "namespace-0001"
).GlobalRankingModel(
rankingName: "ranking-0001"
).GlobalRankingSeason(
season: null,
userId: "user-0001"
);
var it = domain.GlobalRankings(
);
List<EzGlobalRankingData> items = new List<EzGlobalRankingData>();
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->Ranking2->Namespace(
"namespace-0001" // namespaceName
)->GlobalRankingModel(
"ranking-0001" // rankingName
)->GlobalRankingSeason(
nullptr, // season
"user-0001" // userId
);
const auto It = Domain->GlobalRankings(
);
TArray<Gs2::UE5::Ranking2::Model::FEzGlobalRankingDataPtr> Result;
for (auto Item : *It)
{
if (Item.IsError())
{
return false;
}
Result.Add(Item.Current());
}getGlobalRankingModel
Get a specific global ranking definition by name
Retrieves a single global ranking model by specifying its name. The returned information includes the score range, sort order, reward settings, and season/entry period configurations. Use this to display the rules of a specific ranking — for example, showing “High Score Ranking — Resets monthly, Top 100 get rewards, Higher score = better rank” on a ranking detail screen.
Request
| Type | Condition | Required | Default | Value Limits | Description | |
|---|---|---|---|---|---|---|
| namespaceName | string | ✓ | ~ 128 chars | Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). | ||
| rankingName | string | ✓ | ~ 128 chars | Global Ranking Model name Global Ranking Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). |
Result
| Type | Description | |
|---|---|---|
| item | EzGlobalRankingModel | Global Ranking Model |
Implementation Example
var domain = gs2.Ranking2.Namespace(
namespaceName: "namespace-0001"
).GlobalRankingModel(
rankingName: "ranking-0001"
);
var item = await domain.ModelAsync(); var domain = gs2.Ranking2.Namespace(
namespaceName: "namespace-0001"
).GlobalRankingModel(
rankingName: "ranking-0001"
);
var future = domain.ModelFuture();
yield return future;
var item = future.Result; const auto Domain = Gs2->Ranking2->Namespace(
"namespace-0001" // namespaceName
)->GlobalRankingModel(
"ranking-0001" // rankingName
);
const auto Future = Domain->Model();
Future->StartSynchronousTask();
if (Future->GetTask().IsError())
{
return false;
}Value change event handling
var domain = gs2.Ranking2.Namespace(
namespaceName: "namespace-0001"
).GlobalRankingModel(
rankingName: "ranking-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.Ranking2.Namespace(
namespaceName: "namespace-0001"
).GlobalRankingModel(
rankingName: "ranking-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); const auto Domain = Gs2->Ranking2->Namespace(
"namespace-0001" // namespaceName
)->GlobalRankingModel(
"ranking-0001" // rankingName
);
// Start event handling
const auto CallbackId = Domain->Subscribe(
[](TSharedPtr<Gs2::Ranking2::Model::FGlobalRankingModel> 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 triggered when the value stored in the SDK’s local cache changes.
The local cache is updated only when executing the SDK’s API, or by executing stamp sheets via GS2-Distributor with GS2-Gateway notification enabled, or by executing a GS2-JobQueue with GS2-Gateway notification enabled.
Therefore, callbacks will not be invoked if the value is changed in any other way.
listGlobalRankingModels
Get a list of global ranking definitions
Retrieves all global ranking models registered in this namespace. A global ranking is a leaderboard where all players in the game compete against each other — for example, “World High Score”, “Arena Rating”, or “Total Damage Ranking”. Each model defines the ranking rules: score range, sort order (ascending or descending), season schedule, and ranking rewards. Use this to see what global rankings exist — for example, to display a “Leaderboards” menu showing “High Score Ranking”, “Speed Clear Ranking”, “PvP Rating” as options.
Request
| Type | Condition | Required | Default | Value Limits | Description | |
|---|---|---|---|---|---|---|
| namespaceName | string | ✓ | ~ 128 chars | Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). |
Result
| Type | Description | |
|---|---|---|
| items | List<EzGlobalRankingModel> | List of Global Ranking Models |
Implementation Example
var domain = gs2.Ranking2.Namespace(
namespaceName: null
);
var items = await domain.GlobalRankingModelsAsync(
).ToListAsync(); var domain = gs2.Ranking2.Namespace(
namespaceName: null
);
var it = domain.GlobalRankingModels(
);
List<EzGlobalRankingModel> items = new List<EzGlobalRankingModel>();
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->Ranking2->Namespace(
nullptr // namespaceName
);
const auto It = Domain->GlobalRankingModels(
);
TArray<Gs2::UE5::Ranking2::Model::FEzGlobalRankingModelPtr> Result;
for (auto Item : *It)
{
if (Item.IsError())
{
return false;
}
Result.Add(Item.Current());
}Value change event handling
var domain = gs2.Ranking2.Namespace(
namespaceName: null
);
// Start event handling
var callbackId = domain.SubscribeGlobalRankingModels(
() => {
// Called when an element of the list changes.
}
);
// Stop event handling
domain.UnsubscribeGlobalRankingModels(callbackId); var domain = gs2.Ranking2.Namespace(
namespaceName: null
);
// Start event handling
var callbackId = domain.SubscribeGlobalRankingModels(
() => {
// Called when an element of the list changes.
}
);
// Stop event handling
domain.UnsubscribeGlobalRankingModels(callbackId); const auto Domain = Gs2->Ranking2->Namespace(
nullptr // namespaceName
);
// Start event handling
const auto CallbackId = Domain->SubscribeGlobalRankingModels(
[]() {
// Called when an element of the list changes.
}
);
// Stop event handling
Domain->UnsubscribeGlobalRankingModels(CallbackId);Warning
This event is triggered when the value stored in the SDK’s local cache changes.
The local cache is updated only when executing the SDK’s API, or by executing stamp sheets via GS2-Distributor with GS2-Gateway notification enabled, or by executing a GS2-JobQueue with GS2-Gateway notification enabled.
Therefore, callbacks will not be invoked if the value is changed in any other way.
getGlobalRankingReceivedReward
Check if the player has claimed a specific global ranking reward
Retrieves the reward claim record for a specific global ranking and season. Use this to check if the player has already claimed the reward for a specific ranking season — for example, showing a “Claim Reward” button if unclaimed, or “Already Claimed” if already received.
Request
| Type | Condition | Required | Default | Value Limits | Description | |
|---|---|---|---|---|---|---|
| namespaceName | string | ✓ | ~ 128 chars | Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). | ||
| rankingName | string | ✓ | ~ 128 chars | Global Ranking Model name Global Ranking Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). | ||
| season | long | 0 ~ 9223372036854775805 | Season | |||
| gameSession | GameSession | ✓ | GameSession |
Result
| Type | Description | |
|---|---|---|
| item | EzGlobalRankingReceivedReward | Global Ranking Reward Received History |
Implementation Example
var domain = gs2.Ranking2.Namespace(
namespaceName: "namespace-0001"
).GlobalRankingModel(
rankingName: "ranking-0001"
).GlobalRankingSeason(
season: 0,
userId: "user-0001"
).GlobalRankingReceivedReward(
);
var item = await domain.ModelAsync(); var domain = gs2.Ranking2.Namespace(
namespaceName: "namespace-0001"
).GlobalRankingModel(
rankingName: "ranking-0001"
).GlobalRankingSeason(
season: 0,
userId: "user-0001"
).GlobalRankingReceivedReward(
);
var future = domain.ModelFuture();
yield return future;
var item = future.Result; const auto Domain = Gs2->Ranking2->Namespace(
"namespace-0001" // namespaceName
)->GlobalRankingModel(
"ranking-0001" // rankingName
)->GlobalRankingSeason(
0, // season
"user-0001" // userId
)->GlobalRankingReceivedReward(
);
const auto Future = Domain->Model();
Future->StartSynchronousTask();
if (Future->GetTask().IsError())
{
return false;
}Value change event handling
var domain = gs2.Ranking2.Namespace(
namespaceName: "namespace-0001"
).GlobalRankingModel(
rankingName: "ranking-0001"
).GlobalRankingSeason(
season: 0,
userId: "user-0001"
).GlobalRankingReceivedReward(
);
// 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.Ranking2.Namespace(
namespaceName: "namespace-0001"
).GlobalRankingModel(
rankingName: "ranking-0001"
).GlobalRankingSeason(
season: 0,
userId: "user-0001"
).GlobalRankingReceivedReward(
);
// 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); const auto Domain = Gs2->Ranking2->Namespace(
"namespace-0001" // namespaceName
)->GlobalRankingModel(
"ranking-0001" // rankingName
)->GlobalRankingSeason(
0, // season
"user-0001" // userId
)->GlobalRankingReceivedReward(
);
// Start event handling
const auto CallbackId = Domain->Subscribe(
[](TSharedPtr<Gs2::Ranking2::Model::FGlobalRankingReceivedReward> 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 triggered when the value stored in the SDK’s local cache changes.
The local cache is updated only when executing the SDK’s API, or by executing stamp sheets via GS2-Distributor with GS2-Gateway notification enabled, or by executing a GS2-JobQueue with GS2-Gateway notification enabled.
Therefore, callbacks will not be invoked if the value is changed in any other way.
listGlobalRankingReceivedRewards
Get a list of the player’s global ranking reward claim history
Retrieves the player’s history of claimed ranking rewards from global rankings. Each entry shows which ranking and season the reward was claimed for, allowing you to check which rewards have already been collected. Use this to display reward claim status — for example, showing “High Score Ranking Season 1: Claimed, Season 2: Claimed, Season 3: Not yet claimed” on a ranking rewards screen.
Request
| Type | Condition | Required | Default | Value Limits | Description | |
|---|---|---|---|---|---|---|
| namespaceName | string | ✓ | ~ 128 chars | Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). | ||
| rankingName | string | ~ 128 chars | Global Ranking Model name Global Ranking Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). | |||
| season | long | 0 ~ 9223372036854775805 | Season | |||
| gameSession | GameSession | ✓ | GameSession | |||
| pageToken | string | ~ 1024 chars | Token specifying the position from which to start acquiring data | |||
| limit | int | 30 | 1 ~ 1000 | Number of data items to retrieve |
Result
| Type | Description | |
|---|---|---|
| items | List<EzGlobalRankingReceivedReward> | List of Global Ranking Rewards Received |
| nextPageToken | string | Page token to retrieve the rest of the listing |
Implementation Example
var domain = gs2.Ranking2.Namespace(
namespaceName: "namespace-0001"
).GlobalRankingModel(
rankingName: "ranking-0001"
).GlobalRankingSeason(
season: 0,
userId: "user-0001"
);
var items = await domain.GlobalRankingReceivedRewardsAsync(
).ToListAsync(); var domain = gs2.Ranking2.Namespace(
namespaceName: "namespace-0001"
).GlobalRankingModel(
rankingName: "ranking-0001"
).GlobalRankingSeason(
season: 0,
userId: "user-0001"
);
var it = domain.GlobalRankingReceivedRewards(
);
List<EzGlobalRankingReceivedReward> items = new List<EzGlobalRankingReceivedReward>();
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->Ranking2->Namespace(
"namespace-0001" // namespaceName
)->GlobalRankingModel(
"ranking-0001" // rankingName
)->GlobalRankingSeason(
0, // season
"user-0001" // userId
);
const auto It = Domain->GlobalRankingReceivedRewards(
);
TArray<Gs2::UE5::Ranking2::Model::FEzGlobalRankingReceivedRewardPtr> Result;
for (auto Item : *It)
{
if (Item.IsError())
{
return false;
}
Result.Add(Item.Current());
}Value change event handling
var domain = gs2.Ranking2.Namespace(
namespaceName: "namespace-0001"
).GlobalRankingModel(
rankingName: "ranking-0001"
).GlobalRankingSeason(
season: 0,
userId: "user-0001"
);
// Start event handling
var callbackId = domain.SubscribeGlobalRankingReceivedRewards(
() => {
// Called when an element of the list changes.
}
);
// Stop event handling
domain.UnsubscribeGlobalRankingReceivedRewards(callbackId); var domain = gs2.Ranking2.Namespace(
namespaceName: "namespace-0001"
).GlobalRankingModel(
rankingName: "ranking-0001"
).GlobalRankingSeason(
season: 0,
userId: "user-0001"
);
// Start event handling
var callbackId = domain.SubscribeGlobalRankingReceivedRewards(
() => {
// Called when an element of the list changes.
}
);
// Stop event handling
domain.UnsubscribeGlobalRankingReceivedRewards(callbackId); const auto Domain = Gs2->Ranking2->Namespace(
"namespace-0001" // namespaceName
)->GlobalRankingModel(
"ranking-0001" // rankingName
)->GlobalRankingSeason(
0, // season
"user-0001" // userId
);
// Start event handling
const auto CallbackId = Domain->SubscribeGlobalRankingReceivedRewards(
[]() {
// Called when an element of the list changes.
}
);
// Stop event handling
Domain->UnsubscribeGlobalRankingReceivedRewards(CallbackId);Warning
This event is triggered when the value stored in the SDK’s local cache changes.
The local cache is updated only when executing the SDK’s API, or by executing stamp sheets via GS2-Distributor with GS2-Gateway notification enabled, or by executing a GS2-JobQueue with GS2-Gateway notification enabled.
Therefore, callbacks will not be invoked if the value is changed in any other way.
receiveGlobalRankingReward
Claim the global ranking reward
Claims the ranking reward based on the player’s final rank in the specified global ranking and season. The reward is determined by the player’s rank position and the ranking model’s reward settings — for example, top 10 players might receive a special item, while top 100 receive gems. The reward items are automatically granted to the player. Use this when the player taps “Claim Reward” on the ranking results screen after a season ends.
Request
| Type | Condition | Required | Default | Value Limits | Description | |
|---|---|---|---|---|---|---|
| namespaceName | string | ✓ | ~ 128 chars | Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). | ||
| rankingName | string | ✓ | ~ 128 chars | Global Ranking Model name Global Ranking Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). | ||
| season | long | 0 ~ 9223372036854775805 | Season | |||
| gameSession | GameSession | ✓ | GameSession | |||
| config | List<EzConfig> | [] | 0 ~ 32 items | Set values to be applied to transaction variables |
Result
| Type | Description | |
|---|---|---|
| item | EzGlobalRankingModel | Global Ranking Model |
| acquireActions | List<EzAcquireAction> | List of Acquire Actions to be performed when rewards are received |
| transactionId | string | Issued transaction ID |
| stampSheet | string | Stamp sheet used to execute the exchange process |
| stampSheetEncryptionKeyId | string | Cryptographic key GRN used for stamp sheet signature calculations |
| autoRunStampSheet | bool | Whether automatic transaction execution is enabled |
| atomicCommit | bool | Whether to commit the transaction atomically |
| transaction | string | Issued transaction |
| transactionResult | EzTransactionResult | Transaction execution result |
Implementation Example
var domain = gs2.Ranking2.Namespace(
namespaceName: "namespace-0001"
).GlobalRankingModel(
rankingName: "ranking-0001"
).GlobalRankingSeason(
season: 0,
userId: "user-0001"
).GlobalRankingReceivedReward(
);
var result = await domain.ReceiveGlobalRankingRewardAsync(
config: null
);
// In New Experience, stamp sheets are automatically executed at the SDK level.
// If an error occurs, a TransactionException is thrown.
// you can retry with TransactionException::Retry(). var domain = gs2.Ranking2.Namespace(
namespaceName: "namespace-0001"
).GlobalRankingModel(
rankingName: "ranking-0001"
).GlobalRankingSeason(
season: 0,
userId: "user-0001"
).GlobalRankingReceivedReward(
);
var future = domain.ReceiveGlobalRankingRewardFuture(
config: null
);
yield return future;
if (future.Error != null)
{
onError.Invoke(future.Error, null);
yield break;
}
// In New Experience, stamp sheets are automatically executed at the SDK level.
// If an error occurs, a TransactionException is thrown.
// you can retry with TransactionException::Retry(). const auto Domain = Gs2->Ranking2->Namespace(
"namespace-0001" // namespaceName
)->GlobalRankingModel(
"ranking-0001" // rankingName
)->GlobalRankingSeason(
0, // season
"user-0001" // userId
)->GlobalRankingReceivedReward(
);
const auto Future = Domain->ReceiveGlobalRankingReward(
// config
);
Future->StartSynchronousTask();
if (Future->GetTask().IsError())
{
return false;
}getGlobalRankingScore
Get the player’s submitted score for a specific global ranking
Retrieves the player’s score for a specific global ranking and season. Use this to display the player’s current score on a specific leaderboard — for example, showing “Your score: 15,000 pts (Season 3)” on the ranking detail screen.
Request
| Type | Condition | Required | Default | Value Limits | Description | |
|---|---|---|---|---|---|---|
| namespaceName | string | ✓ | ~ 128 chars | Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). | ||
| rankingName | string | ✓ | ~ 128 chars | Global Ranking Model name Global Ranking Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). | ||
| season | long | 0 ~ 9223372036854775805 | Season | |||
| gameSession | GameSession | ✓ | GameSession |
Result
| Type | Description | |
|---|---|---|
| item | EzGlobalRankingScore | Global Ranking Score |
Implementation Example
var domain = gs2.Ranking2.Namespace(
namespaceName: "namespace-0001"
).GlobalRankingModel(
rankingName: "ranking-0001"
).GlobalRankingSeason(
season: 0,
userId: "user-0001"
).GlobalRankingScore(
);
var item = await domain.ModelAsync(); var domain = gs2.Ranking2.Namespace(
namespaceName: "namespace-0001"
).GlobalRankingModel(
rankingName: "ranking-0001"
).GlobalRankingSeason(
season: 0,
userId: "user-0001"
).GlobalRankingScore(
);
var future = domain.ModelFuture();
yield return future;
var item = future.Result; const auto Domain = Gs2->Ranking2->Namespace(
"namespace-0001" // namespaceName
)->GlobalRankingModel(
"ranking-0001" // rankingName
)->GlobalRankingSeason(
0, // season
"user-0001" // userId
)->GlobalRankingScore(
);
const auto Future = Domain->Model();
Future->StartSynchronousTask();
if (Future->GetTask().IsError())
{
return false;
}Value change event handling
var domain = gs2.Ranking2.Namespace(
namespaceName: "namespace-0001"
).GlobalRankingModel(
rankingName: "ranking-0001"
).GlobalRankingSeason(
season: 0,
userId: "user-0001"
).GlobalRankingScore(
);
// 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.Ranking2.Namespace(
namespaceName: "namespace-0001"
).GlobalRankingModel(
rankingName: "ranking-0001"
).GlobalRankingSeason(
season: 0,
userId: "user-0001"
).GlobalRankingScore(
);
// 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); const auto Domain = Gs2->Ranking2->Namespace(
"namespace-0001" // namespaceName
)->GlobalRankingModel(
"ranking-0001" // rankingName
)->GlobalRankingSeason(
0, // season
"user-0001" // userId
)->GlobalRankingScore(
);
// Start event handling
const auto CallbackId = Domain->Subscribe(
[](TSharedPtr<Gs2::Ranking2::Model::FGlobalRankingScore> 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 triggered when the value stored in the SDK’s local cache changes.
The local cache is updated only when executing the SDK’s API, or by executing stamp sheets via GS2-Distributor with GS2-Gateway notification enabled, or by executing a GS2-JobQueue with GS2-Gateway notification enabled.
Therefore, callbacks will not be invoked if the value is changed in any other way.
listGlobalRankingScores
Get a list of the player’s submitted scores for global rankings
Retrieves all scores the player has submitted to global rankings. Each score entry shows which ranking it was submitted to and the score value. Use this to display the player’s own scores — for example, showing “Your High Scores: Stage Clear: 15,000 pts, Arena: 2,400 pts” on a profile or ranking overview screen.
Request
| Type | Condition | Required | Default | Value Limits | Description | |
|---|---|---|---|---|---|---|
| namespaceName | string | ✓ | ~ 128 chars | Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). | ||
| rankingName | string | ~ 128 chars | Global Ranking Model name Global Ranking Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). | |||
| gameSession | GameSession | ✓ | GameSession | |||
| pageToken | string | ~ 1024 chars | Token specifying the position from which to start acquiring data | |||
| limit | int | 30 | 1 ~ 1000 | Number of data items to retrieve |
Result
| Type | Description | |
|---|---|---|
| items | List<EzGlobalRankingScore> | List of Global Ranking Scores |
| nextPageToken | string | Page token to retrieve the rest of the listing |
Implementation Example
var domain = gs2.Ranking2.Namespace(
namespaceName: "namespace-0001"
).GlobalRankingModel(
rankingName: "ranking-0001"
).GlobalRankingSeason(
season: 0,
userId: "user-0001"
);
var items = await domain.GlobalRankingScoresAsync(
).ToListAsync(); var domain = gs2.Ranking2.Namespace(
namespaceName: "namespace-0001"
).GlobalRankingModel(
rankingName: "ranking-0001"
).GlobalRankingSeason(
season: 0,
userId: "user-0001"
);
var it = domain.GlobalRankingScores(
);
List<EzGlobalRankingScore> items = new List<EzGlobalRankingScore>();
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->Ranking2->Namespace(
"namespace-0001" // namespaceName
)->GlobalRankingModel(
"ranking-0001" // rankingName
)->GlobalRankingSeason(
0, // season
"user-0001" // userId
);
const auto It = Domain->GlobalRankingScores(
);
TArray<Gs2::UE5::Ranking2::Model::FEzGlobalRankingScorePtr> Result;
for (auto Item : *It)
{
if (Item.IsError())
{
return false;
}
Result.Add(Item.Current());
}Value change event handling
var domain = gs2.Ranking2.Namespace(
namespaceName: "namespace-0001"
).GlobalRankingModel(
rankingName: "ranking-0001"
).GlobalRankingSeason(
season: 0,
userId: "user-0001"
);
// Start event handling
var callbackId = domain.SubscribeGlobalRankingScores(
() => {
// Called when an element of the list changes.
}
);
// Stop event handling
domain.UnsubscribeGlobalRankingScores(callbackId); var domain = gs2.Ranking2.Namespace(
namespaceName: "namespace-0001"
).GlobalRankingModel(
rankingName: "ranking-0001"
).GlobalRankingSeason(
season: 0,
userId: "user-0001"
);
// Start event handling
var callbackId = domain.SubscribeGlobalRankingScores(
() => {
// Called when an element of the list changes.
}
);
// Stop event handling
domain.UnsubscribeGlobalRankingScores(callbackId); const auto Domain = Gs2->Ranking2->Namespace(
"namespace-0001" // namespaceName
)->GlobalRankingModel(
"ranking-0001" // rankingName
)->GlobalRankingSeason(
0, // season
"user-0001" // userId
);
// Start event handling
const auto CallbackId = Domain->SubscribeGlobalRankingScores(
[]() {
// Called when an element of the list changes.
}
);
// Stop event handling
Domain->UnsubscribeGlobalRankingScores(CallbackId);Warning
This event is triggered when the value stored in the SDK’s local cache changes.
The local cache is updated only when executing the SDK’s API, or by executing stamp sheets via GS2-Distributor with GS2-Gateway notification enabled, or by executing a GS2-JobQueue with GS2-Gateway notification enabled.
Therefore, callbacks will not be invoked if the value is changed in any other way.
putGlobalRanking
Submit a score to a global ranking
Registers the player’s score to the specified global ranking. You can also attach metadata (e.g., a replay ID or character name used). If the player has already submitted a score, this updates it based on the ranking’s rules (e.g., keep the highest score, or always use the latest). Use this after the player completes a scored activity — for example, after clearing a stage, submit the clear time or score to the “High Score Ranking”.
Request
| Type | Condition | Required | Default | Value Limits | Description | |
|---|---|---|---|---|---|---|
| namespaceName | string | ✓ | ~ 128 chars | Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). | ||
| rankingName | string | ✓ | ~ 128 chars | Global Ranking Model name Global Ranking Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). | ||
| gameSession | GameSession | ✓ | GameSession | |||
| score | long | ✓ | 0 ~ 9223372036854775805 | Score The score value submitted by the user. Must be within the range defined by the ranking model’s minimumValue and maximumValue settings. | ||
| metadata | string | ~ 512 chars | Metadata Arbitrary values can be set in the metadata. Since they do not affect GS2’s behavior, they can be used to store information used in the game. |
Result
| Type | Description | |
|---|---|---|
| item | EzGlobalRankingScore | Registered Global Ranking Score |
Implementation Example
var domain = gs2.Ranking2.Namespace(
namespaceName: "namespace-0001"
).GlobalRankingModel(
rankingName: "ranking-0001"
).GlobalRankingSeason(
season: 0,
userId: "user-0001"
);
var result = await domain.PutGlobalRankingAsync(
score: 100L,
metadata: null
);
var item = await result.ModelAsync(); var domain = gs2.Ranking2.Namespace(
namespaceName: "namespace-0001"
).GlobalRankingModel(
rankingName: "ranking-0001"
).GlobalRankingSeason(
season: 0,
userId: "user-0001"
);
var future = domain.PutGlobalRankingFuture(
score: 100L,
metadata: null
);
yield return future;
if (future.Error != null)
{
onError.Invoke(future.Error, null);
yield break;
}
var future2 = future.Result.ModelFuture();
yield return future2;
if (future2.Error != null)
{
onError.Invoke(future2.Error, null);
yield break;
}
var result = future2.Result; const auto Domain = Gs2->Ranking2->Namespace(
"namespace-0001" // namespaceName
)->GlobalRankingModel(
"ranking-0001" // rankingName
)->GlobalRankingSeason(
0, // season
"user-0001" // userId
);
const auto Future = Domain->PutGlobalRanking(
100L // score
// metadata
);
Future->StartSynchronousTask();
if (Future->GetTask().IsError())
{
return false;
}
// obtain changed values / result values
const auto Future2 = Future->GetTask().Result()->Model();
Future2->StartSynchronousTask();
if (Future2->GetTask().IsError())
{
return Future2->GetTask().Error();
}
const auto Result = Future2->GetTask().Result();getClusterRankingRank
Get the player’s own rank in a cluster ranking
Retrieves the player’s own ranking entry within a specific cluster (group), including their rank position and score. Use this to display the player’s position within their group — for example, showing “Your guild rank: #3 (8,500 pts)” at the top of the guild ranking screen.
Request
| Type | Condition | Required | Default | Value Limits | Description | |
|---|---|---|---|---|---|---|
| namespaceName | string | ✓ | ~ 128 chars | Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). | ||
| rankingName | string | ✓ | ~ 128 chars | Cluster Ranking Model name Cluster Ranking Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). | ||
| clusterName | string | ✓ | ~ 1024 chars | Cluster Name The name of the cluster (guild, gathering, or group) that this season belongs to. | ||
| season | long | 0 ~ 9223372036854775805 | Season | |||
| gameSession | GameSession | ✓ | GameSession |
Result
| Type | Description | |
|---|---|---|
| item | EzClusterRankingData | Cluster Ranking |
Implementation Example
var domain = gs2.Ranking2.Namespace(
namespaceName: "namespace-0001"
).ClusterRankingModel(
rankingName: "ranking-0001"
).ClusterRankingSeason(
clusterName: "cluster-0001",
season: null,
gameSession: GameSession
);
var result = await domain.GetClusterRankingRankAsync(
);
var item = await result.ModelAsync(); var domain = gs2.Ranking2.Namespace(
namespaceName: "namespace-0001"
).ClusterRankingModel(
rankingName: "ranking-0001"
).ClusterRankingSeason(
clusterName: "cluster-0001",
season: null,
userId: "user-0001"
);
var future = domain.GetClusterRankingRankFuture(
);
yield return future;
if (future.Error != null)
{
onError.Invoke(future.Error, null);
yield break;
}
var future2 = future.Result.ModelFuture();
yield return future2;
if (future2.Error != null)
{
onError.Invoke(future2.Error, null);
yield break;
}
var result = future2.Result; const auto Domain = Gs2->Ranking2->Namespace(
"namespace-0001" // namespaceName
)->ClusterRankingModel(
"ranking-0001" // rankingName
)->ClusterRankingSeason(
"cluster-0001", // clusterName
nullptr, // season
"user-0001" // userId
);
const auto Future = Domain->GetClusterRankingRank(
);
Future->StartSynchronousTask();
if (Future->GetTask().IsError())
{
return false;
}
// obtain changed values / result values
const auto Future2 = Future->GetTask().Result()->Model();
Future2->StartSynchronousTask();
if (Future2->GetTask().IsError())
{
return Future2->GetTask().Error();
}
const auto Result = Future2->GetTask().Result();listClusterRankings
Get the cluster ranking leaderboard
Retrieves the leaderboard entries for a specific cluster (group), showing players ranked by their scores within that group. Each entry includes the player’s user ID, score, rank position, and any attached metadata. Use this to display the group leaderboard — for example, showing the guild ranking “1st: Alice (8,500 pts), 2nd: Bob (7,200 pts), 3rd: Charlie (6,800 pts)” on a guild ranking screen.
Request
| Type | Condition | Required | Default | Value Limits | Description | |
|---|---|---|---|---|---|---|
| namespaceName | string | ✓ | ~ 128 chars | Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). | ||
| rankingName | string | ✓ | ~ 128 chars | Cluster Ranking Model name Cluster Ranking Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). | ||
| clusterName | string | ✓ | ~ 1024 chars | Cluster Name The name of the cluster (guild, gathering, or group) that this season belongs to. | ||
| season | long | 0 ~ 9223372036854775805 | Season | |||
| gameSession | GameSession | ✓ | GameSession | |||
| pageToken | string | ~ 1024 chars | Token specifying the position from which to start acquiring data | |||
| limit | int | 30 | 1 ~ 1000 | Number of data items to retrieve |
Result
| Type | Description | |
|---|---|---|
| items | List<EzClusterRankingData> | List of Cluster Rankings |
| nextPageToken | string | Page token to retrieve the rest of the listing |
Implementation Example
var domain = gs2.Ranking2.Namespace(
namespaceName: "namespace-0001"
).ClusterRankingModel(
rankingName: "ranking-0001"
).ClusterRankingSeason(
clusterName: "cluster-0001",
season: null,
userId: "user-0001"
);
var items = await domain.ClusterRankingsAsync(
).ToListAsync(); var domain = gs2.Ranking2.Namespace(
namespaceName: "namespace-0001"
).ClusterRankingModel(
rankingName: "ranking-0001"
).ClusterRankingSeason(
clusterName: "cluster-0001",
season: null,
userId: "user-0001"
);
var it = domain.ClusterRankings(
);
List<EzClusterRankingData> items = new List<EzClusterRankingData>();
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->Ranking2->Namespace(
"namespace-0001" // namespaceName
)->ClusterRankingModel(
"ranking-0001" // rankingName
)->ClusterRankingSeason(
"cluster-0001", // clusterName
nullptr, // season
"user-0001" // userId
);
const auto It = Domain->ClusterRankings(
);
TArray<Gs2::UE5::Ranking2::Model::FEzClusterRankingDataPtr> Result;
for (auto Item : *It)
{
if (Item.IsError())
{
return false;
}
Result.Add(Item.Current());
}getClusterRankingModel
Get a specific cluster ranking definition by name
Retrieves a single cluster ranking model by specifying its name. The returned information includes the score range, sort order, cluster type, reward settings, and season/entry period configurations. Use this to display the rules of a specific cluster ranking — for example, showing “Guild DPS Ranking — Weekly reset, compete within your guild, Top 10 get rewards” on a ranking detail screen.
Request
| Type | Condition | Required | Default | Value Limits | Description | |
|---|---|---|---|---|---|---|
| namespaceName | string | ✓ | ~ 128 chars | Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). | ||
| rankingName | string | ✓ | ~ 128 chars | Cluster Ranking Model name Cluster Ranking Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). |
Result
| Type | Description | |
|---|---|---|
| item | EzClusterRankingModel | Cluster Ranking Model |
Implementation Example
var domain = gs2.Ranking2.Namespace(
namespaceName: "namespace-0001"
).ClusterRankingModel(
rankingName: "ranking-0001"
);
var item = await domain.ModelAsync(); var domain = gs2.Ranking2.Namespace(
namespaceName: "namespace-0001"
).ClusterRankingModel(
rankingName: "ranking-0001"
);
var future = domain.ModelFuture();
yield return future;
var item = future.Result; const auto Domain = Gs2->Ranking2->Namespace(
"namespace-0001" // namespaceName
)->ClusterRankingModel(
"ranking-0001" // rankingName
);
const auto Future = Domain->Model();
Future->StartSynchronousTask();
if (Future->GetTask().IsError())
{
return false;
}Value change event handling
var domain = gs2.Ranking2.Namespace(
namespaceName: "namespace-0001"
).ClusterRankingModel(
rankingName: "ranking-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.Ranking2.Namespace(
namespaceName: "namespace-0001"
).ClusterRankingModel(
rankingName: "ranking-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); const auto Domain = Gs2->Ranking2->Namespace(
"namespace-0001" // namespaceName
)->ClusterRankingModel(
"ranking-0001" // rankingName
);
// Start event handling
const auto CallbackId = Domain->Subscribe(
[](TSharedPtr<Gs2::Ranking2::Model::FClusterRankingModel> 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 triggered when the value stored in the SDK’s local cache changes.
The local cache is updated only when executing the SDK’s API, or by executing stamp sheets via GS2-Distributor with GS2-Gateway notification enabled, or by executing a GS2-JobQueue with GS2-Gateway notification enabled.
Therefore, callbacks will not be invoked if the value is changed in any other way.
listClusterRankingModels
Get a list of cluster ranking definitions
Retrieves all cluster ranking models registered in this namespace. A cluster ranking is a leaderboard within a specific group (cluster) — for example, rankings within a guild, a region, or a game server. Unlike global rankings where all players compete together, cluster rankings let players compete within their group, which is useful for guild-based events or regional competitions. Use this to see what cluster rankings exist — for example, to display “Guild DPS Ranking”, “Regional Score Ranking” as options on a ranking screen.
Request
| Type | Condition | Required | Default | Value Limits | Description | |
|---|---|---|---|---|---|---|
| namespaceName | string | ✓ | ~ 128 chars | Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). |
Result
| Type | Description | |
|---|---|---|
| items | List<EzClusterRankingModel> | List of Cluster Ranking Models |
Implementation Example
var domain = gs2.Ranking2.Namespace(
namespaceName: null
);
var items = await domain.ClusterRankingModelsAsync(
).ToListAsync(); var domain = gs2.Ranking2.Namespace(
namespaceName: null
);
var it = domain.ClusterRankingModels(
);
List<EzClusterRankingModel> items = new List<EzClusterRankingModel>();
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->Ranking2->Namespace(
nullptr // namespaceName
);
const auto It = Domain->ClusterRankingModels(
);
TArray<Gs2::UE5::Ranking2::Model::FEzClusterRankingModelPtr> Result;
for (auto Item : *It)
{
if (Item.IsError())
{
return false;
}
Result.Add(Item.Current());
}Value change event handling
var domain = gs2.Ranking2.Namespace(
namespaceName: null
);
// Start event handling
var callbackId = domain.SubscribeClusterRankingModels(
() => {
// Called when an element of the list changes.
}
);
// Stop event handling
domain.UnsubscribeClusterRankingModels(callbackId); var domain = gs2.Ranking2.Namespace(
namespaceName: null
);
// Start event handling
var callbackId = domain.SubscribeClusterRankingModels(
() => {
// Called when an element of the list changes.
}
);
// Stop event handling
domain.UnsubscribeClusterRankingModels(callbackId); const auto Domain = Gs2->Ranking2->Namespace(
nullptr // namespaceName
);
// Start event handling
const auto CallbackId = Domain->SubscribeClusterRankingModels(
[]() {
// Called when an element of the list changes.
}
);
// Stop event handling
Domain->UnsubscribeClusterRankingModels(CallbackId);Warning
This event is triggered when the value stored in the SDK’s local cache changes.
The local cache is updated only when executing the SDK’s API, or by executing stamp sheets via GS2-Distributor with GS2-Gateway notification enabled, or by executing a GS2-JobQueue with GS2-Gateway notification enabled.
Therefore, callbacks will not be invoked if the value is changed in any other way.
getClusterRankingReceivedReward
Check if the player has claimed a specific cluster ranking reward
Retrieves the reward claim record for a specific cluster ranking, cluster, and season. Use this to check if the player has already claimed the reward — for example, showing a “Claim Reward” button if unclaimed, or “Already Claimed” if already received, on a guild ranking results screen.
Request
| Type | Condition | Required | Default | Value Limits | Description | |
|---|---|---|---|---|---|---|
| namespaceName | string | ✓ | ~ 128 chars | Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). | ||
| rankingName | string | ✓ | ~ 128 chars | Cluster Ranking Model name Cluster Ranking Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). | ||
| clusterName | string | ✓ | ~ 1024 chars | Cluster Name The name of the cluster for which the ranking reward was received. | ||
| season | long | 0 ~ 9223372036854775805 | Season | |||
| gameSession | GameSession | ✓ | GameSession |
Result
| Type | Description | |
|---|---|---|
| item | EzClusterRankingReceivedReward | Cluster Ranking Reward Received History |
Implementation Example
var domain = gs2.Ranking2.Namespace(
namespaceName: "namespace-0001"
).ClusterRankingModel(
rankingName: "ranking-0001"
).ClusterRankingSeason(
clusterName: "cluster-0001",
season: 0,
userId: "user-0001"
).ClusterRankingReceivedReward(
);
var item = await domain.ModelAsync(); var domain = gs2.Ranking2.Namespace(
namespaceName: "namespace-0001"
).ClusterRankingModel(
rankingName: "ranking-0001"
).ClusterRankingSeason(
clusterName: "cluster-0001",
season: 0,
userId: "user-0001"
).ClusterRankingReceivedReward(
);
var future = domain.ModelFuture();
yield return future;
var item = future.Result; const auto Domain = Gs2->Ranking2->Namespace(
"namespace-0001" // namespaceName
)->ClusterRankingModel(
"ranking-0001" // rankingName
)->ClusterRankingSeason(
"cluster-0001", // clusterName
0, // season
"user-0001" // userId
)->ClusterRankingReceivedReward(
);
const auto Future = Domain->Model();
Future->StartSynchronousTask();
if (Future->GetTask().IsError())
{
return false;
}Value change event handling
var domain = gs2.Ranking2.Namespace(
namespaceName: "namespace-0001"
).ClusterRankingModel(
rankingName: "ranking-0001"
).ClusterRankingSeason(
clusterName: "cluster-0001",
season: 0,
userId: "user-0001"
).ClusterRankingReceivedReward(
);
// 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.Ranking2.Namespace(
namespaceName: "namespace-0001"
).ClusterRankingModel(
rankingName: "ranking-0001"
).ClusterRankingSeason(
clusterName: "cluster-0001",
season: 0,
userId: "user-0001"
).ClusterRankingReceivedReward(
);
// 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); const auto Domain = Gs2->Ranking2->Namespace(
"namespace-0001" // namespaceName
)->ClusterRankingModel(
"ranking-0001" // rankingName
)->ClusterRankingSeason(
"cluster-0001", // clusterName
0, // season
"user-0001" // userId
)->ClusterRankingReceivedReward(
);
// Start event handling
const auto CallbackId = Domain->Subscribe(
[](TSharedPtr<Gs2::Ranking2::Model::FClusterRankingReceivedReward> 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 triggered when the value stored in the SDK’s local cache changes.
The local cache is updated only when executing the SDK’s API, or by executing stamp sheets via GS2-Distributor with GS2-Gateway notification enabled, or by executing a GS2-JobQueue with GS2-Gateway notification enabled.
Therefore, callbacks will not be invoked if the value is changed in any other way.
listClusterRankingReceivedRewards
Get a list of the player’s cluster ranking reward claim history
Retrieves the player’s history of claimed ranking rewards from cluster rankings. Each entry shows which ranking, cluster, and season the reward was claimed for. Use this to display reward claim status for group rankings — for example, showing “Guild DPS Ranking Season 1: Claimed, Season 2: Not yet claimed” on a guild ranking rewards screen.
Request
| Type | Condition | Required | Default | Value Limits | Description | |
|---|---|---|---|---|---|---|
| namespaceName | string | ✓ | ~ 128 chars | Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). | ||
| rankingName | string | ~ 128 chars | Cluster Ranking Model name Cluster Ranking Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). | |||
| clusterName | string | ~ 1024 chars | Cluster Name The name of the cluster for which the ranking reward was received. | |||
| season | long | 0 ~ 9223372036854775805 | Season | |||
| gameSession | GameSession | ✓ | GameSession | |||
| pageToken | string | ~ 1024 chars | Token specifying the position from which to start acquiring data | |||
| limit | int | 30 | 1 ~ 1000 | Number of data items to retrieve |
Result
| Type | Description | |
|---|---|---|
| items | List<EzClusterRankingReceivedReward> | List of Cluster Ranking Rewards Received |
| nextPageToken | string | Page token to retrieve the rest of the listing |
Implementation Example
var domain = gs2.Ranking2.Namespace(
namespaceName: "namespace-0001"
).ClusterRankingModel(
rankingName: "ranking-0001"
).ClusterRankingSeason(
clusterName: "cluster-0001",
season: 0,
userId: "user-0001"
);
var items = await domain.ClusterRankingReceivedRewardsAsync(
).ToListAsync(); var domain = gs2.Ranking2.Namespace(
namespaceName: "namespace-0001"
).ClusterRankingModel(
rankingName: "ranking-0001"
).ClusterRankingSeason(
clusterName: "cluster-0001",
season: 0,
userId: "user-0001"
);
var it = domain.ClusterRankingReceivedRewards(
);
List<EzClusterRankingReceivedReward> items = new List<EzClusterRankingReceivedReward>();
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->Ranking2->Namespace(
"namespace-0001" // namespaceName
)->ClusterRankingModel(
"ranking-0001" // rankingName
)->ClusterRankingSeason(
"cluster-0001", // clusterName
0, // season
"user-0001" // userId
);
const auto It = Domain->ClusterRankingReceivedRewards(
);
TArray<Gs2::UE5::Ranking2::Model::FEzClusterRankingReceivedRewardPtr> Result;
for (auto Item : *It)
{
if (Item.IsError())
{
return false;
}
Result.Add(Item.Current());
}Value change event handling
var domain = gs2.Ranking2.Namespace(
namespaceName: "namespace-0001"
).ClusterRankingModel(
rankingName: "ranking-0001"
).ClusterRankingSeason(
clusterName: "cluster-0001",
season: 0,
userId: "user-0001"
);
// Start event handling
var callbackId = domain.SubscribeClusterRankingReceivedRewards(
() => {
// Called when an element of the list changes.
}
);
// Stop event handling
domain.UnsubscribeClusterRankingReceivedRewards(callbackId); var domain = gs2.Ranking2.Namespace(
namespaceName: "namespace-0001"
).ClusterRankingModel(
rankingName: "ranking-0001"
).ClusterRankingSeason(
clusterName: "cluster-0001",
season: 0,
userId: "user-0001"
);
// Start event handling
var callbackId = domain.SubscribeClusterRankingReceivedRewards(
() => {
// Called when an element of the list changes.
}
);
// Stop event handling
domain.UnsubscribeClusterRankingReceivedRewards(callbackId); const auto Domain = Gs2->Ranking2->Namespace(
"namespace-0001" // namespaceName
)->ClusterRankingModel(
"ranking-0001" // rankingName
)->ClusterRankingSeason(
"cluster-0001", // clusterName
0, // season
"user-0001" // userId
);
// Start event handling
const auto CallbackId = Domain->SubscribeClusterRankingReceivedRewards(
[]() {
// Called when an element of the list changes.
}
);
// Stop event handling
Domain->UnsubscribeClusterRankingReceivedRewards(CallbackId);Warning
This event is triggered when the value stored in the SDK’s local cache changes.
The local cache is updated only when executing the SDK’s API, or by executing stamp sheets via GS2-Distributor with GS2-Gateway notification enabled, or by executing a GS2-JobQueue with GS2-Gateway notification enabled.
Therefore, callbacks will not be invoked if the value is changed in any other way.
receiveClusterRankingReward
Claim the cluster ranking reward
Claims the ranking reward based on the player’s final rank in the specified cluster ranking, cluster, and season. The reward is determined by the player’s rank position within their group and the ranking model’s reward settings — for example, the top player in each guild might receive a special guild champion item. The reward items are automatically granted to the player. Use this when the player taps “Claim Reward” on the group ranking results screen after a season ends.
Request
| Type | Condition | Required | Default | Value Limits | Description | |
|---|---|---|---|---|---|---|
| namespaceName | string | ✓ | ~ 128 chars | Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). | ||
| rankingName | string | ✓ | ~ 128 chars | Cluster Ranking Model name Cluster Ranking Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). | ||
| clusterName | string | ✓ | ~ 1024 chars | Cluster Name The name of the cluster for which the ranking reward was received. | ||
| season | long | 0 ~ 9223372036854775805 | Season | |||
| gameSession | GameSession | ✓ | GameSession | |||
| config | List<EzConfig> | [] | 0 ~ 32 items | Set values to be applied to transaction variables |
Result
| Type | Description | |
|---|---|---|
| item | EzClusterRankingModel | Cluster Ranking Model |
| acquireActions | List<EzAcquireAction> | List of Acquire Actions to be performed when rewards are received |
| transactionId | string | Issued transaction ID |
| stampSheet | string | Stamp sheet used to execute the exchange process |
| stampSheetEncryptionKeyId | string | Cryptographic key GRN used for stamp sheet signature calculations |
| autoRunStampSheet | bool | Whether automatic transaction execution is enabled |
| atomicCommit | bool | Whether to commit the transaction atomically |
| transaction | string | Issued transaction |
| transactionResult | EzTransactionResult | Transaction execution result |
Implementation Example
var domain = gs2.Ranking2.Namespace(
namespaceName: "namespace-0001"
).ClusterRankingModel(
rankingName: "ranking-0001"
).ClusterRankingSeason(
clusterName: "cluster-0001",
season: 0,
userId: "user-0001"
).ClusterRankingReceivedReward(
);
var result = await domain.ReceiveClusterRankingRewardAsync(
config: null
);
// In New Experience, stamp sheets are automatically executed at the SDK level.
// If an error occurs, a TransactionException is thrown.
// you can retry with TransactionException::Retry(). var domain = gs2.Ranking2.Namespace(
namespaceName: "namespace-0001"
).ClusterRankingModel(
rankingName: "ranking-0001"
).ClusterRankingSeason(
clusterName: "cluster-0001",
season: 0,
userId: "user-0001"
).ClusterRankingReceivedReward(
);
var future = domain.ReceiveClusterRankingRewardFuture(
config: null
);
yield return future;
if (future.Error != null)
{
onError.Invoke(future.Error, null);
yield break;
}
// In New Experience, stamp sheets are automatically executed at the SDK level.
// If an error occurs, a TransactionException is thrown.
// you can retry with TransactionException::Retry(). const auto Domain = Gs2->Ranking2->Namespace(
"namespace-0001" // namespaceName
)->ClusterRankingModel(
"ranking-0001" // rankingName
)->ClusterRankingSeason(
"cluster-0001", // clusterName
0, // season
"user-0001" // userId
)->ClusterRankingReceivedReward(
);
const auto Future = Domain->ReceiveClusterRankingReward(
// config
);
Future->StartSynchronousTask();
if (Future->GetTask().IsError())
{
return false;
}getClusterRankingScore
Get the player’s submitted score for a specific cluster ranking
Retrieves the player’s score for a specific cluster ranking, cluster, and season. Use this to display the player’s current score within their group — for example, showing “Your score in Dragon Slayers guild: 8,500 pts (Season 2)” on a guild ranking detail screen.
Request
| Type | Condition | Required | Default | Value Limits | Description | |
|---|---|---|---|---|---|---|
| namespaceName | string | ✓ | ~ 128 chars | Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). | ||
| rankingName | string | ✓ | ~ 128 chars | Cluster Ranking Model name Cluster Ranking Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). | ||
| clusterName | string | ✓ | ~ 1024 chars | Cluster Name The name of the cluster (guild, gathering, or arbitrary group) that this score belongs to. Verified against the cluster type setting to ensure the user is a member. | ||
| season | long | 0 ~ 9223372036854775805 | Season | |||
| gameSession | GameSession | ✓ | GameSession |
Result
| Type | Description | |
|---|---|---|
| item | EzClusterRankingScore | Cluster Ranking Score |
Implementation Example
var domain = gs2.Ranking2.Namespace(
namespaceName: "namespace-0001"
).ClusterRankingModel(
rankingName: "ranking-0001"
).ClusterRankingSeason(
clusterName: "cluster-0001",
season: 0,
userId: "user-0001"
).ClusterRankingScore(
);
var item = await domain.ModelAsync(); var domain = gs2.Ranking2.Namespace(
namespaceName: "namespace-0001"
).ClusterRankingModel(
rankingName: "ranking-0001"
).ClusterRankingSeason(
clusterName: "cluster-0001",
season: 0,
userId: "user-0001"
).ClusterRankingScore(
);
var future = domain.ModelFuture();
yield return future;
var item = future.Result; const auto Domain = Gs2->Ranking2->Namespace(
"namespace-0001" // namespaceName
)->ClusterRankingModel(
"ranking-0001" // rankingName
)->ClusterRankingSeason(
"cluster-0001", // clusterName
0, // season
"user-0001" // userId
)->ClusterRankingScore(
);
const auto Future = Domain->Model();
Future->StartSynchronousTask();
if (Future->GetTask().IsError())
{
return false;
}Value change event handling
var domain = gs2.Ranking2.Namespace(
namespaceName: "namespace-0001"
).ClusterRankingModel(
rankingName: "ranking-0001"
).ClusterRankingSeason(
clusterName: "cluster-0001",
season: 0,
userId: "user-0001"
).ClusterRankingScore(
);
// 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.Ranking2.Namespace(
namespaceName: "namespace-0001"
).ClusterRankingModel(
rankingName: "ranking-0001"
).ClusterRankingSeason(
clusterName: "cluster-0001",
season: 0,
userId: "user-0001"
).ClusterRankingScore(
);
// 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); const auto Domain = Gs2->Ranking2->Namespace(
"namespace-0001" // namespaceName
)->ClusterRankingModel(
"ranking-0001" // rankingName
)->ClusterRankingSeason(
"cluster-0001", // clusterName
0, // season
"user-0001" // userId
)->ClusterRankingScore(
);
// Start event handling
const auto CallbackId = Domain->Subscribe(
[](TSharedPtr<Gs2::Ranking2::Model::FClusterRankingScore> 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 triggered when the value stored in the SDK’s local cache changes.
The local cache is updated only when executing the SDK’s API, or by executing stamp sheets via GS2-Distributor with GS2-Gateway notification enabled, or by executing a GS2-JobQueue with GS2-Gateway notification enabled.
Therefore, callbacks will not be invoked if the value is changed in any other way.
listClusterRankingScores
Get a list of the player’s submitted scores for cluster rankings
Retrieves the player’s scores submitted to a specific cluster ranking within a specific cluster (group). Use this to display the player’s own scores within their group — for example, showing “Your Guild DPS Score: 8,500 pts” on a guild ranking screen.
Request
| Type | Condition | Required | Default | Value Limits | Description | |
|---|---|---|---|---|---|---|
| namespaceName | string | ✓ | ~ 128 chars | Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). | ||
| rankingName | string | ~ 128 chars | Cluster Ranking Model name Cluster Ranking Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). | |||
| clusterName | string | ~ 1024 chars | Cluster Name The name of the cluster (guild, gathering, or arbitrary group) that this score belongs to. Verified against the cluster type setting to ensure the user is a member. | |||
| season | long | 0 ~ 9223372036854775805 | Season | |||
| gameSession | GameSession | ✓ | GameSession | |||
| pageToken | string | ~ 1024 chars | Token specifying the position from which to start acquiring data | |||
| limit | int | 30 | 1 ~ 1000 | Number of data items to retrieve |
Result
| Type | Description | |
|---|---|---|
| items | List<EzClusterRankingScore> | List of Cluster Ranking Scores |
| nextPageToken | string | Page token to retrieve the rest of the listing |
Implementation Example
var domain = gs2.Ranking2.Namespace(
namespaceName: "namespace-0001"
).ClusterRankingModel(
rankingName: "ranking-0001"
).ClusterRankingSeason(
clusterName: "cluster-0001",
season: 0,
userId: "user-0001"
);
var items = await domain.ClusterRankingScoresAsync(
).ToListAsync(); var domain = gs2.Ranking2.Namespace(
namespaceName: "namespace-0001"
).ClusterRankingModel(
rankingName: "ranking-0001"
).ClusterRankingSeason(
clusterName: "cluster-0001",
season: 0,
userId: "user-0001"
);
var it = domain.ClusterRankingScores(
);
List<EzClusterRankingScore> items = new List<EzClusterRankingScore>();
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->Ranking2->Namespace(
"namespace-0001" // namespaceName
)->ClusterRankingModel(
"ranking-0001" // rankingName
)->ClusterRankingSeason(
"cluster-0001", // clusterName
0, // season
"user-0001" // userId
);
const auto It = Domain->ClusterRankingScores(
);
TArray<Gs2::UE5::Ranking2::Model::FEzClusterRankingScorePtr> Result;
for (auto Item : *It)
{
if (Item.IsError())
{
return false;
}
Result.Add(Item.Current());
}Value change event handling
var domain = gs2.Ranking2.Namespace(
namespaceName: "namespace-0001"
).ClusterRankingModel(
rankingName: "ranking-0001"
).ClusterRankingSeason(
clusterName: "cluster-0001",
season: 0,
userId: "user-0001"
);
// Start event handling
var callbackId = domain.SubscribeClusterRankingScores(
() => {
// Called when an element of the list changes.
}
);
// Stop event handling
domain.UnsubscribeClusterRankingScores(callbackId); var domain = gs2.Ranking2.Namespace(
namespaceName: "namespace-0001"
).ClusterRankingModel(
rankingName: "ranking-0001"
).ClusterRankingSeason(
clusterName: "cluster-0001",
season: 0,
userId: "user-0001"
);
// Start event handling
var callbackId = domain.SubscribeClusterRankingScores(
() => {
// Called when an element of the list changes.
}
);
// Stop event handling
domain.UnsubscribeClusterRankingScores(callbackId); const auto Domain = Gs2->Ranking2->Namespace(
"namespace-0001" // namespaceName
)->ClusterRankingModel(
"ranking-0001" // rankingName
)->ClusterRankingSeason(
"cluster-0001", // clusterName
0, // season
"user-0001" // userId
);
// Start event handling
const auto CallbackId = Domain->SubscribeClusterRankingScores(
[]() {
// Called when an element of the list changes.
}
);
// Stop event handling
Domain->UnsubscribeClusterRankingScores(CallbackId);Warning
This event is triggered when the value stored in the SDK’s local cache changes.
The local cache is updated only when executing the SDK’s API, or by executing stamp sheets via GS2-Distributor with GS2-Gateway notification enabled, or by executing a GS2-JobQueue with GS2-Gateway notification enabled.
Therefore, callbacks will not be invoked if the value is changed in any other way.
putClusterRanking
Submit a score to a cluster ranking
Registers the player’s score to the specified cluster ranking within a specific cluster (group). You can also attach metadata. The cluster name identifies which group the score belongs to — for example, the guild name for a guild ranking. Use this after the player completes a scored activity within their group — for example, after clearing a guild raid boss, submit the DPS score to the “Guild DPS Ranking” for the player’s guild.
Request
| Type | Condition | Required | Default | Value Limits | Description | |
|---|---|---|---|---|---|---|
| namespaceName | string | ✓ | ~ 128 chars | Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). | ||
| rankingName | string | ✓ | ~ 128 chars | Cluster Ranking Model name Cluster Ranking Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). | ||
| clusterName | string | ✓ | ~ 1024 chars | Cluster Name The name of the cluster (guild, gathering, or arbitrary group) that this score belongs to. Verified against the cluster type setting to ensure the user is a member. | ||
| gameSession | GameSession | ✓ | GameSession | |||
| score | long | ✓ | 0 ~ 9223372036854775805 | Score The score value submitted by the user within this cluster. | ||
| metadata | string | ~ 512 chars | Metadata Arbitrary values can be set in the metadata. Since they do not affect GS2’s behavior, they can be used to store information used in the game. |
Result
| Type | Description | |
|---|---|---|
| item | EzClusterRankingScore | Registered Cluster Ranking Score |
Implementation Example
var domain = gs2.Ranking2.Namespace(
namespaceName: "namespace-0001"
).ClusterRankingModel(
rankingName: "ranking-0001"
).ClusterRankingSeason(
clusterName: "cluster-0001",
season: 0,
userId: "user-0001"
);
var result = await domain.PutClusterRankingAsync(
score: 100L,
metadata: null
);
var item = await result.ModelAsync(); var domain = gs2.Ranking2.Namespace(
namespaceName: "namespace-0001"
).ClusterRankingModel(
rankingName: "ranking-0001"
).ClusterRankingSeason(
clusterName: "cluster-0001",
season: 0,
userId: "user-0001"
);
var future = domain.PutClusterRankingFuture(
score: 100L,
metadata: null
);
yield return future;
if (future.Error != null)
{
onError.Invoke(future.Error, null);
yield break;
}
var future2 = future.Result.ModelFuture();
yield return future2;
if (future2.Error != null)
{
onError.Invoke(future2.Error, null);
yield break;
}
var result = future2.Result; const auto Domain = Gs2->Ranking2->Namespace(
"namespace-0001" // namespaceName
)->ClusterRankingModel(
"ranking-0001" // rankingName
)->ClusterRankingSeason(
"cluster-0001", // clusterName
0, // season
"user-0001" // userId
);
const auto Future = Domain->PutClusterRanking(
100L // score
// metadata
);
Future->StartSynchronousTask();
if (Future->GetTask().IsError())
{
return false;
}
// obtain changed values / result values
const auto Future2 = Future->GetTask().Result()->Model();
Future2->StartSynchronousTask();
if (Future2->GetTask().IsError())
{
return Future2->GetTask().Error();
}
const auto Result = Future2->GetTask().Result();getSubscribe
Check if the player is following a specific user for subscribe rankings
Retrieves the subscription information for a specific target user. Use this to check if the player is already following a particular user — for example, showing a “Following” or “Follow” button on another player’s profile, or verifying the subscription before displaying their score on the friend leaderboard.
Request
| Type | Condition | Required | Default | Value Limits | Description | |
|---|---|---|---|---|---|---|
| namespaceName | string | ✓ | ~ 128 chars | Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). | ||
| rankingName | string | ✓ | ~ 128 chars | Subscribe Ranking Model name Subscribe Ranking Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). | ||
| gameSession | GameSession | ✓ | GameSession | |||
| targetUserId | string | ✓ | ~ 128 chars | Subscribe Target User ID |
Result
| Type | Description | |
|---|---|---|
| item | EzSubscribeUser | Subscribed User Information |
Implementation Example
var domain = gs2.Ranking2.Namespace(
namespaceName: "namespace-0001"
).Me(
gameSession: GameSession
).Subscribe(
rankingName: "ranking-0001"
).SubscribeUser(
targetUserId: "user-0002"
);
var result = await domain.GetSubscribeAsync(
);
var item = await result.ModelAsync(); var domain = gs2.Ranking2.Namespace(
namespaceName: "namespace-0001"
).Me(
gameSession: GameSession
).Subscribe(
rankingName: "ranking-0001"
).SubscribeUser(
targetUserId: "user-0002"
);
var future = domain.GetSubscribeFuture(
);
yield return future;
if (future.Error != null)
{
onError.Invoke(future.Error, null);
yield break;
}
var future2 = future.Result.ModelFuture();
yield return future2;
if (future2.Error != null)
{
onError.Invoke(future2.Error, null);
yield break;
}
var result = future2.Result; const auto Domain = Gs2->Ranking2->Namespace(
"namespace-0001" // namespaceName
)->Me(
GameSession
)->Subscribe(
"ranking-0001" // rankingName
)->SubscribeUser(
"user-0002" // targetUserId
);
const auto Future = Domain->GetSubscribe(
);
Future->StartSynchronousTask();
if (Future->GetTask().IsError())
{
return false;
}
// obtain changed values / result values
const auto Future2 = Future->GetTask().Result()->Model();
Future2->StartSynchronousTask();
if (Future2->GetTask().IsError())
{
return Future2->GetTask().Error();
}
const auto Result = Future2->GetTask().Result();listSubscribes
Get a list of users the player is following for subscribe rankings
Retrieves all users that the player has subscribed to (followed) for subscribe rankings. Subscribe rankings only show scores from followed users, so this list determines who appears on the player’s friend leaderboard. Use this to display the player’s “following” list for rankings — for example, showing “Following: Alice, Bob, Charlie” on a friend ranking management screen, or to check how many friends the player is tracking.
Request
| Type | Condition | Required | Default | Value Limits | Description | |
|---|---|---|---|---|---|---|
| namespaceName | string | ✓ | ~ 128 chars | Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). | ||
| rankingName | string | ✓ | ~ 128 chars | Subscribe Ranking Model name Subscribe Ranking Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). | ||
| gameSession | GameSession | ✓ | GameSession | |||
| pageToken | string | ~ 1024 chars | Token specifying the position from which to start acquiring data | |||
| limit | int | 30 | 1 ~ 1000 | Number of data items to retrieve |
Result
| Type | Description | |
|---|---|---|
| items | List<EzSubscribeUser> | List of Subscribed User Information |
| nextPageToken | string | Page token to retrieve the rest of the listing |
Implementation Example
var domain = gs2.Ranking2.Namespace(
namespaceName: "namespace-0001"
).Me(
gameSession: GameSession
);
var items = await domain.SubscribesAsync(
rankingName: "ranking-0001"
).ToListAsync(); var domain = gs2.Ranking2.Namespace(
namespaceName: "namespace-0001"
).Me(
gameSession: GameSession
);
var it = domain.Subscribes(
rankingName: "ranking-0001"
);
List<EzSubscribeUser> items = new List<EzSubscribeUser>();
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->Ranking2->Namespace(
"namespace-0001" // namespaceName
)->Me(
GameSession
);
const auto It = Domain->Subscribes(
"ranking-0001" // rankingName
);
TArray<Gs2::UE5::Ranking2::Model::FEzSubscribeUserPtr> Result;
for (auto Item : *It)
{
if (Item.IsError())
{
return false;
}
Result.Add(Item.Current());
}Value change event handling
var domain = gs2.Ranking2.Namespace(
namespaceName: "namespace-0001"
).Me(
gameSession: GameSession
);
// Start event handling
var callbackId = domain.SubscribeSubscribes(
() => {
// Called when an element of the list changes.
}
);
// Stop event handling
domain.UnsubscribeSubscribes(callbackId); var domain = gs2.Ranking2.Namespace(
namespaceName: "namespace-0001"
).Me(
gameSession: GameSession
);
// Start event handling
var callbackId = domain.SubscribeSubscribes(
() => {
// Called when an element of the list changes.
}
);
// Stop event handling
domain.UnsubscribeSubscribes(callbackId); const auto Domain = Gs2->Ranking2->Namespace(
"namespace-0001" // namespaceName
)->Me(
GameSession
);
// Start event handling
const auto CallbackId = Domain->SubscribeSubscribes(
[]() {
// Called when an element of the list changes.
}
);
// Stop event handling
Domain->UnsubscribeSubscribes(CallbackId);Warning
This event is triggered when the value stored in the SDK’s local cache changes.
The local cache is updated only when executing the SDK’s API, or by executing stamp sheets via GS2-Distributor with GS2-Gateway notification enabled, or by executing a GS2-JobQueue with GS2-Gateway notification enabled.
Therefore, callbacks will not be invoked if the value is changed in any other way.
getSubscribeRankingRank
Get the player’s own rank in a subscribe (friend) ranking
Retrieves the player’s own ranking entry among their friends, including their rank position and score. Use this to display the player’s position on the friend leaderboard — for example, showing “Your rank among friends: #2 (10,500 pts)” at the top of the friend ranking screen.
Request
| Type | Condition | Required | Default | Value Limits | Description | |
|---|---|---|---|---|---|---|
| namespaceName | string | ✓ | ~ 128 chars | Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). | ||
| rankingName | string | ✓ | ~ 128 chars | Subscribe Ranking Model name Subscribe Ranking Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). | ||
| season | long | 0 ~ 9223372036854775805 | Season | |||
| gameSession | GameSession | ✓ | GameSession |
Result
| Type | Description | |
|---|---|---|
| item | EzSubscribeRankingData | Subscribe Ranking |
Implementation Example
var domain = gs2.Ranking2.Namespace(
namespaceName: "namespace-0001"
).SubscribeRankingModel(
rankingName: "ranking-0001"
).SubscribeRankingSeason(
season: null,
userId: "user-0001"
).SubscribeRankingData(
scorerUserId: null
);
var result = await domain.GetSubscribeRankingRankAsync(
);
var item = await result.ModelAsync(); var domain = gs2.Ranking2.Namespace(
namespaceName: "namespace-0001"
).SubscribeRankingModel(
rankingName: "ranking-0001"
).SubscribeRankingSeason(
season: null,
userId: "user-0001"
).SubscribeRankingData(
scorerUserId: null
);
var future = domain.GetSubscribeRankingRankFuture(
);
yield return future;
if (future.Error != null)
{
onError.Invoke(future.Error, null);
yield break;
}
var future2 = future.Result.ModelFuture();
yield return future2;
if (future2.Error != null)
{
onError.Invoke(future2.Error, null);
yield break;
}
var result = future2.Result; const auto Domain = Gs2->Ranking2->Namespace(
"namespace-0001" // namespaceName
)->SubscribeRankingModel(
"ranking-0001" // rankingName
)->SubscribeRankingSeason(
nullptr, // season
"user-0001" // userId
)->SubscribeRankingData(
nullptr // scorerUserId
);
const auto Future = Domain->GetSubscribeRankingRank(
);
Future->StartSynchronousTask();
if (Future->GetTask().IsError())
{
return false;
}
// obtain changed values / result values
const auto Future2 = Future->GetTask().Result()->Model();
Future2->StartSynchronousTask();
if (Future2->GetTask().IsError())
{
return Future2->GetTask().Error();
}
const auto Result = Future2->GetTask().Result();listSubscribeRankings
Get the subscribe (friend) ranking leaderboard
Retrieves the friend leaderboard, showing only scores from users the player has subscribed to (followed). Each entry includes the user ID, score, rank position, and any attached metadata. Use this to display the friend leaderboard — for example, showing “1st: Alice (12,000 pts), 2nd: You (10,500 pts), 3rd: Bob (9,800 pts)” on a friend ranking screen.
Request
| Type | Condition | Required | Default | Value Limits | Description | |
|---|---|---|---|---|---|---|
| namespaceName | string | ✓ | ~ 128 chars | Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). | ||
| rankingName | string | ✓ | ~ 128 chars | Subscribe Ranking Model name Subscribe Ranking Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). | ||
| season | long | 0 ~ 9223372036854775805 | Season | |||
| gameSession | GameSession | ✓ | GameSession | |||
| pageToken | string | ~ 1024 chars | Token specifying the position from which to start acquiring data | |||
| limit | int | 30 | 1 ~ 1000 | Number of data items to retrieve |
Result
| Type | Description | |
|---|---|---|
| items | List<EzSubscribeRankingData> | List of Subscribe Rankings |
| nextPageToken | string | Page token to retrieve the rest of the listing |
Implementation Example
var domain = gs2.Ranking2.Namespace(
namespaceName: "namespace-0001"
).SubscribeRankingModel(
rankingName: "ranking-0001"
).SubscribeRankingSeason(
season: null,
userId: "user-0001"
);
var items = await domain.SubscribeRankingsAsync(
).ToListAsync(); var domain = gs2.Ranking2.Namespace(
namespaceName: "namespace-0001"
).SubscribeRankingModel(
rankingName: "ranking-0001"
).SubscribeRankingSeason(
season: null,
userId: "user-0001"
);
var it = domain.SubscribeRankings(
);
List<EzSubscribeRankingData> items = new List<EzSubscribeRankingData>();
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->Ranking2->Namespace(
"namespace-0001" // namespaceName
)->SubscribeRankingModel(
"ranking-0001" // rankingName
)->SubscribeRankingSeason(
nullptr, // season
"user-0001" // userId
);
const auto It = Domain->SubscribeRankings(
);
TArray<Gs2::UE5::Ranking2::Model::FEzSubscribeRankingDataPtr> Result;
for (auto Item : *It)
{
if (Item.IsError())
{
return false;
}
Result.Add(Item.Current());
}getSubscribeRankingModel
Get a specific subscribe ranking definition by name
Retrieves a single subscribe ranking model by specifying its name. The returned information includes the score range, sort order, and season/entry period configurations. Use this to display the rules of a specific subscribe ranking — for example, showing “Friends High Score — Weekly reset, Higher score = better rank” on a ranking detail screen.
Request
| Type | Condition | Required | Default | Value Limits | Description | |
|---|---|---|---|---|---|---|
| namespaceName | string | ✓ | ~ 128 chars | Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). | ||
| rankingName | string | ✓ | ~ 128 chars | Subscribe Ranking Model name Subscribe Ranking Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). |
Result
| Type | Description | |
|---|---|---|
| item | EzSubscribeRankingModel | Subscribe Ranking Model |
Implementation Example
var domain = gs2.Ranking2.Namespace(
namespaceName: "namespace-0001"
).SubscribeRankingModel(
rankingName: "ranking-0001"
);
var item = await domain.ModelAsync(); var domain = gs2.Ranking2.Namespace(
namespaceName: "namespace-0001"
).SubscribeRankingModel(
rankingName: "ranking-0001"
);
var future = domain.ModelFuture();
yield return future;
var item = future.Result; const auto Domain = Gs2->Ranking2->Namespace(
"namespace-0001" // namespaceName
)->SubscribeRankingModel(
"ranking-0001" // rankingName
);
const auto Future = Domain->Model();
Future->StartSynchronousTask();
if (Future->GetTask().IsError())
{
return false;
}Value change event handling
var domain = gs2.Ranking2.Namespace(
namespaceName: "namespace-0001"
).SubscribeRankingModel(
rankingName: "ranking-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.Ranking2.Namespace(
namespaceName: "namespace-0001"
).SubscribeRankingModel(
rankingName: "ranking-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); const auto Domain = Gs2->Ranking2->Namespace(
"namespace-0001" // namespaceName
)->SubscribeRankingModel(
"ranking-0001" // rankingName
);
// Start event handling
const auto CallbackId = Domain->Subscribe(
[](TSharedPtr<Gs2::Ranking2::Model::FSubscribeRankingModel> 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 triggered when the value stored in the SDK’s local cache changes.
The local cache is updated only when executing the SDK’s API, or by executing stamp sheets via GS2-Distributor with GS2-Gateway notification enabled, or by executing a GS2-JobQueue with GS2-Gateway notification enabled.
Therefore, callbacks will not be invoked if the value is changed in any other way.
listSubscribeRankingModels
Get a list of subscribe ranking definitions
Retrieves all subscribe ranking models registered in this namespace. A subscribe ranking is a friends-only leaderboard — the player only sees scores from users they have subscribed to (followed). This is perfect for friend competitions — for example, “Friends High Score” or “Friends Weekly Challenge” where players compete only against their friends rather than all players in the game. Use this to see what subscribe rankings exist — for example, to display “Friends High Score”, “Friends Speed Clear” as options on a friend ranking screen.
Request
| Type | Condition | Required | Default | Value Limits | Description | |
|---|---|---|---|---|---|---|
| namespaceName | string | ✓ | ~ 128 chars | Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). |
Result
| Type | Description | |
|---|---|---|
| items | List<EzSubscribeRankingModel> | List of Subscribe Ranking Models |
Implementation Example
var domain = gs2.Ranking2.Namespace(
namespaceName: null
);
var items = await domain.SubscribeRankingModelsAsync(
).ToListAsync(); var domain = gs2.Ranking2.Namespace(
namespaceName: null
);
var it = domain.SubscribeRankingModels(
);
List<EzSubscribeRankingModel> items = new List<EzSubscribeRankingModel>();
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->Ranking2->Namespace(
nullptr // namespaceName
);
const auto It = Domain->SubscribeRankingModels(
);
TArray<Gs2::UE5::Ranking2::Model::FEzSubscribeRankingModelPtr> Result;
for (auto Item : *It)
{
if (Item.IsError())
{
return false;
}
Result.Add(Item.Current());
}Value change event handling
var domain = gs2.Ranking2.Namespace(
namespaceName: null
);
// Start event handling
var callbackId = domain.SubscribeSubscribeRankingModels(
() => {
// Called when an element of the list changes.
}
);
// Stop event handling
domain.UnsubscribeSubscribeRankingModels(callbackId); var domain = gs2.Ranking2.Namespace(
namespaceName: null
);
// Start event handling
var callbackId = domain.SubscribeSubscribeRankingModels(
() => {
// Called when an element of the list changes.
}
);
// Stop event handling
domain.UnsubscribeSubscribeRankingModels(callbackId); const auto Domain = Gs2->Ranking2->Namespace(
nullptr // namespaceName
);
// Start event handling
const auto CallbackId = Domain->SubscribeSubscribeRankingModels(
[]() {
// Called when an element of the list changes.
}
);
// Stop event handling
Domain->UnsubscribeSubscribeRankingModels(CallbackId);Warning
This event is triggered when the value stored in the SDK’s local cache changes.
The local cache is updated only when executing the SDK’s API, or by executing stamp sheets via GS2-Distributor with GS2-Gateway notification enabled, or by executing a GS2-JobQueue with GS2-Gateway notification enabled.
Therefore, callbacks will not be invoked if the value is changed in any other way.
getSubscribeRankingScore
Get the player’s submitted score for a specific subscribe ranking
Retrieves the player’s score for a specific subscribe (friend) ranking and season. Use this to display the player’s current score in a specific friend ranking — for example, showing “Your score: 12,000 pts (This week)” on the friend ranking detail screen.
Request
| Type | Condition | Required | Default | Value Limits | Description | |
|---|---|---|---|---|---|---|
| namespaceName | string | ✓ | ~ 128 chars | Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). | ||
| rankingName | string | ✓ | ~ 128 chars | Subscribe Ranking Model name Subscribe Ranking Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). | ||
| season | long | 0 ~ 9223372036854775805 | Season | |||
| gameSession | GameSession | ✓ | GameSession |
Result
| Type | Description | |
|---|---|---|
| item | EzSubscribeRankingScore | Subscribe Ranking Score |
Implementation Example
var domain = gs2.Ranking2.Namespace(
namespaceName: "namespace-0001"
).SubscribeRankingModel(
rankingName: "ranking-0001"
).SubscribeRankingSeason(
season: 0,
userId: "user-0001"
).SubscribeRankingScore(
);
var item = await domain.ModelAsync(); var domain = gs2.Ranking2.Namespace(
namespaceName: "namespace-0001"
).SubscribeRankingModel(
rankingName: "ranking-0001"
).SubscribeRankingSeason(
season: 0,
userId: "user-0001"
).SubscribeRankingScore(
);
var future = domain.ModelFuture();
yield return future;
var item = future.Result; const auto Domain = Gs2->Ranking2->Namespace(
"namespace-0001" // namespaceName
)->SubscribeRankingModel(
"ranking-0001" // rankingName
)->SubscribeRankingSeason(
0, // season
"user-0001" // userId
)->SubscribeRankingScore(
);
const auto Future = Domain->Model();
Future->StartSynchronousTask();
if (Future->GetTask().IsError())
{
return false;
}Value change event handling
var domain = gs2.Ranking2.Namespace(
namespaceName: "namespace-0001"
).SubscribeRankingModel(
rankingName: "ranking-0001"
).SubscribeRankingSeason(
season: 0,
userId: "user-0001"
).SubscribeRankingScore(
);
// 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.Ranking2.Namespace(
namespaceName: "namespace-0001"
).SubscribeRankingModel(
rankingName: "ranking-0001"
).SubscribeRankingSeason(
season: 0,
userId: "user-0001"
).SubscribeRankingScore(
);
// 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); const auto Domain = Gs2->Ranking2->Namespace(
"namespace-0001" // namespaceName
)->SubscribeRankingModel(
"ranking-0001" // rankingName
)->SubscribeRankingSeason(
0, // season
"user-0001" // userId
)->SubscribeRankingScore(
);
// Start event handling
const auto CallbackId = Domain->Subscribe(
[](TSharedPtr<Gs2::Ranking2::Model::FSubscribeRankingScore> 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 triggered when the value stored in the SDK’s local cache changes.
The local cache is updated only when executing the SDK’s API, or by executing stamp sheets via GS2-Distributor with GS2-Gateway notification enabled, or by executing a GS2-JobQueue with GS2-Gateway notification enabled.
Therefore, callbacks will not be invoked if the value is changed in any other way.
listSubscribeRankingScores
Get a list of the player’s submitted scores for subscribe rankings
Retrieves all scores the player has submitted to subscribe (friend) rankings. Use this to display the player’s own scores in friend rankings — for example, showing “Your Friends High Score: 12,000 pts” on a friend ranking overview screen.
Request
| Type | Condition | Required | Default | Value Limits | Description | |
|---|---|---|---|---|---|---|
| namespaceName | string | ✓ | ~ 128 chars | Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). | ||
| rankingName | string | ~ 128 chars | Subscribe Ranking Model name Subscribe Ranking Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). | |||
| gameSession | GameSession | ✓ | GameSession | |||
| pageToken | string | ~ 1024 chars | Token specifying the position from which to start acquiring data | |||
| limit | int | 30 | 1 ~ 1000 | Number of data items to retrieve |
Result
| Type | Description | |
|---|---|---|
| items | List<EzSubscribeRankingScore> | List of Subscribe Ranking Scores |
| nextPageToken | string | Page token to retrieve the rest of the listing |
Implementation Example
var domain = gs2.Ranking2.Namespace(
namespaceName: "namespace-0001"
).SubscribeRankingModel(
rankingName: "ranking-0001"
).SubscribeRankingSeason(
season: 0,
userId: "user-0001"
);
var items = await domain.SubscribeRankingScoresAsync(
).ToListAsync(); var domain = gs2.Ranking2.Namespace(
namespaceName: "namespace-0001"
).SubscribeRankingModel(
rankingName: "ranking-0001"
).SubscribeRankingSeason(
season: 0,
userId: "user-0001"
);
var it = domain.SubscribeRankingScores(
);
List<EzSubscribeRankingScore> items = new List<EzSubscribeRankingScore>();
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->Ranking2->Namespace(
"namespace-0001" // namespaceName
)->SubscribeRankingModel(
"ranking-0001" // rankingName
)->SubscribeRankingSeason(
0, // season
"user-0001" // userId
);
const auto It = Domain->SubscribeRankingScores(
);
TArray<Gs2::UE5::Ranking2::Model::FEzSubscribeRankingScorePtr> Result;
for (auto Item : *It)
{
if (Item.IsError())
{
return false;
}
Result.Add(Item.Current());
}Value change event handling
var domain = gs2.Ranking2.Namespace(
namespaceName: "namespace-0001"
).SubscribeRankingModel(
rankingName: "ranking-0001"
).SubscribeRankingSeason(
season: 0,
userId: "user-0001"
);
// Start event handling
var callbackId = domain.SubscribeSubscribeRankingScores(
() => {
// Called when an element of the list changes.
}
);
// Stop event handling
domain.UnsubscribeSubscribeRankingScores(callbackId); var domain = gs2.Ranking2.Namespace(
namespaceName: "namespace-0001"
).SubscribeRankingModel(
rankingName: "ranking-0001"
).SubscribeRankingSeason(
season: 0,
userId: "user-0001"
);
// Start event handling
var callbackId = domain.SubscribeSubscribeRankingScores(
() => {
// Called when an element of the list changes.
}
);
// Stop event handling
domain.UnsubscribeSubscribeRankingScores(callbackId); const auto Domain = Gs2->Ranking2->Namespace(
"namespace-0001" // namespaceName
)->SubscribeRankingModel(
"ranking-0001" // rankingName
)->SubscribeRankingSeason(
0, // season
"user-0001" // userId
);
// Start event handling
const auto CallbackId = Domain->SubscribeSubscribeRankingScores(
[]() {
// Called when an element of the list changes.
}
);
// Stop event handling
Domain->UnsubscribeSubscribeRankingScores(CallbackId);Warning
This event is triggered when the value stored in the SDK’s local cache changes.
The local cache is updated only when executing the SDK’s API, or by executing stamp sheets via GS2-Distributor with GS2-Gateway notification enabled, or by executing a GS2-JobQueue with GS2-Gateway notification enabled.
Therefore, callbacks will not be invoked if the value is changed in any other way.
putSubscribeRanking
Submit a score to a subscribe ranking
Registers the player’s score to the specified subscribe (friend) ranking. You can also attach metadata. This score will appear on the friend leaderboards of all users who have subscribed to (followed) this player. Use this after the player completes a scored activity — for example, after clearing a stage, submit the score to the “Friends High Score” ranking so the player’s friends can see it.
Request
| Type | Condition | Required | Default | Value Limits | Description | |
|---|---|---|---|---|---|---|
| namespaceName | string | ✓ | ~ 128 chars | Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). | ||
| rankingName | string | ✓ | ~ 128 chars | Subscribe Ranking Model name Subscribe Ranking Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). | ||
| gameSession | GameSession | ✓ | GameSession | |||
| score | long | ✓ | 0 ~ 9223372036854775805 | Score | ||
| metadata | string | ~ 512 chars | Metadata Arbitrary values can be set in the metadata. Since they do not affect GS2’s behavior, they can be used to store information used in the game. |
Result
| Type | Description | |
|---|---|---|
| item | EzSubscribeRankingScore | Registered Subscribe Ranking Score |
Implementation Example
var domain = gs2.Ranking2.Namespace(
namespaceName: "namespace-0001"
).SubscribeRankingModel(
rankingName: "ranking-0001"
).SubscribeRankingSeason(
season: 0,
userId: "user-0001"
);
var result = await domain.PutSubscribeRankingAsync(
score: 100L,
metadata: null
);
var item = await result.ModelAsync(); var domain = gs2.Ranking2.Namespace(
namespaceName: "namespace-0001"
).SubscribeRankingModel(
rankingName: "ranking-0001"
).SubscribeRankingSeason(
season: 0,
userId: "user-0001"
);
var future = domain.PutSubscribeRankingFuture(
score: 100L,
metadata: null
);
yield return future;
if (future.Error != null)
{
onError.Invoke(future.Error, null);
yield break;
}
var future2 = future.Result.ModelFuture();
yield return future2;
if (future2.Error != null)
{
onError.Invoke(future2.Error, null);
yield break;
}
var result = future2.Result; const auto Domain = Gs2->Ranking2->Namespace(
"namespace-0001" // namespaceName
)->SubscribeRankingModel(
"ranking-0001" // rankingName
)->SubscribeRankingSeason(
0, // season
"user-0001" // userId
);
const auto Future = Domain->PutSubscribeRanking(
100L // score
// metadata
);
Future->StartSynchronousTask();
if (Future->GetTask().IsError())
{
return false;
}
// obtain changed values / result values
const auto Future2 = Future->GetTask().Result()->Model();
Future2->StartSynchronousTask();
if (Future2->GetTask().IsError())
{
return Future2->GetTask().Error();
}
const auto Result = Future2->GetTask().Result();