使用者和域範圍的使用者 ID

Roblox 為每個用戶分配一個唯一的 域範圍使用者 ID，這是針對他們互動的每個遊戲或應用程式的。這個頁面解釋了域範圍識別的工作原理，以及如何在您的遊戲代碼中使用 User 類型。

以下概念是用戶識別的核心：

域範圍使用者 ID

域範圍使用者 ID 是分配給特定 遊戲 或 應用程式 中用戶的唯一標識符。與全局使用者 ID 不同，域範圍使用者 ID 僅在發出該 ID 的域內有意義，因此相同的用戶在他們互動的每個遊戲或應用中都有不同的域範圍使用者 ID。在域範圍 ID 推出之前加入遊戲的玩家在該遊戲中保持原有的全局使用者 ID（請參見 Returning players）。

域類型由 Enum.DomainType 表示：

域範圍 ID 的工作原理

當玩家加入您的遊戲時，他們會獲得一個對該遊戲唯一的域範圍使用者 ID。相同的玩家在加入不同的遊戲時會獲得一個不同的域範圍使用者 ID。這意味著：

• 域範圍使用者 ID 是整數，類似於現有的全局使用者 ID。
• 域範圍使用者 ID 不會與任何現有的全局使用者 ID 發生衝突。
• 相同的數值可能會在不同的域中出現在不同的用戶之間。唯一的鍵是域類型、域 ID 和域範圍使用者 ID 的組合。

示例場景

以下示例演示了不同遊戲如何引用相同的用戶：

返回玩家

如果玩家在範圍使用者 ID 推出之前已經加入您的遊戲，他們在該遊戲中會保持原有的全局使用者 ID。這確保了現有的數據存儲鍵、排行榜和庫存繼續正常運作，無需任何更改。

使用使用者類型

User 是在遊戲代碼中識別用戶的標準方式。User 值帶有域範圍使用者 ID 以及域類型和域 ID，因此身份上下文始終與標識符一起傳遞。 有關完整 API 詳細信息，請參閱 User 參考。

從玩家獲取使用者

獲取 User 的主要方法是通過連接的 Player，通過 Player.User：

local Players = game:GetService("Players")

Players.PlayerAdded:Connect(function(player)
    local user = player.User
    print("域用戶 ID:", user.Id)
    print("域類型:", user.DomainType)
    print("域 ID:", user.DomainId)
end)

從 ID 構造使用者

要從當前遊戲中的已知用戶 ID 創建 User，請使用 User.fromId()：

local user = User.fromId(knownUserId)

使用使用者與引擎 API

接受用戶 ID 參數的引擎 API 也可以直接接受 User 值。建議使用 User：

-- 兩種形式均可行：
BadgeService:AwardBadge(player.User, badgeId)    -- 建議使用
BadgeService:AwardBadge(player.UserId, badgeId)

-- 兩種形式均可行：
local target = Players:GetPlayerByUserId(player.User) -- 建議使用
local target = Players:GetPlayerByUserId(someUserId)

當數字用戶 ID 傳遞給接受用戶 ID 的引擎 API 時，它會自動包裝為一個內部的 User。

返回用戶 ID 的引擎 API

返回數字用戶 ID 的引擎 API 繼續使用相同的字段名稱和類型。每個返回的 ID 是全局 ID 或域範圍使用者 ID，具體取決於用戶是在範圍 ID 推出之前還是之後加入遊戲的：

• 返回玩家（在範圍 ID 推出之前首次加入）— API 返回用戶的全局使用者 ID。
• 新玩家（在範圍 ID 推出後首次加入）— API 返回用戶的域範圍使用者 ID。

全局和域範圍使用者 ID 都是標準整數，不會發生衝突，因此現有代碼可以繼續正常讀取這些數字字段。

存儲用戶身份

對於單一遊戲中的數據存儲鍵，直接使用 user.Id：

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

對於可能被其他系統讀取或需要完整域上下文的值，使用 User 進行序列化 ToString()：

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

-- 稍後，從字符串恢復
local user = User.fromString(encoded)

有關序列化保證的更多詳細信息，請參閱 User 參考。

最佳實踐

• 在新代碼中使用 Player.User 作為標準標識符。
• 在持久化或傳輸 User 值時，使用 ToString() 和 fromString()。
• 不要使用來自一個域的數字用戶 ID 來識別另一個域中的用戶。

何時使用使用者或玩家

• 對於伺服器內操作，使用 Player：角色移動、GUI、傳送、聊天、庫存。
• 對於超出會話的身份，使用 User：數據存儲、Open Cloud 工具、跨遊戲引用。