數據儲存

Class.DataStoreService 允許您存儲在不同會話之間需要保持的資料，例如玩家的道具欄或技能點。資料存儲是按體驗一致的，因此任何體驗的地方都可以存取並變更相同的資料，包括位置在不同的伺服器上。

如果您想要在您的數據儲存中添加粒度權限控制，並且在 Studio 或 Roblox 伺服器外存取它們，您可以使用 開啟雲端 API 對數據儲存。

對於您需要更新或存取的暫時資料，請使用 內存存儲 。

啟用工作室存取

由預設情況下，Studio 中測試的體驗無法存取資料儲存，因此您必須先啟用它們。在 Studio 中存取資料儲存可能會對於生產體驗造成危險，因此您必須先啟用它們。為了避免覆蓋生產資料，請不要在體驗上啟用此設定。相反，為了測試個別體驗版本，請啟用此設定。

要在 已發布 的體驗啟用 Studio 存取權限：

1. 前往 首頁 > 遊戲設定 > 安全 。
2. 啟用 啟用 Studio 存取 API 服務 切換。
3. 按一下 儲存 。

存取資料儲存

要存取體驗內的資料儲存：

1. 將 DataStoreService 添加到伺服器端的 Script 。
2. 使用 GetDataStore() 取得資料存取服務 功能並指定您想要使用的資料存取服務名稱。如果資料存取服務不存在，Studio 會在您首次儲存體驗資料時創建一個。

local DataStoreService = game:GetService("DataStoreService")

local experienceStore = DataStoreService:GetDataStore("PlayerExperience")

創建資料

資料存取庫是基本上像 Lua 桌子一樣的字典。 A 個獨特的 鑰匙 索引每個值在資料存取商店 商家中，像使用者的獨特 Player.UserId 或名稱一個體驗促銷的名稱串。

要創建新的項目，請使用 SetAsync() 並指定鑰匙名稱和值。

local DataStoreService = game:GetService("DataStoreService")

local experienceStore = DataStoreService:GetDataStore("PlayerExperience")

local success, errorMessage = pcall(function()
	experienceStore:SetAsync("User_1234", 50)
end)
if not success then
	print(errorMessage)
end

更新資料

要變更任何存取資商店 商家存檔的值，請使用 Class.GlobalDataStore:UpdateAsync()|UpdateAsync() 以更新入口的鑰匙名稱和回歸函數，以便定義您想要更新入口的方式。此回歸函數接受目前的值並返回按照您定義的方式更新值的新值。如果回歸函數返回 nil ，寫入操

local DataStoreService = game:GetService("DataStoreService")

local nicknameStore = DataStoreService:GetDataStore("Nicknames")

local function makeNameUpper(currentName)
	local nameUpper = string.upper(currentName)
	return nameUpper
end

local success, updatedName = pcall(function()
	return nicknameStore:UpdateAsync("User_1234", makeNameUpper)
end)
if success then
	print("Uppercase Name:", updatedName)
end

設定與更新

使用 set 快速更新特定鍵。 SetAsync() 函數：

• 如果兩個服務器嘗試設置相同的鑰匙，可能會導致資料不一致
• 只有寫入限制

使用更新來處理多個伺服器的嘗試。UpdateAsync() 函數：

• 閱取最近更新時從伺服器閱取的當前鑰匙值
• 因為它在寫之前就會読取
• 計算寫入和寫出限制

閱取資料

要閱取資料存取資料庫條目的值，請使用 GetAsync() 並使用條目的鑰匙名稱。

local DataStoreService = game:GetService("DataStoreService")

local experienceStore = DataStoreService:GetDataStore("PlayerExperience")

local success, currentExperience = pcall(function()
	return experienceStore:GetAsync("User_1234")
end)
if success then
	print(currentExperience)
end

增加資料

要在資料商店 商家取中增加整數，請使用 IncrementAsync() 並且在隨入的鑰匙名稱和數字上輸入數量，以增加數值的變更量。 IncrementAsync() 是一種便利的函數，可以讓您避免呼叫

local DataStoreService = game:GetService("DataStoreService")

local experienceStore = DataStoreService:GetDataStore("PlayerExperience")

local success, newExperience = pcall(function()
	return experienceStore:IncrementAsync("Player_1234", 1)
end)
if success then
	print(newExperience)
end

移除資料

要移除一個項目並且返回關鍵所屬性的值，請呼叫 RemoveAsync()。

local DataStoreService = game:GetService("DataStoreService")

local nicknameStore = DataStoreService:GetDataStore("Nicknames")

local success, removedValue = pcall(function()
	return nicknameStore:RemoveAsync("User_1234")
end)
if success then
	print(removedValue)
end

金屬元素

鑰匙與屬性的元數有兩種類型：

• 服務定義 : 服務器所定義的預設只讀屬性，例如最近更新時間和創建時間。每個對象都有服務定義的屬性。
• 使用者定義 : 標籤和類別的自訂標準。由 DataStoreSetOptions 對象和 SetMetadata() 函數定義。

要管理元數據，請擴展 SetAsync()、UpdateAsync()、GetAsync()、1>Class.GlobalDataStore:IncrementAsync()|IncrementAsync()1> 和 4>

• SetAsync() 接受可選的第三和第四個引數：

  • Class.Player.UserId|UserIds 的表。這可以幫助進行內容版權和知識產權追蹤和移除。

  • 一個 DataStoreSetOptions 對物件，你可以使用 SetMetadata() 函數來定義自訂元素。

    local DataStoreService = game:GetService("DataStoreService")
    
    local experienceStore = DataStoreService:GetDataStore("PlayerExperience")
    
    local setOptions = Instance.new("DataStoreSetOptions")
    setOptions:SetMetadata({["ExperienceElement"] = "Fire"})
    
    local success, errorMessage = pcall(function()
        experienceStore:SetAsync("User_1234", 50, {1234}, setOptions)
    end)
    if not success then
        print(errorMessage)
    end

• GetAsync() ， IncrementAsync() 和 RemoveAsync() 在 0> Class.DataStoreKeyInfo0> 對物件中返回第二個值。這個第二個值包含服務器定義的屬性和函數以

  • Class.DataStoreKeyInfo:GetUserIds()|GetUserIds() 函數擷取您傳送給 UserIds 的表 SetAsync()。
  • Class.DataStoreKeyInfo:GetMetric()|GetMetric() 函數會擷取您傳送給 SetAsync() 的用戶定義元素，這些元素通過 SetMetadata() 傳送給您。
  • Class.DataStoreKeyInfo.Version|Version 屬性會擷取鑰鍵的版本。
  • Class.DataStoreKeyInfo.CreatedTime|CreatedTime 屬性擷取鑰匙創建時間，格式為自從時代起始的毫秒數。
  • Class.DataStoreKeyInfo.UpdatedTime|UpdatedTime 屬性擷取鑰匙上次更新的時間，以秒計量單位來表示自從史詩起始至今的時間。

  local DataStoreService = game:GetService("DataStoreService")
  
  local experienceStore = DataStoreService:GetDataStore("PlayerExperience")
  
  local success, currentExperience, keyInfo = pcall(function()
      return experienceStore:GetAsync("User_1234")
  end)
  if success then
      print(currentExperience)
      print(keyInfo.Version)
      print(keyInfo.CreatedTime)
      print(keyInfo.UpdatedTime)
      print(keyInfo:GetUserIds())
      print(keyInfo:GetMetadata())
  end

• Class.GlobalDataStore:UpdateAsync()|UpdateAsync() 的回歸函數在 DataStoreKeyInfo 對象中增加一個額外參數，描述當前關鍵狀態。它返回修改的值、與 UserIds 關聯的鑰匙，以及鑰匙的元素數據。

  local DataStoreService = game:GetService("DataStoreService")
  
  local nicknameStore = DataStoreService:GetDataStore("Nicknames")
  
  local function makeNameUpper(currentName, keyInfo)
      local nameUpper = string.upper(currentName)
      local userIDs = keyInfo:GetUserIds()
      local metadata = keyInfo:GetMetadata()
      return nameUpper, userIDs, metadata
  end
  
  local success, updatedName, keyInfo = pcall(function()
      return nicknameStore:UpdateAsync("User_1234", makeNameUpper)
  end)
  if success then
      print(updatedName)
      print(keyInfo.Version)
      print(keyInfo.CreatedTime)
      print(keyInfo.UpdatedTime)
      print(keyInfo:GetUserIds())
      print(keyInfo:GetMetadata())
  end

對於定義元件的限制，請參閱 元件限制 。

已訂購資料儲存

預設情況下，資料儲存不會排序其內容。如果您需要以排序的方式取得資料，例如在持續排行榜統計中，請您 GetOrderedDataStore() 而不是 GetDataStore() 。

local DataStoreService = game:GetService("DataStoreService")

local characterAgeStore = DataStoreService:GetOrderedDataStore("CharacterAges")

命令資料儲存支持相同的基本功能，作為預設資料儲存，以及獨特 GetSortedAsync() 函數。這會擷取 多個排序鑰匙 ，基於特定排序順序、頁面大小和最低值/最大值。

下面的例子將角色資料排成三條，每一條都在下降順序，然後在頁面上循環，並在每個角色的名稱和年齡上輸出。

local DataStoreService = game:GetService("DataStoreService")

local characterAgeStore = DataStoreService:GetOrderedDataStore("CharacterAges")

-- 正在擷取指定的資料商店 商家
local characters = {
	Mars = 19,
	Janus = 20,
	Diana = 18,
	Venus = 25,
	Neptune = 62
}
for char, age in characters do
	local success, errorMessage = pcall(function()
		characterAgeStore:SetAsync(char, age)
	end)
	if not success then
		print(errorMessage)
	end
end

-- 將資料按照下降排序顯示在每個條記錄的三個頁面上
local success, pages = pcall(function()
	return characterAgeStore:GetSortedAsync(false, 3)
end)
if success then
	while true do
		-- 取得目前 (第一) 頁
		local entries = pages:GetCurrentPage()
		-- 在頁面上的所有鑰匙值對中執行重複
		for _, entry in entries do
			print(entry.key .. " : " .. tostring(entry.value))
		end
		-- 檢查上一頁是否已到達
		if pages.IsFinished then
			break
		else
			print("----------")
			-- 前往下一頁的進展
			pages:AdvanceToNextPageAsync()
		end
	end
end