ToolDelta Wiki

主题

game_utils 库 - 高级游戏接口 ​

获取方法 ​

python
from tooldelta import game_utils

game_utils 库 提供了一些使得获取游戏内数据更便捷的方法。

获取符合选择器的玩家列表 ​

python
def getTarget(sth: str, timeout: float = 5) -> list[str]

获取符合目标选择器的所有玩家的玩家名列表。

  • 参数：

    参数名类型说明
    sthstr玩家目标选择器（必须以 @ 开头）
    timeoutfloat获取超时时间， 默认为 5 秒， 超时引发 TimeoutError

  • 返回：

    • list[str]：玩家名列表， 若没有匹配目标则返回空列表

  • 异常：

    类型说明
    ValueError目标选择器格式错误， 或无法获取目标

获取详细坐标信息 ​

python
def getPos(target: str, timeout: float = 5) -> dict

获取玩家的坐标相关的详细信息。

  • 参数：

    参数类型说明
    targetstr玩家名 / 玩家目标选择器
    timeoutfloat获取超时时间，默认为 5 秒，超时引发 TimeoutError

  • 返回：

    • dict 表示坐标详细信息。 当 target 为 @a 选择器时， 返回以目标名为键的字典：
      • {目标名}：每个目标名对应一个内层字典，结构如下
        • "dimension" (int)：目标所在维度 ID
        • "position"：坐标字典
          • "x" (float)：目标 x 坐标
          • "y" (float)：目标 y 坐标（经过修正）
          • "z" (float)：目标 z 坐标
        • "yRot" (float)：目标水平视角
    • 当 target 为单个目标（或形如 @a[tag=...] 的单个匹配选择器）时， 直接返回上述内层字典 {"dimension": int, "position": {...}, "yRot": float}。

  • 报错：

    类型说明
    ValueError当目标玩家不存在时抛出该异常
    ValueError当获取位置信息失败时抛出该异常
    AttributeError当获取玩家 UUID 失败时抛出该异常

获取简略坐标 ​

python
def getPosXYZ(playername: str, timeout: float = 30) -> tuple[float, float, float]

获取玩家的简略坐标值，并以坐标三元元组返回。

  • 参数：

    参数类型说明
    playernamestr玩家名 / 玩家目标选择器
    timeoutfloat获取超时时间， 默认为 30 秒， 超时引发 TimeoutError

  • 返回：

    类型说明
    tuple[float, float, float]简略坐标三元元组 (x, y, z)

获取背包内物品数量 ​

python
def getItem(
    target: str,
    itemName: str,
    itemSpecialID: int = -1
) -> int

获取单个玩家背包内指定的物品的数量。

  • 参数：

    参数类型说明
    targetstr玩家名 / 玩家目标选择器（支持 @a 前缀选择器）
    itemNamestr物品的 Minecraft ID， 如 "minecraft:diamond"
    itemSpecialIDint物品的特殊值， 默认为 -1

  • 返回：

    类型说明
    int玩家持有的该物品的数量

  • 异常：

    类型说明
    ValueError未找到目标玩家， 或物品 ID 错误

获取计分板分数 ​

python
def getScore(
    scb_name: str,
    target: str,
    timeout: float = 30
) -> int

获取目标项的计分板对应分数。

  • 参数：

    参数名类型说明
    scb_namestr计分板名
    targetstr玩家名 / 目标选择器 / 计分板项名
    timeoutfloat获取超时时间，默认为 30 秒，超时引发 TimeoutError

  • 返回：

    • int: 分数

  • 异常：

    • ValueError: 计分板名 / 对应计分板项不存在

判断命令是否执行成功 ​

python
def isCmdSuccess(cmd: str, timeout: float = 30) -> bool

发送一条 Minecraft 指令并返回其执行成功与否。

  • 参数：

    参数名类型说明
    cmdstrMinecraft 指令
    timeoutfloat获取返回的超时时间，默认为 30 秒

  • 返回：

    • bool: 指令是否执行成功

  • 异常：

    • TimeoutError: 等待指令返回值超时

判断玩家是否为管理员 ​

python
def is_op(playername: str) -> bool

判断一个在线玩家是否为管理员。

  • 参数：

    参数名类型说明
    playernamestr玩家名

  • 返回：

    • bool: 是否为管理员

  • 异常：

    类型说明
    ValueError玩家不存在时抛出该异常

从展示框取出物品 ​

python
def take_item_out_item_frame(pos: tuple[float, float, float]) -> None

从物品展示框取出物品。

  • 参数：
    • pos (tuple[float, float, float])：物品展示框的坐标
  • 返回：
    • None

获取多项计分板分数 ​

python
def getMultiScore(scoreboardNameToGet: str, targetNameToGet: str) -> int | dict

获取单个或多个计分板分数项。

  • 参数：

    参数类型说明
    scoreboardNameToGetstr计分板名， 支持 * 通配符表示全部计分板
    targetNameToGetstr获取分数的对象 / 目标选择器， 支持 * 通配符表示全部对象

  • 返回：

    • int | dict：返回结果取决于参数：
      • 当 targetNameToGet 为 * 或以 @ 开头时， 返回 dict， 以计分板项名为键、 分数为值（即 {计分板项: 分数}）；
      • 当 scoreboardNameToGet 为 * 时， 返回 dict， 以目标名为键、 分数为值（即 {目标名: 分数}）；
      • 否则返回单个 int 分数。

  • 异常：

    类型说明
    Exception无法获取计分板分数， 或指定的计分板 / 目标不存在

查询玩家背包内容 ​

python
def queryPlayerInventory(selector: str) -> dict

查询玩家背包内容。

  • 参数：

    参数类型说明
    selectorstr目标选择器

  • 返回：

    类型说明
    dict玩家背包内容（由游戏返回的 DataSet 解析而来）

  • 异常：

    类型说明
    ValueError查询玩家背包内容失败

获取指定坐标的方块 ID ​

python
def getBlockTile(x: int, y: int, z: int) -> str

获取指定坐标的方块的 ID。

  • 参数：

    参数类型说明
    xintX 坐标
    yintY 坐标
    zintZ 坐标

  • 返回：

    类型说明
    str该坐标方块的 ID； 若该处为空气或超出世界范围， 返回 "air"

获取 tickingarea 列表 ​

python
def getTickingAreaList() -> dict

获取 tickingarea 列表。

  • 参数：

    • 无

  • 返回：

    类型说明
    dict以 tickingarea 名称为键的字典， 每个值包含 "dimension"（维度名）、 "start"（起始坐标列表）与 "end"（结束坐标列表）

  • 异常：

    类型说明
    AttributeError获取 tickingarea 列表失败

等待玩家聊天消息 ​

python
def waitMsg(playername: str, timeout: float = 30) -> str | None

等待玩家在聊天栏发送消息， 并获取其返回内容。

  • 参数：

    参数类型说明
    playernamestr玩家名
    timeoutfloat超时等待时间， 默认为 30 秒

  • 返回：

    类型说明
    str | None玩家发送的消息内容； 若超时或玩家中途退出则返回 None

向玩家发送原始文本 ​

python
def rawText(playername: str, text: str) -> None

向指定玩家发送原始文本消息。

  • 参数：

    参数类型说明
    playernamestr玩家名称
    textstr要发送的文本

  • 返回：

    • None

向玩家发送 tellraw 消息 ​

python
def tellrawText(playername: str, title: str | None = None, text: str = "") -> None

向指定玩家发送 tellraw 消息。

  • 参数：

    参数类型说明
    playernamestr玩家名称
    titlestr | None标题文本（可选）。 为 None 时直接发送 text
    textstr消息文本， 默认为空字符串

  • 返回：

    • None

设置玩家状态效果 ​

python
def set_player_effect(
    player_name,
    effect,
    duration,
    level,
    particle,
    icon_flicker=True,
    timeout=1.5
) -> bool | ValueError

设置玩家的状态效果。

  • 参数：

    参数类型说明
    player_namestr玩家名称（String）或是选择器（String）
    effectstr效果 ID（String）， 参考 EffectIDS 中内容
    durationint持续时间（int）， 为 0 代表永久（仅限 ToolDelta 运行时）， Max: 1000000
    levelint效果等级（int）， Max: 255
    particlebool是否显示粒子（Boolean）
    icon_flickerbool是否使图标闪烁（Boolean）， 默认为 True， 仅限 ToolDelta 运行时
    timeoutfloat超时时间（float）， 默认为 1.5， 可选

  • 返回：

    类型说明
    bool是否设置成功
    ValueError设置失败时返回的包含错误信息的 ValueError 对象（等级超过 255、 持续时间超过 1000000、 没有匹配目标或未知错误）

向服务器发送自定义事件 ​

python
def notifyToServer(gameNamespace: str, modNamespace: str, eventName: str, eventData: Any)

通过 PyRpc 数据包向服务器发送 ModEventC2S 事件。

  • 参数：

    参数类型说明
    gameNamespacestr游戏命名空间
    modNamespacestr模组命名空间
    eventNamestr事件名
    eventDataAny事件数据

  • 返回：

    • None

获取所有玩家列表 ​

python
def get_all_player() -> list[str]

获取所有玩家列表。

  • 参数：

    • 无

  • 返回：

    类型说明
    list[str]当前所有在线玩家的玩家名列表

获取机器人名称 ​

python
def get_robotname() -> str

获取机器人名称。

  • 参数：

    • 无

  • 返回：

    类型说明
    str机器人名称

DotCS 兼容方法 ​

以下方法为适配原 DotCS 而保留的兼容封装， 内部直接转发到 game_ctrl 上的对应方法， 详见 指令和数据包发送等。

python
def sendcmd(cmd, waitForResp=False, timeout=30)
def sendwscmd(cmd, waitForResp=False, timeout=30)
def sendwocmd(cmd)
def sendPacket(pktID, pkt)
  • sendcmd(cmd, waitForResp=False, timeout=30)：发送命令到游戏控制器， 可选择是否等待响应； waitForResp 为 False 时返回 None， 否则返回 Packet_CommandOutput 对象。
  • sendwscmd(cmd, waitForResp=False, timeout=30)：发送 WSCMD 命令到游戏控制器， 返回 Packet_CommandOutput | None。
  • sendwocmd(cmd)：发送 WO 命令到游戏控制器， 返回 None。
  • sendPacket(pktID, pkt)：发送数据包给游戏控制器， 返回 None。