Tóm tắt
Dùng DataStoreService từ một Script server: tải dữ liệu người chơi bằng GetAsync khi họ vào, giữ nó trong một table khi họ chơi, và lưu bằng UpdateAsync theo chu kỳ, khi họ rời đi (PlayerRemoving) và khi server tắt (game:BindToClose). Bọc mỗi lệnh gọi trong pcall và thử lại vài lần khi thất bại.
- Để test trong Studio, hãy publish place và bật File > Experience Settings > Security > Enable Studio Access to API Services trong một game test riêng: Studio dùng cùng dữ liệu với các server thật.
- Nếu dữ liệu của người chơi không tải được, đừng bao giờ lưu người chơi đó. Lưu các giá trị mặc định sẽ ghi đè tiến trình thật của họ.
- Giữ một table cho mỗi người chơi dưới một key, ví dụ
User_12345, và lưu theo chu kỳ, không phải mỗi lần có thay đổi. - Với trao đổi vật phẩm hoặc vật phẩm trả phí, hãy thêm khóa phiên (session lock) để hai server không thể cùng lưu một người chơi.
Trong trang này
- Quyền truy cập Studio
- DataStore hoạt động thế nào
- GetAsync và UpdateAsync
- 1. Module PlayerData
- Module được dựng thế nào
- 2. Làm việc với dữ liệu
- 3. Cảnh báo
- 4. Kiểm tra trong Studio
- Vì sao dữ liệu bị mất
- Khóa phiên
- Giới hạn
- Phiên bản và sao lưu
- Common errors
- With RoCode
- Câu hỏi thường gặp
- Nguồn và tài liệu đọc thêm
Trước khi bắt đầu: bật quyền truy cập cho Studio trong bản sao test
Game chạy trong Studio không thể truy cập data store cho đến khi bạn cho phép. Quyền này có một cái bẫy mà tài liệu Roblox cảnh báo: khi đó Studio đọc và ghi cùng data store với game thật, nên một bài test reset xu của bạn trong Studio cũng reset nó trong game thật, và một lỗi trong code test có thể làm hỏng key của người chơi thật.
- Tạo một bản sao test. Lưu place ra file, mở bản sao, chọn File > Publish to Roblox As và bấm Create new game. Đừng thêm nó như một place bên trong game thật: mọi place của cùng một game dùng chung data store.
- Trong bản sao test, mở File > Experience Settings và chuyển sang Security.
- Bật Enable Studio Access to API Services và bấm Save.
Lệnh gọi data store chỉ chạy trong Script server; LocalScript nào thử sẽ bị lỗi, nên client không thể ghi dữ liệu đã lưu. Khi một nút bấm cần thay đổi nó, client nhờ server qua RemoteEvent, và server quyết định (xem hướng dẫn về RemoteEvent, bằng tiếng Anh).
Data store lưu dữ liệu người chơi thế nào
Data store là một tập key và giá trị có tên trên server của Roblox, dùng chung cho mọi server và mọi place trong game của bạn. DataStoreService:GetDataStore("PlayerData") trả về một kho như vậy.
Khuyến nghị của Roblox gói gọn trong quy tắc một kho cho dữ liệu người chơi, một key cho mỗi người chơi, một table trong mỗi key. Tạo key từ UserId của người chơi, ví dụ User_12345, và không bao giờ từ tên, vì họ có thể đổi tên. Mẫu cố định User_{UserId} cũng cho phép quy trình tự động của Roblox về quyền được lãng quên tìm thấy dữ liệu của người chơi, nếu bạn thiết lập nó.
| Kiểu | Lưu được? | Ghi chú |
|---|---|---|
| Số, chuỗi, boolean, buffer | Có | Chuỗi phải là UTF-8 hợp lệ. Đừng lưu inf hoặc nan. |
| Table | Có | Nếu mọi thứ bên trong cũng lưu được. Table có key số không bắt đầu từ 1 (nên độ dài của nó là 0) sẽ quay lại với các key đó dưới dạng chuỗi. |
Instance, Vector3, CFrame, Color3 | Không | Lưu sẽ báo lỗi hoặc ghi ra nil. Hãy lưu tên vật phẩm, hoặc vị trí bằng ba con số. |
Mỗi yêu cầu là một lệnh gọi web có thể thất bại, mất thời gian và tiêu vào ngân sách theo phút. Vì vậy các hệ thống lưu đáng tin cậy chỉ đọc dữ liệu một lần khi người chơi vào, giữ nó trong một table trên server khi họ chơi, và thỉnh thoảng ghi ngược lại.
GetAsync, SetAsync hay UpdateAsync: chọn cái nào
| Phương thức | Làm gì | Dùng cho |
|---|---|---|
GetAsync(key) | Đọc giá trị. Kết quả được cache trên server này trong 4 giây. | Tải dữ liệu người chơi |
SetAsync(key, value) | Ghi đè giá trị mà không đọc nó. Một lần ghi. | Key mới hoặc giá trị không phụ thuộc vào giá trị cũ |
UpdateAsync(key, callback) | Đọc giá trị mới nhất, đưa nó cho hàm của bạn và ghi lại thứ hàm trả về. Một lần đọc và một lần ghi. | Lưu dữ liệu người chơi và mọi key mà nhiều server có thể ghi |
IncrementAsync(key, delta) | Cộng một số nguyên vào số nguyên đã lưu. | Bộ đếm |
RemoveAsync(key) | Xóa key và trả về giá trị cũ. Các phiên bản trước vẫn có thể liệt kê và đọc được. | Xóa dữ liệu người chơi |
SetAsync ghi mù: nếu hai server lưu cùng một key gần như cùng lúc, lần ghi cuối thắng, dù nó chứa gì. UpdateAsync đọc giá trị hiện tại trước, và nếu trong lúc đó có server khác ghi vào, Roblox chạy lại hàm của bạn với giá trị mới. Roblox khuyên dùng nó bất cứ khi nào lần ghi phụ thuộc vào giá trị hiện tại hoặc nhiều server có thể ghi vào key, mà dữ liệu người chơi chính là như vậy. Hàm có ba quy tắc:
- Nó không được nhường luồng (yield): không có
task.wait()hay lệnh gọi data store nào khác bên trong. - Nó có thể chạy hơn một lần, nên chỉ được tính giá trị mới và không bao giờ trao vật phẩm hay kích hoạt sự kiện.
- Trả về
nilsẽ hủy lần ghi. Module dùng điều này để không ghi đè dữ liệu do phiên bản game mới hơn lưu.
Bước 1: tạo module PlayerData
ModuleScript này là code duy nhất nói chuyện với data store. Nó tải dữ liệu người chơi khi họ vào, giữ trong bộ nhớ, lưu mỗi 180 giây, khi họ rời đi và khi server tắt, và từ chối lưu những người chưa tải được dữ liệu.
- Trong Explorer, rê chuột lên ServerScriptService, bấm + và chèn một ModuleScript. Đổi tên nó thành
PlayerDatavà thay nội dung bằng code bên dưới. - ModuleScript chỉ chạy khi có script nào đó nạp nó (require). Chèn vào ServerScriptService một Script tên
Mainvới dòng này:local PlayerData = require(game:GetService("ServerScriptService").PlayerData). Các script server khác nạp nó theo cùng cách. - Sửa
DEFAULTSvà kiểuDatacho hợp với game của bạn, giữ mỗi trường là số, chuỗi, boolean hoặc table.
ServerScriptService
PlayerData ModuleScript new
Main Script new
StarterPlayer
StarterPlayerScripts
DataWarning LocalScript new
-- PlayerData: tải dữ liệu người chơi khi họ vào, giữ trong bộ nhớ
-- và lưu theo chu kỳ, khi họ rời đi và khi server tắt.
-- Các script server khác đọc và thay đổi dữ liệu qua PlayerData.Get(player).
local Players = game:GetService("Players")
local DataStoreService = game:GetService("DataStoreService")
local RunService = game:GetService("RunService")
local STORE_NAME = "PlayerData"
local SCHEMA_VERSION = 2 -- tăng lên khi hình dạng dữ liệu thay đổi, và thêm một bước vào migrate()
local AUTOSAVE_SECONDS = 180
-- Trong Studio, lệnh gọi thất bại sẽ bỏ cuộc ngay, nên bài test không có quyền truy cập kho chạy nhanh
local MAX_ATTEMPTS = if RunService:IsStudio() then 1 else 4
local FIRST_RETRY_SECONDS = 1 -- nhân đôi sau mỗi lần thất bại: 1, 2, 4
export type Data = {
SchemaVersion: number,
Coins: number,
Level: number,
Inventory: { string },
}
-- Thứ một người chơi hoàn toàn mới bắt đầu với
local DEFAULTS: { [string]: any } = {
Coins = 0,
Level = 1,
Inventory = {},
}
type Session = {
key: string,
userId: number,
data: Data,
canSave: boolean, -- false nếu tải thất bại: dữ liệu mặc định không được thay thế tiến trình thật
}
-- Được gọi bên trong mỗi pcall bên dưới, nên place chưa publish
-- (không có quyền truy cập kho) vẫn tải người chơi với dữ liệu mặc định
local function store(): DataStore
return DataStoreService:GetDataStore(STORE_NAME)
end
local sessions: { [Player]: Session } = {}
local pendingSaves: { [string]: number } = {} -- các lần lưu vẫn đang chạy, theo key
local loadedEvent = Instance.new("BindableEvent")
local PlayerData = {}
-- Kích hoạt kèm người chơi khi dữ liệu của họ sẵn sàng. Lấy table qua PlayerData.Get(player):
-- table gửi qua BindableEvent đến nơi dưới dạng bản sao, và sửa nó sẽ không thay đổi gì.
PlayerData.Loaded = loadedEvent.Event
local function deepCopy(value: any): any
if type(value) ~= "table" then
return value
end
local copy = {}
for key, item in value do
copy[key] = deepCopy(item)
end
return copy
end
local function defaultData(): Data
local data = deepCopy(DEFAULTS) -- bản sao mới, để người chơi không bao giờ dùng chung một table Inventory
data.SchemaVersion = SCHEMA_VERSION
return data
end
-- Đưa dữ liệu đã lưu về schema hiện tại. Trả về nil nếu không thể dùng an toàn.
local function migrate(saved: any): Data?
if type(saved) ~= "table" then
return nil
end
local version = tonumber(saved.SchemaVersion) or 1
if version > SCHEMA_VERSION then
return nil -- được lưu bởi phiên bản game mới hơn: không tải và không ghi đè ở đây
end
-- Mỗi thay đổi schema một bước, từ cũ đến mới
if version < 2 then
-- Ví dụ: ở phiên bản 1 tiền tệ tên là Gold. Chỉ sao chép nó nếu chưa có Coins,
-- để dữ liệu cũ đã có Coins nhưng chưa có SchemaVersion giữ nguyên giá trị.
if saved.Coins == nil then
saved.Coins = saved.Gold
end
saved.Gold = nil
end
-- Thêm các trường xuất hiện sau lần lưu cuối của người chơi, và thay các giá trị sai kiểu
for field, default in DEFAULTS do
if type(saved[field]) ~= type(default) then
saved[field] = deepCopy(default)
end
end
saved.SchemaVersion = SCHEMA_VERSION
return saved
end
-- Chạy lệnh gọi data store trong pcall. Nếu thất bại, đợi rồi thử lại, mỗi lần nhân đôi
-- thời gian chờ và thêm chút ngẫu nhiên, để các server không cùng thử lại một lúc.
local function withRetries(label: string, call: () -> any): (boolean, any)
for attempt = 1, MAX_ATTEMPTS do
local ok, result = pcall(call)
if ok then
return true, result
end
warn(`{label} failed (attempt {attempt} of {MAX_ATTEMPTS}): {result}`)
if attempt < MAX_ATTEMPTS then
local waitTime = FIRST_RETRY_SECONDS * 2 ^ (attempt - 1)
task.wait(waitTime + math.random() * waitTime / 2)
end
end
return false, nil
end
local function save(session: Session): boolean
if not session.canSave then
return false
end
local key = session.key
pendingSaves[key] = (pendingSaves[key] or 0) + 1
local newerSchema = false
local ok = withRetries(`Save {key}`, function()
return store():UpdateAsync(key, function(current: any)
if type(current) == "table" and (tonumber(current.SchemaVersion) or 1) > SCHEMA_VERSION then
newerSchema = true
return nil -- trả về nil sẽ hủy lần ghi
end
-- Ghi cả table hiện tại, kèm dấu UserId của người chơi
return session.data, { session.userId }
end)
end)
local left = (pendingSaves[key] or 1) - 1
if left > 0 then
pendingSaves[key] = left
else
pendingSaves[key] = nil
end
if newerSchema then
session.canSave = false
warn(`{key} was saved by a newer version of the game, so this server stopped saving it`)
end
return ok and not newerSchema
end
local function startAutosave(player: Player, session: Session)
task.spawn(function()
-- Bắt đầu ở một thời điểm ngẫu nhiên trong chu kỳ, để các server không cùng lưu một lúc
task.wait(math.random() * AUTOSAVE_SECONDS)
while sessions[player] == session do
save(session)
task.wait(AUTOSAVE_SECONDS)
end
end)
end
local function load(player: Player)
local key = "User_" .. player.UserId
-- Nếu người chơi vừa rời server này rồi quay lại, trước hết đợi lần lưu cuối hoàn tất
while pendingSaves[key] do
task.wait()
end
local ok, saved = withRetries(`Load {key}`, function()
return store():GetAsync(key)
end)
if player.Parent ~= Players then
return -- rời đi trong lúc đang tải: không có gì thay đổi, không có gì để lưu
end
local data: Data? = nil
if ok then
data = if saved == nil then defaultData() else migrate(saved)
end
local session: Session = {
key = key,
userId = player.UserId,
data = data or defaultData(),
canSave = data ~= nil,
}
if not session.canSave then
warn(`Could not load {key}. {player.Name} is playing on default data that will not be saved.`)
end
sessions[player] = session
player:SetAttribute("DataLoaded", session.canSave) -- GUI có thể đọc giá trị này và cảnh báo người chơi
startAutosave(player, session)
loadedEvent:Fire(player)
end
local function endSession(player: Player)
local session = sessions[player]
if not session then
return
end
sessions[player] = nil -- dừng vòng tự động lưu, và gọi lại lần nữa sẽ không làm gì
save(session)
end
-- Table dữ liệu đang dùng của người chơi, hoặc nil khi chưa tải xong. Chỉ thay đổi nó từ script server.
function PlayerData.Get(player: Player): Data?
local session = sessions[player]
return if session then session.data else nil
end
-- True khi dữ liệu người chơi đã tải và sẽ được lưu. Kiểm tra trước mọi giao dịch bán.
function PlayerData.CanSave(player: Player): boolean
local session = sessions[player]
return session ~= nil and session.canSave
end
-- Lưu ngay, không đợi bộ hẹn giờ, cho những khoảnh khắc quan trọng như mua hàng.
-- Nhường luồng và trả về true khi lưu thành công.
function PlayerData.SaveNow(player: Player): boolean
local session = sessions[player]
return session ~= nil and save(session)
end
Players.PlayerAdded:Connect(load)
Players.PlayerRemoving:Connect(endSession)
for _, player in Players:GetPlayers() do
task.spawn(load, player) -- người chơi đã vào trước khi module này được nạp lần đầu
end
game:BindToClose(function()
-- Server cho các hàm này 30 giây, nên lưu tất cả mọi người cùng lúc
for player in sessions do
task.spawn(endSession, player)
end
-- Sau đó đợi mọi lần lưu còn đang chạy, kể cả những lần bắt đầu trong PlayerRemoving
while next(pendingSaves) do
task.wait()
end
end)
return PlayerData
Khi game đã ra mắt, đừng đổi STORE_NAME và mẫu key User_. Đổi bất kỳ cái nào trong hai sẽ trỏ module tới các key trống, và mọi người chơi sẽ bắt đầu lại từ giá trị mặc định.
Module bảo vệ dữ liệu thế nào
Giá trị mặc định và phiên bản schema
Người chơi mới nhận một bản sao mới của DEFAULTS. Phải là bản sao: nếu mọi người chơi dùng chung một table Inventory, vật phẩm thêm cho một người sẽ xuất hiện ở tất cả mọi người.
Mỗi table đã lưu mang theo SchemaVersion. Thêm một trường không cần phiên bản mới, vì migrate điền các trường còn thiếu từ giá trị mặc định. Đổi tên hoặc sắp xếp lại thì cần: tăng SCHEMA_VERSION và thêm một bước, như ví dụ đổi tên Gold thành Coins (trong game mới, hãy xóa nó và bắt đầu từ 1). Dữ liệu có phiên bản cao hơn của server đến từ một bản phát hành mới hơn đang được triển khai dần, nên các server cũ không đụng tới nó.
Lần tải thất bại không bao giờ được lưu
Quy tắc này chống việc bị xóa sạch dữ liệu. Nếu mọi lần thử tải đều thất bại, người chơi chơi với dữ liệu mặc định, nhưng canSave bằng false, nên các giá trị đó không bao giờ ghi đè tiến trình thật của họ. Module cũng đặt thuộc tính DataLoaded thành false, và bước 3 dùng nó để báo cho người chơi. Ví dụ mẫu của Roblox xử lý lần tải thất bại theo cùng cách và đề xuất điều này thay cho việc kick; nếu bạn muốn kick, hãy gọi player:Kick() kèm thông báo ở chỗ module in cảnh báo.
Thử lại với khoảng chờ tăng dần
withRetries bọc mỗi lệnh gọi trong pcall. Sau một lần thất bại, nó đợi 1, rồi 2, rồi 4 giây, mỗi lần cộng thêm ngẫu nhiên tới một nửa thời gian đó, và dừng sau bốn lần thử (trong Studio là sau một lần, để place không có quyền truy cập kho khởi động ngay). Phần ngẫu nhiên giãn các lần thử lại của nhiều server sau sự cố, còn giới hạn giữ thời gian chờ trong khoảng 10 giây, nằm trong 30 giây mà server có khi tắt. Vì mỗi lần lưu ghi cả table đang dùng qua UpdateAsync, một lần thử lại hoàn tất muộn không thể đưa dữ liệu cũ trở lại.
Khi nào module lưu
| Khi nào | Vì sao |
|---|---|
| Mỗi 180 giây khi người chơi còn trên server | Giới hạn phần mất khi server sập. Lần lưu đầu rơi vào một thời điểm ngẫu nhiên trong chu kỳ, để các server không cùng lưu một lúc. Ví dụ mẫu của Roblox cũng dùng 180 giây. |
Khi người chơi rời đi (PlayerRemoving) | Lần lưu cuối thông thường. Phiên bị xóa trước, nên tự động lưu dừng lại. |
Khi server tắt (game:BindToClose) | Mọi người còn trên server được lưu cùng lúc, và hàm đợi từng lần lưu đang chạy. Roblox cho nó 30 giây. |
Theo yêu cầu, qua PlayerData.SaveNow(player) | Sau những việc không được để mất, ví dụ mua hàng. |
Nếu người chơi vào lại cùng server khi lần lưu cuối của họ vẫn đang chạy, lần tải mới sẽ đợi lần lưu đó xong, nên không thể đọc phải giá trị cũ.
Bước 2: đọc và thay đổi dữ liệu từ các script khác
Mọi script server nạp module đều làm việc với cùng các table:
| Lệnh gọi | Làm gì |
|---|---|
PlayerData.Get(player) | Table dữ liệu đang dùng của người chơi, hoặc nil khi chưa tải xong. Sửa trực tiếp các trường, ví dụ data.Coins += 10, và lần lưu tiếp theo sẽ ghi nhận. |
PlayerData.Loaded | Kích hoạt kèm người chơi khi dữ liệu của họ sẵn sàng, kể cả sau lần tải thất bại. Chỉ truyền người chơi, vì table gửi qua BindableEvent đến nơi dưới dạng bản sao. |
PlayerData.CanSave(player) | false nếu tải thất bại. Kiểm tra trước mọi giao dịch bán: món mua không lưu được sẽ mất khi người chơi rời đi. |
PlayerData.SaveNow(player) | Lưu ngay và trả về true nếu thành công. Có nhường luồng. |
Module là nơi duy nhất chứa dữ liệu đã lưu, còn leaderstats chỉ để hiển thị: dựng nó như trong hướng dẫn bảng xếp hạng, điền từ PlayerData.Get(player) trong handler Loaded và cập nhật cả hai khi giá trị thay đổi. Đừng bao giờ đọc ngược giá trị đã lưu từ leaderstats và đừng bao giờ để một script thứ hai lưu cùng key.
Script nạp module sau khi người chơi đã vào sẽ bỏ lỡ Loaded của họ. Hãy kết nối handler, rồi lặp thêm qua Players:GetPlayers() và xử lý mọi người mà PlayerData.Get(player) đã trả về table.
Thay một script lưu cũ, ví dụ từ hướng dẫn bảng xếp hạng? Giá trị của nó vẫn nằm trong kho và key riêng của nó, nên module này sẽ cho mọi người bắt đầu từ giá trị mặc định. Trước khi chạy, hoặc trỏ STORE_NAME và tiền tố User_ về cái cũ (migrate coi dữ liệu không có SchemaVersion là phiên bản 1 và điền các trường còn thiếu), hoặc chuyển các giá trị cũ sang, rồi xóa script cũ.
Client không bao giờ sửa trực tiếp dữ liệu này. Nút cửa hàng kích hoạt RemoteEvent; server kiểm tra CanSave, so giá với Coins của người chơi, sửa table và gọi SaveNow. Hướng dẫn GUI cửa hàng dựng một giao dịch mua như vậy ở phía server.
Có ví dụ làm sẵn về thêm trường trong hướng dẫn game simulator nhấp chuột: nó thêm PowerLevel và Rebirths vào DEFAULTS và kiểu Data, rồi sửa chúng trong table mà PlayerData.Get trả về. migrate cấp các trường mới cho người chơi có bản lưu cũ.
Bước 3: báo cho người chơi biết dữ liệu không tải được
Người chơi có dữ liệu không tải được cần biết phiên này sẽ không được lưu, để vào lại thay vì chơi phí công. LocalScript này theo dõi thuộc tính DataLoaded và hiện một banner khi nó bằng false.
local Players = game:GetService("Players")
local player = Players.LocalPlayer
local shown = false
local function showWarning()
if shown or player:GetAttribute("DataLoaded") ~= false then
return
end
shown = true
local gui = Instance.new("ScreenGui")
gui.Name = "DataWarning"
gui.ResetOnSpawn = false
local label = Instance.new("TextLabel")
label.AnchorPoint = Vector2.new(0.5, 0)
label.Position = UDim2.new(0.5, 0, 0, 12)
label.Size = UDim2.new(0.8, 0, 0, 48)
label.BackgroundColor3 = Color3.fromRGB(110, 28, 28)
label.TextColor3 = Color3.new(1, 1, 1)
label.TextScaled = true
label.Text = "Your saved progress could not be loaded. Nothing you do in this server will be saved, so rejoin later."
label.Parent = gui
gui.Parent = player:WaitForChild("PlayerGui")
end
-- Server đặt DataLoaded một lần, sau khi thử tải dữ liệu của người chơi này
player:GetAttributeChangedSignal("DataLoaded"):Connect(showWarning)
showWarning()
Bước 4: kiểm tra việc lưu trong Studio
Làm việc này trong bản sao test đã bật quyền truy cập cho Studio.
- Cho bản thân thứ gì đó để lưu. Dưới dòng require trong
Main, thêm:PlayerData.Loaded:Connect(function(player) local data = PlayerData.Get(player) if data then data.Coins += 100 print(player.Name, data.Coins) end end) - Bấm Play. Cửa sổ Output (trong menu Window hoặc ở tab Script) sẽ hiện tên bạn và 100 (ở lần chạy đầu), không có cảnh báo
Could not load. - Bấm Stop. Kết thúc bài test sẽ đóng server, và module lưu bạn trước khi đóng.
- Bấm Play lần nữa. Output phải hiện 200, hơn lần trước 100. Nếu nó lại hiện cùng con số, việc lưu đã thất bại: đọc các cảnh báo phía trên.
- Kiểm tra đường lỗi. Tắt quyền truy cập cho Studio và bấm Play. Sau vài giây thử lại, Output sẽ hiện
Could not load User_...và 100, và banner ở bước 3 xuất hiện. Dừng test, bật lại quyền truy cập và bấm Play: Output sẽ hiện 300, tức 200 đã lưu cộng 100, vì phiên thất bại không bao giờ ghi đè dữ liệu của bạn. - Xóa dòng test khỏi
Main.
Vì sao dữ liệu người chơi bị mất
Đây là những cách thường gặp khiến hệ thống lưu làm mất tiến trình. Module xử lý trong code bốn dòng đầu và dòng về schema; các dòng còn lại phụ thuộc vào việc bạn lưu gì và lưu thế nào, còn dòng cuối cần khóa phiên.
| Chuyện gì xảy ra | Kết quả | Cách phòng tránh |
|---|---|---|
| Tải thất bại mà script vẫn lưu | Giá trị mặc định ghi đè tiến trình thật: mất sạch dữ liệu | Không bao giờ lưu người chơi có lần tải thất bại |
Chỉ lưu trong PlayerRemoving | Server sập hoặc tắt sẽ bỏ qua lần lưu | Tự động lưu cộng với BindToClose đợi các lần lưu của nó |
Không có pcall hoặc không thử lại | Một yêu cầu thất bại làm dừng script hoặc mất lần lưu | pcall với vài lần thử lại giãn cách theo thời gian |
| Lưu mỗi lần có thay đổi | Yêu cầu xếp hàng; khi hàng đợi có 30, yêu cầu mới bị loại bỏ | Giữ dữ liệu trong bộ nhớ và lưu theo chu kỳ |
| Lưu thứ mà kho không lưu được | Lưu báo lỗi, hoặc giá trị quay về nil | Lưu số, chuỗi, boolean và table gồm những thứ đó |
| Đổi hình dạng dữ liệu mà không migrate | Bản lưu cũ được tải vào sai trường | Phiên bản schema và một bước migrate |
| Hai script lưu cùng một key | Mỗi lần lưu ghi đè các trường của script kia | Một module sở hữu key |
| Hai server cùng giữ một người chơi | Server có dữ liệu cũ lưu sau cùng và ghi đè tiến trình mới | Khóa phiên |
Khóa phiên, "lock lost" và ProfileStore
Người chơi chỉ kết nối với một server tại một thời điểm, nhưng lần lưu cuối của server cũ có thể vẫn đang chạy khi họ vào server mới: thử lại chậm, teleport hoặc vào lại nhanh. Nếu server mới tải dữ liệu trước, nó sẽ có dữ liệu cũ, và server nào lưu sau cùng sẽ thắng. Tài liệu Roblox lưu ý rằng trong game có trao đổi vật phẩm, khoảng hở này là nguyên nhân thường gặp của lỗi nhân bản vật phẩm.
Khóa phiên (session lock) bịt khoảng hở này. Khi một server tải key của người chơi, trong cùng lệnh gọi UpdateAsync nó ghi ID khóa của mình vào metadata của key. Bất kỳ server nào khác thấy một khóa chưa hết hạn không phải do nó đặt sẽ không tải và không lưu key đó. Server sở hữu làm mới khóa ở mỗi lần tự động lưu và gỡ nó ở lần lưu cuối; nếu nó ngừng làm mới, khóa hết hạn và server khác có thể lấy nó.
"Lock lost" nghĩa là gì
Trong hệ thống có khóa phiên, một server mất khóa khi key của người chơi giờ thuộc về server khác, vì khóa đã hết hạn hoặc bị chiếm. Bản sao của nó có thể đã cũ, nên nó phải ngừng lưu người chơi này; cách phản ứng thường gặp là kick họ kèm thông báo để họ kết nối lại. Nếu bạn thấy "lock lost" khi là người chơi, đó là thông báo của chính hệ thống lưu của game đó, và chỉ nhà phát triển game đó mới giải thích được.
Bạn có cần nó không?
Module trong hướng dẫn này không khóa phiên. Không có khóa, trường hợp xấu nhất thực tế là: trong một cuộc đua hiếm gặp, người chơi mất những gì đã kiếm được trên server cũ sau lần lưu thành công cuối của nó. Hãy thêm khóa khi việc nhân bản hoặc mất mát gây thiệt hại thật cho người chơi: trao đổi, developer product, vật phẩm hiếm hoặc teleport thường xuyên.
| Lựa chọn | Là gì | Cần biết |
|---|---|---|
| Module trong hướng dẫn này | Tải, cache trong bộ nhớ, thử lại, tự động lưu, lưu khi tắt server và phiên bản schema, không có khóa | Đủ ngắn để đọc hết và sửa |
| Ví dụ của Roblox cho dữ liệu người chơi và mua hàng | Code mẫu từ Roblox có khóa phiên, thử lại theo thứ tự cho từng key và xử lý biên nhận mua hàng | Roblox nói nó chưa được kiểm chứng qua thời gian trong một game nổi tiếng và không nên dùng nguyên trạng khi chưa test kỹ |
| ProfileStore | Module cộng đồng miễn phí, mã nguồn mở, kế nhiệm ProfileService, xây quanh khóa phiên và tự động lưu | Không phải của Roblox. Chuyển một game đang có sang nó cần migrate dữ liệu đã lưu |
Với mọi module bên thứ ba, Roblox khuyên kiểm tra ai sở hữu nó, nó có được bảo trì không và bạn sẽ truy cập dữ liệu của mình thế nào nếu không có nó. Cùng tài liệu đó gọi DataStore2 là thư viện đã lỗi thời mà game mới không nên dùng.
Giới hạn của data store
Đây là các giới hạn theo tài liệu Roblox ngày 30 tháng 9 năm 2026. Roblox có điều chỉnh chúng, nên hãy xem trang mã lỗi và giới hạn (bằng tiếng Anh) trước khi dựa vào một con số chính xác.
| Loại yêu cầu | Kho thường | Kho có thứ tự (ordered) |
|---|---|---|
Đọc: GetAsync, phần đọc trong UpdateAsync | 60 + 40 × số người chơi | 60 + 40 × số người chơi |
Ghi: SetAsync, IncrementAsync, phần ghi trong UpdateAsync | 60 + 40 × số người chơi | 30 + 5 × số người chơi |
Liệt kê: ListKeysAsync hoặc GetSortedAsync cho kho có thứ tự | 5 + 2 × số người chơi | 5 + 2 × số người chơi |
Xóa: RemoveAsync | 60 + 40 × số người chơi | 30 + 5 × số người chơi |
Với 20 người chơi, server có thể ghi thường 860 lần mỗi phút; tự động lưu của module này dùng khoảng 7 lần trong số đó, cộng một lần cho mỗi người chơi rời đi. Thứ làm cạn ngân sách là lưu mỗi khi nhặt một đồng xu. Ngân sách thứ hai áp dụng cho cả game và dùng chung với Open Cloud: 300 lần đọc mỗi phút cộng 40 cho mỗi người chơi đang online, và 300 lần ghi cộng 20 cho mỗi người chơi.
| Giới hạn | Giá trị |
|---|---|
| Tên kho, tên key, scope | Mỗi cái 50 ký tự |
| Giá trị trong một key | 4.194.304 ký tự dưới dạng JSON |
| Đọc một key từ mọi server | 25 MB mỗi phút |
| Ghi vào một key từ mọi server | 4 MB mỗi phút, mỗi yêu cầu được làm tròn lên KB kế tiếp |
| Yêu cầu đang chờ | 30 cho mỗi hàng đợi; vượt quá thì yêu cầu thất bại với lỗi 301-306 |
| Dung lượng cho cả game | 500 MB cộng 1 MB cho mỗi người dùng từ trước đến nay |
Đo kích thước dữ liệu người chơi bằng #HttpService:JSONEncode(data), và xem ngân sách còn lại của server đang chạy bằng DataStoreService:GetRequestBudgetForRequestType(Enum.DataStoreRequestType.StandardWrite). Các lệnh GetAsync được trả lời từ cache 4 giây không bị tính. Chế độ Run trong Studio có giới hạn riêng, có thể thấp hơn, nên để kiểm tra giới hạn yêu cầu, Roblox khuyên dùng Team Create.
Phiên bản và bản sao lưu
Data store thường tự lưu lịch sử cho bạn. Lần ghi đầu tiên vào một key trong mỗi giờ theo UTC được giữ lại như một phiên bản, còn các lần ghi sau trong giờ đó ghi đè lên nhau. Phiên bản cũ hết hạn 30 ngày sau khi bị một lần ghi mới hơn thay thế; phiên bản mới nhất không bao giờ hết hạn. Kho có thứ tự không lưu phiên bản.
Để khôi phục một người chơi, mở Data Stores Manager (Creations, game của bạn, Configure > Data Stores Manager), chọn key của họ, chọn một phiên bản trước đó và bấm Revert; việc này cần quyền Edit. Làm khi người chơi đang offline, nếu không server đang giữ phiên của họ sẽ lưu bản sao của nó đè lên bản khôi phục. Từ script server, ListVersionsAsync và GetVersionAsync tìm và đọc phiên bản cũ, rồi bạn ghi nó trở lại làm giá trị hiện tại.
Trước khi phát hành một bản cập nhật thay đổi cách lưu dữ liệu, Roblox khuyên tạo snapshot qua Open Cloud Snapshot Data Stores API (mỗi game một lần mỗi ngày). Không có nó, một lần lưu lỗi lúc 3:30 UTC sẽ ghi đè mọi thứ đã ghi vào key đó từ 3:00, vì nó rơi vào cùng phiên bản theo giờ.
Lỗi thường gặp và cách sửa
Lỗi data store hiện trong cửa sổ Output của Studio, và module in một cảnh báo kèm nội dung lỗi của Roblox ở mỗi lần thử thất bại. Hướng dẫn về lỗi script giải thích cách đọc Output nói chung.
StudioAccessToApisNotAllowed (lỗi 403)
"Can't write to DataStore from Studio because API access is not enabled." Hãy publish place, rồi bật Enable Studio Access to API Services trong File > Experience Settings > Security, trong bản sao test.
DataStore request was added to queue
Server gửi yêu cầu nhanh hơn ngân sách cho phép, hoặc ghi một key quá thường xuyên, thường do lưu mỗi lần thay đổi hoặc trong vòng lặp. Khi hàng đợi có 30 yêu cầu, yêu cầu mới thất bại với lỗi 301-306. Giữ dữ liệu trong bộ nhớ và lưu theo chu kỳ.
CantStoreValue (lỗi 104), hoặc một trường quay về nil
Table chứa thứ mà kho không lưu được, ví dụ Instance, Vector3 hoặc Color3. Thay vào đó hãy lưu tên, ID hoặc các con số đơn giản và dựng lại đối tượng khi tải.
ValueTooLarge (lỗi 105)
Một key chứa hơn 4.194.304 ký tự JSON. Đo bằng #HttpService:JSONEncode(data), bỏ những gì có thể dựng lại, hoặc chia dữ liệu ra nhiều key cố định.
Không có lỗi nhưng dữ liệu không được lưu
Tìm cảnh báo Could not load của module: sau lần tải thất bại, nó cố ý từ chối lưu. Nếu không, có lẽ giá trị đã được sửa trong LocalScript, thứ không bao giờ đến được server, hoặc một script khác đang lưu cùng key.
Dữ liệu bị reset mỗi lần vào lại game
Key thay đổi giữa các phiên (được tạo từ player.Name, hoặc bạn đã đổi STORE_NAME), lần tải thất bại và bạn thấy giá trị mặc định, hoặc không có script nào nạp module nên nó hoàn toàn không chạy. Kiểm tra Output và xem Main có nạp PlayerData không.
Làm bằng RoCode
Nếu không muốn tự ráp, RoCode có thể làm việc này ngay trong place bạn đang mở. Đây là AI agent độc lập, không phải của Roblox, làm việc qua plugin cho Roblox Studio: nó viết Luau dùng DataStoreService như mọi script khác và tạo script trong Explorer của bạn. Bản thân nó không bao giờ truy cập data store của bạn, nhưng với plugin 3.9 trở lên, nó có thể bấm Play để chạy một playtest ngắn, nơi script của bạn chạy như trong mọi bài test.
Thêm tính năng lưu vào game của tôi: lưu Coins, Level và Inventory trong một module PlayerData có tự động lưu và lưu khi server tắt, và hiện Coins trong leaderstats mà tôi đã có.
- Có thể tìm leaderstats và code DataStore sẵn có qua Search Scripts và Read Script, để mở rộng những gì bạn đã có thay vì thêm script lưu thứ hai. Trong place lớn, hãy nêu tên script hoặc thư mục trong tin nhắn.
- Tạo ModuleScript và Script nạp nó qua Create Script, hoặc sửa những cái đã có qua Edit Script
- Chạy Check Script cho mỗi script đã viết: kiểm tra biên dịch ngay trong Studio với danh sách cảnh báo ngắn, không phải kiểm tra kiểu và không phải chạy thử
- Gửi thay đổi theo từng đợt, và mỗi đợt là một điểm hoàn tác (undo) trong Studio
Bạn vẫn phải tự bật Studio Access to API Services trong bản sao test: RoCode không thể đổi cài đặt này. Với plugin 3.9 trở lên, playtest ngắn của nó đọc lỗi, và với plugin 3.9.11 trở lên nó có thể điều khiển một nhân vật thử nghiệm để kiểm tra game có chạy không, nhưng nó chỉ kiểm tra những gì nó tự quyết định kiểm tra, nên hãy tự chơi và chắc chắn rằng Coins, Level và Inventory được lưu và tải lại. Nếu việc lưu thất bại trong bài test của bạn, Check Output có thể đọc các dòng Server từ playtest bạn đã chạy. Tính năng lưu thường được thêm khi vòng chơi chính đã chạy; làm game Roblox bằng AI, mỗi lần một hệ thống trình bày thứ tự này. RoCode kết nối với Studio thế nào.
Câu hỏi thường gặp
Làm sao bật DataStore trong Roblox Studio?
Publish place, mở File > Experience Settings > Security, bật Enable Studio Access to API Services và bấm Save. Hãy làm trong một game test riêng, vì khi đó Studio dùng cùng data store với các server thật của game đó.
Roblox có tự động lưu dữ liệu người chơi không?
Không. Không có gì về người chơi được giữ lại sau phiên nếu một script server không lưu nó qua DataStoreService, kể cả leaderstats.
Nên chọn ProfileStore hay dùng thẳng DataStoreService?
ProfileStore cũng được xây trên data store, nên câu hỏi là bạn có muốn người khác viết và bảo trì khóa phiên giúp bạn không. Với trao đổi, vật phẩm trả phí hoặc teleport thường xuyên, khóa phiên đáng giá, dù lấy từ thư viện hay từ ví dụ mẫu của Roblox. Với game nhỏ hơn, một module như module này dễ đọc và dễ sửa hơn.
Làm sao reset hoặc xóa dữ liệu của người chơi?
Trong Data Stores Manager, tìm key và chọn Mark for Deletion, có thể hủy trong thời gian chờ, hoặc gọi RemoveAsync cho key từ một script server. Làm khi người chơi đang offline, nếu không lần lưu tiếp theo của server họ sẽ ghi dữ liệu trở lại. Trong bản sao test, đổi STORE_NAME sẽ cho mọi người bắt đầu lại từ đầu; đừng bao giờ làm vậy trong game thật.
Nguồn và tài liệu đọc thêm
- Roblox Creator Docs: Data stores (bằng tiếng Anh). quyền truy cập Studio, GetAsync, SetAsync, UpdateAsync, set và update
- Roblox Creator Docs: Best practices for data stores (bằng tiếng Anh). một key cho mỗi người chơi, dữ liệu trong bộ nhớ, thử lại với khoảng chờ tăng dần, module bên thứ ba
- Roblox Creator Docs: Data store error codes and limits (bằng tiếng Anh). mã lỗi, giới hạn yêu cầu của server và game, giới hạn kích thước, thông lượng và dung lượng
- Roblox Creator Docs: Versioning, listing and caching (bằng tiếng Anh). phiên bản theo giờ, snapshot, cache 4 giây, những gì lưu được
- Roblox Creator Docs: Implement player data and purchasing systems (bằng tiếng Anh). ví dụ mẫu, khóa phiên, tải thất bại, tự động lưu mỗi 180 giây
- Roblox Creator Docs: Data Stores Manager (bằng tiếng Anh). xem key, khôi phục phiên bản, xóa dữ liệu
- Roblox Engine API: DataModel:BindToClose (bằng tiếng Anh). 30 giây để tắt server
Cách kiểm tra code: mọi script trong trang này đều qua trình kiểm tra kiểu nghiêm ngặt (strict) của Luau với định nghĩa API của Roblox (luau-lsp, 20 tháng 11, 2026). Kiểm tra kiểu bắt được API gõ sai và kiểu dữ liệu sai, không bắt được lỗi logic của game, nên hãy thử trong Studio trước khi xuất bản.