> For the complete documentation index, see [llms.txt](/llms.txt)

# GS2-Experience SDK for Game Engine API リファレンス

ゲームエンジン向け GS2-Experience SDK の モデルの仕様 と API のリファレンス



## モデル

### EzStatus

ステータス<br>

ステータスとはプロパティID毎に存在するエンティティで、<br>
現在の経験値やランクキャップの値を保持します。<br>

プロパティID とはステータス固有のIDで、開発者が任意の値を設定できます。<br>
GS2 では経験値を有する GS2-Inventory のアイテムセットGRN や GS2-Dictionary のエントリーGRN の後ろに<br>
経験値モデルとなるサフィックスを追加した値をプロパティIDとすることを推奨しています。

|  | 型 | 有効化条件 | 必須 | デフォルト | 値の制限 | 説明 |
| --- | --- | --- | --- | --- | --- | --- |
| experienceName | string |  | ✓ |  |  ~ 128文字 | 経験値モデル名<br>このステータスのランキングルールを定義する経験値モデルの名前です。どのランクアップ閾値テーブルとランクキャップ設定が適用されるかを決定します。 |
| propertyId | string |  | ✓ |  |  ~ 1024文字 | プロパティID<br>ユーザースコープ内でこのステータスを一意に識別する開発者定義の識別子です。経験値を持つ GS2-Inventory のアイテムセット GRN や GS2-Dictionary のエントリー GRN の末尾に経験値モデルのサフィックスを付与した値を使用することを推奨します。 |
| experienceValue | long |  |  | 0 | 0 ~ 9223372036854775805 | 累計獲得経験値<br>このステータスが蓄積した合計経験値です。現在のランクはこの値からランクアップ閾値テーブルを使用して算出されます。現在のランクキャップに対応する閾値を超えて経験値を獲得することはできません。 |
| rankValue | long |  |  | 0 | 0 ~ 9223372036854775805 | 現在のランク<br>ランクアップ閾値テーブルを使用して累計経験値から算出されるランク（レベル）です。0 から開始し、経験値閾値を超えるごとに増加します。現在のランクキャップ値を超えることはできません。 |
| rankCapValue | long |  | ✓ |  | 0 ~ 9223372036854775805 | 現在のランクキャップ<br>このステータスが現在到達できる最大ランクです。初期値は経験値モデルの defaultRankCap に設定され、限界突破などのランクキャップ増加操作により maxRankCap まで引き上げることができます。 |
| nextRankUpExperienceValue | long |  |  | 0 | 0 ~ 9223372036854775805 | 次のランクアップの経験値量<br>次のランクに到達するために必要な累計経験値の閾値です。ステータスが既にランクキャップに到達している場合は 0 を返します。ゲーム UI でプログレスバーや残り経験値を表示するのに便利です。 |

**関連するメソッド:**
getStatus - 特定のアイテムやキャラクターのレベル・経験値ステータスを取得する
getStatusWithSignature - 改ざん防止の署名付きでレベル・経験値ステータスを取得する
listStatuses - プレイヤーのレベル・経験値ステータスの一覧を取得する


---

### EzExperienceModel

経験値モデル<br>

経験値とランクシステムのルールを定義します。ランクアップに必要な経験値の閾値、デフォルトのランクキャップ、最大ランクキャップを設定します。ランクキャップはステータスが到達できる最大ランクを制限し、ステータスごとに最大ランクキャップまで引き上げることができます（例: 限界突破）。オプションで、現在のランクに基づいて報酬倍率を調整する入手アクションレートテーブルを含めることができます。

|  | 型 | 有効化条件 | 必須 | デフォルト | 値の制限 | 説明 |
| --- | --- | --- | --- | --- | --- | --- |
| name | string |  | ✓ |  |  ~ 128文字 | 経験値モデル名<br>経験値モデル固有の名前。英数字および -(ハイフン) _(アンダースコア) .(ピリオド)で指定します。 |
| metadata | string |  |  |  |  ~ 2048文字 | メタデータ<br>メタデータには任意の値を設定できます。<br>これらの値は GS2 の動作には影響しないため、ゲーム内で利用する情報の保存先として使用できます。 |
| defaultExperience | long |  |  | 0 | 0 ~ 9223372036854775805 | 経験値の初期値<br>新規作成されたステータスに割り当てられる経験値です。通常、プレイヤーが進行の最初から始めるように 0 に設定されます。初期ランクはこの値からランクアップ閾値テーブルを使用して決定されます。 |
| defaultRankCap | long |  | ✓ |  | 0 ~ 9223372036854775805 | ランクキャップの初期値<br>新規作成されたステータスが到達できるデフォルトの最大ランクです。このランクの閾値を超えた経験値は破棄されるかオーバーフロースクリプトがトリガーされます。ランクキャップは限界突破などの操作により、ステータスごとに maxRankCap まで引き上げることができます。 |
| maxRankCap | long |  | ✓ |  | 0 ~ 9223372036854775805 | ランクキャップの最大値<br>ランクキャップの絶対的な上限です。ランクキャップ増加操作（限界突破など）を行っても、ランクキャップはこの値を超えることはできません。defaultRankCap 以上の値である必要があります。 |
| rankThreshold | [EzThreshold](#ezthreshold) |  | ✓ |  |  | ランクアップ閾値<br>各ランクに必要な累計経験値を定義する閾値テーブルを参照します。閾値のエントリ数が到達可能な最大ランクを決定し、各エントリの値は次のランクに到達するために必要な経験値を指定します。 |
| acquireActionRates | [List&lt;EzAcquireActionRate&gt;](#ezacquireactionrate) |  |  |  | 0 ~ 100 items | 報酬加算テーブルリスト<br>ステータスのランクを参照として使用する際に報酬量を調整するランクベースの倍率テーブルを定義します。各テーブルはランクと倍率をマッピングし、同じアクションからより高ランクのキャラクターがより多くの報酬を受け取るような仕組みを実現できます。 |

**関連するメソッド:**
getExperienceModel - 名前を指定して経験値モデルを取得する
listExperienceModels - 経験値モデルの一覧を取得する


---

### EzThreshold

ランクアップ閾値<br>

ランクアップ閾値は経験値からランク（レベル）を決定するために必要な数列です。<br>
[10, 20] という値を設定した場合、経験値の値が 0~9 の間はランク1、10~19 の間はランク2、経験値の値が 20 でランク3 となり、それ以上経験値を入手することが出来なくなります。

|  | 型 | 有効化条件 | 必須 | デフォルト | 値の制限 | 説明 |
| --- | --- | --- | --- | --- | --- | --- |
| metadata | string |  |  |  |  ~ 2048文字 | メタデータ<br>メタデータには任意の値を設定できます。<br>これらの値は GS2 の動作には影響しないため、ゲーム内で利用する情報の保存先として使用できます。 |
| values | List&lt;long&gt; |  | ✓ |  | 1 ~ 10000 items | ランクアップ経験値閾値リスト<br>ランク進行を定義する累計経験値の順序付き配列です。エントリ数が到達可能な最大ランクを決定します。例えば [10, 20] の場合、経験値 0〜9 でランク1、10〜19 でランク2、20 以上でランク3（それ以上の経験値獲得は不可）となります。 |


**関連するモデル:**
EzExperienceModel - 経験値モデル



---

### EzAcquireAction

入手アクション

|  | 型 | 有効化条件 | 必須 | デフォルト | 値の制限 | 説明 |
| --- | --- | --- | --- | --- | --- | --- |
| action | 文字列列挙型<br>enum {<br>}<br> |  | ✓ |  |  | 入手アクションで実行するアクションの種類 |
| request | string |  | ✓ |  |  ~ 524288文字 | アクション実行時に使用されるリクエストのJSON文字列 |


---

### EzAcquireActionRate

報酬加算テーブル<br>

ステータスの現在のランクに基づいて報酬量を調整するランクベースの倍率テーブルを定義します。テーブルの各エントリはランクに対応し、入手量に適用される倍率を指定します。標準的な倍精度浮動小数点値と、大規模な計算用の大数値文字列表現の両方をサポートします。

|  | 型 | 有効化条件 | 必須 | デフォルト | 値の制限 | 説明 |
| --- | --- | --- | --- | --- | --- | --- |
| name | string |  | ✓ |  |  ~ 128文字 | 報酬加算テーブル名<br>この報酬加算テーブルの一意な識別子です。特定の入手アクションに適用する倍率テーブルを指定する際に参照されます。 |
| mode | 文字列列挙型<br>enum {<br>&nbsp;&nbsp;"double",<br>&nbsp;&nbsp;"big"<br>}<br> |  |  | "double" |  | 報酬加算テーブルの種類<br>倍率値の数値精度を選択します。標準的な浮動小数点数（2^48 まで）には "double" を、大規模な計算が必要な場合は 1024 桁までの文字列表現をサポートする "big" を使用します。"double": 2^48 未満の浮動小数点数 / "big": 文字列表記で1024桁未満の浮動小数点数 /  |
| rates | List&lt;double&gt; | {mode} == "double" | ✓※ |  | 1 ~ 10000 items | ランクごとの加算量(倍率)<br>ランクをインデックスとする倍率値の配列です。i 番目のエントリはステータスがランク i の時に適用される報酬倍率を定義します。mode が "double" に設定されている場合に使用されます。<br><br>※ mode が "double" であれば 必須 |
| bigRates | List&lt;string&gt; | {mode} == "big" | ✓※ |  | 1 ~ 10000 items | ランクごとの加算量(倍率)<br>ランクをインデックスとする文字列表現の倍率値の配列です。i 番目のエントリはステータスがランク i の時に適用される報酬倍率を定義します。大数値精度が必要な計算で mode が "big" に設定されている場合に使用されます。<br><br>※ mode が "big" であれば 必須 |


**関連するモデル:**
EzExperienceModel - 経験値モデル



---

### EzVerifyActionResult

検証アクションの実行結果

|  | 型 | 有効化条件 | 必須 | デフォルト | 値の制限 | 説明 |
| --- | --- | --- | --- | --- | --- | --- |
| action | 文字列列挙型<br>enum {<br>}<br> |  | ✓ |  |  | 検証アクションで実行するアクションの種類 |
| verifyRequest | string |  | ✓ |  |  ~ 524288文字 | アクション実行時に使用されるリクエストのJSON文字列 |
| statusCode | int |  |  |  | 0 ~ 999 | ステータスコード |
| verifyResult | string |  |  |  |  ~ 1048576文字 | 結果内容 |


**関連するモデル:**
EzTransactionResult - トランザクション実行結果



---

### EzConsumeActionResult

消費アクションの実行結果

|  | 型 | 有効化条件 | 必須 | デフォルト | 値の制限 | 説明 |
| --- | --- | --- | --- | --- | --- | --- |
| action | 文字列列挙型<br>enum {<br>}<br> |  | ✓ |  |  | 消費アクションで実行するアクションの種類 |
| consumeRequest | string |  | ✓ |  |  ~ 524288文字 | アクション実行時に使用されるリクエストのJSON文字列 |
| statusCode | int |  |  |  | 0 ~ 999 | ステータスコード |
| consumeResult | string |  |  |  |  ~ 1048576文字 | 結果内容 |


**関連するモデル:**
EzTransactionResult - トランザクション実行結果



---

### EzAcquireActionResult

入手アクションの実行結果

|  | 型 | 有効化条件 | 必須 | デフォルト | 値の制限 | 説明 |
| --- | --- | --- | --- | --- | --- | --- |
| action | 文字列列挙型<br>enum {<br>}<br> |  | ✓ |  |  | 入手アクションで実行するアクションの種類 |
| acquireRequest | string |  | ✓ |  |  ~ 524288文字 | アクション実行時に使用されるリクエストのJSON文字列 |
| statusCode | int |  |  |  | 0 ~ 999 | ステータスコード |
| acquireResult | string |  |  |  |  ~ 1048576文字 | 結果内容 |


**関連するモデル:**
EzTransactionResult - トランザクション実行結果



---

### EzTransactionResult

トランザクション実行結果<br>

サーバーサイドでのトランザクションの自動実行機能を利用して実行されたトランザクションの実行結果

|  | 型 | 有効化条件 | 必須 | デフォルト | 値の制限 | 説明 |
| --- | --- | --- | --- | --- | --- | --- |
| transactionId | string |  | ✓ |  | 36 ~ 36文字 | トランザクションID |
| verifyResults | [List&lt;EzVerifyActionResult&gt;](#ezverifyactionresult) |  |  |  | 0 ~ 10 items | 検証アクションの実行結果リスト |
| consumeResults | [List&lt;EzConsumeActionResult&gt;](#ezconsumeactionresult) |  |  | [] | 0 ~ 10 items | 消費アクションの実行結果リスト |
| acquireResults | [List&lt;EzAcquireActionResult&gt;](#ezacquireactionresult) |  |  | [] | 0 ~ 100 items | 入手アクションの実行結果リスト |


---

## メソッド

### getExperienceModel

名前を指定して経験値モデルを取得する<br>

名前を指定して、経験値モデルを1件取得します。<br>
取得できる情報には、各レベルに必要な経験値（ランクアップ閾値）、デフォルトの最大レベル、絶対的な最大レベルが含まれます。<br>
レベルの進捗を計算・表示する際に使います。たとえば、プレイヤーの武器が次のレベルに到達するのにあとどれだけ経験値が必要か、限界突破後の最大レベルはいくつかを表示するのに便利です。

#### Request

|  | 型 | 有効化条件 | 必須 | デフォルト | 値の制限 | 説明 |
| --- | --- | --- | --- | --- | --- | --- |
| namespaceName | string |  | ✓|  |  ~ 128文字 | ネームスペース名<br>ネームスペース固有の名前。英数字および -(ハイフン) _(アンダースコア) .(ピリオド)で指定します。 |
| experienceName | string |  | ✓|  |  ~ 128文字 | 経験値モデル名<br>経験値モデル固有の名前。英数字および -(ハイフン) _(アンダースコア) .(ピリオド)で指定します。 |

#### Result

|  | 型 | 説明 |
| --- | --- | --- |
| item | [EzExperienceModel](#ezexperiencemodel) | 経験値モデル|

#### 実装例




**Unity (UniTask)**
```csharp
    var domain = gs2.Experience.Namespace(
        namespaceName: "namespace-0001"
    ).ExperienceModel(
        experienceName: "experience-0001"
    );
    var item = await domain.ModelAsync();

```

**Unity (Vanilla)**
```cs
    var domain = gs2.Experience.Namespace(
        namespaceName: "namespace-0001"
    ).ExperienceModel(
        experienceName: "experience-0001"
    );
    var future = domain.ModelFuture();
    yield return future;
    var item = future.Result;

```

**Unreal Engine 5**
```cpp
    const auto Domain = Gs2->Experience->Namespace(
        "namespace-0001" // namespaceName
    )->ExperienceModel(
        "experience-0001" // experienceName
    );
    const auto Future = Domain->Model();
    Future->StartSynchronousTask();
    if (Future->GetTask().IsError())
    {
        return false;
    }

```


##### 値の変更イベントハンドリング




**Unity (UniTask)**
```csharp
    var domain = gs2.Experience.Namespace(
        namespaceName: "namespace-0001"
    ).ExperienceModel(
        experienceName: "experience-0001"
    );
    
    // イベントハンドリングを開始
    var callbackId = domain.Subscribe(
        value => {
            // 値が変化した時に呼び出される
            // value には変更後の値が渡ってくる
        }
    );

    // イベントハンドリングを停止
    domain.Unsubscribe(callbackId);

```

**Unity (Vanilla)**
```cs
    var domain = gs2.Experience.Namespace(
        namespaceName: "namespace-0001"
    ).ExperienceModel(
        experienceName: "experience-0001"
    );
    
    // イベントハンドリングを開始
    var callbackId = domain.Subscribe(
        value => {
            // 値が変化した時に呼び出される
            // value には変更後の値が渡ってくる
        }
    );

    // イベントハンドリングを停止
    domain.Unsubscribe(callbackId);

```

**Unreal Engine 5**
```cpp
    const auto Domain = Gs2->Experience->Namespace(
        "namespace-0001" // namespaceName
    )->ExperienceModel(
        "experience-0001" // experienceName
    );
    
    // イベントハンドリングを開始
    const auto CallbackId = Domain->Subscribe(
        [](TSharedPtr<Gs2::Experience::Model::FExperienceModel> value) {
            // 値が変化した時に呼び出される
            // value には変更後の値が渡ってくる
        }
    );

    // イベントハンドリングを停止
    Domain->Unsubscribe(CallbackId);

```


{{% alert title="Warning" color="warning" %}}このイベントはSDKがもつローカルキャッシュの値が変更された時に呼び出されます。

ローカルキャッシュは SDK が持つ API の実行、または GS2-Gateway の通知を有効にした GS2-Distributor 経由でのスタンプシートの実行、または GS2-Gateway の通知を有効にした GS2-JobQueue の実行によって変化したもののみが対象となります。

そのため、これらの方法以外で値が変更されてもコールバックは呼び出されません。
{{% /alert %}}

---

### listExperienceModels

経験値モデルの一覧を取得する<br>

このネームスペースに登録されているすべての経験値モデルを取得します。<br>
経験値モデルはレベルアップの仕組みを定義します。各レベルに必要な経験値、デフォルトの最大レベル、絶対的な最大レベルなどを設定します。<br>
レベルアップ関連のUIを構築する際に使います。たとえば「次のレベルまで: 150/500 EXP」の表示や、キャラクター詳細画面でレベルアップの閾値を表示するのに便利です。

#### Request

|  | 型 | 有効化条件 | 必須 | デフォルト | 値の制限 | 説明 |
| --- | --- | --- | --- | --- | --- | --- |
| namespaceName | string |  | ✓|  |  ~ 128文字 | ネームスペース名<br>ネームスペース固有の名前。英数字および -(ハイフン) _(アンダースコア) .(ピリオド)で指定します。 |

#### Result

|  | 型 | 説明 |
| --- | --- | --- |
| items | [List&lt;EzExperienceModel&gt;](#ezexperiencemodel) | 経験値モデルリスト|

#### 実装例




**Unity (UniTask)**
```csharp
    var domain = gs2.Experience.Namespace(
        namespaceName: "namespace-0001"
    );
    var items = await domain.ExperienceModelsAsync(
    ).ToListAsync();

```

**Unity (Vanilla)**
```cs
    var domain = gs2.Experience.Namespace(
        namespaceName: "namespace-0001"
    );
    var it = domain.ExperienceModels(
    );
    List<EzExperienceModel> items = new List<EzExperienceModel>();
    while (it.HasNext())
    {
        yield return it.Next();
        if (it.Error != null)
        {
            onError.Invoke(it.Error, null);
            break;
        }
        if (it.Current != null)
        {
            items.Add(it.Current);
        }
        else
        {
            break;
        }
    }

```

**Unreal Engine 5**
```cpp
    const auto Domain = Gs2->Experience->Namespace(
        "namespace-0001" // namespaceName
    );
    const auto It = Domain->ExperienceModels(
    );
    TArray<Gs2::UE5::Experience::Model::FEzExperienceModelPtr> Result;
    for (auto Item : *It)
    {
        if (Item.IsError())
        {
            return false;
        }
        Result.Add(Item.Current());
    }

```


##### 値の変更イベントハンドリング




**Unity (UniTask)**
```csharp
    var domain = gs2.Experience.Namespace(
        namespaceName: "namespace-0001"
    );
    
    // イベントハンドリングを開始
    var callbackId = domain.SubscribeExperienceModels(
        () => {
            // リストの要素が変化した時に呼び出される
        }
    );

    // イベントハンドリングを停止
    domain.UnsubscribeExperienceModels(callbackId);

```

**Unity (Vanilla)**
```cs
    var domain = gs2.Experience.Namespace(
        namespaceName: "namespace-0001"
    );
    
    // イベントハンドリングを開始
    var callbackId = domain.SubscribeExperienceModels(
        () => {
            // リストの要素が変化した時に呼び出される
        }
    );

    // イベントハンドリングを停止
    domain.UnsubscribeExperienceModels(callbackId);

```

**Unreal Engine 5**
```cpp
    const auto Domain = Gs2->Experience->Namespace(
        "namespace-0001" // namespaceName
    );
    
    // イベントハンドリングを開始
    const auto CallbackId = Domain->SubscribeExperienceModels(
        []() {
            // リストの要素が変化した時に呼び出される
        }
    );

    // イベントハンドリングを停止
    Domain->UnsubscribeExperienceModels(CallbackId);

```


{{% alert title="Warning" color="warning" %}}このイベントはSDKがもつローカルキャッシュの値が変更された時に呼び出されます。

ローカルキャッシュは SDK が持つ API の実行、または GS2-Gateway の通知を有効にした GS2-Distributor 経由でのスタンプシートの実行、または GS2-Gateway の通知を有効にした GS2-JobQueue の実行によって変化したもののみが対象となります。

そのため、これらの方法以外で値が変更されてもコールバックは呼び出されません。
{{% /alert %}}

---

### getStatus

特定のアイテムやキャラクターのレベル・経験値ステータスを取得する<br>

プレイヤーが所持する特定のプロパティの現在のレベル、経験値、最大レベルを取得します。<br>
プロパティは経験値モデル名（どのレベルアップシステムを使うか）とプロパティID（どのアイテムやキャラクターか）で識別します。<br>
詳細画面を表示する際に使います。たとえば「鉄の剣 Lv.15 — EXP: 3200/5000 — 最大Lv: 50」のような表示に便利です。

#### Request

|  | 型 | 有効化条件 | 必須 | デフォルト | 値の制限 | 説明 |
| --- | --- | --- | --- | --- | --- | --- |
| namespaceName | string |  | ✓|  |  ~ 128文字 | ネームスペース名<br>ネームスペース固有の名前。英数字および -(ハイフン) _(アンダースコア) .(ピリオド)で指定します。 |
| experienceName | string |  | ✓|  |  ~ 128文字 | 経験値モデル名<br>このステータスのランキングルールを定義する経験値モデルの名前です。どのランクアップ閾値テーブルとランクキャップ設定が適用されるかを決定します。 |
| gameSession | GameSession | | ✓|  |  | GameSession |
| propertyId | string |  | ✓|  |  ~ 1024文字 | プロパティID<br>ユーザースコープ内でこのステータスを一意に識別する開発者定義の識別子です。経験値を持つ GS2-Inventory のアイテムセット GRN や GS2-Dictionary のエントリー GRN の末尾に経験値モデルのサフィックスを付与した値を使用することを推奨します。 |

#### Result

|  | 型 | 説明 |
| --- | --- | --- |
| item | [EzStatus](#ezstatus) | ステータス|

#### 実装例




**Unity (UniTask)**
```csharp
    var domain = gs2.Experience.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    ).Status(
        experienceName: "character_ssr",
        propertyId: "property-0001"
    );
    var item = await domain.ModelAsync();

```

**Unity (Vanilla)**
```cs
    var domain = gs2.Experience.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    ).Status(
        experienceName: "character_ssr",
        propertyId: "property-0001"
    );
    var future = domain.ModelFuture();
    yield return future;
    var item = future.Result;

```

**Unreal Engine 5**
```cpp
    const auto Domain = Gs2->Experience->Namespace(
        "namespace-0001" // namespaceName
    )->Me(
        GameSession
    )->Status(
        "character_ssr", // experienceName
        "property-0001" // propertyId
    );
    const auto Future = Domain->Model();
    Future->StartSynchronousTask();
    if (Future->GetTask().IsError())
    {
        return false;
    }

```


##### 値の変更イベントハンドリング




**Unity (UniTask)**
```csharp
    var domain = gs2.Experience.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    ).Status(
        experienceName: "character_ssr",
        propertyId: "property-0001"
    );
    
    // イベントハンドリングを開始
    var callbackId = domain.Subscribe(
        value => {
            // 値が変化した時に呼び出される
            // value には変更後の値が渡ってくる
        }
    );

    // イベントハンドリングを停止
    domain.Unsubscribe(callbackId);

```

**Unity (Vanilla)**
```cs
    var domain = gs2.Experience.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    ).Status(
        experienceName: "character_ssr",
        propertyId: "property-0001"
    );
    
    // イベントハンドリングを開始
    var callbackId = domain.Subscribe(
        value => {
            // 値が変化した時に呼び出される
            // value には変更後の値が渡ってくる
        }
    );

    // イベントハンドリングを停止
    domain.Unsubscribe(callbackId);

```

**Unreal Engine 5**
```cpp
    const auto Domain = Gs2->Experience->Namespace(
        "namespace-0001" // namespaceName
    )->Me(
        GameSession
    )->Status(
        "character_ssr", // experienceName
        "property-0001" // propertyId
    );
    
    // イベントハンドリングを開始
    const auto CallbackId = Domain->Subscribe(
        [](TSharedPtr<Gs2::Experience::Model::FStatus> value) {
            // 値が変化した時に呼び出される
            // value には変更後の値が渡ってくる
        }
    );

    // イベントハンドリングを停止
    Domain->Unsubscribe(CallbackId);

```


{{% alert title="Warning" color="warning" %}}このイベントはSDKがもつローカルキャッシュの値が変更された時に呼び出されます。

ローカルキャッシュは SDK が持つ API の実行、または GS2-Gateway の通知を有効にした GS2-Distributor 経由でのスタンプシートの実行、または GS2-Gateway の通知を有効にした GS2-JobQueue の実行によって変化したもののみが対象となります。

そのため、これらの方法以外で値が変更されてもコールバックは呼び出されません。
{{% /alert %}}

---

### getStatusWithSignature

改ざん防止の署名付きでレベル・経験値ステータスを取得する<br>

getStatus と同じレベル・経験値情報を取得しますが、データが改ざんされていないことを証明する暗号署名も一緒に返します。<br>
プレイヤーのレベルを信頼できる方法で検証する必要がある場合に便利です。たとえば、他のサービスでレベルを条件として使う場合や、外部システムにレベルデータを渡して真正性を確認する必要がある場合に使います。

#### Request

|  | 型 | 有効化条件 | 必須 | デフォルト | 値の制限 | 説明 |
| --- | --- | --- | --- | --- | --- | --- |
| namespaceName | string |  | ✓|  |  ~ 128文字 | ネームスペース名<br>ネームスペース固有の名前。英数字および -(ハイフン) _(アンダースコア) .(ピリオド)で指定します。 |
| experienceName | string |  | ✓|  |  ~ 128文字 | 経験値モデル名<br>このステータスのランキングルールを定義する経験値モデルの名前です。どのランクアップ閾値テーブルとランクキャップ設定が適用されるかを決定します。 |
| gameSession | GameSession | | ✓|  |  | GameSession |
| propertyId | string |  | ✓|  |  ~ 1024文字 | プロパティID<br>ユーザースコープ内でこのステータスを一意に識別する開発者定義の識別子です。経験値を持つ GS2-Inventory のアイテムセット GRN や GS2-Dictionary のエントリー GRN の末尾に経験値モデルのサフィックスを付与した値を使用することを推奨します。 |
| keyId | string |  | | "grn:gs2:{region}:{ownerId}:key:default:key:default" |  ~ 1024文字 | 暗号鍵GRN |

#### Result

|  | 型 | 説明 |
| --- | --- | --- |
| item | [EzStatus](#ezstatus) | ステータス|
| body | string | 検証対象のオブジェクト|
| signature | string | 署名|

#### 実装例




**Unity (UniTask)**
```csharp
    var domain = gs2.Experience.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    ).Status(
        experienceName: "character_ssr",
        propertyId: "property-0001"
    );
    var result = await domain.GetStatusWithSignatureAsync(
        keyId: "key-0001"
    );
    var item = await result.ModelAsync();
    var body = result.Body;
    var signature = result.Signature;

```

**Unity (Vanilla)**
```cs
    var domain = gs2.Experience.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    ).Status(
        experienceName: "character_ssr",
        propertyId: "property-0001"
    );
    var future = domain.GetStatusWithSignatureFuture(
        keyId: "key-0001"
    );
    yield return future;
    if (future.Error != null)
    {
        onError.Invoke(future.Error, null);
        yield break;
    }
    var future2 = future.Result.ModelFuture();
    yield return future2;
    if (future2.Error != null)
    {
        onError.Invoke(future2.Error, null);
        yield break;
    }
    var result = future2.Result;
    var body = future.Result.Body;
    var signature = future.Result.Signature;

```

**Unreal Engine 5**
```cpp
    const auto Domain = Gs2->Experience->Namespace(
        "namespace-0001" // namespaceName
    )->Me(
        GameSession
    )->Status(
        "character_ssr", // experienceName
        "property-0001" // propertyId
    );
    const auto Future = Domain->GetStatusWithSignature(
        "key-0001" // keyId
    );
    Future->StartSynchronousTask();
    if (Future->GetTask().IsError())
    {
        return false;
    }

    // obtain changed values / result values
    const auto Future2 = Future->GetTask().Result()->Model();
    Future2->StartSynchronousTask();
    if (Future2->GetTask().IsError())
    {
        return Future2->GetTask().Error();
    }
    const auto Result = Future2->GetTask().Result();
    const auto Body = Result->Body;
    const auto Signature = Result->Signature;

```


---

### listStatuses

プレイヤーのレベル・経験値ステータスの一覧を取得する<br>

プレイヤーのアイテムやキャラクターの現在のレベルと経験値情報を取得します。<br>
経験値モデル名でフィルタリングすることもできます。省略するとすべての経験値タイプのステータスが返されます。<br>
各ステータスには、特定のプロパティ（武器やキャラクターなど）の現在の経験値、現在のレベル、最大レベルが含まれます。<br>
プレイヤーがレベルを上げたアイテムの一覧画面を構築するのに使います。たとえば「鉄の剣 Lv.15、炎の杖 Lv.8」のように表示できます。

#### Request

|  | 型 | 有効化条件 | 必須 | デフォルト | 値の制限 | 説明 |
| --- | --- | --- | --- | --- | --- | --- |
| namespaceName | string |  | ✓|  |  ~ 128文字 | ネームスペース名<br>ネームスペース固有の名前。英数字および -(ハイフン) _(アンダースコア) .(ピリオド)で指定します。 |
| experienceName | string |  | |  |  ~ 128文字 | 経験値モデル名 |
| gameSession | GameSession | | ✓|  |  | GameSession |
| pageToken | string |  | |  |  ~ 1024文字 | データの取得を開始する位置を指定するトークン |
| limit | int |  | | 30 | 1 ~ 1000 | データの取得件数 |

#### Result

|  | 型 | 説明 |
| --- | --- | --- |
| items | [List&lt;EzStatus&gt;](#ezstatus) | ステータスのリスト|
| nextPageToken | string | リストの続きを取得するためのページトークン|

#### 実装例




**Unity (UniTask)**
```csharp
    var domain = gs2.Experience.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    );
    var items = await domain.StatusesAsync(
        experienceName: "character_ssr"
    ).ToListAsync();

```

**Unity (Vanilla)**
```cs
    var domain = gs2.Experience.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    );
    var it = domain.Statuses(
        experienceName: "character_ssr"
    );
    List<EzStatus> items = new List<EzStatus>();
    while (it.HasNext())
    {
        yield return it.Next();
        if (it.Error != null)
        {
            onError.Invoke(it.Error, null);
            break;
        }
        if (it.Current != null)
        {
            items.Add(it.Current);
        }
        else
        {
            break;
        }
    }

```

**Unreal Engine 5**
```cpp
    const auto Domain = Gs2->Experience->Namespace(
        "namespace-0001" // namespaceName
    )->Me(
        GameSession
    );
    const auto It = Domain->Statuses(
        "character_ssr" // experienceName
    );
    TArray<Gs2::UE5::Experience::Model::FEzStatusPtr> Result;
    for (auto Item : *It)
    {
        if (Item.IsError())
        {
            return false;
        }
        Result.Add(Item.Current());
    }

```


##### 値の変更イベントハンドリング




**Unity (UniTask)**
```csharp
    var domain = gs2.Experience.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    );
    
    // イベントハンドリングを開始
    var callbackId = domain.SubscribeStatuses(
        () => {
            // リストの要素が変化した時に呼び出される
        }
    );

    // イベントハンドリングを停止
    domain.UnsubscribeStatuses(callbackId);

```

**Unity (Vanilla)**
```cs
    var domain = gs2.Experience.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    );
    
    // イベントハンドリングを開始
    var callbackId = domain.SubscribeStatuses(
        () => {
            // リストの要素が変化した時に呼び出される
        }
    );

    // イベントハンドリングを停止
    domain.UnsubscribeStatuses(callbackId);

```

**Unreal Engine 5**
```cpp
    const auto Domain = Gs2->Experience->Namespace(
        "namespace-0001" // namespaceName
    )->Me(
        GameSession
    );
    
    // イベントハンドリングを開始
    const auto CallbackId = Domain->SubscribeStatuses(
        []() {
            // リストの要素が変化した時に呼び出される
        }
    );

    // イベントハンドリングを停止
    Domain->UnsubscribeStatuses(CallbackId);

```


{{% alert title="Warning" color="warning" %}}このイベントはSDKがもつローカルキャッシュの値が変更された時に呼び出されます。

ローカルキャッシュは SDK が持つ API の実行、または GS2-Gateway の通知を有効にした GS2-Distributor 経由でのスタンプシートの実行、または GS2-Gateway の通知を有効にした GS2-JobQueue の実行によって変化したもののみが対象となります。

そのため、これらの方法以外で値が変更されてもコールバックは呼び出されません。
{{% /alert %}}

---