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;
工程语义:
- 文件名不区分大小写,自动转小写:头文件注释明文——
"foo.bar"与"Foo.bar"是同一文件,写入后再迭代读到的文件名是小写。 FileRead返回实际读到的字节数:不足cubDataToRead时按文件实际大小返回;文件不存在返回负值。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;
工程语义:
- 配额是「总量 + 可用」两个输出:
GetQuota填pnTotalBytes(总配额)与puAvailableBytes(剩余可用);本 mock 用 1GB 模拟总量,真实配额以官方为准。 - 文件列表用迭代器:
GetFileCount拿数量,GetFileNameAndSize(iFile)按下标取名字与大小。 - 单次写入有大小上限:真实常量
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;
工程语义:
- 按文件控制同步平台:
ERemoteStoragePlatform是位掩码(Windows=1«0、OSX=1«1、Linux=1«3…,k_ERemoteStoragePlatformAll = 0xffffffff),不同平台可同步到不同设备。 - 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.h | FileWrite/FileRead/FileDelete/FileExists | 文件生命周期 |
isteamremotestorage.h | GetQuota | 总量 + 可用配额 |
isteamremotestorage.h | GetFileCount/GetFileNameAndSize | 文件枚举 |
isteamremotestorage.h | SetSyncPlatforms/GetSyncPlatforms | 按文件同步平台 |
isteamremotestorage.h | IsCloudEnabledForApp/SetCloudEnabledForApp | App 级开关 |
isteamremotestorage.h | FilePersisted | 云端已同步判定 |
isteamremotestorage.h | FileWriteStream* | 流式写入 |
数据口径与来源
- 接口签名、
ERemoteStoragePlatform位值、k_unMaxCloudFileChunkSize = 100MB、文件名大小写归一化注释:SDK v1.65public/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 存档同步与冲突 。
继续阅读
探索更多技术文章
浏览归档,发现更多关于系统设计、工具链和工程实践的内容。