Steamworks 文獻庫
Steam 物品庫物品動態屬性
Steam 物品庫服務的新功能具有在任何物品執行個體上儲存任意字串、整數、布林值,或浮動屬性的能力。

這些屬性類似於個別物品標籤。 然而,與不可變的個別物品標籤不同的是,這些屬性是動態的,可透過安全的 Web API 呼叫或 Steamworks API 修改。

另外一項不同之處在於,物品一經交易,動態物品屬性便會被清除。 目前,查看使用者的 Steam 物品庫或 Steam 社群市集中的物品時,無法檢視其動態物品屬性。

取得物品屬性


動態物品會自動與其他的物品屬性傳送至 Steam 用戶端,並可以使用屬性名稱 dynamic_props 呼叫 ISteamInventory::GetResultItemProperty 取得。 該物品所有的動態屬性將以字串形式的 JSON 填入所提供的緩衝區。 如何恰當解析此字串,則取決於您的應用程式。

針對任何以 JSON 形式傳回物品的 Web API 呼叫,dynamic_props 索引碼將指向裝載動態物品屬性的完整 JSON 物件。

修改物品屬性


您可從您其中一台安全的伺服器,使用 IInventoryService/ModifyItems Web API 和加密的發行商金鑰修改物品。

或者,也可以從 Steam 用戶端,透過 Steamworks API 和呼叫 ISteamInventory::StartUpdatePropertiesISteamInventory::RemovePropertyISteamInventory::SetProperty,和ISteamInventory::SubmitUpdateProperties 來修改物品屬性。 然而,您必須先在合作夥伴網站的 Steam 物品庫服務設定頁面將可以從用戶端設定的屬性加入白名單。 我們建議僅將可以接受未信任的用戶端設定(也就是說使用者可假造訊息,將值設定為任何他們希望的值)的屬性加入白名單。

目前每次呼叫最多可為使用者修改 100 項物品。 此呼叫具有以使用者劃分的速度限制,所以最好累積一定數量的修改,於合適的時間再為遊戲發送。 現階段每項物品的 JSON 大小上限為 1024 個位元組。

施行限制

如前所述,您可將部分允許於用戶端設定的屬性加入白名單。 但您也可對目標物品的任何 tag_category 值限制能與其配對的特定 tag_category:tag_value,以進一步限制可以設定哪些屬性。 將這些標籤限制與用戶端 API 搭配使用,便可讓用戶端只能在合理情況下設定屬性(意即,帽子不能紀錄擊殺數,但火箭發射器可以)。 必要的標籤可能會存在於物品或其關聯的物品定義上。

範例


假設您希望記錄使用者使用火箭發射器的次數, 那麼,可以達到的辦法有很多種。但無論採取何種方法,如同先前所提到的,由於修改物品屬性的呼叫有速度限制,因此最好先累積一定數量的屬性修改。

WebAPI

在您安全的遊戲伺服器上,您可將統計資料累積至最後一輪遊戲,或其他合適時機,並使用加密的發行商金鑰,將結果 POST 至 IInventoryService/ModifyItems Web API。

POST 呼叫的表單資料範例:
appid: 480 key: "0123456789abcdeffedcba9876543210" input_json:{ "steamid" : "1234", "timestamp" : 1513274037, "updates" : [] }

Steamworks API

如果您希望使用 Steamworks API 修改物品屬性(同樣地,帶有安全隱憂),則須將它們列入您的應用程式的白名單中。

然後,和上方的範例一樣,一旦遊戲回合結束或到了適當的時間,您便可開始一項更新、設定屬性,然後將更新提交至 Steam。

SteamInventoryUpdateHandle_t updateHandle = SteamInventory()->StartUpdateProperties(); SteamInventory()->SetProperty( updateHandle, nItemID, "num_times_fired", nNumTimesFired ); SteamInventoryResult_t resultUpdate; SteamInventory()->SubmitUpdateProperties( updateHandle, &resultUpdate );

然後便可在 SteamInventoryResultReady_t 的回呼處理常式中,取得更新這些物品屬性的呼叫結果。

在地化

動態屬性通常不會在使用者背包的 Web 檢視中彩現。 然而,若將動態屬性名稱設為可替換的標記,便可以在物品說明中使用其值。

以前面的範例來說,物品定義的說明字串可以是:
火箭發射器發射過 %num_times_fired% 次。

在 Web 上的說明就會是:
火箭發射器發射過 100 次。

沒有相應動態屬性的替換標記(也就是符合「%([a-zA-Z0-9.-_]+)%」正則表示式的字串)將被自動刪除。 若在 Steam 物品庫服務頁面下的「物品動態屬性」區塊設置動態屬性,並設定「類型」欄位,那麼整數和浮點數將以 0 取代,布林屬性則以「false」取代。