Roblox离线技能

Roblox离线技能 是做什么的？

目的

使用本技能来构建和审查可靠的Roblox玩家数据系统，以及针对玩家离线时间计算的进度系统。它涵盖了架构、实现、测试、运维和恢复。这是为AI代理提供的指导，而非一个已部署的持久化框架。

触发条件

当任务涉及以下内容时，使用本技能：

• 保存、加载、重置、迁移、恢复或检查玩家数据。
• DataStoreService、标准DataStore、OrderedDataStore、MemoryStoreService、Open Cloud DataStores或Creator Hub Data Stores Manager。
• 玩家配置文件、货币、背包、宠物、升级、地块、农作物、机器、生成器、排行榜和持久化设置。
• 会话所有权、会话锁定、自动保存、重试、请求预算、限流、PlayerRemoving或BindToClose。
• 离线收益、挂机收入、农场计时器、生产、冷却时间或重连后的进度。
• 数据丢失、过时写入、重复奖励、损坏记录、购买收据或架构迁移。

不要将本技能用于不涉及持久化玩家数据的无关UI、地图、动画、战斗或通用游戏玩法任务。

核心事实

1. DataStoreService提供持久化的Roblox云存储。通过服务器代码访问，需要Roblox服务连接。
2. Creator Hub Data Stores Manager是一个用于查看和管理数据的仪表板。它不是Luau服务或运行时数据库API。
3. MemoryStoreService提供临时的跨服务器数据。条目会过期，它不是永久性的玩家配置文件存储。
4. OrderedDataStore用于有序的数字值，通常是持久化的排行榜分数。它不是一个完整的玩家配置文件。
5. 服务器内存是活动服务器的易失性工作副本。如果在成功保存前进程退出，它可能会丢失。
6. 离线进度通常指玩家返回后由服务器计算的有上限的追赶。它并不意味着在无活跃服务器的情况下，私有世界继续模拟。
7. 完全断开连接的客户端无法写入Roblox云DataStore。不要承诺一个正常的已发布Roblox体验可以在没有连接的情况下继续游戏并保存到云。
8. DataStoreService调用应位于服务器脚本或被服务器脚本require的ModuleScript中。切勿从本地脚本保存规范数据。
9. UpdateAsync是一个读取-修改-写入操作。它本身不实现会话锁定。
10. 一次成功的请求并不能证明返回的配置文件在结构上有效或与当前架构兼容。
11. 加载失败不等同于键缺失或新玩家。
12. 除非目标体验确实在Studio中运行过，否则切勿声称代码已在Roblox Studio中测试过。

必需工作流

1. 编辑前检查

检查实际体验、文件、脚本、ModuleScript、远程事件、包和可用的Studio集成。

确定：

• 每个DataStore名称、作用域、键构建器、键前缀和存储适配器。
• 所有GetAsync、SetAsync、UpdateAsync、IncrementAsync、RemoveAsync、版本和列表调用。
• PlayerAdded、PlayerRemoving、BindToClose、自动保存任务、购买收据处理器以及每个配置键的每个写入器。
• 当前架构、默认模板、迁移版本以及配置文件变为可写入的确切点。
• 项目是使用原生DataStoreService、第三方配置文件库还是自定义包装器。
• 目前如何处理配置文件所有权、重试、同键排序和关闭。
• 用户所指的“离线”是什么意思：离线时间追赶、临时服务中断、模拟测试还是完全断开连接的游戏。

不要仅凭截图、仓库名称或几个孤立的代码片段来推断架构。除非有证据表明需要更改，否则请保留正在工作的系统。

2. 验证Roblox行为

使用references/official-roblox-sources.md作为来源索引。在编码前，重新查阅当前Roblox Creator Hub文档，了解API签名、配额、服务行为、配置和弃用信息。

使用Roblox文档了解引擎保证。对于第三方包，检查目标项目中安装的确切版本，并验证该包自身的API。不要凭记忆或旧示例发明库方法。

3. 按需求选择存储

需求	正确的起点
持久的玩家进度	通过DataStoreService或维护的配置文件层的标准DataStore
持久的数字排名	OrderedDataStore
临时的共享跨服务器状态	MemoryStoreService
当前服务器的实时配置文件	服务器内存
检查或恢复已存储的条目	Creator Hub Data Stores Manager和版本API
外部管理	通过可信后端的Open Cloud
离线时间进度	持久配置文件加上服务端追赶计算
完全断开连接的独立游戏	正常Roblox云DataStore不提供

当配置文件合适且其字段需要一致更新时，优先使用一个稳定的、基于UserId的配置文件键。仅在真正因大小、吞吐量或访问模式原因时才进行拆分。不要为每个玩家创建一个DataStore。

4. 安全加载和拥有配置文件

只有在所选架构下成功加载并获得独占所有权后，配置文件才变为可写入状态。

1. 当服务器收到PlayerAdded时开始加载。
2. 使用现有的持久化层获取配置文件/会话锁。
3. 区分有效的键缺失结果与网络故障、限流、会话冲突、格式错误数据和不受支持的架构。
4. 验证负载并应用有序、确定性的迁移。
5. 仅在所有必需步骤成功完成后，才将配置文件发布为就绪状态。
6. 让服务器游戏玩法通过受控方法修改服务器拥有的工作副本。
7. 如果配置文件库报告所有权已结束，立即停止修改。

切勿在瞬态加载失败后创建可写入的默认配置文件。这可能会覆盖回归玩家的真实数据。

5. 使用排序和有界重试进行保存

• 使用pcall或项目已建立的错误层处理网络调用。
• 仅重试瞬态错误，使用有界的指数退避和随机抖动。
• 不要永久重试无效参数或永久性故障。
• 按键序列化写入。一个旧的延迟重试不得覆盖较新的成功保存。
• 将可重试操作设计为幂等的，因为失败的响应可能使写入结果不确定。
• 当新值依赖于当前存储状态或可能存在并发写入时，使用UpdateAsync。
• 当已建立独占所有权和替换语义时，SetAsync适用于有意的全值替换。不要普遍禁止调用它。
• 保持UpdateAsync转换回调具有确定性、非yielding，并且无外部副作用。切勿在回调内部执行等待、HTTP调用、远程调用、收据授予、分析或创建实例等操作。
• 从UpdateAsync转换返回nil会取消写入。
• 观察当前的请求预算和限流行为。UpdateAsync会消耗读取和写入预算。
• 错开自动保存。不要每帧保存，也不要用每次微小的游戏事件触发保存。

6. 正确实现离线进度

在构建离线奖励系统之前，请阅读references/offline-progression.md和examples/offline-progress.luau。

服务器必须：

1. 加载并验证配置文件。
2. 确认独占会话所有权。
3. 读取保存的时间戳和服务器拥有的生产输入。
4. 获取当前服务器端纪元时间。
5. 计算非负的经过时间，并将其限制在配置的最大值内。
6. 从已验证的所有权和服务器端定义中推导生产率。
7. 应用配置的离线效率、资格和奖励上限。
8. 在配置文件工作副本中一起更新奖励及其相应的模拟时间戳。
9. 通过活跃的配置文件层持久化。
10. 将展示数据复制到客户端。

使用os.time()或其他有文档记录的服务器端纪元时间戳进行跨会话计算。切勿将os.clock()用作纪元时间戳。切勿信任客户端时钟、经过时长、生产率、作物阶段、资产列表或上次领取时间戳。

不要重复奖励同一时间间隔。不要重复计算在线生产。不要为每离线秒运行一个无界循环。有意识地处理缺失、格式错误、零、负和未来的时间戳。

7. 保护开发和生产数据

• 使用单独的已发布开发或暂存体验进行实时DataStore集成测试。
• 仅对该隔离的测试体验启用Studio访问API服务。
• Roblox警告，Studio可以访问与实时应用程序相同的DataStore。切勿在正式环境中对该设置启用常规测试。
• 使用模拟或内存适配器进行确定性逻辑测试。模拟不是真实的玩家保存，也不是持久化存储。
• 使用一次性账户和测试键。
• 未经明确的操作员授权、精确的目标识别和恢复计划，不要删除、回滚、重命名或覆盖生产数据。
• 将Open Cloud凭据保留在可信后端。切勿将其暴露在本地脚本、客户端、公共仓库或提示上下文中。

8. 诚实验证和报告

使用references/test-matrix.md。涵盖首次和返回配置文件、加载失败、冲突、过时所有者、写入顺序、重试、自动保存、关闭、崩溃恢复、格式错误负载、迁移、离线上限、重复领取和重复收据。

准确报告验证级别：

• 静态审查
• 纯单元测试
• 模拟/内存集成测试
• 已发布暂存DataStore测试
• Roblox Studio运行时测试
• 多服务器/会话冲突测试

这些是不同的检查项。如果Studio或暂存环境不可用，请说明运行时验证尚未完成。

不可商榷的禁止事项

• 切勿从本地脚本保存规范的玩家数据。
• 切勿信任客户端提供的UserId、余额、价格、背包、所有权、奖励率、时间戳、经过时间或购买结果。
• 切勿将瞬态加载错误视为新玩家。
• 切勿将MemoryStoreService或服务器RAM用作永久配置文件存储。
• 切勿在新体验中使用DataStore2。Roblox目前将其标识为旧版库。
• 切勿在UpdateAsync回调中yield或执行副作用。
• 切勿让同键写入和重试发生竞态。
• 切勿将强制抢夺活跃会话作为正常重试手段。
• 切勿在配置文件库管理的键上写入原始值。
• 切勿声称UpdateAsync单独实现了会话锁定。
• 切勿运行无界的离线模拟循环。
• 切勿暴露Open Cloud密钥。
• 未经明确授权和恢复计划，切勿破坏性地修改生产数据。
• 切勿声称进行了但实际未进行的Studio测试。

参考地图

仅加载当前任务所需的文档：

• references/architecture-and-services.md：服务角色、DataStore Manager、Open Cloud和存储选择。
• references/player-data-lifecycle.md：配置文件生命周期、内存工作副本、就绪状态、离开和关闭。
• references/session-locking-and-failures.md：会话所有权、UpdateAsync、写入顺序、重试、限流和未知结果。
• references/offline-progression.md：挂机奖励、作物计时器、生成器、时间戳数学、上限和断连限制。
• references/studio-testing.md：API访问、暂存、模拟和安全测试隔离。
• references/schema-migrations-and-recovery.md：序列化、架构版本、迁移、版本历史和恢复。
• references/security-and-purchases.md：远程事件、服务器权威、收据、Open Cloud密钥和数据隐私。
• references/performance-and-limits.md：有记录的限值、预算、吞吐量和运维调优。
• references/library-selection.md：原生DataStoreService、官方参考代码和第三方包评估。
• references/game-patterns.md：配置文件、排行榜、地块、挂机系统、交易和购买。
• references/test-matrix.md：验证场景。
• references/official-roblox-sources.md：仅限Roblox Creator Hub来源链接。
• examples/profile-template.luau：说明性的配置文件形状。
• examples/offline-progress.luau：纯有界离线奖励计算。

必需的实现响应

对于实现和调试任务：

1. 总结在实际项目中找到的现有架构。
2. 解释预期的数据流和最小安全变更。
3. 列出要创建或修改的确切文件。
4. 提供完整的、上下文感知的代码，而不是孤立的片段。
5. 解释设置、暂存和任何架构迁移步骤。
6. 报告实际测试和剩余的运行时检查。
7. 说明重要的限制和风险，不要虚构保证。

尊重用户要求的语言和风格。保留工作的系统。不要添加无关功能，也不要出于风格原因替换现有的持久化库。