class Player

The Player class represents a player on the server. It can be used to query information about the player or manipulate them, such as getting or setting their position, orientation, world, gamemode and more.

Important

The Player is also an Entity and can do everything Entity can.

Do not instantiate the Player class directly but use one of the following methods instead:

player = mc.getPlayer()  # get any single online player
players = mc.getPlayerList()  # get list of all online players
playerfoo = mc.getOfflinePlayer("foo")  # get player with name 'foo' even if offline

Once you have your players you can use them in a multitude of ways:

player.pos  # get the current position of player
player.pos = Vec3(0, 0, 0)  # teleport player to origin
player.world  # get current world the player is in
player.world = mc.end  # teleport player into end
player.facing  # get direction player is currently looking at as directional vector
player.facing = Vec3().east()  # make player face straight east
# use teleport if you want to set position, facing direction and/or world at once:
player.teleport(pos=Vec3(0, 0, 0), world=mc.end)  # teleport player into origin in the end

# other modifiers
player.kill()  # kill player
player.creative()  # change player gamemode to creative
player.giveItems("snowball", 64)  # give player 64 snowballs into inventory
player.giveEffect("glowing", 5)  # give player glowing for 5 seconds
player.runCommand("clear")  # run command as player and clear player inventory
...

Note

Whether or not exceptions from operations on offline players are ignored is controlled by the global variable mcpq.player.ALLOW_OFFLINE_PLAYER_OPS, which is True by default. Players can go offline at any time and even checking with online before every operation will not guarantee that the player is online by the time the operation is received by the server. To make life easier all PlayerNotFound exceptions will be caught and ignored if mcpq.player.ALLOW_OFFLINE_PLAYER_OPS is True. Note that this will make it look like the operation succeeded, even if the player was (already) offline. Instead, use PlayerJoinEvent, PlayerLeaveEvent or update your online players regularly with mc.getPlayerList() to control the state of your online players.

Note

The number of times the player data will be updated is controlled by the global variable mcpq.player.CACHE_PLAYER_TIME, which is 0.2 by default. This means, using a player’s position will initially query the position from the server but then use this position for 0.2 seconds before updating the position again (as long as the position is not set in the mean time). The same holds true for all other properties of the player. This improves performance but may also cause bugs or problems if the interval in which the up-to-date position is requred is lower than mcpq.player.CACHE_PLAYER_TIME.

property name: str

The name of this player, equivalent to id

property type: Block

The EntityType of the player, is always "player"

property online: bool

Whether the player is currently online

property loaded: bool

Not applicable to player, use online instead

remove() → None

Not applicable to player, use kill() or kick() instead

gamemode(mode: Literal['adventure', 'creative', 'spectator', 'survival']) → None

Set the players gamemode to mode

Parameters:

mode (Literal["adventure", "creative", "spectator", "survival"]) – the gamemode the player should be set to

adventure() → None

Equivalent to gamemode() with argument "adventure"

creative() → None

Equivalent to gamemode() with argument "creative"

spectator() → None

Equivalent to gamemode() with argument "spectator"

survival() → None

Equivalent to gamemode() with argument "survival"

giveItems(item: str | Block, amount: int = 1, *, nbt: NbtCompound | None = None) → None

Put amount of certain item into the player’s inventory. The item can be a string or a Block with component data:

mc.getPlayer().giveItems("snowball", 64)  # give player 64 snowballs (4 stacks of 16)
sword = mc.Block("diamond_sword").withData({"enchantments": {"sharpness": 5}})
# item can be given as is
mc.getPlayer().giveItems(sword)  # give player enchanted sword
# blocks have to be changed to block_state format
b = mc.Block("acacia_stairs").withData({"waterlogged": True})
mc.getPlayer().giveItems(b.asBlockStateForItem())  # give player already waterlogged stairs

Note

nbt is only used for servers prior to 1.20.5 and will be removed in the future. All more modern servers use ComponentData, which can be set on the item.

postToChat(*objects, sep: str = ' ') → None

Print objects in chat separated by sep and only visible to player. All objects are converted to strings using str() first.

p = mc.getPlayer()
p.postToChat(f"Hello {p.name}, only you can see this")

You can also use the module mcpq.text to color or markup your chat messages.

from mcpq import text
p.postToChat(text.RED + text.BOLD + "super " + text.RESET + text.BLUE + "cool!")

Parameters:

sep (str, optional) – the separator between each object, defaults to “ “

kick() → None

ban() → None

pardon() → None

op() → None

deop() → None

runCommand(command: str) → None

Run the command as if it was typed in chat as /-command by and at the location of the given entity. Returns immediately without waiting for the command to finish executing.

entity.runCommand("kill")  # kill this entity
entity.runCommand("effect give @s glowing")  # @s refers to this entity

Parameters:

command (str) – the command without the slash /

runCommandBlocking(command: str) → str

Run the command as if it was typed in chat as /-command by and at the location of the given entity. Blocks and waits for the command to finish executing returning the command’s result.

response = entity.runCommandBlocking("data get entity @s")  # @s refers to this entity

Caution

The plugin that is built against the spigot-Bukkit API does not fully support the return of command output, specifically the capturing of output of vanilla commands. Instead it only supports the capturing of Bukkit commands, which can be seen with mc.runCommandBlocking("help Bukkit").split("\n")

Parameters:

command (str) – the command without the slash /

Returns:

the console output of the command

Return type:

str

property id: str

The unique id of the entity on the server

property pos: Vec3

Get the position as Vec3 the entity is at. When assigned to is equivalent to self.teleport(pos=pos)

property facing: Vec3

Get the directional Vec3 unit-vector the entity is facing in. When assigned to is equivalent to self.teleport(facing=facing)

property world: World

Get the world/dimension as World the entity is in. When assigned to is equivalent to self.teleport(world=world) and can also be used with the key of the world instead of the world object.

getEntitiesAround(distance: float, type: str | Block | None = None, only_spawnable: bool = True) → list[Entity]

Get all other entities in a certain radius around this one

Parameters:

• distance (float) – the radius around this entity in which to get other entities

• type (str | EntityType | None, optional) – the type of entitiy to get, get all types if None, defaults to None

• only_spawnable (bool, optional) – if True get only entities that can spawn, otherwise also get things like projectiles and drops, defaults to True

Returns:

list of filtered entities with distance from this one less or equal to distance

Return type:

list[Entity]

getNbt() → NbtCompound | None

Get the entity’s NBT data as NBT or None if the entity is not loaded. The data is not cached NBT data is always queried on call.

Caution

This function requires command output captuing. The plugin that is built against the spigot-Bukkit API does not fully support the return of command output.

giveEffect(effect: str, seconds: int = 0, amplifier: int = 0, particles: bool = True) → None

Give this entity a (potion) effect

Parameters:

• effect (str) – the name of the effect, e.g., "glowing"

• seconds (int, optional) – the number of seconds the effect should persist or infinite duration if 0, defaults to 0

• amplifier (int, optional) – the strength of the effect, amplifier + 1 is the level of the effect, defaults to 0

• particles (bool, optional) – whether or not to show particles for the effect, defaults to True

kill() → None

Kill this entity

replaceHelmet(armortype: Block | str = 'leather_helmet', unbreakable: bool = True, binding: bool = True, vanishing: bool = False, color: Literal['white', 'orange', 'magenta', 'light_blue', 'yellow', 'lime', 'pink', 'gray', 'light_gray', 'cyan', 'purple', 'blue', 'brown', 'green', 'red', 'black'] | int | None = None, *, nbt: NbtCompound | None = None) → None

Replace whatever the entity has on their head with the given armortype, default to leather_helmet with color if given. May set the helment as unbreakable and/or enchant the helmet with binding or vanishing respectively.

Note

nbt is only used for servers prior to 1.20.5 and will be removed in the future. All more modern servers use ComponentData, which can be set on the armortype.

# enchant helmet with protection 4 (in addition to curse_of_binding)
helmet = mc.materials.getById("leather_helmet").withData({"enchantments": {"protection": 4}})
mc.getPlayer().replaceHelmet(helmet)

This can be used to separate the players into any number of separate teams, like so:

from mcpq import Minecraft
from itertools import cycle
mc = Minecraft()
colors = ["red", "blue"]
teams = {color: [] for color in colors}
for player, color in zip(mc.getPlayerList(), cycle(colors)):
   teams[color].append(player)
   player.replaceHelmet(color=color)
   player.postToChat("You are in team:", color)

replaceItem(where: str, item: Block | str, amount: int = 1, *, nbt: NbtCompound | None = None) → None

Replace an inventory location where with a given item. The location can be something like armor.[head|chest|legs|feet|body], weapon.[mainhand|offhand], hotbar.[0-8], inventory.[0-26], enderchest.[0-26] or container.[0-52]. The item can be a string or a Block with component data:

sword = mc.materials.getById("diamond_sword").withData({"enchantments": {"sharpness": 5}})
mc.getPlayer().replaceItem("weapon.mainhand", sword)

Note

nbt is only used for servers prior to 1.20.5 and will be removed in the future. All more modern servers use ComponentData, which can be set on the item.

teleport(pos: Vec3 | None = None, facing: Vec3 | None = None, world: World | str | None = None) → None

Change the entity’s position, facing direction and/or world by teleporting it. Any of the arguments not set will not be changed. For example, it is possible to only change the world the entity is in without changing its (relative) coordinates or facing direction and vice versa.

# teleport entity to origin in same world
entity.teleport(pos=Vec3(0, 0, 0))
# teleport entity to end at same relative coordinates
entity.teleport(world=mc.end)
# make entity face straigth east without changing world or position
entity.teleport(facing=Vec3().east())
# teleport entity into origin at end facing east
entity.teleport(pos=Vec3(), facing=Vec3().east(), world=mc.end)

Parameters:

• pos (Vec3 | None, optional) – New position the entity should be teleported to, or None if position should not change, defaults to None

• facing (Vec3 | None, optional) – New direction (directional vector) the entity should face, or None if facing direction should not change, defaults to None

• world (World | str | None, optional) – New world the entity should be teleported to, or None if world should not change, defaults to None