GS2-Inventory SDK for Game Engine API リファレンス
モデル
EzInventoryModel
インベントリモデル
インベントリはゲームプレイヤーが所有しているアイテムを格納する鞄のようなものです。 インベントリには容量が設定でき、容量を超えては所有できません。
インベントリの容量は拡張することができます。 スタンプシートの報酬に設定ができますので、スタンプシートを使用して報酬を付与できる手段であれば、拡張の方法は問いません。
型 | 必須 | デフォルト | 値の制限 | 説明 | |
---|---|---|---|---|---|
name | string | ✓ | ~ 128文字 | インベントリモデル名 | |
metadata | string | ~ 128文字 | メタデータ | ||
initialCapacity | int | ✓ | ~ 2147483646 | 初期サイズ | |
maxCapacity | int | ✓ | ~ 2147483646 | 最大サイズ |
EzItemModel
アイテムモデル
アイテムは ポーション×99
のようにインベントリの1容量に対して複数所有できます。
1容量で複数所有している状態を アイテムをスタック
する。と呼び、アイテムごとにスタックできる最大数量を指定できます。
スタックできる最大数量に達したとき、新しくインベントリの容量を確保して所有することができるか、入手することが出来なくなるかをアイテムごとに設定できます。
型 | 必須 | デフォルト | 値の制限 | 説明 | |
---|---|---|---|---|---|
name | string | ✓ | ~ 128文字 | アイテムモデル名 | |
metadata | string | ~ 128文字 | メタデータ | ||
stackingLimit | long | ✓ | 1 ~ 9223372036854775806 | スタック可能な最大数量 | |
allowMultipleStacks | bool | ✓ | スタック可能な最大数量を超えた時複数枠にアイテムを保管することを許すか | ||
sortValue | int | ✓ | ~ 2147483646 | 表示順番 |
EzInventory
インベントリ
インベントリはゲームプレイヤーが所有しているアイテムを格納する鞄のようなものです。 カバンには容量があり、プレイヤーごとに容量を拡張することができます。
型 | 必須 | デフォルト | 値の制限 | 説明 | |
---|---|---|---|---|---|
inventoryId | string | ✓ | ~ 1024文字 | インベントリGRN | |
inventoryName | string | ✓ | ~ 128文字 | インベントリモデル名 | |
currentInventoryCapacityUsage | int | ✓ | 0 | ~ 2147483646 | キャパシティ使用量 |
currentInventoryMaxCapacity | int | ✓ | 1 ~ 2147483646 | 最大キャパシティ |
EzItemSet
アイテムはゲームプレイヤーの所有物です。
型 | 必須 | デフォルト | 値の制限 | 説明 | |
---|---|---|---|---|---|
itemSetId | string | ✓ | ~ 1024文字 | 有効期限ごとのアイテム所持数量GRN | |
name | string | ✓ | UUID | ~ 36文字 | アイテムセットを識別する名前 |
inventoryName | string | ✓ | ~ 128文字 | インベントリモデルの名前 | |
itemName | string | ✓ | ~ 128文字 | アイテムモデルの名前 | |
count | long | ✓ | 1 ~ 9223372036854775806 | 所持数量 | |
sortValue | int | ✓ | ~ 2147483646 | 表示順番 | |
expiresAt | long | ✓ | 0 | 有効期限 |
メソッド
getInventoryModel
インベントリ名を指定してインベントリモデルを取得
Request
型 | 必須 | デフォルト | 値の制限 | 説明 | |
---|---|---|---|---|---|
namespaceName | string | ✓ | ~ 32文字 | ネームスペース名 | |
inventoryName | string | ✓ | ~ 128文字 | インベントリモデル名 |
Result
型 | 説明 | |
---|---|---|
item | EzInventoryModel | インベントリモデル |
実装例
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
インベントリモデルの一覧を取得
Request
型 | 必須 | デフォルト | 値の制限 | 説明 | |
---|---|---|---|---|---|
namespaceName | string | ✓ | ~ 32文字 | ネームスペース名 |
Result
型 | 説明 | |
---|---|---|
items | List<EzInventoryModel> | インベントリモデルのリスト |
実装例
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
インベントリ名とアイテム名を指定してアイテムモデルを取得
Request
型 | 必須 | デフォルト | 値の制限 | 説明 | |
---|---|---|---|---|---|
namespaceName | string | ✓ | ~ 32文字 | ネームスペース名 | |
inventoryName | string | ✓ | ~ 128文字 | インベントリモデル名 | |
itemName | string | ✓ | ~ 128文字 | アイテムモデル名 |
Result
型 | 説明 | |
---|---|---|
item | EzItemModel |
実装例
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
インベントリ名を指定してアイテムモデルの一覧を取得
Request
型 | 必須 | デフォルト | 値の制限 | 説明 | |
---|---|---|---|---|---|
namespaceName | string | ✓ | ~ 32文字 | ネームスペース名 | |
inventoryName | string | ✓ | ~ 128文字 | インベントリモデル名 |
Result
型 | 説明 | |
---|---|---|
items | List<EzItemModel> | アイテムモデルのリスト |
実装例
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
インベントリ名を指定してインベントリの情報を取得
Request
型 | 必須 | デフォルト | 値の制限 | 説明 | |
---|---|---|---|---|---|
namespaceName | string | ✓ | ~ 32文字 | ネームスペース名 | |
inventoryName | string | ✓ | ~ 128文字 | インベントリモデル名 | |
accessToken | string | ✓ | ~ 128文字 | ユーザーID |
Result
型 | 説明 | |
---|---|---|
item | EzInventory | インベントリ |
実装例
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
インベントリの一覧を取得
ゲームプレイヤーに紐付いたインベントリの一覧を取得します。
Request
型 | 必須 | デフォルト | 値の制限 | 説明 | |
---|---|---|---|---|---|
namespaceName | string | ✓ | ~ 32文字 | ネームスペース名 | |
accessToken | string | ✓ | ~ 128文字 | ユーザーID | |
pageToken | string | ~ 1024文字 | データの取得を開始する位置を指定するトークン | ||
limit | int | ✓ | 30 | 1 ~ 1000 | データの取得件数 |
Result
型 | 説明 | |
---|---|---|
items | List<EzInventory> | インベントリのリスト |
nextPageToken | string | リストの続きを取得するためのページトークン |
実装例
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
アイテムを消費
ゲーム内からアイテムを消費したい場合に使用します。
GS2のシステムと連携してアイテムの増減を行う場合はこのAPIを使用することはありません。 なぜなら、商品を購入するためや、クエストに参加するために必要な対価の場合は GS2-Showcase や GS2-Quest 上で対価を設定し、 商品の購入時やクエスト参加時に自動的に対価としてアイテムやその他のリソースが消費されるためです。
そのため、このAPIはGS2を介さない要素のためにアイテムを消費する場合に使用してください。
Request
型 | 必須 | デフォルト | 値の制限 | 説明 | |
---|---|---|---|---|---|
namespaceName | string | ✓ | ~ 32文字 | ネームスペース名 | |
inventoryName | string | ✓ | ~ 128文字 | インベントリモデルの名前 | |
itemName | string | ✓ | ~ 128文字 | アイテムモデルの名前 | |
accessToken | string | ✓ | ~ 128文字 | ユーザーID | |
consumeCount | long | ✓ | 1 ~ 9223372036854775806 | 消費する量 | |
itemSetName | string | ~ 36文字 | アイテムセットを識別する名前 |
Result
型 | 説明 | |
---|---|---|
items | List<EzItemSet> | 消費後の有効期限ごとのアイテム所持数量のリスト |
itemModel | EzItemModel | アイテムモデル |
inventory | EzInventory | インベントリ |
Error
このAPIには特別な例外が定義されています。 GS2-SDK for GameEngine ではゲーム内でハンドリングが必要そうなエラーは一般的な例外から派生した特殊化した例外を用意することでハンドリングしやすくしています。 一般的なエラーの種類や、ハンドリング方法は こちら のドキュメントを参考にしてください。
型 | 基底クラス | 説明 |
---|---|---|
ConflictException | ConflictException | アイテムの操作処理が衝突しました。リトライが必要です |
InsufficientException | BadRequestException | アイテムの所持数量が不足しています |
実装例
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
インベントリ名とアイテム名を指定してアイテムを取得
アイテムは複数のスタックに分割されて応答されることがあります。 また、有効期限の異なるアイテムは、必ず別のスタックになります。
Request
型 | 必須 | デフォルト | 値の制限 | 説明 | |
---|---|---|---|---|---|
namespaceName | string | ✓ | ~ 32文字 | ネームスペース名 | |
inventoryName | string | ✓ | ~ 128文字 | インベントリモデルの名前 | |
itemName | string | ✓ | ~ 128文字 | アイテムモデルの名前 | |
accessToken | string | ✓ | ~ 128文字 | ユーザーID |
Result
型 | 説明 | |
---|---|---|
items | List<EzItemSet> | 有効期限毎のアイテム所持数量リスト |
itemModel | EzItemModel | アイテムモデル |
inventory | EzInventory | インベントリ |
実装例
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
インベントリ名とアイテム名を指定して署名付きアイテムを取得
このAPIによって、APIを呼び出した瞬間に該当アイテムを所有していることを証明することができる
Request
型 | 必須 | デフォルト | 値の制限 | 説明 | |
---|---|---|---|---|---|
namespaceName | string | ✓ | ~ 32文字 | ネームスペース名 | |
inventoryName | string | ✓ | ~ 128文字 | インベントリモデルの名前 | |
itemName | string | ✓ | ~ 128文字 | アイテムモデルの名前 | |
accessToken | string | ✓ | ~ 128文字 | ユーザーID | |
itemSetName | string | ~ 36文字 | アイテムセットを識別する名前 | ||
keyId | string | ✓ | ~ 1024文字 | 暗号鍵GRN |
Result
型 | 説明 | |
---|---|---|
items | List<EzItemSet> | 有効期限毎のアイテム所持数量リスト |
itemModel | EzItemModel | アイテムモデル |
inventory | EzInventory | インベントリ |
body | string | 署名対象のアイテムセット情報 |
signature | string | 署名 |
実装例
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
指定したインベントリ内の所有しているアイテム一覧を取得
Request
型 | 必須 | デフォルト | 値の制限 | 説明 | |
---|---|---|---|---|---|
namespaceName | string | ✓ | ~ 32文字 | ネームスペース名 | |
inventoryName | string | ✓ | ~ 128文字 | インベントリの名前 | |
accessToken | string | ✓ | ~ 128文字 | ユーザーID | |
pageToken | string | ~ 1024文字 | データの取得を開始する位置を指定するトークン | ||
limit | int | ✓ | 30 | 1 ~ 1000 | データの取得件数 |
Result
型 | 説明 | |
---|---|---|
items | List<EzItemSet> | 有効期限ごとのアイテム所持数量のリスト |
nextPageToken | string | リストの続きを取得するためのページトークン |
実装例
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)
{
}