GS2-Buff

バフ機能

GS2-Buff は GS2 が提供するマイクロサービスの対価や報酬、ユーザーデータの最大値に補正を一元管理する機能を提供します。期間限定で報酬を増加させる機能や、サブスクリプション契約状態であればユーザーデータの最大値が増加するような機能を実現するために利用できます。

バフエンティティ

各マイクロサービスに加える補正の単位です。基礎値を 1.0 として、各パラメータに対してどの程度増減させるかを定義します。補正値の定義方法は「Add」と「Mul」が用意されており、Add 1.5 とすると補正値は2.5倍に、Mul 1.5 とすると補正値は1.5倍になります。

適用優先度

補正値には適用優先度を設定できます。優先度に設定された値が小さい補正値から順番に補正値の計算が行われます。たとえば、以下の補正値が定義されていたとします。

補正値の種類	補正値	適用優先度
Add	0.2	1
Mul	1.5	2
Add	0.2	3

この場合、以下の順番で補正値の計算が実行されます。

1.0 + 0.2 = 1.2
1.2 * 1.5 = 1.8
1.8 + 0.2 = 2.0

そして、最終的な補正値は 2.0倍となります。

補正対象の設定

バフによる補正対象は大きく2種類あり、「モデル」と「アクション」があります。どのようなモデルやアクションを設定できるかは各マイクロサービスのバフに関するドキュメントを参照してください。

モデル

モデルの適用対象の例には以下のようなものがあります。

GS2-Experience のランクキャップ
GS2-Stamina のスタミナ最大値
GS2-Showcase の入手アクション
GS2-Showcase の消費アクション

アクション

アクションの適用対象の例には以下のようなものがあります。

GS2-Experience の経験値加算量
GS2-Stamina のスタミナ回復量
GS2-Stamina のスタミナ消費量

補正適用条件の設定

GS2-Showcase に適用するとして、どの DisplayItem に補正値を適用するのか？ GS2-Experience に適用するとして、どの Status に補正値を適用するのか？といった適用条件を設定するのがこのパラメーターです。

各バフに対してどのような適用条件が設定できるかは各マイクロサービスのバフに関するドキュメントを参照してください。

モデルとGRN

適用条件にはモデルとGRNを指定します。バフによっては複数のモデルを指定できる場合があります。例えば、GS2-Showcase であれば、Showcase 内の全ての DisplayItem に補正を適用するために、Showcase の GRN を指定するパターンと Showcase 内の特定の DisplayItem にのみ補正を適用するために DisplayItem の GRN を指定するパターンがあります。

バフには複数の適用条件を設定でき、いずれかの条件に該当すると補正値が適用されます。つまり、1つのバフエンティティに複数の DisplayItem を適用条件に設定することで、1つのバフエンティティで複数の DisplayItem に対する補正値を定義できます。

補正の適用方法

GS2-Buff の ApplyBuff API を呼び出すと「コンテキストスタック」が応答されます。 GS2 が提供するあらゆるAPIにはコンテキストスタックを設定可能なインターフェースが用意されています。 GS2-Buff が応答したコンテキストスタックを各APIの呼び出し時に指定することでバフを適用できます。

ゲームエンジン向けのSDKのような高レベルなSDKでは、コンテキストスタックの指定はラップされ明示的に指定する必要がないケースがあります。

補正の適用範囲

バフの適用範囲は広範囲で、マスターデータの取得APIでもバフが適用されます。コンテキストスタックを指定した状態でマスターデータ取得APIを呼び出すと、バフがかかった状態の値が応答されます。ゲーム内でバフがかかっていない状態の値を併記したい場合は、コンテキストスタックを付与しないAPIアクセスを組み合わせて表示する必要があります。

バフエンティティと GS2-Schedule の連携

コンテキストスタック内のバフ情報は有効期間を保持します。つまり、バフエンティティに有効期間として GS2-Schedule のイベントが設定されている場合、イベント期間外になった際には自動的にバフは適用されなくなります。

ただし、新しくバフの適用条件が変更になったり、新しいバフが追加された場合は改めて ApplyBuff を呼び出してバフを反映する必要があります。

コンテキストスタックの有効期限

コンテキストスタックには有効期限が設定されています。 ApplyBuff を呼び出した時点から24時間を経過するとコンテキストスタックは効力を失います。

ApplyBuff は条件に変更がなくとも24時間以内に再度実行するようにしてください。

実装例

バフを適用

    var domain = gs2.Buff.Namespace(
        "buff"
    ).Me(
        GameSession
    ).Buff();
    gs2 = await domain.ApplyBuffAsync();

    // 新しい gs2 オブジェクトを通してアクセスするとバフがかかった値で処理される

詳細なリファレンス

APIリファレンス