Almacenamiento de datos

El DataStoreService le permite almacenar datos que necesitan persistir entre sesiones, como artículos en el inventario de un jugador o puntos de habilidad. Los almacenes de datos son consistentes por experiencia, por lo que cualquier lugar en una experiencia puede acceder y cambiar los mismos datos, incluidos los lugares en diferentes servidores.

Si desea agregar un control de permiso granular a sus almacenes de datos y acceder a ellos fuera de los servidores de Studio o Roblox, puede usar Abrir API de la nube para almacenar datos .

Para datos temporales que necesita actualizar o acceder con frecuencia, use almacenes de memoria.

Habilitando el acceso de Studio

Por defecto, las experiencias probadas en Studio no pueden acceder a almacenes de datos, por lo que primero debes habilitarlas. Acceder a almacenes de datos en Studio puede ser peligroso para las experiencias en vivo, ya que Studio accede a los mismos almacenes de datos que la aplicación del cliente. Para evitar sobrescribir los datos de producción, no habilite esta configuración para las versiones de prueba separadas de la experiencia.

Para habilitar el acceso de Studio en una experiencia publicada:

1. Vaya a Inicio > Configuración del juego > Seguridad .
2. Habilita el Activar acceso a API Services alternar/activar.
3. Haga clic en Guardar .

Accediendo a almacenes de datos

Para acceder a un almacén de datos dentro de una experiencia:

1. Agregue DataStoreService a un servidor Script .
2. Usa la función GetDataStore() GetDataStore() | y especifica el nombre del almacén de datos que quieres usar. Si el almacén de datos no existe, Studio crea uno cuando guardas tus datos de experiencia por primera vez.

local DataStoreService = game:GetService("DataStoreService")

local experienceStore = DataStoreService:GetDataStore("PlayerExperience")

Creando Datos

Un almacén de datos es esencialmente un diccionario, similar a una tabla Lua. Un key único indexa cada valor en el tiendade datos, como un Player.UserId o una cadena de nombre para un promoción de experiencia.

Para crear una nueva entrada, llame a SetAsync() con el nombre de la llave y un valor.

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

Actualizar datos

Para cambiar cualquier valor almacenado en un tiendade datos, llama a Class.GlobalDataStore:UpdateAsync()|UpdateAsync() con el nombre de la entrada y una función de llamada que define cómo actualizar la entrada. Esta función de llamada toma el valor actual y devuelve un nuevo valor basado en la lógica que defines. Si la función de llamada devuelve nil , la operación de escritura se cancela y el valor no se actualiza.

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

Establecer vs Actualizar

Usa el método de actualización de clave para actualizar rápidamente una clave específica. La función SetAsync() :

• Puede causar desconsistencia de datos si dos servidores intentan asignar la misma clave al mismo tiempo
• Solo cuenta contra el límite de escritura

Usa update para manejar múltiples intentos de servidor. La función UpdateAsync() :

• Lee el valor de la llave actual del servidor que la última vez actualizó antes de realizar cualquier cambio
• Es más lento porque lee antes de escribir
• Cuenta contra ambos los límites de lectura y escritura

Leer datos

Para leer el valor de una entrada de almacén de datos, llame a GetAsync() con el nombre de la llave de la entrada.

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

Incrementando Datos

Para incrementar un número en un tiendade datos, llama IncrementAsync() con el nombre de la entrada y un número para cambiar el valor. IncrementAsync() es una función de conveniencia que te permite evitar llamar UpdateAsync() y aumentar manual

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

Eliminando datos

Para eliminar una entrada y devolver el valor asociado a la clave, llama a 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

Metadatos

Hay dos tipos de metadatos asociados con las llaves:

• Servicio definido : Metadatos de lectura predeterminados, como la hora de actualización más reciente y el tiempo de creación. Cada objeto tiene metadatos de servicio definidos.
• Usuario-definido : Metadatos personalizados para la etiqueta y la categorización. Definido usando el objeto DataStoreSetOptions y la función SetMetadata().

Para administrar el metadato, expanda las funciones SetAsync(), UpdateAsync(), GetAsync(), 1> Class.GlobalDataStore:IncrementAsync()|IncrementAsync()1> y 4> Class.

• SetAsync() acepta los argumentos opcionales de tercer y cuarto argumento:

  • Una tabla de UserIds . Esto puede ayudar con el seguimiento del derecho de autor y la propiedad intelectual y la eliminación de contenido.

  • Un objeto DataStoreSetOptions , en el que puedes definir metadatos personalizados usando la función Class.DataStoreSetOptions:SetMetric()|SetMetric() .

    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() y RemoveAsync() devuelve un segundo valor en el objeto 0> Class.DataStoreKeyInfo0> . Este segundo valor contiene propiedades y funciones de servicio para recuperar metadatos de usuarios.

  • La función GetUserIds() recupera la tabla de UserIds que le pasaste a SetAsync().
  • La función GetMetadata() recupera los metadatos que proporcionaste a SetAsync() a través de SetMetadata() .
  • La propiedad Version recupera la versión de la clave.
  • La propiedad CreatedTime recupera el tiempo en que se creó la llave, formateado como el número de milisegundos desde la épica.
  • La propiedad UpdatedTime recupera la última vez que la llave se actualizó, en formato de número de milisegundos desde el épico.

  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

• La función de llamada de UpdateAsync() toma un parámetro adicional en el objeto DataStoreKeyInfo que describe el estado actual de la llave. Devuelve el valor modificado, las llaves asociadas con UserIds y el metadato de la clave.

  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

Para los límites al definir metadatos, consulte Límites de metadatos.

Almacenamiento de datos ordenado

Por defecto, los almacenes de datos no clasifican su contenido. Si necesita obtener datos de manera ordenada, como en las estadísticas de clasificación persistente, llame a GetOrderedDataStore() en lugar de GetDataStore() .

local DataStoreService = game:GetService("DataStoreService")

local characterAgeStore = DataStoreService:GetOrderedDataStore("CharacterAges")

Los almacenes de datos ordenados admiten las mismas funciones básicas que los almacenes de datos predeterminados, más la función única GetSortedAsync() . Esto recupera múltiples llaves ordenadas según un orden de clasificación específico, el tamaño de la página y los valores mínimos/máximos.

El siguiente ejemplo clasifica los datos de los personajes en páginas con tres entradas, cada una en orden descendente, luego ciclos a través de las páginas y salidas de cada personaje y su edad.

local DataStoreService = game:GetService("DataStoreService")

local characterAgeStore = DataStoreService:GetOrderedDataStore("CharacterAges")

-- Popula el almacén de datos tienda
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

-- Ordena los datos por orden descendente en páginas de tres entradas cada una
local success, pages = pcall(function()
	return characterAgeStore:GetSortedAsync(false, 3)
end)
if success then
	while true do
		-- Obtiene la página actual (primer)
		local entries = pages:GetCurrentPage()
		-- itera a través de todos los pares de valores clave en la página
		for _, entry in entries do
			print(entry.key .. " : " .. tostring(entry.value))
		end
		-- Comprueba si se ha alcanzado la última página
		if pages.IsFinished then
			break
		else
			print("------")
			-- Avanzos a la página siguiente
			pages:AdvanceToNextPageAsync()
		end
	end
end