Hướng dẫn · Dữ liệu người chơi

Cách lưu dữ liệu người chơi trong Roblox Studio bằng DataStore

Roblox không nhớ gì về người chơi giữa các phiên nếu một script server không lưu lại. Trong hướng dẫn này, bạn sẽ dựng một module PlayerData để tải, giữ trong bộ nhớ và lưu dữ liệu của từng người chơi qua DataStoreService, rồi tìm hiểu cách kiểm tra, các giới hạn và những cách dữ liệu đã lưu bị mất.

Cập nhật ngày 20 tháng 11, 202621 phút đọcTác giả:

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
  1. Quyền truy cập Studio
  2. DataStore hoạt động thế nào
  3. GetAsync và UpdateAsync
  4. 1. Module PlayerData
  5. Module được dựng thế nào
  6. 2. Làm việc với dữ liệu
  7. 3. Cảnh báo
  8. 4. Kiểm tra trong Studio
  9. Vì sao dữ liệu bị mất
  10. Khóa phiên
  11. Giới hạn
  12. Phiên bản và sao lưu
  13. Common errors
  14. With RoCode
  15. Câu hỏi thường gặp
  16. 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.

  1. 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.
  2. Trong bản sao test, mở File > Experience Settings và chuyển sang Security.
  3. 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

Minh họaBài kiểm tra ở bước 4 của hướng dẫn, tua nhanh: Play, Stop lưu phiên vào data store, Play lần nữa tải nó lên, nên Output hiện 200.

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ó.

Những gì có thể lưu trong data store
KiểuLưu được?Ghi chú
Số, chuỗi, boolean, bufferCóChuỗi phải là UTF-8 hợp lệ. Đừng lưu inf hoặc nan.
TableCó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, Color3KhôngLư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

Các phương thức chính của data store
Phương thứcLà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ề nil sẽ 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.

  1. Trong Explorer, rê chuột lên ServerScriptService, bấm + và chèn một ModuleScript. Đổi tên nó thành PlayerData và thay nội dung bằng code bên dưới.
  2. ModuleScript chỉ chạy khi có script nào đó nạp nó (require). Chèn vào ServerScriptService một Script tên Main vớ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.
  3. Sửa DEFAULTS và kiểu Data cho hợp với game của bạn, giữ mỗi trường là số, chuỗi, boolean hoặc table.
Explorer sau bước 1-3
ServerScriptService
    PlayerData ModuleScript new
    Main Script new
StarterPlayer
    StarterPlayerScripts
        DataWarning LocalScript new
ModuleScript trong ServerScriptService tên là PlayerData
-- 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àoVì sao
Mỗi 180 giây khi người chơi còn trên serverGiớ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ọiLà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.LoadedKí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.

LocalScript trong StarterPlayerScripts tên là DataWarning
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.

  1. 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)
  2. 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.
  3. Bấm Stop. Kết thúc bài test sẽ đóng server, và module lưu bạn trước khi đóng.
  4. 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.
  5. 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.
  6. 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 raKết quảCách phòng tránh
Tải thất bại mà script vẫn lưuGiá trị mặc định ghi đè tiến trình thật: mất sạch dữ liệuKhông bao giờ lưu người chơi có lần tải thất bại
Chỉ lưu trong PlayerRemovingServer sập hoặc tắt sẽ bỏ qua lần lưuTự độ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ạiMột yêu cầu thất bại làm dừng script hoặc mất lần lưupcall 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 đổiYê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 đượcLưu báo lỗi, hoặc giá trị quay về nilLưu số, chuỗi, boolean và table gồm những thứ đó
Đổi hình dạng dữ liệu mà không migrateBản lưu cũ được tải vào sai trườngPhiên bản schema và một bước migrate
Hai script lưu cùng một keyMỗi lần lưu ghi đè các trường của script kiaMột module sở hữu key
Hai server cùng giữ một người chơiServer có dữ liệu cũ lưu sau cùng và ghi đè tiến trình mớiKhó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ọnLà gìCần biết
Module trong hướng dẫn nàyTả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àngCode 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àngRoblox 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ỹ
ProfileStoreModule 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ưuKhô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.

Giới hạn yêu cầu mặc định cho mỗi server, mỗi phút
Loại yêu cầuKho thườngKho có thứ tự (ordered)
Đọc: GetAsync, phần đọc trong UpdateAsync60 + 40 × số người chơi60 + 40 × số người chơi
Ghi: SetAsync, IncrementAsync, phần ghi trong UpdateAsync60 + 40 × số người chơi30 + 5 × số người chơi
Liệt kê: ListKeysAsync hoặc GetSortedAsync cho kho có thứ tự5 + 2 × số người chơi5 + 2 × số người chơi
Xóa: RemoveAsync60 + 40 × số người chơi30 + 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 kích thước và thông lượng
Giới hạnGiá trị
Tên kho, tên key, scopeMỗi cái 50 ký tự
Giá trị trong một key4.194.304 ký tự dưới dạng JSON
Đọc một key từ mọi server25 MB mỗi phút
Ghi vào một key từ mọi server4 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ả game500 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.

Bạn gõ

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ó.

RoCode làm
  • 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

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.

Thử RoCode trong chính game của bạn.

Mỗi ngày có credit miễn phí, không cần thẻ. Cài plugin, mô tả tính năng và xem kết quả xuất hiện trong Studio.