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

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

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



## モデル

### EzScore

スコア<br>

ゲームプレイヤーごと・カテゴリーごとに登録されたスコアを保持するエンティティです。<br>
各スコアエントリはユニークIDで識別され、カテゴリーとスコア登録ユーザーに関連付けられます。<br>
合算モードでは、新しいスコアは個別のエントリを作成するのではなく、AddScore 操作で既存の合計に加算されます。<br>
カテゴリーの最小値・最大値の範囲外のスコアは登録時に拒否されます。

|  | 型 | 有効化条件 | 必須 | デフォルト | 値の制限 | 説明 |
| --- | --- | --- | --- | --- | --- | --- |
| categoryName | string |  | ✓ |  |  ~ 128文字 | カテゴリー名 |
| userId | string |  | ✓ |  |  ~ 128文字 | ユーザーID |
| uniqueId | string |  | ✓ | UUID |  ~ 36文字 | ユニークID<br>このスコアエントリを一意に識別する UUID。<br/>作成時に自動生成されます。uniqueByUserId が無効の場合、同一ユーザーの同一カテゴリー内の複数スコアエントリを区別するために使用されます。 |
| scorerUserId | string |  | ✓ |  |  ~ 128文字 | ユーザーID |
| score | long |  | ✓ |  | 0 ~ 9223372036854775805 | スコア<br>プレイヤーが登録したスコア値。<br/>カテゴリーに設定された最小値・最大値の範囲内である必要があります。合算モードでは、AddScore 操作でこの値をインクリメントできます。 |
| metadata | string |  |  |  |  ~ 512文字 | メタデータ<br>メタデータには任意の値を設定できます。<br/>これらの値は GS2 の動作には影響しないため、ゲーム内で利用する情報の保存先として使用できます。 |

**関連するメソッド:**
putScore - ランキングにスコアを登録する
getScore - プレイヤーが登録した特定のスコアを取得する
listScores - 特定プレイヤーが登録したスコアの一覧を取得する


---

### EzRanking

ランキング<br>

ランキングリーダーボードの1エントリを表し、ユーザーの順位、スコア、および関連メタデータを含みます。<br>
グローバルランキング（全プレイヤーが共有ボードでバッチ集計により競争）とスコープランキング（購読したプレイヤーに基づくユーザーごとのボードでリアルタイム反映）の2種類があります。<br>
ランキングはカテゴリーに設定されたソート方向で並び替えられ、同スコアのエントリは同順位を共有しつつ異なるインデックスを保持します。

|  | 型 | 有効化条件 | 必須 | デフォルト | 値の制限 | 説明 |
| --- | --- | --- | --- | --- | --- | --- |
| rank | long |  | ✓ |  | 1 ~ 9223372036854775805 | 順位<br>このエントリのランキング順位（1始まり）。<br/>同スコアのエントリは同じ順位を共有します。例えば、2ユーザーが1位タイの場合、両方とも順位1となり次のエントリは順位3になります。 |
| index | long |  | ✓ |  | 0 ~ 9223372036854775805 | インデックス<br>ランキングリスト内のゼロベースの連番インデックス。<br/>rank と異なり、複数のエントリが同スコアを共有していてもインデックスは常にユニークで連続します。ページネーションや範囲ベースのクエリに使用されます。 |
| userId | string |  | ✓ |  |  ~ 128文字 | ユーザーID |
| score | long |  | ✓ |  | 0 ~ 9223372036854775805 | スコア<br>このランキングエントリのスコア値。<br/>合算モードの場合、登録された全スコアの累積合計です。ランキングのソート順に使用される値はカテゴリーの orderDirection 設定に依存します。 |
| metadata | string |  |  |  |  ~ 512文字 | メタデータ<br>このランキングエントリに関連付けられた任意のメタデータ。<br/>スコア登録時に設定され、ランキング結果と共に返されます。最大512文字。 |
| createdAt | long |  | ✓ |  |  | 作成日時<br>UNIX 時間・ミリ秒<br/>※ サーバー側で自動的に設定 |

**関連するメソッド:**
getNearRanking - 特定のスコア付近のランキングを取得する
getRank - 特定プレイヤーの順位とスコアを取得する
getRanking - ランキングのリーダーボードを取得する


---

### EzSubscribeUser

購読ユーザー<br>

スコープランキングカテゴリー内の個別の購読関係を表します。<br>
各エントリは、親ユーザーが指定カテゴリーでターゲットユーザーのスコアを購読（フォロー）していることを示します。

|  | 型 | 有効化条件 | 必須 | デフォルト | 値の制限 | 説明 |
| --- | --- | --- | --- | --- | --- | --- |
| userId | string |  | ✓ |  |  ~ 128文字 | ユーザーID |
| targetUserId | string |  | ✓ |  |  ~ 128文字 | 購読対象ユーザーID<br>購読先のプレイヤーのユーザーID。<br/>このユーザーのスコアが、購読元ユーザーの指定カテゴリーにおけるスコープランキングに表示されます。 |

**関連するメソッド:**
listSubscribes - フレンドランキング用にフォローしているプレイヤーの一覧を取得する
subscribe - プレイヤーをフォローしてフレンドランキングに含める
unsubscribe - プレイヤーのフォローを解除してフレンドランキングから除外する


---

### EzCategoryModel

カテゴリーモデル<br>

カテゴリー毎に異なるランキングを作成できます。<br>

カテゴリーには登録できるスコアの最小値・最大値を設定でき、その範囲外のスコアは破棄されます。<br>
ランキングを集計する際にスコアを小さいものを上位（昇順）にするか、大きいものを上位（降順）にするかを設定できます。<br>

ランキングの種類として `グローバル` と `スコープ` を選択できます。<br>
グローバルは全プレイヤーが同じ結果を参照するもので、スコープはフレンド内ランキングや、ギルド内ランキングのようなゲームプレイヤー毎に結果の異なるランキングです。<br>

グローバルランキングはカテゴリーごとにランキングの集計間隔を15分～24時間で設定できます。<br>
スコープランキングはリアルタイムで集計結果が反映されます。<br>

ランキングデータには世代という設定があり、世代を変更することで登録されたスコアをリセットすることができます。

|  | 型 | 有効化条件 | 必須 | デフォルト | 値の制限 | 説明 |
| --- | --- | --- | --- | --- | --- | --- |
| name | string |  | ✓ |  |  ~ 128文字 | カテゴリーモデル名<br>カテゴリーモデル固有の名前。英数字および -(ハイフン) _(アンダースコア) .(ピリオド)で指定します。 |
| metadata | string |  |  |  |  ~ 1024文字 | メタデータ<br>メタデータには任意の値を設定できます。<br/>これらの値は GS2 の動作には影響しないため、ゲーム内で利用する情報の保存先として使用できます。 |
| scope | 文字列列挙型<br>enum {<br>&nbsp;&nbsp;"global",<br>&nbsp;&nbsp;"scoped"<br>}<br> |  | ✓ |  |  | ランキングの種類<br>このカテゴリーのランキングタイプ。<br/>"global" は全プレイヤーが共有する単一のリーダーボードを作成し、設定された間隔でバッチ集計されます。<br/>"scoped" は購読したプレイヤー（フレンドやギルドメンバー等）に基づくユーザーごとのリーダーボードを作成し、スコアがリアルタイムで反映されます。"global": グローバル / "scoped": スコープ /  |
| globalRankingSetting | [EzGlobalRankingSetting](#ezglobalrankingsetting) | {scope} == "global" | ✓※ |  |  | グローバルランキング設定<br>グローバルランキングモード固有の設定。集計間隔、固定時刻、スコアのユニーク性、世代管理、および追加の期間限定スコープを含みます。<br/>scope が "global" に設定されている場合のみ適用されます。<br><br>※ scope が "global" であれば 必須 |
| entryPeriodEventId | string |  |  |  |  ~ 1024文字 | スコア登録期間イベントID<br>スコア登録を受け付ける期間を定義する GS2-Schedule イベントの GRN。<br/>この期間外のスコア登録リクエストは拒否されます。未設定の場合、スコアはいつでも登録できます。 |
| accessPeriodEventId | string |  |  |  |  ~ 1024文字 | アクセス期間イベントID<br>ランキングデータを閲覧できる期間を定義する GS2-Schedule イベントの GRN。<br/>この期間外のランキング取得リクエストは拒否されます。未設定の場合、ランキングはいつでもアクセスできます。 |

**関連するメソッド:**
getCategory - 特定のランキングカテゴリの詳細を取得する
listCategories - ランキングカテゴリの一覧を取得する


---

### EzGlobalRankingSetting

グローバルランキング設定<br>

グローバルは全プレイヤーが同じ結果を参照するものです。<br>
ランキングの集計間隔を15分～24時間で設定できます。<br>

ランキングデータには世代という設定があり、世代を変更することで登録されたスコアをリセットすることができます。

|  | 型 | 有効化条件 | 必須 | デフォルト | 値の制限 | 説明 |
| --- | --- | --- | --- | --- | --- | --- |
| calculateIntervalMinutes | int |  | ✓ |  | 15 ~ 1440 | 集計間隔（分）<br>連続するランキング再集計の間隔（分）。<br/>システムはこの間隔で、登録された全スコアに基づいてグローバルランキングを定期的に再集計します。<br/>範囲: 15～1440分（15分～24時間）。 |
| additionalScopes | [List&lt;EzScope&gt;](#ezscope) |  |  |  | 0 ~ 10 items | 追加スコープリスト<br>追加の期間限定集計スコープのリスト。<br/>各スコープは指定した日数以内に登録されたスコアのみを対象とする別ランキングを定義します。<br/>全期間のグローバルランキングと併せて、デイリー・ウィークリー・マンスリーなどのリーダーボードを作成できます。最大10件。 |


**関連するモデル:**
EzCategoryModel - カテゴリーモデル



---

### EzScope

集計スコープ<br>

グローバルランキングモードにおける追加の期間限定集計スコープを定義します。<br>
通常、グローバルランキングは登録されたスコア全てを対象に集計が行われます。<br>
スコープを追加することで、指定した日数以内に登録されたスコアのみを対象とする別ランキングを作成でき、全期間ランキングと併せてデイリー・ウィークリー・マンスリーなどのリーダーボードを実現できます。

|  | 型 | 有効化条件 | 必須 | デフォルト | 値の制限 | 説明 |
| --- | --- | --- | --- | --- | --- | --- |
| name | string |  | ✓ |  |  ~ 128文字 | スコープ名<br>カテゴリー内でこの集計スコープを一意に識別する名前。<br/>複数の期間限定ランキングボードを区別するために使用されます（例: "daily", "weekly"）。最大128文字。 |
| targetDays | long |  | ✓ |  | 1 ~ 365 | 集計対象日数<br>集計ウィンドウに含める日数。<br/>現在時刻からこの日数以内に登録されたスコアのみがスコープランキングの対象となります。範囲: 1～365日。 |


**関連するモデル:**
EzGlobalRankingSetting - グローバルランキング設定



---

## メソッド

### getCategory

特定のランキングカテゴリの詳細を取得する<br>

ランキングカテゴリ名を指定して、スコアリングルールと設定を含む詳細を取得します。<br>

レスポンスには以下が含まれます:<br>
- スコア範囲: 登録可能なスコアの最小値と最大値<br>
- ソート順: スコアが高いほど上位（降順）か、スコアが低いほど上位（昇順、タイムアタックランキングなどに便利）か<br>
- スコープタイプ: グローバルランキングかスコープ付き（フレンド）ランキングか<br>
- グローバルランキングの場合: 計算間隔とタイミング設定<br>
- エントリー/アクセス期間: GS2-Schedule のイベントと連携している場合、スコア登録やランキング閲覧が可能な期間<br>

詳細画面でランキングのルールや設定を表示する際に使います。

#### Request

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

#### Result

|  | 型 | 説明 |
| --- | --- | --- |
| item | [EzCategoryModel](#ezcategorymodel) | カテゴリモデル|

#### 実装例




**Unity (UniTask)**
```csharp
    var domain = gs2.Ranking.Namespace(
        namespaceName: "namespace-0001"
    ).CategoryModel(
        categoryName: "category-0001"
    );
    var item = await domain.ModelAsync();

```

**Unity (Vanilla)**
```cs
    var domain = gs2.Ranking.Namespace(
        namespaceName: "namespace-0001"
    ).CategoryModel(
        categoryName: "category-0001"
    );
    var future = domain.ModelFuture();
    yield return future;
    var item = future.Result;

```

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

```


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




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

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

```

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

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

```

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

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

```


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

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

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

---

### listCategories

ランキングカテゴリの一覧を取得する<br>

ネームスペースに定義されているすべてのランキングカテゴリを取得します。<br>
各カテゴリは独立したリーダーボードを表します。たとえば「ハイスコア」「ボスタイムアタック」「週間バトル勝利数」などです。<br>

ランキングには2つのタイプがあります:<br>
- グローバルランキング: すべてのプレイヤーが1つのリーダーボードで順位付けされます。ランキングは定期的に再計算される（リアルタイムではない）ため、スコア登録からランキングへの反映には遅延があります。<br>
- スコープ付きランキング: プレイヤーごとに、自分と購読（フォロー）しているプレイヤーだけが表示されるパーソナライズされたリーダーボードです（「フレンドランキング」のようなもの）。こちらはリアルタイムで計算されます。<br>

ランキング画面で利用可能なリーダーボードの一覧を表示する際に使います。たとえば「世界ランキング」「フレンドランキング」「週間ランキング」などのタブを表示するような画面です。

#### Request

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

#### Result

|  | 型 | 説明 |
| --- | --- | --- |
| items | [List&lt;EzCategoryModel&gt;](#ezcategorymodel) | カテゴリモデルのリスト|

#### 実装例




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

```

**Unity (Vanilla)**
```cs
    var domain = gs2.Ranking.Namespace(
        namespaceName: "namespace-0001"
    );
    var it = domain.CategoryModels(
    );
    List<EzCategoryModel> items = new List<EzCategoryModel>();
    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->Ranking->Namespace(
        "namespace-0001" // namespaceName
    );
    const auto It = Domain->CategoryModels(
    );
    TArray<Gs2::UE5::Ranking::Model::FEzCategoryModelPtr> Result;
    for (auto Item : *It)
    {
        if (Item.IsError())
        {
            return false;
        }
        Result.Add(Item.Current());
    }

```


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




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

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

```

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

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

```

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

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

```


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

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

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

---

### listSubscribes

フレンドランキング用にフォローしているプレイヤーの一覧を取得する<br>

指定されたランキングカテゴリで、現在のプレイヤーが購読（フォロー）しているプレイヤーの一覧を取得します。<br>
スコープ付き（フレンド）ランキングで使用します。他のプレイヤーを購読すると、そのプレイヤーのスコアがパーソナライズされたフレンドランキングに表示されるようになります。<br>

ランキング画面で「フォロー中」リストを表示する際に使います。フレンドリーダーボードにどのプレイヤーのスコアが含まれているかを確認できます。<br>

たとえば PlayerA、PlayerB、PlayerC を購読している場合、フレンドランキングにはこの3人と自分自身のスコアが表示されます。

#### Request

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

#### Result

|  | 型 | 説明 |
| --- | --- | --- |
| items | [List&lt;EzSubscribeUser&gt;](#ezsubscribeuser) | 購読対象ユーザー情報のリスト|

#### 実装例




**Unity (UniTask)**
```csharp
    var domain = gs2.Ranking.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    ).RankingCategory(
        categoryName: "category-0001",
        additionalScopeName: null
    );
    var items = await domain.SubscribeUsersAsync(
    ).ToListAsync();

```

**Unity (Vanilla)**
```cs
    var domain = gs2.Ranking.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    ).RankingCategory(
        categoryName: "category-0001",
        additionalScopeName: null
    );
    var it = domain.SubscribeUsers(
    );
    List<EzSubscribeUser> items = new List<EzSubscribeUser>();
    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->Ranking->Namespace(
        "namespace-0001" // namespaceName
    )->Me(
        GameSession
    )->RankingCategory(
        "category-0001", // categoryName
        nullptr // additionalScopeName
    );
    const auto It = Domain->SubscribeUsers(
    );
    TArray<Gs2::UE5::Ranking::Model::FEzSubscribeUserPtr> Result;
    for (auto Item : *It)
    {
        if (Item.IsError())
        {
            return false;
        }
        Result.Add(Item.Current());
    }

```


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




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

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

```

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

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

```

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

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

```


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

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

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

---

### subscribe

プレイヤーをフォローしてフレンドランキングに含める<br>

指定されたカテゴリで他のプレイヤーを購読し、そのプレイヤーのスコアが自分のスコープ付き（フレンド）ランキングに表示されるようにします。<br>
「フォロー」機能のようなものです。購読後、対象プレイヤーのスコアがパーソナライズされたフレンドリーダーボードに表示されるようになります。<br>

主な使い方:<br>
- プレイヤーがフレンド追加した際に、すべてのランキングカテゴリで自動的に購読する<br>
- プレイヤーのプロフィール画面に「リーダーボードでフォロー」ボタンを設置する<br>
- 対戦後、対戦した相手をフォローできるようにする<br>

自分自身を購読することはできません（自分のスコアはフレンドランキングに自動的に含まれます）。

#### Request

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

#### Result

|  | 型 | 説明 |
| --- | --- | --- |
| item | [EzSubscribeUser](#ezsubscribeuser) | 購読対象ユーザー情報|

#### 実装例




**Unity (UniTask)**
```csharp
    var domain = gs2.Ranking.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    ).RankingCategory(
        categoryName: "category-0001",
        additionalScopeName: null
    );
    var result = await domain.SubscribeAsync(
        targetUserId: "user-0002"
    );
    var item = await result.ModelAsync();

```

**Unity (Vanilla)**
```cs
    var domain = gs2.Ranking.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    ).RankingCategory(
        categoryName: "category-0001",
        additionalScopeName: null
    );
    var future = domain.SubscribeFuture(
        targetUserId: "user-0002"
    );
    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;

```

**Unreal Engine 5**
```cpp
    const auto Domain = Gs2->Ranking->Namespace(
        "namespace-0001" // namespaceName
    )->Me(
        GameSession
    )->RankingCategory(
        "category-0001", // categoryName
        nullptr // additionalScopeName
    );
    const auto Future = Domain->Subscribe(
        "user-0002" // targetUserId
    );
    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();

```


---

### unsubscribe

プレイヤーのフォローを解除してフレンドランキングから除外する<br>

指定されたランキングカテゴリで、指定されたプレイヤーの購読を解除します。<br>
購読解除後、対象プレイヤーのスコアはスコープ付き（フレンド）ランキングに表示されなくなります。<br>

プレイヤーがフレンドリーダーボードで誰かのスコアを表示しないようにしたいときに使います。たとえばフレンド解除時やフォロー解除時です。

#### Request

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

#### Result

|  | 型 | 説明 |
| --- | --- | --- |
| item | [EzSubscribeUser](#ezsubscribeuser) | 解除した購読対象ユーザー情報|

#### 実装例




**Unity (UniTask)**
```csharp
    var domain = gs2.Ranking.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    ).RankingCategory(
        categoryName: "category-0001",
        additionalScopeName: null
    ).SubscribeUser(
        targetUserId: "user-0002"
    );
    var result = await domain.UnsubscribeAsync(
    );

```

**Unity (Vanilla)**
```cs
    var domain = gs2.Ranking.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    ).RankingCategory(
        categoryName: "category-0001",
        additionalScopeName: null
    ).SubscribeUser(
        targetUserId: "user-0002"
    );
    var future = domain.UnsubscribeFuture(
    );
    yield return future;
    if (future.Error != null)
    {
        onError.Invoke(future.Error, null);
        yield break;
    }

```

**Unreal Engine 5**
```cpp
    const auto Domain = Gs2->Ranking->Namespace(
        "namespace-0001" // namespaceName
    )->Me(
        GameSession
    )->RankingCategory(
        "category-0001", // categoryName
        nullptr // additionalScopeName
    )->SubscribeUser(
        "user-0002" // targetUserId
    );
    const auto Future = Domain->Unsubscribe(
    );
    Future->StartSynchronousTask();
    if (Future->GetTask().IsError())
    {
        return false;
    }
    const auto Result = Future->GetTask().Result();

```


---

### getNearRanking

特定のスコア付近のランキングを取得する<br>

指定されたスコア値を中心としたランキングの一部を取得します。<br>
プレイヤーが「自分がどのあたりの順位か」を確認するのに便利です。たとえばリーダーボード上で、プレイヤーのスコアの前後数人を表示できます。<br>

一般的な使い方: プレイヤーがゲームを終えた後、自分のスコアとその付近のランキングを表示:<br>
「98位: PlayerX (5,200 pt) → あなた: 5,150 pt → 99位: PlayerY (5,100 pt)」<br>

このAPIはグローバルランキングでのみ使用できます。スコープ付き（フレンド）ランキングの場合はリストが十分小さいため、代わりに GetRanking を使ってください。

#### Request

|  | 型 | 有効化条件 | 必須 | デフォルト | 値の制限 | 説明 |
| --- | --- | --- | --- | --- | --- | --- |
| namespaceName | string |  | ✓|  |  ~ 128文字 | ネームスペース名<br>ネームスペース固有の名前。英数字および -(ハイフン) _(アンダースコア) .(ピリオド)で指定します。 |
| categoryName | string |  | ✓|  |  ~ 128文字 | カテゴリーモデル名<br>カテゴリーモデル固有の名前。英数字および -(ハイフン) _(アンダースコア) .(ピリオド)で指定します。 |
| additionalScopeName | string |  | |  |  ~ 128文字 | スコープ名<br>カテゴリー内でこの集計スコープを一意に識別する名前。<br/>複数の期間限定ランキングボードを区別するために使用されます（例: "daily", "weekly"）。最大128文字。 |
| score | long |  | ✓|  | 0 ~ 9223372036854775805 | スコア<br>このランキングエントリのスコア値。<br/>合算モードの場合、登録された全スコアの累積合計です。ランキングのソート順に使用される値はカテゴリーの orderDirection 設定に依存します。 |

#### Result

|  | 型 | 説明 |
| --- | --- | --- |
| items | [List&lt;EzRanking&gt;](#ezranking) | ランキングのリスト|

#### 実装例




**Unity (UniTask)**
```csharp
    var domain = gs2.Ranking.Namespace(
        namespaceName: "namespace-0001"
    ).User(
        userId: "user-0001"
    ).RankingCategory(
        categoryName: "category-0001",
        additionalScopeName: null
    );
    var items = await domain.NearRankingsAsync(
        score: 1000L
    ).ToListAsync();

```

**Unity (Vanilla)**
```cs
    var domain = gs2.Ranking.Namespace(
        namespaceName: "namespace-0001"
    ).User(
        userId: "user-0001"
    ).RankingCategory(
        categoryName: "category-0001",
        additionalScopeName: null
    );
    var it = domain.NearRankings(
        score: 1000L
    );
    List<EzRanking> items = new List<EzRanking>();
    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->Ranking->Namespace(
        "namespace-0001" // namespaceName
    )->User(
        "user-0001" // userId
    )->RankingCategory(
        "category-0001", // categoryName
        nullptr // additionalScopeName
    );
    const auto It = Domain->NearRankings(
        1000L // score
    );
    TArray<Gs2::UE5::Ranking::Model::FEzRankingPtr> Result;
    for (auto Item : *It)
    {
        if (Item.IsError())
        {
            return false;
        }
        Result.Add(Item.Current());
    }

```


---

### getRank

特定プレイヤーの順位とスコアを取得する<br>

特定プレイヤーのランキング情報を、順位とスコアを含めて取得します。<br>
結果画面やプロフィールページで「あなたの順位: 42位 (8,500 pt)」のように表示する際に使います。<br>

scorerUserId（順位を調べたいプレイヤー）を指定する必要があります。uniqueId はカテゴリがプレイヤーごとにスコアを1つしか許可しない場合は省略できます（デフォルト "0"）。カテゴリがプレイヤーごとに複数スコアを許可する場合は、uniqueId を指定してどのスコアを調べるか特定します。

#### Request

|  | 型 | 有効化条件 | 必須 | デフォルト | 値の制限 | 説明 |
| --- | --- | --- | --- | --- | --- | --- |
| namespaceName | string |  | ✓|  |  ~ 128文字 | ネームスペース名<br>ネームスペース固有の名前。英数字および -(ハイフン) _(アンダースコア) .(ピリオド)で指定します。 |
| categoryName | string |  | ✓|  |  ~ 128文字 | カテゴリーモデル名<br>カテゴリーモデル固有の名前。英数字および -(ハイフン) _(アンダースコア) .(ピリオド)で指定します。 |
| additionalScopeName | string |  | |  |  ~ 128文字 | スコープ名<br>カテゴリー内でこの集計スコープを一意に識別する名前。<br/>複数の期間限定ランキングボードを区別するために使用されます（例: "daily", "weekly"）。最大128文字。 |
| scorerUserId | string |  | ✓|  |  ~ 128文字 | スコアを獲得したユーザーのユーザーID |
| gameSession | GameSession | | ✓|  |  | GameSession |
| uniqueId | string |  | | "0" |  ~ 36文字 | スコアのユニークID |

#### Result

|  | 型 | 説明 |
| --- | --- | --- |
| item | [EzRanking](#ezranking) | ランキング|

#### 実装例




**Unity (UniTask)**
```csharp
    var domain = gs2.Ranking.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    ).RankingCategory(
        categoryName: "category-0001",
        additionalScopeName: null
    ).Ranking(
        scorerUserId: "user-0001",
        index: null
    );
    var item = await domain.ModelAsync(
        scorerUserId : "user-0001"
    );

```

**Unity (Vanilla)**
```cs
    var domain = gs2.Ranking.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    ).RankingCategory(
        categoryName: "category-0001",
        additionalScopeName: null
    ).Ranking(
        scorerUserId: "user-0001",
        index: null
    );
    var future = domain.Model(
        scorerUserId : "user-0001"
    );
    yield return future;
    var item = future.Result;

```

**Unreal Engine 5**
```cpp
    const auto Domain = Gs2->Ranking->Namespace(
        "namespace-0001" // namespaceName
    )->Me(
        GameSession
    )->RankingCategory(
        "category-0001", // categoryName
        nullptr // additionalScopeName
    )->Ranking(
        "user-0001", // scorerUserId
        nullptr // index
    );
    const auto Future = Domain->Model(
        "user-0001" // scorerUserId
    );
    Future->StartSynchronousTask();
    if (Future->GetTask().IsError())
    {
        return false;
    }

```


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




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

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

```

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

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

```

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

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

```


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

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

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

---

### getRanking

ランキングのリーダーボードを取得する<br>

指定されたカテゴリのランキング一覧を取得します。プレイヤーがスコア順に並んで表示されます。<br>
リーダーボード画面を表示するためのメインAPIです。たとえば「1位: PlayerA (10,500 pt)、2位: PlayerB (9,800 pt)、...」のような表示です。<br>

startIndex を指定して特定の順位から取得を開始できます（例: startIndex=0 でトップから、startIndex=99 で100位付近から）。<br>

グローバルランキングの場合、データは最後の計算結果に基づくため、スコア登録からランキング更新まで遅延がある場合があります。<br>
スコープ付き（フレンド）ランキングの場合、データはリアルタイムで計算されます。<br>

カテゴリが追加スコープに対応している場合、additionalScopeName を指定してランキングをさらに絞り込めます。

#### Request

|  | 型 | 有効化条件 | 必須 | デフォルト | 値の制限 | 説明 |
| --- | --- | --- | --- | --- | --- | --- |
| namespaceName | string |  | ✓|  |  ~ 128文字 | ネームスペース名<br>ネームスペース固有の名前。英数字および -(ハイフン) _(アンダースコア) .(ピリオド)で指定します。 |
| categoryName | string |  | ✓|  |  ~ 128文字 | カテゴリーモデル名<br>カテゴリーモデル固有の名前。英数字および -(ハイフン) _(アンダースコア) .(ピリオド)で指定します。 |
| additionalScopeName | string |  | |  |  ~ 128文字 | スコープ名<br>カテゴリー内でこの集計スコープを一意に識別する名前。<br/>複数の期間限定ランキングボードを区別するために使用されます（例: "daily", "weekly"）。最大128文字。 |
| gameSession | GameSession | | |  |  | GameSession |
| limit | int |  | | 30 | 1 ~ 1000 | データの取得件数 |
| pageToken | string |  | |  |  ~ 4096文字 | データの取得を開始する位置を指定するトークン |
| startIndex | long |  | |  | 0 ~ 9223372036854775805 | ランキングの取得を開始するインデックス |

#### Result

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

#### 実装例




**Unity (UniTask)**
```csharp
    var domain = gs2.Ranking.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    ).RankingCategory(
        categoryName: "category-0001",
        additionalScopeName: null
    );
    var items = await domain.RankingsAsync(
    ).ToListAsync();

```

**Unity (Vanilla)**
```cs
    var domain = gs2.Ranking.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    ).RankingCategory(
        categoryName: "category-0001",
        additionalScopeName: null
    );
    var it = domain.Rankings(
    );
    List<EzRanking> items = new List<EzRanking>();
    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->Ranking->Namespace(
        "namespace-0001" // namespaceName
    )->Me(
        GameSession
    )->RankingCategory(
        "category-0001", // categoryName
        nullptr // additionalScopeName
    );
    const auto It = Domain->Rankings(
    );
    TArray<Gs2::UE5::Ranking::Model::FEzRankingPtr> Result;
    for (auto Item : *It)
    {
        if (Item.IsError())
        {
            return false;
        }
        Result.Add(Item.Current());
    }

```


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




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

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

```

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

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

```

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

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

```


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

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

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

---

### putScore

ランキングにスコアを登録する<br>

指定されたランキングカテゴリにプレイヤーのスコアを登録します。<br>
プレイヤーが記録したいスコアを達成したときに呼び出します。たとえばステージクリア後、タイムアタック終了時、対戦終了時などです。<br>

スコアにはメタデータ（文字列）をオプションで添付できます。リーダーボード上でスコアと一緒に表示したい追加情報を保存するのに便利です。たとえばプレイヤーのキャラクター名、チーム構成、リプレイデータなどです。<br>

スコアの扱いはカテゴリのタイプによって異なります:<br>
- グローバルランキング: スコアが収集され、次のスケジュールされた間隔でランキングが再計算されます。ランキングが更新されるまで遅延があります。<br>
- スコープ付きランキング: スコアは即座に反映され、このプレイヤーを購読（フォロー）しているプレイヤーのフレンドランキングに表示されます。<br>

注意: カテゴリの設定によって、プレイヤーごとに最高スコア（昇順ランキングの場合は最低スコア）のみが保持される場合と、複数のスコアが許可される場合があります。

#### Request

|  | 型 | 有効化条件 | 必須 | デフォルト | 値の制限 | 説明 |
| --- | --- | --- | --- | --- | --- | --- |
| namespaceName | string |  | ✓|  |  ~ 128文字 | ネームスペース名<br>ネームスペース固有の名前。英数字および -(ハイフン) _(アンダースコア) .(ピリオド)で指定します。 |
| categoryName | string |  | ✓|  |  ~ 128文字 | カテゴリーモデル名<br>カテゴリーモデル固有の名前。英数字および -(ハイフン) _(アンダースコア) .(ピリオド)で指定します。 |
| gameSession | GameSession | | ✓|  |  | GameSession |
| score | long |  | ✓|  | 0 ~ 9223372036854775805 | スコア<br>このランキングエントリのスコア値。<br/>合算モードの場合、登録された全スコアの累積合計です。ランキングのソート順に使用される値はカテゴリーの orderDirection 設定に依存します。 |
| metadata | string |  | |  |  ~ 512文字 | メタデータ<br>このランキングエントリに関連付けられた任意のメタデータ。<br/>スコア登録時に設定され、ランキング結果と共に返されます。最大512文字。 |

#### Result

|  | 型 | 説明 |
| --- | --- | --- |
| item | [EzScore](#ezscore) | 登録したスコア|

#### 実装例




**Unity (UniTask)**
```csharp
    var domain = gs2.Ranking.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    ).RankingCategory(
        categoryName: "category-0001",
        additionalScopeName: null
    );
    var result = await domain.PutScoreAsync(
        score: 1000L,
        metadata: null
    );
    var item = await result.ModelAsync();

```

**Unity (Vanilla)**
```cs
    var domain = gs2.Ranking.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    ).RankingCategory(
        categoryName: "category-0001",
        additionalScopeName: null
    );
    var future = domain.PutScoreFuture(
        score: 1000L,
        metadata: null
    );
    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;

```

**Unreal Engine 5**
```cpp
    const auto Domain = Gs2->Ranking->Namespace(
        "namespace-0001" // namespaceName
    )->Me(
        GameSession
    )->RankingCategory(
        "category-0001", // categoryName
        nullptr // additionalScopeName
    );
    const auto Future = Domain->PutScore(
        1000L // score
        // metadata
    );
    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();

```


---

### getScore

プレイヤーが登録した特定のスコアを取得する<br>

指定されたランキングカテゴリで、指定されたプレイヤーの1つのスコアレコードを取得します。<br>
特定スコアの詳細を表示する際に使います。たとえばスコアの値、登録日時、添付されたメタデータ（キャラクター名やリプレイデータなど）を表示できます。<br>

uniqueId はプレイヤーが複数スコアを持つ場合にどのスコアを取得するかを指定します。カテゴリがプレイヤーごとにスコアを1つしか許可しない場合（最も一般的なケース）は、uniqueId を省略するか "0" に設定できます。

#### Request

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

#### Result

|  | 型 | 説明 |
| --- | --- | --- |
| item | [EzScore](#ezscore) | スコア|

#### 実装例




**Unity (UniTask)**
```csharp
    var domain = gs2.Ranking.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    ).Score(
        categoryName: "category-0001",
        scorerUserId: "user-0002",
        uniqueId: "unique-0001"
    );
    var item = await domain.ModelAsync();

```

**Unity (Vanilla)**
```cs
    var domain = gs2.Ranking.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    ).Score(
        categoryName: "category-0001",
        scorerUserId: "user-0002",
        uniqueId: "unique-0001"
    );
    var future = domain.ModelFuture();
    yield return future;
    var item = future.Result;

```

**Unreal Engine 5**
```cpp
    const auto Domain = Gs2->Ranking->Namespace(
        "namespace-0001" // namespaceName
    )->Me(
        GameSession
    )->Score(
        "category-0001", // categoryName
        "user-0002", // scorerUserId
        "unique-0001" // uniqueId
    );
    const auto Future = Domain->Model();
    Future->StartSynchronousTask();
    if (Future->GetTask().IsError())
    {
        return false;
    }

```


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




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

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

```

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

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

```

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

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

```


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

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

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

---

### listScores

特定プレイヤーが登録したスコアの一覧を取得する<br>

指定されたランキングカテゴリで、特定のプレイヤーが登録したすべてのスコアを取得します。<br>
プレイヤーのスコア履歴を表示する際に使います。たとえば、タイムアタックステージの全挑戦記録を一覧表示するような場合です。<br>

ランキングの表示（すべてのプレイヤーをスコア順に表示）とは異なり、このAPIは1人の特定プレイヤーの登録スコアに焦点を当てています。<br>

カテゴリがプレイヤーごとにスコアを1つしか許可しない場合は1件だけ返されます。複数スコアが許可されている場合（例: 複数回の挑戦）は、すべてのスコアが返されます。

#### Request

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

#### Result

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

#### 実装例




**Unity (UniTask)**
```csharp
    var domain = gs2.Ranking.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    );
    var items = await domain.ScoresAsync(
        categoryName: "category-0001",
        scorerUserId: "user-0002"
    ).ToListAsync();

```

**Unity (Vanilla)**
```cs
    var domain = gs2.Ranking.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    );
    var it = domain.Scores(
        categoryName: "category-0001",
        scorerUserId: "user-0002"
    );
    List<EzScore> items = new List<EzScore>();
    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->Ranking->Namespace(
        "namespace-0001" // namespaceName
    )->Me(
        GameSession
    );
    const auto It = Domain->Scores(
        "category-0001", // categoryName
        "user-0002" // scorerUserId
    );
    TArray<Gs2::UE5::Ranking::Model::FEzScorePtr> Result;
    for (auto Item : *It)
    {
        if (Item.IsError())
        {
            return false;
        }
        Result.Add(Item.Current());
    }

```


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




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

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

```

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

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

```

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

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

```


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

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

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

---