สตอเรจข้อมูล

DataStoreService ช่วยให้คุณสามารถเก็บข้อมูลที่ต้องการให้คงอยู่ระหว่างเซสชัน เช่น รายการในคลังของผู้เล่นหรือคะแนนทักษะ สตอเรจข้อมูลมีความสอดคล้องกันต่อเกม ดังนั้นสถานที่ใดๆ ในเกมจึงสามารถเข้าถึงและเปลี่ยนแปลงข้อมูลเดียวกันได้ รวมถึงสถานที่ในเซิร์ฟเวอร์ต่างๆ

หากคุณต้องการเพิ่มการควบคุมสิทธิ์อย่างละเอียดให้กับสตอเรจข้อมูลของคุณและเข้าถึงข้อมูลเหล่านี้จากภายนอก Studio หรือเซิร์ฟเวอร์ Roblox คุณสามารถใช้ Open Cloud APIs สำหรับสตอเรจข้อมูล.

ในการดูและติดตามสตอเรจข้อมูลทั้งหมดในเกมผ่าน Creator Hub ให้ใช้ Data Stores Manager.

สำหรับข้อมูลชั่วคราวที่คุณต้องอัปเดตหรือเข้าถึงบ่อยๆ ให้ใช้ memory stores.

เปิดใช้งานการเข้าถึง Studio

โดยค่าเริ่มต้น เกมที่ทดสอบใน Studio ไม่สามารถเข้าถึงสตอเรจข้อมูลได้ ดังนั้นคุณต้องเปิดใช้งานก่อน การเข้าถึงสตอเรจข้อมูลใน Studio อาจมีความอันตรายต่อเกมที่มีอยู่จริงเนื่องจาก Studio เข้าถึงสตอเรจข้อมูลเดียวกันกับแอปพลิเคชันไคลเอ็นต์ เพื่อหลีกเลี่ยงการเขียนทับข้อมูลที่อยู่ในผลิตภัณฑ์ โปรดอย่าเปิดใช้งานการตั้งค่านี้สำหรับเกมที่มีอยู่แล้ว ให้เปิดใช้งานสำหรับเวอร์ชันทดสอบแยกของเกมแทน

เพื่อเปิดใช้งานการเข้าถึง Studio ในเกมที่ เผยแพร่:

1. เปิดหน้าต่าง File ⟩ Experience Settings ของ Studio
2. ไปที่ Security
3. เปิดใช้งานการตั้งค่า Enable Studio Access to API Services
4. คลิก Save

เข้าถึงสตอเรจข้อมูล

ในการเข้าถึงสตอเรจข้อมูลภายในเกม:

1. เพิ่ม DataStoreService ใน Script ด้านเซิร์ฟเวอร์
2. ใช้ฟังก์ชัน GetDataStore() และกำหนดชื่อของสตอเรจข้อมูลที่คุณต้องการใช้ หากสตอเรจข้อมูลไม่มีอยู่ มันจะถูกสร้างขึ้นเมื่อคุณบันทึกข้อมูลเกมของคุณครั้งแรก

local DataStoreService = game:GetService("DataStoreService")

local gameStore = DataStoreService:GetDataStore("PlayerGame")

สร้างข้อมูล

สตอเรจข้อมูลเป็นเหมือนพจนานุกรม คล้ายกับตาราง Luau คีย์ key ที่ไม่ซ้ำกันจะทำหน้าที่เป็นดัชนีค่าต่างๆในสตอเรจข้อมูล เช่น Player.UserId ที่ไม่ซ้ำกันของผู้ใช้หรือสตริงที่ตั้งชื่อสำหรับโปรโมชั่นเกม

เพื่อสร้างรายการใหม่ ให้เรียก SetAsync() พร้อมชื่อคีย์และค่า

local DataStoreService = game:GetService("DataStoreService")

local gameStore = DataStoreService:GetDataStore("PlayerGame")

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

อัปเดตข้อมูล

ในการเปลี่ยนแปลงค่าที่เก็บไว้ในสตอเรจข้อมูล ให้เรียก UpdateAsync() พร้อมชื่อคีย์ของรายการและฟังก์ชัน callback ที่กำหนดวิธีการที่คุณต้องการปรับปรุงรายการ ฟังก์ชัน callback นี้รับค่าปัจจุบันและคืนค่าปใหม่ตามตรรกะที่คุณกำหนด หากฟังก์ชัน callback คืนค่า 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

ตั้งค่า vs อัปเดต

ใช้ set เพื่ออัปเดตคีย์เฉพาะอย่างรวดเร็ว ฟังก์ชัน SetAsync():

• อาจทำให้ข้อมูลไม่สอดคล้องกันได้หากสองเซิร์ฟเวอร์พยายามตั้งค่าเดียวกันในเวลาเดียวกัน
• นับเฉพาะในขีดจำกัดการเขียน

ใช้ update เพื่อจัดการความพยายามจากเซิร์ฟเวอร์หลายเครื่อง ฟังก์ชัน UpdateAsync():

• อ่านค่าคีย์ปัจจุบันจากเซิร์ฟเวอร์ที่อัปเดตล่าสุดก่อนที่จะทำการเปลี่ยนแปลงใดๆ
• ช้ากว่าเนื่องจากอ่านก่อนเขียน
• นับทั้งในขีดจำกัดการอ่านและการเขียน

อ่านข้อมูล

ในการอ่านค่าของรายการในสตอเรจข้อมูล ให้เรียก GetAsync() พร้อมชื่อคีย์ของรายการ

local DataStoreService = game:GetService("DataStoreService")

local gameStore = DataStoreService:GetDataStore("PlayerGame")

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

เพิ่มข้อมูล

ในการเพิ่มจำนวนเต็มในสตอเรจข้อมูล ให้เรียก IncrementAsync() พร้อมชื่อคีย์ของรายการและหมายเลขที่จะแสดงการเปลี่ยนแปลงค่า IncrementAsync() เป็นฟังก์ชันที่สะดวกช่วยให้คุณหลีกเลี่ยงการเรียก UpdateAsync() และทำการเพิ่มจำนวนเต็มด้วยตนเอง

local DataStoreService = game:GetService("DataStoreService")

local gameStore = DataStoreService:GetDataStore("PlayerGame")

local success, newGame = pcall(function()
	return gameStore:IncrementAsync("Player_1234", 1)
end)
if success then
	print(newGame)
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(), IncrementAsync(), และ RemoveAsync()

• SetAsync() รองรับอาร์กิวเมนต์ที่สามและสี่ซึ่งไม่บังคับ:

  • ตารางของ UserIds ซึ่งช่วยในการติดตามและลบลิขสิทธิ์เนื้อหาและทรัพย์สินทางปัญญา

  • วัตถุ DataStoreSetOptions ซึ่งคุณสามารถกำหนดเมตาดาต้าแบบกำหนดเองโดยใช้ฟังก์ชัน SetMetadata()

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

• GetAsync(), IncrementAsync(), และ RemoveAsync() คืนค่าที่สองในวัตถุ DataStoreKeyInfo ค่าที่สองนี้ประกอบด้วยคุณสมบัติที่บริการกำหนดและฟังก์ชันในการดึงเมตาดาต้าที่ผู้ใช้กำหนด

  • ฟังก์ชัน GetUserIds() ดึงตารางของ UserIds ที่คุณส่งไปยัง SetAsync()
  • ฟังก์ชัน GetMetadata() ดึงเมตาดาต้าที่ผู้ใช้กำหนดซึ่งคุณส่งไปยัง SetAsync() ผ่าน SetMetadata()
  • คุณสมบัติ Version ดึงเวอร์ชันของคีย์
  • คุณสมบัติ CreatedTime ดึงเวลาที่คีย์ถูกสร้าง ขนาดของข้อมูลจะถูกจัดรูปแบบเป็นจำนวนมิลลิวินาทีที่นับตั้งแต่เอพอค
  • คุณสมบัติ UpdatedTime ดึงเวลาที่คีย์ถูกอัปเดตล่าสุด ขนาดของข้อมูลจะถูกจัดรูปแบบเป็นจำนวนมิลลิวินาทีที่นับตั้งแต่เอพอค

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

• ฟังก์ชัน callback ของ 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