GS2-ScriptによるGS2(Game Server Services)の機能拡張

こんにちは、ゲームソリューション部の入井です。

今回の記事では、GS2の各種マイクロサービスの処理内容を細かくカスタマイズ可能な機能であるGS2-Scriptについて、概要と使い方をご紹介します。

GS2-Scriptとは

GS2-ScriptはGS2が提供する機能の1つで、専用のスクリプトをGS2上に登録しておくことで、GS2の様々なマイクロサービスの動作を拡張することができます。

具体的には、各マイクロサービスの特定の処理タイミングで任意のスクリプトが実行されるよう設定しておくことで、各処理の結果を調整することが可能です。例えば、GS2-Lotteryの抽選実行時に追加でスクリプトも実行し、特定の条件を満たす際に任意の景品を追加する、といったような形で調整できます。

スクリプトの実行タイミングはイベントトリガーと呼ばれており、マイクロサービス毎に個別に設定されています。例えばGS2-Lotteryでは上述のように抽選実行時にスクリプトを呼び出すことができます。

各サービスでのイベントトリガーについては、以下のようなサービス毎に用意されているScriptトリガーリファレンスにて確認できます。

https://docs.gs2.io/ja/api_reference/lottery/script/

スクリプトについては、Luaという言語を使って書く必要があります。Luaの文法については、以下のサイトが参考になります。

https://takezoff.github.io/x8support/#!lua_basics.md

また、GS2では上記の基本文法の他に、以下のページで書かれているような拡張メソッドも用意されています。Luaのテーブル型とJSONの相互変換や、HTTPリクエスト等のGS2の機能を拡張する上で便利な機能が揃っています。

https://docs.gs2.io/ja/articles/script/

なお、今回の記事では取り扱いませんが、Luaスクリプトの他にもAWSのAmazon EventBridgeと連携することで機能を拡張することもできます。こちらについては、以下の公式ドキュメントで詳細な手順が記載されています。

https://docs.gs2.io/ja/overview/workflow/coding/extend/event_bridge/

実際にScriptを動かしてみた

今回は、以前に以下の記事で作成したアイテム購入処理関係のリソースを使って、GS2-Scriptの検証を行いました。

https://dev.classmethod.jp/articles/gs2-buy-item-transaction/

上記記事のアイテム購入処理では、プレイヤーのアイテム情報の管理にGS2-Inventoryを使い、購入処理にGS2-Exchangeを使用しました。今回は、GS2-Inventoryにスクリプトを組み込んでみます。

GS2-Inventoryのイベントトリガー

GS2-Inventoryのトリガーリファレンスを見ると、以下のようなタイミングでGS2-Scriptを呼び出すことが可能と書かれています。（主要なもののみ抜粋）

GS2-Inventory Script トリガーリファレンス

この中から今回はconsume（アイテム消費実行前）トリガーにスクリプトを設定してみます。

スクリプトの作成

イベントトリガーでスクリプトを呼び出すためには、まずGS2-Script上にスクリプトを登録しておく必要があります。

スクリプト登録にあたっては、マネージドコンソールのGS2-Script設定画面にアクセスし、最初にネームスペースを作成します。その後、ネームスペース上で「スクリプトの新規作成」をクリックします。

スクリプト編集画面では、エディタを使ってスクリプトを記載できるほか、任意の引数を渡してのテストも実行できるようになっています。

GS2-inventoryのconsumeトリガーでは、以下のようなフォーマットになっています（ドキュメントより引用）

Request

Result

RequestがスクリプトがGS2から受け取る引数で、ResultはスクリプトがGS2へ送る戻り値のフォーマットとなります。Resultで必須と指定されているプロパティがスクリプトの戻り値に含まれていないと、エラーが発生します。

今回の場合、Resultはpermitが必須となっています。これがtrueだとアイテムが通常通り消費されますが、falseだと消費が中断される形です。

overridConsumeCountは必須ではないですが、数値を指定することでその名の通りアイテムの消費量を上書きすることができます。

今回は、引数の一部を標準出力し、通常通りにアイテム消費を行う以下のスクリプトを作成しました。名前は「inventoryTest」で登録しました。

consumeItemName = args.consumeItemName
userId = args.userId
consumeCount = args.consumeCount

print(consumeItemName)
print(userId)
print(consumeCount)

result = {
    permit=true
}

イベントトリガーへの設定

作成したスクリプトをGS2-Inventoryのconsumeイベントトリガーへ組み込んでいきます。

マネジメントコンソール上でGS2-Inventoryの設定画面を開きます。拡張スクリプトという部分があるので、そこの「アイテムを消費するときに実行するスクリプト」という項目で先ほど登録したスクリプトを指定します。

これで、イベントトリガーへのスクリプトの登録は完了です。

動作結果

Unityプロジェクト上で動作を確認します。

ボタンを押すことで、持ち物の中のお金を150円支払ってジュースを1個手に入れる処理をGS2上で設定しています。持ち物の管理にはGS2-Inventoryを使い、GS2-Exchangeで持ち物同士の交換処理を設定しています。

ボタンをクリックすると、GS2上での設定通りお金が減ってジュースが増えました。スクリプトではGS2の処理結果に変更を加えていないので、想定通りの動作となります。

次は、スクリプトの内容を少し書き換えてみます。overrideConsumeCountで5を指定しました。

consumeItemName = args.consumeItemName
userId = args.userId
consumeCount = args.consumeCount

print(consumeItemName)
print(userId)
print(consumeCount)

result = {
    permit=true,
    overrideConsumeCount=5
}

新しいスクリプトを登録した上で、もう一度動作を確認してみます。

ボタンをクリックすると、今度はお金は5円しか消費されませんでした。ジュースは従来通り1つ増えています。

これは、先ほどのスクリプトでアイテムの消費数が5になるようGS2の処理に介入したためです。このように、GS2-Scriptを使用することでGS2の処理内容を全く別のものに調整することが可能となっています。

今回はアイテム消費数を強制的に5に変更しましたが、例えばスクリプト中に条件分岐を入れることで、特定の条件を満たす場合のみ消費数を増減させたり、アイテムの消費を中止するといった処理が実装可能です。

なお、GS2-Scriptのネームスペースでログ書き出しを有効化していると、GS2-LogのアクセスログリストでGS2-Scriptのinvokeメソッドの実行記録として、スクリプトのログが記録されます。なお、スクリプト中の標準出力内容は、以下のようにレスポンスのoutput内に表示されます。

まとめ

GS2-Scriptを利用するまでの流れを紹介しました。

今回書いたスクリプトはかなりシンプルなものでしたが、より複雑なスクリプトを作成することでGS2の標準機能では対応していないことも実行できるようになります。

ただ、あまり複雑なものを作ってしまうと運用のためのコストが高くなってしまうため、利用場面はよく見極める必要があると思われます。