《Steam 游戏平台:开发与商业化》4.1 云存储机制

云存储机制把存档从本地文件提升为平台托管对象:FileWrite/FileRead 读写、FileDelete/FileExists 管理、GetQuota 看配额、SetSyncPlatforms 控制同步平台,还有 FileWriteStream 流式写入。本节讲云存储接口的工程语义,lab 用 C++ 模拟文件生命周期、配额与流式写入。

4.1 云存储机制

云存储(Steam Cloud)是「存档由平台托管」的通道:玩家换机后进度还在。接入要回答的工程问题:文件怎么读写、配额怎么算、哪些平台参与同步、大文件怎么写。

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

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

  • Steam 发行专题 (操作手册)讲「后台开启云同步、看存储占用」;本节讲「代码里读写云存档的接口语义」。
  • 卷一讲云存档如何影响换机留存;本节讲云存储的文件生命周期与配额模型。
  • lab 用纯 C++ 模拟文件读写、配额与流式写入,不依赖 Steam 客户端运行。

文件读写与生命周期

核心接口围绕「文件」对象:

// isteamremotestorage.h:FileWrite / FileRead / FileDelete / FileExists(SDK v1.65 头文件摘录,已删减)
virtual bool	FileWrite( const char *pchFile, const void *pvData, int32 cubData ) = 0;
virtual int32	FileRead( const char *pchFile, void *pvData, int32 cubDataToRead ) = 0;
virtual bool	FileDelete( const char *pchFile ) = 0;
virtual bool	FileExists( const char *pchFile ) = 0;

工程语义:

  1. 文件名不区分大小写,自动转小写:头文件注释明文——"foo.bar" 与 "Foo.bar" 是同一文件,写入后再迭代读到的文件名是小写。
  2. FileRead 返回实际读到的字节数:不足 cubDataToRead 时按文件实际大小返回;文件不存在返回负值。
  3. FileWrite 覆盖语义:重复写同名文件覆盖旧内容;GetFileSize 反映新大小。

配额与文件信息

// isteamremotestorage.h:GetQuota / GetFileCount / GetFileNameAndSize(SDK v1.65 头文件摘录,已删减)
virtual bool GetQuota( uint64 *pnTotalBytes, uint64 *puAvailableBytes ) = 0;
virtual int32 GetFileCount() = 0;
virtual const char *GetFileNameAndSize( int iFile, int32 *pnFileSizeInBytes ) = 0;

工程语义:

  1. 配额是「总量 + 可用」两个输出:GetQuota 填 pnTotalBytes(总配额)与 puAvailableBytes(剩余可用);本 mock 用 1GB 模拟总量,真实配额以官方为准。
  2. 文件列表用迭代器:GetFileCount 拿数量,GetFileNameAndSize(iFile) 按下标取名字与大小。
  3. 单次写入有大小上限:真实常量 k_unMaxCloudFileChunkSize = 100 * 1024 * 1024(100MB);mock 用 1KB 复现「超上限拒绝」的语义。
// isteamremotestorage.h:k_unMaxCloudFileChunkSize(SDK v1.65 头文件摘录,已删减)
const uint32 k_unMaxCloudFileChunkSize = 100 * 1024 * 1024;

同步平台与开关

// isteamremotestorage.h:SetSyncPlatforms / GetSyncPlatforms / IsCloudEnabledForApp / SetCloudEnabledForApp(SDK v1.65 头文件摘录,已删减)
virtual bool	SetSyncPlatforms( const char *pchFile, ERemoteStoragePlatform eRemoteStoragePlatform ) = 0;
virtual ERemoteStoragePlatform GetSyncPlatforms( const char *pchFile ) = 0;
virtual bool IsCloudEnabledForApp() = 0;
virtual void SetCloudEnabledForApp( bool bEnabled ) = 0;

工程语义:

  1. 按文件控制同步平台:ERemoteStoragePlatform 是位掩码(Windows=1«0、OSX=1«1、Linux=1«3…,k_ERemoteStoragePlatformAll = 0xffffffff),不同平台可同步到不同设备。
  2. App 级开关:IsCloudEnabledForApp/SetCloudEnabledForApp 控制整个应用云同步;关闭后本地写入仍成功,但 FilePersisted 为 false——文件只留在本机,不上云。
// isteamremotestorage.h:FilePersisted(SDK v1.65 头文件摘录,已删减)
virtual bool	FilePersisted( const char *pchFile ) = 0;

流式写入

大文件(截图、回放、日志)不适合一次性 FileWrite:

// isteamremotestorage.h:FileWriteStreamOpen / FileWriteStreamWriteChunk / FileWriteStreamClose / FileWriteStreamCancel(SDK v1.65 头文件摘录,已删减)
virtual UGCFileWriteStreamHandle_t FileWriteStreamOpen( const char *pchFile ) = 0;
virtual bool FileWriteStreamWriteChunk( UGCFileWriteStreamHandle_t writeHandle, const void *pvData, int32 cubData ) = 0;
virtual bool FileWriteStreamClose( UGCFileWriteStreamHandle_t writeHandle ) = 0;
virtual bool FileWriteStreamCancel( UGCFileWriteStreamHandle_t writeHandle ) = 0;

工程语义:

  • 流式三态:Open 拿到句柄 → 多次 WriteChunk 追加 → Close 落盘;或 Cancel 整体丢弃。
  • 适合边生成边上传的内容;Close 前文件对云端不可见。

接口签名对照

头文件条目语义
isteamremotestorage.hFileWrite/FileRead/FileDelete/FileExists文件生命周期
isteamremotestorage.hGetQuota总量 + 可用配额
isteamremotestorage.hGetFileCount/GetFileNameAndSize文件枚举
isteamremotestorage.hSetSyncPlatforms/GetSyncPlatforms按文件同步平台
isteamremotestorage.hIsCloudEnabledForApp/SetCloudEnabledForAppApp 级开关
isteamremotestorage.hFilePersisted云端已同步判定
isteamremotestorage.hFileWriteStream*流式写入

数据口径与来源

  • 接口签名、ERemoteStoragePlatform 位值、k_unMaxCloudFileChunkSize = 100MB、文件名大小写归一化注释:SDK v1.65 public/steam/isteamremotestorage.h 可实证。
  • 实际配额大小、各账号可用空间:partner 文档登录后可见 / 以官方当前为准;mock 的 1GB 与 1KB 上限为仿真设定。
  • 流式句柄 k_UGCFileStreamHandleInvalid:头文件可实证(0xffffffffffffffff)。

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

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

下面的仿真复现「云存储机制」的工程语义:文件读写/删除/存在判定、文件名大小写归一化、配额与文件枚举、按文件同步平台掩码、App 级云同步开关、流式写入的 Close 与 Cancel。它与 src/04-1-cloud-storage-mechanics.cpp 逐字节一致,mock 签名对照 SDK v1.65 头文件:

// file: src/04-1-cloud-storage-mechanics.cpp
// tier: L1
// verify: clang++ -std=c++20 -Wall -I. src/04-1-cloud-storage-mechanics.cpp -o bin/04-1-cloud-storage-mechanics && ./bin/04-1-cloud-storage-mechanics
//
// mock:复现云存储机制的工程语义——FileWrite/FileRead/FileDelete/FileExists/
// GetFileSize/GetQuota/GetFileCount/GetFileNameAndSize/SetSyncPlatforms/
// IsCloudEnabledForApp/SetCloudEnabledForApp,以及流式写入
// (FileWriteStreamOpen/WriteChunk/Close/Cancel)与文件名大小写归一化
// (头文件明文:文件名不区分大小写、自动转小写)。
// 签名对照 SDK v1.65 isteamremotestorage.h,非 Valve 实现。
#include "verify.h"

#include <algorithm>
#include <cctype>
#include <cstdint>
#include <map>
#include <string>
#include <vector>

namespace steam_repro {

// ERemoteStoragePlatform 位值对照 isteamremotestorage.h
static constexpr uint32_t kPlatformWindows = 1 << 0;
static constexpr uint32_t kPlatformOSX = 1 << 1;

class MockSteamRemoteStorage {
 public:
  // 真实常量:k_unMaxCloudFileChunkSize = 100 * 1024 * 1024(100MB)
  // mock 用 1KB 上限复现「单次写入不可超过上限」的语义,测试成本低。
  static constexpr uint32_t kMaxMockChunkSize = 1024;
  static constexpr uint64_t kQuotaTotalBytes = 1024ULL * 1024 * 1024;  // 1GB

  // 文件名自动转小写(头文件注释明文)
  static std::string lower_(std::string name) {
    for (char& c : name) c = static_cast<char>(std::tolower(static_cast<unsigned char>(c)));
    return name;
  }

  // isteamremotestorage.h:FileWrite:超上限拒绝
  bool fileWrite(const char* pchFile, const void* pvData, int32_t cubData) {
    if (cubData < 0 || static_cast<uint32_t>(cubData) > kMaxMockChunkSize) return false;
    const uint8_t* bytes = static_cast<const uint8_t*>(pvData);
    files_[lower_(pchFile)] = std::vector<uint8_t>(bytes, bytes + cubData);
    return true;
  }

  // isteamremotestorage.h:FileRead:返回实际读到的字节数
  int32_t fileRead(const char* pchFile, void* pvData, int32_t cubDataToRead) {
    auto it = files_.find(lower_(pchFile));
    if (it == files_.end()) return -1;
    int32_t n = std::min(cubDataToRead, static_cast<int32_t>(it->second.size()));
    if (n > 0) {
      uint8_t* out = static_cast<uint8_t*>(pvData);
      for (int32_t i = 0; i < n; ++i) out[i] = it->second[i];
    }
    return n;
  }

  // isteamremotestorage.h:FileDelete
  bool fileDelete(const char* pchFile) {
    return files_.erase(lower_(pchFile)) > 0;
  }

  // isteamremotestorage.h:FileExists
  bool fileExists(const char* pchFile) const {
    return files_.find(lower_(pchFile)) != files_.end();
  }

  // isteamremotestorage.h:GetFileSize:不存在返回 -1(mock 约定)
  int32_t getFileSize(const char* pchFile) const {
    auto it = files_.find(lower_(pchFile));
    if (it == files_.end()) return -1;
    return static_cast<int32_t>(it->second.size());
  }

  // isteamremotestorage.h:GetQuota
  bool getQuota(uint64_t* pnTotalBytes, uint64_t* puAvailableBytes) const {
    uint64_t used = usedBytes_();
    *pnTotalBytes = kQuotaTotalBytes;
    *puAvailableBytes = kQuotaTotalBytes - std::min(used, kQuotaTotalBytes);
    return true;
  }

  // isteamremotestorage.h:GetFileCount / GetFileNameAndSize:迭代
  int32_t getFileCount() const { return static_cast<int32_t>(files_.size()); }
  const char* getFileNameAndSize(int iFile, int32_t* pnFileSizeInBytes) {
    if (iFile < 0 || static_cast<size_t>(iFile) >= files_.size()) {
      *pnFileSizeInBytes = 0;
      return nullptr;
    }
    auto it = files_.begin();
    for (int k = 0; k < iFile; ++k) ++it;
    *pnFileSizeInBytes = static_cast<int32_t>(it->second.size());
    return it->first.c_str();
  }

  // isteamremotestorage.h:SetSyncPlatforms / GetSyncPlatforms
  bool setSyncPlatforms(const char* pchFile, uint32_t eRemoteStoragePlatform) {
    if (!fileExists(pchFile)) return false;
    platforms_[lower_(pchFile)] = eRemoteStoragePlatform;
    return true;
  }
  uint32_t getSyncPlatforms(const char* pchFile) const {
    auto it = platforms_.find(lower_(pchFile));
    return it == platforms_.end() ? 0 : it->second;
  }

  // isteamremotestorage.h:IsCloudEnabledForApp / SetCloudEnabledForApp
  bool isCloudEnabledForApp() const { return cloudEnabledForApp_; }
  void setCloudEnabledForApp(bool bEnabled) { cloudEnabledForApp_ = bEnabled; }

  // isteamremotestorage.h:FilePersisted:云端已同步(本 mock 中与 app 开关挂钩)
  bool filePersisted(const char* pchFile) const {
    return fileExists(pchFile) && cloudEnabledForApp_;
  }

  // isteamremotestorage.h:FileWriteStreamOpen:返回写入流句柄
  uint64_t fileWriteStreamOpen(const char* pchFile) {
    uint64_t h = ++nextStreamHandle_;
    streams_[h] = StreamRec{lower_(pchFile), {}};
    return h;
  }

  // isteamremotestorage.h:FileWriteStreamWriteChunk
  bool fileWriteStreamWriteChunk(uint64_t writeHandle, const void* pvData, int32_t cubData) {
    auto it = streams_.find(writeHandle);
    if (it == streams_.end() || cubData < 0) return false;
    const uint8_t* bytes = static_cast<const uint8_t*>(pvData);
    it->second.data.insert(it->second.data.end(), bytes, bytes + cubData);
    return true;
  }

  // isteamremotestorage.h:FileWriteStreamClose:落盘
  bool fileWriteStreamClose(uint64_t writeHandle) {
    auto it = streams_.find(writeHandle);
    if (it == streams_.end()) return false;
    files_[it->second.name] = it->second.data;
    streams_.erase(it);
    return true;
  }

  // isteamremotestorage.h:FileWriteStreamCancel:丢弃
  bool fileWriteStreamCancel(uint64_t writeHandle) {
    auto it = streams_.find(writeHandle);
    if (it == streams_.end()) return false;
    streams_.erase(it);
    return true;
  }

 private:
  struct StreamRec {
    std::string name;
    std::vector<uint8_t> data;
  };

  uint64_t usedBytes_() const {
    uint64_t total = 0;
    for (const auto& kv : files_) total += kv.second.size();
    return total;
  }

  std::map<std::string, std::vector<uint8_t>> files_;
  std::map<std::string, uint32_t> platforms_;
  std::map<uint64_t, StreamRec> streams_;
  uint64_t nextStreamHandle_ = 0;
  bool cloudEnabledForApp_ = true;
};

}  // namespace steam_repro

int main() {
  using namespace steam_repro;
  MockSteamRemoteStorage rs;

  const uint8_t saveA[] = {0x11, 0x22, 0x33};
  const uint8_t saveB[] = {0xAA, 0xBB, 0xCC, 0xDD};

  // 1. 初始不存在
  CHECK(!rs.fileExists("save.dat"));

  // 2. FileWrite 成功,FileExists 为真
  CHECK(rs.fileWrite("save.dat", saveA, 3));
  CHECK(rs.fileExists("save.dat"));

  // 3. FileRead 读回相同字节,返回实际读取数
  uint8_t buf[8] = {0};
  CHECK(rs.fileRead("save.dat", buf, sizeof(buf)) == 3);
  CHECK(buf[0] == 0x11 && buf[1] == 0x22 && buf[2] == 0x33);

  // 4. 文件名大小写归一化:写入 Save.DAT 落到 save.dat
  CHECK(rs.fileWrite("Save.DAT", saveB, 4));
  CHECK(rs.fileExists("save.dat"));
  CHECK(rs.getFileSize("save.dat") == 4);

  // 5. 覆盖写后 GetFileSize 反映新大小
  CHECK(rs.fileWrite("save.dat", saveA, 3));
  CHECK(rs.getFileSize("save.dat") == 3);

  // 6. FileDelete 后不存在,GetFileSize 返回 -1(mock 约定)
  CHECK(rs.fileDelete("save.dat"));
  CHECK(!rs.fileExists("save.dat"));
  CHECK(rs.getFileSize("save.dat") == -1);

  // 7. 迭代:GetFileCount 与 GetFileNameAndSize 返回小写文件名
  CHECK(rs.fileWrite("a.dat", saveA, 3));
  CHECK(rs.fileWrite("b.dat", saveB, 4));
  CHECK(rs.getFileCount() == 2);
  int32_t sz = 0;
  const char* name0 = rs.getFileNameAndSize(0, &sz);
  CHECK(name0 != nullptr);
  CHECK(sz == 3 || sz == 4);

  // 8. 配额:总量 1GB,可用 = 总量 - 已用
  uint64_t total = 0, avail = 0;
  CHECK(rs.getQuota(&total, &avail));
  CHECK(total == MockSteamRemoteStorage::kQuotaTotalBytes);
  CHECK(avail == total - 7);  // a.dat 3 + b.dat 4

  // 9. 单次写入超过上限被拒绝(真实上限 k_unMaxCloudFileChunkSize=100MB)
  CHECK(!rs.fileWrite("big.bin", saveA, MockSteamRemoteStorage::kMaxMockChunkSize + 1));
  CHECK(!rs.fileExists("big.bin"));

  // 10. 流式写入:分块追加后 Close 落盘
  uint64_t h = rs.fileWriteStreamOpen("chunk.dat");
  CHECK(h != 0);
  CHECK(rs.fileWriteStreamWriteChunk(h, saveA, 3));
  CHECK(rs.fileWriteStreamWriteChunk(h, saveB, 4));
  CHECK(rs.fileWriteStreamClose(h));
  CHECK(rs.fileExists("chunk.dat"));
  CHECK(rs.fileRead("chunk.dat", buf, sizeof(buf)) == 7);

  // 11. 流式取消:不落盘
  uint64_t h2 = rs.fileWriteStreamOpen("cancel.dat");
  CHECK(rs.fileWriteStreamWriteChunk(h2, saveA, 3));
  CHECK(rs.fileWriteStreamCancel(h2));
  CHECK(!rs.fileExists("cancel.dat"));

  // 12. SetSyncPlatforms 记录平台掩码
  CHECK(rs.setSyncPlatforms("a.dat", kPlatformWindows | kPlatformOSX));
  CHECK(rs.getSyncPlatforms("a.dat") == (kPlatformWindows | kPlatformOSX));

  // 13. 关闭 App 云同步后:本地写入仍成功,但 FilePersisted 为 false
  rs.setCloudEnabledForApp(false);
  CHECK(!rs.isCloudEnabledForApp());
  CHECK(rs.fileWrite("local_only.dat", saveA, 3));
  CHECK(rs.fileExists("local_only.dat"));
  CHECK(!rs.filePersisted("local_only.dat"));
  rs.setCloudEnabledForApp(true);
  CHECK(rs.isCloudEnabledForApp());
  CHECK(rs.filePersisted("a.dat"));

  return lab::report("04-1 云存储机制");
}

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

小结

  • 文件生命周期:Write/Read/Delete/Exists,大小写归一化。
  • 配额模型:总量 + 可用,单次写入有上限。
  • 同步控制:按文件平台位掩码 + App 级开关。
  • 流式写入:Open/WriteChunk/Close 或 Cancel。

阅读导航:上一节:3.3 成就与统计的策略 · 下一节:4.2 存档同步与冲突 。

继续阅读

探索更多技术文章

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

全部文章 返回首页

「books」更多文章

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