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 | Default | 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 | Default | 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 | Default | 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 | Default | 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 | Default | 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 | Default | 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 | Default | 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)
{
}