Usuários e IDs de usuário com escopo

*Este conteúdo é traduzido por IA (Beta) e pode conter erros. Para ver a página em inglês, clique aqui.

O Roblox expõe um ID de usuário efetivo para cada usuário em cada jogo, grupo ou aplicativo. Dependendo do histórico do usuário com esse domínio, seu ID de usuário efetivo é seu ID de usuário global ou um ID de usuário com escopo. Esta página explica como os IDs de usuário efetivos funcionam 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:

ConceitoDescrição
UsuárioUma conta persistente no Roblox.
JogadorA representação de um usuário dentro do modelo de dados de um jogo em execução (veja Jogadores).
Tipo de dado UserUm tipo de dado que carrega o ID de usuário efetivo de um usuário e seu contexto de domínio. Este é o identificador padrão para referenciar usuários no código do jogo.
ID de usuário globalO ID de usuário a nível de plataforma que o Roblox atribui a cada conta. É globalmente único em todo o Roblox.
ID de usuário com escopoUm ID de usuário atribuído dentro de um domínio específico. Os IDs de usuário com escopo de um usuário são diferentes em cada jogo, grupo ou aplicativo.
ID de usuário efetivoO único ID de usuário que o Roblox expõe para um usuário dentro de um domínio.
Usuário pré-implementaçãoUm usuário que interagiu pela primeira vez com um domínio antes da implementação do ID de usuário com escopo. Nesse domínio, seu ID de usuário efetivo permanece sendo seu ID de usuário global.
Usuário pós-implementaçãoUm usuário que interagiu pela primeira vez com um domínio após a implementação do ID de usuário com escopo. Nesse domínio, seu ID de usuário efetivo é um ID de usuário com escopo.

IDs de usuário efetivos e domínios

Cada usuário tem um ID de usuário efetivo dentro de um jogo, grupo ou aplicativo específico. O Roblox não expõe IDs de usuário globais e com escopo separados para o mesmo usuário nesse domínio:

  • Um usuário pré-implementação tem seu ID de usuário global como seu ID de usuário efetivo.
  • Um usuário pós-implementação tem um ID de usuário com escopo como seu ID de usuário efetivo. Esse ID é significativo apenas dentro desse domínio.

No código do jogo, Player.UserId e Player.User.Id retornam esse ID de usuário efetivo e sempre têm o mesmo valor numérico (Player.User.Id é igual a Player.UserId), então seu código não precisa de lógica de ramificação para escolher entre eles.

O Roblox escopo a identidade do usuário em três tipos de domínios:

DomínioEscopado paraExemplo
Experiência (Enum.DomainType.EXPERIENCE)Uma experiência específicaID de um jogador em sua experiência
GrupoUm grupo específico do Roblox (comunidade)ID de um membro em seu grupo
Aplicativo OAuth (Enum.DomainType.OAUTH)Um aplicativo OAuth específicoID de um usuário em sua ferramenta externa

Como os IDs de usuário efetivos funcionam

Quando um jogador entra em seu jogo, ele tem um ID de usuário efetivo para aquele jogo. O ID de usuário efetivo de um usuário pós-implementação é um ID de usuário com escopo exclusivo para aquele jogo. Eles recebem um ID de usuário com escopo diferente em qualquer outro jogo, grupo ou aplicativo onde também sejam um usuário pós-implementação. Isso significa:

  • IDs de usuário efetivos são inteiros, sejam eles globais ou com escopo.
  • IDs de usuário efetivos são estáveis entre sessões dentro do mesmo domínio.
  • Um ID de usuário com escopo 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 domínio (tipo de domínio e ID de domínio) e o ID de usuário efetivo.

Cenário de exemplo

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

CenárioContexto do usuárioID de usuário efetivo visto pelo jogo
Usuário se conecta ao Jogo AUsuário pré-implementação123 (ID de usuário global, inalterado)
Usuário se conecta ao Jogo BUsuário pós-implementação500789 (ID de usuário com escopo para o Jogo B)
Usuário se conecta ao Jogo CUsuário pós-implementação302441 (ID de usuário com escopo para o Jogo C)

Usuários pré-implementação

Se um jogador for um usuário pré-implementação em seu jogo, seu ID de usuário efetivo permanece sendo seu ID de usuário global nesse jogo. Tanto Player.UserId quanto Player.User.Id retornam esse ID de usuário global. O Roblox não expõe um segundo ID de usuário para o jogador nesse jogo. Isso garante que as chaves do armazenamento de dados existentes, placares e inventários continuem funcionando sem alterações.

Domínio de grupo

Cada grupo do Roblox é seu próprio domínio. Um usuário tem um ID de usuário efetivo dentro de um grupo, separado de seu ID de usuário efetivo em qualquer jogo ou aplicativo OAuth:

Trabalhando com o Tipo de Usuário

User é a maneira padrão de identificar usuários no código do jogo. Um valor User carrega o ID de usuário efetivo junto com o tipo de domínio e ID de domínio, então o contexto de identidade sempre viaja com o identificador. Para detalhes completos da API, veja a referência de User.

Obter um Usuário de um Jogador

A principal maneira 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 efetivo:", user.Id) -- Sempre corresponde a player.UserId
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 efetivo conhecido dentro do jogo atual, use User.fromId():

local user = User.fromId(knownUserId)

Usando Usuário com APIs do motor

APIs do motor 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 motor que aceita IDs de usuário, ele é automaticamente encapsulado em um User internamente.

APIs do motor que retornam IDs de usuário

APIs do motor que retornam IDs de usuário numéricos retornam o ID de usuário efetivo do usuário:

  • Usuários pré-implementação — a API retorna o ID de usuário global do usuário.
  • Usuários pós-implementação — a API retorna o ID de usuário com escopo do usuário.

Player.UserId, Player.User.Id, e outras APIs do motor retornam esse mesmo ID de usuário efetivo para um usuário em seu jogo, então o código existente que lê campos de ID de usuário numéricos continua funcionando sem lógica de ramificação.

Solicitações e respostas do Open Cloud usam o mesmo ID de usuário efetivo para o domínio de destino. Eles não expõem um segundo ID de usuário para o mesmo usuário nesse domínio.

Armazenando a identidade do usuário

Use um ID de usuário efetivo numérico apenas para identificar um usuário dentro de um único domínio. Uma chave de armazenamento de dados em um jogo pode usar user.Id diretamente:

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

Quando outro domínio lê a identidade armazenada, como um aplicativo OAuth que modera usuários, armazene a string de ToString(). A string codifica o contexto do domínio junto com o ID de usuário efetivo. Usar apenas o inteiro pode aplicar uma ação ao usuário errado quando o mesmo número identifica um usuário diferente em outro domínio.

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, veja a referência de User.

Melhores práticas

  • Use Player.User como o identificador padrão em novos códigos.
  • Use o ID de usuário efetivo numérico apenas dentro de um único domínio, como chaves de armazenamento de dados para um jogo.
  • Use ToString() e fromString() quando outro domínio ler a identidade armazenada.

Quando usar Usuário ou Jogador

  • 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 do Open Cloud, referências entre jogos.
©2026 Roblox Corporation, Roblox, o logotipo Roblox e Powering Imagination estão entre nossas marcas registradas e não registradas nos EUA e em outros países.