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 online "default" player
players = mc.getPlayers()  # 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. Use PlayerJoinEvent, PlayerLeaveEvent or update your online players regularly with mc.getPlayers() 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: str

The type 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(type: str, amount: int = 1, nbt: NBT | None = None) → None

Put items into the player’s inventory

Parameters:

  • type (str) – id of item or block to receive

  • amount (int, optional) – amount of items to receive, defaults to 1

  • nbt (NBT | None, optional) – additional nbt data of items, defaults to None

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.

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 /

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 | None = None, only_spawnable: bool = True) → list[Entity]

Get all other entities in a certain radius around self

Parameters:

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

  • type (str | 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 self less or equal to distance

Return type:

list[Entity]

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

Give self 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, defaults to 30

  • 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: 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: NBT | None = None) → None
replaceItem(where: str, item: str, amount: int = 1, nbt: NBT | None = None) → None
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