GS2-Matchmaking GS2-Deploy/CDK リファレンス

エンティティ

Namespace

ネームスペース

ネームスペースは一つのプロジェクトで同じサービスを異なる用途で複数利用できるようにするための仕組みです。
GS2 のサービスは基本的にネームスペースというレイヤーがあり、ネームスペースが異なれば同じサービスでもまったく別のデータ空間として取り扱われます。

そのため、各サービスの利用を開始するにあたってネームスペースを作成する必要があります。

	型	必須	デフォルト	値の制限	説明
name	string	✓		~ 128文字	ネームスペース名
description	string			~ 1024文字	説明文
enableRating	bool	✓	false		レーティング計算機能を使用するか
enableDisconnectDetection	string	✓	“disable”	~ 128文字	マッチメイキング中プレイヤーの切断検知
disconnectDetectionTimeoutSeconds	int	{enableDisconnectDetection} == “enable”		15 ~ 600	マッチメイキング中にプレイヤーを切断と見なすまでの待機時間（秒）
createGatheringTriggerType	string	✓		~ 128文字	ギャザリング新規作成時のアクション
createGatheringTriggerRealtimeNamespaceId	string	{createGatheringTriggerType} == “gs2_realtime”		~ 1024文字	ギャザリング作成時にルームを作成する GS2-Realtime のネームスペース
createGatheringTriggerScriptId	string	{createGatheringTriggerType} == “gs2_script”		~ 1024文字	ギャザリング作成時に実行される GS2-Script のスクリプト
completeMatchmakingTriggerType	string	✓		~ 128文字	マッチメイキング完了時のアクション
completeMatchmakingTriggerRealtimeNamespaceId	string	{completeMatchmakingTriggerType} == “gs2_realtime”		~ 1024文字	マッチメイキング完了時にルームを作成する GS2-Realtime のネームスペース
completeMatchmakingTriggerScriptId	string	{completeMatchmakingTriggerType} == “gs2_script”		~ 1024文字	マッチメイキング完了時に実行される GS2-Script のスクリプト
enableCollaborateSeasonRating	string	✓	“disable”	~ 128文字	GS2-SeasonRating との連携を有効にするか
collaborateSeasonRatingNamespaceId	string	{enableCollaborateSeasonRating} == “enable”		~ 1024文字	マッチメイキング完了時にセッションを作成する GS2-SeasonRating のネームスペース
collaborateSeasonRatingTtl	int	{enableCollaborateSeasonRating} == “enable”	60	60 ~ 7200	GS2-SeasonRating の結果を受け付ける最大時間(秒)
changeRatingScript	ScriptSetting				レーティング値が変化した時に実行するスクリプト
joinNotification	NotificationSetting				ギャザリングに新規プレイヤーが参加したときのプッシュ通知
leaveNotification	NotificationSetting				ギャザリングからプレイヤーが離脱したときのプッシュ通知
completeNotification	NotificationSetting				マッチメイキングが完了したときのプッシュ通知
changeRatingNotification	NotificationSetting				レーティングの値が変動したときのプッシュ通知
logSetting	LogSetting				ログの出力設定

enableDisconnectDetection に指定する列挙型の定義

定義	説明
disable	無効
enable	有効

createGatheringTriggerType に指定する列挙型の定義

定義	説明
none	なし
gs2_realtime	GS2-Realtime のルーム作成
gs2_script	GS2-Script の実行

completeMatchmakingTriggerType に指定する列挙型の定義

定義	説明
none	なし
gs2_realtime	GS2-Realtime のルーム作成
gs2_script	GS2-Script の実行

enableCollaborateSeasonRating に指定する列挙型の定義

定義	説明
enable	有効
disable	無効

GetAttr

	型	説明
Item	Namespace	作成したネームスペース

実装例

Type: GS2::Matchmaking::Namespace
Properties:
  Name: namespace1
  Description: null
  EnableRating: true
  EnableDisconnectDetection: null
  DisconnectDetectionTimeoutSeconds: null
  CreateGatheringTriggerType: none
  CreateGatheringTriggerRealtimeNamespaceId: null
  CreateGatheringTriggerScriptId: null
  CompleteMatchmakingTriggerType: none
  CompleteMatchmakingTriggerRealtimeNamespaceId: null
  CompleteMatchmakingTriggerScriptId: null
  EnableCollaborateSeasonRating: disable
  CollaborateSeasonRatingNamespaceId: grn:gs2:ap-northeast-1:YourOwnerId:experience:namespace-0001
  CollaborateSeasonRatingTtl: 60
  ChangeRatingScript: null
  JoinNotification: null
  LeaveNotification: null
  CompleteNotification: null
  ChangeRatingNotification: null
  LogSetting: 
    LoggingNamespaceId: grn:gs2:ap-northeast-1:YourOwnerId:log:namespace-0001

from gs2_cdk import Stack, core, matchmaking

class SampleStack(Stack):

    def __init__(self):
        super().__init__()
        matchmaking.Namespace(
            stack=self,
            name="namespace-0001",
            create_gathering_trigger_type=matchmaking.NamespaceCreateGatheringTriggerType.NONE,
            complete_matchmaking_trigger_type=matchmaking.NamespaceCompleteMatchmakingTriggerType.NONE,
            options=matchmaking.NamespaceOptions(
                enable_rating=True,
                enable_collaborate_season_rating='disable',
                collaborate_season_rating_namespace_id='grn:gs2:ap-northeast-1:YourOwnerId:experience:namespace-0001',
                collaborate_season_rating_ttl=60,
                log_setting=core.LogSetting(
                    logging_namespace_id='grn:gs2:ap-northeast-1:YourOwnerId:log:namespace-0001',
                ),
            ),
        )

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

class SampleStack extends \Gs2Cdk\Core\Model\Stack
{
    function __construct() {
        parent::__construct();
        new \Gs2Cdk\Matchmaking\Model\Namespace_(
            stack: $this,
            name: "namespace-0001",
            createGatheringTriggerType: \Gs2Cdk\Matchmaking\Model\Enum\NamespaceCreateGatheringTriggerType::NONE,
            completeMatchmakingTriggerType: \Gs2Cdk\Matchmaking\Model\Enum\NamespaceCompleteMatchmakingTriggerType::NONE,
            options: new \Gs2Cdk\Matchmaking\Model\Options\NamespaceOptions(
                enableRating: True,
                enableCollaborateSeasonRating: "disable",
                collaborateSeasonRatingNamespaceId: "grn:gs2:ap-northeast-1:YourOwnerId:experience:namespace-0001",
                collaborateSeasonRatingTtl: 60,
                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.matchmaking.model.Namespace(
            this,
            "namespace-0001",
            io.gs2.cdk.matchmaking.model.enums.NamespaceCreateGatheringTriggerType.NONE,
            io.gs2.cdk.matchmaking.model.enums.NamespaceCompleteMatchmakingTriggerType.NONE,
            new io.gs2.cdk.matchmaking.model.options.NamespaceOptions() {
                {
                    enableRating = true;
                    enableCollaborateSeasonRating = "disable";
                    collaborateSeasonRatingNamespaceId = "grn:gs2:ap-northeast-1:YourOwnerId:experience:namespace-0001";
                    collaborateSeasonRatingTtl = 60;
                    logSetting = new io.gs2.cdk.core.model.LogSetting(
                        loggingNamespaceId = "grn:gs2:ap-northeast-1:YourOwnerId:log:namespace-0001"
                    );
                }
            }
        );
    }
}

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

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

class SampleStack extends core.Stack
{
    public constructor() {
        super();
        new matchmaking.model.Namespace(
            this,
            "namespace-0001",
            matchmaking.model.NamespaceCreateGatheringTriggerType.NONE,
            matchmaking.model.NamespaceCompleteMatchmakingTriggerType.NONE,
            {
                enableRating: true,
                enableCollaborateSeasonRating: "disable",
                collaborateSeasonRatingNamespaceId: "grn:gs2:ap-northeast-1:YourOwnerId:experience:namespace-0001",
                collaborateSeasonRatingTtl: 60,
                logSetting: new core.LogSetting(
                    "grn:gs2:ap-northeast-1:YourOwnerId:log:namespace-0001"
                )
            }
        );
    }
}

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

public class SampleStack : Gs2Cdk.Core.Model.Stack
{
    public SampleStack() {
        new Gs2Cdk.Gs2Matchmaking.Model.Namespace(
            this,
            "namespace-0001",
            Gs2Cdk.Gs2Matchmaking.Model.Enums.NamespaceCreateGatheringTriggerType.None,
            Gs2Cdk.Gs2Matchmaking.Model.Enums.NamespaceCompleteMatchmakingTriggerType.None,
            new Gs2Cdk.Gs2Matchmaking.Model.Options.NamespaceOptions {
                enableRating = true,
                enableCollaborateSeasonRating = "disable",
                collaborateSeasonRatingNamespaceId = "grn:gs2:ap-northeast-1:YourOwnerId:experience:namespace-0001",
                collaborateSeasonRatingTtl = 60,
                logSetting = new Gs2Cdk.Core.Model.LogSetting(
                    LoggingNamespaceId = "grn:gs2:ap-northeast-1:YourOwnerId:log:namespace-0001"
                )
            }
        );
    }
}

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

CurrentModelMaster

現在有効なマスターデータ

GS2ではマスターデータの管理にJSON形式のファイルを使用します。
ファイルをアップロードすることで、実際にサーバーに設定を反映することができます。

JSONファイルを作成する方法として、マネージメントコンソール上でのマスターデータエディタを提供していますが
よりゲームの運営に相応しいツールを作成し、適切なフォーマットのJSONファイルを書き出すことでもサービスを利用可能です。

Note

JSONファイルの形式については GS2-Matchmaking マスターデータリファレンスをご参照ください。

	型	必須	デフォルト	値の制限	説明
namespaceName	string	✓		~ 128文字	ネームスペース名
settings	string	✓		~ 5242880文字	マスターデータ

GetAttr

	型	説明
Item	CurrentModelMaster	更新した現在有効なレーティングマスター

実装例

Type: GS2::Matchmaking::CurrentModelMaster
Properties:
  NamespaceName: namespace1
  Settings: {
    "version": "2020-06-24",
    "ratingModels": [
      {
        "name": "rating-0001",
        "volatility": 100,
        "metadata": "RATING_0001"
      },
      {
        "name": "rating-0002",
        "volatility": 150,
        "metadata": "RATING_0002"
      }
    ],
    "seasonModels": 
    
  }

from gs2_cdk import Stack, core, matchmaking

class SampleStack(Stack):

    def __init__(self):
        super().__init__()
        matchmaking.Namespace(
            stack=self,
            # 省略
        ).master_data(
            rating_models=[
                matchmaking.RatingModel(
                    name='rating-0001',
                    volatility=100,
                    options=matchmaking.RatingModelOptions(
                        metadata='RATING_0001',
                    ),
                ),
                matchmaking.RatingModel(
                    name='rating-0002',
                    volatility=150,
                    options=matchmaking.RatingModelOptions(
                        metadata='RATING_0002',
                    ),
                ),
            ],
            season_models=[
            ],
        )

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

class SampleStack extends \Gs2Cdk\Core\Model\Stack
{
    function __construct() {
        parent::__construct();
        (new \Gs2Cdk\Matchmaking\Model\Namespace_(
            stack: $this,
            // 省略
        ))->masterData(
            [
                new \Gs2Cdk\Matchmaking\Model\RatingModel(
                    name:"rating-0001",
                    volatility:100,
                    options: new \Gs2Cdk\Matchmaking\Model\Options\RatingModelOptions(
                        metadata:"RATING_0001"
                    )
                ),
                new \Gs2Cdk\Matchmaking\Model\RatingModel(
                    name:"rating-0002",
                    volatility:150,
                    options: new \Gs2Cdk\Matchmaking\Model\Options\RatingModelOptions(
                        metadata:"RATING_0002"
                    )
                )
            ],
            [
            ]
        );
    }
}

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

class SampleStack extends io.gs2.cdk.core.model.Stack
{
    public SampleStack() {
        super();
        new io.gs2.cdk.matchmaking.model.Namespace(
            this,
            // 省略
        ).masterData(
            Arrays.asList(
                new io.gs2.cdk.matchmaking.model.RatingModel(
                    "rating-0001",
                    100,
                    new io.gs2.cdk.matchmaking.model.options.RatingModelOptions() {
                        {
                            metadata: "RATING_0001";
                        }
                    }
                ),
                new io.gs2.cdk.matchmaking.model.RatingModel(
                    "rating-0002",
                    150,
                    new io.gs2.cdk.matchmaking.model.options.RatingModelOptions() {
                        {
                            metadata: "RATING_0002";
                        }
                    }
                )
            ),
            Arrays.asList(
            )
        );
    }
}

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

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

class SampleStack extends core.Stack
{
    public constructor() {
        super();
        new matchmaking.model.Namespace(
            this,
            // 省略
        ).masterData(
            [
                new matchmaking.model.RatingModel(
                    "rating-0001",
                    100,
                    {
                        metadata: "RATING_0001"
                    }
                ),
                new matchmaking.model.RatingModel(
                    "rating-0002",
                    150,
                    {
                        metadata: "RATING_0002"
                    }
                )
            ],
            [
            ]
        );
    }
}

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

public class SampleStack : Gs2Cdk.Core.Model.Stack
{
    public SampleStack() {
        new Gs2Cdk.Gs2Matchmaking.Model.Namespace(
            this,
            // 省略
        ).MasterData(
            new [] {
                new Gs2Cdk.Gs2Matchmaking.Model.RatingModel(
                    "rating-0001",
                    100,
                    new Gs2Cdk.Gs2Matchmaking.Model.Options.RatingModelOptions {
                        metadata = "RATING_0001"
                    }
                ),
                new Gs2Cdk.Gs2Matchmaking.Model.RatingModel(
                    "rating-0002",
                    150,
                    new Gs2Cdk.Gs2Matchmaking.Model.Options.RatingModelOptions {
                        metadata = "RATING_0002"
                    }
                )
            },
            new [] {
            }
        );
    }
}

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

ScriptSetting

スクリプト設定

GS2 ではマイクロサービスのイベントに関連づけて、カスタムスクリプトを実行することができます。
このモデルは、スクリプトの実行をトリガーするための設定を保持します。

スクリプトの実行方式は大きく2種類あり、それは「同期実行」と「非同期実行」です。
同期実行は、スクリプトの実行が完了するまで処理がブロックされます。
かわりに、スクリプトの実行結果を使ってAPIの実行を止めたり、APIの結果を改ざんすることができます。

一方、非同期実行は、スクリプトの実行が完了するまで処理がブロックされません。
かわりに、スクリプトの実行結果を使ってAPIの実行を止めたり、APIの結果を改ざんすることはできません。
しかし、非同期実行は、スクリプトの実行が完了するまで処理がブロックされないため、APIの応答に影響を与えないため、原則非同期実行を使用することをおすすめします。

非同期実行には実行方式が2種類あり、GS2-Script と Amazon EventBridge があります。
Amazon EventBridge を使用することで、Lua 以外の言語で処理を記述することができます。

	型	必須	デフォルト	値の制限	説明
triggerScriptId	string			~ 1024文字	スクリプトGRN
doneTriggerTargetType	enum { “none”, “gs2_script”, “aws” }	✓	“none”	~ 128文字	完了通知の通知先
doneTriggerScriptId	string	{doneTriggerTargetType} == “gs2_script”		~ 1024文字	スクリプトGRN
doneTriggerQueueNamespaceId	string	{doneTriggerTargetType} == “gs2_script”		~ 1024文字	ネームスペースGRN

doneTriggerTargetType に指定する列挙型の定義

定義	説明
none	なし
gs2_script	GS2-Script
aws	Amazon EventBridge

NotificationSetting

プッシュ通知に関する設定

GS2 のマイクロサービス内で何らかのイベントが発生した際に、プッシュ通知を送信するための設定です。
ここでいうプッシュ通知は GS2-Gateway の提供する WebSocket インターフェースを経由した処理であり、スマートフォンのプッシュ通知とは性質が異なります。
たとえば、マッチメイキングが完了した時やフレンドリクエストが届いた時など、ゲームクライアントの操作とは関係なく状態が変化した際に GS2-Gateway を経由してプッシュ通知をすることで、ゲームクライアントは状態の変化を検知することができます。

GS2-Gateway のプッシュ通知は通知先のデバイスがオフラインだった時に追加の処理としてモバイルプッシュ通知を送信できます。
モバイルプッシュ通知をうまく利用すれば、マッチメイキング中にゲームを終了しても、モバイルプッシュ通知を使用してプレイヤーに通知し、ゲームに戻ってくるフローを実現できる可能性があります。

	型	必須	デフォルト	値の制限	説明
gatewayNamespaceId	string	✓	“grn:gs2:{region}:{ownerId}:gateway:default”	~ 1024文字	プッシュ通知に使用する GS2-Gateway のネームスペース
enableTransferMobileNotification	bool?		false		モバイルプッシュ通知へ転送するか
sound	string	{enableTransferMobileNotification} == true		~ 1024文字	モバイルプッシュ通知で使用するサウンドファイル名

LogSetting

ログの書き出し設定

ログデータの書き出し設定を管理します。この型は、ログデータを書き出すために使用されるログ名前空間の識別子（Namespace ID）を保持します。
ログ名前空間IDは、ログデータを集約し、保存する対象の GS2-Log の名前空間を指定します。
この設定を通じて、この名前空間以下のAPIリクエスト・レスポンスログデータが対象の GS2-Log へ出力されるようになります。
GS2-Log にはリアルタイムでログが提供され、システムの監視や分析、デバッグなどに利用できます。

	型	必須	デフォルト	値の制限	説明
loggingNamespaceId	string	✓		~ 1024文字	ネームスペースGRN

GitHubCheckoutSetting

GitHubからマスターデータをチェックアウトする設定

	型	必須	値の制限	説明
apiKeyId	string	✓	~ 1024文字	GitHub のAPIキーGRN
repositoryName	string	✓	~ 1024文字	リポジトリ名
sourcePath	string	✓	~ 1024文字	ソースコードのファイルパス
referenceType	enum { “commit_hash”, “branch”, “tag” }	✓	~ 128文字	コードの取得元
commitHash	string	{referenceType} == “commit_hash”	~ 1024文字	コミットハッシュ
branchName	string	{referenceType} == “branch”	~ 1024文字	ブランチ名
tagName	string	{referenceType} == “tag”	~ 1024文字	タグ名

referenceType に指定する列挙型の定義

定義	説明
commit_hash	コミットハッシュ
branch	ブランチ
tag	タグ

AttributeRange

募集条件

	型	必須	デフォルト	値の制限	説明
name	string	✓		~ 128文字	属性名
min	int	✓	0	~ 2147483646	ギャザリング参加可能な属性値の最小値
max	int	✓	0	~ 2147483646	ギャザリング参加可能な属性値の最大値

CapacityOfRole

募集枠

	型	必須	デフォルト	値の制限	説明
roleName	string	✓	“default”	~ 128文字	ロール名
roleAliases	List<string>		[]	~ 9 items	ロール名の別名リスト
capacity	int	✓		1 ~ 256	募集人数
participants	List<Player>		[]	~ 1000 items	参加者のプレイヤー情報リスト

Attribute

属性値

	型	必須	デフォルト	値の制限	説明
name	string	✓		~ 128文字	属性名
value	int	✓	0	~ 2147483646	属性値

Player

参加者のプレイヤー情報

	型	必須	デフォルト	値の制限	説明
userId	string	✓		~ 128文字	ユーザーID
attributes	List<Attribute>		[]	~ 5 items	属性値のリスト
roleName	string	✓	“default”	~ 128文字	ロール名
denyUserIds	List<string>		[]	~ 100 items	参加を拒否するユーザIDリスト
createdAt	long	✓	現在時刻		作成日時 (UNIX時間単位：ミリ秒)

GameResult

対戦結果

	型	必須	デフォルト	値の制限	説明
rank	int	✓		~ 2147483646	順位
userId	string	✓		~ 128文字	ユーザーID

Ballot

投票用紙

	型	必須	値の制限	説明
userId	string	✓	~ 128文字	ユーザーID
ratingName	string	✓	~ 128文字	レーティング計算に使用するレーティング名
gatheringName	string	✓	~ 128文字	投票対象のギャザリング名
numberOfPlayer	int	✓	2 ~ 10	参加人数

SignedBallot

署名付の投票用紙

	型	必須	デフォルト	値の制限	説明
body	string	✓		~ 1024文字	投票用紙の署名対象のデータ
signature	string	✓		~ 256文字	投票用紙の署名

WrittenBallot

投票用紙

	型	必須	デフォルト	値の制限	説明
ballot	Ballot	✓			投票用紙
gameResults	List<GameResult>			~ 10 items	投票内容。対戦結果のリスト

TimeSpan

時間間隔

	型	必須	値の制限	説明
days	int	✓	~ 365	現在時刻からの日数
hours	int	✓	~ 24	現在時刻からの時間
minutes	int	✓	~ 60	現在時刻からの分