GS2-Inventory
Manage information about the items a player owns.
There are three methods for managing items. The first is standard inventory and the second is simple inventory and the third is big inventory.
Standard inventory has the following features
- Limit inventory capacity
- Splitting the same item into multiple stacks of a certain quantity
- Setting an expiration date on items
Simple inventory, on the other hand, does not have the features of standard inventory. Instead, it allows you to process the increase or decrease of multiple items at once. By making good use of simple inventory, the number of API calls can be reduced.
Like simple inventory, big inventory does not have the functionality that standard inventory has. It is not possible to increase or decrease multiple items at once, as is the case with simple inventory. Instead, it is possible to hold more than a 64-bit integer quantity of items.
Standard Inventory
Inventory
An entity corresponding to a player’s bag. A bag can have a configurable capacity and cannot contain more items than its capacity.
Item
Items define the type of possessions. The maximum number of items that can be stacked can be specified for an item.
For example, if there is an item type called “Potion” and the maximum number of items that can be stacked is 99 You can have up to 99 potions in your inventory with an inventory capacity usage of 1.
In addition, the item can have multiple stacks. If an item is set to allow multiple stacks, you can have more than 100 potions in your inventory. For example, if you have 150 potions, two entries will be created: one with 99 potions stacked and one with 51 potions stacked. This takes up 2 inventory slots.
If multiple stacks are disabled, you will not be able to have more than 99 potions, and you will be able to discard any additional potions you acquire.
Item expiration date
Items may have an expiration date. Items with an expiration date are automatically removed from your inventory after the expiration date.
Items with an expiration date create a separate stack for each expiration date, and each stack takes up inventory space. Therefore, if you place items with expiration dates on items that cannot have multiple stacks, they will be discarded except for the first item with an expiration date that you purchased (or the first item without an expiration date that you purchased).
Item Sets
To manage multiple stacks of an item type, there is an entity called an item set that groups the item types together. This entity has a stack-specific ID for each stack, in addition to the ID representing the item type. With this stack-specific ID, it is possible to clearly distinguish stacks of “Potion x 99” from stacks of “Potion x 51”.
When consuming a potion, the stack-specific ID can be used in addition to the item ID to indicate which stack the potion is being consumed from. The stack-specific ID can be omitted, in which case the lowest stack will be used first.
Simple Inventory
Simple Inventory
It is an entity that corresponds to a bag owned by a player. It is an entity that binds multiple simple items and has no specific properties in the simple inventory.
Simple Item
An item defines the type of possession.
Big Inventory
Big Inventory
It is an entity equivalent to a player’s bag. It is an entity that binds multiple big items and has no specific properties in the big inventory.
Big Item
An item defines the type of possession.
Example implementation
Obtaining items
The acquisition of items cannot be handled by the SDK for the game engine.
Consuming items
It is not recommended to use this API to process item consumption.
It is recommended to use GS2-Exchange / GS2-Showcase / GS2-Quest services to perform some kind of processing instead of consuming items.
Standard
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;Simple
var result = await gs2.Inventory.Namespace(
namespaceName: "namespace-0001"
).Me(
gameSession: GameSession
).SimpleInventory(
inventoryName: "inventory-0001"
).Item(
itemName: "item-0001"
).ConsumeAsync(
consumeCount: 1L
); const auto Future = Gs2->Inventory->Namespace(
"namespace-0001" // namespaceName
)->Me(
AccessToken
)->SimpleInventory(
"inventory-0001" // inventoryName
)->Item(
"item-0001" // itemName
)->Consume(
1L
);
Future->StartSynchronousTask();
if (!TestFalse(WHAT, Future->GetTask().IsError())) return false;Big
var result = await gs2.Inventory.Namespace(
namespaceName: "namespace-0001"
).Me(
gameSession: GameSession
).BigInventory(
inventoryName: "inventory-0001"
).Item(
itemName: "item-0001"
).ConsumeAsync(
consumeCount: "1"
); const auto Future = Gs2->Inventory->Namespace(
"namespace-0001" // namespaceName
)->Me(
AccessToken
)->BigInventory(
"inventory-0001" // inventoryName
)->Item(
"item-0001" // itemName
)->Consume(
"1"
);
Future->StartSynchronousTask();
if (!TestFalse(WHAT, Future->GetTask().IsError())) return false;Get inventory information
Standard
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();Simple
Simple Inventory does not have this feature
Get a list of items in inventory
Standard
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)
{
}Simple
var items = await gs2.Inventory.Namespace(
namespaceName: "namespace-0001"
).Me(
gameSession: GameSession
).SimpleInventory(
inventoryName: "item"
).ItemsAsync(
).ToListAsync(); const auto It = Gs2->Inventory->Namespace(
"namespace-0001" // namespaceName
)->Me(
AccessToken
)->SimpleInventory(
"item" // inventoryName
)->Items(
);
for (auto Item : *It)
{
}Big
var items = await gs2.Inventory.Namespace(
namespaceName: "namespace-0001"
).Me(
gameSession: GameSession
).BigInventory(
inventoryName: "item"
).ItemsAsync(
).ToListAsync(); const auto It = Gs2->Inventory->Namespace(
"namespace-0001" // namespaceName
)->Me(
AccessToken
)->BigInventory(
"item" // inventoryName
)->Items(
);
for (auto Item : *It)
{
}Expanding inventory capacity
Expanding inventory capacity cannot be handled by the SDK for game engines.
Obtaining a Possession Certificate Signature
When interfacing with other microservices in GS2, you may be asked for data that guarantees that you really own the item in GS2-Inventory.
For example, let’s say that GS2-Inventory manages character possession state and GS2-Formation manages party formation state. When setting up party members in GS2-Formation, you would make an API request to set up a character named “character-0001,” but GS2-Formation will request that you specify “character-0001” in conjunction with a proof-of-possession signature.
This eliminates the need for GS2-Formation to communicate with GS2-Inventory behind the scenes to determine if the character is really owned.
Standard
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;Simple
var result = await gs2.Inventory.Namespace(
namespaceName: "namespace-0001"
).Me(
gameSession: GameSession
).SimpleInventory(
inventoryName: "inventory-0001"
).Item(
itemName: "item-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
)->SimpleInventory(
"inventory-0001" // inventoryName
)->Item(
"item-0001" // itemName
)->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;Big
Big inventory do not have this feature.