Almacenes de datos

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

Si deseas agregar un control de permisos granular a tus almacenes de datos y acceder a ellos fuera de Studio o de los servidores de Roblox, puedes usar Open Cloud APIs para almacenes de datos.

Para ver y monitorear todos los almacenes de datos en un juego a través del Creator Hub, utiliza el Administrador de Almacenes de Datos.

Para datos temporales que necesitas actualizar o acceder con frecuencia, utiliza almacenes en memoria.

Habilitar acceso a Studio

Por defecto, los juegos probados en Studio no pueden acceder a los almacenes de datos, así que primero debes habilitarlos. Acceder a los almacenes de datos en Studio puede ser peligroso para juegos en vivo porque Studio accede a los mismos almacenes de datos que la aplicación cliente. Para evitar sobrescribir datos de producción, no habilites esta configuración para juegos en vivo. En su lugar, habilítalo para una versión de prueba separada del juego.

Para habilitar el acceso a Studio en un juego publicado:

1. Abre la ventana de Configuración de Experiencia en Archivo ⟩ Configuración de Experiencia.
2. Navega a Seguridad.
3. Habilita el interruptor Habilitar acceso a Studio a los servicios API.
4. Haz clic en Guardar.

Acceder a almacenes de datos

Para acceder a un almacén de datos dentro de un juego:

1. Agrega DataStoreService a un Script del lado del servidor.
2. Usa la función GetDataStore() y especifica el nombre del almacén de datos que deseas usar. Si el almacén de datos no existe, Studio crea uno cuando guardas los datos de tu juego por primera vez.

local DataStoreService = game:GetService("DataStoreService")

local gameStore = DataStoreService:GetDataStore("PlayerGame")

Crear datos

Un almacén de datos es esencialmente un diccionario, similar a una tabla de Luau. Una clave única indexa cada valor en el almacén de datos, como el Player.UserId único de un usuario o una cadena nombrada para una promoción del juego.

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

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

Actualizar datos

Para cambiar cualquier valor almacenado en un almacén de datos, llama a UpdateAsync() con el nombre de la clave de la entrada y una función de callback que define cómo deseas actualizar la entrada. Este callback toma el valor actual y devuelve un nuevo valor basado en la lógica que defines. Si el callback 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("Nombre en mayúsculas:", updatedName)
end

Establecer vs actualizar

Usa 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

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

• Lee el valor actual de la clave del servidor que lo actualizó por última vez antes de hacer cualquier cambio
• Es más lenta porque lee antes de escribir
• Cuenta contra los límites de lectura y escritura

Leer datos

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

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

Incrementar datos

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

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

Eliminar datos

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

• Definidos por el servicio: Metadatos predeterminados de solo lectura, como la hora de la última actualización y la hora de creación. Cada objeto tiene metadatos definidos por el servicio.
• Definidos por el usuario: Metadatos personalizados para etiquetado y categorización. Definidos usando el objeto DataStoreSetOptions y la función SetMetadata().

Para gestionar metadatos, expande 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 eliminación de derechos de autor de contenido y propiedad intelectual.

  • Un objeto DataStoreSetOptions, donde puedes definir metadatos personalizados usando la función 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(), y RemoveAsync() devuelven un segundo valor en el objeto DataStoreKeyInfo. Este segundo valor contiene tanto propiedades definidas por el servicio como funciones para obtener metadatos definidos por el usuario.

  • La función GetUserIds() obtiene la tabla de UserIds que pasaste a SetAsync().
  • La función GetMetadata() obtiene los metadatos definidos por el usuario que pasaste a SetAsync() a través de SetMetadata().
  • La propiedad Version obtiene la versión de la clave.
  • La propiedad CreatedTime obtiene la hora en que se creó la clave, formateada como el número de milisegundos desde la época.
  • La propiedad UpdatedTime obtiene la última vez que se actualizó la clave, formateada como el número de milisegundos desde la época.

  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

• La función de callback de UpdateAsync() toma un parámetro adicional en el objeto DataStoreKeyInfo que describe el estado actual de la clave. 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 límites al definir metadatos, consulta los límites de metadatos.

Almacenes de datos ordenados

Por defecto, los almacenes de datos no ordenan su contenido. Si necesitas obtener datos de manera ordenada, como en estadísticas de tabla de clasificación persistentes, llama a GetOrderedDataStore() en lugar de GetDataStore().

local DataStoreService = game:GetService("DataStoreService")

local characterAgeStore = DataStoreService:GetOrderedDataStore("CharacterAges")

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

El siguiente ejemplo ordena los datos de los 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")

-- Población del almacén de datos ordenado
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 en 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
		-- Verifica si se ha alcanzado la última página
		if pages.IsFinished then
			break
		else
			print("----------")
			-- Avanza a la siguiente página
			pages:AdvanceToNextPageAsync()
		end
	end
end

Leer múltiples entradas

Para leer múltiples entradas de almacen de datos ordenado en una sola solicitud, llama a BatchGetAsync() con un array de claves. Este es el contraparte por lotes para leer entradas una a la vez con GetAsync().

BatchGetAsync() devuelve un diccionario que mapea cada clave solicitada a una tabla con un campo value. Las claves que no existen se omiten del diccionario, así que confirma que una clave está presente antes de leer su valor.

Cada clave que solicitas cuenta como una solicitud de lectura, así que una sola llamada para N claves cuenta como N solicitudes contra el límite de lectura del almacén de datos ordenado.

El siguiente ejemplo lee tres puntuaciones de jugadores en una sola solicitud, luego recorre las claves y muestra cada puntuación que existe.

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 .. " no tiene ninguna entrada guardada")
		end
	end
end