Skip to main content

プレイヤーインベントリ

要件

プレイヤーインベントリを使用するには、タイトルにカタログを定義しておく必要があります。詳しくは Catalogs チュートリアルをご覧ください。
必要に応じて、カタログにストアを定義することもできます。
カタログはゲーム内で利用可能なすべてのアイテムのリストであるのに対し、ストアはカタログの中から独自の価格を設定できるアイテムのサブセットです。 1 つのカタログに対して複数のストアを定義できるため、ユーザーセグメンテーションやその他の要因に基づいて、プレイヤーに提示するアイテムセットを使い分けることができます。 Game Manager を使用するか、管理者向け API の SetCatalogItems または UpdateCatalogItems 呼び出しによってカタログを定義すると、クライアントおよびサーバーからさまざまなインベントリ API 呼び出しを利用できるようになります。

API の概要

すべてのインベントリ API 呼び出しは サーバー権威型 かつ安全になるよう設計されています。適切に使用することで、プレイヤーがチートしたり、獲得していないアイテムを取得したりできないようになっています。 クライアント: サーバー: 以下の例は、これらの API メソッドを呼び出すコードブロックを示し、プレイヤーインベントリの基本的なユースケースをセットアップします。
参考までに、これらの例は PlayFab の機能をデモするために作られたゲーム Unicorn Battle から引用しています。
以下で使用する仮想通貨 AUGold で、モンスターと戦うことで獲得できる無料の通貨です (Currencies チュートリアルを参照)。 始める前に、本ガイドの多くの例で繰り返し使用するユーティリティ関数をいくつか定義しておきます。

クライアントのみの例: ヘルスポーションの購入と消費

クライアント API の呼び出し順: PurchaseItemGetUserInventoryConsumeItem まず、カタログにアイテムを定義することから始めます。 Health PotionCatalogItem の要件は次のとおりです。
  • PurchaseItem にはアイテムの正の価格 (5 AU) が必要です。
  • ConsumeItem には、アイテムが Consumable であること、および正の使用回数 (3) が必要です。
  • 購入するプレイヤーは、仮想通貨残高に 5 AU 以上を保有している必要があります。
各呼び出しのコードを以下に示します。

例: プレイヤーがコンテナーを付与され、それを開ける

API の呼び出し順: まず、カタログでコンテナーを定義する必要があります。この例では、コンテナーとして CrystalContainer を選択します。 この例では、鍵を使ってコンテナーを開ける処理も示します。鍵は 任意 のアイテムで、UnlockContainerInstance の呼び出しを成功させるためには、これもプレイヤーインベントリに含まれている必要があります。 この例における CrystalContainerCatalogItem 要件は次のとおりです。
  • CrystalContainerContainer として定義されていること。
  • Container には任意で Key Item を定義できます。これは Container をアンロックするために必要となり、この例では CrystalKey です。
  • Container および Key両方とも 、正の使用回数を持つ Consumable にすることを強く推奨します。これにより、使用後にプレイヤーインベントリから削除されます。

サーバーコード

クライアントコード

鍵とコンテナーの消費

前述の例では、鍵やコンテナーを consumable にすることが提案されていますが、これはあくまで推奨事項です。 しかし、コンテナーとその鍵 (存在する場合) の両方が 非 consumable であると、コンテナーを 無限に 開き直すことができ、そのたびに中身がプレイヤーに付与されてしまいます。 プレイヤーインベントリの容量は 無限ではない ため、このパターンは強く非推奨とされます。consumable なコンテナーがアンロックされると、コンテナーと使用された consumable の鍵の両方の使用回数が自動的に 減少 し、使用回数がゼロになるとプレイヤーインベントリから削除されます。

実用的な選択肢

Consumable ContainerKey なし: 最も基本的なパターンで、開けるとコンテナーが消費され、鍵は存在しません。 Consumable Container、consumable Key: シンプルな鍵付きコンテナーのケースで、プレイヤーは鍵でコンテナーを開けることができます。 両方 が消費され、プレイヤーは残り使用回数のあるコンテナーを、残り使用回数のある鍵でしか開けられません。 Durable Container、consumable Key: プレイヤーが鍵を見つけるたびにコンテナーを開けられるパターンです。鍵は消費され、鍵に残り使用回数がある間だけコンテナーが開かれます。 Consumable Container、durable Key: プレイヤーが、そのキーアイテムに対応する すべての コンテナーを開けられる鍵を持ち続けられるパターンです。コンテナーは消費されますが、プレイヤーはその後もその鍵でコンテナーを開ける能力を維持します。

例: プレイヤーからインベントリアイテムを買い取る

インベントリアイテムをプレイヤーから買い戻すための組み込み API はありません。このプロセスはゲーム固有だからです。ただし、 既存の API メソッドを使って独自の SellItem 体験を構築できます。
  • PlayFab Server API RevokeInventoryItem** を使用すると、インベントリアイテムを削除できます。
  • PlayFab Server API AddUserVirtualCurrency** で、適切な量の仮想通貨を返却できます。現時点で PlayFab API メソッドから実際の通貨を返すことはできません。
アイテムと仮想通貨は密接な関係にあります。詳しくは Currencies チュートリアルをご覧ください。
以下の CloudScript 関数は、これら 2 つのサーバー呼び出しを 1 つのクライアントからアクセス可能な呼び出しにまとめています。

ベストプラクティス

  • 変更を行う前に、すべてのクライアント入力情報が 有効 であることを必ず検証してください。
  • CloudScript はアトミックではないため、呼び出し順序が重要です。 AddUserVirtualCurrency が成功し、 RevokeInventoryItem が失敗する可能性があります。
一般的に、このプロセスにおいては、補償なしに何かを取り上げるよりも、プレイヤーが 獲得していないもの を与えるほうが望ましいです。
この CloudScript 関数は、クライアントから呼び出すことができます。
最終更新日 2026年8月25日