Gegevensopslag

De DataStoreService stelt je in staat om gegevens op te slaan die tussen sessies moeten blijven bestaan, zoals items in de inventaris van een speler of vaardigheidspunten. Gegevensopslag is consistent per spel, zodat elke plaats in een spel dezelfde gegevens kan openen en wijzigen, inclusief plaatsen op verschillende servers.

Als je gedetailleerde toegangscontrole aan je gegevensopslag wilt toevoegen en deze buiten Studio of Roblox-servers wilt openen, kun je Open Cloud API's voor gegevensopslag gebruiken.

Om alle gegevensopslag in een spel via de Creator Hub te bekijken en te monitoren, gebruik je de Gegevensopslagbeheerder.

Voor tijdelijke gegevens die je vaak moet bijwerken of openen, gebruik je geheugenopslag.

Studio-toegang inschakelen

Standaard kunnen spellen die in Studio worden getest geen toegang krijgen tot gegevensopslag, dus je moet ze eerst inschakelen. Toegang tot gegevensopslag in Studio kan gevaarlijk zijn voor live spellen omdat Studio dezelfde gegevensopslag opent als de clienttoepassing. Om te voorkomen dat productiegegevens worden overschreven, schakel deze instelling niet in voor live spellen. Schakel het in voor een aparte testversie van het spel.

Om Studio-toegang in een gepubliceerd spel in te schakelen:

1. Open het Bestand ⟩ Ervaringsinstellingen venster van Studio.
2. Navigeer naar Beveiliging.
3. Schakel de schakelaar Studio-toegang tot API-services inschakelen in.
4. Klik op Opslaan.

Toegang tot gegevensopslag

Om toegang te krijgen tot een gegevensopslag binnen een spel:

1. Voeg DataStoreService toe aan een server-side Script.
2. Gebruik de functie GetDataStore() en geef de naam op van de gegevensopslag die je wilt gebruiken. Als de gegevensopslag niet bestaat, maakt Studio er een aan wanneer je je spelgegevens voor de eerste keer opslaat.

local DataStoreService = game:GetService("DataStoreService")

local gameStore = DataStoreService:GetDataStore("PlayerGame")

Gegevens maken

Een gegevensopslag is in wezen een woordenboek, vergelijkbaar met een Luau-tabel. Een unieke sleutel indexeert elke waarde in de gegevensopslag, zoals de unieke Player.UserId van een gebruiker of een benoemde string voor een spelpromotie.

Om een nieuwe invoer te maken, roep je SetAsync() aan met de sleutelnaam en een waarde.

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

Gegevens bijwerken

Om een opgeslagen waarde in een gegevensopslag te wijzigen, roep je UpdateAsync() aan met de sleutelnaam van de invoer en een callbackfunctie die definieert hoe je de invoer wilt bijwerken. Deze callback neemt de huidige waarde en retourneert een nieuwe waarde op basis van de logica die je definieert. Als de callback nil retourneert, wordt de schrijfoperatie geannuleerd en wordt de waarde niet bijgewerkt.

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("Hoofdletter Naam:", updatedName)
end

Instellen versus bijwerken

Gebruik instellen om snel een specifieke sleutel bij te werken. De functie SetAsync():

• Kan gegevensinconsistentie veroorzaken als twee servers proberen dezelfde sleutel tegelijkertijd in te stellen
• Telt alleen mee voor de schrijflimiet

Gebruik bijwerken om meerdere serverpogingen te verwerken. De functie UpdateAsync():

• Leest de huidige sleutelwaarde van de server die deze het laatst heeft bijgewerkt voordat er wijzigingen worden aangebracht
• Is langzamer omdat het leest voordat het schrijft
• Telt mee voor zowel de lees- als schrijflimieten

Gegevens lezen

Om de waarde van een gegevensopslaginvoer te lezen, roep je GetAsync() aan met de sleutelnaam van de invoer.

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

Gegevens verhogen

Om een geheel getal in een gegevensopslag te verhogen, roep je IncrementAsync() aan met de sleutelnaam van de invoer en een getal voor hoeveel je de waarde wilt wijzigen. IncrementAsync() is een handige functie die je in staat stelt om UpdateAsync() niet aan te roepen en handmatig het geheel getal te verhogen.

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

Gegevens verwijderen

Om een invoer te verwijderen en de waarde die aan de sleutel is gekoppeld terug te geven, roep je RemoveAsync() aan.

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

Metadata

Er zijn twee soorten metadata die aan sleutels zijn gekoppeld:

• Service-gedefinieerd: Standaard alleen-lezen metadata, zoals de meest recente update tijd en creatietijd. Elk object heeft service-gedefinieerde metadata.
• Door gebruiker gedefinieerd: Aangepaste metadata voor tagging en categorisatie. Gedefinieerd met behulp van het DataStoreSetOptions object en de functie SetMetadata().

Om metadata te beheren, breid je de functies SetAsync(), UpdateAsync(), GetAsync(), IncrementAsync(), en RemoveAsync() uit.

• SetAsync() accepteert de optionele derde en vierde argumenten:

  • Een tabel van UserIds. Dit kan helpen bij het volgen en verwijderen van auteursrechten en intellectuele eigendomsrechten.

  • Een DataStoreSetOptions object, waar je aangepaste metadata kunt definiëren met behulp van de functie 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(), en RemoveAsync() retourneren een tweede waarde in het DataStoreKeyInfo object. Deze tweede waarde bevat zowel service-gedefinieerde eigenschappen als functies om door gebruiker gedefinieerde metadata op te halen.

  • De functie GetUserIds() haalt de tabel van UserIds op die je aan SetAsync() hebt doorgegeven.
  • De functie GetMetadata() haalt door gebruiker gedefinieerde metadata op die je aan SetAsync() hebt doorgegeven via SetMetadata().
  • De eigenschap Version haalt de versie van de sleutel op.
  • De eigenschap CreatedTime haalt de tijd op waarop de sleutel is gemaakt, geformatteerd als het aantal milliseconden sinds de epoch.
  • De eigenschap UpdatedTime haalt de laatste tijd op waarop de sleutel is bijgewerkt, geformatteerd als het aantal milliseconden sinds de epoch.

  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

• De callbackfunctie van UpdateAsync() neemt een extra parameter in het DataStoreKeyInfo object dat de huidige sleutelstatus beschrijft. Het retourneert de gewijzigde waarde, de sleutels die zijn gekoppeld aan UserIds, en de metadata van de sleutel.

  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

Voor limieten bij het definiëren van metadata, zie de metadata-limieten.

Geordende gegevensopslag

Standaard sorteren gegevensopslag hun inhoud niet. Als je gegevens op een geordende manier wilt ophalen, zoals in persistente leaderboard-statistieken, roep je GetOrderedDataStore() aan in plaats van GetDataStore().

local DataStoreService = game:GetService("DataStoreService")

local characterAgeStore = DataStoreService:GetOrderedDataStore("CharacterAges")

Geordende gegevensopslag ondersteunt dezelfde basisfuncties als standaard gegevensopslag, plus de unieke functie GetSortedAsync(). Dit haalt meerdere gesorteerde sleutels op op basis van een specifieke sorteervolgorde, paginagrootte en minimum-/maximumwaarden.

Het volgende voorbeeld sorteert karaktergegevens in pagina's met drie invoeren, elk in aflopende volgorde, en doorloopt vervolgens de pagina's en geeft de naam en leeftijd van elk karakter weer.

local DataStoreService = game:GetService("DataStoreService")

local characterAgeStore = DataStoreService:GetOrderedDataStore("CharacterAges")

-- Vul geordende gegevensopslag
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

-- Sorteert gegevens in aflopende volgorde in pagina's van drie invoeren elk
local success, pages = pcall(function()
	return characterAgeStore:GetSortedAsync(false, 3)
end)
if success then
	while true do
		-- Haalt de huidige (eerste) pagina op
		local entries = pages:GetCurrentPage()
		-- Itereert door alle sleutel-waarde paren op de pagina
		for _, entry in entries do
			print(entry.key .. " : " .. tostring(entry.value))
		end
		-- Controleert of de laatste pagina is bereikt
		if pages.IsFinished then
			break
		else
			print("----------")
			-- Gaat naar de volgende pagina
			pages:AdvanceToNextPageAsync()
		end
	end
end

Meerdere invoeren lezen

Om meerdere geordende gegevensopslag invoeren in één verzoek te lezen, roep je BatchGetAsync() aan met een array van sleutels. Dit is de batch-tegenhanger van het lezen van invoeren één voor één met GetAsync().

BatchGetAsync() retourneert een woordenboek dat elke aangevraagde sleutel koppelt aan een tabel met een value-veld. Sleutels die niet bestaan, worden weggelaten uit het woordenboek, dus bevestig dat een sleutel aanwezig is voordat je de waarde leest.

Elke sleutel die je aanvraagt, telt als één leesverzoek, dus een enkele oproep voor N sleutels telt als N verzoeken tegen de geordende gegevensopslag leeslimiet.

Het volgende voorbeeld leest drie spelerscores in één verzoek en doorloopt vervolgens de sleutels en geeft elke score weer die bestaat.

local DataStoreService = game:GetService("DataStoreService")

local playerScores = DataStoreService:GetOrderedDataStore("PlayerScores")
local keys = {"Player_123", "Player_456", "Player_789"}

local success, results = pcall(function()
	return playerScores:BatchGetAsync(keys)
end)
if success then
	for _, key in keys do
		local entry = results[key]
		if entry then
			print(key .. " : " .. tostring(entry.value))
		else
			print(key .. " heeft geen opgeslagen invoer")
		end
	end
end