Almacenes de datos

El DataStoreService te permite almacenar datos que deben persistir entre sesiones, como artículos en el inventario de un jugador o puntos de habilidad.Las tiendas 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 quieres agregar control de permisos granulares a tus almacenes de datos y acceder a ellos fuera de los servidores de Studio o Roblox, puedes usar Abre API de nube para almacenes de datos.

Para ver y monitorear todos los almacenes de datos en una experiencia a través del Centro de creadores, use el Gestor de almacenes de datos.

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

Habilitar el acceso de Studio

Por defecto, las experiencias probadas en Studio no pueden acceder a los almacenes de datos, por lo que primero debes habilitarlas.Acceder a almacenes de datos en Studio puede ser peligroso para las experiencias en vivo porque Studio accede a los mismos almacenes de datos que la aplicación del cliente.Para evitar sobrescribir los datos de producción, no active esta configuración para las experiencias en vivo.En cambio, activarlo para una versión de prueba separada de la experiencia.

Para habilitar el acceso de Studio en una experiencia publicada :

1. Abre Configuración del juego.
2. Navegue a Seguridad .
3. Habilita la opción Habilitar el acceso de Studio a los servicios de API .
4. Haga clic en Guardar .

Almacenes de datos de acceso

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

1. Añade DataStoreService a un lado del servidor Script.
2. Usa la función 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 guarda por primera vez los datos de su experiencia.

local DataStoreService = game:GetService("DataStoreService")

local experienceStore = DataStoreService:GetDataStore("PlayerExperience")

Crear datos

Un almacén de datos es esencialmente un diccionario, similar a una tabla Luau.Un índice único de clave indexa cada valor en el tiendade datos, como una clave única de Player.UserId o una cadena llamada para una promoción de experiencia.

Para crear una nueva entrada, llame a SetAsync() con el nombre de la clave 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, llame a UpdateAsync() con el nombre de la clave de la entrada y una función de devolución de llamada que defina cómo desea actualizar la entrada.Esta llamada de devolución toma el valor actual y devuelve un nuevo valor basado en la lógica que definas.Si la llamada de devolución 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 actualización

Use set para actualizar rápidamente una clave específica. La función SetAsync():

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

Use actualización para manejar intentos de múltiples servidores. La función UpdateAsync():

• Lee el valor de la clave actual del servidor que lo actualizó por última vez antes de realizar cualquier cambio
• Es más lento porque se 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 clave 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

Datos de incremento

Para incrementar un entero en un tiendade datos, llame a IncrementAsync() con el nombre de la clave de la entrada y un número para cuánto cambiar el valor. IncrementAsync() es una función de conveniencia que te permite evitar llamar UpdateAsync() e incrementar manualmente el entero.

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

Eliminar datos

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

• Definido por el servicio : Metadatos de lectura predeterminados, como el tiempo de actualización más reciente y el tiempo de creación. Cada objeto tiene metadatos definidos por el servicio.
• Definido por el usuario : Metadatos personalizados para etiquetar y categorizar. Definido usando el objeto DataStoreSetOptions y la función SetMetadata().

Para administrar metadatos, expanda las funciones SetAsync(), UpdateAsync(), GetAsync(), IncrementAsync() y RemoveAsync().

• SetAsync() acepta los argumentos opcionales tercero y cuarto:

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

  • Un objeto DataStoreSetOptions donde puedes definir metadatos personalizados usando la función SetMetadata().

    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() devuelven un segundo valor en el objeto DataStoreKeyInfo.Este segundo valor contiene tanto propiedades y funciones definidas por el servicio como para recuperar metadatos definidos por el usuario.

  • La función GetUserIds() recupera la tabla de UserIds que pasaste a SetAsync() .
  • La función GetMetadata() recupera metadatos definidos por el usuario que pasaste 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 clave, formateada como el número de milisegundos desde el momento de la época.
  • La propiedad UpdatedTime recupera la última vez que se actualizó la clave, formateada como el número de milisegundos desde el momento de la época.

  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 devolución de llamada de UpdateAsync() toma un parámetro adicional en el objeto DataStoreKeyInfo que describe el estado de la clave actual.Devuelve el valor modificado, las claves asociadas con UserIds , y los metadatos 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 los límites de metadatos limites de metadatos.

Almacenes de datos ordenados

Por defecto, los almacenes de datos no ordenan su contenido.Si necesita obtener datos de una manera ordenada, como en las estadísticas de tabla 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 claves ordenadas basadas en un orden de clasificación específico, el tamaño de la página y los valores mínimo/máximo.

El siguiente ejemplo ordena los datos de personajes en páginas con tres entradas, cada una en orden descendente, luego recorre las páginas y muestra el nombre y la edad de cada personaje.

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 (primera)
		local entries = pages:GetCurrentPage()
		-- Itera a través de todos los pares clave-valor en la página
		for _, entry in entries do
			print(entry.key .. " : " .. tostring(entry.value))
		end
		-- Comprueba si se ha llegado a la última página
		if pages.IsFinished then
			break
		else
			print("----------")
			-- Avances a la siguiente página
			pages:AdvanceToNextPageAsync()
		end
	end
end