玩家对象

玩家对象表示一个在线的玩家，包含了玩家的一些属性，也可以通过玩家对象中的方法对玩家进行操作。

获取玩家对象的方法：

通过各种会传参玩家对象的事件获取
通过玩家数据管理器 PlayerInfoMaintainer 获取

PlayerInfoMaintainer

获取方法

在插件主类内，通过自身属性 game_ctrl 的 players 属性获取。

python

class MyPlugin(Plugin):
    ...

    def something(self):
        players: "PlayerInfoMaintainer" = self.game_ctrl.players

获取所有在线玩家的列表

python

players.getAllPlayers()

获取当前所有在线的玩家的玩家对象。

返回：
返回值类型说明
list[Player] 所有在线的玩家对象的列表

返回值类型	说明
list[Player]	所有在线的玩家对象的列表

获取机器人所对应的玩家对象

python

players.getBotInfo()

获取 ToolDelta 机器人所对应的玩家对象。

返回：
返回值类型说明
Player 玩家对象

返回值类型	说明
Player	玩家对象

通过玩家名获取玩家实例

python

players.getPlayerByName(name)

根据玩家名获取玩家对象。

参数：
参数类型说明
name str 玩家名
返回：
返回值类型说明
Player 玩家对象
None 玩家不存在

参数	类型	说明
name	str	玩家名

返回值类型	说明
Player	玩家对象
None	玩家不存在

通过 UUID 获取玩家实例

python

players.getPlayerByUUID(uuid)

根据玩家 UUID 获取玩家对象。

参数：
参数类型说明
uuid str | uuid.UUID 玩家 UUID，也可传入 uuid.UUID 对象
返回：
返回值类型说明
Player 玩家对象
None 玩家不存在

参数	类型	说明
uuid	str \| uuid.UUID	玩家 UUID，也可传入 `uuid.UUID` 对象

返回值类型	说明
Player	玩家对象
None	玩家不存在

通过 uniqueID 获取玩家对象

python

players.getPlayerByUniqueID(unique_id)

根据玩家 uniqueID 获取玩家对象。

参数：
参数类型说明
unique_id int 玩家唯一标识
返回：
返回值类型说明
Player 玩家对象
None 玩家不存在

参数	类型	说明
unique_id	int	玩家唯一标识

返回值类型	说明
Player	玩家对象
None	玩家不存在

通过 XUID 获取玩家实例

python

players.getPlayerByXUID(xuid)

根据玩家 XUID 获取玩家对象。

参数：
参数类型说明
xuid str 玩家 XUID
返回：
返回值类型说明
Player 玩家对象
None 玩家不存在

参数	类型	说明
xuid	str	玩家 XUID

返回值类型	说明
Player	玩家对象
None	玩家不存在

通过 DeviceID 获取玩家实例

python

players.getPlayerByDeviceID(did)

根据玩家 DeviceID 获取玩家对象。

参数：
参数类型说明
did str 玩家 DeviceID
返回：
返回值类型说明
Player 玩家对象
None 玩家不存在

参数	类型	说明
did	str	玩家 DeviceID

返回值类型	说明
Player	玩家对象
None	玩家不存在

通过 RuntimeID 获取玩家实例

python

players.getPlayerByRuntimeID(rt_id)

根据玩家 RuntimeID 获取玩家对象。

参数：
参数类型说明
rt_id int 玩家 RuntimeID
返回：
返回值类型说明
Player 玩家对象
None 玩家不存在

参数	类型	说明
rt_id	int	玩家 RuntimeID

返回值类型	说明
Player	玩家对象
None	玩家不存在

获取玩家能力

python

players.get_player_ability(player)

获取指定玩家的能力数据。

参数：
参数类型说明
player Player 玩家对象
返回：
返回值类型说明
Abilities 玩家能力
报错：
类型说明
ValueError 获取玩家能力超时

参数	类型	说明
player	Player	玩家对象

类型	说明
ValueError	获取玩家能力超时

遍历在线玩家

使用 for 循环遍历所有在线玩家。

示例：

python

for player in self.game_ctrl.players:
    self.print(player.name)

Player

玩家 Player 对象存储了玩家的各种信息，有许多方法对玩家执行功能。

属性名	类型	说明
name	str	玩家名称
uuid	str	玩家 UUID，玩家唯一标识，在不同租赁服中都相同
xuid	str	玩家 XUID。通常为玩家 UUID 后八位
unique_id	int	玩家唯一标识
device_id	str \| None	玩家设备 ID
runtime_id	int \| None	玩家运行时 ID
platform_chat_id	str	玩家平台聊天 ID，对于网易MC无用
build_platform	str	玩家游戏使用的平台
online	bool	玩家是否在线
abilities	Abilities	玩家拥有的能力权限

显示聊天栏信息

python

player.show(text)

对该玩家显示聊天栏消息。

参数：

参数名	类型	说明
text	str	显示的文本

示例：

python

player.show("Hello World")

等待输入

python

player.input()

等待并获取玩家在聊天栏输入的内容。

参数：

参数名	类型	说明
prompt	str	可选参数，显示的提示文本，默认不显示
timeout	float	可选参数，等待输入超时时间，默认为 30 秒

不同返回值的类型	说明
str	玩家在聊天栏输入的内容
None	等待玩家输入超时

示例：

python

resp = player.input("生命因何而沉睡？")
if resp == "因为我们终将从梦中醒来":
    player.show("回答正确！")
elif resp is None:
    player.show("看起来你已经陷入沉睡了...")
else:
    player.show("回答错误！")

显示标题

python

player.setTitle(title, subtitle)

对该玩家显示标题大字信息。

参数：

参数	类型	说明
title	str	显示的主标题
subtitle	str	可选参数，显示的副标题，默认为空

示例：

python

player.setTitle(
    "Hello World",
    "欢迎使用 ToolDelta"
)

显示行动栏消息

python

player.setActionbar(text)

对该玩家显示行动栏信息。

参数：

参数	类型	说明
text	str	显示的文本

示例：

python

player.setActionbar(
    "Hello World"
)

获取坐标

python

player.getPos()

获取玩家坐标。

参数：

参数	类型	说明
timeout	float	坐标获取超时时间，默认为 5 秒

多返回值类型	说明
int	玩家所在的维度ID
float	玩家所在的 X 坐标
float	玩家所在的 Y 坐标
float	玩家所在的 Z 坐标

报错：

类型	说明
TimeoutError	获取坐标返回超时

示例：

python

dim, x, y, z = player.getPos()
print(dim, x, y, z)
# output: 0 0.5 0.0 0.5
# 代表在主世界的 坐标 0.5, 0, 0.5 处

获取分数

python

player.getScore(scoreboard_name)

获取玩家的计分板分数。

参数：

参数名	类型	说明
scoreboard_name	str	计分板名称
timeout	float	获取计分板超时时间，默认为 5 秒

返回类型	说明
int	玩家的计分板分数

报错：

类型	说明
TimeoutError	获取计分板超时
ValueError	计分板不存在或玩家没有分数

示例：

python

money = player.getScore("金币")

获取物品数量

python

player.getItemCount(item_id)

获取玩家背包内某物品的数量。

参数：

参数名	类型	说明
item_id	str	物品 ID
item_data	int	可选参数，物品数据值，默认为 -1
timeout	float	可选参数，获取物品数量超时时间，默认为 5 秒

类型	说明
int	此物品的数量

报错：

类型	说明
TimeoutError	获取物品数量超时

获取玩家背包内各槽位物品

python

player.queryInventory()

返回：QueriedInventory

属性： QueriedInventory：

属性名	类型	说明
first	int	Unknown
last	int	Unknown
slotCount	int	总槽位数
slots	list[QueriedInventoryItem \| None]	槽位物品列表，为空则为 None

QueriedInventoryItem：

属性名	类型	说明
aux	int	物品数据值
enchantments	list[QueriedInventoryItemEnchant]	槽位物品附魔列表
freeStackSize	int	剩余空槽位数
id	str	物品 ID
maxStackSize	int	最大堆叠数
namespace	str	物品命名空间，如 "minecraft:"
stackSize	int	物品数量

QueriedInventoryItemEnchant：

属性名	类型	说明
level	int	附魔等级
name	str	附魔名称（经过本地化，如 "耐久 III"）
type	int	附魔类型 ID对照表文档

示例：

python

inventory = player.queryInventory()
slot_0 = inventory.slots[0]
if slot_0 is None:
    print("槽位为空")
else:
    print(slot_0.id)

获取玩家能力

python

player.abilities

获取该玩家的能力数据（Abilities 实例）。

警告

获取玩家能力时若长时间未收到对应数据包，会抛出 ValueError（获取玩家能力超时）。

返回值类型	说明
Abilities	玩家能力

设置玩家能力

python

player.setAbilities(abilities, upload=True)
player.abilities = abilities  # 等价的属性赋值写法

设置玩家能力权限。也可以通过给 player.abilities 属性赋值的方式设置。

参数：

参数名	类型	说明
abilities	Abilities	玩家权限能力
upload	bool	可选参数，是否立即上传到租赁服，默认为 True

示例：

python

ab = player.abilities
# 禁止该玩家 PVP
ab.attack_players = False
player.setAbilities(ab)

判断玩家是否为管理员

python

player.is_op()

判断该玩家是否为管理员（即命令权限等级是否大于等于 3）。

返回值类型	说明
bool	是否为管理员

获取可安全用于指令的名称

python

player.safe_name

获取经过转义、可安全拼接到指令中的玩家名（在玩家名两侧加上引号，并转义其中的反斜杠与双引号）。

获取玩家选择器（已弃用）

python

player.getSelector()

弃用

请改为使用 safe_name 属性。

获取包含玩家名的选择器，等价于 @a[name="{player.name}"]。

返回值类型	说明
str	选择器字符串

UnreadyPlayer

UnreadyPlayer 表示一个尚未与框架建立完整关联的玩家数据，通常出现在玩家刚加入、从接入点获取全局玩家数据等场景，需要调用 ready(parent) 转化为可用的 Player 对象。

属性名	类型	说明
uuid	str	玩家 UUID
unique_id	int	玩家唯一标识
name	str	玩家名称
xuid	str	玩家 XUID
platform_chat_id	str	玩家平台聊天 ID
runtime_id	int \| None	玩家运行时 ID
device_id	str \| None	玩家设备 ID
build_platform	int	玩家游戏使用的平台
online	bool	玩家是否在线，默认为 True
abilities	Abilities \| None	玩家能力，默认为 None

转化为 Player 对象

python

unready_player.ready(parent)

将该 UnreadyPlayer 转化为 Player 对象。

参数：

参数	类型	说明
parent	PlayerInfoMaintainer	玩家数据管理器

返回值类型	说明
Player	转化得到的玩家对象

Abilities 实例

Abilities 实例存储了玩家的能力信息。

属性名	类型	说明
build	bool	是否允许建造
mine	bool	是否允许挖掘
doors_and_switches	bool	是否允许与门和开关等交互
open_containers	bool	是否允许打开容器
attack_players	bool	是否允许攻击玩家
attack_mobs	bool	是否允许攻击怪物
operator_commands	bool	是否允许使用管理命令
teleport	bool	是否允许传送
player_permissions	int	玩家权限等级，0为访客，1为普通玩家，2为管理员，3为自定义权限（并不意味着是管理员！）
command_permissions	int	命令权限等级

自动推断权限等级

python

abilities.auto_permission_level()

根据各项能力开关自动推断权限等级。

返回值类型	说明
int	0 为访客，1 为普通玩家，2 为管理员，3 为自定义权限

序列化为整数

python

abilities.marshal()

将能力开关序列化为一个整数（仅包含 build、mine、doors_and_switches、open_containers、attack_players、attack_mobs、operator_commands、teleport 八项）。

返回值类型	说明
int	序列化后的整数

从整数反序列化

python

Abilities.unmarshal(abilities, player_permissions, command_permissions)

从整数及权限等级构造 Abilities 实例。

参数：

参数	类型	说明
abilities	int	序列化后的能力整数
player_permissions	int	玩家权限等级
command_permissions	int	命令权限等级

返回值类型	说明
Abilities	构造得到的玩家能力

Ability 枚举

Ability 是 IntEnum，枚举了玩家各项能力在能力位掩码中的位置，可用于 Abilities.marshal() 与 Abilities.unmarshal() 的位运算。

成员	值	说明
AbilityBuild	0	建造
AbilityMine	1	挖掘
AbilityDoorsAndSwitches	2	门与开关
AbilityOpenContainers	3	打开容器
AbilityAttackPlayers	4	攻击玩家
AbilityAttackMobs	5	攻击怪物
AbilityOperatorCommands	6	管理员命令
AbilityTeleport	7	传送
AbilityInvulnerable	8	无敌
AbilityFlying	9	飞行
AbilityMayFly	10	允许飞行
AbilityInstantBuild	11	瞬间建造
AbilityLightning	12	闪电
AbilityFlySpeed	13	飞行速度
AbilityWalkSpeed	14	行走速度
AbilityMuted	15	禁言
AbilityWorldBuilder	16	世界建筑者
AbilityNoClip	17	穿墙
AbilityPrivilegedBuilder	18	特权建筑者
AbilityCount	19	能力数量

玩家对象 ​

PlayerInfoMaintainer ​

获取方法 ​

获取所有在线玩家的列表 ​

获取机器人所对应的玩家对象 ​

通过玩家名获取玩家实例 ​

通过 UUID 获取玩家实例 ​

通过 uniqueID 获取玩家对象 ​

通过 XUID 获取玩家实例 ​

通过 DeviceID 获取玩家实例 ​

通过 RuntimeID 获取玩家实例 ​

获取玩家能力 ​

遍历在线玩家 ​

Player ​

显示聊天栏信息 ​

等待输入 ​

显示标题 ​

显示行动栏消息 ​

获取坐标 ​

获取分数 ​

获取物品数量 ​

获取玩家背包内各槽位物品 ​

获取玩家能力 ​

设置玩家能力 ​

判断玩家是否为管理员 ​

获取可安全用于指令的名称 ​

获取玩家选择器（已弃用） ​

UnreadyPlayer ​

转化为 Player 对象 ​

Abilities 实例 ​

自动推断权限等级 ​

序列化为整数 ​

从整数反序列化 ​

Ability 枚举 ​

玩家对象

PlayerInfoMaintainer

获取方法

获取所有在线玩家的列表

获取机器人所对应的玩家对象

通过玩家名获取玩家实例

通过 UUID 获取玩家实例

通过 uniqueID 获取玩家对象

通过 XUID 获取玩家实例

通过 DeviceID 获取玩家实例

通过 RuntimeID 获取玩家实例

获取玩家能力

遍历在线玩家

Player

显示聊天栏信息

等待输入

显示标题

显示行动栏消息

获取坐标

获取分数

获取物品数量

获取玩家背包内各槽位物品

获取玩家能力

设置玩家能力

判断玩家是否为管理员

获取可安全用于指令的名称

获取玩家选择器（已弃用）

UnreadyPlayer

转化为 Player 对象

Abilities 实例

自动推断权限等级

序列化为整数

从整数反序列化

Ability 枚举