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
# get all entities in world, even non-spawnable ones (usually not needed)
entities = world.getEntities(only_spawnable=False)
entities = world.getEntities("pig")  # get all pigs in world
# get all falling_block in world, which are not spawnable (only_spawnable=False)
entities = world.getEntities("falling_block", only_spawnable=False)
# get all entities in world in 20 block radius around origin
entities = world.getEntitiesAround(Vec3(0, 0, 0), 20)
# spawn a creeper at origin and get it as entity
mycreeper = world.spawnEntity("creeper", Vec3(0, 0, 0))

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
# run command as entity and disable its ai, @s refers to itself
entity.runCommand("data merge entity @s {NoAI:1b}")
...

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 even checking with loaded before every operation will 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 caught 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 dead.

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.

# 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