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
};
工程语义上有三个要点:
- 「种类」和「实例」是分离的。玩家拥有 3 把相同定义的刀,是 3 个实例 ID;消耗其中 1 把,是某个实例的数量减一(13.3 详讲)。显示层通常按定义聚合,但操作层必须按实例处理。
- 定义表是配置驱动的。ItemDef 不是硬编码在代码里,而是通过 Steamworks 后台配置、客户端用
LoadItemDefinitions拉取并监听SteamInventoryDefinitionUpdate_t。这让游戏可以在不发布客户端补丁的情况下新增物品种类(头文件注释明确「does not allow for adding new item types without a client patch」是硬编码的缺点)。 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;
工程语义:
- 先探测长度、再取回数据。
GetResultItems传空数组时返回 true 并把所需件数写进punOutItemsArraySize;再分配足够数组、把大小传进去取回。缓冲区不足则返回 false。这与云存储FileRead、加密票据GetEncryptedAppTicket的两段式惯例一致。 - 结果句柄必须用
DestroyResult释放。头文件对GetAllItems明确要求「You must call DestroyResult on this handle when you are done with it」。句柄是分配出来的资源,不释放就是泄漏;释放后再读,GetResultStatus返回错误、GetResultItems返回 false。 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;
「定义表」和「拥有物」的边界是接入工程最容易写错的地方:
- 定义表是全量目录,库存是个人账本。定义表告诉 UI「世界上有哪些物品种类」,库存告诉玩家「你拥有哪些实例」。拿到定义号不等于拥有该物品——判断所有权必须读库存结果集。
- 序列化结果是所有权的证据。
SerializeResult/DeserializeResult(本节不展开)允许把最小结果集发给其他玩家,配合签名防伪造;CheckResultSteamID则防止玩家假装持有别人的库存。这为 13.3 的「限定条目出示」和交易验证打下基础。
接口签名对照
| 头文件 | 条目 | 语义 |
|---|---|---|
isteaminventory.h | SteamItemDef_t | 物品种类定义号(32 位,1..999999999) |
isteaminventory.h | SteamItemInstanceID_t | 具体物品实例 ID(64 位全局唯一) |
isteaminventory.h | SteamItemDetails_t | 结果最小单位:实例/定义/数量/标志 |
isteaminventory.h | GetAllItems(SteamInventoryResult_t*) | 捕获完整库存快照到新结果句柄 |
isteaminventory.h | GetResultItems(handle, out[], size) | 两段式读取结果集明细 |
isteaminventory.h | GetResultStatus(handle) | 结果句柄状态(Pending/OK/错误) |
isteaminventory.h | GetItemDefinitionIDs(out[], size) | 查询全量 ItemDef 定义表 |
isteaminventory.h | DestroyResult(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 微交易与资产经济 。
继续阅读
探索更多技术文章
浏览归档,发现更多关于系统设计、工具链和工程实践的内容。