跳轉到主要內容

玩家物品欄

需求

若要使用玩家物品欄,您必須為您的遊戲定義目錄。如需詳細資訊,請閱讀我們的目錄教學課程。
您也可以選擇為目錄定義商店。
目錄是遊戲中所有可用物品的清單,而商店則是目錄中物品的子集,可選擇設定獨特的定價。 每個目錄可以定義多個商店,讓您可以根據使用者區段或其他因素,向玩家呈現不同的物品集。 透過 Game Manager 或我們的系統管理 SetCatalogItems 或 UpdateCatalogItems API 呼叫定義目錄後,您就可以在用戶端和伺服器上使用各種物品欄 API 呼叫。

API 概觀

所有物品欄 API 呼叫的設計都是以伺服器為權威且安全的。正確使用時,客戶將無法作弊,或取得他們未賺取的物品。 用戶端: 伺服器: 下方所示的範例說明呼叫這些 API 方法的程式碼區塊,並設定玩家物品欄的基本使用案例。
供您參考,這些範例來自 Unicorn Battle,這是我們為了示範 PlayFab 功能而建置的範例遊戲。
下方使用的 AU 虛擬貨幣是 Gold,這是透過與怪物戰鬥賺取的免費貨幣 (請參閱我們的貨幣教學課程)。 在開始之前,我們將定義一些公用程式函式,這些函式將在本指南的大多數範例中使用和重複使用。

僅限用戶端的範例:購買並消耗生命藥水

用戶端 API 呼叫順序:PurchaseItem、GetUserInventory、ConsumeItem 首先,我們必須在目錄中定義物品。 PlayFab - Economy - 編輯目錄物品 以下是生命藥水的 CatalogItem 需求。
  • PurchaseItem 需要正的物品價格 (5 AU)。
  • ConsumeItem 需要物品為 Consumable,且具有正的物品計數 (3)。
  • 進行購買的玩家必須在其虛擬貨幣餘額中有五個 AU 可用。
下方提供每個呼叫的程式碼。

範例:玩家獲得並開啟容器

API 呼叫順序: 首先,我們必須從目錄中定義的容器開始。在此範例中,我們為容器選取了 CrystalContainer。 此範例也示範使用鑰匙開啟容器——鑰匙是選用物品,也必須位於玩家物品欄中,UnlockContainerInstance 呼叫才能成功。 PlayFab - Economy - 編輯目錄容器 在此範例中,CrystalContainer 的 CatalogItem 需求包括:
  • CrystalContainer 必須定義為 Container。
  • Container 可以選擇性地定義 Key Item,之後就需要它才能解鎖 Container——在此案例中為 CrystalKey。
  • 強烈建議您的 Container 和任何 Key 都設為 Consumable,並具有正的使用次數,讓它們在使用後從玩家物品欄中移除。

伺服器程式碼

用戶端程式碼

消耗鑰匙和容器

在上一個範例中,建議鑰匙和/或容器為可消耗,不過這只是建議。 但如果容器及其鑰匙 (如果有) 不可消耗,容器就可以無限次重新開啟,每次都會將其內容授與玩家。 由於玩家物品欄容量並非無限,強烈不建議使用此模式。解鎖可消耗容器時,容器和所使用的可消耗鑰匙都會自動減少其使用次數,當使用次數達到零時,就會從玩家物品欄中移除。

可行的選項

可消耗容器,無鑰匙:最基本的模式,容器在開啟時被消耗,且沒有鑰匙。 可消耗容器、可消耗鑰匙:簡單的鎖定容器案例,允許玩家使用鑰匙開啟容器。兩者都會被消耗,玩家只能使用仍有剩餘使用次數的鑰匙開啟仍有剩餘使用次數的容器。 耐久容器、可消耗鑰匙:這允許玩家在每次找到鑰匙時開啟容器。鑰匙會被消耗,且只有在鑰匙仍有剩餘使用次數時才能開啟容器。 可消耗容器、耐久鑰匙:這允許玩家保留一把可以開啟所有以其作為鑰匙物品之容器的鑰匙。容器會被消耗,但玩家保留稍後使用鑰匙開啟容器的能力。

範例:向玩家收購物品欄物品

由於收購流程因遊戲而異,因此沒有向玩家收購物品欄物品的內建 API。不過,您可以使用現有的 API 方法打造您自己的 SellItem 體驗:
  • PlayFab 伺服器 API RevokeInventoryItem** 可讓您移除物品欄物品。
  • PlayFab 伺服器 API AddUserVirtualCurrency** 可以退還適當數量的虛擬貨幣。目前無法透過 PlayFab API 方法退還真實貨幣。
物品和虛擬貨幣之間有密切的關係。如需詳細資訊,請參閱我們的貨幣教學課程。
下列 CloudScript 函式將上述兩個伺服器呼叫合併為單一用戶端可存取的呼叫。

最佳做法

  • 在進行任何變更之前,請務必確認所有用戶端輸入資訊都是有效的。
  • CloudScript 並非不可部分完成,因此呼叫順序很重要:AddUserVirtualCurrency 可能成功,而 RevokeInventoryItem 可能失敗。
一般而言,在此程序中給予玩家一些他們未賺取的東西,會比在沒有補償的情況下拿走某些東西更好。
接著就可以從用戶端存取此 CloudScript 函式。
最後修改於 2026年10月8日