GS2-Buff

バフ機能
Tags:

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

バフエンティティ

各マイクロサービスに加える補正の単位です。
基礎値を 1.0 として、各パラメータに対してどの程度増減させるかを定義します。
補正値の定義方法は「Rate Add」と「Mul」、「Value Add」が用意されています。
「Rate Add」と「Mul」は補正値の係数に対する演算で Rate Add 1.5 とすると補正値は2.5倍に、Mul 1.5 とすると補正値は1.5倍になります。
「Value Add」は係数ではなく値を直接加算する演算で Value Add 5 とすると補正値は +5 となります。「Value Add」はモデルやアクションの数値にのみ適用可能で Transaction Action に対して適用することはできません。

適用優先度

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

補正値の種類補正値適用優先度
Rate Add0.21
Mul1.52
Rate Add0.23

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

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

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

Value Add が含まれる補正計算

補正値の中に 「Value Add」が含まれる場合は、補正計算が 「Value Add」の定義されている優先度の前で一旦計算し、計算後の値に対して値の加算が行われます。

補正値の種類補正値適用優先度
Rate Add0.21
Mul1.52
Value Add23
Rate Add0.24

この場合、まずは Value Add が出現する直前までの補正値の計算が実行されます。

1.0 + 0.2 = 1.2
1.2 * 1.5 = 1.8

そして、入力値に一旦この補正値を適用します。例えば入力が 10 の場合、1.8倍して補正後の値は 18 となります。
補正後の値に対して「Value Add」の +2 が適用され、補正後の値は 20 となります。

続けて Value Add が出現した直後からの補正値の計算が実行されます。

1.0 + 0.2 = 1.2

そして、入力値に一旦この補正値を適用します。入力が 10 の場合、1.2倍して補正後の値は 12 となります。
「Value Add」 後の補正値にこの値を加算します。

20 + 12 = 32

これで、入力が 10 の場合の最終的な補正後の値は 32 となります。

全体の式をまとめると以下のようになります。入力値を x としています。

((x(1.0 + 0.2) * 1.5) + 2) + (1.0 + 0.2)

補正対象の設定

バフによる補正対象は大きく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 オブジェクトを通してアクセスするとバフがかかった値で処理される

詳細なリファレンス