14.1 平台工具机制
前面各章解决「接入某个功能域」,这一节和下一节解决「运行在什么环境上」。ISteamUtils 是一组与具体功能无关的平台工具:当前 AppID、服务器时间、国家码、电量、硬件类型。它最典型的一个工程问题是:怎么判断游戏跑在 Steam Deck / Steam Machine 上、怎么选默认画质档。SDK v1.65 有一个明确的接口变更——IsRunningOnSteamDeck() 已被移除,硬件判定改用返回枚举的 IsRunningOnSteamHardware() 配合 IsRunningUnderProton()。
本卷所有接口口径以 Steamworks SDK v1.65(2026-07-23) 为准。本节摘录的签名对照该版本 public/steam/isteamutils.h。
本章与站内既有内容的分工
- Steam 发行专题 (操作手册)讲「后台填 Deck 兼容性、提交测试」;本节讲「代码里读平台状态的接口语义」。
- 卷一《平台机制与商店》讲平台机制;本节给
ISteamUtils的接口位:哪些是环境事实、哪些是配置。 - 14.2 讲手柄输入,14.3 讲平台服务依赖治理;本节是平台服务的「环境感知」底座。
环境事实:AppID、国家码与时间
ISteamUtils 提供一批只读环境事实,头文件注释把它们与「用户级数据」明确区分:
// isteamutils.h:基础工具方法(SDK v1.65 头文件摘录,已删减)
virtual uint32 GetSecondsSinceAppActive() = 0;
virtual uint32 GetServerRealTime() = 0;
virtual const char *GetIPCountry() = 0;
virtual uint32 GetAppID() = 0;
virtual uint8 GetCurrentBatteryPower() = 0;
工程语义:
GetAppID是运行环境的锚点。进程实际属于哪个 App 由 Steam 客户端决定(配合 steam_appid.txt 做开发),很多后续判断(DLC、统计、成就)都以它为根。mock 里应断言返回值与配置一致。GetServerRealTime是可信时间源。服务器时间(Unix 秒)用于活动截止、掉落冷却等对时敏感的判定——比客户端本机时钟更可靠。GetIPCountry返回 2 位 ISO 3166-1-alpha-2 国家码。地区化定价、合规开关常用它做入口判断;注意它是「IP 定位」结果,不一定是账号地区。GetCurrentBatteryPower用 255 表示交流供电。0..100 是剩余百分比;低电量是掌机/笔记本场景降级的重要输入(下一节详讲)。
硬件判定:v1.65 的接口变更
SDK v1.65 的头文件里已经找不到 IsRunningOnSteamDeck()。硬件判定收敛成 IsRunningOnSteamHardware()——它返回的是 ESteamHardwareType 枚举而不是布尔值:
// isteamutils.h:ESteamHardwareType / IsRunningOnSteamHardware(SDK v1.65 头文件摘录,已删减)
enum ESteamHardwareType
{
k_ESteamHardwareTypeNone = 0, // Not playing on a Steam hardware device
k_ESteamHardwareTypeSteamDeck = 1,
k_ESteamHardwareTypeSteamMachine = 2,
k_ESteamHardwareTypeSteamFrame = 3,
};
virtual ESteamHardwareType IsRunningOnSteamHardware() = 0;
工程语义:
- 别用旧接口判断 Deck。
IsRunningOnSteamDeck在 v1.65 已移除,写新代码必须用IsRunningOnSteamHardware() == k_ESteamHardwareTypeSteamDeck。头文件注释还强调:这个方法只用于「usage analytics, support, diagnostic 等非功能性决策」。 - 功能/能力决策要换别的接口。头文件列了一组替代:
GetSteamHardwareDefaultConfig()、IsSteamInBigPictureMode()、IsRunningUnderProton()、IsSteamRunningInVR()、GetCurrentBatteryPower()。也就是说:想选画质档用配置档接口,想判输入模式用 Big Picture,想判兼容层用 Proton——不要把「是不是 Deck」当作唯一信号。 - Deck 兼容层也要分。
IsRunningUnderProton()返回是否在 Proton 兼容层下运行。Deck 原生是 SteamOS,但也可能跑 Windows 游戏的 Proton;桌面 Linux 也常走 Proton。二者要分开判断:硬件类型决定形态,Proton 决定兼容层路径。
默认配置档:GetSteamHardwareDefaultConfig
选默认画质档的标准姿势是让 Steam 客户端给一个「配置档」,而不是自己枚举设备型号:
// isteamutils.h:GetSteamHardwareDefaultConfig / IsRunningUnderProton(SDK v1.65 头文件摘录,已删减)
virtual ESteamHardwareDefaultConfig GetSteamHardwareDefaultConfig() = 0;
virtual bool IsRunningUnderProton() = 0;
工程语义(头文件注释给了完整的选档步骤):
- 先取配置档,再映射到游戏预设。配置档可能是设备专属(
k_ESteamHardwareDefaultConfigSteamDeck)或通用档(Low/Medium/High/Max)。游戏把 Low/Medium/High/Max 映射到自己预设;预设数不足 4 个时允许多个档映射到同一预设。 - 配置档可被 partner 后台改写。发行商可以在 partner 站定制「某设备返回哪个档」,因此游戏不需要为未来新硬件重新编译——这正是用配置档而非型号枚举的核心价值。
- Proton 与电量是降级输入。Proton 下性能差异大,低电量要强制降档;本节 mock 用「配置档 → 预设 → 低电量兜底」三步演示,量级均为模型假设,非官方数值。
接口签名对照
| 头文件 | 条目 | 语义 |
|---|---|---|
isteamutils.h | GetAppID() | 当前进程 AppID |
isteamutils.h | GetIPCountry() | 2 位 ISO 3166-1-alpha-2 国家码 |
isteamutils.h | GetServerRealTime() | Steam 服务器 Unix 时间 |
isteamutils.h | GetSecondsSinceAppActive() | 进程激活以来秒数 |
isteamutils.h | GetCurrentBatteryPower() | 电量百分比;255=交流供电 |
isteamutils.h | IsRunningUnderProton() | 是否 Proton 兼容层运行 |
isteamutils.h | IsRunningOnSteamHardware() | 返回 ESteamHardwareType(v1.65 取代 IsRunningOnSteamDeck) |
isteamutils.h | GetSteamHardwareDefaultConfig() | 默认配置档(可被 partner 后台定制) |
数据口径与来源
- 接口签名、
ESteamHardwareType/ESteamHardwareDefaultConfig枚举:SDK v1.65public/steam/isteamutils.h可实证(本机镜像已核对,IsRunningOnSteamDeck已移除)。 - 「非功能性决策用 IsRunningOnSteamHardware、功能性决策用替代接口」:头文件注释明文。
- 电量阈值、Deck 预设映射、性能量级:模型假设,非官方数值;partner 后台对配置档的定制以官方当前为准。
以上接口口径撰写时对照 Steamworks SDK v1.65 头文件与 partner.steamgames.com 官方文档核对;登录后可见数据以官方当前为准。
可运行产物:C++ 最小验证
下面的仿真复现「平台工具机制」的工程语义:GetAppID/GetIPCountry/GetServerRealTime/GetSecondsSinceAppActive/GetCurrentBatteryPower 环境事实、IsRunningOnSteamHardware 返回 ESteamHardwareType(非布尔)、IsRunningUnderProton、GetSteamHardwareDefaultConfig 与配置档→预设→低电量兜底的选档链。它与 src/14-1-platform-utils-mechanics.cpp 逐字节一致,mock 接口签名对照 SDK v1.65 头文件:
// file: src/14-1-platform-utils-mechanics.cpp
// tier: L1
// verify: clang++ -std=c++20 -Wall -I. src/14-1-platform-utils-mechanics.cpp -o bin/14-1-platform-utils-mechanics && ./bin/14-1-platform-utils-mechanics
//
// mock:复现 ISteamUtils 平台工具机制的工程语义——GetAppID/GetIPCountry/
// GetServerRealTime/GetSecondsSinceAppActive/GetCurrentBatteryPower、
// IsRunningUnderProton、IsRunningOnSteamHardware(返回 ESteamHardwareType,
// SDK v1.65 已移除 IsRunningOnSteamDeck)、GetSteamHardwareDefaultConfig 与
// 默认配置档选择。
// 签名对照 SDK v1.65 isteamutils.h,非 Valve 实现。
#include "verify.h"
#include <cstdint>
#include <string>
namespace steam_repro {
// ESteamHardwareType 对照 isteamutils.h
enum MockHardwareType {
kHardwareNone = 0,
kHardwareSteamDeck = 1,
kHardwareSteamMachine = 2,
kHardwareSteamFrame = 3,
};
// ESteamHardwareDefaultConfig 对照 isteamutils.h
enum MockHardwareDefaultConfig {
kConfigNone = 0,
kConfigLow = 1,
kConfigMedium = 2,
kConfigHigh = 3,
kConfigMax = 4,
kConfigSteamDeck = 5,
kConfigSteamMachine = 6,
kConfigSteamFrame = 7,
};
// 游戏侧默认画质预设(mock 模型,非官方数值)
enum MockPreset { kPresetLow = 0, kPresetMedium = 1, kPresetHigh = 2, kPresetMax = 3 };
class MockSteamUtils {
public:
MockSteamUtils(uint32_t appId, const char* ipCountry, uint32_t serverTime,
uint8_t battery, bool proton, MockHardwareType hw)
: appId_(appId), ipCountry_(ipCountry), serverTime_(serverTime),
battery_(battery), proton_(proton), hw_(hw) {}
// GetAppID:当前进程的 AppID。对照 isteamutils.h:GetAppID
uint32_t getAppID() const { return appId_; }
// GetIPCountry:2 位 ISO 3166-1-alpha-2 国家码(mock 数据)。
// 对照 isteamutils.h:GetIPCountry
const char* getIPCountry() const { return ipCountry_; }
// GetServerRealTime:Steam 服务器 Unix 时间。对照 isteamutils.h:GetServerRealTime
uint32_t getServerRealTime() const { return serverTime_; }
// GetSecondsSinceAppActive:本进程激活以来的秒数(每次调用递增,mock 行为)。
// 对照 isteamutils.h:GetSecondsSinceAppActive
uint32_t getSecondsSinceAppActive() { return activeSeconds_++; }
// GetCurrentBatteryPower:0..100,255 表示交流供电。对照 isteamutils.h:GetCurrentBatteryPower
uint8_t getCurrentBatteryPower() const { return battery_; }
// IsRunningUnderProton:Proton 兼容层下运行。对照 isteamutils.h:IsRunningUnderProton
bool isRunningUnderProton() const { return proton_; }
// IsRunningOnSteamHardware:返回 ESteamHardwareType(SDK v1.65 移除
// IsRunningOnSteamDeck,返回类型是非布尔枚举)。对照 isteamutils.h:IsRunningOnSteamHardware
MockHardwareType isRunningOnSteamHardware() const { return hw_; }
// GetSteamHardwareDefaultConfig:默认返回与硬件类型对应的配置档;
// 可用 override_ 模拟 partner 后台按设备定制。对照 isteamutils.h:GetSteamHardwareDefaultConfig
MockHardwareDefaultConfig getSteamHardwareDefaultConfig() const {
if (override_ != kConfigNone) return override_;
switch (hw_) {
case kHardwareSteamDeck: return kConfigSteamDeck;
case kHardwareSteamMachine: return kConfigSteamMachine;
case kHardwareSteamFrame: return kConfigSteamFrame;
default: return kConfigNone;
}
}
void setDefaultConfigOverride(MockHardwareDefaultConfig c) { override_ = c; }
private:
uint32_t appId_;
const char* ipCountry_;
uint32_t serverTime_;
uint8_t battery_;
bool proton_;
MockHardwareType hw_;
MockHardwareDefaultConfig override_ = kConfigNone;
uint32_t activeSeconds_ = 0;
};
// 把硬件默认配置档映射为游戏画质预设(mock 模型假设)
MockPreset presetFromConfig(MockHardwareDefaultConfig cfg) {
switch (cfg) {
case kConfigLow: return kPresetLow;
case kConfigMedium: return kPresetMedium;
case kConfigHigh: return kPresetHigh;
case kConfigMax: return kPresetMax;
case kConfigSteamDeck: return kPresetMedium; // 模型假设:Deck 档取中
case kConfigSteamMachine: return kPresetHigh;
case kConfigSteamFrame: return kPresetHigh;
default: return kPresetMedium;
}
}
// 低电量兜底:电量低于 20% 时强制最低档(模型假设)
MockPreset applyBatteryCap(MockPreset preset, uint8_t battery) {
if (battery < 20 && preset > kPresetLow) return kPresetLow;
return preset;
}
} // namespace steam_repro
int main() {
using namespace steam_repro;
// 桌面 + Windows 原生:普通台式机
MockSteamUtils desktop(480, "CN", 1735000000, 255, false, kHardwareNone);
// 1. GetAppID 返回当前 AppID
CHECK(desktop.getAppID() == 480);
// 2. GetIPCountry 返回 2 位国家码(mock 数据)
CHECK(desktop.getIPCountry() == std::string("CN"));
// 3. GetServerRealTime 返回服务器 Unix 时间
CHECK(desktop.getServerRealTime() == 1735000000);
// 4. GetSecondsSinceAppActive 单调递增
CHECK(desktop.getSecondsSinceAppActive() == 0);
CHECK(desktop.getSecondsSinceAppActive() == 1);
CHECK(desktop.getSecondsSinceAppActive() == 2);
// 5. 交流供电时电量返回 255
CHECK(desktop.getCurrentBatteryPower() == 255);
// 6. 桌面设备:IsRunningOnSteamHardware 返回 None(非布尔!)
CHECK(desktop.isRunningOnSteamHardware() == kHardwareNone);
// 7. 非 Proton 下 IsRunningUnderProton 为 false
CHECK(!desktop.isRunningUnderProton());
// 8. 桌面无定制配置:默认 None
CHECK(desktop.getSteamHardwareDefaultConfig() == kConfigNone);
// Steam Deck:SteamOS(非 Proton)
MockSteamUtils deck(480, "US", 1735000001, 82, false, kHardwareSteamDeck);
CHECK(deck.isRunningOnSteamHardware() == kHardwareSteamDeck);
CHECK(deck.getSteamHardwareDefaultConfig() == kConfigSteamDeck);
// 9. Deck 档映射为中等预设(模型假设),再叠加电量兜底
CHECK(presetFromConfig(deck.getSteamHardwareDefaultConfig()) == kPresetMedium);
CHECK(applyBatteryCap(kPresetMedium, 82) == kPresetMedium);
// 10. 低电量(18%)强制降到最低档
CHECK(applyBatteryCap(kPresetHigh, 18) == kPresetLow);
CHECK(applyBatteryCap(kPresetLow, 18) == kPresetLow);
// Proton 台式机:兼容层下运行
MockSteamUtils protonPc(480, "DE", 1735000002, 255, true, kHardwareNone);
CHECK(protonPc.isRunningUnderProton());
CHECK(protonPc.isRunningOnSteamHardware() == kHardwareNone);
// 11. 电池供电:电量 35 时如实返回
MockSteamUtils laptop(480, "JP", 1735000003, 35, false, kHardwareNone);
CHECK(laptop.getCurrentBatteryPower() == 35);
// 12. partner 后台按设备定制:把 Steam Machine 默认档覆盖为 High
MockSteamUtils machine(480, "US", 1735000004, 255, false, kHardwareSteamMachine);
CHECK(machine.getSteamHardwareDefaultConfig() == kConfigSteamMachine);
machine.setDefaultConfigOverride(kConfigHigh);
CHECK(machine.getSteamHardwareDefaultConfig() == kConfigHigh);
CHECK(presetFromConfig(kConfigHigh) == kPresetHigh);
// 13. Steam Frame 映射为 High(模型假设)
MockSteamUtils frame(480, "US", 1735000005, 255, false, kHardwareSteamFrame);
CHECK(frame.isRunningOnSteamHardware() == kHardwareSteamFrame);
CHECK(presetFromConfig(kConfigSteamFrame) == kPresetHigh);
return lab::report("14-1 平台工具机制");
}
本机实测(Apple clang 16,clang++ -std=c++20 -Wall):编译通过(零警告),断言 24/24 通过。
小结
ISteamUtils提供环境事实:AppID、国家码、服务器时间、秒数、电量。- v1.65 已移除
IsRunningOnSteamDeck:硬件判定用IsRunningOnSteamHardware()(返回枚举),功能决策用GetSteamHardwareDefaultConfig()等替代接口。 GetSteamHardwareDefaultConfig把设备适配交给 Steam 客户端与 partner 后台,游戏只做「配置档→预设」映射。- 电量、Proton、Big Picture 是降级与形态判定的补充信号。
阅读导航:上一节:13.3 库存的商业模型 · 下一节:14.2 手柄与输入 。
继续阅读
探索更多技术文章
浏览归档,发现更多关于系统设计、工具链和工程实践的内容。