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;
工程语义:
- 生产环境不靠
GenerateItems发资产。正式发放要走 partner 工具或 Web API(登录后可见),GenerateItems在头文件里被限定为 prototyping。接入工程应把它留在开发构建里,用编译开关隔离。 - 生成是「定义 + 数量」成对输入的。
pArrayItemDefs与punArrayQuantity等长,表示每种定义生成几件;返回的结果集里每个实例有全局唯一 ID(mock 里可断言实例 ID 单调递增)。 - 资产经济里「物品从哪来」必须可审计。掉落、促销、购买各有入口(
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;
工程语义:
- 价格是「当前价 + 基础价」双轨。
pCurrentPrice是玩家本地货币下的实时价,pBasePrice是基础价——促销折扣就是两者之差。UI 显示「划线价 + 现价」时读这两个字段,而不是自己猜折扣。 - 先
RequestPrices再读价格。GetNumItemsWithPrices/GetItemsWithPrices/GetItemPrice都依赖价格已拉取;本地货币由 Steam 换算,客户端不自己做汇率。 - 价格是配置而非代码。改价不需要发客户端补丁,接入工程应把价格视为服务端数据,避免在代码里硬编码任何货币数字。
购买与授权: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
};
工程语义(也是本节最重要的机制判断):
- 授权位
m_bAuthorized是 Steam 判定的。StartPurchase只发起流程,扣不扣款由 Steam 的微交易系统决定;客户端收到m_bAuthorized == 0就绝不能发放物品。 - 订单与条目一一对应。回调里的
m_ulOrderID要和SteamInventoryStartPurchaseResult_t里的对上,接入工程用订单号做幂等:同一订单被重复回调也不能重复发资产。 - 真正的购买触发是 partner 工具语义。客户端
StartPurchase面向「游戏内商店」;后端驱动的微交易(如网页/移动端触发)属于 partner/Web API 侧,正文只讲机制判断,不写后台点击步骤。
接口签名对照
| 头文件 | 条目 | 语义 |
|---|---|---|
isteaminventory.h | GenerateItems(...) | 生成条目(仅原型/发行商组账号可用) |
isteaminventory.h | RequestPrices() | 异步请求全部条目价格 |
isteaminventory.h | GetNumItemsWithPrices() | 有价条目数量(需先 RequestPrices) |
isteaminventory.h | GetItemPrice(def, cur, base) | 单条目当前价/基础价 |
isteaminventory.h | StartPurchase(defs, qtys, len) | 发起游戏内购买流程 |
isteaminventory.h | SteamInventoryStartPurchaseResult_t | 购买初始化结果(订单/交易号) |
isteamuser.h | MicroTxnAuthorizationResponse_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 库存的商业模型 。
继续阅读
探索更多技术文章
浏览归档,发现更多关于系统设计、工具链和工程实践的内容。