Utenti e ID utente specifici

Roblox espone un ID utente efficace per ogni utente in ciascun gioco, gruppo o app. A seconda della storia dell'utente con quel dominio, il loro ID utente efficace è o il loro ID utente globale o un ID utente specifico. Questa pagina spiega come funzionano gli ID utente efficaci e come utilizzare il tipo User nel codice del tuo gioco.

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

ID utente efficaci e domini

Ogni utente ha un ID utente efficace all'interno di un gioco, gruppo o app specifico. Roblox non espone ID utente globali e specifici separati per lo stesso utente in quel dominio:

• Un utente pre-distribuzione ha il proprio ID utente globale come ID utente efficace.
• Un utente post-distribuzione ha un ID utente specifico come ID utente efficace. Quell'ID ha significato solo all'interno di quel dominio.

Nel codice del gioco, Player.UserId e Player.User.Id restituiscono entrambi questo ID utente efficace e hanno sempre lo stesso valore numerico (Player.User.Id è uguale a Player.UserId), quindi il tuo codice non ha bisogno di logica di ramificazione per scegliere tra di essi.

Roblox definisce l'identità dell'utente attraverso tre tipi di domini:

Come funzionano gli ID utente efficaci

Quando un giocatore entra nel tuo gioco, ha un ID utente efficace per quel gioco. L'ID utente efficace di un utente post-distribuzione è un ID utente specifico unico per quel gioco. Ricevono un ID utente specifico diverso in qualsiasi altro gioco, gruppo o app in cui sono anche un utente post-distribuzione. Questo significa:

• Gli ID utente efficaci sono interi, siano essi globali o specifici.
• Gli ID utente efficaci sono stabili attraverso le sessioni all'interno dello stesso dominio.
• Un ID utente specifico non collide con alcun ID utente globale esistente.
• Lo stesso valore numerico può apparire in domini diversi per utenti diversi. La chiave unica è la combinazione del dominio (tipo di dominio e ID dominio) e l'ID utente efficace.

Scenario di esempio

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

Utenti pre-distribuzione

Se un giocatore è un utente pre-distribuzione nel tuo gioco, il loro ID utente efficace rimane il loro ID utente globale in quel gioco. Sia Player.UserId che Player.User.Id restituiscono quell'ID utente globale. Roblox non espone un secondo ID utente per il giocatore in quel gioco. Questo garantisce che le chiavi del data store esistenti, le classifiche e gli inventari continuino a funzionare senza alcuna modifica.

Dominio del gruppo

Ogni gruppo Roblox è un proprio dominio. Un utente ha un ID utente efficace all'interno di un gruppo, separato dal loro ID utente efficace in qualsiasi gioco o applicazione OAuth:

• I controlli di gruppo in gioco non cambiano — I metodi del motore su Player come Player:IsInGroupAsync(), Player:GetRankInGroupAsync(), e Player:GetRoleInGroupAsync(), così come GroupService:PromptJoinAsync(), risolvono l'identità internamente senza esporre un ID utente.
• Le API di gruppo Open Cloud utilizzano il dominio del gruppo — Questo si applica agli endpoint che elencano o gestiscono le iscrizioni ai gruppi e le richieste di adesione.

Lavorare con il tipo Utente

User è il modo standard per identificare gli utenti nel codice del gioco. Un valore User porta l'ID utente efficace insieme al tipo di dominio e all'ID dominio, quindi il contesto dell'identità viaggia sempre con l'identificatore. Per dettagli completi sull'API, vedere il riferimento a 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("ID utente efficace:", user.Id) -- Sempre corrisponde a player.UserId
    print("Tipo di dominio:", user.DomainType)
    print("ID dominio:", user.DomainId)
end)

Costruire un Utente da un ID

Per creare un User da un ID utente efficace noto all'interno del gioco corrente, utilizzare 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. Si consiglia di utilizzare User:

-- Entrambe le forme funzionano:
BadgeService:AwardBadge(player.User, badgeId)    -- Raccomandato
BadgeService:AwardBadge(player.UserId, badgeId)

-- Entrambe le forme 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 racchiuso in un User internamente.

API del motore che restituiscono ID utente

Le API del motore che restituiscono ID utente numerici restituiscono l'ID utente efficace dell'utente:

• Utenti pre-distribuzione — l'API restituisce l'ID utente globale dell'utente.
• Utenti post-distribuzione — l'API restituisce l'ID utente specifico dell'utente.

Player.UserId, Player.User.Id, e altre API del motore restituiscono tutti questo stesso ID utente efficace per un utente nel tuo gioco, quindi il codice esistente che legge i campi ID utente numerici continua a funzionare senza logica di ramificazione.

Le richieste e le risposte di Open Cloud utilizzano lo stesso ID utente efficace per il dominio target. Non espongono un secondo ID utente per lo stesso utente in quel dominio.

Memorizzare l'identità dell'utente

Utilizza un ID utente efficace numerico solo per identificare un utente all'interno di un singolo dominio. Una chiave del data store in un gioco può utilizzare user.Id direttamente:

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

Quando un altro dominio legge l'identità memorizzata, come un'app OAuth che modera gli utenti, memorizza la stringa da ToString(). La stringa codifica il contesto del dominio insieme all'ID utente efficace. Utilizzare solo l'intero può applicare un'azione all'utente sbagliato quando lo stesso numero identifica un utente diverso in un altro dominio.

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

-- Più tardi, ripristina dalla stringa
local user = User.fromString(encoded)

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

Migliori pratiche

• Utilizza Player.User come identificatore standard nel nuovo codice.
• Utilizza l'ID utente efficace numerico solo all'interno di un singolo dominio, come le chiavi del data store per un gioco.
• Utilizza ToString() e fromString() quando un altro dominio legge l'identità memorizzata.

Quando utilizzare Utente o Giocatore

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