Utenti e ID utente specifici del dominio

Roblox assegna a ciascun utente un ID utente specifico del dominio unico per gioco o app con cui interagiscono. Questa pagina spiega come funziona l'identificazione specifica del dominio e come utilizzare il tipo User nel codice del tuo gioco.

I seguenti concetti sono centrali per l'identificazione degli utenti:

ID utente specifici del dominio

Un ID utente specifico del dominio è un identificatore unico assegnato a un utente all'interno di un gioco o app specifica. A differenza di un ID utente globale, un ID utente specifico del dominio ha senso solo all'interno del dominio che lo ha emesso, quindi lo stesso utente ha un ID utente specifico del dominio diverso in ogni gioco o app con cui interagisce. I giocatori che si sono uniti al tuo gioco prima del rollout dell'ID specifico mantengono il loro ID utente globale originale in quel gioco (vedi Giocatori di ritorno).

I tipi di dominio sono rappresentati da Enum.DomainType:

Come funzionano gli ID specifici del dominio

Quando un giocatore si unisce al tuo gioco, riceve un ID utente specifico del dominio che è unico per quel gioco. Lo stesso giocatore che si unisce a un gioco diverso riceve un ID utente specifico del dominio diverso. Questo significa che:

• Gli ID utente specifici del dominio sono interi, simili agli ID utente globali esistenti.
• Un ID utente specifico del dominio non colliderebbe mai con alcun ID utente globale esistente.
• Lo stesso valore numerico può apparire in diversi domini per diversi utenti. La chiave unica è la combinazione di tipo di dominio, ID di dominio e ID utente specifico del dominio.

Scenario di esempio

Il seguente esempio dimostra come diversi giochi facciano riferimento allo stesso utente:

Giocatori di ritorno

Se un giocatore ha già partecipato al tuo gioco prima del rollout dell'ID utente specifico, mantiene il suo ID utente globale originale in quel gioco. Questo garantisce che le chiavi dell'archiviazione dei dati esistenti, le classifiche e gli inventari continuino a funzionare senza alcuna modifica.

Lavorare con il tipo Utente

User è il modo standard per identificare gli utenti nel codice del gioco. Un valore User porta con sé l'ID utente specifico del dominio insieme al tipo di dominio e all'ID di dominio, quindi il contesto identitario viaggia sempre con l'identificatore. Per dettagli completi sull'API, consulta il riferimento di User.

Ottenere un Utente da un Giocatore

Il modo principale per ottenere un User è da un Player connesso tramite Player.User:

local Players = game:GetService("Players")

Players.PlayerAdded:Connect(function(player)
    local user = player.User
    print("Domain user ID:", user.Id)
    print("Domain type:", user.DomainType)
    print("Domain ID:", user.DomainId)
end)

Costruire un Utente da un ID

Per creare un User da un ID utente noto all'interno del gioco corrente, usa User.fromId():

local user = User.fromId(knownUserId)

Utilizzare l'Utente con le API del motore

Le API del motore che accettano un parametro ID utente accettano anche valori User direttamente. È consigliato utilizzare User:

-- Entrambi i formati funzionano:
BadgeService:AwardBadge(player.User, badgeId)    -- Raccomandato
BadgeService:AwardBadge(player.UserId, badgeId)

-- Entrambi i formati funzionano:
local target = Players:GetPlayerByUserId(player.User) -- Raccomandato
local target = Players:GetPlayerByUserId(someUserId)

Quando un ID utente numerico viene passato a un'API del motore che accetta ID utente, viene automaticamente avvolto in un User internamente.

API del motore che restituiscono ID utente

Le API del motore che restituiscono ID utente numerici continuano a utilizzare gli stessi nomi di campo e tipi. Ogni ID restituito è un ID globale o un ID utente specifico del dominio a seconda che l'utente si sia unito al gioco prima o dopo il rollout dell'ID specifico:

• Giocatori di ritorno (prima partecipazione prima del lancio dell'ID specifico) — l'API restituisce l'ID utente globale dell'utente.
• Nuovi giocatori (prima partecipazione dopo il lancio dell'ID specifico) — l'API restituisce l'ID utente specifico del dominio dell'utente.

Entrambi gli ID utente globali e specifici del dominio sono interi standard che non collidono, quindi il codice esistente che legge questi campi numerici continua a funzionare.

Memorizzare l'identità dell'utente

Per le chiavi dell'archiviazione dati all'interno di un singolo gioco, utilizza direttamente user.Id:

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

Per i valori che possono essere letti da altri sistemi o necessitano di un contesto di dominio completo, serializza il User con ToString():

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

-- In seguito, ripristina dalla stringa
local user = User.fromString(encoded)

Per ulteriori dettagli sulle garanzie di serializzazione, consulta il riferimento di User.

Migliori pratiche

• Usa Player.User come identificatore standard nel nuovo codice.
• Usa ToString() e fromString() quando persisti o trasmetti un valore User.
• Non utilizzare un ID utente numerico di un dominio per identificare un utente in un altro dominio.

Quando usare Utente o Giocatore

• Usa Player per azioni in-server: movimento del personaggio, GUI, teletrasporto, chat, inventario.
• Usa User per identità che sopravvivono a una sessione: archiviazione dati, strumenti Open Cloud, riferimenti tra giochi.