《Steam 游戏平台:开发与商业化》14.2 手柄与输入

本节接 ISteamInput 手柄与输入机制:Init 生命周期、GetConnectedControllers 枚举、GetActionSetHandle/GetDigitalActionHandle 句柄查询、ActivateActionSet 动作集切换与 GetDigitalActionData 数字动作状态。lab 用 C++ mock 控制器连接、动作集/数字动作句柄与按键状态,验证同名句柄幂等与动作集切换后的可用性。

14.2 手柄与输入

上一节讲了「运行在什么环境」,这一节讲「怎么读玩家的手柄输入」。ISteamInput 的核心理念是动作(Action)抽象:游戏不读「Xbox 的 A 键」「PS 的 X 键」,而是读「跳跃(jump)」「攻击(attack)」这些动作,绑定由 Steam 客户端在后台配置里完成。这样一套动作定义就能覆盖 Xbox、PlayStation、Switch、Steam Deck 等数百种设备——头文件开头就写明它支持「over three hundred devices」。

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

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

  • Steam 发行专题 (操作手册)讲「提交控制器模板、配置动作集」;本节讲「代码里用 ISteamInput 读动作的接口语义」。
  • 卷一《平台机制与商店》讲平台机制;本节给动作抽象、句柄查询、动作集切换的接口位。
  • 14.1 的 IsSteamInBigPictureMode/GetCurrentBatteryPower 与本节配合:判断何时用手柄、何时降级功耗。

生命周期与设备枚举

ISteamInput 要求显式 Init/Shutdown;GetConnectedControllers 在 RunFrame 之后才返回设备:

// isteaminput.h:Init / GetConnectedControllers(SDK v1.65 头文件摘录,已删减)
virtual bool Init( bool bExplicitlyCallRunFrame ) = 0;

virtual int GetConnectedControllers( STEAM_OUT_ARRAY_COUNT( STEAM_INPUT_MAX_COUNT, Receives list of connected controllers ) InputHandle_t *handlesOut ) = 0;

工程语义:

  1. Init/Shutdown 成对,句柄查询放启动期。头文件多次强调 action set/digital action 句柄应在初始化时查询并保存(「All action handles should be queried during initialization for performance reasons」),运行时不再重复查字符串。
  2. bExplicitlyCallRunFrame 决定更新节奏。为 false 时由 SteamAPI_RunCallbacks() 顺带更新;为 true 时游戏每帧手动 RunFrame,换取最低延迟(头文件注释说这样能把延迟压到最低)。
  3. GetConnectedControllers 返回数量并写句柄。数组应至少 STEAM_INPUT_MAX_COUNT(16)大小;返回数量是「已连接并启用」的控制器数。注意 RunFrame 必须先调用——注释明文「must be called from somewhere before GetConnectedControllers will return any handles」。

动作抽象:动作集与数字动作

游戏内逻辑不依赖具体按键,而是依赖「动作集(Action Set)」和「动作(Action)」两层句柄:

// isteaminput.h:GetActionSetHandle / GetDigitalActionHandle / GetDigitalActionData(SDK v1.65 头文件摘录,已删减)
virtual InputActionSetHandle_t GetActionSetHandle( const char *pszActionSetName ) = 0;
virtual InputDigitalActionHandle_t GetDigitalActionHandle( const char *pszActionName ) = 0;
virtual InputDigitalActionData_t GetDigitalActionData( InputHandle_t inputHandle, InputDigitalActionHandle_t digitalActionHandle ) = 0;

struct InputDigitalActionData_t
{
	bool bState;
	bool bActive;
};

工程语义:

  1. 动作集是「场景」的输入切换。菜单、步行、驾驶是不同动作集;游戏按状态切换动作集,同一设备上的键位映射随之变化。ActivateActionSet 很便宜,头文件建议直接放进状态循环反复调用。
  2. InputDigitalActionData_t 分 bState 与 bActive。bActive 表示该动作在当前动作集里是否可用(有没有绑定);bState 是当前是否按下。判断「按下了跳跃」必须同时看 bActive——否则在没绑定的动作集里也可能读到状态。
  3. 同名句柄查询幂等。启动期多次查询同一名字返回同一句柄,这是「启动期缓存」的前提;mock 里要断言幂等性。
  4. 动作状态的语义是「绑定后的当前值」。玩家改绑定、换设备,GetDigitalActionData 返回的永远是「当前设备上的当前动作值」,游戏逻辑不用知道具体是哪个物理键。

动作集切换与多控制器

// isteaminput.h:ActivateActionSet(SDK v1.65 头文件摘录,已删减)
virtual void ActivateActionSet( InputHandle_t inputHandle, InputActionSetHandle_t actionSetHandle ) = 0;

工程语义:

  1. 每个控制器独立持有当前动作集。本地多人、双控制器时,各控制器可处于不同动作集;游戏按 InputHandle_t 分别读取。
  2. 切换后旧动作集的动作 bActive 变 false。这天然实现了「菜单里跳跃键无效」——无需在游戏逻辑里额外判断当前状态,直接看 bActive 即可。
  3. 动作原点(origins)用于 UI 提示。需要显示「按 A」这种图标时用 GetDigitalActionOrigins/GetGlyphForActionOrigin,把原点枚举转成当前设备的字形——这也是「不识别设备型号、只按动作抽象」的延续。

接口签名对照

头文件条目语义
isteaminput.hInit(bool)启用本接口(false=RunCallbacks 顺带更新)
isteaminput.hShutdown()结束使用本接口
isteaminput.hGetConnectedControllers(out[])枚举已连接控制器(先 RunFrame)
isteaminput.hGetActionSetHandle(name)动作集句柄(启动期查询并缓存)
isteaminput.hGetDigitalActionHandle(name)数字动作句柄
isteaminput.hGetDigitalActionData(handle, action)数字动作状态(bState/bActive)
isteaminput.hActivateActionSet(handle, set)切换控制器当前动作集
isteaminput.hGetCurrentActionSet(handle)读取当前动作集

数据口径与来源

  • 接口签名、InputDigitalActionData_t 字段、STEAM_INPUT_MAX_COUNT=16:SDK v1.65 public/steam/isteaminput.h 可实证(本机镜像已核对)。
  • 「句柄启动期查询缓存」「先 RunFrame 再枚举」「动作集切换很便宜」:头文件注释明文。
  • 具体按键布局、绑定方案、设备支持清单:partner 登录后文档口径,以官方当前为准。

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

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

下面的仿真复现「手柄与输入」的工程语义:Init/Shutdown、GetConnectedControllers 枚举、GetActionSetHandle/GetDigitalActionHandle 同名幂等、ActivateActionSet/GetCurrentActionSet 切换、GetDigitalActionData 的 bState/bActive 语义与多控制器独立状态。它与 src/14-2-input-controller.cpp 逐字节一致,mock 接口签名对照 SDK v1.65 头文件:

// file: src/14-2-input-controller.cpp
// tier: L1
// verify: clang++ -std=c++20 -Wall -I. src/14-2-input-controller.cpp -o bin/14-2-input-controller && ./bin/14-2-input-controller
//
// mock:复现 ISteamInput 手柄与输入机制的工程语义——Init/Shutdown、
// GetConnectedControllers 枚举、GetActionSetHandle/GetDigitalActionHandle
// 句柄查询、ActivateActionSet/GetCurrentActionSet 动作集切换、
// GetDigitalActionData 数字动作状态。
// 签名对照 SDK v1.65 isteaminput.h,非 Valve 实现。
#include "verify.h"

#include <cstdint>
#include <map>
#include <set>
#include <string>
#include <vector>

namespace steam_repro {

using MockInputHandle = uint64_t;
using MockActionSetHandle = uint64_t;
using MockDigitalActionHandle = uint64_t;

// InputDigitalActionData_t 对照 isteaminput.h
struct MockInputDigitalActionData {
  bool bState;  // 当前是否按下
  bool bActive; // 当前动作集里是否可用
};

class MockSteamInput {
 public:
  // Init:bExplicitlyCallRunFrame=true 表示需要手动 RunFrame;
  // 这里统一在 getConnectedControllers/getDigitalActionData 前刷新状态。
  // 对照 isteaminput.h:Init
  bool init(bool /*bExplicitlyCallRunFrame*/) {
    inited_ = true;
    return true;
  }

  // Shutdown:结束使用本接口。对照 isteaminput.h:Shutdown
  bool shutdown() {
    inited_ = false;
    controllers_.clear();
    return true;
  }

  // GetConnectedControllers:把已连接的控制器句柄写入数组,返回数量。
  // 对照 isteaminput.h:GetConnectedControllers
  int getConnectedControllers(MockInputHandle* handlesOut, uint32_t maxCount) const {
    if (!inited_) return 0;
    uint32_t n = static_cast<uint32_t>(controllers_.size());
    if (handlesOut && maxCount >= n) {
      for (uint32_t i = 0; i < n; ++i) handlesOut[i] = controllers_[i];
    }
    return static_cast<int>(n);
  }

  // GetActionSetHandle:查询动作集句柄(启动期查询一次并保存)。
  // 对照 isteaminput.h:GetActionSetHandle
  MockActionSetHandle getActionSetHandle(const std::string& name) {
    auto it = actionSets_.find(name);
    if (it != actionSets_.end()) return it->second;
    MockActionSetHandle h = ++nextActionSet_;
    actionSets_[name] = h;
    return h;
  }

  // GetDigitalActionHandle:查询数字动作句柄。对照 isteaminput.h:GetDigitalActionHandle
  MockDigitalActionHandle getDigitalActionHandle(const std::string& name) {
    auto it = digitalActions_.find(name);
    if (it != digitalActions_.end()) return it->second;
    MockDigitalActionHandle h = ++nextDigital_;
    digitalActions_[name] = h;
    return h;
  }

  // ActivateActionSet:切换指定控制器当前动作集(可重复调用)。
  // 对照 isteaminput.h:ActivateActionSet
  void activateActionSet(MockInputHandle handle, MockActionSetHandle setHandle) {
    currentActionSet_[handle] = setHandle;
  }

  // GetCurrentActionSet:读取当前动作集。对照 isteaminput.h:GetCurrentActionSet
  MockActionSetHandle getCurrentActionSet(MockInputHandle handle) const {
    auto it = currentActionSet_.find(handle);
    return it == currentActionSet_.end() ? 0 : it->second;
  }

  // GetDigitalActionData:读数字动作状态;仅当前动作集里的动作才 bActive。
  // 对照 isteaminput.h:GetDigitalActionData
  MockInputDigitalActionData getDigitalActionData(MockInputHandle handle,
                                                  MockDigitalActionHandle action) const {
    MockInputDigitalActionData d{false, false};
    auto it = controllerState_.find(handle);
    if (it == controllerState_.end()) return d;
    MockActionSetHandle active = currentActionSet_.count(handle) ? currentActionSet_.at(handle) : 0;
    auto actionIt = setActions_.find(active);
    if (actionIt == setActions_.end()) return d;
    if (actionIt->second.count(action) == 0) return d;  // 不在当前动作集
    d.bActive = true;
    d.bState = it->second.pressed.count(action) != 0;
    return d;
  }

  // ---- mock 辅助(非 SDK 接口):模拟设备连接/按键 ----
  void connect(MockInputHandle handle) {
    if (std::find(controllers_.begin(), controllers_.end(), handle) == controllers_.end()) {
      controllers_.push_back(handle);
    }
    controllerState_[handle] = {};
    currentActionSet_[handle] = 0;
  }
  void bind(MockActionSetHandle setHandle, MockDigitalActionHandle action) {
    setActions_[setHandle].insert(action);
  }
  void press(MockInputHandle handle, MockDigitalActionHandle action) {
    controllerState_[handle].pressed.insert(action);
  }
  void release(MockInputHandle handle, MockDigitalActionHandle action) {
    controllerState_[handle].pressed.erase(action);
  }

 private:
  struct CtrlState {
    std::set<MockDigitalActionHandle> pressed;
  };
  bool inited_ = false;
  std::vector<MockInputHandle> controllers_;
  std::map<std::string, MockActionSetHandle> actionSets_;
  std::map<std::string, MockDigitalActionHandle> digitalActions_;
  std::map<MockInputHandle, MockActionSetHandle> currentActionSet_;
  std::map<MockActionSetHandle, std::set<MockDigitalActionHandle>> setActions_;
  std::map<MockInputHandle, CtrlState> controllerState_;
  MockActionSetHandle nextActionSet_ = 0;
  MockDigitalActionHandle nextDigital_ = 0;
};

}  // namespace steam_repro

int main() {
  using namespace steam_repro;

  MockSteamInput input;

  // 1. 未 Init 前没有控制器
  MockInputHandle handles[2] = {0, 0};
  CHECK(input.getConnectedControllers(handles, 2) == 0);

  // 2. Init 成功
  CHECK(input.init(false));

  // 3. 连接 2 台控制器后枚举
  input.connect(1001);
  input.connect(1002);
  CHECK(input.getConnectedControllers(handles, 2) == 2);
  CHECK(handles[0] == 1001 && handles[1] == 1002);

  // 4. 句柄不足时不写入
  CHECK(input.getConnectedControllers(nullptr, 0) == 2);

  // 5. 动作集句柄查询:非零、同名幂等
  MockActionSetHandle menu = input.getActionSetHandle("Menu");
  MockActionSetHandle combat = input.getActionSetHandle("Combat");
  CHECK(menu != 0 && combat != 0);
  CHECK(menu != combat);
  CHECK(input.getActionSetHandle("Menu") == menu);

  // 6. 数字动作句柄查询:非零、同名幂等
  MockDigitalActionHandle jump = input.getDigitalActionHandle("jump");
  MockDigitalActionHandle attack = input.getDigitalActionHandle("attack");
  CHECK(jump != 0 && attack != 0);
  CHECK(jump != attack);
  CHECK(input.getDigitalActionHandle("jump") == jump);

  // 7. 默认动作集为空:未激活时无数据
  CHECK(input.getCurrentActionSet(1001) == 0);
  MockInputDigitalActionData idle = input.getDigitalActionData(1001, jump);
  CHECK(!idle.bActive && !idle.bState);

  // 8. 绑定 + 激活动作集后,动作可用但未按下
  input.bind(combat, jump);
  input.bind(combat, attack);
  input.activateActionSet(1001, combat);
  CHECK(input.getCurrentActionSet(1001) == combat);
  MockInputDigitalActionData up = input.getDigitalActionData(1001, jump);
  CHECK(up.bActive && !up.bState);

  // 9. 按下后 bState 为 true,释放后回 false
  input.press(1001, jump);
  CHECK(input.getDigitalActionData(1001, jump).bState);
  input.release(1001, jump);
  CHECK(!input.getDigitalActionData(1001, jump).bState);

  // 10. 切换动作集后,旧动作集中的动作不再 active
  input.activateActionSet(1001, menu);
  CHECK(input.getCurrentActionSet(1001) == menu);
  MockInputDigitalActionData afterSwitch = input.getDigitalActionData(1001, jump);
  CHECK(!afterSwitch.bActive);

  // 11. 另一台控制器状态独立
  input.activateActionSet(1002, combat);
  CHECK(input.getCurrentActionSet(1002) == combat);
  CHECK(input.getDigitalActionData(1002, jump).bActive);
  CHECK(input.getDigitalActionData(1001, jump).bActive == false);

  // 12. Shutdown 清理控制器
  CHECK(input.shutdown());
  CHECK(input.getConnectedControllers(handles, 2) == 0);

  return lab::report("14-2 手柄与输入");
}

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

小结

  • ISteamInput 用动作抽象覆盖数百种设备;句柄启动期查询并缓存。
  • Init(bExplicitlyCallRunFrame) 决定由 RunCallbacks 顺带更新还是手动 RunFrame 压延迟。
  • GetConnectedControllers 前必须先 RunFrame;bState/bActive 分开判断。
  • 动作集按场景切换,切换后旧动作 bActive=false;多控制器各自持有当前动作集。

阅读导航:上一节:14.1 平台工具机制 · 下一节:14.3 平台服务集成策略 。

继续阅读

探索更多技术文章

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

全部文章 返回首页

「books」更多文章

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