Datenspeicher

Der DataStoreService ermöglicht es Ihnen, Daten zu speichern, die zwischen Sitzungen bestehen bleiben müssen, wie z. B. Gegenstände 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 für Ihre Datenspeicher hinzufügen und von außerhalb von Studio oder Roblox-Servern darauf 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 zuerst aktivieren. Der Zugriff auf Datenspeicher im Studio kann für Live-Spiele gefährlich sein, da das Studio auf dieselben Datenspeicher wie die Clientanwendung zugreift. 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 Fenster Datei ⟩ Erlebnis-Einstellungen in Studio.
2. Navigieren Sie zu Sicherheit.
3. Aktivieren Sie den Schalter Studio-Zugriff auf API-Dienste 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 einzigartiger Schlüssel indiziert jeden Wert im Datenspeicher, wie 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. Diese Callback-Funktion nimmt den aktuellen Wert und gibt einen neuen Wert basierend auf der von Ihnen definierten Logik zurück. Wenn die Callback-Funktion 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

Setzen vs. Aktualisieren

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

• Kann Dateninkonsistenzen verursachen, wenn zwei Server versuchen, denselben Schlüssel gleichzeitig zu setzen
• Zählt nur gegen das Schreiblimit

Verwenden Sie update, um Mehrserverversuche 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 sie zuerst liest, bevor sie schreibt
• Zählt sowohl gegen die Lese- als auch gegen die Schreiblimits

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 zu bestimmen, um wie viel der Wert geändert werden soll. IncrementAsync() ist eine Komfortfunktion, die es Ihnen ermöglicht, den Aufruf von UpdateAsync() zu vermeiden und die Ganzzahl manuell zu inkrementieren.

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 dienstdefinierte Metadaten.
• Benutzerdefiniert: Benutzerdefinierte Metadaten zum Taggen und Kategorisieren. Definiert mit dem DataStoreSetOptions-Objekt und der Funktion SetMetadata().

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 Urheberrechten und geistigem Eigentum helfen.

  • 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 DataStoreKeyInfo-Objekt zurück. Dieser zweite Wert enthält sowohl dienstdefinierte Eigenschaften als auch Funktionen zum Abrufen benutzerdefinierter Metadaten.

  • Die Funktion GetUserIds() ruft die Tabelle von UserIds ab, die Sie an SetAsync() übergeben haben.
  • Die Funktion GetMetadata() ruft die benutzerdefinierten 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() nimmt einen zusätzlichen Parameter im DataStoreKeyInfo-Objekt entgegen, 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 Ranglistenstatistiken, rufen Sie GetOrderedDataStore() anstelle von GetDataStore() auf.

local DataStoreService = game:GetService("DataStoreService")

local characterAgeStore = DataStoreService:GetOrderedDataStore("CharacterAges")

Bestellte Datenspeicher unterstützen dieselben grundlegenden Funktionen wie Standarddatenspeicher sowie die einzigartige Funktion GetSortedAsync(). Diese ruft mehrere sortierte Schlüssel basierend auf einer bestimmten Sortierreihenfolge, Seitenanzahl und minimalen/maximalen Werten ab.

Im folgenden Beispiel werden Charakterdaten in Seiten mit drei Einträgen sortiert, jeweils in absteigender Reihenfolge, und dann wird durch die Seiten geschleift und der Name und das Alter jedes Charakters ausgegeben.

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
		-- Holt die aktuelle (erste) Seite
		local entries = pages:GetCurrentPage()
		-- Iteriert durch 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

Mehrere Einträge lesen

Um mehrere bestellte Datenspeicher-Einträge in einer einzigen Anfrage zu lesen, rufen Sie BatchGetAsync() mit einem Array von Schlüsseln auf. Dies ist das Batch-Gegenstück zum Lesen von Einträgen einzeln mit GetAsync().

BatchGetAsync() gibt ein Wörterbuch zurück, das jeden angeforderten Schlüssel einer Tabelle mit einem value-Feld zuordnet. Schlüssel, die nicht existieren, werden aus dem Wörterbuch weggelassen, daher sollten Sie bestätigen, dass ein Schlüssel vorhanden ist, bevor Sie seinen Wert lesen.

Jeder angeforderte Schlüssel zählt als eine Leseanfrage, sodass ein einzelner Aufruf für N Schlüssel als N Anfragen gegen das Lese-Limit des bestellten Datenspeichers zählt.

Im folgenden Beispiel werden drei Spielergebnisse in einer einzigen Anfrage gelesen, dann wird durch die Schlüssel geschleift und jedes vorhandene Ergebnis ausgegeben.

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 .. " hat keinen gespeicherten Eintrag")
		end
	end
end