user

User ¶

Python

User(
    entity_id: int,
    username: str,
    uuid: str,
    *,
    state: ConnectionState
)

Bases: Player

Enhanced Minecraft Player class with utility methods

Note

Use hasattr to check for attribute availability before accessing them, as some attributes may not always be present.

ATTRIBUTE	DESCRIPTION
`username`	The player's username. TYPE: `str`
`gamemode`	Current gamemode ID (0: survival, 1: creative, 2: adventure, 3: spectator). TYPE: `int`
`dimension`	Current dimension ID (-1: nether, 0: overworld, 1: end). TYPE: `int`
`health`	Player's current health points. TYPE: `float`
`food`	Player's current food (hunger) level. TYPE: `int`
`food_saturation`	Player's current food saturation level. TYPE: `float`
`level`	Player's experience level. TYPE: `int`
`total_experience`	Total accumulated experience points. TYPE: `int`
`experience_bar`	Progress on the experience bar (0.0 to 1.0). TYPE: `float`
`held_slot`	Index of the currently held inventory slot. TYPE: `int`
`spawn_point`	Player's current spawn point coordinates. TYPE: `Vector3D[float]`
`invulnerable`	Whether the player is invulnerable. TYPE: `bool`
`flying`	Whether the player is currently flying. TYPE: `bool`
`allow_flying`	Whether the player is allowed to fly. TYPE: `bool`
`creative_mode`	Whether the player is in creative mode. TYPE: `bool`
`flying_speed`	The player's flying speed multiplier. TYPE: `float`
`fov_modifier`	Field of view modifier affecting the player's view. TYPE: `float`

inventory `property` ¶

Python

inventory: Optional[gui.Window]

Get the player's inventory window

air `property` ¶

Python

air: int

Remaining air ticks.

RETURNS	DESCRIPTION
`int`	Number of air ticks remaining before drowning

custom_name `property` ¶

Python

custom_name: Optional[str]

Custom name text component or None.

RETURNS	DESCRIPTION
`Optional[str]`	Custom display name for the entity, or None if not set

is_custom_name_visible `property` ¶

Python

is_custom_name_visible: bool

Whether custom name is visible above entity.

RETURNS	DESCRIPTION
`bool`	True if custom name should be displayed above the entity

is_silent `property` ¶

Python

is_silent: bool

Whether entity makes sounds.

RETURNS	DESCRIPTION
`bool`	True if entity is silent and won't produce sounds

no_gravity `property` ¶

Python

no_gravity: bool

Whether entity is affected by gravity.

RETURNS	DESCRIPTION
`bool`	True if entity ignores gravity effects

max_health `property` ¶

Python

max_health: float

Maximum health attribute value.

RETURNS	DESCRIPTION
`float`	Maximum health points for this entity

movement_speed `property` ¶

Python

movement_speed: float

Movement speed attribute value.

RETURNS	DESCRIPTION
`float`	Movement speed multiplier for this entity

armor `property` ¶

Python

armor: float

Armor attribute value.

RETURNS	DESCRIPTION
`float`	Armor points providing damage reduction

attack_speed `property` ¶

Python

attack_speed: float

Attack speed attribute value.

RETURNS	DESCRIPTION
`float`	Attack speed multiplier for this entity

on_fire `property` ¶

Python

on_fire: bool

Whether entity is on fire (bit 0).

RETURNS	DESCRIPTION
`bool`	True if entity is currently on fire

crouched `property` ¶

Python

crouched: bool

Whether entity is crouching (bit 1).

RETURNS	DESCRIPTION
`bool`	True if entity is in crouching state

sprinting `property` ¶

Python

sprinting: bool

Whether entity is sprinting (bit 3).

RETURNS	DESCRIPTION
`bool`	True if entity is currently sprinting

invisible `property` ¶

Python

invisible: bool

Whether entity is invisible (bit 5).

RETURNS	DESCRIPTION
`bool`	True if entity has invisibility effect active

glowing `property` ¶

Python

glowing: bool

Whether entity is glowing (bit 6).

RETURNS	DESCRIPTION
`bool`	True if entity has glowing outline effect

flying_with_elytra `property` ¶

Python

flying_with_elytra: bool

Whether entity is flying with elytra (bit 7).

RETURNS	DESCRIPTION
`bool`	True if entity is gliding with elytra wings

equipment `property` ¶

Python

equipment: Dict[int, gui.Slot]

Get all equipment slots.

RETURNS	DESCRIPTION
`Dict[int, gui.Slot]`	Dictionary mapping slot IDs to their equipment slots.

has_equipment `property` ¶

Python

has_equipment: bool

Check if the entity has any equipment.

RETURNS	DESCRIPTION
`bool`	True if entity has equipment, False otherwise.

hand_states `property` ¶

Python

hand_states: int

Hand state bit mask.

RETURNS	DESCRIPTION
`int`	Bit mask containing hand usage states

potion_effect_color `property` ¶

Python

potion_effect_color: int

Potion effect particle color.

RETURNS	DESCRIPTION
`int`	RGB color value for potion effect particles

is_potion_effect_ambient `property` ¶

Python

is_potion_effect_ambient: bool

Whether potion effect is ambient.

RETURNS	DESCRIPTION
`bool`	True if potion effect particles are ambient (less visible)

arrows_in_entity `property` ¶

Python

arrows_in_entity: int

Number of arrows stuck in entity.

RETURNS	DESCRIPTION
`int`	Count of arrows visually stuck in the entity

is_hand_active `property` ¶

Python

is_hand_active: bool

Whether hand is active (using item).

RETURNS	DESCRIPTION
`bool`	True if entity is currently using an item with their hand

active_hand `property` ¶

Python

active_hand: int

Which hand is active (0=main, 1=off).

RETURNS	DESCRIPTION
`int`	Hand index: 0 for main hand, 1 for off-hand

info `property` ¶

Python

info: Optional[tab.PlayerInfo]

Get additional player information from the server's tab list.

RETURNS	DESCRIPTION
`Optional[tab.TabPlayer]`	The player's tab list entry if they are currently online and visible in the tab list, None otherwise.

additional_hearts `property` ¶

Python

additional_hearts: float

Additional hearts.

RETURNS	DESCRIPTION
`float`	The number of additional hearts the player has.

score `property` ¶

Python

score: int

Player score.

RETURNS	DESCRIPTION
`int`	The player's current score.

displayed_skin_parts `property` ¶

Python

displayed_skin_parts: int

Displayed skin parts bit mask.

RETURNS	DESCRIPTION
`int`	Bit mask representing which skin parts are displayed.

main_hand `property` ¶

Python

main_hand: int

Main hand preference.

RETURNS	DESCRIPTION
`int`	The main hand preference (0=left, 1=right).

left_shoulder_entity `property` ¶

Python

left_shoulder_entity: Optional[Any]

Left shoulder entity NBT data.

RETURNS	DESCRIPTION
`Optional[Any]`	NBT data of the entity on the left shoulder, or None if empty.

right_shoulder_entity `property` ¶

Python

right_shoulder_entity: Optional[Any]

Right shoulder entity NBT data.

RETURNS	DESCRIPTION
`Optional[Any]`	NBT data of the entity on the right shoulder, or None if empty.

cape_enabled `property` ¶

Python

cape_enabled: bool

Whether cape is enabled (bit 0).

RETURNS	DESCRIPTION
`bool`	True if the cape is enabled, False otherwise.

jacket_enabled `property` ¶

Python

jacket_enabled: bool

Whether jacket is enabled (bit 1).

RETURNS	DESCRIPTION
`bool`	True if the jacket is enabled, False otherwise.

left_sleeve_enabled `property` ¶

Python

left_sleeve_enabled: bool

Whether left sleeve is enabled (bit 2).

RETURNS	DESCRIPTION
`bool`	True if the left sleeve is enabled, False otherwise.

right_sleeve_enabled `property` ¶

Python

right_sleeve_enabled: bool

Whether right sleeve is enabled (bit 3).

RETURNS	DESCRIPTION
`bool`	True if the right sleeve is enabled, False otherwise.

left_pants_leg_enabled `property` ¶

Python

left_pants_leg_enabled: bool

Whether left pants leg is enabled (bit 4).

RETURNS	DESCRIPTION
`bool`	True if the left pants leg is enabled, False otherwise.

right_pants_leg_enabled `property` ¶

Python

right_pants_leg_enabled: bool

Whether right pants leg is enabled (bit 5).

RETURNS	DESCRIPTION
`bool`	True if the right pants leg is enabled, False otherwise.

hat_enabled `property` ¶

Python

hat_enabled: bool

Whether hat is enabled (bit 6).

RETURNS	DESCRIPTION
`bool`	True if the hat is enabled, False otherwise.

is_left_handed `property` ¶

Python

is_left_handed: bool

Whether player is left-handed (main hand = 0).

RETURNS	DESCRIPTION
`bool`	True if the player is left-handed, False otherwise.

is_right_handed `property` ¶

Python

is_right_handed: bool

Whether player is right-handed (main hand = 1).

RETURNS	DESCRIPTION
`bool`	True if the player is right-handed, False otherwise.

has_left_shoulder_parrot `property` ¶

Python

has_left_shoulder_parrot: bool

Whether player has a parrot on left shoulder.

RETURNS	DESCRIPTION
`bool`	True if there's an entity on the left shoulder, False otherwise.

has_right_shoulder_parrot `property` ¶

Python

has_right_shoulder_parrot: bool

Whether player has a parrot on right shoulder.

RETURNS	DESCRIPTION
`bool`	True if there's an entity on the right shoulder, False otherwise.

translate `async` ¶

Python

translate(
    position: Optional[Vector3D[float]] = None,
    rotation: Optional[Rotation] = None,
    on_ground: bool = True,
) -> None

Update the player's position and/or rotation.

PARAMETER	DESCRIPTION
`position`	The new position to set for the player. TYPE: `Optional[Vector3D[float]]` DEFAULT: `None`
`rotation`	The new rotation to set for the player. TYPE: `Optional[Rotation]` DEFAULT: `None`
`on_ground`	Whether the player is currently on the ground. When this changes from False to True, fall damage may be applied based on the distance fallen. TYPE: `bool` DEFAULT: `True`

sneak `async` ¶

Python

sneak(state: bool = True) -> None

Perform sneaking action.

PARAMETER	DESCRIPTION
`state`	True to start sneaking, False to stop sneaking. Default is True. TYPE: `bool` DEFAULT: `True`

sprint `async` ¶

Python

sprint(state: bool = True) -> None

Perform sprinting action.

PARAMETER	DESCRIPTION
`state`	True to start sprinting, False to stop sprinting. Default is True. TYPE: `bool` DEFAULT: `True`

action `async` ¶

Python

action(action_id: Literal[5], jump_boost: int) -> None

Python

action(action_id: Literal[2, 6, 7, 8]) -> None

Python

action(action_id: int, jump_boost: int = 0) -> None

Perform an entity action.

PARAMETER	DESCRIPTION
`action_id`	The ID of the action to perform. Valid values include: Text Only `2: Leave bed 5: Start jump with horse (should be handled separately with jump_boost) 6: Stop jump with horse 7: Open horse inventory 8: Start flying with elytra` TYPE: `int`
`jump_boost`	Jump strength (0-100) used only with action_id 5. TYPE: `int` DEFAULT: `0`

interact_with `async` ¶

Python

interact_with(
    entity: BaseEntity, hand: Literal[0, 1] = 0
) -> None

Perform a right-click interaction with an entity.

PARAMETER	DESCRIPTION
`entity`	The target entity. TYPE: `BaseEntity`
`hand`	Hand used to interact (0 = main hand, 1 = off-hand). TYPE: `Literal[0, 1]` DEFAULT: `0`

attack `async` ¶

Python

attack(entity: BaseEntity) -> None

Perform a left-click attack on an entity.

PARAMETER	DESCRIPTION
`entity`	The target entity. TYPE: `BaseEntity`

interact_at `async` ¶

Python

interact_at(
    entity: BaseEntity,
    hitbox: Vector3D[float],
    hand: Literal[0, 1] = 0,
) -> None

Perform a precise interaction at a specific location on an entity.

PARAMETER	DESCRIPTION
`entity`	The target entity. TYPE: `BaseEntity`
`hitbox`	The coordinates on the entity's hitbox. TYPE: `Vector3D[float]`
`hand`	Hand used to interact (0 = main hand, 1 = off-hand). TYPE: `Literal[0, 1]` DEFAULT: `0`

swing_arm `async` ¶

Python

swing_arm(hand: Literal[0, 1] = 0) -> None

Swing the player's arm.

PARAMETER	DESCRIPTION
`hand`	Hand to swing (0 = main hand, 1 = off-hand). TYPE: `Literal[0, 1]` DEFAULT: `0`

use_item `async` ¶

Python

use_item(hand: Literal[0, 1] = 0) -> None

Use the item in the specified hand.

This sends a Use Item packet to the server, which is triggered when right-clicking with an item. This can be used for: - Eating food - Drinking potions - Using tools (bow, fishing rod, etc.) - Placing blocks - Activating items

PARAMETER	DESCRIPTION
`hand`	Hand to use the item with (0 = main hand, 1 = off hand). TYPE: `Literal[0, 1]` DEFAULT: `0`

spectate_entity `async` ¶

Python

spectate_entity(target_uuid: str) -> None

Teleport to and spectate an entity.

This sends a Spectate packet to the server to teleport the player to the specified entity. The player must be in spectator mode for this to work. The entity can be in any dimension - if necessary, the player will be respawned in the correct world.

PARAMETER	DESCRIPTION
`target_uuid`	The UUID of the entity to teleport to and spectate. While commonly used for players, this can be any entity UUID. The packet will be ignored if the entity cannot be found, isn't loaded, or if the player attempts to teleport to themselves. TYPE: `str`

release_item_use `async` ¶

Python

release_item_use() -> None

Use the currently held item.

For example, shooting a bow, finishing eating, or using buckets.

start_digging `async` ¶

Python

start_digging(position: Vector3D[int], face: int) -> None

Start digging a block.

PARAMETER	DESCRIPTION
`position`	The (x, y, z) coordinates of the block to start digging. TYPE: `Vector3D[int]`
`face`	The face of the block being targeted (0=down, 1=up, 2=north, 3=south, 4=west, 5=east). TYPE: `int`

cancel_digging `async` ¶

Python

cancel_digging(position: Vector3D[int], face: int) -> None

Cancel digging a block.

PARAMETER	DESCRIPTION
`position`	The (x, y, z) coordinates of the block where digging is cancelled. TYPE: `Vector3D[int]`
`face`	The face of the block being targeted. TYPE: `int`

finish_digging `async` ¶

Python

finish_digging(position: Vector3D[int], face: int) -> None

Finish digging (break) a block.

PARAMETER	DESCRIPTION
`position`	The (x, y, z) coordinates of the block being broken. TYPE: `Vector3D[int]`
`face`	The face of the block being targeted. TYPE: `int`

drop_item_stack `async` ¶

Python

drop_item_stack() -> None

Drop the entire item stack.

This corresponds to pressing the drop key with a modifier to drop the full stack. Position is set to (0, 0, 0) and face is set to down (0) as per protocol.

drop_item `async` ¶

Python

drop_item() -> None

Drop a single item.

This corresponds to pressing the drop key without modifiers. Position is set to (0, 0, 0) and face is set to down (0) as per protocol.

swap_item_in_hand `async` ¶

Python

swap_item_in_hand() -> None

Swap item to the second hand.

Used to swap or assign an item to the offhand slot. Position is set to (0, 0, 0) and face is set to down (0) as per protocol.

toggle_flight `async` ¶

Python

toggle_flight() -> None

Toggle flight mode on/off.

This automatically handles the flight state based on current abilities. Only works if the player has flight permissions (creative mode, etc.).

change_held_slot `async` ¶

Python

change_held_slot(slot: int) -> None

Change the selected hotbar slot.

PARAMETER	DESCRIPTION
`slot`	The hotbar slot to select (0-8). TYPE: `int`

interact_with_block `async` ¶

Python

interact_with_block(
    position: Vector3D[int],
    face: int,
    hand: Literal[0, 1] = 0,
    cursor: Vector3D[float] = None,
) -> None

Interact with a block (right-click action).

This function handles all types of block interactions including placing blocks, opening containers, activating mechanisms, using doors, and other right-click actions.

PARAMETER	DESCRIPTION
`position`	The position of the block to interact with. TYPE: `Vector3D[int]`
`face`	The face of the block being targeted. TYPE: `int`
`hand`	Hand to use for the interaction: - 0: main hand - 1: off-hand TYPE: `Literal[0, 1]` DEFAULT: `0`
`cursor`	The cursor position on the targeted face, with coordinates from 0.0 to 1.0. If not provided, defaults to center of the face (0.5, 0.5, 0.5). TYPE: `Vector3D[float]` DEFAULT: `None`

Notes

Behavior depends on your held item and the block. Examples: - Placing blocks

Opening containers (chests, furnaces)
Activating buttons, levers, redstone
Using tools on blocks

Ensure you have permission to interact with blocks or open containers.

update_sign_text `async` ¶

Python

update_sign_text(
    position: Vector3D[float],
    line1: str = "",
    line2: str = "",
    line3: str = "",
    line4: str = "",
) -> None

Update the text on a sign.

PARAMETER	DESCRIPTION
`position`	The position of the sign. TYPE: `Vector3D[float]`
`line1`	First line of text. TYPE: `str` DEFAULT: `''`
`line2`	Second line of text. TYPE: `str` DEFAULT: `''`
`line3`	Third line of text. TYPE: `str` DEFAULT: `''`
`line4`	Fourth line of text. TYPE: `str` DEFAULT: `''`

move_vehicle `async` ¶

Python

move_vehicle(
    position: Vector3D[float], yaw: float, pitch: float
) -> None

Move a vehicle (boat, minecart, etc.) that the player is riding.

PARAMETER	DESCRIPTION
`position`	The absolute position of the vehicle. TYPE: `Vector3D[float]`
`yaw`	The absolute yaw rotation in degrees. TYPE: `float`
`pitch`	The absolute pitch rotation in degrees. TYPE: `float`

steer_boat `async` ¶

Python

steer_boat(right_paddle: bool, left_paddle: bool) -> None

Control boat paddle movement for visual effects.

PARAMETER	DESCRIPTION
`right_paddle`	Whether the right paddle is turning. TYPE: `bool`
`left_paddle`	Whether the left paddle is turning. TYPE: `bool`

steer_vehicle `async` ¶

Python

steer_vehicle(
    sideways: float, forward: float, flags: int
) -> None

Control vehicle movement and actions.

PARAMETER	DESCRIPTION
`sideways`	Sideways movement. Positive values steer to the left of the player. TYPE: `float`
`forward`	Forward movement. Positive values move forward. TYPE: `float`
`flags`	Bit mask for vehicle actions. 0x1: jump, 0x2: unmount. TYPE: `int`

update_metadata ¶

Python

update_metadata(metadata: Dict[int, Any]) -> None

Update entity metadata from metadata packet.

PARAMETER	DESCRIPTION
`metadata`	New metadata values indexed by metadata ID TYPE: `Dict[int, Any]`

update_properties ¶

Python

update_properties(
    properties: Dict[str, Dict[str, Any]],
) -> None

Update entity attributes from properties packet.

PARAMETER	DESCRIPTION
`properties`	Attribute properties containing base values and modifiers TYPE: `Dict[str, Dict[str, Any]]`

get_attribute ¶

Python

get_attribute(key: str, default: float = 0.0) -> float

Get final attribute value.

PARAMETER	DESCRIPTION
`key`	Attribute key name TYPE: `str`
`default`	Default value if attribute not found. TYPE: `float` DEFAULT: `0.0`

RETURNS	DESCRIPTION
`float`	Final attribute value after applying modifiers

get_metadata_value ¶

Python

get_metadata_value(index: int, default: Any = None) -> Any

Get metadata value by index with default fallback.

PARAMETER	DESCRIPTION
`index`	Metadata index to retrieve TYPE: `int`
`default`	Default value if metadata not found. TYPE: `Any` DEFAULT: `None`

RETURNS	DESCRIPTION
`Any`	Metadata value at the specified index, or default if not found

set_equipment ¶

Python

set_equipment(slot: gui.Slot) -> None

Set equipment in the specified slot.

RETURNS	DESCRIPTION
`None`

user

User ¶

inventory property ¶

air property ¶

custom_name property ¶

is_custom_name_visible property ¶

is_silent property ¶

no_gravity property ¶

max_health property ¶

movement_speed property ¶

armor property ¶

attack_speed property ¶

on_fire property ¶

crouched property ¶

sprinting property ¶

invisible property ¶

glowing property ¶

flying_with_elytra property ¶

equipment property ¶

has_equipment property ¶

hand_states property ¶

potion_effect_color property ¶

is_potion_effect_ambient property ¶

arrows_in_entity property ¶

is_hand_active property ¶

active_hand property ¶

info property ¶

additional_hearts property ¶

score property ¶

displayed_skin_parts property ¶

main_hand property ¶

left_shoulder_entity property ¶

right_shoulder_entity property ¶

cape_enabled property ¶

jacket_enabled property ¶

left_sleeve_enabled property ¶

right_sleeve_enabled property ¶

left_pants_leg_enabled property ¶

right_pants_leg_enabled property ¶

hat_enabled property ¶

is_left_handed property ¶

is_right_handed property ¶

has_left_shoulder_parrot property ¶

has_right_shoulder_parrot property ¶

translate async ¶

sneak async ¶

sprint async ¶

action async ¶

interact_with async ¶

attack async ¶

interact_at async ¶

swing_arm async ¶

use_item async ¶

spectate_entity async ¶

release_item_use async ¶

start_digging async ¶

cancel_digging async ¶

finish_digging async ¶

drop_item_stack async ¶

drop_item async ¶

swap_item_in_hand async ¶

toggle_flight async ¶

change_held_slot async ¶

interact_with_block async ¶

update_sign_text async ¶

move_vehicle async ¶

steer_boat async ¶

steer_vehicle async ¶

update_metadata ¶

update_properties ¶

get_attribute ¶

get_metadata_value ¶

set_equipment ¶

inventory `property` ¶

air `property` ¶

custom_name `property` ¶

is_custom_name_visible `property` ¶

is_silent `property` ¶

no_gravity `property` ¶

max_health `property` ¶

movement_speed `property` ¶

armor `property` ¶

attack_speed `property` ¶

on_fire `property` ¶

crouched `property` ¶

sprinting `property` ¶

invisible `property` ¶

glowing `property` ¶

flying_with_elytra `property` ¶

equipment `property` ¶

has_equipment `property` ¶

hand_states `property` ¶

potion_effect_color `property` ¶

is_potion_effect_ambient `property` ¶

arrows_in_entity `property` ¶

is_hand_active `property` ¶

active_hand `property` ¶

info `property` ¶

additional_hearts `property` ¶

score `property` ¶

displayed_skin_parts `property` ¶

main_hand `property` ¶

left_shoulder_entity `property` ¶

right_shoulder_entity `property` ¶

cape_enabled `property` ¶

jacket_enabled `property` ¶

left_sleeve_enabled `property` ¶

right_sleeve_enabled `property` ¶

left_pants_leg_enabled `property` ¶

right_pants_leg_enabled `property` ¶

hat_enabled `property` ¶

is_left_handed `property` ¶

is_right_handed `property` ¶

has_left_shoulder_parrot `property` ¶

has_right_shoulder_parrot `property` ¶

translate `async` ¶

sneak `async` ¶

sprint `async` ¶

action `async` ¶

interact_with `async` ¶

attack `async` ¶

interact_at `async` ¶

swing_arm `async` ¶

use_item `async` ¶

spectate_entity `async` ¶

release_item_use `async` ¶

start_digging `async` ¶

cancel_digging `async` ¶

finish_digging `async` ¶

drop_item_stack `async` ¶

drop_item `async` ¶

swap_item_in_hand `async` ¶

toggle_flight `async` ¶

change_held_slot `async` ¶

interact_with_block `async` ¶

update_sign_text `async` ¶

move_vehicle `async` ¶

steer_boat `async` ¶

steer_vehicle `async` ¶