《Steam 游戏平台:开发与商业化》13.3 库存的商业模型

本节接库存商业模型的接口语义:ConsumeItem 消耗、ExchangeItems 原子合成、TransferItemQuantity 堆叠拆分、AddPromoItem 一次性促销、TriggerItemDrop 游玩时长掉落与 ESteamItemFlags 交易约束。lab 用 C++ mock 消耗、配方、拆分、促销与掉落,验证原子性、一次性授予与数量约束。

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;

工程语义:

  1. 消耗是「数量」不是「整件」。ConsumeItem 带 unQuantity,消耗到零时物品标记 k_ESteamItemConsumed。mock 里要断言:数量不足时调用失败、状态不变;消耗到零标记位置位。
  2. k_ESteamItemNoTrade 是商业约束位。限定条目/促销条目通常带不可交易位——「账号锁定、不能交易或转赠」。这个位是永久附着在实例上的(头文件注释「permanently attached to specific item instances」),接入工程判断可交易性读它,而不是自己维护一份清单。
  3. 消耗即稀缺性设计。限时消耗品(增益道具、钥匙)让玩家持续回来;但消耗不可逆,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;

工程语义:

  1. 配方由 ItemDef 定义,评估在库存服务端。客户端给「要生成的条目」和「要消耗的实例」,服务端按配方原子评估:组件不匹配或数量不足,整个交换失败,不会出现「扣了材料没给产物」的中间态。mock 必须验证失败原子性:组件不足时状态完全不变。
  2. 合成是内容纵深的引擎。ExchangeItems 让低价值条目可以合成为高价值条目(材料→装备→套装),消耗天然构成经济闭环。它的副作用是通缩——需要掉落端不断注水。
  3. 开箱/转化是同一机制。头文件注释点名「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;

工程语义:

  1. 拆分/合并只发生在同定义之间。TransferItemQuantity 把源堆的一部分移给目标堆,目标无效(k_SteamItemInstanceIDInvalid)时生成新实例;不同定义不能合并——mock 里要断言跨定义合并失败。
  2. 掉落受游玩时长积分约束。掉落必须有积分才触发,积分不足返回空结果集;掉落清单的「珍稀度」由后台配置。头文件注释警告:玩家能篡改 dropListDefinition 参数,所以别用它直接控制珍稀度——珍稀判定要放在服务端。
  3. 掉落调用要选时机。头文件建议在回合间隙或玩家死亡时调用(如 between rounds or while the player is dead),既避免打断操作,也让掉落成为「再来一局」的正反馈。

接口签名对照

头文件条目语义
isteaminventory.hESteamItemFlags物品状态位(NoTrade/Removed/Consumed)
isteaminventory.hConsumeItem(handle, id, qty)永久消耗数量(不可逆)
isteaminventory.hExchangeItems(handle, gen[], destroy[], ...)原子合成:消耗组件、生成产物
isteaminventory.hTransferItemQuantity(handle, src, qty, dest)堆叠拆分/合并(同定义)
isteaminventory.hAddPromoItem(handle, def)一次性限定促销条目
isteaminventory.hTriggerItemDrop(handle, dropDef)游玩时长积分兑换掉落

数据口径与来源

  • 接口签名、ESteamItemFlags 位定义、注释语义:SDK v1.65 public/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 平台工具机制 。

继续阅读

探索更多技术文章

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

全部文章 返回首页

「books」更多文章

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