<no title> — MCPQ 1.0.0 documentation

MCPQ 1.0.0 documentation

class Minecraft(host: str = 'localhost', port: int = 1789)

  `Minecraft` is the main object of interacting with Minecraft servers that have the mcpq-plugin. When constructing the class, a `host` and `port` of the server should be provided to which a connection will be built. They default to `"localhost"` and `1789` respectively. All other worlds, events, entities and more are then received via the methods of that instance.

      from mcpq import Minecraft
      mc = Minecraft()  # connect to localhost
      mc.postToChat("Hello Minecraft")  # send  message in chat

  Note

  Generally, it is sufficient to construct one `Minecraft` instance per server or active connection, as this connection is thread-safe and reusable. However, it is also possible to connect with multiple instances from the same or different hosts at the same time.

  Caution

  The connection used by the server is not encrypted or otherwise secured, meaning that any man-in-the-middle can read and modify any information sent between the program and the Minecraft server. For security reasons it is recommended to connect from the same host as the server is running on. By default, the plugin does only allow connections from `localhost` to prevent access from third parties.

  The `Minecraft` instance is also an event handler, the default `World` and can be used to query `Entity` and `Player` objects from the server. Checkout the corresponding classes for more information.

  property host: str

    The Minecraft server host address this instance is connected to.

  property port: int

    The Minecraft server port this instance is connected to.

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

    Print objects in chat separated by sep. All objects are converted to strings using `str()` first.

        mc.postToChat("Hello Minecraft")
        mc.postToChat("Players online:", mc.getPlayers())

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

        from mcpq.text import *  # RED, BLUE, BOLD, RESET ...
        mc.postToChat(RED + BOLD + "super " + RESET + BLUE + "cool!")
        # prints "super cool!", where "super" is red and bold, and "cool!" is blue

        # or alternatively, in order to not mix up your namespaces (especially `mcpq.colors`)
        from mcpq import text
        mc.postToChat(text.RED + text.BOLD + "super " + text.RESET + text.BLUE + "cool!")

    Parameters:

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

  runCommand(command: str) → None

    Run the command as if it was typed in chat as `/`-command. The command is run with the highest possible permission and no other modifiers.

        mc.runCommand("kill @e")
        mc.runCommand("gamerule doDaylightCycle false")

    Parameters:

      command (str) – the command without the slash `/`

  property worlds: tuple[World, ...]

    Give a tuple of all worlds loaded on the server. Does not automatically call `refreshWorlds()`.

    Returns:

      A tuple of all worlds loaded on the server

    Return type:

      tuple[World, …]

  property overworld: World

    Identical to `getWorldByKey()` with key `"minecraft:overworld"`.

    Returns:

      The overworld world `World` object

    Return type:

      World

  property nether: World

    Identical to `getWorldByKey()` with key `"minecraft:the_nether"`.

    Returns:

      The nether world `World` object

    Return type:

      World

  property end: World

    Identical to `getWorldByKey()` with key `"minecraft:the_end"`.

    Returns:

      The end world `World` object

    Return type:

      World

  getWorldByKey(key: str) → World

    The key of a world is the dimensions internal name/id. Typically a regular server has the following worlds/keys:

    - `"minecraft:overworld"`

    - `"minecraft:the_nether"`

    - `"minecraft:the_end"`

    The `"minecraft:"` prefix may be omitted, e.g., `"the_nether"`.

    If the given key does not exist an exception is raised.

    Parameters:

      key (str) – Internal name/id of the world, such as `"minecraft:the_nether"` or `"the_nether"`

    Returns:

      The corresponding `World` object

    Return type:

      World

  getWorldByName(name: str) → World

    The name of a world is the folder or namespace the world resides in. The setting for the world the server opens is found in `server.properties`. A typical, unmodified PaperMC server will save the worlds in the following folders:

    - `"world"`, for the overworld

    - `"world_the_nether"`, for the nether

    - `"world_the_end"`, for the end

    The name of the overworld (default `world`) is used as the prefix for the other folders.

    If the given name does not exist an exception is raised.

    Parameters:

      name (str) – Foldername the world is saved in, such as `world`

    Returns:

      The corresponding `World` object

    Return type:

      World

  refreshWorlds() → None

    Fetches the currently loaded worlds from server and updates the world objects. This should only be called if the loaded worlds on the server change, for example, with the Multiverse Core Plugin. By default, the worlds will be refreshed on first use only.

  getEntityById(entity_id: str) → Entity

    Get an entity with a certain entity_id, even if it is not loaded.

    Normally the entity_id is not known ahead of time. Prefer using `getEntities()`, `getEntitiesAround()` and `spawnEntity()`, which all return entities.

    Parameters:

      entity_id (str) – the unique entity identified

    Returns:

      the corresponding entity with that id, even if not loaded

    Return type:

      Entity

  getOfflinePlayer(name: str) → Player

    Get the `Player` with the given name no matter if the player is online or not. Does not raise any errors if the player is offline.

    Parameters:

      name (str) – player name/id

    Returns:

      the player with the given name

    Return type:

      Player

  getPlayers(names: list[str] | None = None) → list[Player]

    Get all currently online players on the entire server. If names is provided get all players with the given names only if they are online. Will raise an error if names is provided and at least one player with given name is offline.

    Parameters:

      names (list[str] | None, optional) – if given return only players with given names or error if one of the given players is offline, otherwise if names is None will return all currently online players, defaults to None

    Returns:

      the list of all currently online players, or if names is provided, only those online players

    Return type:

      list[Player]

  getPlayerNames() → list[str]

    Equivalent to `getPlayers()` but only return their names instead.

    Returns:

      list of all currently online `Player` names

    Return type:

      list[str]

  getPlayer(name: str | None = None) → Player

    Get any currently online player, which will become the default player thereafter, or get the online player with given name. Will raise an error if either no player is online, or if the player with given name is not online.

    If you want to check for any currently online players, use `getPlayers()` instead.

    Parameters:

      name (str | None, optional) – name of the online `Player` that should be returned, or None if any online player will do, defaults to None

    Returns:

      the player with name if name is given, else any online player that will become default player thereafter

    Return type:

      Player

  pollPlayerJoinEvents(maximum: int | None = 10) → list[PlayerJoinEvent]
    Parameters:

      maximum (int | None, optional) – the maxmimum number of events to return, if None return all events

    Returns:

      a list of events of that type since last poll, oldest first

    Return type:

      list[PlayerJoinEvent]

  pollPlayerLeaveEvents(maximum: int | None = 10) → list[PlayerLeaveEvent]
    Parameters:

      maximum (int | None, optional) – the maxmimum number of events to return, if None return all events

    Returns:

      a list of events of that type since last poll, oldest first

    Return type:

      list[PlayerLeaveEvent]

  pollPlayerDeathEvents(maximum: int | None = 10) → list[PlayerDeathEvent]
    Parameters:

      maximum (int | None, optional) – the maxmimum number of events to return, if None return all events

    Returns:

      a list of events of that type since last poll, oldest first

    Return type:

      list[PlayerDeathEvent]

  pollChatEvents(maximum: int | None = 10) → list[ChatEvent]
    Parameters:

      maximum (int | None, optional) – the maxmimum number of events to return, if None return all events

    Returns:

      a list of events of that type since last poll, oldest first

    Return type:

      list[ChatEvent]

  pollBlockHitEvents(maximum: int | None = 10) → list[BlockHitEvent]
    Parameters:

      maximum (int | None, optional) – the maxmimum number of events to return, if None return all events

    Returns:

      a list of events of that type since last poll, oldest first

    Return type:

      list[BlockHitEvent]

  pollProjectileHitEvents(maximum: int | None = 10) → list[ProjectileHitEvent]
    Parameters:

      maximum (int | None, optional) – the maxmimum number of events to return, if None return all events

    Returns:

      a list of events of that type since last poll, oldest first

    Return type:

      list[ProjectileHitEvent]

  registerCallbackPlayerJoinEvent(callback: Callable[[PlayerJoinEvent], None]) → None
    Parameters:

      callback (Callable[[PlayerJoinEvent], None]) – the function that should be called with the event as argument for each event of that type

  registerCallbackPlayerLeaveEvent(callback: Callable[[PlayerLeaveEvent], None]) → None
    Parameters:

      callback (Callable[[PlayerLeaveEvent], None]) – the function that should be called with the event as argument for each event of that type

  registerCallbackPlayerDeathEvents(callback: Callable[[PlayerDeathEvent], None]) → None
    Parameters:

      callback (Callable[[PlayerDeathEvent], None]) – the function that should be called with the event as argument for each event of that type

  registerCallbackChatEvent(callback: Callable[[ChatEvent], None]) → None
    Parameters:

      callback (Callable[[ChatEvent], None]) – the function that should be called with the event as argument for each event of that type

  registerCallbackBlockHitEvent(callback: Callable[[BlockHitEvent], None]) → None
    Parameters:

      callback (Callable[[BlockHitEvent], None]) – the function that should be called with the event as argument for each event of that type

  registerCallbackProjectileHitEvent(callback: Callable[[ProjectileHitEvent], None]) → None
    Parameters:

      callback (Callable[[ProjectileHitEvent], None]) – the function that should be called with the event as argument for each event of that type

  stopEventPollingAndClearCallbacks() → None

    Stops all active event capturing and clears event backlogs and registered callback functions. Calling a polling function or registering a callback afterwards, will start capturing events anew.

  property pvp: bool

    True if any world on the server has pvp enabled. Can be set to enable or disable pvp on all worlds on the server.

  getHighestPos(x: int, z: int) → Vec3

    The position of the highest non-air block with given x and z in the world.

    Returns:

      The position of the highest non-air block with given x and z

    Return type:

      Vec3

  getHeight(x: int, z: int) → int

    Equivalent to the y value of `getHighestPos()` with x and z.

  getBlock(pos: Vec3) → str

    The block type/id at position pos in world.

    Note

    The function does only query the block type/id, no additional block data is included.

    Parameters:

      pos (Vec3) – position to query block from

    Returns:

      block type/id at queried position

    Return type:

      str

  getBlockList(positions: list[Vec3]) → list[str]

    The list of all block types/ids at given positions in world in the same order.

    Note

    The function does only query the block types/ids, no additional block data is included.

    Parameters:

      positions (list[Vec3]) – list of positions to query

    Returns:

      list of block types/ids at given positions (same order)

    Return type:

      list[str]

  setBlock(blocktype: str, pos: Vec3) → None

    Change the block at position pos to blocktype in world. This will overwrite any block at that position.

    Parameters:

      - blocktype (str) – the valid block type/id to set the block to

      - pos (Vec3) – the position where the block should be set

  setBed(pos: Vec3, direction: Literal['east', 'south', 'west', 'north'] = 'east', color: Literal['white', 'orange', 'magenta', 'light_blue', 'yellow', 'lime', 'pink', 'gray', 'light_gray', 'cyan', 'purple', 'blue', 'brown', 'green', 'red', 'black'] = 'red') → None

    Place a bed at pos in direction with color, which is composed of two placed blocks with specific block data.

    Parameters:

      - pos (Vec3) – the position of foot part of bed

      - direction (CARDINAL, optional) – direction in which to place head part of bed, defaults to “east”

      - color (COLOR, optional) – color of bed, defaults to “red”

  setBlockList(blocktype: str, positions: list[Vec3]) → None

    Change all blocks at positions to blocktype in world. This will overwrite all blocks at the given positions. This is more efficient that using `setBlock()` mutliple times with the same blocktype.

    Parameters:

      - blocktype (str) – the valid block type/id to set the blocks to

      - positions (list[Vec3]) – the positions where the blocks should be set

  setBlockCube(blocktype: str, pos1: Vec3, pos2: Vec3) → None

    Change all blocks in a cube between the corners pos1 and pos2 in world to blocktype, where both positions are inclusive. meaning that both given positions/corners will be part of the cube. This will overwrite all blocks between the given positions. The positions span a cube if all their coordinates are different, a plane if one of their coordinates is the same or a line if two of their three coordinates are the same.

        # xlen, ylen, zlen are the length of the cube in the specified axis
        start = Vec3()  # this would be the lowest (most negative coordinates) corner of the cube we want to draw, here origin
        world.setBlockCube("diamond_block", start, start.addX(xlen).addY(ylen).addZ(zlen))

        # this is equivalent to (but more efficent and faster than)

        for x in range(xlen + 1):
            for y in range(ylen + 1):
                for z in range(zlen + 1):
                    world.setBlock("diamond_block", start.addX(x).addY(y).addZ(z))

    Parameters:

      - blocktype (str) – the valid block type/id to set the blocks to

      - pos1 (Vec3) – the position of one corner of the cube

      - pos2 (Vec3) – the position of the opposite corner of the cube

  copyBlockCube(pos1: Vec3, pos2: Vec3) → list[list[list[str]]]

    Get all block types in a cube between pos1 and pos2 inclusive. Should be used in conjunction with `pasteBlockCube()`.

    Note

    The function does only copy the block types/ids, no additional block data is included.

    Parameters:

      - pos1 (Vec3) – the position of one corner of the cube

      - pos2 (Vec3) – the position of the opposite corner of the cube

    Returns:

      the block types in the cube given as rows of x with columns of y with slices of depth z respectively

    Return type:

      list[list[list[str]]]

  pasteBlockCube(blocktypes: list[list[list[str]]], pos: Vec3, rotation: Literal['east', 'south', 'west', 'north', 'up', 'down'] = 'east', flip_x: bool = False, flip_y: bool = False, flip_z: bool = False) → None

    Paste the block types in the cube blocktypes into the world at position pos where pos is the negative most corner of the cube along all three axes. Additional options can be used to change the rotation of blocks in the copied cube, however, no matter in which way the cube is rotated and/or flipped, pos will also be the most negative corner. Should be used in conjunction with `copyBlockCube()`.

    Note

    The `copyBlockCube()` function does only copy the block types/ids, no additional block data is included.

        start = Vec3(0, 0, 0)
        end = start.addX(5).addY(5).addZ(5)
        # copy a 6x6x6 block cube from origin in world
        blocks = world.copyBlockCube(start, end)
        # replace that space with the same blocks but rotated by 90 degrees
        world.pasteBlockCube(blocks, start, "south")
        # copy same original block at different point above origin
        world.pasteBlockCube(blocks, start.up(200))

    Parameters:

      - blocktypes (list[list[list[str]]]) – the cube of block types/ids that should be pasted, given as rows of x with columns of y with slices of depth z respectively

      - pos (Vec3) – the most negative corner along all three axes of the cube where the cube should be pasted

      - rotation (DIRECTION, optional) – the direction of the x axis of the cube to be pasted (“east” means copied x axis aligns with real x axis, i.e., the original orientation), defaults to “east”

      - flip_x (bool, optional) – flip pasted blocks along x axis, defaults to False

      - flip_y (bool, optional) – flip pasted blocks along y axis, defaults to False

      - flip_z (bool, optional) – flip pasted blocks along z axis, defaults to False

  spawnEntity(type: str, pos: Vec3) → Entity

    Spawn and return a new entitiy of given type at position pos in world. The entity has default settings and behavior.

    Parameters:

      - type (str) – the valid entity type that should be spawned (must be spawnable without additional parameters)

      - pos (Vec3) – the position where to spawn the entitiy in the world

    Returns:

      the `Entity` entity spawned

    Return type:

      entity.Entity

  spawnItems(pos: Vec3, type: str, amount: int = 1) → None

    Spawn amount many collectable items of type at pos.

    Parameters:

      - pos (Vec3) – position where to spawn the items

      - type (str) – the item type, e.g., `"minecraft:arrow"`

      - amount (int, optional) – number of items to spawn, defaults to 1

  getEntities(type: str | None = None, only_spawnable: bool = True) → list[Entity]

    Get all (loaded) entities in the world. If a type is provided, only entities of that type are returned. By default only entities of types that could be spawned using `spawnEntity()` are returned. To get all entities (except players) set `only_spawnable=False`, which will also return non-spawnable entities such as e.g. `"falling_block"` or `"dropped_item"`.

    Parameters:

      - type (str | None, optional) – if provided returns only entities of that type, returns all types if None, defaults to None

      - only_spawnable (bool, optional) – if False, will also return non-spawnable entities, defaults to True

    Returns:

      list of (loaded and filtered) entities in the world

    Return type:

      list[entity.Entity]

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

    Equivalent to `getEntities()`, however, is filtered to only return entities within distance around pos. Is more efficient that filtering the list manually.

    Parameters:

      - pos (Vec3) – position around which the entities are returned

      - distance (float) – the maximum distance entities returned have around pos

      - type (str | None, optional) – if provided returns only entities of that type, returns all types if None, defaults to None

      - only_spawnable (bool, optional) – if False, will also return non-spawnable entities, defaults to True

    Returns:

      list of (loaded and filtered) entities in the world closer than distance to pos

    Return type:

      list[entity.Entity]

  removeEntities(type: str | None = None) → None

    Remove all entities (except players) from the world, they do not drop anything. If type is provided remove only entities of that type.

    Parameters:

      type (str | None, optional) – if provided removes only entities of that type, otherwise remove all entities, defaults to None