Roblox 離線技能
目的
使用此技能建構與審查可靠的 Roblox 玩家資料系統，以及根據玩家離開遊戲的時間計算進度。此技能涵蓋架構、實作、測試、營運與復原。這是為 AI 代理提供的指導方針，而非已部署的持久化框架。
觸發條件
當任務涉及以下項目時使用此技能：
- 儲存、載入、重置、遷移、還原或檢視玩家資料。
- DataStoreService、標準 DataStore、OrderedDataStore、MemoryStoreService、Open Cloud DataStore 或 Creator Hub Data Stores Manager。
- 玩家設定檔、貨幣、物品欄、寵物、升級、地塊、農作物、機器、生產設備、排行榜與持久化設定。
- 工作階段所有權、工作階段鎖定、自動儲存、重試、請求配額、節流、PlayerRemoving 或 BindToClose。
- 離線收益、閒置收入、農場計時器、生產、冷卻時間或重新連線後的進度。
- 資料遺失、過時寫入、重複獎勵、損毀記錄、購買收據或資料綱要遷移。
除非任務觸及持久化玩家資料，否則請勿將此技能用於不相關的 UI、地圖、動畫、戰鬥或一般遊戲玩法任務。
核心事實
- DataStoreService 提供持久的 Roblox 雲端儲存。需由伺服器程式碼存取，且需要 Roblox 服務連線。
- Creator Hub Data Stores Manager 是用於檢視與管理資料的儀表板。它不是 Luau 服務或執行時期資料庫 API。
- MemoryStoreService 提供暫時的跨伺服器資料。條目會過期，且不是永久性的玩家設定檔儲存。
- OrderedDataStore 用於有序的數值，通常是持久的排行榜分數。它不是完整的玩家設定檔。
- 伺服器記憶體是活躍伺服器的易失性工作副本。若在成功儲存前處理程序結束，則可能遺失。
- 離線進度通常指玩家返回後由伺服器計算的有限追趕（catch-up）。不表示在沒有活躍伺服器的情況下，私人世界會繼續模擬。
- 完全斷線的客戶端無法寫入 Roblox 雲端 DataStore。請勿承諾一般已發布的 Roblox 體驗能在無連線狀態下持續遊玩並進行雲端儲存。
- DataStoreService 呼叫應位於伺服器 Script 或由伺服器 Script 所需的 ModuleScript 中。絕不從 LocalScript 儲存規範資料。
- UpdateAsync 是一種讀取-修改-寫入操作。它本身並不實作工作階段鎖定。
- 成功的請求不代表傳回的設定檔在結構上有效或與當前綱要相容。
- 載入失敗不等於缺少金鑰或新玩家。
- 除非目標體驗確實已在 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. 安全地載入與擁有設定檔
只有在根據所選架構成功載入並取得獨佔擁有權後，設定檔才變得可寫入。
- 伺服器收到 PlayerAdded 事件時開始載入。
- 使用現有的持久化層取得設定檔/工作階段的鎖定。
- 區分有效的「缺少金鑰」結果與網路故障、節流、工作階段衝突、格式錯誤的資料及不支援的綱要。
- 驗證載入的資料，並套用有序、確定性的遷移。
- 僅在所有必要步驟成功完成後，才將設定檔標記為「就緒」。
- 讓伺服器遊戲玩法透過受控的方法修改伺服器擁有的工作副本。
- 如果設定檔函式庫報告所有權已結束，立即停止修改。
在短暫的載入失敗後，絕不建立可寫入的預設設定檔。這可能會覆寫回歸玩家的真實資料。
5. 使用順序與有限重試進行儲存
- 使用 pcall 或專案既有的錯誤處理層處理網路呼叫。
- 僅對暫時性錯誤進行重試，使用有限的指數退避與隨機抖動。
- 不要對無效引數或永久性失敗進行無限重試。
- 序列化每個金鑰的寫入。舊的延遲重試不得覆寫較新的成功儲存。
- 設計可重試的操作為冪等，因為失敗的回應可能使寫入結果不確定。
- 當新值取決於當前儲存狀態或可能發生並發寫入時，使用 UpdateAsync。
- 當已建立獨佔擁有權與替換語義時，SetAsync 可用於有意的完整值替換。不要將其普遍視為禁止。
- 保持 UpdateAsync 轉換回呼（transform callback）為確定性、非暫停（non-yielding）且無外部副作用。絕不在回呼內部執行等待（waits）、HTTP 呼叫、遠端呼叫、收據授予、分析或建立 Instance。
- UpdateAsync 轉換回呼回傳 nil 會取消寫入。
- 遵守當前的請求配額與節流行為。UpdateAsync 會同時消耗讀取與寫入配額。
- 錯開自動儲存。不要每一影格或為每一個微小的遊戲事件都進行儲存。
6. 正確實作離線進度
在建構離線獎勵系統前，請閱讀 references/offline-progression.md 與 examples/offline-progress.luau。
伺服器必須：
- 載入與驗證設定檔。
- 確認獨佔的工作階段所有權。
- 讀取儲存的時間戳記與伺服器擁有的生產輸入。
- 取得當前的伺服器端紀元時間（epoch time）。
- 計算非負的經過時間，並限制在設定的最大值內。
- 從驗證過的所有權與伺服器端定義推導出生產速率。
- 套用設定的離線效率、資格與獎勵上限。
- 在設定檔工作副本中一併更新獎勵與其對應的模擬時間戳記。
- 透過活躍的設定檔層進行持久化。
- 將顯示用資料複寫至客戶端。
使用 os.time() 或其他有文件記錄的伺服器端紀元時間戳記進行跨工作階段計算。絕不使用 os.clock() 作為紀元時間戳記。絕不相信客戶端時鐘、經過時間、生產速率、作物階段、資產清單或最後領取時間戳記。
不要重複發放相同時間間隔的獎勵。不要重複計算線上生產。不要為每一個離線秒數執行無限迴圈。需審慎處理缺失、格式錯誤、零、負數及未來的時間戳記。
7. 保護開發與正式環境資料
- 使用單獨發布的開發或暫存（staging）體驗進行即時的 DataStore 整合測試。
- 僅在該隔離的測試體驗上啟用 Studio Access to API Services。
- Roblox 警告 Studio 可以存取與正式應用程式相同的 DataStore。絕不能為常規測試在正式環境上啟用此設定。
- 使用模擬（mock）或記憶體內介面卡進行確定性的邏輯測試。模擬不是真正的玩家儲存，也不是持久化儲存。
- 使用可丟棄的帳號與測試金鑰。
- 若無明確的操作者授權、精確的目標識別與復原計畫，請勿刪除、還原、重新命名或覆寫正式環境資料。
- 將 Open Cloud 憑證保存在可信的後端。絕不能將其暴露在 LocalScript、客戶端、公開儲存庫或提示上下文（prompt context）中。
8. 誠實驗證與報告
使用 references/test-matrix.md。涵蓋首次與返回的設定檔、載入失敗、衝突、過時擁有者、寫入順序、重試、自動儲存、關機、崩潰復原、格式錯誤的資料、遷移、離線上限、重複領取及重複收據。
準確報告驗證等級：
- 靜態審查
- 純單元測試
- 模擬/記憶體內整合測試
- 已發布的暫存 DataStore 測試
- Roblox Studio 執行時期測試
- 多伺服器/工作階段衝突測試
這些是不同的檢查。如果無法使用 Studio 或暫存環境，請說明執行時期驗證仍有待完成。
不可協商的禁止事項
- 絕不從 LocalScript 儲存規範的玩家資料。
- 絕不相信客戶端提供的 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：純粹的有限離線獎勵計算。
要求的實作回應
對於實作與除錯任務：
- 總結在實際專案中找到的現有架構。
- 解釋預期的資料流程與最小安全變更。
- 列出需要建立或修改的確切檔案。
- 提供完整且具情境感知的程式碼，而非零散的片段。
- 解釋設定、暫存環境及任何綱要遷移步驟。
- 報告實際的測試與剩餘的執行時期檢查。
- 說明重要的限制與風險，不要憑空編造保證。
尊重使用者要求的語言與風格。保留運作中的系統。不要新增不相關的功能，或因為風格原因取代現有的持久化函式庫。