<no title> — MCPQ 1.0.0 documentation

MCPQ 1.0.0 documentation

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 checking with `online` before every operation will still 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 cought 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[&quot;adventure&quot;, &quot;creative&quot;, &quot;spectator&quot;, &quot;survival&quot;]) – 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.

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

    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