Usuarios e identificadores de usuario con ámbito de dominio

Roblox asigna a cada usuario un identificador de usuario con ámbito de dominio único por juego o aplicación con la que interactúa. Esta página explica cómo funciona la identificación con ámbito de dominio y cómo utilizar el tipo User en el código de tu juego.

Los siguientes conceptos son fundamentales para la identificación de usuarios:

Identificadores de usuario con ámbito de dominio

Un identificador de usuario con ámbito de dominio es un identificador único asignado a un usuario dentro de un juego o aplicación específica. A diferencia de un identificador de usuario global, un identificador de usuario con ámbito de dominio solo tiene sentido dentro del dominio que lo emitió, por lo que el mismo usuario tiene un identificador de usuario con ámbito de dominio diferente en cada juego o aplicación con la que interactúa. Los jugadores que se unieron a tu juego antes del lanzamiento del ID con ámbito conservan su identificador de usuario global original en ese juego (ver Jugadores regresantes).

Los tipos de dominio están representados por Enum.DomainType:

Cómo funcionan los identificadores con ámbito de dominio

Cuando un jugador se une a tu juego, recibe un identificador de usuario con ámbito de dominio que es único para ese juego. El mismo jugador al unirse a un juego diferente recibe un identificador de usuario con ámbito de dominio diferente. Esto significa:

• Los identificadores de usuario con ámbito de dominio son enteros, similares a los identificadores de usuario globales existentes.
• Un identificador de usuario con ámbito de dominio no se superpone con ningún identificador de usuario global existente.
• El mismo valor numérico puede aparecer en diferentes dominios para diferentes usuarios. La clave única es la combinación de tipo de dominio, ID de dominio e identificador de usuario con ámbito de dominio.

Escenario de ejemplo

El siguiente ejemplo demuestra cómo diferentes juegos hacen referencia al mismo usuario:

Jugadores regresantes

Si un jugador ya se unió a tu juego antes del lanzamiento del ID de usuario con ámbito, conserva su identificador de usuario global original en ese juego. Esto garantiza que las claves del almacén de datos existentes, las tablas de clasificación y los inventarios continúen funcionando sin cambios.

Trabajando con el tipo Usuario

User es la forma estándar de identificar usuarios en el código del juego. Un valor User lleva consigo el identificador de usuario con ámbito de dominio junto con el tipo de dominio y el ID de dominio, por lo que el contexto de identidad siempre viaja con el identificador. Para obtener detalles completos de la API, consulta la referencia de User.

Obtener un Usuario de un Jugador

La forma principal de obtener un User es a partir de un Player conectado a través de Player.User:

local Players = game:GetService("Players")

Players.PlayerAdded:Connect(function(player)
    local user = player.User
    print("Identificador de usuario de dominio:", user.Id)
    print("Tipo de dominio:", user.DomainType)
    print("ID de dominio:", user.DomainId)
end)

Construir un Usuario a partir de un ID

Para crear un User a partir de un ID de usuario conocido dentro del juego actual, utiliza User.fromId():

local user = User.fromId(knownUserId)

Usando Usuario con APIs del motor

Las APIs del motor que aceptan un parámetro de ID de usuario también aceptan valores User directamente. Se recomienda usar User:

-- Ambas formas funcionan:
BadgeService:AwardBadge(player.User, badgeId)    -- Recomendado
BadgeService:AwardBadge(player.UserId, badgeId)

-- Ambas formas funcionan:
local target = Players:GetPlayerByUserId(player.User) -- Recomendado
local target = Players:GetPlayerByUserId(someUserId)

Cuando se pasa un ID numérico de usuario a una API del motor que acepta IDs de usuario, se envuelve automáticamente en un User internamente.

APIs del motor que devuelven IDs de usuario

Las APIs del motor que devuelven identificadores de usuario numéricos continúan usando los mismos nombres de campo y tipos. Cada ID devuelto es ya sea un ID global o un identificador de usuario con ámbito de dominio, dependiendo de si el usuario se unió al juego antes o después del lanzamiento del ID con ámbito:

• Jugadores regresantes (primera unión antes del lanzamiento del ID con ámbito) — la API devuelve el ID global del usuario.
• Nuevos jugadores (primera unión después del lanzamiento del ID con ámbito) — la API devuelve el ID de usuario con ámbito de dominio del usuario.

Tanto los identificadores de usuario globales como los identificadores de usuario con ámbito de dominio son enteros estándar que no colisionan, por lo que el código existente que lee estos campos numéricos sigue funcionando.

Almacenando la identidad del usuario

Para claves de almacén de datos dentro de un solo juego, utiliza user.Id directamente:

local key = ("player_%d"):format(player.User.Id)
PlayerDataStore:SetAsync(key, data)

Para valores que pueden ser leídos por otros sistemas o que necesitan un contexto de dominio completo, serializa el User con ToString():

local encoded = player.User:ToString()
SomeDataStore:SetAsync("support_ticket_user", encoded)

-- Más tarde, restaura desde la cadena
local user = User.fromString(encoded)

Para más detalles sobre las garantías de serialización, consulta la referencia de User.

Mejores prácticas

• Utiliza Player.User como el identificador estándar en un nuevo código.
• Utiliza ToString() y fromString() al persistir o transmitir un valor User.
• No utilices un ID de usuario numérico de un dominio para identificar a un usuario en otro dominio.

Cuándo usar Usuario o Jugador

• Utiliza Player para acciones en servidor: movimiento de personajes, GUI, teletransportación, chat, inventario.
• Utiliza User para identidad que perdura más allá de una sesión: almacenes de datos, herramientas de Open Cloud, referencias entre juegos.