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 control de permiso granular a tus almacenes de datos y acceder a ellos fuera de Studio o servidores de Roblox, puedes usar API de Open Cloud para almacenes de datos.

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

Para datos temporales que necesitas actualizar o acceder frecuentemente, usa 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 producción 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ítala 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 ⟩ Configuraciones.
2. Navega a Seguridad.
3. Habilita el interruptor Habilitar acceso de 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 creará uno cuando guardes 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 de 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 clave de la entrada y una función de callback que defina cómo deseas actualizar la entrada. Este callback recibe el valor actual y devuelve un nuevo valor basado en la lógica que definas. 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 la actualizó por última vez antes de hacer cambios.
• 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 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 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() e incrementar 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 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 claves:

• Definido por el servicio: Metadatos predeterminados de solo lectura, como el tiempo de la 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 etiquetado y categorización. Definido 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 la eliminación y el seguimiento 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 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 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 el tiempo en que se creó la clave, formateado 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 los 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 tablas 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 función recupera varias claves ordenadas basado en un orden de clasificación específico, tamaño de página, y valores mínimos/máximos.

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

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