《Steam 游戏平台:开发与商业化》13.1 库存机制

本节接 ISteamInventory 库存机制:ItemDef 定义表、GetAllItems 异步快照、GetResultItems 两段式读取结果集、GetResultStatus 与 DestroyResult 的结果句柄生命周期。lab 用 C++ mock 库存条目、定义表与结果句柄,验证两段式读取、空间不足拒绝与句柄释放后的失效语义。

13.1 库存机制

上一节(12.3)讲了平台事件如何驱动产品决策,这一节进入本卷第三个接口域的前半段:库存。Steam 库存不是「游戏自己存一个 JSON 文件」,而是由 Steam 后端托管的、与账号绑定的物品账本:物品的「种类」由 ItemDef 定义,「每一件」有全局唯一的实例 ID,「一次查询」返回一个可序列化的结果集。这三个基本量决定了接入工程的写法——读取永远异步、结果永远要释放、序列化结果可以拿去证明所有权。

本卷所有接口口径以 Steamworks SDK v1.65(2026-07-23) 为准。本节摘录的签名对照该版本 public/steam/isteaminventory.h。

本章与站内既有内容的分工

  • Steam 发行专题 (操作手册)讲「后台配置库存条目、设置定价」;本节讲「代码里用 ISteamInventory 读库存的接口语义」。
  • 卷一《平台机制与商店》讲机制如何决定设计定价;本节讲 ItemDef、实例 ID、结果集这三个库存基本量的工程语义。
  • 库存的商业模型(限时、稀缺、交易)在 13.3 展开,本节只讲「读」的机制。
  • lab 用纯 C++ mock 库存条目、定义表与结果句柄,不依赖 Steam 客户端运行。

三个基本量:ItemDef、实例与结果集

isteaminventory.h 开头就定义了三个关键类型。**ItemDef(定义)**是「物品种类」,32 位整数,有效范围在 1 到 999999999 之间;**实例 ID(ItemInstanceID)**是「具体的一件」,全局唯一,组合(玩家,具体物品)唯一且不会转移或复用;**结果集句柄(InventoryResult_t)**是一次异步查询的输出容器:

// isteaminventory.h:SteamItemInstanceID_t / SteamItemDef_t / SteamItemDetails_t(SDK v1.65 头文件摘录,已删减)
typedef uint64 SteamItemInstanceID_t;

typedef int32 SteamItemDef_t;

struct SteamItemDetails_t
{
	SteamItemInstanceID_t m_itemId;
	SteamItemDef_t m_iDefinition;
	uint16 m_unQuantity;
	uint16 m_unFlags; // see ESteamItemFlags
};

工程语义上有三个要点:

  1. 「种类」和「实例」是分离的。玩家拥有 3 把相同定义的刀,是 3 个实例 ID;消耗其中 1 把,是某个实例的数量减一(13.3 详讲)。显示层通常按定义聚合,但操作层必须按实例处理。
  2. 定义表是配置驱动的。ItemDef 不是硬编码在代码里,而是通过 Steamworks 后台配置、客户端用 LoadItemDefinitions 拉取并监听 SteamInventoryDefinitionUpdate_t。这让游戏可以在不发布客户端补丁的情况下新增物品种类(头文件注释明确「does not allow for adding new item types without a client patch」是硬编码的缺点)。
  3. SteamItemDetails_t 是结果的最小单位。m_itemId 对应一件具体物品,m_iDefinition 告诉 UI 去查哪条定义,m_unQuantity 表示堆叠数量,m_unFlags 携带 ESteamItemFlags 里的状态位(如 k_ESteamItemNoTrade 不可交易)。

读取库存:异步快照与两段式结果集

库存查询全部是异步的:调用方先拿到一个结果句柄,等 SteamInventoryResultReady_t 回调,再读结果。SDK v1.65 里 GetAllItems 捕获当前库存的完整快照,GetResultItems 把结果拷贝进调用方数组:

// isteaminventory.h:GetAllItems / GetResultItems(SDK v1.65 头文件摘录,已删减)
virtual bool GetAllItems( SteamInventoryResult_t *pResultHandle ) = 0;

virtual bool GetResultItems( SteamInventoryResult_t resultHandle,
							STEAM_OUT_ARRAY_COUNT( punOutItemsArraySize,Output array) SteamItemDetails_t *pOutItemsArray,
							uint32 *punOutItemsArraySize ) = 0;

工程语义:

  1. 先探测长度、再取回数据。GetResultItems 传空数组时返回 true 并把所需件数写进 punOutItemsArraySize;再分配足够数组、把大小传进去取回。缓冲区不足则返回 false。这与云存储 FileRead、加密票据 GetEncryptedAppTicket 的两段式惯例一致。
  2. 结果句柄必须用 DestroyResult 释放。头文件对 GetAllItems 明确要求「You must call DestroyResult on this handle when you are done with it」。句柄是分配出来的资源,不释放就是泄漏;释放后再读,GetResultStatus 返回错误、GetResultItems 返回 false。
  3. GetResultStatus 用 EResult 表达生命周期。挂起是 k_EResultPending,就绪是 k_EResultOK,服务暂时不可用是 k_EResultServiceUnavailable,超出每用户库存上限是 k_EResultLimitExceeded——接入工程按这些结果码决定是重试、展示还是降级。

定义表查询与结果序列化

GetItemDefinitionIDs 返回所有已定义 ItemDef 的 ID 集合,同样是两段式(空数组探测大小):

// isteaminventory.h:GetItemDefinitionIDs(SDK v1.65 头文件摘录,已删减)
virtual bool GetItemDefinitionIDs(
			STEAM_OUT_ARRAY_COUNT(punItemDefIDsArraySize,List of item definition IDs) SteamItemDef_t *pItemDefIDs,
			STEAM_DESC(Size of array is passed in and actual size used is returned in this param) uint32 *punItemDefIDsArraySize ) = 0;

「定义表」和「拥有物」的边界是接入工程最容易写错的地方:

  1. 定义表是全量目录,库存是个人账本。定义表告诉 UI「世界上有哪些物品种类」,库存告诉玩家「你拥有哪些实例」。拿到定义号不等于拥有该物品——判断所有权必须读库存结果集。
  2. 序列化结果是所有权的证据。SerializeResult/DeserializeResult(本节不展开)允许把最小结果集发给其他玩家,配合签名防伪造;CheckResultSteamID 则防止玩家假装持有别人的库存。这为 13.3 的「限定条目出示」和交易验证打下基础。

接口签名对照

头文件条目语义
isteaminventory.hSteamItemDef_t物品种类定义号(32 位,1..999999999)
isteaminventory.hSteamItemInstanceID_t具体物品实例 ID(64 位全局唯一)
isteaminventory.hSteamItemDetails_t结果最小单位:实例/定义/数量/标志
isteaminventory.hGetAllItems(SteamInventoryResult_t*)捕获完整库存快照到新结果句柄
isteaminventory.hGetResultItems(handle, out[], size)两段式读取结果集明细
isteaminventory.hGetResultStatus(handle)结果句柄状态(Pending/OK/错误)
isteaminventory.hGetItemDefinitionIDs(out[], size)查询全量 ItemDef 定义表
isteaminventory.hDestroyResult(handle)释放结果句柄与关联内存

数据口径与来源

  • 接口签名、类型定义、注释语义:SDK v1.65 public/steam/isteaminventory.h 可实证(本机镜像已核对)。
  • 结果句柄需 DestroyResult、GetAllItems 受频率限制、定义号范围:头文件注释明文。
  • 具体物品定价、掉落率、每用户库存上限数值:partner 登录后文档口径或后台配置,以官方当前为准;本卷不给出虚构精确值。

以上接口口径撰写时对照 Steamworks SDK v1.65 头文件与 partner.steamgames.com 官方文档核对;登录后可见数据以官方当前为准。

可运行产物:C++ 最小验证

下面的仿真复现「库存机制」的工程语义:ItemDef 定义表、GetAllItems 快照、GetResultItems 两段式读取、GetResultStatus 状态、GetItemDefinitionIDs 查询、DestroyResult 句柄释放。它与 src/13-1-inventory-mechanics.cpp 逐字节一致,mock 接口签名对照 SDK v1.65 头文件:

// file: src/13-1-inventory-mechanics.cpp
// tier: L1
// verify: clang++ -std=c++20 -Wall -I. src/13-1-inventory-mechanics.cpp -o bin/13-1-inventory-mechanics && ./bin/13-1-inventory-mechanics
//
// mock:复现 ISteamInventory 库存机制的工程语义——ItemDef 定义表、
// GetAllItems 异步快照、GetResultItems 读取结果集、GetResultStatus 结果状态、
// GetItemDefinitionIDs 定义表查询、DestroyResult 释放句柄。
// 签名对照 SDK v1.65 isteaminventory.h,非 Valve 实现。
#include "verify.h"

#include <cstdint>
#include <map>
#include <vector>

namespace steam_repro {

// 类型对照 isteaminventory.h:SteamItemDef_t / SteamItemInstanceID_t / SteamItemDetails_t
using MockItemDef = int32_t;
using MockItemInstanceID = uint64_t;
using MockInventoryResult = int32_t;
constexpr MockInventoryResult kInvalidResult = -1;

// EResult 常用值对照 steamclientpublic.h(mock 只用到 OK / Pending / InvalidParam)
enum MockEResult {
  kResultOK = 1,
  kResultPending = 22,
  kResultInvalidParam = 8,
};

struct MockItemDetails {
  MockItemInstanceID itemId;
  MockItemDef definition;
  uint16_t quantity;
  uint16_t flags;
};

class MockSteamInventory {
 public:
  MockSteamInventory() { loadDefinitions(); }

  // 内置一张 ItemDef 表:定义号在 [1, 999999999] 之间(头文件注释明文),
  // 其余字段为 mock 数据。
  void loadDefinitions() {
    defs_.push_back({100, "plasma_pack", 0});
    defs_.push_back({101, "ember_blade", 1});
    defs_.push_back({102, "nova_core", 1});
    defs_.push_back({200, "starter_crate", 1});
  }

  // 初始库存:两件物品(实例 id 1001/1002,mock 数据)
  void seedInventory() {
    items_.push_back({1001, 100, 1, 0});
    items_.push_back({1002, 101, 3, 0});
  }

  // GetItemDefinitionIDs:pItemDefIDs 为空时返回 true 并写所需大小;
  // 非空时空间不足返回 false。对照 isteaminventory.h:GetItemDefinitionIDs
  bool getItemDefinitionIDs(MockItemDef* pItemDefIDs, uint32_t* pSize) {
    if (!pSize) return false;
    if (!pItemDefIDs) {
      *pSize = static_cast<uint32_t>(defs_.size());
      return true;
    }
    if (*pSize < defs_.size()) return false;
    for (size_t i = 0; i < defs_.size(); ++i) pItemDefIDs[i] = defs_[i].def;
    *pSize = static_cast<uint32_t>(defs_.size());
    return true;
  }

  // GetAllItems:捕获当前库存的完整快照到新结果句柄(注意:真实接口
  // 要求用完调 DestroyResult)。对照 isteaminventory.h:GetAllItems
  bool getAllItems(MockInventoryResult* pResultHandle) {
    if (!pResultHandle) return false;
    *pResultHandle = ++nextResult_;
    results_[*pResultHandle] = items_;
    return true;
  }

  // GetResultStatus:k_EResultOK / k_EResultPending / 无效句柄 k_EResultInvalidParam。
  // 对照 isteaminventory.h:GetResultStatus
  MockEResult getResultStatus(MockInventoryResult resultHandle) const {
    auto it = results_.find(resultHandle);
    if (it == results_.end()) return kResultInvalidParam;
    return kResultOK;
  }

  // GetResultItems:把结果集拷贝进平面数组,并写回实际数量。
  // 对照 isteaminventory.h:GetResultItems
  bool getResultItems(MockInventoryResult resultHandle, MockItemDetails* pOutItems,
                      uint32_t* pSize) const {
    auto it = results_.find(resultHandle);
    if (it == results_.end()) return false;
    if (!pSize) return false;
    if (!pOutItems) {
      *pSize = static_cast<uint32_t>(it->second.size());
      return true;
    }
    if (*pSize < it->second.size()) return false;
    for (size_t i = 0; i < it->second.size(); ++i) pOutItems[i] = it->second[i];
    *pSize = static_cast<uint32_t>(it->second.size());
    return true;
  }

  // DestroyResult:释放结果句柄与关联内存。对照 isteaminventory.h:DestroyResult
  void destroyResult(MockInventoryResult resultHandle) { results_.erase(resultHandle); }

  size_t definitionCount() const { return defs_.size(); }
  size_t inventorySize() const { return items_.size(); }

 private:
  struct Def {
    MockItemDef def;
    const char* name;
    uint32_t basePrice;
  };
  std::vector<Def> defs_;
  std::vector<MockItemDetails> items_;
  std::map<MockInventoryResult, std::vector<MockItemDetails>> results_;
  MockInventoryResult nextResult_ = 0;
};

}  // namespace steam_repro

int main() {
  using namespace steam_repro;

  MockSteamInventory inv;
  inv.seedInventory();

  // 1. ItemDef 定义表:内置 4 条(mock 数据)
  CHECK(inv.definitionCount() == 4);

  // 2. GetItemDefinitionIDs 两段式:先探测大小,再取回
  uint32_t defSize = 0;
  CHECK(inv.getItemDefinitionIDs(nullptr, &defSize));
  CHECK(defSize == 4);
  MockItemDef defs[4] = {0};
  CHECK(inv.getItemDefinitionIDs(defs, &defSize));
  CHECK(defSize == 4);

  // 3. 定义表内容与顺序
  CHECK(defs[0] == 100 && defs[1] == 101 && defs[2] == 102 && defs[3] == 200);

  // 4. 空间不足:返回 false 且大小不变
  uint32_t small = 2;
  CHECK(!inv.getItemDefinitionIDs(defs, &small));
  CHECK(small == 2);

  // 5. GetAllItems 创建有效结果句柄(非 k_SteamInventoryResultInvalid)
  MockInventoryResult handle = kInvalidResult;
  CHECK(inv.getAllItems(&handle));
  CHECK(handle != kInvalidResult);

  // 6. GetResultStatus:就绪
  CHECK(inv.getResultStatus(handle) == kResultOK);

  // 7. GetResultItems 两段式:先探测件数
  uint32_t itemCount = 0;
  CHECK(inv.getResultItems(handle, nullptr, &itemCount));
  CHECK(itemCount == 2);

  // 8. GetResultItems 取回明细:实例 id、定义号、数量
  MockItemDetails out[2] = {};
  CHECK(inv.getResultItems(handle, out, &itemCount));
  CHECK(itemCount == 2);
  CHECK(out[0].itemId == 1001 && out[0].definition == 100 && out[0].quantity == 1);
  CHECK(out[1].itemId == 1002 && out[1].definition == 101 && out[1].quantity == 3);

  // 9. 无效句柄:GetResultStatus 返回错误,GetResultItems 返回 false
  CHECK(inv.getResultStatus(9999) == kResultInvalidParam);
  CHECK(!inv.getResultItems(9999, out, &itemCount));

  // 10. DestroyResult 后句柄失效:状态错误、结果不可读
  inv.destroyResult(handle);
  CHECK(inv.getResultStatus(handle) == kResultInvalidParam);
  uint32_t stale = 99;
  CHECK(!inv.getResultItems(handle, nullptr, &stale));

  // 11. 销毁后再次 GetAllItems:新句柄可正常读到当前库存
  MockInventoryResult fresh = kInvalidResult;
  CHECK(inv.getAllItems(&fresh));
  CHECK(fresh != handle);
  uint32_t freshCount = 0;
  CHECK(inv.getResultItems(fresh, nullptr, &freshCount));
  CHECK(freshCount == inv.inventorySize());
  inv.destroyResult(fresh);

  return lab::report("13-1 库存机制");
}

本机实测(Apple clang 16,clang++ -std=c++20 -Wall):编译通过(零警告),断言 25/25 通过。

小结

  • 库存三基本量:ItemDef(种类)、实例 ID(具体一件)、结果集句柄(一次查询的输出)。
  • 读取永远异步:GetAllItems 拿句柄 → 等回调 → GetResultItems 两段式取回明细。
  • 结果句柄是资源:用完必须 DestroyResult;释放后句柄立即失效。
  • 定义表是配置驱动的全量目录,与个人库存账本严格分离。

阅读导航:上一节:12.3 平台事件的产品设计 · 下一节:13.2 微交易与资产经济 。

继续阅读

探索更多技术文章

浏览归档,发现更多关于系统设计、工具链和工程实践的内容。

全部文章 返回首页

「books」更多文章

  1. 《大规模分布式计算深入解析》15.3 落地:从 Neo4j 到自研图引擎
  2. 《大规模分布式计算深入解析·图计算与图数据库内核》 · 目录与学习路径(45 篇)
  3. 《大规模分布式计算深入解析》15.2 十一卷主线:从切分到图