《Steam 游戏平台:开发与商业化》14.1 平台工具机制

本节接 ISteamUtils 平台工具机制:GetAppID/GetIPCountry/GetServerRealTime/GetSecondsSinceAppActive/GetCurrentBatteryPower 与硬件判定。SDK v1.65 已移除 IsRunningOnSteamDeck,改用 IsRunningOnSteamHardware(返回 ESteamHardwareType)与 IsRunningUnderProton。lab 用 C++ mock 平台状态与默认配置档选择,验证非布尔硬件判定与低电量兜底。

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;

工程语义:

  1. GetAppID 是运行环境的锚点。进程实际属于哪个 App 由 Steam 客户端决定(配合 steam_appid.txt 做开发),很多后续判断(DLC、统计、成就)都以它为根。mock 里应断言返回值与配置一致。
  2. GetServerRealTime 是可信时间源。服务器时间(Unix 秒)用于活动截止、掉落冷却等对时敏感的判定——比客户端本机时钟更可靠。
  3. GetIPCountry 返回 2 位 ISO 3166-1-alpha-2 国家码。地区化定价、合规开关常用它做入口判断;注意它是「IP 定位」结果,不一定是账号地区。
  4. 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;

工程语义:

  1. 别用旧接口判断 Deck。IsRunningOnSteamDeck 在 v1.65 已移除,写新代码必须用 IsRunningOnSteamHardware() == k_ESteamHardwareTypeSteamDeck。头文件注释还强调:这个方法只用于「usage analytics, support, diagnostic 等非功能性决策」。
  2. 功能/能力决策要换别的接口。头文件列了一组替代:GetSteamHardwareDefaultConfig()、IsSteamInBigPictureMode()、IsRunningUnderProton()、IsSteamRunningInVR()、GetCurrentBatteryPower()。也就是说:想选画质档用配置档接口,想判输入模式用 Big Picture,想判兼容层用 Proton——不要把「是不是 Deck」当作唯一信号。
  3. 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;

工程语义(头文件注释给了完整的选档步骤):

  1. 先取配置档,再映射到游戏预设。配置档可能是设备专属(k_ESteamHardwareDefaultConfigSteamDeck)或通用档(Low/Medium/High/Max)。游戏把 Low/Medium/High/Max 映射到自己预设;预设数不足 4 个时允许多个档映射到同一预设。
  2. 配置档可被 partner 后台改写。发行商可以在 partner 站定制「某设备返回哪个档」,因此游戏不需要为未来新硬件重新编译——这正是用配置档而非型号枚举的核心价值。
  3. Proton 与电量是降级输入。Proton 下性能差异大,低电量要强制降档;本节 mock 用「配置档 → 预设 → 低电量兜底」三步演示,量级均为模型假设,非官方数值。

接口签名对照

头文件条目语义
isteamutils.hGetAppID()当前进程 AppID
isteamutils.hGetIPCountry()2 位 ISO 3166-1-alpha-2 国家码
isteamutils.hGetServerRealTime()Steam 服务器 Unix 时间
isteamutils.hGetSecondsSinceAppActive()进程激活以来秒数
isteamutils.hGetCurrentBatteryPower()电量百分比;255=交流供电
isteamutils.hIsRunningUnderProton()是否 Proton 兼容层运行
isteamutils.hIsRunningOnSteamHardware()返回 ESteamHardwareType(v1.65 取代 IsRunningOnSteamDeck)
isteamutils.hGetSteamHardwareDefaultConfig()默认配置档(可被 partner 后台定制)

数据口径与来源

  • 接口签名、ESteamHardwareType/ESteamHardwareDefaultConfig 枚举:SDK v1.65 public/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 手柄与输入 。

继续阅读

探索更多技术文章

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

全部文章 返回首页

「books」更多文章

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