GS2-Dictionary

図鑑機能

GS2-Dictionary では、ゲーム内で入手したアイテムやキャラクターの図鑑機能を実現します。

基本的に、GS2-Inventory のシンプルな実装バージョンと捉えていただければよく、入手済み・未入手の2値の所持状態を管理できます。

図鑑以外の用途にも使用できます。たとえばアバターパーツの所持状態はいい例です。アバターパーツを持っているかは、パーツごとに2値で状態管理できれば十分なので GS2-Dictionary 向きです。

ただし、不要なパーツを売却できる仕様がある場合は GS2-Dictionary ではエントリーの削除ができないため扱えません。ゲームが必要とする仕様にあわせて GS2-Inventory と GS2-Dictionary を使い分ける必要があります。

GS2-Inventory との違い

スタックの概念の有無

GS2-Inventory は同一アイテムを複数所持する際に、スタックの概念があります。これは、ポーションは最大99個スタック可能で、99個を超えると2個目のスタックを作成するというような仕様です。

この仕様があるため、GS2-Inventory では「ポーションの所持数量を取得する」というAPIの戻り値がリストになっています。これはポーションが複数スタック存在する可能性があるためです。この仕様はポーションのようなデータを管理するには都合がいいのですが、図鑑のようなシンプルな所持状態を管理するにはオーバースペックで、リストを取り扱うとコードの記述量も増加します。

入手処理で複数エントリーを登録可能

GS2-Inventory はポーションの入手とエリクサーの入手は別のAPIリクエストで処理する必要があります。 GS2-Dictionary は1回のAPIリクエストで最大10個のエントリーを登録できます。

実装例

図鑑への記録

図鑑への記録はゲームエンジン用の SDK では処理できません。

GS2-Quest のクリア報酬として倒したモンスターを記録する報酬を設定したり、GS2-Showcase で購入したアイテムを記録する報酬を設定することで、記録処理を行う必要があります。

図鑑に記録可能なマスターデータのリスト取得

マスターデータは事前に GS2 にアップロードする必要があります。マスターデータの管理方法については別途マスターデータを取り扱うためのセクションがありますので、そちらを確認してください。

    var items = await gs2.Dictionary.Namespace(
        namespaceName: "namespace-0001"
    ).EntryModelsAsync(
    ).ToListAsync();

    const auto Domain = Gs2->Dictionary->Namespace(
        "namespace-0001" // namespaceName
    );
    const auto It = Domain->EntryModels(
    );
    TArray<Gs2::UE5::Dictionary::Model::FEzEntryModelPtr> Result;
    for (auto Item : *It)
    {
        if (Item.IsError())
        {
            return false;
        }
        Result.Add(Item.Current());
    }

図鑑に記録されたエントリーのリスト取得

    var items = await gs2.Dictionary.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    ).EntriesAsync(
    ).ToListAsync();

    const auto Domain = Gs2->Dictionary->Namespace(
        "namespace-0001" // namespaceName
    )->Me(
        AccessToken
    );
    const auto It = Domain->Entries(
    );
    for (auto Item : *It)
    {

    }

所持証明署名の取得

GS2 内の他のマイクロサービスと連携する際に、本当に GS2-Dictionary でエントリーが記録済みか保証したデータを求められることがあります。

たとえば、GS2-Dictionary でアバターパーツの所持状態を管理しており、GS2-Formation でアバターパーツの編成状態を管理するとします。 GS2-Formation に髪型を設定する際に「hair-0001」というパーツを設定するよう APIリクエストを出すことになりますが GS2-Formation は所持証明署名をとあわせて「hair-0001」を指定するよう要求します。

これによって、GS2-Formation は裏で GS2-Dictionary と通信して、本当に所持しているパーツかを判断する必要がなくなります。

    var result = await gs2.Dictionary.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    ).Entry(
        entryModelName: "entry-0001"
    ).GetEntryWithSignatureAsync(
        keyId: "grn:gs2:{region}:{yourOwnerId}:key:namespace-0001:key:key-0001"
    );

    var body = result.Body;
    var signature = result.Signature;

    const auto Domain = Gs2->Dictionary->Namespace(
        "namespace-0001" // namespaceName
    )->Me(
        AccessToken
    )->Entry(
        "entry-0001" // entryModelName
    );
    const auto Future = Domain->GetEntryWithSignature(
        "key-0001"
    );
    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 false;
    const auto Result = Future2->GetTask().Result();
    const auto Body = Result->Body;
    const auto Signature = Result->Signature;

詳細なリファレンス

APIリファレンス