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;
工程语义:
- Init/Shutdown 成对,句柄查询放启动期。头文件多次强调 action set/digital action 句柄应在初始化时查询并保存(「All action handles should be queried during initialization for performance reasons」),运行时不再重复查字符串。
bExplicitlyCallRunFrame决定更新节奏。为 false 时由SteamAPI_RunCallbacks()顺带更新;为 true 时游戏每帧手动RunFrame,换取最低延迟(头文件注释说这样能把延迟压到最低)。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;
};
工程语义:
- 动作集是「场景」的输入切换。菜单、步行、驾驶是不同动作集;游戏按状态切换动作集,同一设备上的键位映射随之变化。
ActivateActionSet很便宜,头文件建议直接放进状态循环反复调用。 InputDigitalActionData_t分bState与bActive。bActive表示该动作在当前动作集里是否可用(有没有绑定);bState是当前是否按下。判断「按下了跳跃」必须同时看bActive——否则在没绑定的动作集里也可能读到状态。- 同名句柄查询幂等。启动期多次查询同一名字返回同一句柄,这是「启动期缓存」的前提;mock 里要断言幂等性。
- 动作状态的语义是「绑定后的当前值」。玩家改绑定、换设备,
GetDigitalActionData返回的永远是「当前设备上的当前动作值」,游戏逻辑不用知道具体是哪个物理键。
动作集切换与多控制器
// isteaminput.h:ActivateActionSet(SDK v1.65 头文件摘录,已删减)
virtual void ActivateActionSet( InputHandle_t inputHandle, InputActionSetHandle_t actionSetHandle ) = 0;
工程语义:
- 每个控制器独立持有当前动作集。本地多人、双控制器时,各控制器可处于不同动作集;游戏按
InputHandle_t分别读取。 - 切换后旧动作集的动作
bActive变 false。这天然实现了「菜单里跳跃键无效」——无需在游戏逻辑里额外判断当前状态,直接看bActive即可。 - 动作原点(origins)用于 UI 提示。需要显示「按 A」这种图标时用
GetDigitalActionOrigins/GetGlyphForActionOrigin,把原点枚举转成当前设备的字形——这也是「不识别设备型号、只按动作抽象」的延续。
接口签名对照
| 头文件 | 条目 | 语义 |
|---|---|---|
isteaminput.h | Init(bool) | 启用本接口(false=RunCallbacks 顺带更新) |
isteaminput.h | Shutdown() | 结束使用本接口 |
isteaminput.h | GetConnectedControllers(out[]) | 枚举已连接控制器(先 RunFrame) |
isteaminput.h | GetActionSetHandle(name) | 动作集句柄(启动期查询并缓存) |
isteaminput.h | GetDigitalActionHandle(name) | 数字动作句柄 |
isteaminput.h | GetDigitalActionData(handle, action) | 数字动作状态(bState/bActive) |
isteaminput.h | ActivateActionSet(handle, set) | 切换控制器当前动作集 |
isteaminput.h | GetCurrentActionSet(handle) | 读取当前动作集 |
数据口径与来源
- 接口签名、
InputDigitalActionData_t字段、STEAM_INPUT_MAX_COUNT=16:SDK v1.65public/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 平台服务集成策略 。
继续阅读
探索更多技术文章
浏览归档,发现更多关于系统设计、工具链和工程实践的内容。