13.3 库存的商业模型
13.1 讲「读库存」,13.2 讲「资产怎么来、怎么买」,这一节把库存当作商业模型的载体来谈工程语义:消耗、合成、拆分、促销、掉落,以及交易约束。买断制游戏里,库存不是收入主力,但它是「买断之后的补充收入与留存杠杆」——限时掉落制造稀缺、限定条目制造身份、合成消耗制造内容纵深。本节只讲这些操作的接口语义与机制判断,不臆造转化率等官方数值。
本卷所有接口口径以 Steamworks SDK v1.65(2026-07-23) 为准。本节摘录的签名对照该版本 public/steam/isteaminventory.h。
本章与站内既有内容的分工
- Steam 发行专题 (操作手册)讲「后台配置掉落率、开交易」;本节讲「代码里把库存做成商业模型的接口语义」。
- 卷一《平台机制与商店》讲平台机制;本节在机制位的基础上给出接口位:消耗/合成/促销/掉落的落地写法。
- idb 财务(收入口径 )讲报表与 LTV;本节给接入侧「物品生命周期」口径。
- 转化率、掉落率等精确数值:官方不公开,正文只给量级并标注模型假设;lab 验证机制不验证数值。
消耗与状态标志
ConsumeItem 永久移除物品,头文件注释直接用了「not for the faint of heart」——消耗是不可逆的,接入工程必须给高摩擦的确认 UI。物品的状态由 ESteamItemFlags 承载:
// isteaminventory.h:ESteamItemFlags / ConsumeItem(SDK v1.65 头文件摘录,已删减)
enum ESteamItemFlags
{
k_ESteamItemNoTrade = 1 << 0, // This item is account-locked and cannot be traded or given away.
k_ESteamItemRemoved = 1 << 8, // The item has been destroyed, traded away, expired, or otherwise invalidated
k_ESteamItemConsumed = 1 << 9, // The item quantity has been decreased by 1 via ConsumeItem API.
};
virtual bool ConsumeItem( SteamInventoryResult_t *pResultHandle, SteamItemInstanceID_t itemConsume, uint32 unQuantity ) = 0;
工程语义:
- 消耗是「数量」不是「整件」。
ConsumeItem带unQuantity,消耗到零时物品标记k_ESteamItemConsumed。mock 里要断言:数量不足时调用失败、状态不变;消耗到零标记位置位。 k_ESteamItemNoTrade是商业约束位。限定条目/促销条目通常带不可交易位——「账号锁定、不能交易或转赠」。这个位是永久附着在实例上的(头文件注释「permanently attached to specific item instances」),接入工程判断可交易性读它,而不是自己维护一份清单。- 消耗即稀缺性设计。限时消耗品(增益道具、钥匙)让玩家持续回来;但消耗不可逆,UI 必须给确认,工程上把
ConsumeItem放进受控入口。
原子合成:ExchangeItems
ExchangeItems 是生成与消耗的原子组合,用来实现合成配方、转化、开箱:
// isteaminventory.h:ExchangeItems(SDK v1.65 头文件摘录,已删减)
virtual bool ExchangeItems( SteamInventoryResult_t *pResultHandle,
STEAM_ARRAY_COUNT(unArrayGenerateLength) const SteamItemDef_t *pArrayGenerate, STEAM_ARRAY_COUNT(unArrayGenerateLength) const uint32 *punArrayGenerateQuantity, uint32 unArrayGenerateLength,
STEAM_ARRAY_COUNT(unArrayDestroyLength) const SteamItemInstanceID_t *pArrayDestroy, STEAM_ARRAY_COUNT(unArrayDestroyLength) const uint32 *punArrayDestroyQuantity, uint32 unArrayDestroyLength ) = 0;
工程语义:
- 配方由 ItemDef 定义,评估在库存服务端。客户端给「要生成的条目」和「要消耗的实例」,服务端按配方原子评估:组件不匹配或数量不足,整个交换失败,不会出现「扣了材料没给产物」的中间态。mock 必须验证失败原子性:组件不足时状态完全不变。
- 合成是内容纵深的引擎。
ExchangeItems让低价值条目可以合成为高价值条目(材料→装备→套装),消耗天然构成经济闭环。它的副作用是通缩——需要掉落端不断注水。 - 开箱/转化是同一机制。头文件注释点名「a chest」和「items which unpack themselves」都可用
ExchangeItems实现——把箱子实例换成其中的物品。
堆叠拆分与游玩时长掉落
TransferItemQuantity 处理可堆叠物品(拆堆、合并、转到同定义新堆),TriggerItemDrop 把游玩时长积分兑换成掉落:
// isteaminventory.h:TransferItemQuantity / TriggerItemDrop(SDK v1.65 头文件摘录,已删减)
virtual bool TransferItemQuantity( SteamInventoryResult_t *pResultHandle, SteamItemInstanceID_t itemIdSource, uint32 unQuantity, SteamItemInstanceID_t itemIdDest ) = 0;
virtual bool TriggerItemDrop( SteamInventoryResult_t *pResultHandle, SteamItemDef_t dropListDefinition ) = 0;
工程语义:
- 拆分/合并只发生在同定义之间。
TransferItemQuantity把源堆的一部分移给目标堆,目标无效(k_SteamItemInstanceIDInvalid)时生成新实例;不同定义不能合并——mock 里要断言跨定义合并失败。 - 掉落受游玩时长积分约束。掉落必须有积分才触发,积分不足返回空结果集;掉落清单的「珍稀度」由后台配置。头文件注释警告:玩家能篡改
dropListDefinition参数,所以别用它直接控制珍稀度——珍稀判定要放在服务端。 - 掉落调用要选时机。头文件建议在回合间隙或玩家死亡时调用(如
between rounds or while the player is dead),既避免打断操作,也让掉落成为「再来一局」的正反馈。
接口签名对照
| 头文件 | 条目 | 语义 |
|---|---|---|
isteaminventory.h | ESteamItemFlags | 物品状态位(NoTrade/Removed/Consumed) |
isteaminventory.h | ConsumeItem(handle, id, qty) | 永久消耗数量(不可逆) |
isteaminventory.h | ExchangeItems(handle, gen[], destroy[], ...) | 原子合成:消耗组件、生成产物 |
isteaminventory.h | TransferItemQuantity(handle, src, qty, dest) | 堆叠拆分/合并(同定义) |
isteaminventory.h | AddPromoItem(handle, def) | 一次性限定促销条目 |
isteaminventory.h | TriggerItemDrop(handle, dropDef) | 游玩时长积分兑换掉落 |
数据口径与来源
- 接口签名、
ESteamItemFlags位定义、注释语义:SDK v1.65public/steam/isteaminventory.h可实证(本机镜像已核对)。 - 掉落率、促销频率、转化率、限时周期:官方不公开精确值,正文只给「掉落制造稀缺、限定制造身份」的量级判断并标注模型假设。
- 后台掉落配置、交易开关:partner 登录后文档口径,以官方当前为准。
以上接口口径撰写时对照 Steamworks SDK v1.65 头文件与 partner.steamgames.com 官方文档核对;登录后可见数据以官方当前为准。
可运行产物:C++ 最小验证
下面的仿真复现「库存商业模型」的工程语义:ConsumeItem 消耗与数量不足拒绝、Consumed 标志、ExchangeItems 原子合成与失败原子性、TransferItemQuantity 拆分与跨定义拒绝、NoTrade 交易约束、AddPromoItem 一次性授予、TriggerItemDrop 游玩时长积分消耗。它与 src/13-3-inventory-business.cpp 逐字节一致,mock 接口签名对照 SDK v1.65 头文件:
// file: src/13-3-inventory-business.cpp
// tier: L1
// verify: clang++ -std=c++20 -Wall -I. src/13-3-inventory-business.cpp -o bin/13-3-inventory-business && ./bin/13-3-inventory-business
//
// mock:复现库存商业模型的工程语义——ConsumeItem 消耗、
// ExchangeItems 原子合成(配方)、TransferItemQuantity 堆叠拆分、
// AddPromoItem 一次性促销、TriggerItemDrop 游玩时长掉落、
// k_ESteamItemNoTrade 不可交易标志。
// 签名对照 SDK v1.65 isteaminventory.h,非 Valve 实现。
#include "verify.h"
#include <cstdint>
#include <map>
#include <vector>
namespace steam_repro {
using MockItemDef = int32_t;
using MockItemInstanceID = uint64_t;
using MockInventoryResult = int32_t;
constexpr MockInventoryResult kInvalidResult = -1;
// k_SteamItemInstanceIDInvalid 对照 isteaminventory.h
constexpr MockItemInstanceID kInvalidInstanceID = ~MockItemInstanceID(0);
// ESteamItemFlags 标志对照 isteaminventory.h
constexpr uint16_t kItemNoTrade = 1 << 0;
constexpr uint16_t kItemConsumed = 1 << 9;
struct MockItem {
MockItemInstanceID itemId;
MockItemDef definition;
uint32_t quantity;
uint16_t flags;
};
class MockSteamInventory {
public:
// mock 库存:instanceId -> item
MockSteamInventory() {
items_[5001] = {5001, 100, 5, 0};
items_[5002] = {5002, 101, 1, 0};
items_[5003] = {5003, 102, 2, 0};
items_[5004] = {5004, 103, 1, kItemNoTrade}; // 不可交易的限定条目
}
// ConsumeItem:消耗数量;数量不足失败;消耗到 0 标记 k_ESteamItemConsumed。
// 对照 isteaminventory.h:ConsumeItem
bool consumeItem(MockInventoryResult* pResultHandle, MockItemInstanceID itemId,
uint32_t qty) {
auto it = items_.find(itemId);
if (it == items_.end() || it->second.quantity < qty) return false;
it->second.quantity -= qty;
if (it->second.quantity == 0) {
it->second.flags |= kItemConsumed;
}
if (pResultHandle) *pResultHandle = ++nextResult_;
return true;
}
// ExchangeItems:原子合成——组件数量不足时整体失败、不改任何状态;
// 成功则消耗组件、生成产物。对照 isteaminventory.h:ExchangeItems
bool exchangeItems(MockInventoryResult* pResultHandle,
const MockItemDef* genDefs, const uint32_t* genQtys, uint32_t genLen,
const MockItemInstanceID* destroyIds, const uint32_t* destroyQtys,
uint32_t destroyLen) {
for (uint32_t i = 0; i < destroyLen; ++i) {
auto it = items_.find(destroyIds[i]);
if (it == items_.end() || it->second.quantity < destroyQtys[i]) return false;
}
for (uint32_t i = 0; i < destroyLen; ++i) {
items_[destroyIds[i]].quantity -= destroyQtys[i];
if (items_[destroyIds[i]].quantity == 0) items_[destroyIds[i]].flags |= kItemConsumed;
}
std::vector<MockItem> produced;
for (uint32_t i = 0; i < genLen; ++i) {
MockItem it;
it.itemId = ++nextInstance_;
it.definition = genDefs[i];
it.quantity = genQtys[i];
it.flags = 0;
items_[it.itemId] = it;
produced.push_back(it);
}
if (pResultHandle) *pResultHandle = ++nextResult_;
return true;
}
// TransferItemQuantity:堆叠拆分/合并。dest 无效则生成新实例。
// 对照 isteaminventory.h:TransferItemQuantity
bool transferItemQuantity(MockInventoryResult* pResultHandle,
MockItemInstanceID srcId, uint32_t qty, MockItemInstanceID destId) {
auto sit = items_.find(srcId);
if (sit == items_.end() || sit->second.quantity < qty) return false;
if (destId == kInvalidInstanceID) {
MockItem it;
it.itemId = ++nextInstance_;
it.definition = sit->second.definition;
it.quantity = qty;
it.flags = sit->second.flags;
items_[it.itemId] = it;
sit->second.quantity -= qty;
} else {
auto dit = items_.find(destId);
if (dit == items_.end() || dit->second.definition != sit->second.definition) return false;
sit->second.quantity -= qty;
dit->second.quantity += qty;
}
if (pResultHandle) *pResultHandle = ++nextResult_;
return true;
}
// AddPromoItem:一次性的限定促销条目;已授予则结果集为空。
// 对照 isteaminventory.h:AddPromoItem
bool addPromoItem(MockInventoryResult* pResultHandle, MockItemDef def) {
if (promos_.count(def)) return true; // 已授予:成功但无新增
MockItem it;
it.itemId = ++nextInstance_;
it.definition = def;
it.quantity = 1;
it.flags = kItemNoTrade;
items_[it.itemId] = it;
promos_[def] = true;
if (pResultHandle) *pResultHandle = ++nextResult_;
return true;
}
// TriggerItemDrop:消耗游玩时长积分换取掉落;积分不足返回空结果集。
// 对照 isteaminventory.h:TriggerItemDrop
bool triggerItemDrop(MockInventoryResult* pResultHandle, MockItemDef dropDef) {
if (playtimeCredit_ < kDropCost) {
if (pResultHandle) *pResultHandle = ++nextResult_;
return true;
}
playtimeCredit_ -= kDropCost;
MockItem it;
it.itemId = ++nextInstance_;
it.definition = dropDef;
it.quantity = 1;
it.flags = 0;
items_[it.itemId] = it;
if (pResultHandle) *pResultHandle = ++nextResult_;
return true;
}
void addPlaytimeCredit(uint32_t credit) { playtimeCredit_ += credit; }
uint32_t playtimeCredit() const { return playtimeCredit_; }
// 最近一次分配的实例 id(mock 调试访问器,非 SDK 接口)
MockItemInstanceID lastAllocatedInstance() const { return nextInstance_; }
uint32_t quantityOf(MockItemInstanceID id) const {
auto it = items_.find(id);
return it == items_.end() ? 0 : it->second.quantity;
}
uint16_t flagsOf(MockItemInstanceID id) const {
auto it = items_.find(id);
return it == items_.end() ? 0 : it->second.flags;
}
bool exists(MockItemInstanceID id) const { return items_.count(id) != 0; }
bool isTradable(MockItemInstanceID id) const {
auto it = items_.find(id);
return it == items_.end() ? false : (it->second.flags & kItemNoTrade) == 0;
}
size_t inventorySize() const { return items_.size(); }
static constexpr uint32_t kDropCost = 100;
private:
std::map<MockItemInstanceID, MockItem> items_;
std::map<MockItemDef, bool> promos_;
MockInventoryResult nextResult_ = 0;
MockItemInstanceID nextInstance_ = 6000;
uint32_t playtimeCredit_ = 0;
};
} // namespace steam_repro
int main() {
using namespace steam_repro;
MockSteamInventory inv;
// 1. ConsumeItem:消耗 2 后剩 3
CHECK(inv.consumeItem(nullptr, 5001, 2));
CHECK(inv.quantityOf(5001) == 3);
// 2. 数量不足时失败
CHECK(!inv.consumeItem(nullptr, 5001, 4));
CHECK(inv.quantityOf(5001) == 3);
// 3. 消耗到 0:标记 k_ESteamItemConsumed
CHECK(inv.consumeItem(nullptr, 5002, 1));
CHECK(inv.flagsOf(5002) & kItemConsumed);
// 4. ExchangeItems:用 2 个定义 100 换 1 个定义 200(mock 配方)
MockItemDef gen = 200;
uint32_t genQty = 1;
const MockItemInstanceID destroyIds[1] = {5001};
const uint32_t destroyQtys[1] = {2};
CHECK(inv.exchangeItems(nullptr, &gen, &genQty, 1, destroyIds, destroyQtys, 1));
CHECK(inv.quantityOf(5001) == 1); // 5 - 2 再减前面消耗的 2 = 1
// 5. 组件不足:原子失败,状态不变
size_t before = inv.inventorySize();
CHECK(!inv.exchangeItems(nullptr, &gen, &genQty, 1, destroyIds, destroyQtys, 1));
CHECK(inv.quantityOf(5001) == 1);
CHECK(inv.inventorySize() == before);
// 6. TransferItemQuantity:拆分到新实例(dest 无效)
CHECK(inv.transferItemQuantity(nullptr, 5003, 1, kInvalidInstanceID));
CHECK(inv.quantityOf(5003) == 1); // 2 - 1
MockItemInstanceID splitId = inv.lastAllocatedInstance();
CHECK(inv.exists(splitId));
CHECK(inv.quantityOf(splitId) == 1);
// 7. TransferItemQuantity:不同定义不可合并
CHECK(!inv.transferItemQuantity(nullptr, 5001, 1, 5003));
// 8. NoTrade 标志:不可交易条目拒绝交易
CHECK(!inv.isTradable(5004));
CHECK(inv.isTradable(5001));
// 9. AddPromoItem:一次性授予,重复调用不重复发放
MockInventoryResult promoHandle = kInvalidResult;
CHECK(inv.addPromoItem(&promoHandle, 300));
MockItemInstanceID promoId = inv.lastAllocatedInstance();
CHECK(inv.exists(promoId));
CHECK(inv.flagsOf(promoId) & kItemNoTrade); // 促销条目默认不可交易
size_t sizeAfterPromo = inv.inventorySize();
CHECK(inv.addPromoItem(nullptr, 300));
CHECK(inv.inventorySize() == sizeAfterPromo); // 未新增
// 10. TriggerItemDrop:无游玩时长积分时为空结果(成功但不掉落)
MockInventoryResult dropHandle = kInvalidResult;
CHECK(inv.triggerItemDrop(&dropHandle, 400));
size_t sizeBeforeDrop = inv.inventorySize();
CHECK(inv.inventorySize() == sizeBeforeDrop); // 无新增
// 11. 补充积分后掉落:积分扣除、条目新增
inv.addPlaytimeCredit(250);
CHECK(inv.playtimeCredit() == 250);
CHECK(inv.triggerItemDrop(nullptr, 400));
CHECK(inv.playtimeCredit() == 150);
CHECK(inv.inventorySize() == sizeBeforeDrop + 1);
return lab::report("13-3 库存的商业模型");
}
本机实测(Apple clang 16,clang++ -std=c++20 -Wall):编译通过(零警告),断言 29/29 通过。
小结
ConsumeItem不可逆:按数量消耗,消耗到零标记k_ESteamItemConsumed;UI 必须高摩擦确认。k_ESteamItemNoTrade永久附着实例,是交易约束的权威位。ExchangeItems原子合成:组件不足整体失败,是合成/开箱/转化的统一机制。TransferItemQuantity只在同定义间拆分合并;TriggerItemDrop消耗游玩时长积分,珍稀度判定放服务端。
阅读导航:上一节:13.2 微交易与资产经济 · 下一节:14.1 平台工具机制 。
继续阅读
探索更多技术文章
浏览归档,发现更多关于系统设计、工具链和工程实践的内容。