用户和域范围用户 ID

Roblox 为每个用户分配一个独特的 域范围用户 ID，用于他们与之交互的每个游戏或应用程序。 本页面解释了域范围识别的工作原理以及如何在您的游戏代码中使用 User 类型。

以下概念是用户识别的核心：

域范围用户 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 和域范围用户 ID 都是标准整数，不会冲突，因此读取这些数字字段的现有代码继续工作。

存储用户身份

对于单个游戏中的数据存储键，请直接使用 user.Id：

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

对于可能被其他系统读取或需要完整域上下文的值，使用 ToString() 序列化 User：

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：数据存储、开放云工具、跨游戏引用。