/ja/ Recent content in Game Server Services ユーザーガイドへようこそ on Game Server Services | Docs Hugo ja /ja/microservices/account/ Mon, 01 Jan 0001 00:00:00 +0000 /ja/microservices/account/ Game Server Services が提供するアカウントシステムは「匿名アカウント」という種類のアカウントシステムです。 日本ではメジャーな仕組みですが、多くの地域では奇妙に感じるアカウントシステムかもしれません。 しかし、このアカウントシステムはゲームにおいて非常に理にかなったアカウントシステムです。 匿名アカウントとは何ですか？ 通常イメージするアカウント管理は、ログインIDがありパスワードがあるものでしょう。 匿名アカウントもその点は変わりません。 しかし、ログインIDとパスワードの両方がシステムによってランダムに決定されるというのが最大の特徴です。 システムによって発行されたログインID・パスワードをデバイスのローカルストレージに保存し、2回目以降はその情報を利用してログインすることでゲームを再開できます。 graph TD Startup --> LoadSave{"デバイスストレージから<br/>匿名アカウントを読み込み"} LoadSave -- Not Exists --> CreateAccount["匿名アカウントを作成"] CreateAccount --> SaveAccount["匿名アカウントを保存"] SaveAccount --> Login["ログイン"] LoadSave -- Exists --> Login Login --> InGame 匿名アカウントのメリット 簡単な登録：ユーザーは煩雑な登録プロセスを経ずにゲームをすぐに開始することができます。特に、無料で遊べるF2Pスタイルのゲームでは、多くのユーザーがゲームを試してもらうためには登録の手間を減らすことが重要です。 プレイヤー情報の保護：ログインIDやパスワードを自分で設定する必要がないため、個人情報やプライバシーが保護されます。また、パスワードの再設定や変更なども必要ありません。 引き継ぎのしやすさ：引き継ぎ情報に各種プラットフォームのID基盤やSNSのアカウントなどを利用することができ、異なるデバイスやアプリ間での引き継ぎがスムーズに行えます。 匿名でのプレイ体験：プレイヤーは匿名でゲームをプレイすることができるため、リアルネームやニックネームを使用しなくてもよく、より自由なプレイ体験を楽しむことができます。 引き継ぎ デバイスのローカルストレージほど信頼性の低い場所は他にはありません。 デバイスを落としてしまうかもしれませんし、デバイスを壊してしまうかもしれません。 そのとき、ゲームデータを全て失ってしまうとしたら、それは絶望的な状況です。 ゲームプレイヤーは、匿名アカウントでゲームを体験し、本当に気に入ったら「引き継ぎ情報」を登録できます。 引き継ぎ情報には各種プラットフォーマーのID基盤の情報を利用してもいいですし、SNSのアカウントを設定してもいいでしょう。ゲームパブリッシャーのID基盤も良さそうです。 引き継ぎ情報はスロット番号0〜1024の範囲で管理され、最大1,025種類まで登録できます。 用途に応じて各スロットに異なる認証手段を紐付けることで、幅広い引き継ぎシナリオを実現できます。 引き継ぎ情報には各種ID基盤で認証した結果得られるユーザーIDなどを記録します。 そして、全く新しいデバイスで引き継ぎを実行します。各種ID基盤にログインし、得られたユーザーIDで引き継ぎを実行すると 過去に引き継ぎ情報を設定した匿名アカウントでログインするための情報を取得することができます。 この情報を再びデバイスのローカルストレージに保存して、今後のログインに利用します。 graph TD InGame -- ゲームを気に入った --> AddTakeOverSetting["引き継ぎ情報を登録"] AddTakeOverSetting --> BrokenDevice["スマホが壊れた"] NewDevice["新しいスマホ"] --> DoTakeOver["引き継ぎ情報を入力して<br/>引き継ぎを実行"] DoTakeOver -- 匿名アカウントを復元 --> SaveAccount["匿名アカウントを保存"] SaveAccount --> Login["ログイン"] OpenID Connect 連携 引き継ぎ情報の登録、引き継ぎ処理の実行に OpenID Connect に準拠した認証システムを使用するためのサポートが用意されています。 /ja/microservices/ad_reward/ Mon, 01 Jan 0001 00:00:00 +0000 /ja/microservices/ad_reward/ モバイルゲームのマネタイズ手法としてプレイヤーに広告を視聴してもらい、広告プラットフォームから報酬を得ることも一般的になりました。 広告が正しく視聴された時に広告プラットフォームからサーバー間連携で通知をもらい、GS2 に報酬を付与することでチート行為を防ぐことができます。 クライアント側のコールバックのみで報酬を付与する設計では、改ざんされた SDK を使用してチートが行われるリスクがあります。 GS2-AdReward は広告プラットフォームから GS2 への直接の Server-to-Server(S2S) 通知を介して、信頼できる視聴完了イベントを契機に報酬を発行する仕組みを提供します。 視聴ポイント 一般的に GS2 では対価と報酬を設定してリソースの交換を行っていますが、サーバー間通信の仕様が広告プラットフォームごとに異なり、データの粒度も異なるため GS2-AdReward では広告の視聴が確認できた際に《視聴ポイント》を1ポイント加算するようになっています。 獲得した《視聴ポイント》は GS2-Exchange や GS2-Showcase などで使用可能な消費アクションとして消費できます。 これにより、ゲーム内のあらゆる報酬と広告視聴を疎結合に結びつけられるため、新しい広告キャンペーンを追加する際にも報酬の設計を再利用できます。 トランザクションアクション GS2-AdReward では以下のトランザクションアクションを提供しています。 種別 アクション 説明 消費 Gs2AdReward:ConsumePointByUserId 視聴ポイントの消費 入手 Gs2AdReward:AcquirePointByUserId 視聴ポイントの加算 graph TD InGame["ゲーム"] -- 広告を視聴 --> ViewAd["広告"] ViewAd -- 広告の視聴が完了 --> AdPlatform2["広告プラットフォーム"] ViewAd -- 広告の視聴が完了 --> InGame2["ゲーム"] AdPlatform2 -- 広告の視聴完了を通知 --> AdReward["GS2-AdReward"] AdReward --> AddPoint["ポイントを付与"] AdReward -- ポイント付与を通知 --> InGame2 InGame2 -- 視聴ポイントとアイテムを交換 --> Exchange["GS2-Exchange"] 対応している広告プラットフォーム 現在 GS2-AdReward は以下の広告プラットフォームに対応しています。 追加で対応を希望される場合はサポートにご連絡ください。 /ja/microservices/buff/ Mon, 01 Jan 0001 00:00:00 +0000 /ja/microservices/buff/ GS2-Buff は GS2 が提供するマイクロサービスの対価や報酬、ユーザーデータの最大値の補正を一元管理する機能を提供します。 期間限定で報酬を増加させる機能や、サブスクリプション契約状態であればユーザーデータの最大値が増加するような機能を実現するために利用できます。 GS2-Buff は他のマイクロサービスを直接書き換えるのではなく、API 呼び出しの際に渡される「コンテキストスタック」というメタ情報を介して各マイクロサービスに補正値を伝播させます。 そのため、バフの内容や期間を変更しても各マイクロサービスのマスターデータやプレイヤーデータをいっさい書き換えることなく適用・解除が行えるのが大きな特徴です。 ユースケース GS2-Buff が想定する代表的なユースケースは以下の通りです。 期間限定で経験値の取得量を 2 倍にするキャンペーン 特定のショーケースで販売される商品の価格を一律 20% オフ サブスクリプション契約中はスタミナの最大値を引き上げる 特定の装備を装備中のみクエスト報酬を増加させる イベント期間中だけ強化素材の消費量を半減させる graph LR Player["プレイヤー"] -->|ApplyBuff| Buff[GS2-Buff] Buff -->|コンテキストスタック| Player Player -->|API + コンテキストスタック| Other["他のマイクロサービス<br/>(GS2-Experience / GS2-Stamina / GS2-Showcase など)"] Other -.参照.-> Buff Other -->|補正後の値| Player マスターデータ管理 マスターデータを登録することでマイクロサービスで利用可能なデータや振る舞いを設定できます。 マスターデータの種類には以下があります。 BuffEntryModel: 補正値と対象を定義する基本モデル マスターデータの登録はマネージメントコンソールから登録する他、GitHubからデータを反映したり、GS2-Deployを使ってCIから登録するようなワークフローを組むことが可能です。 BuffEntryModel の主な設定項目 設定項目 説明 name バフを識別する一意な名前 metadata クライアント側で利用する任意メタデータ expression 補正計算式の種別 (Rate Add / Mul / Value Add) targetType 補正対象が「モデル」か「アクション」か targetModel / targetAction 補正対象のモデル名・アクション名・条件 GRN・補正レート priority 適用優先度。値が小さいものから順に計算 applyPeriodScheduleEventId GS2-Schedule のイベントによる有効期間 バフエンティティ 各マイクロサービスに加える補正の単位です。 基礎値を 1. /ja/microservices/chat/ Mon, 01 Jan 0001 00:00:00 +0000 /ja/microservices/chat/ GS2-Chat を利用することで、ゲーム内にテキストチャットを組み込むことが可能です。 テキストチャットは新着メッセージの検知のために常時接続セッションを必要とし、サーバーに求める要件も複雑になります。 Game Server Services を利用すれば、そのようなめんどくさい常時接続セッションの管理からも解放されます。 ルーム GS2-Chat の利用を開始するには、まずはルームを作成する必要があります。 ルームはプレイヤーが自由に作成できるようにもできますし、開発サイドで用意したルームをプレイヤーに使用させることもできます。 また、投稿できるユーザーIDのホワイトリストを設定して特定メンバー専用のルームを構築することも可能です。 一点気をつけなければならないのが、GS2-Chat は投稿可能なメッセージの数をルームごとに1秒間あたり3件までしか保証しません。 これを超える頻度でメッセージの投稿を行うとエラーが発生する可能性があります。 そのため、ソーシャルネットワークのタイムラインのような大量のプレイヤーを1つのルームに格納するような要件には向きません。 パスワード ルームにはパスワードを設定することが可能です。 パスワードが設定されたルームのメッセージを取得する際や、メッセージを投稿する際にはパスワードの指定が必要となります。 ルーム設定の更新 ルームの作成後、メタデータやパスワード、ホワイトリスト（投稿可能なユーザーIDリスト）を更新することが可能です。これにより、動的にルームのアクセス権限を変更したり、ルームの属性情報を変更したりできます。 購読 プレイヤーはルームを購読することで、ルームへの新着メッセージの通知を受けることができるようになります。 メッセージにはカテゴリを設定可能で、ルーム内のカテゴリごとに購読が可能です。 ギルドチャットの実装においてギルドマスターからのメッセージだけカテゴリを特別なものに設定し、ギルドメンバーはギルドマスターからのメッセージだけは絶対に購読させるようなことができます。 購読設定は後から更新することも可能です。受信するカテゴリの追加・削除や、オフライン時のモバイルプッシュ通知転送設定を動的に変更できます。 購読による通知処理は GS2-Gateway の通知機能が利用されますが、GS2-Gateway には通知先プレイヤーがオフラインの場合 モバイルプッシュ通知などの、ゲーム外の方法で通知する機能が用意されています。 1つのルームを購読できる人数に明確な制限はありませんが、通知を送信するために GS2-Gateway のAPIリクエストが発生するため、GS2のAPI利用料金が通知先1件ごとに発生します。 また、通知先が多くなると通知が届くまでにかかる時間が長くなります。 ルーム名を指定して、そのルームを現在誰が購読しているかの一覧を取得することも可能です。 actor Player1 actor Player2 participant "GS2-Chat#Room" participant "GS2-Gateway#Namespace" participant "Firebase Cloud Messaging" Player1 -> "GS2-Chat#Room" : Subscribe Player2 -> "GS2-Chat#Room" : Post Message "GS2-Chat#Room" -> "GS2-Gateway#Namespace" : Send Notification to Player1 "GS2-Gateway#Namespace" -> "Firebase Cloud Messaging" : Notification(if player is offline) "GS2-Gateway#Namespace" -> Player1 : Notification Player1 -> "GS2-Chat#Room" : Load New Message メッセージ ルームに対してメッセージを送信することが可能です。 メッセージの保持期間はネームスペースの設定 messageLifeTimeDays で1〜30日の範囲で指定でき、保持期間を超えたメッセージは削除されます。 /ja/microservices/datastore/ Mon, 01 Jan 0001 00:00:00 +0000 /ja/microservices/datastore/ GS2-Datastore を利用することで、任意のバイナリデータをサーバーに保存できます。 アップロードしたデータにはアクセス権限を設定でき、public（全員に公開）、protected（指定したユーザーIDにのみ公開：最大100件）、private（自分のみ）から選択します。 GS2-Datastore は UGC やレースゲームのゴーストデータのようなデータをアップロードするのが主たる目的で、プレイヤーのユーザーデータを保存するのには必ずしも適切ではありません。 なぜなら、所持品の所持数量をバイナリデータとして保存していると、セーブデータやアプリ本体の改竄でアイテムを増殖したり、入手量を不正に増加させた改造アプリでのプレイを許してしまうためです。 所持品の所持数量であれば、GS2-Inventory のような専用のマイクロサービスを利用することで、そのような不正行為は行えなくなります。 ユーザーデータの中でも、コンフィグの設定値など、改竄されてもゲームバランスに影響を与えることがないデータについて保存することを否定するわけではありません。 ユースケース GS2-Datastore が想定する代表的なユースケースは以下の通りです。 ユーザーが投稿したスクリーンショットやリプレイなどの UGC コンテンツの保存 レースゲームにおけるゴーストデータの共有 フォトモードで撮影した画像のクラウド共有 ゲーム設定など改竄されてもゲームバランスに影響を与えないユーザーデータの保存 ステージのカスタムマップデータの公開・共有 アクセススコープ データオブジェクトには 3 種類のアクセススコープがあり、用途に応じて使い分けます。 スコープ 説明 主な用途 public 全プレイヤーがダウンロード可能 UGC コンテンツの公開、ゴースト共有 protected allowUserIds に指定したユーザーのみがダウンロード可能（最大100件） フレンドのみへの共有 private アップロードしたユーザー本人のみがダウンロード可能 個人のセーブデータ、設定値 スコープと許可ユーザーは UpdateDataObject で後から変更することも可能です。 アーキテクチャ GS2-Datastore はバイナリデータの保存場所などを記録したメタデータを管理しており、実際のバイナリデータの保存には外部のクラウドストレージを利用しています。 そのため、アップロード・ダウンロード処理は複数のステップを必要とします。 この処理の流れは、Game Engine 向けの SDK ではラップした高レベルなAPIが用意されているため、気にする必要はありませんが 各種プログラミング言語向けの SDK には高レベルなAPIは用意されていませんので、利用者自身で複数ステップを処理する必要があります。 アップロードプロセス sequenceDiagram actor Player as プレイヤー participant Namespace as GS2-Datastore#Namespace participant Storage as Cloud Storage Player->>Namespace: PrepareUpload Namespace-->>Player: Cloud Storage URL Player->>Storage: Upload Payload Storage-->>Player: OK Player->>Namespace: DoneUpload Namespace->>Storage: Check exists Namespace-->>Player: OK ダウンロードプロセス sequenceDiagram actor Player as プレイヤー participant Namespace as GS2-Datastore#Namespace participant Storage as Cloud Storage Player->>Namespace: PrepareDownload Namespace-->>Player: Cloud Storage URL Player->>Storage: Download Storage-->>Player: Payload アップロード処理中のダウンロード GS2-Datastore はすでにアップロードしたデータを更新することができます。 Prepare ReUpload を呼び出してから Done Upload を呼び出すまでの間は、更新前の古いファイルがダウンロード可能な状態となり、中途半端なデータがダウンロードされることはありません。 /ja/microservices/deploy/ Mon, 01 Jan 0001 00:00:00 +0000 /ja/microservices/deploy/ GS2-Deploy は、GS2 の各マイクロサービスのネームスペースやマスターデータをコードとして管理し、宣言的にプロビジョニングするための機能を提供します。 AWS の CloudFormation に近い思想で設計されており、テンプレートファイルに記述したリソース定義を元に、複数のマイクロサービスをまたいだ環境構築・更新・削除をひとつのまとまり（スタック）として扱えます。 ゲーム開発においては、マスターデータの調整やネームスペース構成の変更が頻繁に発生します。 GS2-Deploy を活用することで、これらの変更を Git で管理し、GitHub などのリポジトリと連携した CI/CD パイプラインから自動的にデプロイする運用が可能になります。 スタック (Stack) スタックは、GS2 のリソースをまとめて管理する単位です。 スタックは YAML 形式で記述されたテンプレートを元に作成され、テンプレートに記述されたリソース定義に従って、ネームスペースやマスターデータなどを自動的に作成・更新・削除します。 1つのスタックには複数のマイクロサービスにまたがるリソースを含めることができ、ゲームを構成する一連の設定をひとまとまりとして扱えます。 graph LR Template["テンプレート(YAML)"] --> Stack["スタック"] Stack --> R1["GS2-Account ネームスペース"] Stack --> R2["GS2-Inventory マスターデータ"] Stack --> R3["GS2-Mission マスターデータ"] Stack --> R4["GS2-Showcase マスターデータ"] スタックは内部的に以下の状態を持ちます。 CREATE_PROCESSING: 作成処理中 CREATE_COMPLETE: 作成が完了し、リソースが利用可能 UPDATE_PROCESSING: 更新処理中 UPDATE_COMPLETE: 更新完了 ROLLBACK_PROCESSING: 失敗時のロールバック処理中 ROLLBACK_COMPLETE: ロールバック完了 DELETE_PROCESSING: 削除処理中 DELETE_COMPLETE: 削除完了 スタックの更新時に途中で失敗した場合は、自動的に変更前の状態に戻す《ロールバック》処理が行われます。 テンプレート テンプレートは YAML 形式で記述します。記述するセクションは以下です。 GS2TemplateFormatVersion: テンプレートのフォーマットバージョン Description: スタックの説明 Resources: 作成するリソースの定義 Outputs: スタック作成後に他システムから参照できる値の定義 以下はテンプレートの記述例です。 /ja/microservices/dictionary/ Mon, 01 Jan 0001 00:00:00 +0000 /ja/microservices/dictionary/ GS2-Dictionary では、ゲーム内で入手したアイテムやキャラクターの図鑑機能を実現します。 基本的に、GS2-Inventory のシンプルな実装バージョンと捉えていただければよく、入手済み・未入手の2値の所持状態を管理できます。 図鑑以外の用途にも使用できます。たとえばアバターパーツの所持状態はいい例です。 アバターパーツを持っているかは、パーツごとに2値で状態管理できれば十分なので GS2-Dictionary 向きです。 他にも、達成済みのチュートリアルステップ管理、開放済みのカットシーン管理、解禁済みのBGM一覧など、二値の状態として表現できる要素全般に活用できます。 graph TD Boss["ボスを討伐"] -- 報酬としてエントリー追加 --> Dictionary["GS2-Dictionary に記録"] Shop["ショップで購入"] -- 報酬としてエントリー追加 --> Dictionary Dictionary --> Browse["プレイヤーが図鑑を閲覧"] Dictionary -- 所持証明署名 --> Formation["GS2-Formation などで利用"] GS2-Inventory との違い スタックの概念の有無 GS2-Inventory は同一アイテムを複数所持する際に、スタックの概念があります。 これは、ポーションは最大99個スタック可能で、99個を超えると2個目のスタックを作成する というような仕様です。 この仕様があるため、GS2-Inventory では「ポーションの所持数量を取得する」というAPIの戻り値がリストになっています。 これはポーションが複数スタック存在する可能性があるためです。 この仕様はポーションのようなデータを管理するには都合がいいのですが、図鑑のようなシンプルな所持状態を管理するにはオーバースペックで、リストを取り扱うとコードの記述量も増加します。 入手処理で複数エントリーを登録可能 GS2-Inventory はポーションの入手とエリクサーの入手は別のAPIリクエストで処理する必要があります。 GS2-Dictionary は1回のAPIリクエストで最大100個のエントリーを登録できます。 これにより、クエストクリア時の報酬として「倒したモンスター全種類を一括で図鑑に登録」といった処理を1リクエストで効率的に行えます。 エントリーの検証と削除 GS2-Dictionary では、一度記録したエントリーを削除したり、特定のエントリーを入手済みか（または未入手か）を検証することができます。期間限定のイベントアイテムの所持状態をリセットしたり、特定のアイテムを入手している場合のみクエストを開始できるといった制限を設けるといった運用が可能です。 機能比較 項目 GS2-Dictionary GS2-Inventory 状態管理 所持/未所持の2値 数量・スタック管理 1リクエストでの登録数 最大100件 1件ずつ お気に入り機能 あり なし 所持証明署名 あり あり（ItemSet 単位） 主用途 図鑑、アバターパーツ、解禁状態 通常のアイテム所持 マスターデータ（EntryModel） 図鑑に登録可能なエントリーをマスターデータとして定義します。 EntryModel の主な設定項目は以下の通りです。 /ja/microservices/distributor/ Mon, 01 Jan 0001 00:00:00 +0000 /ja/microservices/distributor/ GS2-Distributor は、GS2 の各マイクロサービスをまたいだトランザクション処理を実現するための中核となるサービスです。 プレイヤーが「アイテムを消費して報酬を得る」「スタミナを消費してクエストを開始する」といった、複数のマイクロサービスをまたいだ一連の処理を安全に実行するための基盤を提供します。 GS2 では、プレイヤーにとってデメリットとなる操作を《消費アクション》、メリットとなる操作を《入手アクション》と呼びます。 GS2-Distributor は、これらのアクションをまとめた《トランザクション》を受け取り、適切なマイクロサービスに転送・実行することで、ゲームサイクルを構成する全ての処理を一貫した形で扱えるようにします。 トランザクションの仕組みについて詳しくは トランザクション を参照してください。 トランザクションを構成するアクション GS2 のトランザクションは、以下の3種類のアクションから構成されます。 graph LR Issue["トランザクション発行<br/>(ストア・クエスト・ミッション など)"] --> Verify["検証アクション"] Verify --> Consume["消費アクション"] Consume --> Acquire["入手アクション"] Acquire --> Done["完了"] 検証アクション (VerifyAction) トランザクションの実行を開始する前に、消費アクションや入手アクションを実行できる状態にあるかを事前にチェックするアクションです。 例えば「特定のアイテムを所持していること」「ランクが一定値以上であること」「特定のクエストをクリア済みであること」などの条件を、消費を発生させる前に確認できます。 検証に失敗した場合、消費アクション・入手アクション は実行されません。 消費アクション (ConsumeAction) プレイヤーにとってデメリットとなる処理を表すアクションです。 アイテムの消費、通貨の消費、スタミナの消費、回数制限カウンターの増加などが該当します。 消費アクションが実行されると、各マイクロサービスは「実行済みであること」を証明する署名を発行します。 この署名は次の入手アクションの実行時に検証され、消費アクションを全て通過していなければ入手アクションは実行できない仕組みです。 入手アクション (AcquireAction) プレイヤーにとってメリットとなる処理を表すアクションです。 アイテムの入手、通貨の入手、経験値の入手、クエストの開始処理などが該当します。 入手アクションは、関連する全ての消費アクションが正常終了したことを示す署名が揃ったときにのみ実行されます。 トランザクションの構造 GS2 のトランザクションは「複数の消費アクション + 1つの入手アクション」という構造で発行されます。 トランザクションは GS2-Showcase / GS2-Quest / GS2-Mission など、各マイクロサービスのトランザクション発行 API の応答として受け取り、ゲームクライアントは取得したトランザクションを GS2-Distributor 経由で実行します。 なお、GS2 SDK にはトランザクションの実行を自動化する仕組みが組み込まれており、多くの場合、ゲーム側でトランザクションを意識的に実行する必要はありません。 発行 API の結果に含まれる TransactionDomain の WaitAsync を呼び出すだけで、消費アクション・入手アクションが正しい順番で実行され、結果を取得できます。 /ja/microservices/enchant/ Mon, 01 Jan 0001 00:00:00 +0000 /ja/microservices/enchant/ 装備やキャラクターにユニークなランダムパラメーターを付与する機能を実現します。 RPG における武器の追加ステータス、ガチャで入手したカードに付与される個体値、ハクスラ系における装備の追加効果など、「同じアイテムでも個体ごとに性能が異なる」表現を実装する際に活用できます。 ランダムパラメーターには2種類用意しています。 バランスパラメーター レアリティパラメーター graph TD Item["装備・キャラクターなど<br/>(propertyId で識別)"] --> Choose{パラメーター種別} Choose -- 総量を分配 --> Balance["バランスパラメーター<br/>例: 攻撃力60/防御力40"] Choose -- 確率で複数付与 --> Rarity["レアリティパラメーター<br/>例: クリティカル率+5%、HP+100"] Balance --> ReDraw1["再抽選 / 値の直接設定"] Rarity --> ReDraw2["再抽選 / 追加 / 値の直接設定"] ランダムパラメーターは「対象アイテムの識別子」となる propertyId をキーとして管理されます。 propertyId には GS2-Inventory のアイテムインスタンスIDや、GS2-Formation のフォーム識別子などを指定することで、装備個体ごとにパラメーターを紐付けることができます。 バランスパラメーター バランスパラメーターは用意された複数のパラメーターを定められた総量でランダムに分配します。 たとえば、攻撃力と防御力の2つのパラメーターを用意し、総量に100を設定した場合に攻撃力が60で抽選されると防御力は40になります。 マスター項目 説明 name バランスパラメーターモデル名 totalValue パラメーター値の合計総量 initialValueStrategy 初期値の決定方法（average：平均値 / random：ランダム） parameters 分配対象となるパラメーターの一覧 再抽選 バランスパラメーターは再抽選が可能です。 再抽選を行う際に、一部パラメーターの値を固定することができます。 パラメーターを一部固定することで、プレイヤーがパラメーターの最適化を効率的にを行う手段を提供することができます。 初期値 バランスパラメーターの初期値はランダム値にするか、平均値にするかを定めることが可能です。 値の直接設定 バランスパラメーターには、管理画面や API（トランザクションアクション）を通じて、抽選を経ずに任意の値を直接設定することも可能です。これにより、特定のイベント報酬として固定のステータスを持つ装備を配布するといった運用が可能になります。 レアリティパラメーター レアリティパラメーターは、バランスパラメーターのように一定のパラメーターに値を分配するのではなく、 装備やスキルに一定確率で追加パラメーターを付与するようなケースで利用できます。 /ja/microservices/enhance/ Mon, 01 Jan 0001 00:00:00 +0000 /ja/microservices/enhance/ この機能は開発者によっては全く理解できない機能でしょう。 しかし、日本をはじめとしたモバイルゲームのデファクトスタンダードのゲームシステムには必ず存在する機能です。 このゲームメカニクス自体は Game as a Service を実現する上で有用な知識になるはずですので、理解できない開発者向けにゲームメカニズムの解説を加えます。 強化機能のゲームメカニクスについて十分な知識がある場合はこの先の解説セクションは読み飛ばして問題ありません。 強化機能のゲームメカニクス 強化機能自体は非常にシンプルなゲームシステムで、素材アイテムを消費することで、対象の経験値を加算できる仕組みです。 バトルに参加して経験値を入手するという方法だけでなく、様々な方法でキャラクターや装備の育成ができるようになっています。 （装備にもレベルがあります） さて、このゲームシステムがなぜ Game as a Service を実現するのに一役買っているかを説明しましょう。 一言で言えば、プレイ時間の水増しで活躍しています。 開発速度よりゲームのプレイ速度のほうが圧倒的に早いのは、みなさん十分理解しているでしょう。 私たちゲーム開発者が3年間かけて開発したゲームを、プレイヤーは10時間で終えてしまうわけです。 しかし、この差を埋めないと Game as a Service は成り立ちません。 つまり、プレイヤーのコンテンツ消費速度にデバフをかける必要があります。その魔法が強化のゲームシステムです。 一般的な Game as a Service のゲームは毎月1回はイベントを実施しています。 そのイベントには、なんらかのボスが存在し、プレイヤーはそのボスをイベント期間繰り返し討伐し続けることになります。 ボスはプレイヤーの成長段階に合わせて複数の難易度を用意し、討伐することでキャラクターや装備の強化素材を手に入れることができます。 集めた強化素材を使用して、キャラクターや装備の経験値に変換し成長させます。 キャラクターや装備を成長させると、より高難易度のボスにチャレンジできるようになります。 こうすることで、プレイヤー全員がイベントに参加しつつ、自分のキャラクターの成長段階にあわせた強化素材を入手し、キャラクターや装備を成長させる遊びを楽しむことができます。 実際には、強化素材を直接ボスがドロップすることは少ないかもしれません。 代わりにイベント期間だけチャレンジできるガチャがあり、そのガチャを引くためのポイントを集めて、ガチャを経由して素材を手に入れたり イベント期間だけ開店するショップで、ボスを討伐することで得られるゲーム内通貨を集めて、ショップから強化素材を購入するなど プレイヤーの判断でどこを優先して強化するかを決定できるようにするような工夫はありますが、最終的にはプレイヤーがキャラクターの育成に必要な時間を引き伸ばしてプレイ時間を水増ししています。 イベントを通して一貫して変わらないのは、プレイヤーのキャラクターが強くなるということです。 イベントが終わると強くなったキャラクターを使用して、より高難度の恒常コンテンツを楽しむなど、次の楽しみに繋げています。 graph TD BossBattle["Boss Battle"] -- Acquire Event Point --> Shop Shop -- Buy Enhance Materials --> Enhance["Enhance Character"] Enhance -- More Formidable --> BossBattle アーキテクチャ 強化には素材となるアイテムを管理している GS2-Inventory と、強化対象のキャラクターや装備を管理している GS2-Inventory または GS2-Dictionary。 そして、そのキャラクターや装備の経験値・レベルを管理している GS2-Experience を GS2-Enhance を通して操作することで実現しています。 /ja/microservices/exchange/ Mon, 01 Jan 0001 00:00:00 +0000 /ja/microservices/exchange/ GS2 が提供するマイクロサービスの中でも特に重用される機能です。 あらゆるマイクロサービスのリソースを、全く異なるマイクロサービスのリソースに変換する役割を担います。 ゲームの仕様にはリソースの交換に関するものが多数存在し、その度に GS2-Exchange の出番が発生します。 リソース交換の例 強化素材の変換 GS2-Inventory で管理する ★1 の強化素材 10個を、同じく GS2-Inventory で管理する ★2 の強化素材 1個と交換 6時間に1回アイテムを入手できる GS2-Stamina で管理する6時間で1回復するスタミナ1を、GS2-Inventory で管理するアイテムと交換 アイテムを売却 GS2-Inventory で管理するアイテムを、同じく GS2-Inventory で管理するゲーム内通貨と交換 交換の種類 GS2-Exchange はマスターデータで定められた交換レートで直ちに交換できるダイレクト交換と、 交換を実行した後、現実時間で一定時間経過したのちに交換結果を得られる非同期交換、 購入する度にコストが上昇するコスト上昇型交換の3つのモードが存在します。 flowchart LR Verify["対価検証<br/>(verifyActions)"] --> Consume["対価消費<br/>(consumeActions)"] Consume -->|timingType=direct| Acquire["報酬付与<br/>(acquireActions)"] Consume -->|timingType=await| Await["Await オブジェクト作成"] Await -. lockTime 経過 .-> Acquire2["AcquireAsync で報酬受取"] 交換の挙動はネームスペース設定の enableDirectExchange / enableAwaitExchange でモードごとに有効化できます。 レートモデルの timingType を direct または await に切り替えることで個別のレートが即時交換と非同期交換のいずれで動作するかを選択できます。 非同期交換の挙動 非同期交換を使用した場合、交換を実行したタイミングで対価は消費され、 報酬を得る代わりに Await オブジェクトが作成されます。 Await オブジェクトの作成時刻からマスターデータで定義された交換待機時間（lockTime 秒）が経過すると報酬を受け取ることができます。 /ja/microservices/experience/ Mon, 01 Jan 0001 00:00:00 +0000 /ja/microservices/experience/ Game as a Service において、成長要素は不可欠です。 キャラクターの成長をおこない、成長したキャラクターでさらに高難度のコンテンツに挑むゲームサイクルを実装するための経験値・ランク機能を提供します。 GS2-Experience は単一のキャラクターのレベルだけでなく、複数のプロパティ（キャラクター、武器、パーティ、ギルドなど）の成長を 1 つのマイクロサービスで一元管理できる柔軟な設計となっています。 ユースケース GS2-Experience が想定する代表的なユースケースは以下の通りです。 プレイヤーキャラクターのレベル管理 育成可能な装備品のレベル管理 ギルドやチームのランク管理 称号・バトルパスのレベル管理 スキルツリーの各スキル熟練度管理 graph LR Player[プレイヤー] -->|経験値加算| Exp[GS2-Experience] Exp -->|ランク計算| Status[Status] Status -->|閾値超え| RankUp[ランクアップ] RankUp -->|報酬付与| Inventory[GS2-Inventory] RankUp -->|スタミナ最大値更新| Stamina[GS2-Stamina] ランク GS2-Experience は経験値の値から自動的にランクの値を計算します。 そのためには、マスターデータを利用してランクアップの閾値となる経験値テーブルを定義する必要があります。 Experience Model でランクアップ閾値を管理し、その下に任意の値を持つプロパティIDをぶら下げることができます。 プロパティIDごとに経験値の値は管理され、経験値の値に基づいてランクが決定します。 Experience Model とプロパティIDの関係 graph TD N[Namespace] --> EM1["ExperienceModel<br/>character_ssr"] N --> EM2["ExperienceModel<br/>character_sr"] N --> EM3["ExperienceModel<br/>weapon"] EM1 --> P11["プロパティID:<br/>character-001"] EM1 --> P12["プロパティID:<br/>character-002"] EM3 --> P31["プロパティID:<br/>weapon-001"] EM3 --> P32["プロパティID:<br/>weapon-002"] たとえば「キャラクターの種類ごとに必要経験値テーブルを変えたい」「キャラクター個別にランクキャップを変えたい」といったケースで、ExperienceModel をキャラクター種別ごとに用意し、プロパティID にキャラクターの個別 ID を割り当てることで実現できます。 /ja/microservices/formation/ Mon, 01 Jan 0001 00:00:00 +0000 /ja/microservices/formation/ 所有しているリソースを組み合わせて1つの何かを編成するという仕様は一般的です。 複数のキャラクターを編成してパーティを作ったり、武器・防具といったアイテムを編成して装備するといったものです。 GS2-Formation は「どんなスロットが存在するか」「各スロットに何を装着できるか」「同じ種類の編成をいくつまで保持できるか」をマスターデータで定義し、プレイヤーごとの編成内容を管理するマイクロサービスです。 用語 graph LR MoldModel --> FormModel FormModel --> SlotModel PropertyFormModel --> SlotModel2[SlotModel] Mold --> Form Form --> Slot PropertyForm --> Slot2[Slot] 用語 説明 MoldModel 同種の編成（パーティ・装備セットなど）を複数保有するための型。容量（保存枠）の概念を持つ FormModel Mold に紐づく Form の構成定義。どのようなスロットを持つかを定義する PropertyFormModel プロパティIDで参照する単独の編成定義。Mold を介さず1キャラクター1編成のような形態で使う SlotModel スロットの定義。スロットに装着できるプロパティを正規表現で制限できる Mold プレイヤーごとの Mold 実体。capacity を持ち最大容量まで Form を作成可能 Form Mold 内の編成インスタンス。index で識別される PropertyForm プロパティID単位の編成インスタンス Slot プレイヤーが実際に装着しているリソースを保持する フォーム キャラクターの装備機能を実現するにあたって、武器・兜・籠手・胴・脚・足といった複数のスロットを用意し、 各スロットに適合するアイテムのみを装備できるように設定が可能です。 Form Model では、どのようなスロットが存在するのか、各スロットにはどのようなアイテムを編成できるのかをマスターデータとして定義します。 Mold と PropertyForm の使い分け flowchart LR subgraph Mold M1["Form #0"] M2["Form #1"] M3["Form #2 (空き枠)"] end subgraph PropertyForm P1["character-001 の編成"] P2["character-002 の編成"] end Mold を使うケース: パーティ編成1〜N のように、編成セットを番号（index）で管理し、最大保有数（capacity）を成長要素として拡張したい場合 PropertyForm を使うケース: キャラクターごと・装備セットごとなど、外部のリソースID（propertyId）に1対1で結びつく編成 Mold の MoldModel は initialMaxCapacity（初期容量）と maxCapacity（拡張上限）を持ち、プレイヤーの成長やマネタイズ施策に応じてキャパシティを増減できます。 /ja/microservices/freeze/ Mon, 01 Jan 0001 00:00:00 +0000 /ja/microservices/freeze/ GS2-Freeze は、ゲームから利用する GS2 のマイクロサービスのバージョンを任意のタイミングで固定 (freeze) し、運営側が管理するタイミングでバージョンを更新できるようにするための機能です。 通常、GS2 のマイクロサービスは継続的にバージョンアップが行われ、ゲームは常に最新のバージョンの API を利用することになります。 多くのタイトルではこの運用で問題ありませんが、リリース直後の大規模タイトルや、長期にわたって安定性を最優先したい局面では、サービス側の更新タイミングをゲーム運営側でコントロールしたいというニーズが存在します。 GS2-Freeze はこのようなニーズに応えるための、エンタープライズ向けの機能です。 Tip GS2-Freeze はエンタープライズ向けの機能で、すべてのお客様に対して広範囲に提供される機能ではありません。 利用をご希望の場合はサポートまでお問い合わせください。 ステージ GS2-Freeze の中心となる概念が「ステージ (Stage)」です。 ステージは「特定の時点で固定された GS2 マイクロサービスのバージョンの集合」を表します。 各ステージには以下の情報が紐付きます。 ステージ名 (name): ステージを一意に識別する名前 ソースステージ名 (sourceStageName): バージョン情報の取得元となるステージの名前 ソート順 (sortNumber): 開発・検証・本番といったステージの並び順を表す番号 ステータス (status): ステージの状態 (プロモート中、ロールバック中など) ゲームのクライアント・サーバーは、利用したいステージを指定してGS2のAPIを呼び出すことで、そのステージに固定されたバージョンのマイクロサービスを利用できます。 graph LR Latest["最新の GS2 マイクロサービス"] -- Promote --> StageDev["Stage: dev"] StageDev -- Promote --> StageStg["Stage: staging"] StageStg -- Promote --> StageProd["Stage: production"] Game["ゲームクライアント"] -- API リクエスト --> StageProd プロモート / ロールバック ステージのバージョンを更新する操作を「プロモート (Promote)」と呼びます。 プロモートを実行すると、ソースステージに固定されているバージョンが、対象のステージにコピーされます。 たとえば「staging ステージのバージョンを production ステージへプロモートする」ことで、検証済みのバージョンを本番に反映できます。 /ja/microservices/friend/ Mon, 01 Jan 0001 00:00:00 +0000 /ja/microservices/friend/ ゲーム専用のソーシャルグラフを形成するための機能を提供します。 ソーシャルグラフはプラットフォーマーも提供している機能がありますが、ゲーム内で独自に形成することにも価値があります。 プラットフォーム全体で使用されるフレンド関係は登録を行うのに慎重になりがちです。 なぜなら「私はこの人と今遊んでるゲームは一緒に遊びたいけれど、他のゲームを一緒に遊びたいとは思っていない」というケースが存在するためです。 プラットフォーマーが提供するソーシャルグラフはリアルに近い関係性を反映したもので、ゲーム固有のソーシャルグラフはそのゲーム内の関係性を反映したものとして扱うと、プレイヤーはより気軽にフレンド機能を利用してくれます。 フレンド フレンドになるためには、双方向の同意関係が必要です。 フレンド関係を構築したいいずれかのプレイヤーが、相手にフレンドリクエストを送信し、フレンドリクエストを受け取ったプレイヤーがそれに同意することでフレンド関係が成立します。 フォロー フォローは相手の同意なく、関係を構築することができます。 フォローされている人は自分が誰にフォローされているかを一覧として知る術はありません。 この仕様はソーシャルネットワークのフォローの仕様を想像していると違和感があるかもしれません。 しかし、ゲーム内でフォロー機能を実装している多くのゲームの仕様をみていて、その必要性がないと判断しました。 自分をフォローしてくれているプレイヤーが自分のゴーストキャラクターと一緒に冒険に出た場合、 冒険で得た報酬を分け与えてくれるだけで十分で、誰が一緒に冒険してくれたのかにはあまり興味がなかっためです。 一覧で取得することはできませんが、冒険で得た報酬を分け与える処理として GS2-Inbox に報酬付きメッセージを届ける際に メッセージのペイロードに、一緒に冒険に出たプレイヤーのユーザーIDを載せることで、プロフィールを伝えること自体は可能です。 プロフィール GS2-Friend はプレイヤーのプロフィールを保持する領域を提供します。 プロフィールには任意の値を保持でき、スペースが3箇所存在します。 他プレイヤーが自由に参照できる「パブリックプロフィール」 フォローしているプレイヤーが参照できる「フォロワープロフィール」 フレンドが参照できる「フレンドプロフィール」 それぞれ、用途に合わせて使い分けることが可能です。 ブラックリスト ゲームを長期間プレイしていると、不快に感じるプレイヤーがいるかもしれません。 そのようなプレイヤーをリスト化して永続化する機能です。 あくまで永続化する機能が存在するだけで、ここに追加するだけでは何も機能は果たしません。 GS2-Matchmaking のマッチメイキング条件にリストを渡すなど別途ここに記録したリストを必要に応じて使用する必要があります。 スクリプトトリガー ネームスペースに followScript ・ unfollowScript ・ sendRequestScript ・ cancelRequestScript ・ acceptRequestScript ・ rejectRequestScript ・ deleteFriendScript ・ updateProfileScript を設定すると、フォローやフレンドリクエスト、プロフィール更新など各操作の前後でカスタムスクリプトを実行できます。スクリプトは同期・非同期の実行方式を選択でき、非同期では GS2-Script や Amazon EventBridge を介した外部連携にも対応します。これらの設定は GS2-Deploy や各言語向け CDK でテンプレート化して管理できます。 設定できる主なイベントトリガーとスクリプト設定名は以下の通りです。 followScript（完了通知: followDone）: フォローの前後 unfollowScript（完了通知: unfollowDone）: フォロー解除の前後 sendRequestScript（完了通知: sendRequestDone）: フレンドリクエスト送信の前後 cancelRequestScript（完了通知: cancelRequestDone）: フレンドリクエスト取消の前後 acceptRequestScript（完了通知: acceptRequestDone）: フレンドリクエスト承諾の前後 rejectRequestScript（完了通知: rejectRequestDone）: フレンドリクエスト拒否の前後 deleteFriendScript（完了通知: deleteFriendDone）: フレンド削除の前後 updateProfileScript（完了通知: updateProfileDone）: プロフィール更新の前後 プッシュ通知 設定できる主なプッシュ通知と設定名は以下の通りです。 /ja/microservices/gateway/ Mon, 01 Jan 0001 00:00:00 +0000 /ja/microservices/gateway/ GS2-Gateway はゲームクライアントとサーバーとの間で WebSocket による常時接続を維持し、サーバーから任意のタイミングで通知を送るための機能を提供します。 通常のゲームサーバーとの通信はクライアントからのリクエストに対してサーバーが応答する形式ですが、GS2-Gateway を使うことでサーバー起点の通知 (メッセージ着信・フレンド申請・ギルドからの招集など) をリアルタイムにクライアントへ届けることができます。 sequenceDiagram participant Client participant Gateway as GS2-Gateway participant Service as 各マイクロサービス Client->>Gateway: WebSocket 接続 Client->>Gateway: SetUserId(認証) Service->>Gateway: SendNotification Gateway->>Client: 通知ペイロード配信 主な機能 WebSocket 常時接続 GS2-Gateway は WebSocket プロトコルでクライアントからの接続を受け付け、ユーザーごとに接続情報を保持します。 他のマイクロサービスから「このユーザーに通知を送りたい」というリクエストが届くと、接続中のクライアントに対してペイロードを配信します。 主要な連携先は以下です。 GS2-Inbox: 新規メッセージの着信通知 GS2-Friend: フレンド申請・承認の通知 GS2-Guild: ギルド参加申請、ギルド内の状況変化通知 GS2-Matchmaking: マッチング完了通知 GS2-Distributor: トランザクション自動実行のための通知 GS2-JobQueue: 新規ジョブが積まれた際の通知 同時接続制御 ネームスペース内のユーザーは原則として同時に1セッションのみを保持できます。 SetUserId 実行時に allowConcurrentAccess を false にすると、すでに他のセッションが接続中の場合は、新しいセッション側で同時接続エラーとして検知できます。 true にすると、新しいセッションが接続された時点で古いセッションが切断されます。 この機能を利用することで、複数デバイスからの同時ログインを抑止できます。 GS2-Account のパスワード自動変更機能と組み合わせると、アカウント共有や引き継ぎ後の旧デバイスの締め出しをより強固に行うことができます。 Firebase Cloud Messaging 連携 (モバイルプッシュ通知) クライアントが起動していない (WebSocket が接続されていない) 状態でも通知を届けたい場合は、Firebase Cloud Messaging (FCM) との連携機能を利用できます。 /ja/microservices/grade/ Mon, 01 Jan 0001 00:00:00 +0000 /ja/microservices/grade/ キャラクターや装備の育成には短期成長目標としてのレベルアップとは別にグレードアップを用意することが一般的な仕様です。 グレードアップすることによって、レベルキャップを引き上げることができ、キャラクターや装備をより強力に育成することが可能となります。 グレードアップの方法はいくつかの方法が考えられ、育成素材を消費することでグレードアップできるものや、同種のキャラクターや装備を合成することでグレードアップできるものもあります。 GS2-Grade は方法については問わず、グレードごとのレベルキャップを設定することで、GS2-Experience のレベルキャップの運用をより簡易に実装できるようにすることを目的としています。 graph LR Player["プレイヤーの所持物"] -- グレードアップ --> Grade["GS2-Grade<br/>(グレード値が上昇)"] Grade -- ApplyRankCap --> Experience["GS2-Experience<br/>(ランクキャップが反映)"] Experience -- 経験値の獲得 --> LevelUp["レベルアップ"] グレード グレードごとに GS2-Experience のランクキャップに設定する値を定義できます。 グレードはキャラクターや装備のような対象を一意に指す propertyId ごとに管理され、Status として個別に保持されます。 フィールド 説明 gradeName グレードモデル名 propertyId グレードを適用するリソースを示すGRN（例: GS2-Inventory の ItemSet） gradeValue 現在のグレード値（0始まりの整数） グレードの初期値 プロパティIDが正規表現にマッチするかによって初期グレードの値を設定できます。 例えば、GS2-Inventory の ItemModel の名前が SSR から始まる場合はグレード3、SR から始まる場合はグレード2で開始するようにすることで ItemModel の種類によって初期のランクキャップを変えることが可能です。 マスターデータの defaultGrades に複数の propertyIdRegex と defaultGradeValue の組を登録することで初期グレードを宣言します。 グレード引き上げ素材判定 グレードアップの方法として「同種のキャラクターや装備を合成する」ケースで、素材として使用しようとしているリソースが「同種のキャラクターや装備」であるかを判定する処理をサポートする機能が用意されています。 グレードのプロパティIDから正規表現によって、パラメーターを取り出して正規表現を構築し、素材として使用しようとしているリソースのプロパティIDがマッチするかを判定することで実現します。 例えば、GS2-Inventory の ItemSet が同種の ItemModel によるものかを判定する場合は以下のように正規表現を設定します。 propertyIdRegex: grn:gs2:{region}:{ownerId}:inventory:namespace-0001:user:(. /ja/microservices/guard/ Mon, 01 Jan 0001 00:00:00 +0000 /ja/microservices/guard/ GS2-Guard は GS2 のAPIエンドポイントに対するアクセスを保護するための機能を提供します。 特定の国や地域、IPアドレス、匿名化されたIP、ホスティング事業者のIP、評判の悪いIPなど、さまざまな条件で送信元を判定し、API リクエストを許可・拒否する仕組みを構築できます。 不正利用やチート行為、攻撃的なトラフィックからゲームサーバーを守るための、いわばゲーム向けの軽量な WAF (Web Application Firewall) として機能します。 GS2-Guard はゲームクライアントから直接利用する機能ではなく、運営側でブロッキングポリシーを定義し、他のGS2マイクロサービスのAPIに対して適用するための仕組みです。 ブロッキングポリシー GS2-Guard のネームスペースには BlockingPolicyModel を1つ設定でき、ここにアクセス制御のルールを記述します。 GS2の各マイクロサービスのネームスペースから、対象の GS2-Guard ネームスペースを参照することで、そのマイクロサービスへの API リクエストにブロッキングポリシーが適用されます。 ブロッキングポリシーで設定できる主な項目は以下の通りです。 既定の制限 (defaultRestriction): 既定で API リクエストを許可するか拒否するか 例外的に許可するサービス (passServices): 制限を適用しないGS2のサービス名のリスト 地理的制限 (locationDetection / locations / locationRestriction): リクエストの送信元の国・地域を判定し、特定の国・地域だけ許可・拒否する 匿名IP制限 (anonymousIpDetection / anonymousIpRestriction): Tor出口ノードやVPNなど、匿名化サービス経由のリクエストを判定し、許可・拒否する ホスティング事業者のIP制限 (hostingProviderIpDetection / hostingProviderIpRestriction): クラウド事業者などホスティング由来のIPからのリクエストを判定し、許可・拒否する 評判の悪いIPの制限 (reputationIpDetection / reputationIpRestriction): 攻撃の踏み台として知られるなど、悪評のあるIPからのリクエストを判定し、許可・拒否する 個別IPアドレス制限 (ipAddressesDetection / ipAddresses / ipAddressRestriction): 任意のIPアドレス・CIDRレンジを指定して、許可・拒否する graph LR Client["ゲームクライアント"] -- API リクエスト --> Guard["GS2-Guard<br/>(ブロッキングポリシー判定)"] Guard -- 許可 --> Microservice["他のGS2マイクロサービス"] Guard -- 拒否 --> Block["403 / アクセス拒否"] 検出と制限の分離 各検出条件 (Detection) は「無効」「有効」のいずれかを取り、検出条件が有効な場合に「対応する制限 (Restriction)」が適用されます。 これにより、検出だけ行ってログに残しておき、しばらく状況を確認したのちに本格的に拒否を有効化する、といった段階的な運用が可能です。 /ja/microservices/guild/ Mon, 01 Jan 0001 00:00:00 +0000 /ja/microservices/guild/ 複数のプレイヤーでチームを作成し、一緒になんらかの目標に向かって活動するための機能がギルド機能です。 GS2-Guild はギルドメンバーの管理と、ギルドメンバーが実行できる権限管理を行うためのマイクロサービスです。 GS2-Guild において「ギルド」は一人のプレイヤーとして処理され、ギルドユーザーと呼びます。 ギルドメンバーはギルドユーザーとして情報を取得・更新可能なフェデレーションを行うことで、ギルドメンバーが共通のプロパティを操作可能な状態を実現します。 例えば プレイヤーA プレイヤーB が所属している ギルドA があったと仮定します。 プレイヤーレベル や スタミナ といった一般的な情報が プレイヤーA や プレイヤーB に紐づいて管理されることは容易に想像できるでしょう。 これと同じように ギルドA に紐づいて ギルドレベル のようなプロパティを紐づけて管理することも容易に想像できるでしょう。 GS2-Guild の思想の特徴的な部分として プレイヤーA プレイヤーB と ギルドA の明確な区別はなく一律 ユーザー と捉えて処理されることにあります。 そのため、ギルドが持つプロパティには GS2 のあらゆるユーザーデータを扱うマイクロサービスを使用して管理できます。 たとえば、ギルドに GS2-Experience のランク・経験値を持たせることもできますし、GS2-Stamina のスタミナを持たせることもできますし、GS2-SkillTree のスキルツリーを持たせることもできます。 そして、GS2-Guild ではギルドメンバーを管理するとともに、ギルドメンバーが ギルドユーザー としてGS2のAPIを呼び出せるアクセストークンを発行する機能があります。 その際にギルドユーザーとしてどのAPIを呼び出せるのかをより細かく制御するためのアクセス権限制御機能があります。 この機能を利用すれば ギルドマスター の役職をもつプレイヤーのみが、ギルドユーザーとして GS2-Showcase の商品を購入できるような機能を実現できます。 ギルドモデル ギルド単位の設定は GuildModel で管理します。defaultMaximumMemberCount と maximumMemberCount でメンバーの初期値と上限を定め、inactivityPeriodDays にギルドマスターの無活動期間を指定すると自動的に後継者を選出できます。rejoinCoolTimeMinutes で脱退後の再参加クールタイム、maxConcurrentJoinGuilds や maxConcurrentGuildMasterCount で同時参加ギルド数やギルドマスターの人数制限も設定可能です。 ギルドメンバー ギルドに所属しているプレイヤーを指します ロール ギルドに所属しているプレイヤーの役職に相当するエンティティで、実行可能なAPIの種類を定義します。 1つのギルドモデルに最大10種類のロールを定義できます。 権限設定 ロールには GS2-Identifier のポリシードキュメントを定義できます。 ギルドユーザーに変わる前の権限 && ロールの権限 の範囲でAPIを呼び出すことができます。 /ja/microservices/identifier/ Mon, 01 Jan 0001 00:00:00 +0000 /ja/microservices/identifier/ GS2-Identifier は、GS2 マネージメントコンソールおよび GS2 の API にアクセスするためのクレデンシャルを管理するサービスです。 GS2 のオーナーアカウントに紐づくユーザー、各ユーザーに付与される権限 (セキュリティポリシー)、そして実際の API 呼び出しに利用するクライアントID / クライアントシークレットを発行・管理します。 GS2-Identifier はゲームクライアントから直接呼び出すことを想定していないサービスであり、運営側のセットアップやデプロイ自動化、CI/CD パイプラインなどで利用されます。 IAM 的な設計 GS2-Identifier は、クラウドサービスにおける IAM (Identity and Access Management) に相当する概念を提供します。 主要な要素は次の通りです。 ユーザー: GS2 オーナーアカウント配下に作成する個別の利用主体 セキュリティポリシー: 操作可能なリソースとアクションを記述したポリシー文書 セキュリティポリシーのアタッチ: ユーザーに対してセキュリティポリシーを紐づけ、権限を付与 クライアントID / クライアントシークレット: ユーザーごとに発行される API 認証情報 graph TD Owner["GS2 オーナー"] --> User["ユーザー"] User -->|アタッチ| Policy["セキュリティポリシー"] User -->|発行| Credential["クライアントID<br/>クライアントシークレット"] Credential -->|認証| API["GS2 API"] Policy -->|権限制御| API セキュリティポリシー セキュリティポリシーは、JSON 形式で記述された権限定義です。許可するリソース GRN と、許可するアクション (Gs2Account:CreateAccount のような操作識別子) を記述することで、そのポリシーがアタッチされたユーザーに対してどのような操作を許可するかを表現します。 開発・運用の各フェーズに応じて適切なポリシーを設計し、ユーザーごとに最小権限を付与する運用が推奨されます。 クライアントID / クライアントシークレット ユーザーに対して発行されるクライアントIDとクライアントシークレットは、GS2 API を呼び出す際の認証情報として利用されます。1ユーザーに対して複数のクレデンシャルを発行することができ、用途やデバイスに応じて使い分けることができます。 /ja/microservices/idle/ Mon, 01 Jan 0001 00:00:00 +0000 /ja/microservices/idle/ ゲームをプレイしていない期間に応じて報酬を付与する仕組みを実現します。 スマートフォン向けゲームでは「久しぶりにアプリを起動したら大量の報酬を獲得できた」というデザインがプレイヤーの再訪促進に強く寄与します。 GS2-Idle はそのような放置報酬を簡単に組み込むためのマイクロサービスです。 graph LR Start["待機開始"] --> Idle["放置時間が経過"] Idle --> Prediction["獲得予定報酬を取得"] Prediction --> Receive["報酬を受取"] Receive --> Start カテゴリー 放置報酬は複数用意することができます。 プレイヤーはカテゴリー毎に1つの待機時間を持つことができます。 カテゴリーは「キャラクターのスタミナ自然回復」「採掘場の自動採掘」「素材の自動生成」など、それぞれ独立した放置報酬の単位として活用できます。 放置時間 カテゴリーには放置時間 何分毎に報酬を得られるかと、放置時間の最大値の初期値を設定できます。 放置時間の最大値はプレイヤーごとに引き上げることが可能です。報酬受取後に未消化の待機時間をリセットするか次回に持ち越すかは rewardResetMode で選択できます。 rewardResetMode 振る舞い Reset 報酬受取時に経過時間が0にリセットされます。獲得タイミングのあまり時間は破棄されます。 CarryOver 報酬受取時に獲得済みのインターバル分だけ経過時間から減算されます。あまり時間は次回の待機にも引き継がれます。 放置報酬 放置報酬には放置時間が一定時間経過すると得られるアイテムの一覧を定義します。 付与する報酬は、「経験値＋アイテム」のように複数(最大10個)設定することができます。 さらに、待機時間内で報酬の内容にバリエーションをもてるように、複数の報酬リストを設定することができます。 例えば、10分待機する毎に「経験値+10」と「強化素材Lv.1 x 1」を入手できる。 ただし、60分毎のタイミングでは上記の報酬の代わりに「経験値+20」と「強化素材Lv.2 x 1」を入手できる。 上記のような例を考えてみましょう。 この場合、放置報酬には以下のようなテーブルを設定します。 - 報酬1 報酬2 1 経験値+10 強化素材Lv.1 x 1 2 経験値+10 強化素材Lv.1 x 1 3 経験値+10 強化素材Lv.1 x 1 4 経験値+10 強化素材Lv.1 x 1 5 経験値+10 強化素材Lv. /ja/microservices/inbox/ Mon, 01 Jan 0001 00:00:00 +0000 /ja/microservices/inbox/ システムや運営からプレイヤーにメッセージやプレゼントを届ける仕組みを実現します。 ゲームでは「お詫び配布」「ログインボーナス」「課金特典」「イベント報酬」など、プレイヤーに非同期で報酬を届けるシチュエーションが頻繁に発生します。 GS2-Inbox はメッセージのキューイング、未読／既読管理、報酬の添付、有効期限による自動削除を提供し、ゲームのライフサイクル全般を通じてプレゼントボックス機能を担います。 sequenceDiagram participant Ops as 運営 / サーバー participant Inbox as GS2-Inbox participant Player as プレイヤー Ops->>Inbox: メッセージ送信 (報酬付き) Inbox-->>Player: receiveNotification 通知 Player->>Inbox: メッセージ一覧取得 Player->>Inbox: メッセージ開封 (Read) Inbox->>Player: 添付報酬を付与 (トランザクション) Player->>Inbox: 既読メッセージの削除 メッセージ 既読管理 メッセージは既読状態をもちます。 既読状態のメッセージをリストに残すか、リストから削除するかを設定が可能です。 ネームスペース設定の isAutomaticDeletingEnabled を有効にすると、既読化のタイミングでメッセージが自動削除されます。 プレゼントボックスの一覧には未受領のメッセージだけを残す仕様を、サーバー側の追加実装なしで実現できます。 報酬の添付 メッセージには報酬を添付することが可能です。 既読フラグを立てる代わりに、メッセージに添付された報酬を受け取ることができます。 添付できる報酬は GS2 のトランザクション機構を介した入手アクション（readAcquireActions）として表現されるため、GS2-Inventory GS2-Money GS2-Experience など、任意のマイクロサービスのリソースを報酬として配布できます。 有効期限 メッセージには有効期限（expiresAt）を設定できます。 有効期限を迎えたメッセージは、未読状態、開封後の既読状態にかかわらず、自動的に削除されます。 添付された報酬を受け取っていなかったとしても削除されます。 メッセージのライフサイクル stateDiagram-v2 [*] --> Unread: メッセージ受信 Unread --> Read: 開封 (Read) Unread --> Expired: 有効期限切れ Read --> Deleted: 削除 (Delete) Read --> AutoDeleted: isAutomaticDeletingEnabled Read --> Expired: 有効期限切れ Deleted --> [*] AutoDeleted --> [*] Expired --> [*] グローバルメッセージ 特定のプレイヤーではなく、全プレイヤーに対して同一のメッセージを配布したい場合は「グローバルメッセージ」を使用します。 グローバルメッセージはマスターデータとして定義し、各プレイヤーが ReceiveGlobalMessageAsync を呼び出した際に、まだ受け取っていないメッセージをそのプレイヤーの受信ボックスにコピーします。 /ja/microservices/inventory/ Mon, 01 Jan 0001 00:00:00 +0000 /ja/microservices/inventory/ プレイヤーが所持しているアイテムの情報を管理します。 アイテムの管理には3種類の方式があります。 1つ目はスタンダードインベントリ、2つ目はシンプルインベントリ、3つ目は巨大インベントリです。 スタンダードインベントリは以下のような機能を有します インベントリの容量制限 同一アイテムを一定数量ごとに複数のスタックに分割 アイテムに有効期限を設定 シンプルインベントリはスタンダードインベントリが持つような機能は持ちません しかし、その代わりに複数のアイテムの増減処理をまとめて行うことができます。 シンプルインベントリをうまく利用することで、APIのコール数を削減することが可能です。 巨大インベントリはシンプルインベントリと同じくスタンダードインベントリが持つような機能は持ちません。 シンプルインベントリのように複数のアイテムの増減処理をまとめて行うこともできません。 その代わり、アイテムの所持数量を 64bit 整数の範囲を超えて保持することができます。 スタンダードインベントリ インベントリ プレイヤーが所持するカバンに相当するエンティティです。 カバンには容量が設定可能で、その容量を超えるアイテムを格納することはできません。 アイテム アイテムは所持品の種類を定義します。 アイテムには、スタック可能な最大数量を指定できます。 たとえば、ポーションというアイテムの種類が存在し、最大99個スタック可能とした場合 インベントリの容量の消費量1で99個までポーションを所持することが可能となります。 さらに、アイテムには複数スタックを所持可能かを指定できます。 複数スタック所持を可能に設定すると、100個以上のポーションを所持できるようになり、 例えば、150個のポーションを所持している場合は 99 個スタックされたポーションと、51個スタックされたポーションの2つのエントリが作成され、 インベントリの容量が 2 消費されます。 複数スタック所持を不可能の設定した場合、99個を超えるポーションを所持することはできなくなり それ以上ポーションを入手しても破棄されます。 アイテムの有効期限 アイテムには有効期限を設定できます。 有効期限を設定したアイテムは、設定時刻をすぎると自動的にインベントリから消去されます。 有効期限の設定されたアイテムは有効期限ごとに異なるスタックが作成され、それぞれインベントリの容量を消費します。 そのため、複数スタックを所持できないアイテムに有効期限をつけて配布すると、最初に入手した有効期限のアイテム（あるは最初に入手した有効期限のないアイテム）以外は破棄されます。 アイテムを使用する際には明示的に有効期限（アイテムセット名）を指定しなければ、有効期限の近いアイテムから優先して消費されます。 アイテムセット 1種類のアイテムを複数スタック管理できるよう、アイテムの種類をまとめたアイテムセットというエンティティが存在します。 このエンティティはスタックごとにアイテムの種類を表すIDとは別に、スタック固有のIDをもちます。 このスタック固有のIDを使用すれば、「ポーション x 99」と「ポーション x 51」のそれぞれのスタックを明確に区別することができます。 参照元 (Reference Of) アイテムセットには「参照元」情報を付与することができます。これは、特定のアイテムが他のエンティティ（例：キャラクターの装備、パーティへの編成、マーケットへの出品など）から使用されていることを示すために利用されます。 参照元が1つ以上設定されているアイテムセットは、たとえ所持数量が十分であっても消費したり削除したりすることができなくなります。これにより、装備中のアイテムを誤って売却したり、強化素材にしてしまうといったミスをシステムレベルで防ぐことができます。 ポーションを消費する際に、ポーションを示すアイテムIDに加えてスタック固有のIDを指定することで、どちらのスタックから消費するかを明示することができます。 スタック固有のIDは省略可能で、省略した場合は最も少ないスタックから優先して使用されます。 シンプルインベントリ シンプルインベントリ プレイヤーが所持するカバンに相当するエンティティです。 複数のシンプルアイテムを束ねる存在で、シンプルインベントリでは特にプロパティを持ちません。 シンプルアイテム アイテムは所持品の種類を定義します。 巨大インベントリ 巨大インベントリ プレイヤーが所持するカバンに相当するエンティティです。 複数の巨大アイテムを束ねる存在で、巨大インベントリでは特にプロパティを持ちません。 巨大アイテム アイテムは所持品の種類を定義します。 スクリプトトリガー ネームスペースに acquireScript・overflowScript・consumeScript・simpleItemAcquireScript・simpleItemConsumeScript・bigItemAcquireScript・bigItemConsumeScript を設定すると、アイテムの入手・消費処理の前後でカスタムスクリプトを呼び出せます。スクリプトは同期・非同期の実行方式を選択でき、非同期では GS2-Script や Amazon EventBridge を介した外部処理にも対応します。 /ja/microservices/job_queue/ Mon, 01 Jan 0001 00:00:00 +0000 /ja/microservices/job_queue/ GS2-JobQueue はゲームサーバー上で実行する処理を非同期に積み上げるためのジョブキュー機能を提供します。 ゲームの処理には、すぐに結果を返す必要のないものや、サーバー側で時間をかけて段階的に進めたいものがあります。 そのような処理を「ジョブ」としてキューに登録しておき、後からプレイヤーがアクセスしたタイミングや明示的なAPI呼び出しによって実行することができます。 主な用途 GS2-Script を非同期に実行するための実行基盤 長時間処理を細かいステップに分割し、ステップごとにジョブとして登録して順次処理する ログイン中に発生したリワード配布などをまとめてサーバー側でトランザクション発行・実行 他マイクロサービスの完了通知ハンドラとして、後続処理を非同期に行う graph LR Producer["ジョブ登録元<br/>(他のマイクロサービス / GS2-Script)"] --> Queue["GS2-JobQueue"] Queue --> Run["プレイヤーが Run を実行<br/>または 自動実行"] Run --> Script["GS2-Script"] Script -- 成功 --> Result["JobResult として記録"] Script -- 失敗 --> Retry{"最大試行回数<br/>に到達?"} Retry -- No --> Queue Retry -- Yes --> DeadLetter["DeadLetterJob として保管"] 自動実行モード ネームスペースの設定で enableAutoRun を有効にすると、各マイクロサービスのAPI処理の最後にユーザーのキューに積まれているジョブを自動的に実行します。 プレイヤーがアプリを操作するだけで、サーバー側に積まれたジョブが順次消化されていきます。 enableAutoRun を無効にする場合は、クライアントから明示的に Run API を呼び出してジョブを実行する必要があります。 ジョブ結果 ジョブの実行結果は試行回数(tryNumber)ごとに JobResult として記録されます。 JobResult には GS2-Script の終了コード・実行ログ・結果ペイロードなどが含まれ、後から実行履歴を確認することができます。 通知設定 ネームスペースの設定で runNotification ・ pushNotification を構成しておくと、ジョブが実行されたとき、または新規にジョブがキューに積まれたときに GS2-Gateway を経由してクライアントへ通知できます。 この通知をフックに、クライアント側で残り情報を再取得するといった連携が可能です。 /ja/microservices/key/ Mon, 01 Jan 0001 00:00:00 +0000 /ja/microservices/key/ GS2-Key は、GS2 内で利用される暗号化キー (共通鍵) を管理し、AES による暗号化・復号 API を提供するサービスです。 機密性の高いデータをサーバー側で暗号化・復号する用途のほか、GS2 自身が内部的に利用する各種署名・暗号化処理の鍵管理基盤としても利用されます。 暗号化キーの管理 GS2-Key では、暗号化キーをネームスペース配下に作成して管理します。 キーには次のような情報を持たせることができます。 キー名 説明 (description: 用途や説明など、運用上の識別に利用) 実際の暗号化に使用される秘密鍵 (シークレット) は、キーの作成時に GS2 側で安全に生成され、GS2 内部に保管されます。秘密鍵自体をクライアント側に取り出して利用する設計ではなく、暗号化・復号のリクエストを GS2-Key に送信して結果のみを受け取る仕組みとなっています。 graph TD App["アプリケーション"] -->|Encrypt(平文)| Key["GS2-Key"] Key -->|暗号文| App App -->|サーバーに保管<br/>または送信| Storage["データストア"] Storage -->|暗号文| App2["アプリケーション"] App2 -->|Decrypt(暗号文)| Key Key -->|平文| App2 利用シーン GS2 内部での利用 GS2-Account のパスワード署名や、GS2-Auth のトークン発行など、GS2 内部で機密データを扱うマイクロサービスは GS2-Key が管理するキーを利用しています。各マイクロサービスのネームスペースを作成する際にキーを指定することで、そのネームスペース内で必要となる暗号化処理に利用されます。 アプリケーション独自データの暗号化 アプリケーション独自で機密情報を扱う場合にも、GS2-Key の Encrypt / Decrypt API を直接呼び出して暗号化・復号を行うことができます。秘密鍵をアプリケーション内に組み込むことなく、サーバーサイドでの暗号化が実現できます。 機密性の高い設定値や、外部サービスへの認証情報などを GS2 側で安全に管理したい場面で活用できます。 トランザクションアクション GS2-Key ではトランザクションアクションを提供していません。 マスターデータ管理 GS2-Key ではマスターデータの登録はありません。マネージメントコンソール、GS2-Deploy、API を通じてキーを作成・管理します。 /ja/microservices/limit/ Mon, 01 Jan 0001 00:00:00 +0000 /ja/microservices/limit/ プレイヤーが行動できる回数を制限するための仕組みです。 「1日に5回までガチャを引ける」「1週間に1度だけ受け取れる報酬」など、ゲーム内で頻出する回数制限を一元的に管理できます。 graph LR Action["プレイヤーの行動"] --> CountUp["カウントアップ (maxValue 指定)"] CountUp -- 上限に達していない --> Success["処理を許可"] CountUp -- 上限に達している --> Failure["処理を拒否"] Reset["リセット周期"] --> Counter["カウンターを 0 に戻す"] カウンター プレイヤーの行動回数を表現するためのエンティティで、 カウンターの値を上昇する際に許容可能な最大値を指定してカウントアップを試みることで最大値を超える場合はカウントアップが失敗し、後続の処理を失敗させることができるメカニズムで回数制限を実現します。 このとき、カウンターに対して最大値が存在するのではなく、カウントアップアクションに最大値が設定できるのが特徴です。 たとえば、スタミナの回復処理を例に考えてみます。 多くのゲームでは1日にスタミナを回復できる回数には上限が設けられています。 そして、回復をすればするほど、回復に必要な金額が上昇していきます。 このような仕様は以下のように表現できます。 ティアー 回復に必要なコスト 実行できる回数 Tier.1 5 10 Tier.2 10 10 Tier.3 20 10 Tier.4 40 10 そして、これを 回数制限のカウントアップアクションと、回復に必要なコストとして捉えたのが以下です。 ティアー カウンター名 カウンターの上昇量 カウンターの最大値 回復に必要なコスト Tier.1 RecoveryStaminaCounter 1 10 5 Tier.2 RecoveryStaminaCounter 1 20 10 Tier.3 RecoveryStaminaCounter 1 30 20 Tier.4 RecoveryStaminaCounter 1 40 40 全てのティアーで同じカウンターを使用し、回復に必要なコストが安いものほど、カウンターの最大値を低く設定しています。 /ja/microservices/lock/ Mon, 01 Jan 0001 00:00:00 +0000 /ja/microservices/lock/ GS2-Lock は、リソース単位で動作するミューテックスを提供し、複数のサーバープロセス・複数の処理系から同一リソースへ同時にアクセスすることを防ぐための分散排他制御サービスです。 ゲームの運営では「同じプレイヤーに対して同じ処理を二重に実行してしまう」「異なるバックエンドサーバーが同じデータを同時に書き換えてしまう」といった問題が容易に発生します。GS2-Lock を利用すると、これらの問題をマイクロサービスとして提供される共有ミューテックスによって防ぐことができます。 ミューテックスの基本 GS2-Lock のロックは「ネームスペース」「ユーザーID」「プロパティID」の組み合わせによって識別される「ミューテックス」というリソースに対して取得します。 プロパティID には、排他制御を行いたいリソースを一意に識別する任意の文字列を指定します。例えば「ガチャの抽選処理」「アイテムの所持数更新」「外部連携への通知送信」など、二重実行を避けたい処理ごとに異なるプロパティIDを割り当てる運用が考えられます。 graph TD Server1["バックエンドサーバーA"] -->|Lock| Mutex["GS2-Lock<br/>ミューテックス"] Server2["バックエンドサーバーB"] -->|Lock 待機| Mutex Mutex -->|取得成功| Server1 Server1 -->|Unlock| Mutex Mutex -->|取得成功| Server2 トランザクションID ロックを取得する際にはトランザクションIDを指定します。同じトランザクションIDで同じミューテックスに対して再帰的にロックを取得した場合、参照カウントが加算されるリエントラントロックとして振る舞います。解放時には同数の Unlock を実行することでロックが完全に解放されます。 異なるトランザクションIDによる二重取得は競合となり、先に取得したセッションがロックを解放するまで待機状態となります。 TTL による自動解放 ロックには TTL (Time To Live) を設定でき、TTL を経過するとロックは自動的に解放されます。 これにより、ロックを取得した処理系が異常終了したり、ネットワーク障害でロック解放処理が呼び出されなかった場合でもデッドロックを防ぐことが可能です。TTL は処理の最大想定実行時間に応じて適切な値を設定してください。 マルチタイトル・複数バックエンド間での排他 GS2-Lock は GS2 のマイクロサービスとして提供されるため、マルチタイトル間や複数のバックエンドサーバー、複数のリージョン間で共通の排他制御を実現できます。 GS2-Script から呼び出すことで、サーバーサイドスクリプトの内部から他のスクリプト実行や外部処理との排他制御を行うことも可能です。 トランザクションアクション GS2-Lock ではトランザクションアクションを提供していません。 マスターデータ管理 GS2-Lock ではマスターデータの登録はありません。ネームスペースを作成するだけで利用を開始できます。 実装例 GS2-Lock は管理API/サーバーサイドAPI中心のマイクロサービスです。ゲームエンジン用 SDK (Unity/Unreal Engine) には専用の Domain クラスが提供されていません。 主に GS2-Script 内のサーバーサイドロジックや、自社のバックエンドサーバーから利用することを想定しているため、ゲームクライアントから直接呼び出すのではなく、以下のいずれかの手段で操作することを推奨します。 GS2-Script からの呼び出し (サーバーサイドスクリプト経由の排他制御) 各種言語向け一般SDK (C# / Go / Python / TypeScript / PHP / Java) によるバックエンドサーバーからの呼び出し マネジメントコンソール (動作確認・運用時) GS2 CLI 各種SDKの詳細は対応するリファレンスページを参照してください。 /ja/microservices/log/ Mon, 01 Jan 0001 00:00:00 +0000 /ja/microservices/log/ GS2-Log はゲームに組み込まれた全ての Game Server Services マイクロサービスのAPIアクセスログを集約・保存する機能を提供します。 ゲームの運営において「いつ・誰が・どのAPIを・どのような引数で呼び出し・どのような結果を返したか」を後から追跡できることは非常に重要です。 不正なプレイヤーの調査、ゲームバランスの確認、お問い合わせ対応、KPI 集計などのあらゆる運用業務の基盤として GS2-Log のデータを活用できます。 GS2-Log の機能はゲームクライアントから直接利用するものではなく、運営側のツールやデータ分析基盤と連携して活用するためのものです。 ログの種類 GS2-Log は以下の4種類のログを記録します。 AccessLog 各マイクロサービスのAPIが呼び出されるたびに記録されるログです。 timestamp: API呼び出し時刻 requestId: リクエストを一意に識別するID service: 呼び出されたマイクロサービス名 method: 呼び出されたAPIメソッド名 userId: 呼び出し元のユーザーID request: リクエストパラメーター (JSON文字列) result: 応答内容 (JSON文字列) API単位の細かい挙動追跡が可能で、不具合の調査や行動ログの分析に利用できます。 IssueStampSheetLog トランザクションが発行された際に記録されるログです。 トランザクションは Game Server Services における入手・消費アクションのまとめ実行単位であり、発行時の消費アクション一覧と、何をきっかけに発行されたのかを記録します。 timestamp: 発行時刻 transactionId: トランザクションID(トランザクション発行単位の識別子) service: 発行元マイクロサービス method: 発行元API userId: ユーザーID action: 入手アクション args: アクションの引数 tasks: トランザクションに含まれる消費アクション一覧 ExecuteStampSheetLog / ExecuteStampTaskLog トランザクション全体・消費アクションが実行された際に記録されるログです。 IssueStampSheetLog と組み合わせることで、いつ発行されたトランザクションが、いつどのように実行されたかをトレースできます。 この情報は、リプレイ攻撃や不正な多重実行、サービス間の整合性問題の検知に活用できます。 sequenceDiagram participant Client participant ServiceA as マイクロサービスA participant Sheet as トランザクション participant ServiceB as マイクロサービスB participant Log as GS2-Log Client->>ServiceA: 報酬リクエスト ServiceA->>Log: AccessLog ServiceA->>Sheet: トランザクション発行 ServiceA->>Log: IssueStampSheetLog Sheet->>ServiceB: 消費アクション実行 ServiceB->>Log: ExecuteStampTaskLog Sheet->>Log: ExecuteStampSheetLog ログのエクスポート先 GS2-Log で記録したログは、ネームスペースの設定で指定したエクスポート先に転送できます。 /ja/microservices/login_reward/ Mon, 01 Jan 0001 00:00:00 +0000 /ja/microservices/login_reward/ ゲームに毎日ログインしたプレイヤーへ報酬を配布する仕組みです。 日替わりのアイテム配布や、7日／30日サイクルでループするログインボーナス、見逃した日の報酬を後から補償する機能など、運営現場でよく使われるパターンを汎用的に提供します。 モード ログインボーナスの提供方法は《スケジュールモード》と《ストリーミングモード》2種類の方式があります。 graph LR Mode{ボーナスモード} --> Schedule["スケジュールモード<br/>(mode: schedule)"] Mode --> Streaming["ストリーミングモード<br/>(mode: streaming)"] Schedule -- 日付に固定 --> SchEx["1日目=金貨、2日目=銀貨…<br/>取り逃しはスキップ"] Streaming -- 順番に消化 --> StrEx["1個目=金貨、2個目=銀貨…<br/>取り逃しても次回に持ち越し"] Streaming --> Repeat{"repeat 設定"} Repeat -- enabled --> Loop["終端到達後に先頭から再開"] Repeat -- disabled --> Stop["終端で停止"] スケジュールモード GS2-Schedule のイベントと関連付けて利用します。 報酬として配布するトランザクションアクションを各日程分定義します。 イベントの開始日時から24時間ごとに報酬が変化し、各報酬を1回受け取ることができます。 途中で取り逃がした報酬があった場合は、スキップされます。 ストリーミングモード ストリーミングモードはストリームに設定された報酬として配布するトランザクションアクションを先頭から順番に配布します。 受け取らなかった日があったとしても、スキップはされずストリームの次の報酬が手に入ります。 ストリーミングモードのログインボーナスに GS2-Schedule のイベントを関連づけると、イベントの開始日時から24時間ごとにストリームの次の報酬を受け取ることができます。 設定しない場合は、報酬の種類が変化する時間をUTCタイムゾーンの24時間単位で指定して利用します。 繰り返し ストリーミングモードのログインボーナスには繰り返し設定ができます。 繰り返し設定（repeat: enabled）を有効にすると、ストリームの終端に到達した場合 翌日はストリームの先頭から報酬の受け取りを再開できます。 この機能を利用することで、常設のログインボーナスを7日ごとや30日ごとにループさせることができます。 repeat: disabled を選択すると、ストリームの最後まで配布した後はそのボーナスからの報酬入手は停止します。期間限定キャンペーンなどに利用できます。 見逃し補償 スケジュールモードで取り逃がした場合や、ストリーミングモードでもイベント開催期間中ではストリームのすべてのアイテムを入手できないような状態に陥った時に使える機能が見逃し補償機能です。 設定されたコストを支払うことで、取り逃がしたアイテムを入手することができます。 見逃し補償が利用できるのは GS2-Schedule のイベントと関連づけられたログインボーナスのみで、イベントの開始日からの経過日数までの報酬のみが受け取れます。 つまり、未来のログインボーナスはコストを支払っても受け取ることはできません。 見逃し補償のコストとして、missedReceiveReliefConsumeActions に GS2-Money2 などの消費アクションを設定でき、ジェムを消費して見逃した日を取り戻すといった運用が可能です。 受け取りの前提条件として missedReceiveReliefVerifyActions に検証アクションを指定することもできます。 /ja/microservices/lottery/ Mon, 01 Jan 0001 00:00:00 +0000 /ja/microservices/lottery/ ガチャを実装するための仕組みです。 GS2-Lottery では、通常ガチャとボックスガチャに対応しています。 graph TD Trigger["抽選トリガー<br/>(GS2-Showcase の購入報酬 / クエストクリア報酬 など)"] --> LotteryModel["LotteryModel<br/>(抽選モデル)"] LotteryModel -- "mode = normal" --> Normal["通常モード抽選"] LotteryModel -- "mode = box" --> Box["ボックスモード抽選"] Normal --> PrizeTable["景品テーブル<br/>(PrizeTable)"] Box --> BoxData["プレイヤー専有ボックス"] PrizeTable --> Prize["Prize<br/>(acquireActions)"] BoxData --> Prize Prize --> Acquire["GS2-Distributor<br/>報酬配布"] 通常ガチャ 通常ガチャは指定された確率で純粋な抽選を行います。 景品テーブル 景品テーブルとは、ガチャを実行した時に出てくる景品の排出確率を定義したものです。 マスターデータとして定義することになります。 重み 景品テーブルでの確率の設定は、景品ごとの重みを設定します。 具体的には以下のようなテーブルを作成することになります。 重み 景品A 1 景品B 2 景品C 4 これを百分率による確率として解釈すると以下のように解釈できます。 重み 確率 景品A 1 14.285% 景品B 2 28.571% 景品C 4 57.143% 百分率ベースで確率を設定する必要がある場合、全てを足して100%になるよう考える必要がありますが 重みベースで確率を設定する場合は、そのような負担をする必要がなくなります。 /ja/microservices/matchmaking/ Mon, 01 Jan 0001 00:00:00 +0000 /ja/microservices/matchmaking/ プレイヤーを条件に基づいてグルーピングする機能です。 対戦相手を見つけるために利用することができます。 スクリプトトリガー ネームスペースに createGatheringTriggerScriptId ・ completeMatchmakingTriggerScriptId ・ changeRatingScript を設定すると、ギャザリング作成完了時・マッチング完了時・レーティング変動時にカスタムスクリプトを実行できます。 設定できる主なイベントトリガーとスクリプト設定名は以下の通りです。 createGatheringTriggerScriptId: ギャザリング作成完了時 completeMatchmakingTriggerScriptId: マッチング完了時 changeRatingScript: レーティング変動時 プッシュ通知 設定できる主なプッシュ通知と設定名は以下の通りです。 joinNotification: マッチング参加時に通知 leaveNotification: マッチング離脱時に通知 completeNotification: マッチング完了時に通知 changeRatingNotification: レーティング変動時に通知 いずれも GS2-Gateway 経由で通知でき、オフライン端末へのモバイルプッシュ転送も可能です。 マスターデータ運用 マスターデータを登録することでマイクロサービスで利用可能なデータや振る舞いを設定できます。 マスターデータの種類には以下があります。 RatingModel: レーティング計算設定 SeasonModel: シーズン期間設定 マスターデータの登録はマネージメントコンソールから登録する他、GitHubからデータを反映したり、GS2-Deployを使ってCIから登録するようなワークフローを組むことが可能です。 追加設定 enableDisconnectDetection を有効化するとマッチメイキング中の切断検知を行い、disconnectDetectionTimeoutSeconds でタイムアウトを調整できます。また enableCollaborateSeasonRating を設定するとマッチメイキング完了時に GS2-SeasonRating と連携し、結果を受け付けるセッションを生成できます。 トランザクションアクション GS2-Matchmaking では以下のトランザクションアクションを提供しています。 検証アクション: 永続ギャザリングへの参加状況の検証 「永続ギャザリングへの参加状況の検証」を検証アクションとして利用することで、特定のシーズンギャザリング（チームやクラスター）に所属しているプレイヤーのみが受け取れる報酬の設定などが可能になります。これにより、シーズンごとのグループ対抗イベントや、特定のコミュニティ限定のインセンティブ付与といった施策をトランザクション内で安全に制御できます。 ユースケース別設計ガイド パーティトークンを使ったマッチメイキング マッチメイキング完了後に1名が離脱し補充したい場合や、事前にパーティを編成してからマッチメイキングを行いたい場合は「パーティトークン」を使用します。 パーティメンバーはそれぞれプレイヤートークン（有効期限3分）を発行し、パーティの代表者に送信します。代表者はパーティトークン発行APIに送信することでパーティトークン（有効期限10分）を入手し、ギャザリング作成またはギャザリング検索を呼び出します。これにより、パーティメンバー全員が参加した状態のギャザリングを作成または参加できます。 パーティ同士のマッチメイキング たとえば4 vs 4 の対戦で事前に編成したパーティを分散させたくない場合、まず4人のマッチメイキングを実行してパーティ単位のギャザリングを作成し、その後各パーティの代表者が定員2人のマッチメイキングを行うことでパーティ同士のマッチメイキングを実現できます。 マッチメイキング中のプレイヤー間の通信 マッチメイキング完了前にプレイヤー間でのやりとりが必要な場合、ギャザリング作成時に以下の2つの方法を使用できます。 GS2-Chat と連携したチャットルーム作成: メタデータの低頻度（秒間3回以内）交換に適しています GS2-Realtime と連携したゲームサーバの起動: 高頻度の通信や、人数が不足した状態でゲームを遊ばせたい場合に適しています マッチメイキング完了後の処理 マッチメイキングが完了したときに以下の方法でプレイヤーに通知できます。 /ja/microservices/mega_field/ Mon, 01 Jan 0001 00:00:00 +0000 /ja/microservices/mega_field/ GS2-MegaField は、巨大な3D空間上に存在する大量のプレイヤーの位置情報を、効率的に共有・同期するための機能を提供します。 MMORPG やオープンワールド、メタバース型のサービスなど、同じワールドに大量のプレイヤーが同時にログインするタイトルでは、すべてのプレイヤーの位置情報を全プレイヤーに配信していると、ネットワーク帯域もCPUも破綻してしまいます。 GS2-MegaField は「自分の近傍にいるプレイヤーだけ」を効率的に取得できるようにすることで、この問題を解決します。 エリアとレイヤー GS2-MegaField の空間は「エリア (Area)」と「レイヤー (Layer)」の2つの概念で構成されます。 AreaModel (エリアモデル): 1つの大きな3D空間を表すマスターデータ。たとえば「街の中」「ダンジョン」「フィールド」など、ワールド内の論理的な区画ごとに作成します。 LayerModel (レイヤーモデル): 1つのエリアの中に存在する、用途別のレイヤー。たとえば「プレイヤー用」「NPC用」「アイテム用」のように、同じ場所を異なる目的で重ねて利用できます。 エリアモデルは複数のレイヤーモデルを内包する形でマスターデータとして定義します。 プレイヤーの位置は「どのエリアの、どのレイヤーに、どの座標に居るか」という形で表現されます。 graph TD AreaModel["AreaModel: town"] --> LayerPlayer["LayerModel: player"] AreaModel --> LayerNpc["LayerModel: npc"] AreaModel --> LayerItem["LayerModel: item"] Player1["Player A"] -- Spot --> LayerPlayer Player2["Player B"] -- Spot --> LayerPlayer 空間インデックス GS2-MegaField は、レイヤー内のプレイヤーの位置を空間インデックス (R-Tree ベースの構造) で管理します。 これによって「自分の周囲 N メートル以内に居るプレイヤーをすべて取得する」といった近傍探索を、プレイヤー数に依存せず効率的に処理できます。 レイヤー単位で空間インデックスは独立しており、「プレイヤー同士の近傍」と「NPC との近傍」のような検索を別々に取り扱えます。 プレイヤーの位置情報 各プレイヤーは「自分の現在位置」を MyPosition として GS2-MegaField に送信します。 MyPosition には以下の情報が含まれます。 position: 3D 座標 (x, y, z) vector: 向きベクトル (x, y, z) r: 視界・関心の半径 プレイヤーは位置を送信する際に、同時に「自分が興味のある範囲」を Scope として指定でき、その範囲に居る他のプレイヤーの情報を応答として受け取ることができます。 Scope には以下の情報が含まれます。 /ja/microservices/mission/ Mon, 01 Jan 0001 00:00:00 +0000 /ja/microservices/mission/ ゲーム内の蓄積した行動に基づいて、プレイヤーに報酬を与えるための仕組みです。 一般的に 実績・トロフィー・ミッション と呼ばれる機能を実現するための機能です。 graph TD Action["ゲーム内行動<br/>(クエストクリア / ガチャ実行 など)"] -- "カウンター上昇<br/>(IncreaseCounterByUserId)" --> Counter["ミッションカウンター<br/>(Counter / Scope)"] Counter -- "目標値到達" --> Task["ミッションタスク<br/>(MissionTaskModel)"] Task -- "ReceiveRewards" --> Reward["completeAcquireActions"] Reward --> Distributor["GS2-Distributor<br/>報酬配布"] Task --> Group["ミッショングループ<br/>(MissionGroupModel)"] Group -- "resetType に基づき<br/>受取フラグをリセット" --> Task ミッションカウンター プレイヤーの行動に基づく回数を数えるためのエンティティです。 「クエストをクリアした回数」「キャラクターを強化した回数」「ガチャを引いた回数」といったゲーム内の行動回数をカウントするためのカウンターを用意します。 カウンターにはスコープを設定できます。 スコープには以下の値を設定可能です。 スコープの種類 スコープの内容 リセットしない ゲームプレイ開始からの総計 毎日X時にリセット 当日実行した回数 毎週X曜日X時にリセット 今週実行した回数 毎月X日X時にリセット 今月実行した回数 一定日数ごとにリセット 基準時刻から指定日数ごとにリセット 検証アクションにマッチした時だけカウントアップ verifyAction の実行結果に基づいてカウンターを上昇 カウンターの値は各スコープで管理され、ミッションの達成条件には各スコープの値を利用できます。 graph LR Up["カウンター上昇要求"] --> Counter["Counter"] Counter --> Scope1["スコープ1<br/>リセットしない"] Counter --> Scope2["スコープ2<br/>毎日リセット"] Counter --> Scope3["スコープ3<br/>毎週リセット"] Scope1 -- ScopedValue --> Mission1["累計100回ミッション"] Scope2 -- ScopedValue --> Mission2["デイリー10回ミッション"] Scope3 -- ScopedValue --> Mission3["ウィークリー50回ミッション"] 検証アクションによるスコープ制御 scopeType=verifyAction を利用すると、conditionName と condition により任意条件を定義し、 他のマイクロサービスの検証結果に応じてカウンターを上昇するかの制御ができます。 これにより、特定のイベント期間だけカウンターを上昇するスコープや、特定のキャラクターを編成している状態でのみ上昇するスコープを作ることができます。 /ja/microservices/money/ Mon, 01 Jan 0001 00:00:00 +0000 /ja/microservices/money/ Warning GS2-Money2 がリリースされました。 特別な理由がない限りは新しく利用する場合は GS2-Money2 を利用してください。 ゲーム内のリソースのうち、現金相当の価値を持つリソースを扱う機能です。 日本の資金決済法の前払い式支払い手段（自家型）に該当する資産を取り扱う場合は必ずこの機能を利用してください。 残高 GS2-Money はプレイヤーのもつ課金通貨の残高を単純な数量では管理せず、購入時の価値ごとに数量を管理します。 例えば、100円で100個の課金通貨を購入した場合は課金通貨1個の価値は1円相当となります。 同時に1000円で1200個の課金通貨を購入できるとしましょう。あくまで課金通貨の単価は1円とし、200個はおまけとして無料で処理するのも一つの手段ですし、1000円で購入した場合は単価を 0.8334円 として異なる単価で扱うのも一つの手段です。 後者のような方式を採用した場合、GS2-Money は「単価1円の課金通貨の残高」「単価0.8334円の課金通貨の残高」をそれぞれ分けて管理する機能を持っています。 graph TD Wallet["ウォレット<br/>(スロット番号で区別)"] Wallet --> Paid["有償通貨<br/>(paid)"] Wallet --> Free["無償通貨<br/>(free)"] Paid --> Detail1["単価1円の残高"] Paid --> Detail2["単価0.8334円の残高"] Paid --> Detail3["...購入価値ごと"] 後者を選択するメリットは？ 明らかに後者は会計処理が複雑になり、メリットがないように感じるかもしれません。 サービス提供側としては全くのその通りです。しかし、立場を変えてゲームプレイヤーの立場で考えてみましょう。 ゲームの中には運営によって配られた現金相当の価値が0円の課金通貨（通称 無償通貨）があります。 プレイヤーに課金通貨を購入してもらうために、有償で購入した課金通貨(通称 有償通貨)でしか購入できない魅力的な商品を課金通貨300個で販売したとしましょう。 1000円 で 1200個の課金通貨を購入した際に、1000個の有償通貨と200個の無償通貨 を付与するように処理した場合 プレイヤーは有償通貨300個で購入できる商品を3回しか購入できません。 一方で、単価を0.8334円として1200個全てを有償通貨として取り扱う方法であればプレイヤーは4回購入できます。 この差はプレイヤー心理に多少なりとも影響を与えます。 会計上の都合を優先するか、プレイヤーの利益を優先するか 慎重に検討するべき仕様でしょう。 スロット GS2-Money ではウォレットを複数持つことができます。 その複数のウォレットを区別するためのキーがスロットです。 この機能は他のプラットフォームで購入した課金通貨を持ち込ませないようにしているプラットフォーマーが存在するため、そのガイドラインを遵守するために存在する機能です。 しかし、これらのガイドラインは有償通貨にのみ適用されるため、無償通貨については全てのスロットで共有できる機能があります。 ネームスペースの shareFree を true に設定すると、無償通貨は全スロット共通の残高として扱われます。 消費優先度 プレイヤーが課金通貨を消費する時に、無償通貨を優先して消費するか、有償通貨を優先して消費するかを選択できます。 一般的に無償通貨を優先して消費する仕様が採用されますが、会計上の都合がある場合は有償通貨を優先できます。 有償通貨を消費する場合は、より単価の高い通貨から優先して消費されます。 ネームスペースの priority で以下のいずれかを指定します。 /ja/microservices/money2/ Mon, 01 Jan 0001 00:00:00 +0000 /ja/microservices/money2/ Tip GS2-Money2 は名前の通りバージョン2に相当するマイクロサービスです。 以前のバージョンに関するドキュメントは GS2-Money を参照してください。 ゲーム内のリソースのうち、現金相当の価値を持つリソースを扱う機能です。 日本の資金決済法の前払い式支払い手段（自家型）に該当する資産を取り扱う場合は必ずこの機能を利用してください。 GS2-Money2 は単に「課金通貨の残高」を扱うサービスではなく、以下のような会計・法令対応上の要件をまとめて引き受けるマイクロサービスです。 入金日時・単価ごとの残高管理 レシート検証による不正入金の防止 ウォレットの加減算履歴の保持 プラットフォームのガイドラインに沿った通貨の隔離 サブスクリプション（期間課金）契約の状態管理 未使用残高の集計（前払式支払手段への対応） 残高 GS2-Money2 はプレイヤーのもつ課金通貨の残高を単純な数量では管理せず、購入時の価値ごとに数量を管理します。 例えば、100円で100個の課金通貨を購入した場合は課金通貨1個の価値は1円相当となります。 同時に1000円で1200個の課金通貨を購入できるとしましょう。あくまで課金通貨の単価は1円とし、200個はおまけとして無料で処理するのも一つの手段ですし、1000円で購入した場合は単価を 0.8334円 として異なる単価で扱うのも一つの手段です。 後者のような方式を採用した場合、GS2-Money2 は「単価1円の課金通貨の残高」「単価0.8334円の課金通貨の残高」をそれぞれ分けて管理する機能を持っています。 後者を選択するメリットは？ 明らかに後者は会計処理が複雑になり、メリットがないように感じるかもしれません。 サービス提供側としては全くのその通りです。しかし、立場を変えてゲームプレイヤーの立場で考えてみましょう。 ゲームの中には運営によって配られた現金相当の価値が0円の課金通貨（通称 無償通貨）があります。 プレイヤーに課金通貨を購入してもらうために、有償で購入した課金通貨(通称 有償通貨)でしか購入できない魅力的な商品を課金通貨300個で販売したとしましょう。 1000円 で 1200個の課金通貨を購入した際に、1000個の有償通貨と200個の無償通貨 を付与するように処理した場合 プレイヤーは有償通貨300個で購入できる商品を3回しか購入できません。 一方で、単価を0.8334円として1200個全てを有償通貨として取り扱う方法であればプレイヤーは4回購入できます。 この差はプレイヤー心理に多少なりとも影響を与えます。 会計上の都合を優先するか、プレイヤーの利益を優先するか 慎重に検討するべき仕様でしょう。 スロット GS2-Money ではウォレットを複数持つことができます。 その複数のウォレットを区別するためのキーがスロットです。 この機能は他のプラットフォームで購入した課金通貨を持ち込ませないようにしているプラットフォーマーが存在するため、そのガイドラインを遵守するために存在する機能です。 しかし、これらのガイドラインは有償通貨にのみ適用されるため、無償通貨については全てのスロットで共有できる機能があります。 ネームスペースの sharedFreeCurrency を有効にすると、無償通貨は全スロット共通として扱われ、有償通貨のみがスロットごとに隔離されます。 graph LR subgraph Wallets[Wallets] direction TB S0["Slot 0 (iOS)<br/>有償残高: 1,000"] S1["Slot 1 (Android)<br/>有償残高: 500"] S2["Slot 2 (Steam)<br/>有償残高: 800"] end Shared["無償残高: 200<br/>(sharedFreeCurrency=true)"] -. /ja/microservices/news/ Mon, 01 Jan 0001 00:00:00 +0000 /ja/microservices/news/ ゲーム内のお知らせをHTML形式で配信するための仕組みです。 配信するHTMLコンテンツは hugo(https://gohugo.io/) で生成する必要があります。 GS2-News は記事データをアップロードすると、GS2 側で hugo によるビルドを行い、静的な Web コンテンツとしてホスティングします。ゲームクライアントは配信された一時 URL に対してアクセスすることでお知らせを閲覧できます。 graph LR Author["運営者"] -- "ZIP アップロード" --> GS2["GS2-News"] GS2 -- "hugo build (公開/非公開の<br/>全パターンを事前生成)" --> CDN["CDN (HTML / ZIP)"] Player["プレイヤー"] -- "GetContentsUrl" --> GS2 GS2 -- "URL + Cookie<br/>(1時間有効)" --> Player Player -- "WebView or ZIP DL" --> CDN hugo hugo は静的 Webページを生成するためのジェネレーターです。 ページのレイアウトやデザインを決定するためのテンプレートと、マークダウン形式で記述した記事データをビルドすることでHTMLファイルを生成します。 hugo の利用方法については、hugoの公式サイト または 各種解説サイトをご確認ください。 GS2 では最小限の hugo テンプレートと記事データのサンプルを GitHub で公開しています。 https://github.com/gs2io/gs2-news-sample イベントと連動する記事 GS2-News では、GS2-Schedule で管理するイベントと連動する記事データを管理できます。 /ja/microservices/quest/ Mon, 01 Jan 0001 00:00:00 +0000 /ja/microservices/quest/ ゲームの進捗管理や、クエストの進捗管理を行います。 GS2-Quest はゲームのインゲーム（バトルやステージ）に挑戦するための「入口」と「出口」だけをサーバーで管理するマイクロサービスです。 インゲーム内部のロジックには関与せず、開始時のコスト消費・クリア時の報酬付与・前提条件の判定といった、サーバーで信頼すべき処理に責任を持ちます。 graph LR Start["クエスト開始<br/>StartAsync"] --> Battle["インゲームを実行<br/>(クライアント / 専用サーバー)"] Battle -- 成功 --> End1["クエスト終了報告<br/>EndAsync(isComplete:true)"] Battle -- 失敗 --> End2["クエスト終了報告<br/>EndAsync(isComplete:false)"] End1 --> Reward["クリア報酬を付与"] End2 --> FailedReward["失敗報酬を付与"] クエスト クエスト はインゲームの基本単位で、インゲームを開始する時に選択するエンティティです。 クエストには挑戦に必要なコストと、挑戦によって得られる報酬を設定でき、GS2-Quest はその開始・終了をAPIとして受け付けます。 つまり、GS2-Quest はインゲームの内容には関与しません。 クエストの挑戦コスト クエストを開始状態にするために必要なコストを設定します。 一般的には GS2-Stamina で管理するスタミナを消費したり、GS2-Inventory で管理するアイテムを消費するようなコストを設定します。 QuestModel の consumeActions に消費アクションを設定することで、Start 実行時にトランザクションとしてアトミックに処理されます。 クエストの検証条件 QuestModel の verifyActions に検証アクションを設定すると、クエスト開始時に追加の条件チェックを行えます。 たとえば「特定のアイテムを所持していること」「GS2-Dictionary に特定のエントリーが登録されていること」といった、消費せずに状態だけを確認する条件を表現できます。 クエストのクリア報酬 クエストに挑戦し、クリアした場合に得られる報酬を設定できます。 報酬には複数の種類（Contents）を用意することができます。各 Contents には抽選用の weight を設定でき、確率に応じてどの報酬パターンが適用されるかが決定されます。 この機能を利用すれば、一定の確率でレアモンスターが出現するバージョンのクエストが開始され、報酬が通常より豪華になるような設定が可能です。 初回クリア報酬 クエストを初めてクリアしたときにのみ、追加の報酬を得られるよう設定が可能です。 QuestModel の firstCompleteAcquireActions に入手アクションを設定します。 クリア報酬の減額 クエスト内で出現したモンスターを倒さなかった場合や、宝箱を見落とした場合にクエスト報酬を報酬から減額できます。 クエストの開始APIのレスポンスにはクエスト内で得られる報酬の最大値が応答され、クエストの完了APIにはそのうち実際に入手した数量をレポートします。 そのレポートの際に報酬を減らして報告することで減額が行われます。 報告の際に最大値を超える報酬をレポートしようとするとエラーが発生します。 /ja/microservices/ranking/ Mon, 01 Jan 0001 00:00:00 +0000 /ja/microservices/ranking/ Warning GS2-Ranking2 がリリースされました。 特別な理由がない限りは新しく利用する場合は GS2-Ranking2 を利用してください。 ゲームのスコアやクリアタイムを競うランキング機能を実現します。 ランキングには2種類存在し「参加者全員が同じボード上で競い合うもの」と「購読したプレイヤーのスコアと競い合うもの」があります。 前者はグローバルランキング、後者はスコープランキングと呼びます。 グローバルランキング グローバルランキングは全てのプレイヤーと競い合うためのランキング機能を提供します。 GS2-Ranking では、数億人以上のプレイヤーが参加するような大規模なランキングを実現できます。 その代わり、ランキングの集計はリアルタイムではなく、事前に設定した周期で集計処理が行われ その集計結果をベースに順位計算などを行います。 カテゴリ ランキングの種類を設定します。 順位づけをするにあたって、スコアが大きい方が優れているのか、小さい方が優れているのかを設定する必要があります。 集計間隔 ランキングの集計を行う間隔を設定します。最小15分、最大24時間の範囲で指定ができます。 集計間隔の設定で気をつけなければならないのは、ここで設定する間隔は前回の集計開始時刻からの間隔ではなく、前回の集計終了時刻からの間隔であることです。 集計処理に5分要する状況で、00:00 に初回の集計が動いた場合について考えてみます。 集計開始時刻 集計終了時刻 00:00 00:05 00:20 00:25 00:40 00:45 固定集計時刻 集計間隔を24時間に設定した際に、その集計される時刻を固定したいというニーズがあります。 このようなニーズに対応するために、指定時刻になったら集計周期になっていなくても集計を実行する機能を提供しています。 集計間隔に24時間、固定集計時刻に AM5時 を設定したとします。 集計開始時刻 集計終了時刻 2020-01-01 05:00 2020-01-01 05:05 2020-01-02 05:00 2020-01-02 05:05 ← 23時間55分しか経過していないが、固定集計時刻になったため集計する 2020-01-03 05:00 2020-01-03 05:05 ← 23時間55分しか経過していないが、固定集計時刻になったため集計する スコアの有効範囲 スコアとして登録を受け付ける値の範囲を設定できます。 これによって、明らかに不適切なスコアの登録があった時に登録処理を行わずに捨てることができます。 この場合、不正なスコアの境界を調べるのを困難にするため、クライアントにエラーは返りません。 スコアの登録可能期間 スコアの登録を受け付ける期間の設定として GS2-Schedule のイベントを関連づけることができます。 スコア受け付け期間外にスコアを送信してもスコアは捨てられます。 スコアの登録可能期間外は集計処理は行われないため、集計にまつわる費用は発生しませんが、 スケジュールの判定のために GS2-Schedule のAPIコールは発生します。 そのため、明らかに2度と参照しないランキングに関してはマスターデータから削除することを推奨します。 /ja/microservices/ranking2/ Mon, 01 Jan 0001 00:00:00 +0000 /ja/microservices/ranking2/ Tip GS2-Ranking2 は名前の通りバージョン2に相当するマイクロサービスです。 以前のバージョンに関するドキュメントは GS2-Ranking を参照してください。 ゲームのスコアやクリアタイムを競うランキング機能を実現します。 GS2-Ranking2 は以下の3種類のモードを提供します。 グローバルランキング クラスターランキング 購読ランキング ゲームが必要とするランキング機能の多くはこのいずれかのモードで要件を満たせるはずです。 ランキングモード グローバルランキング グローバルランキングは全てのプレイヤーと競い合うためのランキング機能を提供します。 GS2-Ranking2 では上位1000位のプレイヤーのみランキングに参加可能で、1000位以下のプレイヤーのスコアは送信したとしてもランキングへは登録されません。 以前のバージョンである GS2-Ranking が1億を超えるプレイヤーの正確な順位を返す能力を有する形で提供していましたので、以前のバージョンと比較して大きく仕様が変化しています。 GS2-Ranking では、多くのスコアを扱える代わりに、15分〜24時間の範囲で指定した集計間隔で集計が行われるまでランキングへの登録が行われない仕様で、集計の度に参加人数に応じたコストが生じていました。 GS2-Ranking を利用した開発者からのフィードバックを受けて GS2-Ranking2 は再設計されました。 具体的に以下の点を重要なフィードバックと捉えて再設計しています。 多くのユースケースにおいて上位プレイヤーのみ表示できればよい 順位の変化を即座にランキングへと反映したい プレイヤーの増加によるランキング集計コストの増加は望ましくない 結果として、前述のように上位1000人のプレイヤーのみがランキングに参加でき、1001位以下のプレイヤーは「圏外」として処理する仕組みになりました。 その代わりスコアの登録直後にランキングに反映され、通常のAPIリクエストコスト以上の追加コストは発生しません。 クラスターランキング 概ねグローバルランキングと同じ仕様ですが、唯一異なるのはクラスターIDごとに異なるランキングが作成されることです。 クラスターIDに GS2-Guild のギルドIDを指定することで、ギルドメンバー同士で競うようなランキングを実現するために利用できます。 クラスター参加判定 クラスターランキングでは、クラスターの種類を定義しておくことでスコア登録時にクラスターに参加しているか確認してからスコア登録を実行できます。 たとえば、GS2-Guild のギルドをクラスターとしたランキングを実現する場合、ランキングモードの設定でクラスターの種類に「Gs2Guild::Guild」を指定することで スコア登録時にクラスターIDで指定されたギルドにスコアを登録しようとしているプレイヤーがメンバーとして登録されていることを確認した上でスコアを登録するようにできます。 購読ランキング GS2-Ranking のスコープランキングに類似する仕様のランキング機能です。 他プレイヤーを購読することで、自分のランキングボードに他プレイヤーの最新のスコアを含めることが可能となります。 フレンド内ランキングのようなプレイヤー間で非対称性が強いランキングを実現するために使用します。 購読ランキングにおける反映遅延 スコアの登録を実行すると、プレイヤーを購読しているプレイヤーのランキングに非同期でスコア登録が実行されます。 この処理は通常1秒以内に実行されますが、非同期処理のためスコアが反映されるまで若干の遅延が生じます。 シーズン 各ランキングにはスコアの登録を受け付ける期間として GS2-Schedule のイベントを関連づけることが可能です。 GS2-Schedule のイベントには繰り返し設定が可能で、各ランキングはイベントが繰り返す度にリセットされます。 この機能を実現するために、GS2-Ranking2 は各ランキングに シーズン というプロパティを持っています。 ランキングの結果はシーズンごとに格納され、過去のシーズンの結果をいつでも参照することができます。 ランキング報酬 グローバルランキング・クラスターランキングではランキングの順位報酬を設定できます。 報酬を設定するには 順位閾値 と 報酬の内容 を設定します。 /ja/microservices/realtime/ Mon, 01 Jan 0001 00:00:00 +0000 /ja/microservices/realtime/ ゲームプレイヤー同士での対戦機能を実現するために、低レイテンシーかつ高頻度で通信する場合に利用できる機能です。 GS2 では一般的にAPIリクエスト回数に対して料金が発生しますが、このサービスについてはゲームサーバーが起動すれば、 そのゲームサーバーの起動時間と、通信容量に対して費用が発生し、通信回数に対しては費用が発生しません。 graph TD Match["GS2-Matchmaking で<br/>ロビーを成立"] --> Want["RoomWant でルーム要求"] Want -- ホットスタンバイから割り当て --> Warm["Warm Start (1〜3秒)"] Want -- 新規起動 --> Cold["Cold Start (40〜60秒)"] Warm --> Connect["プレイヤーが接続"] Cold --> Connect Connect --> Play["パケットリレーで対戦中通信"] Play -- 1分間無通信または3時間経過 --> Shutdown["ルーム終了"] サーバータイプ 現在、GS2-Realtime はパケットリレー機能のみを提供しています。 これはゲームサーバーにメッセージを送信すると、そのメッセージが他のプレイヤーにブロードキャストされる機能を基本として プレイヤーIDを指定して、指定したプレイヤーにメッセージを届ける機能のみを有します。 RPCやオブジェクト同期といった機能はSDKには含まれておらず、単純なバイナリデータの送受信のみを行えます。 ペイロードのバイナリエンコーディングはアプリケーション側の責務となるため、Protocol Buffers / FlatBuffers / MessagePack といった任意のエンコーディングを採用できます。 Unreal Engine Dedicated Server ホスティング 開発者が Unreal Engine でビルドした Dedicated Server をホスティングできるようにすることを検討しています。 この機能の提供時期については未定です。 有償サポート契約をしたうえで開発を勧められる、強いニーズがあればスケジュールを調整できますので、ご相談ください。 サーバースペック サーバーの性能を設定できます。性能によって1分あたりの利用料金に差が生じます。 最も安い realtime1.nano で 8人プレイヤーが1秒間に3回メッセージを送り合えることを確認しています。 /ja/microservices/schedule/ Mon, 01 Jan 0001 00:00:00 +0000 /ja/microservices/schedule/ ゲーム内のイベントなどのスケジュールを管理する機能を提供します。 GS2-Schedule は単体ではイベントの期間情報のみを管理する機能を持ち、報酬の付与や購入制限といった処理は他のマイクロサービスと組み合わせて実現します。 GS2-Showcase / GS2-Exchange / GS2-LoginReward / GS2-Mission など、ほぼ全てのゲーム要素マイクロサービスがイベント期間との連携を前提に設計されているため、期間限定の運用施策を行う際の中核となるマイクロサービスです。 イベントの開催期間 イベントの開催期間には2種類あります。 1つ目は、全てのプレイヤーが同じ期間を共有する「絶対期間」、2つ目は、プレイヤーごとに期間が異なる「相対期間」となります。 graph TD Event["イベント"] Event --> Absolute["絶対期間<br/>(scheduleType = absolute)"] Event --> Relative["相対期間<br/>(scheduleType = relative)"] Absolute --> AbsoluteSample["例: 1月1日〜1月3日の<br/>ニューイヤーイベント"] Relative --> RelativeSample["例: 初プレイから7日間<br/>初回ボス撃破から24時間"] 絶対期間 「1月1日〜1月3日でニューイヤーイベントを開催する」といったケースで使用する期間タイプです。 全プレイヤーで同一の開催期間が共有されるため、absoluteBegin / absoluteEnd をマスターデータで指定します。 相対期間 「ゲーム開始から1週間」や「初めてボスを倒してから24時間」のように、プレイヤーによってイベントの期間が異なるケースで使用する期間タイプです。 相対期間を実現するための「トリガー」という仕組みがあります。 トリガーを実行したあと、指定された期間（ttl）がイベントの開催期間として扱われます。 Gs2Schedule:TriggerByUserId アクション トリガーの引き方の種類 トリガーを引く時に、すでにトリガーが引かれている場合のイベント期間の指定方法には複数の方式があります。 トリガーを再起動する（renew） トリガーを延長する（extend） 何もしない（drop） イベントの繰り返し終了日時で有効期限を迎える（repeatCycleEnd） 次回の繰り返し開始日時で有効期限を迎える（repeatCycleNextStart） 絶対期間イベントの終了日時で有効期限を迎える（absoluteEnd） repeatCycleEnd / repeatCycleNextStart / absoluteEnd は、繰り返し設定や絶対期間を持つイベントに合わせて有効期限を自動調整する方式です。 2020年1月1日 00:00にトリガーを引き、7日間の相対期間イベントが開始された場合、2020年1月3日 00:00にトリガーを再度引いたときの各動作は以下のようになります。 方式 イベント終了日時 renew 2020年1月10日 00:00 トリガーの起動時点 2020年1月3日 00:00に7日間を追加 extend 2020年01月14日 00:00 すでに存在するトリガーの有効期限 2020年1月7日 00:00に7日間を追加 drop 2020年01月7日 00:00 すでに存在するトリガーをそのまま維持 繰り返し設定 絶対期間／相対期間ともに、RepeatSetting を組み合わせることで「特定の曜日や時間帯のみ有効」「数日のサイクルで有効・無効を切り替える」といった繰り返しスケジュールを表現できます。 /ja/microservices/script/ Mon, 01 Jan 0001 00:00:00 +0000 /ja/microservices/script/ GS2-Script は、GS2 の各マイクロサービスのイベントに応じてサーバーサイドでカスタムロジックを実行するための、Lua ベースのスクリプト実行環境です。 GS2 の各マイクロサービスには、特定の API 呼び出しの前後にスクリプトを実行する《スクリプトトリガー》という仕組みが用意されています。 これに GS2-Script で記述したスクリプトを紐付けることで、各サービスの標準機能では実現できないゲーム固有の検証ロジックやデータ加工処理、外部システム連携などをサーバー側で動かせます。 クライアント側のロジックは改ざんのリスクがあるため、不正防止や監査の観点で重要な処理はサーバー側で動かしたいケースが多くあります。 GS2-Script を使えば、GS2 のフルマネージド環境の中でそうしたサーバーロジックを記述・運用できます。 Lua スクリプト スクリプトの記述言語には Lua を採用しています。 Lua はゲーム業界での採用実績が豊富な軽量スクリプト言語であり、シンプルな文法と高速な実行性能を備えています。 スクリプトの登録は文字列を直接アップロードする方法と、GitHub リポジトリと連携してファイルを取得する方法の両方が利用できます。 GitHub 連携を利用することで、スクリプトの変更履歴を Git で管理し、Pull Request ベースでのレビュー・運用が可能になります。 スクリプトトリガー 各マイクロサービスのネームスペース設定で、特定の API 処理の前後に実行するスクリプトを指定できます。 スクリプトの実行タイミングは大きく2種類に分かれます。 graph LR Request["API リクエスト"] --> Pre["前処理スクリプト<br/>(同期実行)"] Pre --> Process["GS2 標準処理"] Process --> Done["完了通知スクリプト<br/>(非同期実行)"] Process --> Response["API レスポンス"] 前処理スクリプト (同期実行) API 処理の実行直前に同期実行されるスクリプトです。 スクリプトの実行結果でリクエストパラメーターを変換したり、処理そのものを中断 (例外を発生) させたりできます。 レスポンスタイムには影響しますが、リクエストの内容をサーバー側で動的に判定・改変したい場合に有用です。 例: GS2-Account の createAccountScript の triggerScriptId を設定すると、アカウント作成 API の実行前にスクリプトが走り、特定の条件下では作成を拒否するといった制御ができます。 完了通知スクリプト (非同期実行) API 処理の完了後に非同期で実行されるスクリプトです。 /ja/microservices/season_rating/ Mon, 01 Jan 0001 00:00:00 +0000 /ja/microservices/season_rating/ プレイヤースキルでプレイヤーを分類し、より近い実力のプレイヤーとのマッチメイキングを実現するための機能です。 レーティング値によるマッチメイキング機能は GS2-Matchmaking に備わっていますが、近年増えている現実時間で数週間〜数ヶ月程度のシーズンを通してプレイヤーをランクづけする仕組みには対応していませんでした。 このマイクロサービスは、定めた期間をシーズンと捉え、シーズン期間に高いティアーを目指して対戦を繰り返すゲームサイクルを実現するために利用できます。 そのため、この機能で強さを表す指標はレート値ではなく、どのティアーに属しているかによって表現されます。 graph TD Match["GS2-Matchmaking<br/>マッチメイキング成立"] --> Session["MatchSession 作成"] Session --> Ballot["各プレイヤーが投票用紙を取得<br/>(Ballot / SignedBallot)"] Ballot --> GamePlay["ゲームプレイ"] GamePlay --> Vote["Vote / VoteMultiple<br/>順位を投票"] Vote --> Aggregate{"多数決で結果確定"} Aggregate -- 確定 --> Calc["ポイント変動量を計算<br/>(TierModel に基づく)"] Calc --> Experience["GS2-Experience に<br/>ポイント / ランクを反映"] Aggregate -- 分断 --> Skip["集計せず終了"] ティアー ティアーは一般的にブロンズから始まり、勝ち進めることでシルバー、ゴールド、プラチナ…のように上がっていく仕様が一般的です。 ティアーを上げるには、同一ティアー内のプレイヤーと対戦し、順位によって変動する入手ポイントが閾値を超えると次のティアーに上がれます。 勝負に負けるとポイントは減ることがあり、ポイントが閾値を下回ると前のティアーに下がることがあります。 ティアーモデルの設定項目 各ティアーは TierModel として定義し、以下のパラメータでポイントの増減や昇格時の挙動を制御できます。 項目 説明 metadata ティアー名などの自由記述（ブロンズ/シルバー/ゴールド 等） entryFee ゲーム参加時に消費するポイント。連戦連勝でなければ昇格できない難易度設計に利用 minimumChangePoint 最下位を取った時のポイント減算量 maximumChangePoint 最上位を取った時のポイント加算量 raiseRankBonus ランクアップした際に付与するボーナスポイント。直後に降格しないチャタリング防止に有効 ティアーをまたぐ対戦 レーティング戦において、マッチメイキングのルールは原則的に同一ティアーで構成するべきです。 しかし、プレイヤーが不足するなどの理由で前後のティアーのプレイヤーを含んだ状態でマッチメイキングをする場合も各プレイヤーが属しているティアーの最小・最大変動量と順位を元にポイントの変動量を決定します。 低いティアーのプレイヤーが高いティアーのプレイヤーに勝った場合にボーナスポイントを加算する仕組みやその逆のような仕組みはありません。 本来異なる強さのプレイヤー同士を対戦させて細工で工夫をするより、各ティアーに最低限ゲームプレイを成立させるだけのプレイヤーが滞留するようにティアーの閾値設計を行うことを推奨します。 /ja/microservices/serial_key/ Mon, 01 Jan 0001 00:00:00 +0000 /ja/microservices/serial_key/ ゲーム外の物販やリアルイベント、SNSキャンペーン、コラボキャンペーンなどを通じてゲーム内アイテムを配布したい場合に使用できます。 紙のパッケージや QR コードに印字したコード、メール／SNS で配布する文字列のいずれも同じ仕組みで取り扱うことができます。 ただし、この機能は一部プラットフォーマーは実装を許していないため、採用にあたってはプラットフォーマーのガイドラインを確認するようにしてください。 シリアルコードの種類 シリアルコードは以下の2種類があります。 シリアルキー：1回使用すると再利用できないコード キャンペーンコード：1つのコードを複数人で共有できるコード graph TD SerialCode["シリアルコード"] SerialCode --> SerialKey["シリアルキー<br/>1人1回限定"] SerialCode --> CampaignCode["キャンペーンコード<br/>複数人で共用"] SerialKey --> SerialKeyUse["RPCLP-FP7N-NCDMJ-FLVA-IRI4"] CampaignCode --> CampaignCodeUse["NEWYEAR2026"] シリアルキー 1回使用すると2度と使用できなくなるコード です。 シリアルキーは「RPCLP-FP7N-NCDMJ-FLVA-IRI4」のような形式で発行され、データ長を変更することはできません。 シリアルキー内にはキャンペーンの種類の情報も含まれており、シリアルキーを使用する際にはネームスペースを指定するだけで使用できます。 キャンペーンコード 「ハロウィン2025」「SUMMER」のように人間にとって覚えやすい文字列を、運営側が任意に設定できるコード です。 1つのコードを多数のプレイヤーが共有して引き換えに使用することを想定しています。 キャンペーンコードはキャンペーンに紐づけて発行する シリアルキー とは異なり、キャンペーンの名前自体がコードとして引き換え可能になります。 キャンペーン 「シリアルキー」も「キャンペーンコード」もキャンペーンに属します。 キャンペーンには以下を設定します。 name: キャンペーン名（キャンペーンコードとしても利用される） metadata: 任意のメタデータ enableCampaignCode: キャンペーンコード（キャンペーン名そのものを使った引き換え）を有効化するか キャンペーンは GS2-Schedule のイベントと関連づけることで有効期間を設定することが可能です。 有効期間の検証はトランザクションアクションを組み合わせて実現できます。 シリアルキーの発行 対象のキャンペーンと発行数量を指定してシリアルキーの発行処理を実行することで、シリアルキーが発行されます。 発行処理は非同期ジョブとして実行され、IssueJob を介して進捗を確認できます。 発行されたシリアルキーのリストはCSV形式でダウンロードが可能です。 物販パッケージに印字するなど、大量に発行する用途では数十万件単位での発行も可能です。 シリアルキーの状態 シリアルキーは以下の状態を持ちます。 状態 説明 ACTIVE プレイヤーが利用可能な状態 USED 既に使用済み（再利用不可） INACTIVE 運営によって無効化された状態 実際にプレイヤーが利用できる状態が ACTIVE で、使用すると USED になります。 運営サイドでシリアルキーを無効化すると INACTIVE になります。 /ja/microservices/showcase/ Mon, 01 Jan 0001 00:00:00 +0000 /ja/microservices/showcase/ ゲーム内で商品を販売する際に使用します。 GS2-Exchange との違いは陳列棚が存在することです。 陳列棚には DisplayItem を陳列することができ、DisplayItem を購入するために必要な対価と、商品を購入した際に得られる報酬を設定できます。 陳列棚には2種類存在し、固定の DisplayItem が陳列される《スタンダード陳列棚》と、一定間隔で陳列内容がランダムに抽選される《ランダム陳列棚》が存在します。 graph TD Master["マスターデータ"] --> Showcase["スタンダード陳列棚<br/>(ShowcaseModel)"] Master --> RandomShowcase["ランダム陳列棚<br/>(RandomShowcaseModel)"] Showcase --> DisplayItem["DisplayItem<br/>(SalesItem / SalesItemGroup)"] RandomShowcase --> RandomDisplayItem["RandomDisplayItem<br/>(stock / weight)"] Player["プレイヤー"] -- Buy --> DisplayItem Player -- RandomShowcaseBuy --> RandomDisplayItem DisplayItem -- "consumeActions / acquireActions" --> Transaction["GS2-Distributor<br/>トランザクション実行"] RandomDisplayItem -- "consumeActions / acquireActions" --> Transaction スタンダード陳列棚 スタンダード陳列棚は指定した DisplayItem が全て陳列されます。 DisplayItem には2種類存在し《SalesItem》と《SalesItemGroup》が存在します。 SalesItem SalesItem には購入するするために必要な対価と、購入した際に得られる報酬を設定できます。 SalesItem は次の3種類のアクションで挙動を表現します。 項目 説明 verifyActions 購入条件の検証アクション。指定したマイクロサービスの状態を検証し、条件を満たさない場合は購入を拒否します。 consumeActions 購入時に消費するアクション。GS2-Money2 の通貨や GS2-Inventory のアイテムなどを対価として消費します。 acquireActions 購入時に入手するアクション。GS2-Inventory・GS2-Experience・GS2-Lottery など、任意のマイクロサービスへ報酬として配布します。 SalesItemGroup SalesItemGroup は購入回数に応じて販売する SalesItem が変化する仕組みを実現します。 /ja/microservices/skill_tree/ Mon, 01 Jan 0001 00:00:00 +0000 /ja/microservices/skill_tree/ キャラクターなどの成長要素として一般的に使用されるスキルツリー機能を実現するためのマイクロサービスです。 スキルツリーとは、以下のような木構造を持ち、ノードを解放することでキャラクターのパラメーターを向上させることができる機能を指します。 ノードの解放にはコストが必要で、GS2-SkillTree では各マイクロサービスが提供する《消費アクション》を設定できます。 flowchart TD Base --> Node1[STR+5] Node1 --> Node2[DEF+5] Node2 --> Node3[SPD+5] Node3 --> Node4[STR+5] Node4 --> Node5[DEF+5] Node5 --> Node6[STR+5] Node6 --> Node7[DEF+5] Node3 --> Node10[SPD+5] Node10 --> Node11[DEF+5] Node11 --> Node12[SPD+5] Node12 --> Node13[DEF+5] Node11 --> Node30[SPD+5] Node30 --> Node31[STR+5] Node31 --> Node32[SPD+5] Node7 --> Node20[STR+5] Node13 --> Node20 Node20 --> Node21[STR+5] Node21 --> Node22[STR+5] ノード定義（NodeModel） スキルツリーを構成するノードはマスターデータ NodeModel として定義します。 各ノードは以下のフィールドで構成され、これによりノードの解放条件・コスト・効果・依存関係を表現します。 フィールド 役割 name ノードの識別子 metadata クライアントで表示する説明用テキスト releaseVerifyActions 解放に必要な検証アクション（特定ランクであることなど。最大10件） releaseConsumeActions 解放時に消費されるアクション（SP・アイテム・ゴールド等。1〜10件） restrainReturnRate 未解放化（リストレイン）時のコスト返還率（0. /ja/microservices/stamina/ Mon, 01 Jan 0001 00:00:00 +0000 /ja/microservices/stamina/ スタミナはゲーム内の回数制限機能を実現するものです。 GS2-Limit は「1日に3回」のように回数制限を表現しますが、GS2-Stamina は「8時間で1ポイント回復するスタミナを使用して1日3回に回数制限を実現する」というように、時間経過と消費アクションの組み合わせで制限を表現します。 スタミナの場合、消費するポイントに差をつけることで、Aという行動であれば1日3回、Bという行動であれば1日5回のような仕様を実現できます。 これは、スタミナ1あたりで得られる経験値やゲーム内通貨の指針を設けることで、ゲーム内のどのような行動をとっても、効率のいい行動というものを排除することができ、ゲームバランスを調整しやすくなります。 毎日ログインしてもらうように開発者は努力をするべきなので、あまりこのような仕様にはしませんが、 プレイヤーにとっては8時間で1ポイント回復し、最大15ポイントまで蓄積できる仕様であれば、毎日ログインしなくても5日に1回のログインでもポイントを無駄にすることなく使い切ることができます。 スタミナ スタミナには「回復周期」「回復量」「最大値」を設定します。 graph LR Time["時間経過"] -- "recoverIntervalMinutes ごとに" --> Recover["回復<br/>(+recoverValue)"] Recover --> Value["現在値"] Consume["消費アクション"] -- "-consumeValue" --> Value Value -- "maxValue を超過" --> Overflow["オーバーフロー状態"] パラメーター 説明 value 現在の保有スタミナ値 maxValue 自然回復で到達できる上限値 recoverIntervalMinutes 1ポイント回復するのに必要な分数 recoverValue 1回の回復で増加する値 overflowValue 最大値を超過している分の値 nextRecoverAt 次回回復の予定日時 オーバーフロー スタミナは最大値を超えて回復させることができます。 最大値を超えた状態では時間経過による回復は発生しません。 また、最大値を超えた状態でもUIの都合などで、それ以上は加算させない「本当の最大値」を設定できます。 なぜオーバーフローさせるのですか？ この仕様はあまりスタミナを仕様に組み込んだゲームをプレイする機会のなかった開発者には奇妙に感じるかもしれません。 スタミナは一般的に回復するためのアイテムや、ゲーム内課金によって回復する手段が存在します。 そのアイテムを使用したり、スタミナを購入する際にプレイヤーのストレスを最小化しようとこのような仕様が生まれました。 具体的な例を示しましょう。 このゲームは5分で1ポイントスタミナが回復し、あなたのスタミナの最大値は50ポイントです。 あなたが次にプレイしたいクエストをプレイするにはスタミナが10ポイント必要です。 しかし、現在のあなたのスタミナ値は9ポイントしかなく、5分待たなければ次のクエストをプレイできません。 そこで、あなたはスタミナを購入しようと思いました。スタミナを購入するとスタミナが50ポイント回復します。 しかし、今すぐにスタミナを購入すると、50ポイント回復しても9ポイントは無駄になってしまいます。 そのため、あなたは5分待って1ポイント回復した後でクエストをプレイし、0ポイントにした後で、その次のクエストを遊ぶためにスタミナを購入しました。 これではプレイヤーがゲームを快適にプレイすることはできません。 そこで、最大値を超えてスタミナを回復できる仕様を導入するゲームが生まれました。 スタミナに最大値を超える仕様を加え、ユーザー体験がどのように変化するか見てみましょう。 現在のあなたのスタミナ値は9ポイントしかなく、5分待たなければ次のクエストをプレイできません。 そこで、あなたはスタミナを購入し、スタミナを50ポイント回復し、59ポイントしました。 この状態では時間経過によるスタミナの回復は行われなくなりますが、 あなたはすぐに次のクエストを開始し、スタミナを49ポイントにしました。 GS2-Experience との連携 MaxStaminaTable / RecoverIntervalTable / RecoverValueTable をマスターデータに登録し、GS2-Experience のランク（プレイヤーレベル等）に応じて自動的に最大値・回復周期・回復量を変化させることができます。 プレイヤーレベルアップに合わせて自動的にスタミナの上限が増えるといった、よくある成長要素を簡単に表現できます。 /ja/microservices/state_machine/ Mon, 01 Jan 0001 00:00:00 +0000 /ja/microservices/state_machine/ GS2-Quest はクエストの開始・終了を管理し、開始したクエストに応じて終了時に報酬を受け取れる仕組みを提供しました。 しかし、インゲームのランダム性が強く報酬を事前に特定することが困難なゲーム仕様は、GS2-Quest ではうまく扱えない課題がありました。 GS2-StateMachine はより細かい粒度でインゲームの状態管理をおこなうために開発されました。 ステートマシン インゲームの状態管理に使用するのはステートマシンです。 flowchart TD Start ----> MainStateMachine_Initialize MainStateMachine_Pass ----> Exit subgraph MainStateMachine MainStateMachine_Initialize[[Initialize]] -->|Pass| MainStateMachine_ChoiceSkill MainStateMachine_ChoiceSkill[/ChoiceSkill/] MainStateMachine_InGame([InGame]) -->|Pass| MainStateMachine_NextTurn MainStateMachine_InGame([InGame]) -->|Fail| MainStateMachine_Pass MainStateMachine_NextTurn[[NextTurn]] -->|Next| MainStateMachine_ChoiceSkill MainStateMachine_NextTurn[[NextTurn]] -->|Exit| MainStateMachine_Pass MainStateMachine_Pass[\Pass/] subgraph ChoiceSkill ChoiceSkill_Initialize[[Initialize]] -->|Pass| ChoiceSkill_LotterySkills ChoiceSkill_LotterySkills[[LotterySkills]] -->|Pass| ChoiceSkill_WaitChoiceSkill ChoiceSkill_WaitChoiceSkill([WaitChoiceSkill]) -->|ChoiceSkill| ChoiceSkill_ChoiceSkill ChoiceSkill_WaitChoiceSkill([WaitChoiceSkill]) -->|ReLotterySkill| ChoiceSkill_ReLotterySkill ChoiceSkill_ReLotterySkill[[ReLotterySkill]] -->|Pass| ChoiceSkill_LotterySkills ChoiceSkill_ReLotterySkill[[ReLotterySkill]] -->|AlreadyReLottery| ChoiceSkill_WaitChoiceSkill ChoiceSkill_ChoiceSkill[[ChoiceSkill]] -->|Pass| ChoiceSkill_Pass ChoiceSkill_ChoiceSkill[[ChoiceSkill]] -->|InvalidSkillIndex| ChoiceSkill_WaitChoiceSkill ChoiceSkill_Pass[\Pass/] end end MainStateMachine_ChoiceSkill --> ChoiceSkill_Initialize ChoiceSkill_Pass -->|Pass| MainStateMachine_InGame Player ----->|Interaction| MainStateMachine_InGame Player ----->|Interaction| ChoiceSkill_WaitChoiceSkill あなたがプログラマーならプランナーから上記のようなフローチャートを受け取ったことがあるはずです。 このような状態遷移を表現したものがステートマシンです。 /ja/microservices/version/ Mon, 01 Jan 0001 00:00:00 +0000 /ja/microservices/version/ アプリケーションのバージョンや、追加アセットのバージョン、利用規約に同意しているバージョンなどを判定する機能を提供します。 バージョンチェックを通過した際に、新しい一時的なGS2のクライアントID/シークレットを発行できます。 この機能を利用することで、アプリ内に組み込んだGS2のクライアントID/シークレットは、ログインを行いバージョンチェックを行うAPIしか呼び出す権限を持たず、バージョンチェックを通過した後で、実際にゲームをプレイするのに十分な権限のクライアントID/シークレットを受け取れるようにできます。 graph TD Boot["アプリ起動"] --> Login["GS2-Account でログイン"] Login -- "最小権限の<br/>クライアントID/シークレット" --> Check["GS2-Version<br/>CheckVersion"] Check -- "OK" --> Token["新しい ProjectToken を取得<br/>(本来の権限)"] Check -- "Warning" --> Notify["プレイヤーに更新を促す"] Check -- "Error" --> Force["強制バージョンアップ"] Notify --> Token Token --> Game["ゲーム本編"] バージョンモデル ネームスペースには最大10個のバージョンモデルを宣言できます。バージョンチェックには複数の項目を設定でき、全てのバージョンチェックが通過した場合にのみ、チェックを通過できます。 バージョンモデルには2種類あり「アプリケーションが送信してきたバージョンを元にバージョン判定をする」「ログイン中のユーザーが過去に同意した規約のバージョンを元にバージョン判定をする」ことができます。 前者を「パッシブバージョンチェック」後者を「アクティブバージョンチェック」と呼びます。 マスター項目 説明 name バージョンモデル名（チェック時の識別子） scope passive（パッシブ） / active（アクティブ） type simple（単一のしきい値） / schedule（時刻でしきい値を切り替え） currentVersion アクティブバージョンチェックで、初回参加時に自動的に承認したことにするバージョン warningVersion 警告を出すバージョン閾値（このバージョン以下で warnings を返却） errorVersion エラーとするバージョン閾値（このバージョン以下で errors を返却） scheduleVersions type: schedule 時に時刻ごとのしきい値を定義 needSignature バージョン情報に署名を要求するか signatureKeyId 署名検証に使用する GS2-Key の鍵ID approveRequirement アクティブバージョンチェック時の承認要件（required / optional） バージョン番号のフォーマット {major}. /ja/overview/workflow/setup_gs2/create_account/ Mon, 01 Jan 0001 00:00:00 +0000 /ja/overview/workflow/setup_gs2/create_account/ Game Server Services の利用を開始するには、まずはアカウントの登録が必要です。 アカウントの登録は https://gs2.io のページ下部よりできます。 このフェーズで開発者が利用するアカウントの運用方針について検討する必要があります。 開発者がそれぞれ専用のアカウントを作成して開発 共有アカウントで開発 開発者がそれぞれ専用のアカウントを作成して開発 GS2 としてはこちらの方法を推奨しています。 開発者が専用のアカウントを作成し、専用の環境で開発を進めることで、他の開発者のGS2の設定変更の影響を受けることなくスムーズに開発を進めることができます。 GS2 では 開発者間で GS2のリソース設定を共有する方法を提供しており、この機能を活用することで専用の開発環境を最小の手間でメンテナンスすることができます。 Project "1" *-- "many" Developer Developer "1" -- "1" Gs2Account Gs2Account "1" *-- "many" Gs2Project Gs2Project "1" *-- "many" GS2Resources この方法を採用した時、コストも気になる点かもしれません。 GS2 では Pay-as-you-go スタイルの料金請求を行なっているため、アカウント数やプロジェクト数が増えたからといって追加の費用は発生しません。 その方法については後のステップで解説します。 共有アカウントで開発 プロジェクト用の GS2 アカウント、または開発用の GS2 アカウント を作成し、そのアカウント内に開発用のプロジェクトを作成します。 プロジェクトごとに、プロジェクトの管理機能にアクセス可能なサブアカウントを作成できるため、この仕組みを利用して1つのプロジェクトを複数人で管理できます。 Project "1" *-- "1" "Gs2Project(Dev Env)" "Gs2Project(Dev Env)" "1" *-- "many" User User "1" -- "1" LoginPassword User "1" -- "1" Developer /ja/api_reference/state_machine/format/ Mon, 01 Jan 0001 00:00:00 +0000 /ja/api_reference/state_machine/format/ はじめに GS2 States Language(GSL) は独自の構造を持つステートマシン定義言語です。 ステートマシンは一般的に複数の状態を表す Task と、タスク間の遷移を表す Transition によって構成されます。 外部からのメッセージを送信すると、Transition によって定められたルールに基づいて、「実行中の Task」が遷移することで状態管理を行います。 ステートマシンは 「実行中の Task」以外に「状態変数」を持ちます。 Task にはいくつか種類がありますが、一般的には GS2-Script の実行によって処理を記述できます。 GS2-Script は「状態変数」を参照でき、またスクリプトの実行結果として、「状態変数」を書き換えることができます。 (C) Game Server Services Inc. and affiliates. GSL の仕様の実装および派生仕様は無償で許可します。 ただし、上記コピーライトを派生物に含んでください。 本仕様の派生物をサブライセンスおよび販売を行うことはできません。 本仕様は「現状のまま」提供され、本仕様によって他社の著作権などを侵害していないことを保証するものではありません。 本使用によって生じるあらゆる請求、損害、その他責任についても Game Server Services, Inc. は責任を負わないものとします。 本仕様書に含まれるサンプルコードは特に指定がない限り Apache License, Version 2.0 の下でライセンスされます。 GSL の例 StateMachine MainStateMachine { Variables { int counter; } EntryPoint Task1; Task Task1(int initCounter) { Event StartLoop(); Event Error(string Reason); Payload { args.variables.counter = args. /ja/overview/workflow/setup_gs2_resources/manual_setup/ Mon, 01 Jan 0001 00:00:00 +0000 /ja/overview/workflow/setup_gs2_resources/manual_setup/ 開発者がまずマネージメントコンソールでやるべきことは、ネームスペースの作成とマスターデータの登録です。 これらはマネージメントコンソール上で作成が可能です。 リージョンの選択 サイドメニューの下方にリージョンメニューがあります。 ここからマイクロサービスを操作するリージョンを選択できます。 ネームスペースの作成 マネージメントコンソールにログインし、マイクロサービスを選択します。 ネームスペースの一覧が表示されたら、ネームスペースを新規作成します。 設定項目に値を入力し、確定すればネームスペースの作成は完了です。 マスターデータの登録 マイクロサービスによっては、機能を利用する前にマスターデータの登録が必要な場合があります。 マスターデータの登録が必要なマイクロサービスには、ネームスペースの詳細ページに「マスターデータ」というタブがあります。 タブを選択すると「Currently available master data could not be found」というようなエラーが表示され、まだマスターデータが登録されていないことがわかります。 マスターデータエディターの利用 マスターデータを作成するには マスターデータエディタ が利用できます。 ネームスペースの詳細ページに「マスターデータエディタ」というタブがありますので、それを選択します。 このスクリーンショットは GS2-Inventory の例です。 マスターデータの作成について説明するために、GS2-Inventory がどのようなマスターデータを必要とするのか説明しましょう。 class InventoryModel { +string 名前 +int 初期サイズ +int 最大サイズ } class ItemModel { +string 名前 +int スタック可能な最大数量 +bool スタック可能な最大数量を超えた時、複数枠にアイテムを保管することを許すか +int 表示順番 } Namespace "1" *-- "many" InventoryModel InventoryModel "1" *-- "many" ItemModel GS2-Inventory には容量制限のある Inventory と、Inventory に格納できる Item の定義が必要です。 Inventory には初期容量と最大容量。Item には1容量で最大いくつのアイテムをスタックできるか、アイテムの所持数量がスタックできる最大数に達した時、2スタック目を作成するかを設定します。 /ja/overview/workflow/architect/ Mon, 01 Jan 0001 00:00:00 +0000 /ja/overview/workflow/architect/ ゲームの仕様が決まってきたら、どのように実装するかを検討する必要があります。 GS2 ではゲームの様々な仕様を実現するために活用できるマイクロサービスを提供しています。 GS2 が提供するマイクロサービスの種類と、それぞれのマイクロサービスの役割については以下のドキュメントを参考にしてください。 マイクロサービスの紹介 Game Server Services では設計を手助けするための有償サポートを提供しています。 有償サポートを契約することで、ゲームの仕様を GS2 のスタッフが理解し、最適な GS2 のマイクロサービスの適用方法について一緒に検討します。 サポートメニュー /ja/overview/workflow/setup_gs2_resources/automation_setup/ Mon, 01 Jan 0001 00:00:00 +0000 /ja/overview/workflow/setup_gs2_resources/automation_setup/ マネージメントコンソールを使用したセットアップは手軽に実行できるのは魅力です。 しかし「同じ環境をもう一つ作って欲しい」というオーダーを受けた時にあなたは絶望するに違いありません。 ゲーム開発では一般的に「開発環境」「検証環境」「本番環境」のように複数のサーバー環境を必要とします。 それぞれで、マネージメントコンソール上で同じ操作を繰り返して GS2 への設定をミスをせず行うのは不可能と言えるでしょう。 GS2-Deploy そこで、GS2 には環境構築のためのマイクロサービスである GS2-Deploy が用意されています。 あなたがクラウドに精通したエンジニアであれば、AWS が提供している Cloud Formation の GS2版 と言うだけで、このマイクロサービスの役割を理解できます。 理解できたあなたはこれ以上このページを読み進める必要はありません。GS2 は Cloud Formation のような機能を使って、マイクロサービスをオーケストレーションできます。 そうではないあなたも安心してください。ここから GS2-Deploy について詳しく解説します。 Infrastructure as Code 管理画面を使用して GS2 への設定を反映することの愚かさについて、すでにあなたが理解している信じています。 このような愚かさに対抗するべく、サーバーインフラの世界では様々な改善が行われてきました。 そして、その成果が Infrastructure as Code(IaC) です。 20年前には、サーバーを新しくセットアップすることになったインフラエンジニアは1台1台にコマンドを入力して環境を構築していました。 「HTTPサーバーをインストール」「HTTPサーバーの設定ファイルを更新」「データベースサーバーをインストール」「データベースにスキーマを登録」 その作業は1台であれば問題ありませんが、100台のサーバーに設定するとなるとどうでしょうか？ 1週間かけて100台のサーバーをセットアップしたが、そのうち数台は設定ミスがあって動かない なんてことが起こっていたわけです。 2006年に Amazon が現代のクラウドの基礎と言える Elastic Compute Cloud をローンチしました。 すると、これまで発注してからサーバーが手元に届くまで数ヶ月待つ必要がありましたが、発注してから5分後にはサーバーが手元にある状態になりました。 これはサーバーインフラの世界に激変をもたらしました。 これまでハードウェアのリードタイムが数ヶ月あるのだから、サーバーのセットアップをしてミスがあれば修正する作業を1週間かけてやっていても、非効率をごまかせていました。 しかし、5分でサーバーを調達した後1週間かけてサーバーをセットアップしているのは何かおかしい と気付いた人たちがいます。 そこで、サーバーのセットアップ手順を自動化し、セットアップにかける時間を短縮するモチベーションが高まりました。 その成果物として、出てきたのが サーバーのセットアップ手順をコード化する IaC です。 IaC によって、サーバーのセットアップ時間は高速かつ正確なものになりました。 IaC のアプローチ IaC には2つのアプローチが存在します。 1つ目は命令型、2つ目は宣言型です。 命令型は「apt install httpd」というようなセットアップ手順のコマンドを羅列させ、それを実行することで自動化しようという考えに基づいています。 これは人間が行なっていたセットアップ手順を自動化しようとした場合、素直なアイデアです。 /ja/overview/workflow/setup_gs2/create_project/ Mon, 01 Jan 0001 00:00:00 +0000 /ja/overview/workflow/setup_gs2/create_project/ アカウントの作成が完了したら、プロジェクトを作成します。 プロジェクトには料金プランや、請求先を設定できます。 つまり、1つのアカウントでもプロジェクトごとに異なる請求先を設定できます。 これは、パブリッシャーにGS2の利用料金を負担してもらうデベロッパーにとっては有意義な構成のはずです。 プロジェクトの作成が完了したら、GS2の利用を開始するための準備は整いました。 /ja/articles/tech/error/pattern/ Mon, 01 Jan 0001 00:00:00 +0000 /ja/articles/tech/error/pattern/ GS2 を利用したネットワーク機能の実装において、エラーハンドリングはゲームの安定性とユーザー体験（UX）に直結します。 ここでは、単なる例外のキャッチに留まらない、実践的な実装パターンを紹介します。 1. エラーの分類と対応方針 GS2 の例外は、その性質によって大きく 3 つに分類できます。 分類 該当する例外 (例) 対応方針 一時的なエラー InternalServerError, ServiceUnavailable, RequestTimeout 自動リトライ。数回試行してもダメな場合はエラーダイアログを表示。 ロジック/設定エラー BadRequest, NotFound 開発中に解消すべきエラー。リリース後はバグとしてログ収集し、ユーザーには適切なメッセージを表示。 認証・状態エラー Unauthorized, Conflict, QuotaLimitExceeded 特別なリカバリ処理が必要。再ログインや、データの再同期（ドメインの再取得）を行う。 2. リトライ戦略の実装（指数バックオフ） サーバーの過負荷や一時的なネットワークの不安定さによるエラーに対しては、即座にリトライするのではなく、間隔を空けてリトライする「指数バックオフ（Exponential Backoff）」が推奨されます。 Unity / C# での例（自動リトライ） public async Task<T> ExecuteWithAutoRetry<T>(Func<Task<T>> action, int maxRetries = 3) { for (int i = 0; i < maxRetries; i++) { try { return await action(); } catch (Gs2.Core.Exception.Gs2Exception e) when (e.RecommendAutoRetry) // 自動リトライ推奨か判定 { if (i == maxRetries - 1) throw; // 指数バックオフ: 1s, 2s, 4s. /ja/overview/workflow/setup_gs2_resources/cdk_setup/ Mon, 01 Jan 0001 00:00:00 +0000 /ja/overview/workflow/setup_gs2_resources/cdk_setup/ GS2-Deploy は環境構築のために素晴らしい成果をあげています。 しかし、テンプレートの記述方法にはまだ課題がありました。それは、テンプレートファイルを記述するのに入力支援が得られないことです。 GS2-Deploy を設計するのに AWS の Cloud Formation を参考にしたのはすでに説明した通りですが、 2019年に AWS が発表したのが AWS CDK(Cloud Development Kit)です。 これは、従来のJSONやYAMLでのテンプレートファイルを記述するのに入力支援を得られない という問題の解決策として、各種プログラミング言語でテンプレートを記述できるようにしよう という成果です。 2019年のサービス開始から、GS2 はずっと JSON/YAML によるテンプレートのデプロイ機能を提供してきましたが、2022年11月に GS2 も CDK のサポートを開始しました。 CDK は現在 Go / Java / PHP / Python / TypeScript をサポートしています。 それぞれのプログラミング言語で、GS2-Inventory の GS2-Deploy 用のテンプレートを生成するコードを記述した例が以下です。 Language: Go Java PHP Python TypeScript stack := core.NewStack() inventory.NewNamespace( &stack, "test", inventory.NamespaceOptions{ }, ).MasterData( []inventory.InventoryModel{ inventory.NewInventoryModel( "inventory", 5, 10, []inventory.ItemModel{ inventory.NewItemModel( "Potion", 99, true, 1, inventory. /ja/articles/master_data/cicd/ Mon, 01 Jan 0001 00:00:00 +0000 /ja/articles/master_data/cicd/ マスターデータの更新作業を自動化することで、人為的なミスを減らし、開発サイクルを高速化できます。 自動化のフロー 一般的な自動化のフローは以下の通りです。 データ作成: Excel や Google スプレッドシート、CSV 等でマスターデータを作成。 変換: スプレッドシートから GS2 のマスターデータ形式（JSON）へ変換。 コミット: 変換後の JSON または GS2-Deploy のテンプレートを Git リポジトリへコミット。 デプロイ: CI ツール（GitHub Actions, CircleCI 等）が変更を検知し、GS2 へ反映。 デプロイの自動化 GS2-Deploy を使用する場合 GS2-Deploy のテンプレートにマスターデータを埋め込んでいる場合、CI から GS2-Deploy のスタックを更新することで反映できます。 GitHub Actions の例: jobs: deploy: runs-on: ubuntu-latest steps: - uses: actions/checkout@v2 - name: GS2 Deploy run: | # gs2-cli 等を使用してスタックを更新 gs2-cli deploy update-stack --stack-name master-data --template-file template.yaml マネージメントコンソールのエクスポート/インポートを使用する場合 各マイクロサービスの CurrentItemModelMaster を更新する API を呼び出すことで、JSON ファイルの内容を反映できます。 /ja/api_reference/state_machine/deploy/extention/ Mon, 01 Jan 0001 00:00:00 +0000 /ja/api_reference/state_machine/deploy/extention/ GSL は可読性・記述性に優れたステートマシン定義言語ですが、IDEの入力支援や学習コストの観点で優れているとは言い難い側面があります。 各種プログラミング言語を使用して GSL を定義する方法として、CDK を利用することができます。 CDK の詳細 ステートマシンの定義の開始 ステートマシンを定義を開始するには以下の構文を使用します。 Language: Java PHP Python TypeScript C# class TestStateMachine extends io.gs2.cdk.stateMachine.integration.StateMachineDefinition { public TestStateMachine() { // ここにステート定義を記述 } } class TestStateMachine extends \Gs2Cdk\StateMachine\Integration\StateMachineDefinition { public function __construct() { parent::__construct(); // ここにステート定義を記述 } } class TestStateMachine(gs2_cdk.state_machine.StateMachineDefinition): def __init__(self): # ここにステート定義を記述 class TestStateMachine extends StateMachineDefinition { constructor() { super(); // ここにステート定義を記述 } } public class TestStateMachine : Gs2Cdk.Gs2StateMachine.Integration.StateMachineDefinition { public TestStateMachine() { // ここにステート定義を記述 } } ステートマシンの定義 Language: Java PHP Python TypeScript C# stateMachine( "