GS2-Ranking Deploy/CDK Reference

The template format used when creating stacks with GS2-Deploy, and implementation examples of template output in various languages using CDK

Entities

Resources targeted by the Deploy operation

Namespace

A Namespace allows multiple independent instances of the same service within a single project by separating data spaces and usage contexts. Each GS2 service is managed on a per-namespace basis. Even when using the same service, if the namespace differs, the data is treated as a completely independent data space.

Therefore, you must create a namespace before you can start using each service.

Request

Resource creation and update requests

	Type	Required	Value Limits	Description
name	string	✓	~ 128 chars	Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.).
description	string		~ 1024 chars	Description
transactionSetting	TransactionSetting			Transaction Setting Configuration for controlling how transactions are processed when executing ranking operations.
logSetting	LogSetting			Log Setting Configuration for outputting ranking-related operation logs to GS2-Log. When configured, actions such as score registration, ranking retrieval, and subscription changes are recorded for analysis and auditing.

GetAttr

Resource creation results that can be retrieved using the !GetAttr tag

	Type	Description
Item	Namespace	Namespace created

Implementation Example

Type: GS2::Ranking::Namespace
Properties:
  Name: namespace-0001
  Description: null
  TransactionSetting: null
  LogSetting: 
    LoggingNamespaceId: grn:gs2:ap-northeast-1:YourOwnerId:log:namespace-0001

import (
    "github.com/gs2io/gs2-golang-cdk/core"
    "github.com/gs2io/gs2-golang-cdk/ranking"
)


SampleStack := core.NewStack()
ranking.NewNamespace(
    &SampleStack,
    "namespace-0001",
    ranking.NamespaceOptions{
        LogSetting: &core.LogSetting{
            LoggingNamespaceId: "grn:gs2:ap-northeast-1:YourOwnerId:log:namespace-0001",
        },
    },
)

println(SampleStack.Yaml())  // Generate Template

class SampleStack extends \Gs2Cdk\Core\Model\Stack
{
    function __construct() {
        parent::__construct();
        new \Gs2Cdk\Ranking\Model\Namespace_(
            stack: $this,
            name: "namespace-0001",
            options: new \Gs2Cdk\Ranking\Model\Options\NamespaceOptions(
                logSetting: new \Gs2Cdk\Core\Model\LogSetting(
                    loggingNamespaceId: "grn:gs2:ap-northeast-1:YourOwnerId:log:namespace-0001"
                )
            )
        );
    }
}

print((new SampleStack())->yaml());  // Generate Template

class SampleStack extends io.gs2.cdk.core.model.Stack
{
    public SampleStack() {
        super();
        new io.gs2.cdk.ranking.model.Namespace(
                this,
                "namespace-0001",
                new io.gs2.cdk.ranking.model.options.NamespaceOptions()
                        .withLogSetting(new io.gs2.cdk.core.model.LogSetting(
                            "grn:gs2:ap-northeast-1:YourOwnerId:log:namespace-0001"
                        ))
        );
    }
}

System.out.println(new SampleStack().yaml());  // Generate Template

public class SampleStack : Gs2Cdk.Core.Model.Stack
{
    public SampleStack() {
        new Gs2Cdk.Gs2Ranking.Model.Namespace(
            stack: this,
            name: "namespace-0001",
            options: new Gs2Cdk.Gs2Ranking.Model.Options.NamespaceOptions
            {
                logSetting = new Gs2Cdk.Core.Model.LogSetting(
                    loggingNamespaceId: "grn:gs2:ap-northeast-1:YourOwnerId:log:namespace-0001"
                )
            }
        );
    }
}

Debug.Log(new SampleStack().Yaml());  // Generate Template

import core from "@/gs2cdk/core";
import ranking from "@/gs2cdk/ranking";

class SampleStack extends core.Stack
{
    public constructor() {
        super();
        new ranking.model.Namespace(
            this,
            "namespace-0001",
            {
                logSetting: new core.LogSetting(
                    "grn:gs2:ap-northeast-1:YourOwnerId:log:namespace-0001"
                )
            }
        );
    }
}

console.log(new SampleStack().yaml());  // Generate Template

from gs2_cdk import Stack, core, ranking

class SampleStack(Stack):

    def __init__(self):
        super().__init__()
        ranking.Namespace(
            stack=self,
            name='namespace-0001',
            options=ranking.NamespaceOptions(
                log_setting=core.LogSetting(
                    logging_namespace_id='grn:gs2:ap-northeast-1:YourOwnerId:log:namespace-0001',
                ),
            ),
        )

print(SampleStack().yaml())  # Generate Template

TransactionSetting

Transaction Setting

Transaction Setting controls how transactions are executed, including their consistency, asynchronous processing, and conflict avoidance mechanisms. Combining features like AutoRun, AtomicCommit, asynchronous execution using GS2-Distributor, batch application of script results, and asynchronous Acquire Actions via GS2-JobQueue enables robust transaction management tailored to game logic.

	Type	Condition	Default	Value Limits	Description
enableAutoRun	bool		false		Whether to automatically execute issued transactions on the server side
enableAtomicCommit	bool	{enableAutoRun} == true	false		Whether to commit the execution of transactions atomically * Applicable only if enableAutoRun is true
transactionUseDistributor	bool	{enableAtomicCommit} == true	false		Whether to execute transactions asynchronously * Applicable only if enableAtomicCommit is true
commitScriptResultInUseDistributor	bool	{transactionUseDistributor} == true	false		Whether to execute the commit processing of the script result asynchronously * Applicable only if transactionUseDistributor is true
acquireActionUseJobQueue	bool	{enableAtomicCommit} == true	false		Whether to use GS2-JobQueue to execute the acquire action * Applicable only if enableAtomicCommit is true
distributorNamespaceId	string		“grn:gs2:{region}:{ownerId}:distributor:default”	~ 1024 chars	GS2-Distributor Namespace GRN used to execute transactions
queueNamespaceId	string		“grn:gs2:{region}:{ownerId}:queue:default”	~ 1024 chars	GS2-JobQueue Namespace GRN used to execute transactions

LogSetting

Log Output Setting

Log Output Setting defines how log data is exported. This type holds the GS2-Log namespace identifier (Namespace ID) used to export log data. Specify the GS2-Log namespace where log data is collected and stored in the GRN format for the Log Namespace ID (loggingNamespaceId). Configuring this setting ensures that log data for API requests and responses occurring within the specified namespace is output to the target GS2-Log namespace. GS2-Log provides real-time logs that can be used for system monitoring, analysis, debugging, and other operational purposes.

	Type	Condition	Required	Default	Value Limits	Description
loggingNamespaceId	string		✓		~ 1024 chars	GS2-Log namespace GRN to output logs Must be specified in GRN format starting with “grn:gs2:”.

CurrentRankingMaster

Currently active Ranking Model master data

This master data describes the definitions of Ranking Models currently active within the namespace. Master data describing the currently valid ranking model definitions within the namespace GS2 uses JSON format files for managing master data. By uploading these files, the master data settings are updated on the server.

To create JSON files, GS2 provides a master data editor within the management console. Additionally, you can create tools better suited for game operations and export JSON files in the appropriate format.

Note

Please refer to Master Data Reference of GS2-Ranking for the JSON file format.

Request

Resource creation and update requests

Type

Condition

Required

Default

Value Limits

Description

namespaceName

string

✓

~ 128 chars

Namespace name

Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.).

mode

String Enum
enum {
“direct”,
“preUpload”
}

“direct”

Update mode

Definition	Description
“direct”	Directly update master data
“preUpload”	Upload master data and then update

settings

string

{mode} == “direct”

✓*

~ 5242880 chars

Master Data

* Required if mode is “direct”

uploadToken

string

{mode} == “preUpload”

✓*

~ 1024 chars

Token obtained by pre-upload

Used to apply the uploaded master data.

* Required if mode is “preUpload”

GetAttr

Resource creation results that can be retrieved using the !GetAttr tag

	Type	Description
Item	CurrentRankingMaster	Updated master data of the currently active Ranking Models

Implementation Example

Type: GS2::Ranking::CurrentRankingMaster
Properties:
  NamespaceName: namespace-0001
  Mode: direct
  Settings: {
    "version": "2019-09-17",
    "categories": []
    
  }
  UploadToken: null

import (
    "github.com/gs2io/gs2-golang-cdk/core"
    "github.com/gs2io/gs2-golang-cdk/ranking"
)


SampleStack := core.NewStack()
ranking.NewNamespace(
    &SampleStack,
    "namespace-0001",
    ranking.NamespaceOptions{},
).MasterData(
    []ranking.CategoryModel{
    },
)

println(SampleStack.Yaml())  // Generate Template

class SampleStack extends \Gs2Cdk\Core\Model\Stack
{
    function __construct() {
        parent::__construct();
        (new \Gs2Cdk\Ranking\Model\Namespace_(
            stack: $this,
            name: "namespace-0001"
        ))->masterData(
            [
            ]
        );
    }
}

print((new SampleStack())->yaml());  // Generate Template

class SampleStack extends io.gs2.cdk.core.model.Stack
{
    public SampleStack() {
        super();
        new io.gs2.cdk.ranking.model.Namespace(
            this,
            "namespace-0001"
        ).masterData(
            Arrays.asList(
            )
        );
    }
}

System.out.println(new SampleStack().yaml());  // Generate Template

public class SampleStack : Gs2Cdk.Core.Model.Stack
{
    public SampleStack() {
        new Gs2Cdk.Gs2Ranking.Model.Namespace(
            stack: this,
            name: "namespace-0001"
        ).MasterData(
            new Gs2Cdk.Gs2Ranking.Model.CategoryModel[] {
            }
        );
    }
}

Debug.Log(new SampleStack().Yaml());  // Generate Template

import core from "@/gs2cdk/core";
import ranking from "@/gs2cdk/ranking";

class SampleStack extends core.Stack
{
    public constructor() {
        super();
        new ranking.model.Namespace(
            this,
            "namespace-0001",
        ).masterData(
            [
            ]
        );
    }
}

console.log(new SampleStack().yaml());  // Generate Template

from gs2_cdk import Stack, core, ranking

class SampleStack(Stack):

    def __init__(self):
        super().__init__()
        ranking.Namespace(
            stack=self,
            name="namespace-0001",
        ).master_data(
            categories=[
            ],
        )

print(SampleStack().yaml())  # Generate Template

CategoryModel

Category Model

Different rankings can be created for different categories.

Categories can have a minimum and maximum score that can be registered, and scores outside of that range are discarded. When calculating rankings, it is possible to set whether the scores are to be ranked in ascending or descending order, with the smallest scores being ranked higher (ascending order) or the largest scores being ranked lower (descending order).

You can select global or scope as the type of ranking. Global is a ranking where all players see the same results, and Scope is a ranking where each game player has a different result, such as a ranking among friends or a ranking in a guild.

For global ranking, you can set the ranking interval from 15 minutes to 24 hours for each category. Scope rankings reflect the calculate results in real time.

The ranking data has a setting called “generation,” and the registered scores can be reset by changing the generation.

Type

Condition

Required

Default

Value Limits

Description

categoryModelId

string

~ 1024 chars

Category Model GRN

* Set automatically by the server

name

string

✓

~ 128 chars

Category Model name

Category 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.

minimumValue

long

0 ~ 9223372036854775805

Minimum Value

The minimum score value that can be registered in this category.
Scores below this threshold are rejected at registration time. If not set, there is no lower bound.

maximumValue

long

0 ~ 9223372036854775805

Maximum Value

The maximum score value that can be registered in this category.
Scores above this threshold are rejected at registration time. If not set, there is no upper bound.

sum

bool

false

Sum Mode

When enabled, newly registered scores are added to the user’s existing score total rather than replacing it.
The ranking is then based on the accumulated total. When disabled, each score registration is treated as an independent entry.

orderDirection

String Enum
enum {
“asc”,
“desc”
}

✓

Order Direction

Determines the sort order for ranking calculation.
“asc” (ascending) ranks lower scores higher, suitable for time-based or golf-style rankings.
“desc” (descending) ranks higher scores higher, suitable for point-based or high-score rankings.

Definition	Description
“asc”	ascending-order
“desc”	descending-order

scope

String Enum
enum {
“global”,
“scoped”
}

✓

Scope

The type of ranking for this category.
“global” creates a single leaderboard shared by all players, recalculated at configured intervals (batch processing).
“scoped” creates per-user leaderboards based on subscribed players (e.g., friends or guild members), with real-time score reflection.

Definition	Description
“global”	Global
“scoped”	Scoped

globalRankingSetting

GlobalRankingSetting

{scope} == “global”

✓*

Global Ranking Setting

Configuration specific to global ranking mode, including calculation interval, fixed timing, score uniqueness, generation management, and additional time-windowed scopes.
Only applicable when scope is set to “global”.

* Required if scope is “global”

entryPeriodEventId

string

~ 1024 chars

Entry Period Event ID

GRN of a GS2-Schedule event that defines the time window during which score registration is accepted.
Outside this period, score submission requests are rejected. If not set, scores can be registered at any time.

accessPeriodEventId

string

~ 1024 chars

Access Period Event ID

GRN of a GS2-Schedule event that defines the time window during which ranking data can be viewed.
Outside this period, ranking retrieval requests are rejected. If not set, rankings can be accessed at any time.

Scope

Aggregation Scope

Defines an additional time-windowed aggregation scope for Global Ranking mode. Normally, global ranking is calculated for all registered scores regardless of when they were submitted. By adding scopes, you can create separate rankings that only consider scores registered within a specified number of days, enabling daily, weekly, or monthly leaderboards alongside the all-time ranking.

	Type	Condition	Required	Default	Value Limits	Description
name	string		✓		~ 128 chars	Scope Name A unique name identifying this aggregation scope within the category. Used to distinguish between multiple time-windowed ranking boards (e.g., “daily”, “weekly”). Maximum 128 characters.
targetDays	long		✓		1 ~ 365	Target Days The number of days to include in the aggregation window. Only scores registered within this number of days from the current time are considered for the scoped ranking. Range: 1-365 days.

GlobalRankingSetting

Global Ranking Setting

Global is a ranking where all players see the same results. The ranking interval can be set from 15 minutes to 24 hours.

The ranking data has a setting called “generation,” and the registered scores can be reset by changing the generation.

	Type	Required	Default	Value Limits	Description
uniqueByUserId	bool		true		Unique By User ID When enabled, only one score per user ID is kept in the ranking. If a user submits a new score, it replaces the previous one (keeping the better score based on the sort direction). When disabled, multiple score entries from the same user are allowed, enabling sum-mode or multi-entry competition.
calculateIntervalMinutes	int	✓		15 ~ 1440	Calculate Interval Minutes The interval in minutes between successive ranking recalculations. The system periodically recalculates the global ranking based on all registered scores at this interval. Range: 15 to 1440 minutes (15 minutes to 24 hours).
calculateFixedTiming	FixedTiming				Calculate Fixed Timing Specifies a fixed time of day (UTC) at which ranking recalculation starts. If not set, recalculation occurs at regular intervals from an unspecified base time. Setting this ensures recalculations happen at a predictable, consistent time each day.
additionalScopes	List<Scope>			0 ~ 10 items	Additional Scopes A list of additional time-windowed aggregation scopes. Each scope defines a separate ranking that only considers scores registered within a specified number of days. This enables creating daily, weekly, or monthly leaderboards alongside the all-time global ranking. Maximum 10 scopes.
ignoreUserIds	List<string>			0 ~ 10000 items	Ignore User IDs A list of user IDs whose scores should be excluded from ranking calculation. Useful for filtering out test accounts, administrator accounts, or known cheaters from the leaderboard. Maximum 10,000 entries.
generation	string			~ 256 chars	Generation An arbitrary string representing the current ranking generation. Changing this value effectively resets all registered scores, as scores from a previous generation are no longer included in ranking calculations. Useful for implementing seasonal resets or periodic ranking resets. Maximum 256 characters.

FixedTiming

Fixed Timing

Specifies the fixed time of day at which global ranking calculations start. Without this setting, ranking calculation occurs at regular intervals from an unspecified base time. By specifying a fixed hour and minute, you can ensure that ranking recalculation always begins at a predictable time (in UTC), such as midnight or a specific hour.

	Type	Condition	Required	Default	Value Limits	Description
hour	int				0 ~ 23	Hour The hour (UTC) at which ranking calculation starts. Specified as an integer from 0 to 23.
minute	int				0 ~ 59	Minute The minute at which ranking calculation starts within the specified hour. Specified as an integer from 0 to 59.