Datenspeicher

Der DataStoreService ermöglicht es Ihnen, Daten zu speichern, die zwischen Sitzungen persistent bleiben müssen, wie z.B. Elemente im Inventar eines Spielers oder Fertigkeitspunkte. Datenspeicher sind pro Spiel konsistent, sodass jeder Ort in einem Spiel auf dieselben Daten zugreifen und diese ändern kann, einschließlich Orte auf verschiedenen Servern.

Wenn Sie eine granulare Berechtigungssteuerung zu Ihren Datenspeichern hinzufügen und auf sie außerhalb von Studio oder Roblox-Servern zugreifen möchten, können Sie Open Cloud APIs für Datenspeicher verwenden.

Um alle Datenspeicher in einem Spiel über den Creator Hub anzuzeigen und zu überwachen, verwenden Sie den Data Stores Manager.

Für temporäre Daten, die Sie häufig aktualisieren oder darauf zugreifen müssen, verwenden Sie Speicher im Arbeitsspeicher.

Studio-Zugriff aktivieren

Standardmäßig können Spiele, die im Studio getestet werden, nicht auf Datenspeicher zugreifen, daher müssen Sie dies zunächst aktivieren. Der Zugriff auf Datenspeicher im Studio kann für Live-Spiele gefährlich sein, da das Studio auf dieselben Datenspeicher zugreift wie die Client-Anwendung. Um zu vermeiden, dass Produktionsdaten überschrieben werden, aktivieren Sie diese Einstellung nicht für Live-Spiele. Aktivieren Sie sie stattdessen für eine separate Testversion des Spiels.

Um den Studio-Zugriff in einem veröffentlichten Spiel zu aktivieren:

1. Öffnen Sie das Datei ⟩ Erlebnis-Einstellungen Fenster in Studio.
2. Navigieren Sie zu Sicherheit.
3. Aktivieren Sie den Schalter Zugriff auf API-Dienste im Studio aktivieren.
4. Klicken Sie auf Speichern.

Auf Datenspeicher zugreifen

Um auf einen Datenspeicher innerhalb eines Spiels zuzugreifen:

1. Fügen Sie DataStoreService zu einem serverseitigen Script hinzu.
2. Verwenden Sie die Funktion GetDataStore() und geben Sie den Namen des Datenspeichers an, den Sie verwenden möchten. Wenn der Datenspeicher nicht existiert, erstellt das Studio einen, wenn Sie Ihre Spieldaten zum ersten Mal speichern.

local DataStoreService = game:GetService("DataStoreService")

local gameStore = DataStoreService:GetDataStore("PlayerGame")

Daten erstellen

Ein Datenspeicher ist im Wesentlichen ein Wörterbuch, ähnlich einer Luau-Tabelle. Ein eindeutiger Schlüssel indiziert jeden Wert im Datenspeicher, wie z.B. die eindeutige Player.UserId eines Benutzers oder einen benannten String für eine Spiel-Promo.

Um einen neuen Eintrag zu erstellen, rufen Sie SetAsync() mit dem Schlüsselnamen und einem Wert auf.

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

Daten aktualisieren

Um einen gespeicherten Wert in einem Datenspeicher zu ändern, rufen Sie UpdateAsync() mit dem Schlüsselnamen des Eintrags und einer Callback-Funktion auf, die definiert, wie Sie den Eintrag aktualisieren möchten. Dieses Callback nimmt den aktuellen Wert und gibt einen neuen Wert basierend auf der von Ihnen definierten Logik zurück. Wenn das Callback nil zurückgibt, wird der Schreibvorgang abgebrochen und der Wert wird nicht aktualisiert.

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("Großgeschriebener Name:", updatedName)
end

Set vs update

Verwenden Sie set, um schnell einen bestimmten Schlüssel zu aktualisieren. Die Funktion SetAsync():

• Kann zu Dateninkonsistenzen führen, wenn zwei Server versuchen, zur gleichen Zeit den gleichen Schlüssel zu setzen
• Zählt nur gegen das Schreiblimit

Verwenden Sie update, um Versuche über mehrere Server zu behandeln. Die Funktion UpdateAsync():

• Liest den aktuellen Schlüsselwert von dem Server, der ihn zuletzt aktualisiert hat, bevor Änderungen vorgenommen werden
• Ist langsamer, da zuerst gelesen wird, bevor geschrieben wird
• Zählt gegen sowohl das Lese- als auch das Schreiblimit

Daten lesen

Um den Wert eines Datenspeichereintrags zu lesen, rufen Sie GetAsync() mit dem Schlüsselnamen des Eintrags auf.

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

Daten inkrementieren

Um eine Ganzzahl in einem Datenspeicher zu inkrementieren, rufen Sie IncrementAsync() mit dem Schlüsselnamen des Eintrags und einer Zahl auf, um wie viel der Wert geändert werden soll. IncrementAsync() ist eine Komfortfunktion, die es Ihnen ermöglicht, den Aufruf von UpdateAsync() und das manuelle Inkrementieren der Ganzzahl zu vermeiden.

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

Daten entfernen

Um einen Eintrag zu entfernen und den Wert zurückzugeben, der mit dem Schlüssel verknüpft ist, rufen Sie RemoveAsync() auf.

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

Metadaten

Es gibt zwei Arten von Metadaten, die mit Schlüsseln verknüpft sind:

• Vom Dienst definiert: Standardmäßig schreibgeschützte Metadaten, wie die letzte Aktualisierungszeit und die Erstellungszeit. Jedes Objekt hat vom Dienst definierte Metadaten.
• Benutzerspezifisch definiert: Benutzerdefinierte Metadaten zur Tagging und Kategorisierung. Werden mit dem DataStoreSetOptions-Objekt und der Funktion SetMetadata() definiert.

Um Metadaten zu verwalten, erweitern Sie die Funktionen SetAsync(), UpdateAsync(), GetAsync(), IncrementAsync() und RemoveAsync().

• SetAsync() akzeptiert die optionalen dritten und vierten Argumente:

  • Eine Tabelle von UserIds. Dies kann bei der Verfolgung und Entfernung von Urheberrecht und geistigem Eigentum hilfreich sein.

  • Ein DataStoreSetOptions-Objekt, in dem Sie benutzerdefinierte Metadaten mit der Funktion SetMetadata() definieren können.

    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() und RemoveAsync() geben einen zweiten Wert im Objekt DataStoreKeyInfo zurück. Dieser zweite Wert enthält sowohl dienstedefinierte Eigenschaften als auch Funktionen, um benutzerspezifische Metadaten abzurufen.

  • Die Funktion GetUserIds() ruft die Tabelle von UserIds ab, die Sie an SetAsync() übergeben haben.
  • Die Funktion GetMetadata() ruft die benutzerspezifischen Metadaten ab, die Sie an SetAsync() über SetMetadata() übergeben haben.
  • Die Eigenschaft Version ruft die Version des Schlüssels ab.
  • Die Eigenschaft CreatedTime ruft die Zeit ab, zu der der Schlüssel erstellt wurde, formatiert als die Anzahl der Millisekunden seit der Epoche.
  • Die Eigenschaft UpdatedTime ruft die letzte Zeit ab, zu der der Schlüssel aktualisiert wurde, formatiert als die Anzahl der Millisekunden seit der Epoche.

  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

• Die Callback-Funktion von UpdateAsync() erhält einen zusätzlichen Parameter im Objekt DataStoreKeyInfo, der den aktuellen Schlüsselstatus beschreibt. Sie gibt den modifizierten Wert, die mit UserIds verknüpften Schlüssel und die Metadaten des Schlüssels zurück.

  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

Für Limits bei der Definition von Metadaten siehe die Metadatenlimits.

Bestellte Datenspeicher

Standardmäßig sortieren Datenspeicher ihren Inhalt nicht. Wenn Sie Daten in einer geordneten Weise abrufen müssen, wie z.B. in persistierenden Bestenlisten, rufen Sie stattdessen GetOrderedDataStore() auf.

local DataStoreService = game:GetService("DataStoreService")

local characterAgeStore = DataStoreService:GetOrderedDataStore("CharacterAges")

Bestellte Datenspeicher unterstützen die gleichen grundlegenden Funktionen wie Standarddatenspeicher sowie die einzigartige Funktion GetSortedAsync(), die mehrere sortierte Schlüssel basierend auf einer spezifischen Sortierreihenfolge, Seitengröße und Minimum-/Maximumwerten abruft.

Im folgenden Beispiel werden Charakterdaten in Seiten mit drei Einträgen, jeweils in absteigender Reihenfolge, sortiert und dann wird durch die Seiten iteriert, um die Namen und Alter jedes Charakters auszugeben.

local DataStoreService = game:GetService("DataStoreService")

local characterAgeStore = DataStoreService:GetOrderedDataStore("CharacterAges")

-- Füllt den bestellten Datenspeicher
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

-- Sortiert Daten in absteigender Reihenfolge in Seiten mit jeweils drei Einträgen
local success, pages = pcall(function()
	return characterAgeStore:GetSortedAsync(false, 3)
end)
if success then
	while true do
		-- Ruft die aktuelle (erste) Seite ab
		local entries = pages:GetCurrentPage()
		-- Iteriert über alle Schlüssel-Wert-Paare auf der Seite
		for _, entry in entries do
			print(entry.key .. " : " .. tostring(entry.value))
		end
		-- Überprüft, ob die letzte Seite erreicht wurde
		if pages.IsFinished then
			break
		else
			print("----------")
			-- Geht zur nächsten Seite
			pages:AdvanceToNextPageAsync()
		end
	end
end