API Reference of GS2-Inventory SDK for Game Engine

Model

EzInventoryModel

Inventory Model

Inventory is like a bag that stores items owned by game players. Inventory can have a set capacity and cannot be owned beyond its capacity.

The inventory capacity can be expanded. It can be set to reward stamp sheets, so any method of expansion is acceptable as long as the stamp sheets can be used to grant rewards.

	Type	Require	Limitation	Description
name	string	✓	~ 128 chars	Inventory Model Name
metadata	string		~ 128 chars	metadata
initialCapacity	int	✓	~ 2147483646	Initial Capacity
maxCapacity	int	✓	~ 2147483646	Maximum Capacity

EzItemModel

Item Model

Multiple items can be owned for one capacity of inventory, such as potions x 99. Multiple items owned in one capacity are stacked items. The maximum number of items that can be stacked can be specified for each item.

When the maximum stackable quantity is reached, you can set for each item whether you can reserve a new inventory capacity and own it, or whether it will no longer be available.

	Type	Require	Limitation	Description
name	string	✓	~ 128 chars	Item Model Name
metadata	string		~ 128 chars	metadata
stackingLimit	long	✓	1 ~ 9223372036854775805	Maximum stackable quantity
allowMultipleStacks	bool	✓		Allow items to be stored in multiple slots when the maximum stackable quantity is exceeded?
sortValue	int	✓	~ 2147483646	Display order

EzInventory

Inventory

Inventory is like a bag that stores items owned by game players. The bag has a capacity, and the capacity can be expanded by each player.

	Type	Require	Default	Limitation	Description
inventoryId	string	✓		~ 1024 chars	Inventory GRN
inventoryName	string	✓		~ 128 chars	Inventory Model Name
currentInventoryCapacityUsage	int	✓	0	~ 2147483646	Capacity usage
currentInventoryMaxCapacity	int	✓		1 ~ 2147483646	Maximum capacity

EzItemSet

Items are the property of the game player

	Type	Require	Default	Limitation	Description
itemSetId	string	✓		~ 1024 chars	Quantity of items held per expiration date GRN
name	string	✓	UUID	~ 36 chars	Name identifying the item set
inventoryName	string	✓		~ 128 chars	Inventory Model Name
itemName	string	✓		~ 128 chars	Item Model Name
count	long	✓		1 ~ 9223372036854775805	Quantity in possession
sortValue	int	✓		~ 2147483646	Display order
expiresAt	long	✓	0		Effective date

Methods

getInventoryModel

Get inventory model by specifying inventory name

Request

	Type	Require	Default	Limitation	Description
namespaceName	string	✓		~ 32 chars	Namespace name
inventoryName	string	✓		~ 128 chars	Inventory Model Name

Result

	Type	Description
item	EzInventoryModel	Inventory Model

Implementation Example

    var domain = gs2.Inventory.Namespace(
        namespaceName: "namespace-0001"
    ).InventoryModel(
        inventoryName: "item"
    );
    var item = await domain.ModelAsync();

    var domain = gs2.Inventory.Namespace(
        namespaceName: "namespace-0001"
    ).InventoryModel(
        inventoryName: "item"
    );
    var future = domain.Model();
    yield return future;
    var item = future.Result;

    const auto Domain = Gs2->Inventory->Namespace(
        "namespace-0001" // namespaceName
    )->InventoryModel(
        "item" // inventoryName
    );
    const auto item = Domain.Model();

listInventoryModels

Get list of inventory models

Request

	Type	Require	Default	Limitation	Description
namespaceName	string	✓		~ 32 chars	Namespace name

Result

	Type	Description
items	List<EzInventoryModel>	List of Inventory Models

Implementation Example

    var domain = gs2.Inventory.Namespace(
        namespaceName: "namespace-0001"
    );
    var items = await domain.InventoryModelsAsync(
    ).ToListAsync();

    var domain = gs2.Inventory.Namespace(
        namespaceName: "namespace-0001"
    );
    var it = domain.InventoryModels(
    );
    List<EzInventoryModel> items = new List<EzInventoryModel>();
    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;
        }
    }

    const auto Domain = Gs2->Inventory->Namespace(
        "namespace-0001" // namespaceName
    );
    const auto It = Domain->InventoryModels(
    );
    for (auto Item : *It)
    {

    }

getItemModel

Get item model by specifying inventory name and item name

Request

	Type	Require	Limitation	Description
namespaceName	string	✓	~ 32 chars	Namespace name
inventoryName	string	✓	~ 128 chars	Inventory Model Name
itemName	string	✓	~ 128 chars	Item Model Name

Result

	Type	Description
item	EzItemModel

Implementation Example

    var domain = gs2.Inventory.Namespace(
        namespaceName: "namespace-0001"
    ).InventoryModel(
        inventoryName: "item"
    ).ItemModel(
        itemName: "item-master-0001"
    );
    var item = await domain.ModelAsync();

    var domain = gs2.Inventory.Namespace(
        namespaceName: "namespace-0001"
    ).InventoryModel(
        inventoryName: "item"
    ).ItemModel(
        itemName: "item-master-0001"
    );
    var future = domain.Model();
    yield return future;
    var item = future.Result;

    const auto Domain = Gs2->Inventory->Namespace(
        "namespace-0001" // namespaceName
    )->InventoryModel(
        "item" // inventoryName
    )->ItemModel(
        "item-master-0001" // itemName
    );
    const auto item = Domain.Model();

listItemModels

Get list of item models by specifying the inventory name

Request

	Type	Require	Default	Limitation	Description
namespaceName	string	✓		~ 32 chars	Namespace name
inventoryName	string	✓		~ 128 chars	Inventory Model Name

Result

	Type	Description
items	List<EzItemModel>	List of Item Model

Implementation Example

    var domain = gs2.Inventory.Namespace(
        namespaceName: "namespace-0001"
    ).InventoryModel(
        inventoryName: "item"
    );
    var items = await domain.ItemModelsAsync(
    ).ToListAsync();

    var domain = gs2.Inventory.Namespace(
        namespaceName: "namespace-0001"
    ).InventoryModel(
        inventoryName: "item"
    );
    var it = domain.ItemModels(
    );
    List<EzItemModel> items = new List<EzItemModel>();
    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;
        }
    }

    const auto Domain = Gs2->Inventory->Namespace(
        "namespace-0001" // namespaceName
    )->InventoryModel(
        "item" // inventoryName
    );
    const auto It = Domain->ItemModels(
    );
    for (auto Item : *It)
    {

    }

getInventory

Get inventory information by specifying the inventory name

Request

	Type	Require	Limitation	Description
namespaceName	string	✓	~ 32 chars	Namespace name
inventoryName	string	✓	~ 128 chars	Inventory Model Name
accessToken	string	✓	~ 128 chars	User Id

Result

	Type	Description
item	EzInventory	Inventory

Implementation Example

    var domain = gs2.Inventory.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    ).Inventory(
        inventoryName: "inventory-0001"
    );
    var item = await domain.ModelAsync();

    var domain = gs2.Inventory.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    ).Inventory(
        inventoryName: "inventory-0001"
    );
    var future = domain.Model();
    yield return future;
    var item = future.Result;

    const auto Domain = Gs2->Inventory->Namespace(
        "namespace-0001" // namespaceName
    )->Me(
        AccessToken
    )->Inventory(
        "inventory-0001" // inventoryName
    );
    const auto item = Domain.Model();

listInventories

Get Inventory List

Retrieves list of the inventory associated with a game player.

Request

	Type	Require	Default	Limitation	Description
namespaceName	string	✓		~ 32 chars	Namespace name
accessToken	string	✓		~ 128 chars	User Id
pageToken	string			~ 1024 chars	Token specifying the position from which to start acquiring data
limit	int	✓	30	1 ~ 1000	Number of data acquired

Result

	Type	Description
items	List<EzInventory>	List of Inventories
nextPageToken	string	Page token to retrieve the rest of the listing

Implementation Example

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

    var domain = gs2.Inventory.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    );
    var it = domain.Inventories(
    );
    List<EzInventory> items = new List<EzInventory>();
    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;
        }
    }

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

    }

consume

Consume Item

Use this if you wish to consume items from within the game.

This API is not used to increase or decrease items in conjunction with the GS2 system. This is because if the consideration is needed to purchase an item or to participate in a quest, you can set the consideration on GS2-Showcase or GS2-Quest, and then use the This is because items and other resources are automatically consumed as compensation when purchasing products or participating in quests.

Therefore, this API should be used when items are consumed for elements that do not involve GS2.

Request

	Type	Require	Limitation	Description
namespaceName	string	✓	~ 32 chars	Namespace name
inventoryName	string	✓	~ 128 chars	Inventory Model Name
itemName	string	✓	~ 128 chars	Item Model Name
accessToken	string	✓	~ 128 chars	User Id
consumeCount	long	✓	1 ~ 9223372036854775805	Amount to consume
itemSetName	string		~ 36 chars	Name identifying the item set

Result

	Type	Description
items	List<EzItemSet>	List of item possession quantities per post-consumption expiration date
itemModel	EzItemModel	Item Model
inventory	EzInventory	Inventory

Error

Special exceptions are defined in this API. GS2-SDK for GameEngine provides specialized exceptions derived from general exceptions to facilitate handling of errors that may need to be handled in games. Please refer to the documentation here for more information on common error types and handling methods.

Type	Base Type	Description
ConflictException	ConflictException	Item manipulation process conflicted. Retry required.
InsufficientException	BadRequestException	Insufficient quantity of items in your possession.

Implementation Example

try {
    var domain = gs2.Inventory.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    ).Inventory(
        inventoryName: "inventory-0001"
    ).ItemSet(
        itemName: "item-0001",
        itemSetName: null
    );
    var result = await domain.ConsumeAsync(
        consumeCount: 1L
    );
    var item = await result.ModelAsync();
} catch(Gs2.Gs2Inventory.Exception.Conflict e) {
    // Item manipulation process conflicted. Retry required.
} catch(Gs2.Gs2Inventory.Exception.Insufficient e) {
    // Insufficient quantity of items in your possession.
}

    var domain = gs2.Inventory.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    ).Inventory(
        inventoryName: "inventory-0001"
    ).ItemSet(
        itemName: "item-0001",
        itemSetName: null
    );
    var future = domain.Consume(
        consumeCount: 1L
    );
    yield return future;
    if (future.Error != null)
    {
        if (future.Error is Gs2.Gs2Inventory.Exception.ConflictException)
        {
            // Item manipulation process conflicted. Retry required.
        }
        if (future.Error is Gs2.Gs2Inventory.Exception.InsufficientException)
        {
            // Insufficient quantity of items in your possession.
        }
        onError.Invoke(future.Error, null);
        yield break;
    }
    var future2 = future.Result.Model();
    yield return future2;
    if (future2.Error != null)
    {
        onError.Invoke(future2.Error, null);
        yield break;
    }
    var result = future2.Result;

    const auto Domain = Gs2->Inventory->Namespace(
        "namespace-0001" // namespaceName
    )->Me(
        AccessToken
    )->Inventory(
        "inventory-0001" // inventoryName
    )->ItemSet(
        "item-0001", // itemName
        nullptr // itemSetName
    );
    const auto Future = Domain->Consume(
        1L
    );
    Future->StartSynchronousTask();
    if (Future->GetTask().IsError())
    {
        if (Gs2::Inventory::Error::FConflictError::TypeString == Task->GetTask().Error()->Type())
        {
            // Item manipulation process conflicted. Retry required.
        }
        if (Gs2::Inventory::Error::FInsufficientError::TypeString == Task->GetTask().Error()->Type())
        {
            // Insufficient quantity of items in your possession.
        }
        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();

getItem

Retrieve items by specifying the inventory name and item name

Items may be divided into multiple stacks and responded to. Also, items with different expiration dates will always be in different stacks.

Request

	Type	Require	Limitation	Description
namespaceName	string	✓	~ 32 chars	Namespace name
inventoryName	string	✓	~ 128 chars	Inventory Model Name
itemName	string	✓	~ 128 chars	Item Model Name
accessToken	string	✓	~ 128 chars	User Id

Result

	Type	Description
items	List<EzItemSet>	List of Quantity of items held per expiration date
itemModel	EzItemModel	Item Model
inventory	EzInventory	inventory

Implementation Example

    var domain = gs2.Inventory.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    ).Inventory(
        inventoryName: "item"
    ).ItemSet(
        itemName: "item-0001",
        itemSetName: "itemSet-0001"
    );
    var item = await domain.ModelAsync();

    var domain = gs2.Inventory.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    ).Inventory(
        inventoryName: "item"
    ).ItemSet(
        itemName: "item-0001",
        itemSetName: "itemSet-0001"
    );
    var future = domain.Model();
    yield return future;
    var item = future.Result;

    const auto Domain = Gs2->Inventory->Namespace(
        "namespace-0001" // namespaceName
    )->Me(
        AccessToken
    )->Inventory(
        "item" // inventoryName
    )->ItemSet(
        "item-0001", // itemName
        "itemSet-0001" // itemSetName
    );
    const auto item = Domain.Model();

getItemWithSignature

Retrieve signed items by specifying the inventory name and item name

This API allows you to prove that you own the item at the moment you call the API

Request

	Type	Require	Limitation	Description
namespaceName	string	✓	~ 32 chars	Namespace name
inventoryName	string	✓	~ 128 chars	Inventory Model Name
itemName	string	✓	~ 128 chars	Item Model Name
accessToken	string	✓	~ 128 chars	User Id
itemSetName	string		~ 36 chars	Name identifying the item set
keyId	string	✓	~ 1024 chars	encryption key GRN

Result

	Type	Description
items	List<EzItemSet>	List of Quantity of items held per expiration date
itemModel	EzItemModel	Item Model
inventory	EzInventory	Inventory
body	string	Item Set Information for Signature Subject
signature	string	Signature

Implementation Example

    var domain = gs2.Inventory.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    ).Inventory(
        inventoryName: "inventory-0001"
    ).ItemSet(
        itemName: "item-0001",
        itemSetName: null
    );
    var result = await domain.GetItemWithSignatureAsync(
        keyId: "key-0001"
    );
    var item = await result.ModelAsync();
    var body = result.Body;
    var signature = result.Signature;

    var domain = gs2.Inventory.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    ).Inventory(
        inventoryName: "inventory-0001"
    ).ItemSet(
        itemName: "item-0001",
        itemSetName: null
    );
    var future = domain.GetItemWithSignature(
        keyId: "key-0001"
    );
    yield return future;
    if (future.Error != null)
    {
        onError.Invoke(future.Error, null);
        yield break;
    }
    var future2 = future.Result.Model();
    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;

    const auto Domain = Gs2->Inventory->Namespace(
        "namespace-0001" // namespaceName
    )->Me(
        AccessToken
    )->Inventory(
        "inventory-0001" // inventoryName
    )->ItemSet(
        "item-0001", // itemName
        nullptr // itemSetName
    );
    const auto Future = Domain->GetItemWithSignature(
        "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 (!TestFalse(WHAT, Future2->GetTask().IsError())) return false;
    const auto Result = Future2->GetTask().Result();
    const auto Body = Result->Body;
    const auto Signature = Result->Signature;

listItems

Retrieves list of items owned in the specified inventory

Request

	Type	Require	Default	Limitation	Description
namespaceName	string	✓		~ 32 chars	Namespace name
inventoryName	string	✓		~ 128 chars	Inventory Model Name
accessToken	string	✓		~ 128 chars	User Id
pageToken	string			~ 1024 chars	Token specifying the position from which to start acquiring data
limit	int	✓	30	1 ~ 1000	Number of data acquired

Result

	Type	Description
items	List<EzItemSet>	List of Quantity of items held per expiration date
nextPageToken	string	Page token to retrieve the rest of the listing

Implementation Example

    var domain = gs2.Inventory.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    ).Inventory(
        inventoryName: "item"
    );
    var items = await domain.ItemSetsAsync(
    ).ToListAsync();

    var domain = gs2.Inventory.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    ).Inventory(
        inventoryName: "item"
    );
    var it = domain.ItemSets(
    );
    List<EzItemSet> items = new List<EzItemSet>();
    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;
        }
    }

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

    }