4.2 存档同步与冲突
4.1 讲了单机视角的文件读写;这一节处理云存储真正麻烦的部分:多设备同时玩,同一存档在两端都改了,谁赢。SDK 提供异步读写与本地变更事件,冲突检测与解决由游戏定义。
本卷所有接口口径以 Steamworks SDK v1.65(2026-07-23) 为准。本节摘录的签名对照该版本 public/steam/isteamremotestorage.h。
本章与站内既有内容的分工
- Steam 发行专题 (操作手册)讲「后台云存储容量与策略」;本节讲「代码里处理同步冲突的接口语义」。
- 卷一讲云存档的换机体验设计;本节讲冲突检测的机制与两种解决策略。
- lab 用纯 C++ 模拟双设备冲突,不依赖 Steam 客户端运行。
异步读写
存档同步天然异步——上传/下载是网络操作:
// isteamremotestorage.h:FileWriteAsync / FileReadAsync / FileReadAsyncComplete(SDK v1.65 头文件摘录,已删减)
STEAM_CALL_RESULT( RemoteStorageFileWriteAsyncComplete_t )
virtual SteamAPICall_t FileWriteAsync( const char *pchFile, const void *pvData, uint32 cubData ) = 0;
STEAM_CALL_RESULT( RemoteStorageFileReadAsyncComplete_t )
virtual SteamAPICall_t FileReadAsync( const char *pchFile, uint32 nOffset, uint32 cubToRead ) = 0;
virtual bool FileReadAsyncComplete( SteamAPICall_t hReadCall, void *pvBuffer, uint32 cubToRead ) = 0;
回调结构:
// isteamremotestorage.h:RemoteStorageFileReadAsyncComplete_t(SDK v1.65 头文件摘录,已删减)
struct RemoteStorageFileReadAsyncComplete_t
{
enum { k_iCallback = k_iSteamRemoteStorageCallbacks + 32 };
SteamAPICall_t m_hFileReadAsync; // call handle of the async read which was made
EResult m_eResult; // result
uint32 m_nOffset; // offset in the file this read was at
uint32 m_cubRead; // amount read - will the <= the amount requested
};
工程语义:
- 异步函数返回
SteamAPICall_t句柄:真正结果通过回调结构(RemoteStorageFileWriteAsyncComplete_t/RemoteStorageFileReadAsyncComplete_t)送达,m_eResult是成败。 FileReadAsync支持偏移量读取:nOffset+cubToRead只读文件片段(适合大存档分片);FileReadAsyncComplete把结果填进缓冲。- 写完不立即本地立即可见:
FileWriteAsync完成回调后才算真正写成功。
本地变更事件
另一台设备改动了云端文件,本机如何知道?SDK 通过「本地文件变更」队列告知:
// isteamremotestorage.h:GetLocalFileChangeCount / GetLocalFileChange(SDK v1.65 头文件摘录,已删减)
virtual int32 GetLocalFileChangeCount() = 0;
virtual const char *GetLocalFileChange( int iFile, ERemoteStorageLocalFileChange *pEChangeType, ERemoteStorageFilePathType *pEFilePathType ) = 0;
// isteamremotestorage.h:ERemoteStorageLocalFileChange(SDK v1.65 头文件摘录,已删减)
enum ERemoteStorageLocalFileChange
{
k_ERemoteStorageLocalFileChange_Invalid = 0,
k_ERemoteStorageLocalFileChange_FileUpdated = 1, // The file was updated from another device
k_ERemoteStorageLocalFileChange_FileDeleted = 2, // The file was deleted by another device
};
工程语义:
- 变更队列是一次性消费:每次同步后
GetLocalFileChangeCount反映本轮变化;处理一条取一条。 - 事件类型区分新增/更新与删除:
FileUpdated表示其他设备更新了文件,FileDeleted表示其他设备删了文件。 - 变更事件是游戏的「重新加载」信号:收到
FileUpdated后应重新读该存档文件。
冲突检测与解决
本机已改(本地脏文件)且远端也被另一设备改过,同步时就产生冲突:
工程语义:
- 脏文件先上传:本地有未同步改动时,同步先把脏文件推上服务器;远端无冲突版本则直接标记已同步。
- 冲突判定:本地脏 + 远端有另一设备的更新 → 冲突,不能静默覆盖任何一方。
- 两种解决策略:
- last-writer-wins:比较两端时间戳,取新的一方覆盖旧的一方。
- keep-local:保留本地版本,把本地内容重新上传(覆盖远端)。
- 批量原子提交:多文件存档(清单 + 数据)用
BeginFileWriteBatch/EndFileWriteBatch包裹,要么全部落盘、要么整体丢弃。
// isteamremotestorage.h:BeginFileWriteBatch / EndFileWriteBatch(SDK v1.65 头文件摘录,已删减)
// Indicate to Steam the beginning / end of a set of local file
virtual bool BeginFileWriteBatch() = 0;
virtual bool EndFileWriteBatch() = 0;
接口签名对照
| 头文件 | 条目 | 语义 |
|---|---|---|
isteamremotestorage.h | FileWriteAsync/FileReadAsync/FileReadAsyncComplete | 异步读写 |
isteamremotestorage.h | RemoteStorageFileWriteAsyncComplete_t/RemoteStorageFileReadAsyncComplete_t | 异步完成回调 |
isteamremotestorage.h | GetLocalFileChangeCount/GetLocalFileChange | 本地变更事件 |
isteamremotestorage.h | ERemoteStorageLocalFileChange | 变更类型(Updated/Deleted) |
isteamremotestorage.h | BeginFileWriteBatch/EndFileWriteBatch | 批量原子提交 |
isteamremotestorage.h | GetFileTimestamp | 文件时间戳(冲突裁决依据) |
数据口径与来源
- 接口签名、回调结构字段、
ERemoteStorageLocalFileChange枚举值、批量提交注释:SDK v1.65public/steam/isteamremotestorage.h可实证。 - 冲突解决策略(last-writer-wins / keep-local)是游戏侧设计,非 SDK 强制行为;本 lab 按常见工程实践模拟。
- 时间戳比较的具体规则、多设备最终一致性:以官方文档与 Steam 客户端实际行为为准。
以上接口口径撰写时对照 Steamworks SDK v1.65 头文件与 partner.steamgames.com 官方文档核对;登录后可见数据以官方当前为准。
可运行产物:C++ 最小验证
下面的仿真复现「存档同步与冲突」的工程语义:异步读写(句柄 + 完成回调)、本地文件变更事件(FileUpdated/FileDeleted)、双设备冲突检测与两种解决策略(last-writer-wins / keep-local)、批量原子提交与中途丢弃。它与 src/04-2-save-sync-conflict.cpp 逐字节一致,mock 签名对照 SDK v1.65 头文件:
// file: src/04-2-save-sync-conflict.cpp
// tier: L1
// verify: clang++ -std=c++20 -Wall -I. src/04-2-save-sync-conflict.cpp -o bin/04-2-save-sync-conflict && ./bin/04-2-save-sync-conflict
//
// mock:复现存档同步与冲突的工程语义——异步读写
// (FileWriteAsync/FileReadAsync/FileReadAsyncComplete 与
// RemoteStorageFileWriteAsyncComplete_t/RemoteStorageFileReadAsyncComplete_t)、
// 本地文件变更事件(GetLocalFileChangeCount/GetLocalFileChange,
// ERemoteStorageLocalFileChange_FileUpdated/FileDeleted)、
// 多设备冲突检测与两种解决策略(last-writer-wins / keep-local),
// 以及 BeginFileWriteBatch/EndFileWriteBatch 的批量原子提交。
// 签名对照 SDK v1.65 isteamremotestorage.h,非 Valve 实现。
#include "verify.h"
#include <algorithm>
#include <cstdint>
#include <map>
#include <string>
#include <vector>
namespace steam_repro {
// k_EResultOK 对照 steamclientpublic.h
static constexpr int kEResultOK = 1;
// ERemoteStorageLocalFileChange / ERemoteStorageFilePathType 对照 isteamremotestorage.h
static constexpr int kLocalChangeFileUpdated = 1;
static constexpr int kLocalChangeFileDeleted = 2;
static constexpr int kFilePathAPIFilename = 2;
struct MockFileRec {
std::vector<uint8_t> content;
uint64_t mtime = 0;
uint64_t originDevice = 0;
bool dirty = false;
};
struct MockLocalChange {
std::string file;
int changeType = kLocalChangeFileUpdated;
int pathType = kFilePathAPIFilename;
};
// RemoteStorageFileWriteAsyncComplete_t 结构字段对照 isteamremotestorage.h
struct MockWriteComplete {
int result = 0;
};
// RemoteStorageFileReadAsyncComplete_t 结构字段对照 isteamremotestorage.h
struct MockReadComplete {
uint64_t handle = 0;
int result = 0;
uint32_t offset = 0;
uint32_t cubRead = 0;
};
class MockSteamRemoteStorageSync {
public:
explicit MockSteamRemoteStorageSync(uint64_t deviceId) : deviceId_(deviceId) {}
// isteamremotestorage.h:FileWrite:批量中先进 staging
bool fileWrite(const char* pchFile, const void* pvData, int32_t cubData) {
const uint8_t* bytes = static_cast<const uint8_t*>(pvData);
std::vector<uint8_t> data(bytes, bytes + cubData);
if (inBatch_) {
staging_[pchFile] = data;
return true;
}
return commitLocal_(pchFile, data);
}
bool fileExists(const char* pchFile) const {
return local_.find(pchFile) != local_.end();
}
// isteamremotestorage.h:FileRead
int32_t fileRead(const char* pchFile, void* pvData, int32_t cubDataToRead) {
auto it = local_.find(pchFile);
if (it == local_.end()) return -1;
int32_t n = std::min(cubDataToRead, static_cast<int32_t>(it->second.content.size()));
if (n > 0) {
uint8_t* out = static_cast<uint8_t*>(pvData);
for (int32_t i = 0; i < n; ++i) out[i] = it->second.content[i];
}
return n;
}
// isteamremotestorage.h:FileWriteAsync:返回 SteamAPICall_t,回调记录结果
uint64_t fileWriteAsync(const char* pchFile, const void* pvData, uint32_t cubData) {
const uint8_t* bytes = static_cast<const uint8_t*>(pvData);
std::vector<uint8_t> data(bytes, bytes + cubData);
if (!inBatch_) commitLocal_(pchFile, data);
else staging_[pchFile] = data;
lastWriteComplete_.result = kEResultOK;
return ++nextCall_;
}
// isteamremotestorage.h:FileReadAsync
uint64_t fileReadAsync(const char* pchFile, uint32_t nOffset, uint32_t cubToRead) {
pendingReads_[++nextCall_] = PendingRead{pchFile, nOffset, cubToRead};
return nextCall_;
}
// isteamremotestorage.h:FileReadAsyncComplete:填充缓冲并记录回调
bool fileReadAsyncComplete(uint64_t hReadCall, void* pvBuffer, uint32_t cubToRead) {
auto it = pendingReads_.find(hReadCall);
if (it == pendingReads_.end()) return false;
const PendingRead& pr = it->second;
auto fit = local_.find(pr.file);
if (fit == local_.end()) return false;
uint32_t n = std::min({pr.cubToRead, cubToRead,
static_cast<uint32_t>(fit->second.content.size() - pr.offset)});
if (n > 0) {
uint8_t* out = static_cast<uint8_t*>(pvBuffer);
for (uint32_t i = 0; i < n; ++i) out[i] = fit->second.content[pr.offset + i];
}
lastReadComplete_ = MockReadComplete{hReadCall, kEResultOK, pr.offset, n};
pendingReads_.erase(it);
return true;
}
// isteamremotestorage.h:BeginFileWriteBatch / EndFileWriteBatch:批量原子提交
bool beginFileWriteBatch() {
if (inBatch_) return false;
inBatch_ = true;
staging_.clear();
return true;
}
bool endFileWriteBatch() {
if (!inBatch_) return false;
inBatch_ = false;
for (const auto& kv : staging_) commitLocal_(kv.first, kv.second);
staging_.clear();
return true;
}
// 未 End 即丢弃(模拟批量中途崩溃)
void abortBatch() {
inBatch_ = false;
staging_.clear();
}
// 模拟另一台设备把新文件推上服务器
void applyRemoteFile(const char* pchFile, const std::vector<uint8_t>& data,
uint64_t mtime, uint64_t originDevice) {
remote_[pchFile] = MockFileRec{data, mtime, originDevice, false};
}
void applyRemoteDelete(const char* pchFile) {
remoteDeleted_.push_back(pchFile);
}
// 同步:先上传本地脏文件(远端无冲突版本时标记为已同步),
// 再拉取服务器状态到本地,检测冲突并产生本地变更事件。
// 本机本次已协调(上传/一致)的文件不再重复产生变更事件。
void sync() {
changes_.clear();
conflicts_.clear();
std::vector<std::string> synced;
for (auto& kv : local_) {
if (!kv.second.dirty) continue;
auto rit = remote_.find(kv.first);
if (rit == remote_.end()) {
remote_[kv.first] = kv.second;
kv.second.dirty = false;
synced.push_back(kv.first);
} else if (rit->second.mtime == kv.second.mtime &&
rit->second.originDevice == kv.second.originDevice) {
kv.second.dirty = false;
synced.push_back(kv.first);
}
}
for (auto& kv : remote_) {
const std::string& name = kv.first;
const MockFileRec& remote = kv.second;
if (std::find(synced.begin(), synced.end(), name) != synced.end()) continue;
auto localIt = local_.find(name);
if (localIt == local_.end()) {
local_[name] = remote;
changes_.push_back(MockLocalChange{name, kLocalChangeFileUpdated, kFilePathAPIFilename});
} else if (localIt->second.dirty && remote.originDevice != deviceId_) {
conflicts_.push_back(name);
} else {
bool differs = localIt->second.content != remote.content;
localIt->second = remote;
if (differs && remote.originDevice != deviceId_) {
changes_.push_back(MockLocalChange{name, kLocalChangeFileUpdated, kFilePathAPIFilename});
}
}
}
for (const std::string& name : remoteDeleted_) {
remote_.erase(name); // 服务器端已删除,同步后不再拉取
if (local_.erase(name) > 0) {
changes_.push_back(MockLocalChange{name, kLocalChangeFileDeleted, kFilePathAPIFilename});
}
}
remoteDeleted_.clear(); // 删除事件一次性消费
}
// 冲突解决策略:last-writer-wins(取新 mtime)或 keep-local(保留本地)
void resolveConflictLastWriterWins(const char* pchFile) {
auto lit = local_.find(pchFile);
auto rit = remote_.find(pchFile);
if (lit == local_.end() || rit == remote_.end()) return;
if (rit->second.mtime > lit->second.mtime) lit->second = rit->second;
lit->second.dirty = false;
removeConflict_(pchFile);
}
void resolveConflictKeepLocal(const char* pchFile) {
auto lit = local_.find(pchFile);
if (lit == local_.end()) return;
lit->second.dirty = false;
removeConflict_(pchFile);
}
bool hasConflict(const char* pchFile) const {
for (const std::string& c : conflicts_) {
if (c == pchFile) return true;
}
return false;
}
// isteamremotestorage.h:GetLocalFileChangeCount / GetLocalFileChange
int32_t getLocalFileChangeCount() const { return static_cast<int32_t>(changes_.size()); }
const char* getLocalFileChange(int iFile, int* pEChangeType, int* pEFilePathType) {
if (iFile < 0 || static_cast<size_t>(iFile) >= changes_.size()) return nullptr;
const MockLocalChange& c = changes_[iFile];
*pEChangeType = c.changeType;
*pEFilePathType = c.pathType;
return c.file.c_str();
}
// isteamremotestorage.h:GetFileTimestamp / FilePersisted
int64_t getFileTimestamp(const char* pchFile) const {
auto it = local_.find(pchFile);
return it == local_.end() ? -1 : static_cast<int64_t>(it->second.mtime);
}
bool filePersisted(const char* pchFile) const {
auto it = local_.find(pchFile);
return it != local_.end() && !it->second.dirty;
}
const MockWriteComplete& lastWriteComplete() const { return lastWriteComplete_; }
const MockReadComplete& lastReadComplete() const { return lastReadComplete_; }
private:
struct PendingRead {
std::string file;
uint32_t offset = 0;
uint32_t cubToRead = 0;
};
bool commitLocal_(const std::string& name, const std::vector<uint8_t>& data) {
MockFileRec& rec = local_[name];
rec.content = data;
rec.mtime++;
rec.originDevice = deviceId_;
rec.dirty = true;
return true;
}
void removeConflict_(const char* pchFile) {
for (auto it = conflicts_.begin(); it != conflicts_.end();) {
it = (*it == pchFile) ? conflicts_.erase(it) : it + 1;
}
}
uint64_t deviceId_;
std::map<std::string, MockFileRec> local_;
std::map<std::string, MockFileRec> remote_;
std::vector<std::string> remoteDeleted_;
std::vector<MockLocalChange> changes_;
std::vector<std::string> conflicts_;
bool inBatch_ = false;
std::map<std::string, std::vector<uint8_t>> staging_;
std::map<uint64_t, PendingRead> pendingReads_;
uint64_t nextCall_ = 0;
MockWriteComplete lastWriteComplete_;
MockReadComplete lastReadComplete_;
};
} // namespace steam_repro
int main() {
using namespace steam_repro;
MockSteamRemoteStorageSync s(1); // 本机 device 1
const uint8_t localSave[] = {1, 2, 3, 4};
const std::vector<uint8_t> remoteSave = {9, 9, 9, 9};
const std::vector<uint8_t> newerRemote = {7, 7, 7, 7, 7};
uint8_t buf[16] = {0};
// 1. 异步写:返回句柄,完成回调 result == k_EResultOK
uint64_t hw = s.fileWriteAsync("slot1.dat", localSave, 4);
CHECK(hw != 0);
CHECK(s.lastWriteComplete().result == kEResultOK);
// 2. 异步读:FileReadAsyncComplete 按偏移读回正确字节并记录回调字段
uint64_t hr = s.fileReadAsync("slot1.dat", 1, 3);
CHECK(hr != 0);
CHECK(s.fileReadAsyncComplete(hr, buf, 3));
CHECK(buf[0] == 2 && buf[1] == 3 && buf[2] == 4);
CHECK(s.lastReadComplete().offset == 1);
CHECK(s.lastReadComplete().cubRead == 3);
// 3. 无远端变化同步:无冲突、无变更事件
s.sync();
CHECK(!s.hasConflict("slot1.dat"));
CHECK(s.getLocalFileChangeCount() == 0);
// 4. 远端新文件(device 2):同步后本地更新并产生 FileUpdated 事件
s.applyRemoteFile("slot2.dat", remoteSave, 10, 2);
s.sync();
CHECK(s.getLocalFileChangeCount() == 1);
int ctype = 0, ptype = 0;
CHECK(s.getLocalFileChange(0, &ctype, &ptype) != nullptr);
CHECK(ctype == kLocalChangeFileUpdated);
CHECK(ptype == kFilePathAPIFilename);
CHECK(s.fileRead("slot2.dat", buf, 4) == 4);
CHECK(buf[0] == 9);
// 5. 冲突:本机改了 slot1(dirty)且 device 2 也改过
CHECK(s.fileWrite("slot1.dat", localSave, 4)); // 本机 dirty
s.applyRemoteFile("slot1.dat", newerRemote, 20, 2);
s.sync();
CHECK(s.hasConflict("slot1.dat"));
// 6. last-writer-wins:远端 mtime 更新 → 内容取远端
s.resolveConflictLastWriterWins("slot1.dat");
CHECK(!s.hasConflict("slot1.dat"));
CHECK(s.fileRead("slot1.dat", buf, 5) == 5);
CHECK(buf[0] == 7);
// 7. keep-local:本机优先,内容保留本机
CHECK(s.fileWrite("slot1.dat", localSave, 4));
s.applyRemoteFile("slot1.dat", newerRemote, 30, 2);
s.sync();
CHECK(s.hasConflict("slot1.dat"));
s.resolveConflictKeepLocal("slot1.dat");
CHECK(!s.hasConflict("slot1.dat"));
CHECK(s.fileRead("slot1.dat", buf, 4) == 4);
CHECK(buf[0] == 1);
// 8. 远端删除:同步后产生 FileDeleted 变更事件
s.applyRemoteDelete("slot2.dat");
s.sync();
int dcount = 0;
for (int i = 0; i < s.getLocalFileChangeCount(); ++i) {
int t = 0, p = 0;
const char* fn = s.getLocalFileChange(i, &t, &p);
if (fn != nullptr && t == kLocalChangeFileDeleted) ++dcount;
}
CHECK(dcount == 1);
CHECK(s.fileRead("slot2.dat", buf, 4) == -1);
// 9. 批量原子提交:Begin → 写两个文件 → End → 全部可见
CHECK(s.beginFileWriteBatch());
CHECK(s.fileWrite("batch_a.dat", localSave, 4));
CHECK(s.fileWrite("batch_b.dat", remoteSave.data(), 4));
CHECK(s.endFileWriteBatch());
CHECK(s.fileExists("batch_a.dat"));
CHECK(s.fileExists("batch_b.dat"));
// 10. 批量中途丢弃:文件不落盘
CHECK(s.beginFileWriteBatch());
CHECK(s.fileWrite("ghost.dat", localSave, 4));
s.abortBatch();
CHECK(s.fileRead("ghost.dat", buf, 4) == -1);
// 11. 未 Begin 就 End 返回 false
CHECK(!s.endFileWriteBatch());
// 12. FilePersisted:dirty 时 false,同步上传后 true
CHECK(s.fileWrite("upload.dat", localSave, 4)); // 本地新建,dirty
CHECK(!s.filePersisted("upload.dat"));
s.sync(); // 上传本地脏文件
CHECK(s.filePersisted("upload.dat"));
// 13. 远端更新后 GetFileTimestamp 反映远端 mtime
CHECK(s.getFileTimestamp("slot2.dat") == -1); // 已删除
s.applyRemoteFile("slot2.dat", remoteSave, 55, 2);
s.sync();
CHECK(s.getFileTimestamp("slot2.dat") == 55);
return lab::report("04-2 存档同步与冲突");
}
本机实测(Apple clang 16,clang++ -std=c++20 -Wall):编译通过(零警告),断言 42/42 通过。
小结
- 异步读写:句柄 + 回调,偏移量分片读取。
- 变更事件:其他设备更新/删除会进本地变更队列。
- 冲突:本地脏 + 远端被改 → 显式解决;last-writer-wins 或 keep-local。
- 批量提交:Begin/End 原子性,中途丢弃不落盘。
阅读导航:上一节:4.1 云存储机制 · 下一节:4.3 云存储与游戏设计 。
继续阅读
探索更多技术文章
浏览归档,发现更多关于系统设计、工具链和工程实践的内容。