Usuários e IDs de usuário com escopo de domínio

A Roblox atribui a cada usuário um ID de usuário com escopo de domínio único por jogo ou aplicativo com o qual eles interagem. Esta página explica como a identificação com escopo de domínio funciona e como usar o tipo User no código do seu jogo.

Os seguintes conceitos são centrais para a identificação do usuário:

IDs de usuário com escopo de domínio

Um ID de usuário com escopo de domínio é um identificador único atribuído a um usuário dentro de um jogo ou aplicativo específico. Ao contrário de um ID de usuário global, um ID de usuário com escopo de domínio só é significativo dentro do domínio que o emitiu, portanto, o mesmo usuário tem um ID de usuário com escopo de domínio diferente em cada jogo ou aplicativo com o qual interage. Jogadores que entraram no seu jogo antes da implementação do ID escopado mantêm seu ID de usuário global original naquele jogo (veja Jogadores que retornam).

Os tipos de domínio são representados por Enum.DomainType:

Como funcionam os IDs com escopo de domínio

Quando um jogador entra no seu jogo, ele recebe um ID de usuário com escopo de domínio que é único para aquele jogo. O mesmo jogador entrando em um jogo diferente recebe um ID de usuário com escopo de domínio diferente. Isso significa:

• IDs de usuário com escopo de domínio são inteiros, similares aos IDs de usuário globais existentes.
• Um ID de usuário com escopo de domínio não colide com nenhum ID de usuário global existente.
• O mesmo valor numérico pode aparecer em diferentes domínios para diferentes usuários. A chave única é a combinação do tipo de domínio, ID do domínio e ID de usuário com escopo de domínio.

Cenário de exemplo

O exemplo a seguir demonstra como diferentes jogos referenciam o mesmo usuário:

Jogadores que retornam

Se um jogador já entrou no seu jogo antes da implementação do ID de usuário escopado, ele mantém seu ID de usuário global original naquele jogo. Isso garante que as chaves de armazenamento de dados, placares e inventários existentes continuem a funcionar sem alterações.

Trabalhando com o Tipo User

User é a forma padrão de identificar usuários no código do jogo. Um valor User carrega o ID de usuário com escopo de domínio juntamente com o tipo de domínio e ID de domínio, de modo que o contexto de identidade sempre acompanha o identificador. Para detalhes completos da API, consulte a referência User.

Obter um Usuário de um Jogador

A principal forma de obter um User é a partir de um Player conectado via Player.User:

local Players = game:GetService("Players")

Players.PlayerAdded:Connect(function(player)
    local user = player.User
    print("ID de usuário de domínio:", user.Id)
    print("Tipo de domínio:", user.DomainType)
    print("ID de domínio:", user.DomainId)
end)

Construir um Usuário a partir de um ID

Para criar um User a partir de um ID de usuário conhecido dentro do jogo atual, use User.fromId():

local user = User.fromId(knownUserId)

Usando Usuário com APIs do engine

APIs do engine que aceitam um parâmetro de ID de usuário também aceitam valores User diretamente. Usar User é recomendado:

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

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

Quando um ID de usuário numérico é passado para uma API do engine que aceita IDs de usuário, ele é automaticamente encapsulado em um User internamente.

APIs do engine que retornam IDs de usuários

APIs do engine que retornam IDs de usuários numéricos continuam a usar os mesmos nomes de campos e tipos. Cada ID retornado é ou um ID global ou um ID de usuário com escopo de domínio, dependendo se o usuário entrou no jogo antes ou depois da implementação do ID escopado:

• Jogadores que retornam (entrou pela primeira vez antes do lançamento do ID escopado) — a API retorna o ID global do usuário.
• Novos jogadores (primeira entrada após o lançamento do ID escopado) — a API retorna o ID de usuário com escopo de domínio do usuário.

Tanto os IDs de usuário globais quanto os com escopo de domínio são inteiros padrão que não colidem, portanto o código existente que lê esses campos numéricos continua a funcionar.

Armazenando a identidade do usuário

Para chaves de armazenamento de dados dentro de um único jogo, use user.Id diretamente:

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

Para valores que podem ser lidos por outros sistemas ou que precisam de contexto de domínio completo, serialize o User com ToString():

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

-- Mais tarde, restaure a partir da string
local user = User.fromString(encoded)

Para mais detalhes sobre garantias de serialização, consulte a referência User.

Melhores práticas

• Use Player.User como o identificador padrão em novos códigos.
• Use ToString() e fromString() ao persistir ou transmitir um valor User.
• Não use um ID de usuário numérico de um domínio para identificar um usuário em outro domínio.

Quando usar User ou Player

• Use Player para ações no servidor: movimento de personagem, GUI, teletransporte, chat, inventário.
• Use User para identidade que sobrevive a uma sessão: armazenamento de dados, ferramentas Open Cloud, referências entre jogos.