GS2-Inventory

所持品管理機能

プレイヤーが所持しているアイテムの情報を管理します。

インベントリ

プレイヤーが所持するカバンに相当するエンティティです。 カバンには容量が設定可能で、その容量を超えるアイテムを格納することはできません。

アイテム

アイテムは所持品の種類を定義します。 アイテムには、スタック可能な最大数量を指定できます。

たとえば、ポーションというアイテムの種類が存在し、最大99個スタック可能とした場合 インベントリの容量の消費量1で99個までポーションを所持することが可能となります。

さらに、アイテムには複数スタックを所持可能かを指定できます。 複数スタック所持を可能に設定すると、100個以上のポーションを所持できるようになり、 例えば、150個のポーションを所持している場合は 99 個スタックされたポーションと、51個スタックされたポーションの2つのエントリが作成され、 インベントリの容量が 2 消費されます。

複数スタック所持を不可能の設定した場合、99個を超えるポーションを所持することはできなくなり それ以上ポーションを入手しても破棄されます。

アイテムの有効期限

アイテムには有効期限を設定できます。 有効期限を設定したアイテムは、設定時刻をすぎると自動的にインベントリから消去されます。

有効期限の設定されたアイテムは有効期限ごとに異なるスタックが作成され、それぞれインベントリの容量を消費します。 そのため、複数スタックを所持できないアイテムに有効期限をつけて配布すると、最初に入手した有効期限のアイテム(あるは最初に入手した有効期限のないアイテム)以外は破棄されます。

アイテムセット

1種類のアイテムを複数スタック管理できるよう、アイテムの種類をまとめたアイテムセットというエンティティが存在します。 このエンティティはスタックごとにアイテムの種類を表すIDとは別に、スタック固有のIDをもちます。 このスタック固有のIDを使用すれば、「ポーション x 99」と「ポーション x 51」のそれぞれのスタックを明確に区別することができます。

ポーションを消費する際に、ポーションを示すアイテムIDに加えてスタック固有のIDを指定することで、どちらのスタックから消費するかを明示することができます。 スタック固有のIDは省略可能で、省略した場合は最も少ないスタックから優先して使用されます。

実装例

アイテムを入手

アイテムの入手はゲームエンジン用の SDK では処理できません。

アイテムを消費

このAPIでアイテムの消費処理を行うことは推奨していません。

GS2-Exchange / GS2-Showcase / GS2-Quest といったサービスを通してアイテムの消費を行う代わりに 何らかの処理を実行することを推奨します。

    var result = await gs2.Inventory.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    ).Inventory(
        inventoryName: "inventory-0001"
    ).ItemSet(
        itemName: "item-0001",
        itemSetName: null
    ).ConsumeAsync(
        consumeCount: 1L
    );
    const auto Future = Gs2->Inventory->Namespace(
        "namespace-0001" // namespaceName
    )->Me(
        AccessToken
    )->Inventory(
        "inventory-0001" // inventoryName
    )->ItemSet(
        "item-0001", // itemName
        nullptr // itemSetName
    )->Consume(
        1L
    );
    Future->StartSynchronousTask();
    if (!TestFalse(WHAT, Future->GetTask().IsError())) return false;

インベントリの情報を取得

    var item = await gs2.Inventory.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    ).Inventory(
        inventoryName: "inventory-0001"
    ).ModelAsync();
    const auto item = Gs2->Inventory->Namespace(
        "namespace-0001" // namespaceName
    )->Me(
        AccessToken
    )->Inventory(
        "inventory-0001" // inventoryName
    )->Model();

インベントリ内のアイテム一覧を取得

    var items = await gs2.Inventory.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    ).Inventory(
        inventoryName: "item"
    ).ItemSetsAsync(
    ).ToListAsync();
    const auto It = Gs2->Inventory->Namespace(
        "namespace-0001" // namespaceName
    )->Me(
        AccessToken
    )->Inventory(
        "item" // inventoryName
    )->ItemSets(
    );
    for (auto Item : *It)
    {

    }

インベントリの容量を拡大

インベントリの容量を拡大はゲームエンジン用の SDK では処理できません。

所持証明署名の取得

GS2 内の他のマイクロサービスと連携する際に、本当に GS2-Inventory でアイテムを所有していることを保証したデータを求められることがあります。

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

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

    var result = await gs2.Inventory.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    ).Inventory(
        inventoryName: "inventory-0001"
    ).ItemSet(
        itemName: "item-0001",
        itemSetName: "item-set-0001"
    ).GetItemWithSignatureAsync(
        keyId: "grn:gs2:{region}:{yourOwnerId}:key:namespace-0001:key:key-0001"
    );
    var item = await result.ModelAsync();
    var body = result.Body;
    var signature = result.Signature;
    const auto Future = Gs2->Inventory->Namespace(
        "namespace-0001" // namespaceName
    )->Me(
        AccessToken
    )->Inventory(
        "inventory-0001" // inventoryName
    )->ItemSet(
        "item-0001", // itemName
        "item-set-0001" // itemSetName
    )->GetItemWithSignature(
        "key-0001"
    );
    Future->StartSynchronousTask();
    if (!TestFalse(WHAT, Future->GetTask().IsError())) return false;

    // obtain changed values / result values
    const auto Future2 = Future->GetTask().Result()->Model();
    Future2->StartSynchronousTask();
    if (!TestFalse(WHAT, Future2->GetTask().IsError())) return false;
    const auto Result = Future2->GetTask().Result();
    const auto Body = Result->Body;
    const auto Signature = Result->Signature;

詳細なリファレンス