PyJavaBridge

Base entity proxy

Entity

Entity is the base class for all entities in the game — mobs, animals, projectiles, dropped items, etc. Player extends this class.

Constructor

Entity(uuid: str | None = None)

Resolve an existing entity by its UUID.

entity = Entity("550e8400-e29b-41d4-a716-446655440000")

Class Methods

spawn

entity = await Entity.spawn(entity_type, location, **kwargs)

Spawn a new entity at a location.

zombie = await Entity.spawn(EntityType.ZOMBIE, player.location)
zombie = await Entity.spawn("ZOMBIE", Location(0, 64, 0, "world"))

Attributes

uuid

The entity's universally unique identifier.

type

The entity type (e.g. EntityType.ZOMBIE, EntityType.ARROW).

location

The entity's current location. Re-fetched each access.

world

The world the entity is in.

inventory

The entity's inventory / equipment. For mobs, this is their equipment slots.

held_item

The item in the entity's main hand equipment slot.

yaw

The entity's horizontal rotation in degrees (from its location).

pitch

The entity's vertical rotation in degrees (from its location).

look_direction

Normalized direction vector computed from the entity's yaw and pitch. Useful for spawning projectiles or offsetting positions in front of the entity.

# Spawn a fireball 2 blocks ahead of the player
direction = player.look_direction * 2
fireball = await Entity.spawn("FIREBALL", player.location + direction)
await fireball.set_velocity(direction)

velocity

The entity's current velocity vector.

equipment

The entity's equipment (armor slots and held items). For mobs this is their equipment; for players use inventory instead.

is_dead

Whether the entity is dead.

is_alive

Whether the entity is alive.

is_valid

Whether the entity handle is still valid. Becomes False when the entity is removed from the server. Always check this before interacting with an entity you've stored across ticks.

fire_ticks

Remaining fire ticks. 0 means not on fire. Each tick at 20 TPS, so 100 = 5 seconds of fire.

passengers

Entities riding on top of this entity.

custom_name

The entity's custom name, or None if not set.

custom_name_visible

Whether the custom name tag is visible through walls and at distance.

is_projectile

Whether this entity is a projectile (arrow, snowball, trident, etc.).

shooter

For projectiles, the entity or block that launched it. None for non-projectiles.

is_tamed

Whether this entity is a tameable animal that has been tamed (wolf, cat, horse, etc.).

owner

The player who caused/owns this entity. Works for:

Returns None if the owner is offline or unknown.

owner_uuid

UUID of the owning player, even if they're offline.

owner_name

Name of the owning player, if known.

source

The entity that created this entity. For example, the player who lit a TNT block, or the witch that threw a potion.

@event
async def entity_damage_by_entity(e):
    # Track who's responsible for projectile kills
    damager = e.damager
    if damager.is_projectile and damager.owner:
        owner = damager.owner
        await owner.send_message(f"You hit {{e.entity.type}}!")

    # Check if a tamed wolf attacked something
    if damager.is_tamed:
        await damager.owner.send_message(f"Your {{damager.type}} attacked {{e.entity.type}}")

gravity

Whether the entity is affected by gravity.

glowing

Whether the entity has the glowing outline effect.

invisible

Whether the entity is invisible.

invulnerable

Whether the entity is invulnerable to damage.

silent

Whether the entity makes sounds.

persistent

Whether the entity persists through chunk unloads. Prevents despawning.

collidable

Whether other entities can collide with this entity.

portal_cooldown

The entity's portal cooldown in ticks.

max_fire_ticks

The maximum fire ticks the entity can have (read-only).

freeze_ticks

The entity's powdered-snow freeze ticks.

height

The entity's bounding box height.

width

The entity's bounding box width.

bounding_box

The entity's axis-aligned bounding box as a dictionary.

metadata

Transient Python-side key/value storage attached to this entity. Persists across event handlers within the same session but is not saved to disk.

entity.metadata["spawned_by"] = player.name

bool

Entity implements bool returning is_valid, so you can use:

if entity:  # equivalent to entity.is_valid
    await entity.remove()

Methods

teleport

await entity.teleport(location)

Teleport the entity to a new location.

await zombie.teleport(Location(0, 100, 0, "world"))

remove

await entity.remove()

Remove the entity from the world permanently.

set_velocity

await entity.set_velocity(vector)

Set the entity's velocity. Useful for launching entities, knockback effects, etc.

# Launch entity upward
await entity.set_velocity(Vector(0, 1.5, 0))

set_fire_ticks

await entity.set_fire_ticks(ticks)

Set the entity on fire for a duration.

await entity.set_fire_ticks(100)  # 5 seconds of fire
await entity.set_fire_ticks(0)    # Extinguish

add_passenger

success = await entity.add_passenger(entity)

Make another entity ride on top of this one.

remove_passenger

success = await entity.remove_passenger(entity)

Remove a riding entity.

set_custom_name

await entity.set_custom_name(name)

Set the entity's custom name tag. You can also use property syntax: entity.custom_name = "§cBoss Zombie".

await zombie.set_custom_name("§cBoss Zombie")
# or
zombie.custom_name = "§cBoss Zombie"
del zombie.custom_name  # clears name

set_custom_name_visible

await entity.set_custom_name_visible(value)

Show or hide the custom name tag. When True, the name is visible through walls and at a distance. You can also use property syntax: entity.custom_name_visible = True.

damage

await entity.damage(amount)

Deal damage to the entity.

await zombie.damage(10.0)  # 5 hearts of damage

Mob AI

These methods only work on Mob entities (zombies, skeletons, etc). They will fail silently on non-mob entities like dropped items or projectiles.

target

target = entity.target

Get the mob's current attack target.

set_target

await entity.set_target(target)

Set the mob's attack target. Pass None to clear. You can also use property syntax.

await zombie.set_target(player)
# or
zombie.target = player
del zombie.target  # clear target

is_aware

aware = entity.is_aware

Check if the mob has AI awareness (responds to environment, pathfinds, etc).

set_aware

await entity.set_aware(aware)

Enable or disable AI awareness. When disabled, the mob won't move or react. You can also use property syntax: entity.is_aware = False.

await zombie.set_aware(False)  # freeze the mob

pathfind_to

result = entity.pathfind_to(location, speed=1.0)

Make the mob pathfind to a location using Paper's Pathfinder API.

found = zombie.pathfind_to(player.location, speed=1.5)

stop_pathfinding

await entity.stop_pathfinding()

Stop the mob's current pathfinding. The mob will stand still.

has_line_of_sight

can_see = entity.has_line_of_sight(other)

Check if this mob has line of sight to another entity.

if zombie.has_line_of_sight(player):
    await zombie.set_target(player)

look_at

await entity.look_at(location)

Make the mob face a location.

await zombie.look_at(player.location)

AI Goals

These methods interact with Paper's MobGoals API to inspect and modify mob AI goals.

goal_types

goals = entity.goal_types

Get a list of all active AI goal type keys on the mob.

remove_goal

removed = entity.remove_goal(goal_key)

Remove a specific AI goal by its key. Synchronous.

remove_all_goals

await entity.remove_all_goals()

Remove all AI goals from the mob.

# Create a "dummy" mob that won't do anything
await zombie.remove_all_goals()
await zombie.set_aware(False)

Tags

Entities support Python-side tags — string labels shared across all instances that reference the same entity UUID. Tags are stored in memory (not persisted to disk) and are useful for marking entities across different event handlers.

add_tag

entity.add_tag(tag)

Add a tag to this entity. Synchronous.

zombie.add_tag("boss")

remove_tag

entity.remove_tag(tag)

Remove a tag. Synchronous.

tags

all_tags = entity.tags

Get all tags on this entity.

is_tagged

result = entity.is_tagged(tag)

Check if the entity has a specific tag. Synchronous.

@event
async def entity_damage(e):
    if e.entity.is_tagged("boss"):
        await e.entity.set_custom_name(f"§c Boss HP: {{e.entity.health}}")

Entity Subtypes

See Entity subtypes