《Steam 游戏平台:开发与商业化》13.2 微交易与资产经济

本节接库存微交易的接口语义:GenerateItems 生成条目、RequestPrices/GetItemPrice 价格模型、StartPurchase 触发购买、MicroTxnAuthorizationResponse_t 授权回调。lab 用 C++ mock 条目生成、价格表与购买-授权流程,验证价格可见性、生成唯一性与授权后才落库的机制。

13.2 微交易与资产经济

上一节讲了怎么「读」库存,这一节讲「资产怎么产生、怎么定价、怎么买」。Steam 的资产经济有一个明确的分工:生成与定价是 Steam 后端/partner 工具侧的语义,客户端只负责触发与展示。触发用 ISteamInventory::StartPurchase,价格用 RequestPrices/GetItemPrice 拉取,而真正从玩家账户扣款的微交易授权,客户端收到的是 MicroTxnAuthorizationResponse_t 回调——授权结果是 Steam 判定的,不是客户端说了算。

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

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

  • Steam 发行专题 (操作手册)讲「后台开微交易、配库存价格」;本节讲「客户端接口侧的资产产生与定价工程语义」。
  • 卷一《平台机制与商店》讲机制与定价模型;本节讲 GenerateItems、StartPurchase、价格接口怎么在工程上落地。
  • idb 财务(如《独立开发者的商业指南》的收入口径 )讲收入报表与 LTV;本节给接入侧的条目生成与定价口径。
  • 第 13 章整体不写 Steam 后台点击步骤;lab 用纯 C++ mock 条目生成、价格表与购买-授权流程。

条目生成:原型工具与生产隔离

GenerateItems 能直接给玩家「造物品」,但头文件把它的定位写得很清楚——只是原型工具,只对属于发行商组的 Steam 账号可用:

// isteaminventory.h:GenerateItems(SDK v1.65 头文件摘录,已删减)
virtual bool GenerateItems( SteamInventoryResult_t *pResultHandle, STEAM_ARRAY_COUNT(unArrayLength) const SteamItemDef_t *pArrayItemDefs, STEAM_ARRAY_COUNT(unArrayLength) const uint32 *punArrayQuantity, uint32 unArrayLength ) = 0;

工程语义:

  1. 生产环境不靠 GenerateItems 发资产。正式发放要走 partner 工具或 Web API(登录后可见),GenerateItems 在头文件里被限定为 prototyping。接入工程应把它留在开发构建里,用编译开关隔离。
  2. 生成是「定义 + 数量」成对输入的。pArrayItemDefs 与 punArrayQuantity 等长,表示每种定义生成几件;返回的结果集里每个实例有全局唯一 ID(mock 里可断言实例 ID 单调递增)。
  3. 资产经济里「物品从哪来」必须可审计。掉落、促销、购买各有入口(TriggerItemDrop/AddPromoItem/StartPurchase),生成路径要能区分,否则余额与来源对不上账。

价格模型:RequestPrices 与 GetItemPrice

价格由 Steam 后台配置,客户端拉取而不是写死。RequestPrices 异步请求当前价格,GetItemPrice 取单条:

// isteaminventory.h:RequestPrices / GetItemPrice(SDK v1.65 头文件摘录,已删减)
STEAM_CALL_RESULT( SteamInventoryRequestPricesResult_t )
virtual SteamAPICall_t RequestPrices() = 0;

virtual bool GetItemPrice( SteamItemDef_t iDefinition, uint64 *pCurrentPrice, uint64 *pBasePrice ) = 0;

工程语义:

  1. 价格是「当前价 + 基础价」双轨。pCurrentPrice 是玩家本地货币下的实时价,pBasePrice 是基础价——促销折扣就是两者之差。UI 显示「划线价 + 现价」时读这两个字段,而不是自己猜折扣。
  2. 先 RequestPrices 再读价格。GetNumItemsWithPrices/GetItemsWithPrices/GetItemPrice 都依赖价格已拉取;本地货币由 Steam 换算,客户端不自己做汇率。
  3. 价格是配置而非代码。改价不需要发客户端补丁,接入工程应把价格视为服务端数据,避免在代码里硬编码任何货币数字。

购买与授权:StartPurchase 与 MicroTxnAuthorizationResponse_t

客户端触发购买用 StartPurchase,它返回订单号并通过 SteamInventoryStartPurchaseResult_t 回调给出 m_ulOrderID/m_ulTransID:

// isteaminventory.h:StartPurchase 与 SteamInventoryStartPurchaseResult_t(SDK v1.65 头文件摘录,已删减)
STEAM_CALL_RESULT( SteamInventoryStartPurchaseResult_t )
virtual SteamAPICall_t StartPurchase( STEAM_ARRAY_COUNT(unArrayLength) const SteamItemDef_t *pArrayItemDefs, STEAM_ARRAY_COUNT(unArrayLength) const uint32 *punArrayQuantity, uint32 unArrayLength ) = 0;

struct SteamInventoryStartPurchaseResult_t
{
	enum { k_iCallback = k_iSteamInventoryCallbacks + 4 };
	EResult m_result;
	uint64 m_ulOrderID;
	uint64 m_ulTransID;
};

玩家在 Steam 内完成授权后,客户端收到 MicroTxnAuthorizationResponse_t——它带着 AppID、订单号和授权位:

// isteamuser.h:MicroTxnAuthorizationResponse_t(SDK v1.65 头文件摘录,已删减)
struct MicroTxnAuthorizationResponse_t
{
	enum { k_iCallback = k_iSteamUserCallbacks + 52 };
	
	uint32 m_unAppID;			// AppID for this microtransaction
	uint64 m_ulOrderID;			// OrderID provided for the microtransaction
	uint8 m_bAuthorized;		// if user authorized transaction
};

工程语义(也是本节最重要的机制判断):

  1. 授权位 m_bAuthorized 是 Steam 判定的。StartPurchase 只发起流程,扣不扣款由 Steam 的微交易系统决定;客户端收到 m_bAuthorized == 0 就绝不能发放物品。
  2. 订单与条目一一对应。回调里的 m_ulOrderID 要和 SteamInventoryStartPurchaseResult_t 里的对上,接入工程用订单号做幂等:同一订单被重复回调也不能重复发资产。
  3. 真正的购买触发是 partner 工具语义。客户端 StartPurchase 面向「游戏内商店」;后端驱动的微交易(如网页/移动端触发)属于 partner/Web API 侧,正文只讲机制判断,不写后台点击步骤。

接口签名对照

头文件条目语义
isteaminventory.hGenerateItems(...)生成条目(仅原型/发行商组账号可用)
isteaminventory.hRequestPrices()异步请求全部条目价格
isteaminventory.hGetNumItemsWithPrices()有价条目数量(需先 RequestPrices)
isteaminventory.hGetItemPrice(def, cur, base)单条目当前价/基础价
isteaminventory.hStartPurchase(defs, qtys, len)发起游戏内购买流程
isteaminventory.hSteamInventoryStartPurchaseResult_t购买初始化结果(订单/交易号)
isteamuser.hMicroTxnAuthorizationResponse_t用户对微交易授权请求的应答

数据口径与来源

  • 接口签名、回调结构体字段:SDK v1.65 public/steam/isteaminventory.h、isteamuser.h 可实证(本机镜像已核对)。
  • GenerateItems 仅原型可用、价格以本地货币呈现:头文件注释明文。
  • 具体价格、货币汇率、扣款流程细节:partner 登录后文档口径,以官方当前为准。
  • 本节的 mock 价格表(99/149/399 等)与转化量级为模型假设,仅用于验证接口机制,不代表真实定价。

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

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

下面的仿真复现「微交易与资产经济」的工程语义:GenerateItems 条目生成(唯一实例 ID)、RequestPrices 价格可见性、GetItemsWithPrices/GetItemPrice 读取、StartPurchase 发起订单、MicroTxnAuthorizationResponse_t 授权后落库、拒绝/错误 AppID 不落库。它与 src/13-2-microtransaction-assets.cpp 逐字节一致,mock 接口签名对照 SDK v1.65 头文件:

// file: src/13-2-microtransaction-assets.cpp
// tier: L1
// verify: clang++ -std=c++20 -Wall -I. src/13-2-microtransaction-assets.cpp -o bin/13-2-microtransaction-assets && ./bin/13-2-microtransaction-assets
//
// mock:复现库存微交易与资产经济的工程语义——GenerateItems 生成条目、
// RequestPrices/GetItemPrice/GetItemsWithPrices 价格模型、
// StartPurchase 触发购买流程、MicroTxnAuthorizationResponse_t 授权回调、
// 授权后结果集写入生成条目。
// 签名对照 SDK v1.65 isteaminventory.h / isteamuser.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;

enum MockEResult {
  kResultOK = 1,
  kResultFail = 2,
  kResultInvalidParam = 8,
  kResultLimitExceeded = 25,
};

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

// 模拟 MicroTxnAuthorizationResponse_t(isteamuser.h,k_iSteamUserCallbacks + 52):
// 用户对一笔微交易授权请求的应答。
struct MockMicroTxnAuthorization {
  uint32_t appId;
  uint64_t orderId;
  uint8_t authorized;
};

class MockSteamInventory {
 public:
  MockSteamInventory() {
    // 价格表:只有带 price 的条目才可被 RequestPrices 拉取(mock 数据)。
    prices_[100] = {149, 99};    // plasma_pack:base 149,当前促销 99
    prices_[101] = {399, 399};   // ember_blade:base 399,无折扣
    defs_.push_back({100, "plasma_pack"});
    defs_.push_back({101, "ember_blade"});
    defs_.push_back({102, "nova_core"});
    defs_.push_back({200, "starter_crate"});
  }

  // RequestPrices:请求当前所有适用条目价格。对照 isteaminventory.h:RequestPrices
  MockEResult requestPrices() {
    pricesLoaded_ = true;
    return kResultOK;
  }

  // GetNumItemsWithPrices:需要先 RequestPrices。对照 isteaminventory.h:GetNumItemsWithPrices
  uint32_t getNumItemsWithPrices() const {
    if (!pricesLoaded_) return 0;
    return static_cast<uint32_t>(prices_.size());
  }

  // GetItemsWithPrices:输出定义号、当前价、基础价。对照 isteaminventory.h:GetItemsWithPrices
  bool getItemsWithPrices(MockItemDef* pDefs, uint64_t* pCurrent, uint64_t* pBase,
                          uint32_t len) const {
    if (!pricesLoaded_) return false;
    if (len < prices_.size()) return false;
    uint32_t i = 0;
    for (const auto& kv : prices_) {
      pDefs[i] = kv.first;
      pCurrent[i] = kv.second.current;
      pBase[i] = kv.second.base;
      ++i;
    }
    return true;
  }

  // GetItemPrice:取单个条目价格;无价格返回 false。对照 isteaminventory.h:GetItemPrice
  bool getItemPrice(MockItemDef def, uint64_t* pCurrent, uint64_t* pBase) const {
    auto it = prices_.find(def);
    if (it == prices_.end()) return false;
    if (pCurrent) *pCurrent = it->second.current;
    if (pBase) *pBase = it->second.base;
    return true;
  }

  // GenerateItems:生成一个或多个条目,产出新结果句柄。对照 isteaminventory.h:GenerateItems
  bool generateItems(MockInventoryResult* pResultHandle, const MockItemDef* pDefs,
                     const uint32_t* pQtys, uint32_t len) {
    if (!pResultHandle) return false;
    *pResultHandle = ++nextResult_;
    for (uint32_t i = 0; i < len; ++i) {
      MockItemDetails d;
      d.itemId = ++nextInstance_;
      d.definition = pDefs[i];
      d.quantity = pQtys ? static_cast<uint16_t>(pQtys[i]) : 1;
      d.flags = 0;
      items_.push_back(d);
      results_[*pResultHandle].push_back(d);
    }
    return true;
  }

  // StartPurchase:发起条目购买流程,返回订单号;真正授权在外部应答后落到
  // MicroTxnAuthorizationResponse_t。对照 isteaminventory.h:StartPurchase
  uint64_t startPurchase(const MockItemDef* pDefs, const uint32_t* pQtys, uint32_t len) {
    if (!pricesLoaded_) return 0;
    MockMicroTxnAuthorization pending{480, ++nextOrder_, 0};
    pendingOrders_[pending.orderId] = pending;
    PendingItems pi;
    pi.defs.assign(pDefs, pDefs + len);
    pi.qtys.assign(pQtys, pQtys + len);
    pi.len = len;
    pendingOrderItems_[pending.orderId] = pi;
    return pending.orderId;
  }

  // 处理用户授权应答(对应 MicroTxnAuthorizationResponse_t 回调):authorized=1
  // 才把订单条目落进库存,并产出结果句柄;拒绝则无条目。
  MockInventoryResult onAuthorization(const MockMicroTxnAuthorization& auth) {
    auto pit = pendingOrders_.find(auth.orderId);
    if (pit == pendingOrders_.end()) return kInvalidResult;
    if (pit->second.appId != auth.appId) return kInvalidResult;
    pendingOrders_.erase(pit);
    auto iit = pendingOrderItems_.find(auth.orderId);
    if (iit == pendingOrderItems_.end()) return kInvalidResult;
    auto items = iit->second;
    pendingOrderItems_.erase(iit);
    if (auth.authorized == 0) return kInvalidResult;
    MockInventoryResult handle = ++nextResult_;
    for (uint32_t i = 0; i < items.len; ++i) {
      MockItemDetails d;
      d.itemId = ++nextInstance_;
      d.definition = items.defs[i];
      d.quantity = static_cast<uint16_t>(items.qtys[i]);
      d.flags = 0;
      items_.push_back(d);
      results_[handle].push_back(d);
    }
    return handle;
  }

  bool getResultItems(MockInventoryResult handle, MockItemDetails* pOut,
                      uint32_t* pSize) const {
    auto it = results_.find(handle);
    if (it == results_.end()) return false;
    if (!pSize) return false;
    if (!pOut) {
      *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) pOut[i] = it->second[i];
    *pSize = static_cast<uint32_t>(it->second.size());
    return true;
  }

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

 private:
  struct Price {
    uint64_t base;
    uint64_t current;
  };
  struct PendingItems {
    std::vector<MockItemDef> defs;
    std::vector<uint32_t> qtys;
    uint32_t len;
  };
  std::map<MockItemDef, Price> prices_;
  std::vector<std::pair<MockItemDef, const char*>> defs_;
  std::vector<MockItemDetails> items_;
  std::map<MockInventoryResult, std::vector<MockItemDetails>> results_;
  std::map<uint64_t, MockMicroTxnAuthorization> pendingOrders_;
  std::map<uint64_t, PendingItems> pendingOrderItems_;
  bool pricesLoaded_ = false;
  MockInventoryResult nextResult_ = 0;
  MockItemInstanceID nextInstance_ = 1000;
  uint64_t nextOrder_ = 0;
};

}  // namespace steam_repro

int main() {
  using namespace steam_repro;

  MockSteamInventory inv;

  // 1. 价格未拉取时不可见
  CHECK(inv.getNumItemsWithPrices() == 0);

  // 2. RequestPrices 后价格可见:只有 2 个条目带价(mock 数据)
  CHECK(inv.requestPrices() == kResultOK);
  CHECK(inv.getNumItemsWithPrices() == 2);

  // 3. GetItemsWithPrices:定义号 + 当前价 + 基础价
  MockItemDef defs[4] = {0};
  uint64_t cur[4] = {0};
  uint64_t base[4] = {0};
  CHECK(inv.getItemsWithPrices(defs, cur, base, 4));
  bool saw100 = false, saw101 = false;
  for (int i = 0; i < 2; ++i) {
    if (defs[i] == 100) {
      saw100 = true;
      CHECK(cur[i] == 99 && base[i] == 149);
    }
    if (defs[i] == 101) {
      saw101 = true;
      CHECK(cur[i] == 399 && base[i] == 399);
    }
  }
  CHECK(saw100 && saw101);

  // 4. GetItemPrice:有价条目返回 true 与正确价格
  uint64_t c = 0, b = 0;
  CHECK(inv.getItemPrice(100, &c, &b));
  CHECK(c == 99 && b == 149);

  // 5. GetItemPrice:无价条目返回 false
  CHECK(!inv.getItemPrice(102, &c, &b));

  // 6. GenerateItems:生成 2 件条目,实例 id 唯一且递增
  MockInventoryResult genHandle = kInvalidResult;
  const MockItemDef genDefs[2] = {100, 101};
  const uint32_t genQtys[2] = {1, 2};
  CHECK(inv.generateItems(&genHandle, genDefs, genQtys, 2));
  CHECK(genHandle != kInvalidResult);
  uint32_t genCount = 0;
  CHECK(inv.getResultItems(genHandle, nullptr, &genCount));
  CHECK(genCount == 2);
  MockItemDetails genOut[2] = {};
  CHECK(inv.getResultItems(genHandle, genOut, &genCount));
  CHECK(genOut[0].itemId < genOut[1].itemId);
  CHECK(genOut[0].quantity == 1 && genOut[1].quantity == 2);

  // 7. StartPurchase 在价格未拉取时被拒
  MockSteamInventory noPrice;
  CHECK(noPrice.startPurchase(genDefs, genQtys, 2) == 0);

  // 8. StartPurchase 发起订单:初始未授权
  uint64_t orderId = inv.startPurchase(genDefs, genQtys, 2);
  CHECK(orderId != 0);

  // 9. 用户拒绝授权:不产出条目
  MockMicroTxnAuthorization denied{480, orderId, 0};
  CHECK(inv.onAuthorization(denied) == kInvalidResult);
  CHECK(inv.inventorySize() == 2);  // 只有第 6 步生成的 2 件

  // 10. 授权成功:订单条目落进库存并产出结果句柄
  uint64_t order2 = inv.startPurchase(genDefs, genQtys, 2);
  CHECK(order2 != 0 && order2 != orderId);
  MockMicroTxnAuthorization okAuth{480, order2, 1};
  MockInventoryResult buyHandle = inv.onAuthorization(okAuth);
  CHECK(buyHandle != kInvalidResult);
  uint32_t buyCount = 0;
  CHECK(inv.getResultItems(buyHandle, nullptr, &buyCount));
  CHECK(buyCount == 2);
  MockItemDetails buyOut[2] = {};
  CHECK(inv.getResultItems(buyHandle, buyOut, &buyCount));
  CHECK(buyOut[0].definition == 100 && buyOut[1].definition == 101);
  CHECK(inv.inventorySize() == 4);

  // 11. 错误 AppID 的授权应答不生效
  uint64_t order3 = inv.startPurchase(genDefs, genQtys, 1);
  MockMicroTxnAuthorization wrongApp{481, order3, 1};
  CHECK(inv.onAuthorization(wrongApp) == kInvalidResult);

  return lab::report("13-2 微交易与资产经济");
}

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

小结

  • 条目生成 GenerateItems 是原型工具,生产发放走 partner 工具;生成以「定义 + 数量」成对输入。
  • 价格是服务端配置:RequestPrices 拉取、GetItemPrice 读当前价/基础价,客户端不写死货币数字。
  • 购买 StartPurchase 只发起流程,授权与否由 Steam 判定;MicroTxnAuthorizationResponse_t 的 m_bAuthorized 决定是否落库。
  • 订单号是幂等键:同一订单不可重复发资产。

阅读导航:上一节:13.1 库存机制 · 下一节:13.3 库存的商业模型 。

继续阅读

探索更多技术文章

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

全部文章 返回首页

「books」更多文章

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