Player

概览

字段	值
Kind	`Unit` · 单位 Unit
Realm	`common`

继承关系

Unit（4 属性 / 25 函数 / 6 事件）
- [Player]（4 属性 / 14 函数 / 11 事件）

继承成员

1 个来源 / 4 属性 / 25 函数 / 6 事件

来自 Unit（4 属性 / 25 函数 / 6 事件）
- 属性：AssetId、Name、Desc、Parent
- 函数：ClearAllChildren、GetChildren、GetDescendants、IsAncestorOf、IsDescendantOf、FindFirstAncestor、FindFirstAncestorWhichIsA、FindFirstAncestorOfClass、FindFirstChild、FindFirstChildWhichIsA、FindFirstChildOfClass、HasChildren、GetChildCount、GetChildAtIndex、SetAttribute、GetAttribute、GetAllProps、Clone、IsA、Destroy、GetPropertyChangedSignal、GetAttributeChangedSignal、FindFromPath、GetFullPath、GetDebugId
- 事件：ChildAdded、ChildRemoved、DescendantAdded、DescendantRemoving、AncestryChanged、Destroying

Player 代表当前局内的一名玩家，带有 UserId 唯一标识、所属 Camp 以及 PlayerGui 等界面引用，也是网络消息通信所使用的标识对象。通过 Character 属性可以取得玩家当前操控的单位，并围绕角色的创建与移除提供 CharacterAdded、CharacterRemoving 等事件。它还提供 GetName、IsVip、IsMapLiked、GetPartyId、GetJoinData、GetNetworkPing 等查询接口，以及 Kick、AddFriendWith、LoadCharacterAsync、ResetCharacterToSpawnLocation 等操作接口。

适用场景

常用于读取玩家档案与社交状态，例如用 IsVip、IsInFanClub、GetPartyId、GetJoinData 判断玩家身份与组队信息，或监听 Chatted、OnTeleport、MapLikeChanged 等事件驱动界面与逻辑更新。在客户端还常用 Players.LocalPlayer 取得本地玩家并访问其 PlayerGui.EuiManager，作为界面逻辑的入口。

使用要点

客户端使用 Players.LocalPlayer 取得本地玩家，服务端使用 Players:GetPlayerByUserId(userId) 取得指定玩家，返回值即为 Player 实例，不能自行构造。拿到实例后可直接调用 GetName、GetJoinData、GetNetworkPing 等方法读取信息，或用 GetCustomEventSignal(eventName) 取得自定义事件信号并 Connect 回调。涉及角色的逻辑应先读取 Character 或监听 CharacterAdded，确认单位存在后再操作，需要重新生成角色时调用 LoadCharacterAsync。

注意事项

Player 不能自行创建，应从 Players 获取。Character 可能尚未加载，访问前应判空或监听 CharacterAdded。客户端启动入口中的 Players.LocalPlayer 及其自定义属性信号代理也可能尚未完成初始化；当前运行包有脚本启动后立即调用 LocalPlayer:GetAttributeChangedSignal() 无法正常工作的反馈。需要监听初始阶段属性时，应先确认 LocalPlayer 可用并延迟注册（反馈实测约 1 秒），同时主动读取一次当前属性值，不能只依赖后续变化事件。

代码示例

客户端获取本地玩家名称

lua

-- @runtime client
local players = game:GetService("Players")
local player = players.LocalPlayer
if player ~= nil then
    print("本地玩家名称:", player:GetName())
end

属性 (4)

Name	类型	默认值	说明
`UserId`	`String`	`-`	UserId 是 Player 上的字符串类型属性，表示该玩家的唯一标识，可用于稳定地区分不同玩家。该属性在元数据中标记为只读，与玩家名称不是同一个概念。
`Character`	EggyUnit	`-`	Player 的 Character 属性，类型为 EggyUnit，表示当前由该玩家控制的单位。
`PlayerGui`	PlayerGui	`-`	Player 的 PlayerGui 属性，类型为 PlayerGui，代表该玩家专属的界面容器对象。
`Camp`	Camp	`-`	Player 的 Camp 属性，表示玩家所属的阵营，类型为 Camp。

关联类型

事件 (11)

CharacterAdded

签名：CharacterAdded(character: EggyUnit) 触发：local

当玩家的角色单位创建完成时触发，回调参数 character 为新创建的 EggyUnit。

⚙ 可在客户端或服务端监听；本地信号的作用域不表示该事件仅在客户端可用。

回调参数	类型	说明
`character`	EggyUnit	玩家角色

示例代码

监听角色创建并打印新角色

lua

-- @runtime client
-- 获取 Players 服务，再取本地玩家对象
local Players = game:GetService("Players")
local player = Players.LocalPlayer
if not player then
    print("本地玩家尚未就绪，无法监听角色事件")
    return
end

-- 只监听一次角色创建：角色生成时会带着 EggyUnit 回调
player.CharacterAdded:Once(function(character)
    -- character 是本次创建出来的蛋仔单位
    print("角色创建完成:", character)
end)

-- 同时主动读取一次当前角色，避免错过注册前已经创建的角色
print("当前角色:", player.Character)

CharacterRemoving

签名：CharacterRemoving(character: EggyUnit) 触发：local

当玩家角色销毁时触发的本地事件，回调会收到一个 EggyUnit 类型的参数 character，代表即将被销毁的角色单位。

⚙ 可在客户端或服务端监听角色移除；本地信号作用域不等同于客户端运行端。

回调参数	类型	说明
`character`	EggyUnit	玩家角色

示例代码

监听角色销毁并打印即将销毁的角色

lua

-- @runtime client
-- 获取 Players 服务与本地玩家
local Players = game:GetService("Players")
local player = Players.LocalPlayer
if not player then
    print("本地玩家尚未就绪，无法监听角色事件")
    return
end

-- 只监听一次角色销毁：角色被移除前会带着 EggyUnit 回调
player.CharacterRemoving:Once(function(character)
    -- character 是即将被销毁的蛋仔单位，可在此释放外部引用
    print("角色即将销毁:", character)
end)

-- 注册完成后读取一次当前角色，确认监听生效时的状态
print("当前角色:", player.Character)

OnTeleport

签名：OnTeleport(teleportState: TeleportState, mapId: String, spawnName: String) 触发：local

Player 的本地事件，当玩家传送状态变化时触发。回调参数依次为 teleportState（TeleportState 类型）、mapId（String 类型）与 spawnName（String 类型）。

回调参数	类型	说明
`teleportState`	TeleportState	传送状态
`mapId`	`String`	目标地图编号
`spawnName`	`String`	出生点名称

示例代码

监听传送状态变化

lua

-- @runtime client
local players = game:GetService("Players")
local localPlayer = players.LocalPlayer
if not localPlayer then
	return
end
-- 传送过程中状态会多次变化，这里只观察第一次
localPlayer.OnTeleport:Once(function(teleportState, mapId, spawnName)
	print("传送状态:", teleportState)
	print("目标地图:", mapId, "出生点:", spawnName)
end)
print("已注册 OnTeleport 监听")

Idled

签名：Idled(afkTime: Float) 触发：local

Player 的本地事件，当玩家无输入操作超过 2 分钟后触发，后续定期触发。回调参数 afkTime 为 Float 类型。

回调参数	类型	说明
`afkTime`	`Float`	玩家无输入操作的时间（秒）

示例代码

监听玩家挂机事件

lua

-- @runtime client
local players = game:GetService("Players")
local localPlayer = players.LocalPlayer
if not localPlayer then
	return
end
-- 长时间无输入后触发，afkTime 为累计挂机时长（秒）
localPlayer.Idled:Once(function(afkTime)
	print("玩家已挂机:", afkTime, "秒")
end)
print("已注册 Idled 监听")

LoseClient

签名：LoseClient() 触发：local

Player 的本地事件，当玩家客户端掉线或失联时触发，该事件没有回调参数。

⚙ 该事件用于服务端观察目标玩家客户端掉线或失联；不要在即将掉线的 LocalPlayer 客户端中依赖回调继续执行。

示例代码

服务端监听玩家客户端失联

lua

-- @runtime server
local players = game:GetService("Players")
players.PlayerAdded:Connect(function(player)
    player.LoseClient:Once(function()
        print("玩家客户端失联:", player:GetName())
    end)
end)

OnRelay

签名：OnRelay() 触发：local

Player 的 OnRelay 事件，当玩家顶号登录且客户端就绪后触发，回调不携带参数。

示例代码

监听顶号登录就绪

lua

-- @runtime client
-- 获取玩家服务与本地玩家对象
local players = game:GetService("Players")
local localPlayer = players.LocalPlayer
if localPlayer == nil then
    print("本地玩家尚未就绪")
    return
end
-- 监听顶号登录客户端就绪事件，该事件无参数
localPlayer.OnRelay:Once(function()
    print("顶号登录客户端已就绪")
end)
print("OnRelay 监听注册完成")

Chatted

签名：Chatted(message: String, channelName: String) 触发：local

Player 的本地事件，当玩家发送聊天消息时触发。回调参数为 message（字符串消息内容）与 channelName（字符串频道名），两者均为必填。

回调参数	类型	说明
`message`	`String`	聊天文本内容
`channelName`	`String`	所在频道名

示例代码

监听玩家聊天消息

lua

-- @runtime client
local players = game:GetService("Players")
local localPlayer = players.LocalPlayer
if not localPlayer then
	return
end
-- 聊天事件会同时给出消息内容与频道名
localPlayer.Chatted:Once(function(message, channelName)
	print("收到聊天消息:", message)
	print("所属频道:", channelName)
end)
print("已注册 Chatted 监听")

MapLikeChanged

签名：MapLikeChanged(oldValue: Int, newValue: Int) 触发：local

Player 的本地事件，当玩家对当前地图的点赞状态变更时触发。回调参数 oldValue 与 newValue 均为 Int 类型，分别表示变更前后的值。

回调参数	类型	说明
`oldValue`	`Int`	变更前状态（0=未点赞，1=已点赞）
`newValue`	`Int`	变更后状态（0=未点赞，1=已点赞）

示例代码

监听地图点赞状态变更

lua

-- @runtime client
local players = game:GetService("Players")
local localPlayer = players.LocalPlayer
if not localPlayer then
	return
end
-- 点赞或取消点赞都会触发，回调给出新旧值
localPlayer.MapLikeChanged:Once(function(oldValue, newValue)
	print("地图点赞状态变化:", oldValue, "->", newValue)
end)
print("已注册 MapLikeChanged 监听")

MapFavoriteChanged

签名：MapFavoriteChanged(oldValue: Int, newValue: Int) 触发：local

Player 的本地事件，当玩家对当前地图的收藏状态变更时触发。回调参数 oldValue 与 newValue 均为 Int 类型，分别表示变更前后的值。

回调参数	类型	说明
`oldValue`	`Int`	变更前状态（0=未收藏，1=已收藏）
`newValue`	`Int`	变更后状态（0=未收藏，1=已收藏）

示例代码

监听地图收藏状态变更

lua

-- @runtime client
local players = game:GetService("Players")
local localPlayer = players.LocalPlayer
if not localPlayer then
	return
end
-- 收藏状态变化时输出新旧值，便于同步界面显示
localPlayer.MapFavoriteChanged:Once(function(oldValue, newValue)
	print("地图收藏状态变化:", oldValue, "->", newValue)
end)
print("已注册 MapFavoriteChanged 监听")

AuthorSubscribeChanged

签名：AuthorSubscribeChanged(oldValue: Int, newValue: Int) 触发：local

Player 的本地事件，当玩家对当前地图作者的订阅状态变更时触发。回调参数 oldValue 与 newValue 均为 Int 类型，分别表示变更前后的值。

回调参数	类型	说明
`oldValue`	`Int`	变更前状态（0=未订阅，1=已订阅）
`newValue`	`Int`	变更后状态（0=未订阅，1=已订阅）

示例代码

监听作者订阅状态变更

lua

-- @runtime client
local players = game:GetService("Players")
local localPlayer = players.LocalPlayer
if not localPlayer then
	return
end
-- 回调直接给出变化前后的数值，便于对比展示
localPlayer.AuthorSubscribeChanged:Once(function(oldValue, newValue)
	print("作者订阅状态变化:", oldValue, "->", newValue)
end)
print("已注册 AuthorSubscribeChanged 监听")

InFanClubChanged

签名：InFanClubChanged(oldValue: Int, newValue: Int) 触发：local

Player 的本地事件，当玩家粉丝团加入状态变更时触发。回调参数 oldValue 与 newValue 均为 Int 类型，分别表示变更前后的值。

回调参数	类型	说明
`oldValue`	`Int`	变更前状态（0=未加入，1=已加入）
`newValue`	`Int`	变更后状态（0=未加入，1=已加入）

示例代码

监听粉丝团加入状态变更

lua

-- @runtime client
local players = game:GetService("Players")
local localPlayer = players.LocalPlayer
if not localPlayer then
	return
end
-- 加入或退出粉丝团时都会触发，可据新旧值判断方向
localPlayer.InFanClubChanged:Once(function(oldValue, newValue)
	print("粉丝团状态变化:", oldValue, "->", newValue)
end)
print("已注册 InFanClubChanged 监听")

函数 (14)

GetName

签名：GetName() -> String (玩家名称)

获取玩家名称，返回 String 类型结果。

返回值 String (玩家名称)

示例代码

获取玩家名称并用于提示文案

lua

-- @runtime client
local players = game:GetService("Players")
local localPlayer = players.LocalPlayer
if not localPlayer then
	return
end
-- 读取玩家名称后拼接到欢迎文案中
local playerName = localPlayer:GetName()
print("欢迎玩家:", playerName)

Kick

签名：Kick(reason?: String) -> void

将玩家踢出游戏。参数 reason 为可选的 String 类型说明。

⚙ 调用环境：服务端。通过 Players 服务获取目标 Player 后调用，用于服务器侧踢出指定玩家。

参数	类型	说明
`reason?`	`String`	踢出原因提示，踢出前向该玩家展示 tips

返回值 void

示例代码

踢出指定玩家

lua

-- @runtime server
local players = game:GetService("Players")

players.PlayerAdded:Once(function(player)
    print("踢出玩家:", player:GetName())
    player:Kick()
end)

IsVip

签名：IsVip() -> Bool (是否是乐园会员)

判断玩家是否是乐园会员，返回 Bool 类型结果。

返回值 Bool (是否是乐园会员)

示例代码

判断玩家是否是乐园会员

lua

-- @runtime client
local players = game:GetService("Players")
local localPlayer = players.LocalPlayer
if not localPlayer then
	return
end
-- 会员状态可用于决定是否解锁额外内容
local isVip = localPlayer:IsVip()
print("是否是乐园会员:", isVip)

IsMapLiked

签名：IsMapLiked() -> Bool (是否点赞本地图)

判断玩家是否点赞了本地图，返回 Bool 类型结果。

返回值 Bool (是否点赞本地图)

示例代码

判断玩家是否点赞本地图

lua

-- @runtime client
local players = game:GetService("Players")
local localPlayer = players.LocalPlayer
if not localPlayer then
	return
end
-- 读取点赞状态，用于初始化界面按钮
local isLiked = localPlayer:IsMapLiked()
print("是否点赞本地图:", isLiked)

IsMapFavorited

签名：IsMapFavorited() -> Bool (是否收藏本地图)

判断玩家是否收藏了本地图，返回 Bool 类型结果。

返回值 Bool (是否收藏本地图)

示例代码

判断玩家是否收藏本地图

lua

-- @runtime client
local players = game:GetService("Players")
local localPlayer = players.LocalPlayer
if not localPlayer then
	return
end
-- 返回值可直接用于同步收藏按钮的初始状态
local isFavorited = localPlayer:IsMapFavorited()
print("是否收藏本地图:", isFavorited)

IsInFanClub

签名：IsInFanClub() -> Bool (是否加入了粉丝团)

判断玩家是否加入了粉丝团，返回 Bool 类型结果。

返回值 Bool (是否加入了粉丝团)

示例代码

判断玩家是否已加入粉丝团

lua

-- @runtime client
local players = game:GetService("Players")
local localPlayer = players.LocalPlayer
if not localPlayer then
	return
end
-- 根据返回值决定是否展示粉丝团相关入口
local inFanClub = localPlayer:IsInFanClub()
print("是否加入粉丝团:", inFanClub)

GetPartyId

签名：GetPartyId() -> String (组队标识)

获取玩家在蛋仔岛上的组队标识，返回 String 类型结果。

返回值 String (组队标识)

示例代码

读取蛋仔岛组队标识

lua

-- @runtime client
local players = game:GetService("Players")
local localPlayer = players.LocalPlayer
if not localPlayer then
	return
end
-- 组队标识可用于判断玩家是否处于组队状态
local partyId = localPlayer:GetPartyId()
print("当前组队标识:", partyId)

GetJoinData

签名：GetJoinData() -> JoinData (玩家加入数据字典)

获取玩家加入游戏时携带的数据，返回 JoinData 类型对象。

返回值 JoinData (玩家加入数据字典)

示例代码

读取玩家加入游戏时携带的数据

lua

-- @runtime client
local players = game:GetService("Players")
local localPlayer = players.LocalPlayer
if not localPlayer then
	return
end
-- 非传送进入时部分字段不会出现，读取前先判空
local joinData = localPlayer:GetJoinData()
if joinData.SourceMapId then
	print("本次通过传送进入，来源地图:", joinData.SourceMapId)
else
	print("非传送进入，无来源地图信息")
end

GetNetworkPing

签名：GetNetworkPing() -> Float (玩家网络延迟)

获取玩家网络延迟（秒），返回 Float 类型结果。

⚙ 当前编辑器运行时在客户端调用会产生 Internal Error warning；服务端应从 Players:GetPlayers() 获取目标 Player 后读取网络延迟。

返回值 Float (玩家网络延迟)

示例代码

在服务端读取玩家网络延迟

lua

-- @runtime server
local player = game:GetService("Players"):GetPlayers()[1]
if player == nil then return end
print('玩家网络延迟（秒）:', player:GetNetworkPing())

ResetCharacterToSpawnLocation

签名：ResetCharacterToSpawnLocation(resetCamera: Bool) -> void

将角色复位到出生点。参数 resetCamera 为必填的 Bool 类型，用于指定是否同时复位相机。

参数	类型	说明
`resetCamera`	`Bool`	是否重置相机

返回值 void

示例代码

将角色复位到出生点

lua

-- @runtime client
local players = game:GetService("Players")
local localPlayer = players.LocalPlayer
if not localPlayer then
	return
end
-- 传入 true 表示复位角色的同时重置相机朝向
localPlayer:ResetCharacterToSpawnLocation(true)
print("已请求将角色复位到出生点")

IsFriendsWithAsync

签名：IsFriendsWithAsync(userId: String, checkCallback: Function) -> void

检查指定玩家是否为我的好友。需要传入 userId（String 类型）与 checkCallback（Function 类型）两个必填参数。

参数	类型	说明
`userId`	`String`	玩家编号
`checkCallback`	`Function`	检查结果回调

返回值 void

示例代码

检查与另一位在线玩家的好友关系

lua

-- @runtime client
local players = game:GetService("Players")
local localPlayer = players.LocalPlayer
if localPlayer == nil then return end

local target = nil
for _, candidate in ipairs(players:GetPlayers()) do
    if candidate ~= localPlayer then target = candidate break end
end
if target == nil then
    print("当前没有其他在线玩家可供检查")
    return
end

local targetUserId = tostring(target.UserId)
localPlayer:IsFriendsWithAsync(targetUserId, function(isFriend)
    print("好友关系:", target:GetName(), isFriend)
end)

AddFriendWith

签名：AddFriendWith(userId: String) -> void

向指定玩家发起添加好友请求。参数 userId 为必填的 String 类型玩家标识。

参数	类型	说明
`userId`	`String`	玩家编号

返回值 void

示例代码

向另一位在线玩家发起好友请求

lua

-- @runtime client
local players = game:GetService("Players")
local localPlayer = players.LocalPlayer
if localPlayer == nil then return end

local target = nil
for _, candidate in ipairs(players:GetPlayers()) do
    if candidate ~= localPlayer then target = candidate break end
end
if target == nil then
    print("当前没有其他在线玩家可供添加")
    return
end

local targetUserId = tostring(target.UserId)
localPlayer:AddFriendWith(targetUserId)
print("已向玩家发起好友请求:", target:GetName())

LoadCharacterAsync

签名：LoadCharacterAsync() -> void

异步加载玩家角色。函数无入参，声明中无返回值。

⚙ 该方法会异步触发 CharacterAdded；若需要观察加载结果，应先订阅事件再发起加载，避免角色快速创建时错过通知。

返回值 void

示例代码

异步加载玩家角色并等待创建事件

lua

-- @runtime client
local players = game:GetService("Players")
local localPlayer = players.LocalPlayer
if localPlayer == nil then return end

-- 先监听再加载，避免角色快速创建时错过 CharacterAdded
localPlayer.CharacterAdded:Once(function(character)
    print("角色加载完成:", character.Name)
end)
localPlayer:LoadCharacterAsync()

GetCustomEventSignal

签名：GetCustomEventSignal(eventName: String) -> Signal (自定义事件信号)

GetCustomEventSignal 是 Player 上的函数，用于按名称获取该玩家对应的自定义事件信号。调用时传入字符串参数 eventName（事件名称），返回一个 Signal 对象；对该 Signal 使用 Connect 或 Once 即可注册回调，在玩家触发这一自定义事件时收到通知。

参数	类型	说明
`eventName`	`String`	自定义事件名

返回值 Signal (自定义事件信号)

示例代码

获取本地玩家的自定义事件信号

lua

-- @runtime client
local players = game:GetService("Players")
local localPlayer = players.LocalPlayer
if localPlayer == nil then return end
local signal = localPlayer:GetCustomEventSignal("QuestUpdated")
if signal == nil then
    print('自定义事件不存在，请先确认事件名已注册')
    return
end
signal:Connect(function(payload)
    print("任务事件:", payload)
end)

推球撞方块

跟着做一个小游戏

边做边查

按需求查专题

疯狂农场

Player ​

概览 ​

继承关系 ​

继承成员 ​

适用场景 ​

使用要点 ​

注意事项 ​

代码示例 ​

客户端获取本地玩家名称 ​

属性 (4) ​

关联类型 ​

事件 (11) ​

CharacterAdded ​

CharacterRemoving ​

OnTeleport ​

Idled ​

LoseClient ​

OnRelay ​

Chatted ​

MapLikeChanged ​

MapFavoriteChanged ​

AuthorSubscribeChanged ​

InFanClubChanged ​

函数 (14) ​

GetName ​

Kick ​

IsVip ​

IsMapLiked ​

IsMapFavorited ​

IsInFanClub ​

GetPartyId ​

GetJoinData ​

GetNetworkPing ​

ResetCharacterToSpawnLocation ​

IsFriendsWithAsync ​

AddFriendWith ​

LoadCharacterAsync ​

GetCustomEventSignal ​

Player

概览

继承关系

继承成员

适用场景

使用要点

注意事项

代码示例

客户端获取本地玩家名称

属性 (4)

关联类型

事件 (11)

CharacterAdded

CharacterRemoving

OnTeleport

Idled

LoseClient

OnRelay

Chatted

MapLikeChanged

MapFavoriteChanged

AuthorSubscribeChanged

InFanClubChanged

函数 (14)

GetName

Kick

IsVip

IsMapLiked

IsMapFavorited

IsInFanClub

GetPartyId

GetJoinData

GetNetworkPing

ResetCharacterToSpawnLocation

IsFriendsWithAsync

AddFriendWith

LoadCharacterAsync

GetCustomEventSignal