GS2-Script

Luaスクリプト実行環境

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 処理の完了後に非同期で実行されるスクリプトです。
レスポンスタイムには影響せず、ログ出力・統計記録・外部サービス連携などを安全に行えます。

例: GS2-Account の createAccountScript の doneTriggerScriptId を設定すると、アカウント作成が成功した後にスクリプトが走り、外部の分析基盤に新規ユーザー作成イベントを送信する、といった用途に利用できます。

スクリプトの実行モデル

スクリプトの実行は標準で時間制限が設定されており、過剰に長いスクリプトはエラーになります。
スクリプトの実行時間は応答に含まれ、実行コストとして集計されます。

スクリプト内で発生した例外は API 呼び出し全体の例外として伝播し、前処理スクリプトで例外が発生した場合は GS2 標準処理は実行されません。

スクリプトからの GS2 API アクセス

スクリプト内からは GS2 が提供する API 群をそのまま呼び出せます。
GS2-Inventory のアイテム数を確認してから GS2-Account の処理を行う、GS2-Stamina の残量を見て GS2-Mission の達成判定をするなど、複数のマイクロサービスを横断するロジックをスクリプト内で組み立てられます。

スクリプトの実行コンテキストには、API 呼び出しを行ったユーザーのアクセストークンなども渡されるため、認証済みプレイヤーのコンテキストでサーバー API を呼び出せます。

Amazon EventBridge 連携

完了通知の送信先には、GS2-Script のスクリプトの代わりに Amazon EventBridge を指定することもできます。
EventBridge にイベントを送信することで、AWS Lambda などの AWS サービスや、SaaS のイベント駆動型ワークフローに GS2 のイベントを連携でき、ゲーム外のシステムとの統合が容易になります。

GS2 内で完結する処理は GS2-Script、外部システムとの広範な連携は EventBridge と使い分けることで、シンプルかつスケーラブルな運用が可能です。

マスターデータ管理

GS2-Script ではマスターデータの概念はなく、スクリプトそのものが構成データとして管理されます。
スクリプトの登録・更新はマネージメントコンソールから直接行う他、GS2-Deploy のテンプレート (Type: GS2::Script::Script) として記述し、CI から自動的に反映するワークフローも可能です。

トランザクションアクション

GS2-Script ではトランザクションアクションを提供していません。
スクリプト内から GS2 API を呼び出すことで、間接的に各マイクロサービスのトランザクションを発火させることは可能です。

実装例

GS2-Script は管理API中心のマイクロサービスです。ゲームエンジン用 SDK (Unity/Unreal Engine) には専用の Domain クラスが提供されていません。

スクリプトの登録・更新・実行はサーバー側およびネームスペースの構成に関わる操作のため、ゲームクライアントから直接呼び出すのではなく、以下のいずれかの手段で操作することを推奨します。

  • マネジメントコンソール
  • GS2 CLI
  • 各種言語向け一般SDK (C# / Go / Python / TypeScript / PHP / Java)
  • GS2-Deploy によるテンプレート管理

各種SDKの詳細は対応するリファレンスページを参照してください。

マイクロサービスへのスクリプト紐付け

スクリプトを各マイクロサービスのイベントトリガーに紐付ける場合は、対象サービスのネームスペース設定で参照します。
実運用では、マネージメントコンソールから直接設定する、もしくは GS2-Deploy のテンプレートに記述することで、スクリプトの紐付けまで含めて CI/CD で管理できます。

以下は、GS2-Account の CreateAccountScript に「アカウント作成前」(TriggerScriptId) と「アカウント作成完了通知」(DoneTriggerScriptId) のスクリプトを設定する例です。

GS2TemplateFormatVersion: "2019-05-01"
Resources:
  Script:
    Type: GS2::Script::Script
    Properties:
      NamespaceName: namespace-0001
      Name: createAccount
      Script: |
        local result = { permit = true }
        return result

  AccountNamespace:
    Type: GS2::Account::Namespace
    Properties:
      Name: account-namespace
      CreateAccountScript:
        TriggerScriptId: !GetAttr Script.Item.ScriptId
        DoneTriggerTargetType: gs2_script
        DoneTriggerScriptId: !GetAttr Script.Item.ScriptId
    DependsOn:
      - Script

スクリプトは事前に登録しておき、ネームスペース側からは GRN で参照します。
DependsOn でリソース間の依存関係を宣言することで、スクリプトを先に作成してから、それを参照するネームスペースを作成する順序を保証できます。

詳細なリファレンス

GS2-Script リファレンス