<no title> — MCPQ 1.0.0 documentation

MCPQ 1.0.0 documentation

class Entity

  The `Entity` class represents an entity on the server. It can be used to query information about the entity or manipulate them, such as getting or setting their position, orientation, world and more.

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

      # `world` can be `mc` for default world or a specific world, like `mc.nether`
      entities = world.getEntities()  # get all spawnable entities in world
      entities = world.getEntities(only_spawnable=False)  # get all entities in world, even non-spawnable ones (usually not needed)
      entities = world.getEntities("pig")  # get all pigs in world
      # get all falling_block in world, which are not spawnable, therefore requires the second argument to be False
      entities = world.getEntities("falling_block", only_spawnable=False)
      entities = world.getEntitiesAround(Vec3(0, 0, 0), 20)  # get all entities in world in 20 block radius around origin
      mycreeper = world.spawnEntity("creeper", Vec3(0, 0, 0))  # spawn a creeper at origin and get it as entity

  Once you have your entitiy you can use it in a multitude of ways:

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

      # other modifiers
      entity.kill()  # kill entity
      entity.giveEffect("glowing", 5)  # give entity glowing for 5 seconds
      entity.runCommand("data merge entity @s {NoAI:1b}")  # run command as entity and disable its ai, @s refers to itself
      ...

  Note

  Whether or not exceptions from operations on unloaded or dead entities are ignored is controlled by the global variable `mcpq.entity.ALLOW_UNLOADED_ENTITY_OPS`, which is True by default. Entities can get unloaded or die at any time and checking with `loaded` before every operation will still not guarantee that the entity exists by the time the operation is received by the server. To make life easier all EntityNotFound exceptions will be cought and ignored if `mcpq.entity.ALLOW_UNLOADED_ENTITY_OPS` is True. Note that this will make it look like the operation succeeded, even if the entity was (already) unloaded or offline.

  Note

  The number of times the entity data will be updated is controlled by the global variable `mcpq.entity.CACHE_ENTITY_TIME`, which is 0.2 by default. This means, using an entities’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 entity. 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.entity.CACHE_ENTITY_TIME`.

  property id: str

    The unique id of the entity on the server

  property type: str

    The entity type, such as `"sheep"` or `"creeper"`

  property loaded: bool

    Whether or not the entity exists, i.e., is loaded and not dead.

    Note

    This does not give any guarantees as the entity could be killed or unloaded after the check with the server was made.

  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

  remove() → None

    Remove the entity from world without dropping any drops

  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
  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 `/`

  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