《Steam 游戏平台:开发与商业化》12.1 回调机制

Steamworks 的事件是回调驱动:按 callback id 注册监听,SteamAPI_RunCallbacks 泵出排队事件。本节讲回调注册/注销、FIFO 派发、客户端与游戏服务器两套队列、手动分发模式的工程语义,lab 用 C++ mock 验证注册、派发与队列分离。

12.1 回调机制

前面每一章都在用回调(ValidateAuthTicketResponse_t、GSStatsReceived_t、GlobalStatsReceived_t……),这一节把它们背后的机制讲透:Steamworks 的事件模型是回调驱动——Steam 客户端把事件排队,游戏在自己的循环里调 SteamAPI_RunCallbacks() 把它们泵出来分发给监听者。接入工程要理解注册/注销、派发时机、两套队列(客户端 vs 游戏服务器)与手动分发模式。

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

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

  • Steam 发行专题 (操作手册)讲「后台配置事件订阅」;本节讲「回调在游戏循环里怎么被分发」。
  • 卷一《平台机制与商店》讲平台机制;本节把「事件」落成回调注册与派发的工程口径。
  • lab 用纯 C++ 复现回调注册/注销、FIFO 派发与队列分离,不依赖 Steam 客户端运行。

回调的消息结构:CallbackMsg_t

Steam 把待分发的事件封装成一个消息结构。SDK v1.65 的 CallbackMsg_t:

// steam_api_internal.h:CallbackMsg_t(SDK v1.65 头文件摘录,已删减)
struct CallbackMsg_t
{
	HSteamUser m_hSteamUser; // Specific user to whom this callback applies.
	int m_iCallback; // Callback identifier.  (Corresponds to the k_iCallback enum in the callback structure.)
	uint8 *m_pubParam; // Points to the callback structure
	int m_cubParam; // Size of the data pointed to by m_pubParam
};

工程语义:

  1. m_iCallback 是回调 id,即回调结构里的 k_iCallback:每个回调结构体用 enum { k_iCallback = <base> + <offset> } 声明自己的唯一 id。id 的基址按接口域分区(k_iSteamUserCallbacks = 100、k_iSteamGameServerCallbacks = 200、k_iSteamFriendsCallbacks = 300、k_iSteamAppsCallbacks = 1000、k_iSteamUserStatsCallbacks = 1100……)——这是回调 id 永远唯一的机制保证。
  2. m_pubParam/m_cubParam 是指向回调结构的指针与大小:分发器按 m_iCallback 找监听,把 m_pubParam 强转成对应结构体类型交给处理函数。id 一旦注册错位,强转就错——所以回调 id 的一致性检查是必要的。
  3. m_hSteamUser 标记回调归属的用户:多用户管道(steam pipe)场景下,不同用户的回调由不同句柄区分。工程上处理多用户时不能只看回调内容,还要看归属句柄。

注册与注销:监听的生命周期

监听器用 CCallbackBase 派生对象向 Steam 登记:

// steam_api_internal.h:回调注册(SDK v1.65 头文件摘录,已删减)
S_API void S_CALLTYPE SteamAPI_RegisterCallback( class CCallbackBase *pCallback, int iCallback );
S_API void S_CALLTYPE SteamAPI_UnregisterCallback( class CCallbackBase *pCallback );

工程语义:

  1. 注册发生在对象构造时,注销在析构时:STEAM_CALLBACK 宏声明的成员变量在构造时自动 SteamAPI_RegisterCallback、析构时自动注销。用 STEAM_CALLBACK_MANUAL 则要自己调 Register/Unregister。工程上若手动管理,注销必须与注册对称,否则析构后回调仍会派发进已死对象。
  2. 同一回调 id 可以有多个监听器:一个事件通知多份逻辑(UI 更新 + 数据落盘 + 埋点)是常见用法。注册是追加式,不是覆盖式。
  3. 注销按对象、不按 id:SteamAPI_UnregisterCallback 收的是监听器对象指针,事件到来时不再派发给它。注销一个回调 id 的全部监听器,要么逐个注销对象,要么(工程侧)自己维护注册表。

派发:RunCallbacks 与两套队列

排队的事件不会自动到达——游戏必须在自己的主循环里主动泵取。SDK v1.65 的入口:

// steam_api_common.h:回调泵(SDK v1.65 头文件摘录,已删减)
// Dispatch all queued Steamworks callbacks.
// This is safe to call from multiple threads simultaneously,
// but if you choose to do this, callback code could be executed on any thread.
S_API void S_CALLTYPE SteamAPI_RunCallbacks();

// Dispatch callbacks relevant to the gameserver client and interfaces.
// To register for these, you need to use STEAM_GAMESERVER_CALLBACK.
S_API void S_CALLTYPE SteamGameServer_RunCallbacks();

工程语义:

  1. SteamAPI_RunCallbacks() 是客户端事件泵,SteamGameServer_RunCallbacks() 是游戏服务器事件泵:两套队列按回调的注册来源分拣——普通回调走前者,STEAM_GAMESERVER_CALLBACK 注册的走后者。游戏服务器进程要同时泵两套,别只泵一套导致事件滞留。
  2. 泵的时机在主循环里,频率自己定:注释明说它可以从多线程同时调,但那样回调可能在任何线程执行。工程上默认「主线程定时泵」,工作线程要做内存清理就调 SteamAPI_ReleaseCurrentThreadMemory。
  3. 泵是 FIFO 的:先排队的事件先分发。依赖事件顺序的逻辑(比如「连接成功」必须在「认证结果」之前)能成立,前提是同一管道内的 FIFO 不被破坏。
  4. 泵是拉模型,不是推模型:事件在 Steam 客户端里排队,直到游戏调 RunCallbacks 才被取出分发。游戏阻塞太久(比如每帧只泵一次、帧又很长)会延迟事件到达——工程上对时间敏感的回调要保证泵的频度。

手动分发模式

对「不用 SteamAPI_RunCallbacks、自己控制回调循环」的集成(比如嵌入非游戏主循环),SDK 提供手动分发:

// steam_api.h:手动分发(SDK v1.65 头文件摘录,已删减)
S_API void S_CALLTYPE SteamAPI_ManualDispatch_RunFrame( HSteamPipe hSteamPipe );
S_API bool S_CALLTYPE SteamAPI_ManualDispatch_GetNextCallback( HSteamPipe hSteamPipe, CallbackMsg_t *pCallbackMsg );
S_API void S_CALLTYPE SteamAPI_ManualDispatch_FreeLastCallback( HSteamPipe hSteamPipe );

工程语义:

  1. 手动分发 = RunFrame + 逐个 GetNextCallback 取:每次循环推进管道帧,然后循环取回调处理。文档模板在 steam_api.h 里示范了完整循环:RunFrame → while GetNextCallback → 按 callback.m_iCallback 分发 → FreeLastCallback。
  2. FreeLastCallback 必须成对调用:取到一个回调处理完,必须先 FreeLastCallback 才能取下一个——文档注释强调这一点。漏掉会导致回调累积、内存泄漏。
  3. 手动模式与自动泵互斥:同一管道不能同时用 SteamAPI_RunCallbacks 和手动分发。工程上要在初始化时选一条路走到底,混用会重复分发或漏分发。下面 lab 用 manualMode_ 开关复现这个互斥。

接口签名对照

头文件条目语义
steam_api_internal.hCallbackMsg_t排队回调的消息结构(id/参数/归属用户)
steam_api_internal.hSteamAPI_RegisterCallback注册监听(对象构造时自动)
steam_api_internal.hSteamAPI_UnregisterCallback注销监听(对象析构时自动)
steam_api_common.hSteamAPI_RunCallbacks客户端事件泵(FIFO,主循环调用)
steam_api_common.hSteamGameServer_RunCallbacks游戏服务器事件泵
steam_api.hSteamAPI_ManualDispatch_*手动分发模式(RunFrame/GetNextCallback/FreeLastCallback)
steam_api_internal.h回调基址常量k_iSteamUserCallbacks=100 / GameServer=200 / Friends=300 / Apps=1000 / UserStats=1100

数据口径与来源

  • CallbackMsg_t 字段、注册/注销签名、泵签名、手动分发签名、回调基址常量:SDK v1.65 public/steam/steam_api_common.h、steam_api_internal.h、steam_api.h 可实证(本机镜像已核对)。
  • 「同一回调可多监听」「泵是多线程安全但回调可能跑在任意线程」「FreeLastCallback 必须成对」:头文件注释明文。
  • 回调的实际触发频率、泵的推荐频度:工程经验口径,官方不约束,以自身性能预算为准。

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

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

下面的仿真复现「回调机制」的工程语义:按 callback id 注册/注销监听、同一回调多监听、FIFO 派发、客户端与游戏服务器两套队列独立泵取、手动分发模式禁用自动泵。它与 src/12-1-callback-mechanics.cpp 逐字节一致,mock 接口签名对照 SDK v1.65 头文件:

// file: src/12-1-callback-mechanics.cpp
// tier: L1
// verify: clang++ -std=c++20 -Wall -I. src/12-1-callback-mechanics.cpp -o bin/12-1-callback-mechanics && ./bin/12-1-callback-mechanics
//
// mock:复现回调机制——按 callback id 注册/注销监听、FIFO 派发、
// 客户端与游戏服务器两套队列(RunCallbacks / SteamGameServer_RunCallbacks)、
// 手动分发互斥、析构自动注销。
// 签名对照 SDK v1.65 steam_api_common.h / steam_api_internal.h,非 Valve 实现。
#include "verify.h"

#include <cstdint>
#include <functional>
#include <string>
#include <unordered_map>
#include <vector>

namespace steam_repro {

// CallbackMsg_t 语义:回调标识 + 参数指针 + 参数长度(steam_api_internal.h)
struct MockCallbackMsg {
  int callbackId;
  std::string payload;
  bool gameServer;
};

class MockCallbackSystem {
 public:
  using Handler = std::function<void(const std::string&)>;

  // SteamAPI_RegisterCallback:同一回调允许多个监听
  void registerCallback(int cb, Handler h) { handlers_[cb].push_back(std::move(h)); }

  // SteamAPI_UnregisterCallback:按「回调 id」注销全部监听
  void unregisterAll(int cb) { handlers_.erase(cb); }

  // 入队一个回调事件(客户端或游戏服务器管道的消息)
  void enqueue(int cb, const std::string& payload, bool gameServer) {
    queued_.push_back({cb, payload, gameServer});
  }

  // SteamAPI_RunCallbacks:泵出所有客户端回调;手动分发模式下禁用
  size_t runCallbacks() {
    if (manualMode_) return 0;
    return dispatchQueue(false);
  }

  // SteamGameServer_RunCallbacks:泵出游戏服务器回调
  size_t runGameServerCallbacks() { return dispatchQueue(true); }

  void enableManualDispatch() { manualMode_ = true; }

  size_t delivered() const { return delivered_; }
  size_t pendingCount() const { return queued_.size(); }

 private:
  size_t dispatchQueue(bool gs) {
    size_t n = 0;
    size_t i = 0;
    while (i < queued_.size()) {
      const MockCallbackMsg& msg = queued_[i];
      if (msg.gameServer != gs) {
        ++i;
        continue;
      }
      auto it = handlers_.find(msg.callbackId);
      if (it != handlers_.end()) {
        for (const auto& h : it->second) {
          h(msg.payload);
          ++delivered_;
        }
        ++n;
      }
      queued_.erase(queued_.begin() + static_cast<long>(i));
    }
    return n;
  }

  bool manualMode_ = false;
  size_t delivered_ = 0;
  std::unordered_map<int, std::vector<Handler>> handlers_;
  std::vector<MockCallbackMsg> queued_;
};

}  // namespace steam_repro

int main() {
  using namespace steam_repro;
  MockCallbackSystem sys;
  int hits[3] = {0, 0, 0};

  // 1. 注册两个回调监听
  sys.registerCallback(1001, [&](const std::string&) { ++hits[0]; });
  sys.registerCallback(1002, [&](const std::string& s) { hits[1] += static_cast<int>(s.size()); });

  // 2. 同一回调注册第二个监听器
  sys.registerCallback(1001, [&](const std::string&) { ++hits[2]; });

  // 3. 空队列 pump 无派发
  CHECK(sys.runCallbacks() == 0);
  CHECK(sys.delivered() == 0);

  // 4. 入队并 pump:FIFO 派发
  sys.enqueue(1001, "evt1", false);
  sys.enqueue(1002, "abc", false);
  CHECK(sys.runCallbacks() == 2);
  CHECK(hits[0] == 1);
  CHECK(hits[1] == 3);
  CHECK(hits[2] == 1);

  // 5. 注销 1001 后不再派发
  sys.unregisterAll(1001);
  sys.enqueue(1001, "again", false);
  sys.enqueue(1002, "x", false);
  CHECK(sys.runCallbacks() == 1);  // 只有 1002 派发
  CHECK(hits[0] == 1);
  CHECK(hits[2] == 1);

  // 6. 手动分发模式禁用自动 pump
  MockCallbackSystem manual;
  manual.enableManualDispatch();
  manual.registerCallback(2001, [&](const std::string&) { ++hits[0]; });
  manual.enqueue(2001, "m", false);
  CHECK(manual.runCallbacks() == 0);

  // 7. 游戏服务器回调独立泵
  MockCallbackSystem gs;
  gs.registerCallback(2010, [&](const std::string&) { ++hits[0]; });
  gs.enqueue(2010, "gs", true);
  CHECK(gs.runGameServerCallbacks() == 1);
  CHECK(gs.runCallbacks() == 0);  // 队列已清空

  // 8. 客户端系统累计派发次数
  CHECK(sys.delivered() == 4);

  return lab::report("12-1 回调机制");
}

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

小结

  • Steamworks 是回调驱动:事件排队,SteamAPI_RunCallbacks() 泵出分发;回调 id 按接口域分区保证唯一。
  • 注册/注销随监听对象构造/析构自动进行,同一回调 id 可有多监听,注销按对象不按 id。
  • 客户端与游戏服务器是两套队列,分别由 SteamAPI_RunCallbacks 与 SteamGameServer_RunCallbacks 泵取。
  • 手动分发模式(RunFrame + GetNextCallback + FreeLastCallback)与自动泵互斥,不能混用。

阅读导航:上一节:11.3 测试策略与数据 · 下一节:12.2 异步操作模式 。

继续阅读

探索更多技术文章

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

全部文章 返回首页

「books」更多文章

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