PyJavaBridge

Player API — extends Entity

Player

Player extends Entity with player-specific functionality: health, hunger, experience, permissions, inventory, tab list, game mode, and more.

Constructor

Player(uuid: str | None = None, name: str | None = None)

Resolve a player by UUID or name. At least one must be provided. The player must be online.

p = Player(name="Steve")
p = Player(uuid="550e8400-e29b-41d4-a716-446655440000")

Attributes

name

The player's display name.

uuid

The player's UUID.

location

Current player location.

world

The world the player is in.

health

Current health (0–20 by default, 0 = dead).

food_level

Hunger level (0–20, 20 = full).

game_mode

Current game mode (e.g. GameMode.SURVIVAL, GameMode.CREATIVE).

inventory

The player's inventory (36 slots + armor + offhand).

held_item

The item currently in the player's main hand. Returns an Item proxy (may be air if the hand is empty).

selected_slot

The player's currently selected hotbar slot (0–8).

@event
async def player_item_held(e):
    slot = e.player.selected_slot
    await e.player.send_message(f"Switched to slot {{slot}}")

level

Player experience level (the green number).

exp

Experience progress within the current level (0.0 to 1.0).

is_op

Whether the player is a server operator.

is_flying

Whether the player is currently flying.

is_sneaking

Whether the player is sneaking (shift held).

is_sprinting

Whether the player is sprinting.

is_hand_raised

Whether the player is currently using an item (holding right-click).

hand_raised

Which hand is currently being used (EquipmentSlot.HAND or EquipmentSlot.OFF_HAND). None if the player is not using an item.

is_blocking

Whether the player is actively blocking (for example with a shield).

item_in_use

The item currently being used by the player.

item_in_use_ticks

How many ticks the current item_in_use has been used.

is_sleeping

Whether the player is currently sleeping in a bed.

sleep_ticks

How long the player has been sleeping, in ticks.

scoreboard

The player's current scoreboard.

permission_groups

The player's permission groups. LuckPerms-aware — returns LuckPerms groups if available, otherwise falls back to the basic permission system.

primary_group

The player's primary permission group (LuckPerms). None if LuckPerms is not installed.

tab_list_header

The player's tab list header text.

tab_list_footer

The player's tab list footer text.

tab_list_name

The player's display name in the tab list.

absorption

Absorption hearts amount (golden hearts).

saturation

Food saturation level. Higher saturation prevents hunger drain.

exhaustion

Food exhaustion level. When exhaustion exceeds 4.0, saturation decreases.

attack_cooldown

Attack cooldown progress (0.0 to 1.0). Read-only.

allow_flight

Whether the player is allowed to fly.

locale

The player's client locale string (e.g. "en_US").

ping

The player's ping in milliseconds.

client_brand

The player's client brand (e.g. "vanilla", "fabric").

max_health

The player's maximum health. Default is 20.0 (10 hearts).

bed_spawn_location

The player's bed/respawn location. None if not set.

compass_target

The location the player's compass points to.

Methods

send_message

await player.send_message(message)

Send a chat message to the player.

await player.send_message("§aYou found a secret!")

chat

await player.chat(message)

Make the player send a chat message (as if they typed it).

kick

await player.kick(reason="")

Kick the player from the server.

await player.kick("§cYou have been banned!")

teleport

await player.teleport(location)

Teleport the player. Inherited from Entity.

give_exp

await player.give_exp(amount)

Give raw experience points to the player.

set_exp

await player.set_exp(exp)

Set the experience progress bar within the current level.

set_level

await player.set_level(level)

Set the player's experience level.

set_health

await player.set_health(health)

Set the player's health.

set_food_level

await player.set_food_level(level)

Set the player's hunger level.

set_game_mode

await player.set_game_mode(mode)

Set the player's game mode.

await player.set_game_mode(GameMode.CREATIVE)

set_op

await player.set_op(value)

Set operator status.

set_flying

await player.set_flying(value)

Set flying state. The player must be allowed to fly (creative mode or flight allowed).

set_sneaking

await player.set_sneaking(value)

Force the sneaking state.

set_sprinting

await player.set_sprinting(value)

Force the sprinting state.

set_walk_speed

await player.set_walk_speed(speed)

Set walking speed.

set_fly_speed

await player.set_fly_speed(speed)

Set flying speed.

set_scoreboard

await player.set_scoreboard(scoreboard)

Set the player's active scoreboard.

hide_player

await player.hide_player(other)

Hide another player from this player.

show_player

await player.show_player(other)

Show a previously hidden player to this player.

can_see

visible = await player.can_see(other)

Check if this player can see another player.

open_book

await player.open_book(item)

Open a written book for the player.

send_block_change

await player.send_block_change(location, material)

Send a fake block change to the player (client-side only).

send_particle

await player.send_particle(particle, location, count=1, offset_x=0, offset_y=0, offset_z=0, extra=0)

Send a particle effect to the player.

Cooldowns

get_cooldown

ticks = await player.get_cooldown(material)

Get the remaining cooldown on a material (item type).

set_cooldown

await player.set_cooldown(material, ticks)

Set a cooldown on a material.

has_cooldown

result = await player.has_cooldown(material)

Check if a material has an active cooldown.

Statistics

get_statistic

value = await player.get_statistic(stat, material_or_entity=None)

Get a player statistic value.

playtime = await player.get_statistic("PLAY_ONE_MINUTE")
blocks_mined = await player.get_statistic("MINE_BLOCK", "DIAMOND_ORE")

set_statistic

await player.set_statistic(stat, value, material_or_entity=None)

Set a player statistic value.

Persistent Data Container (PDC)

Store custom data on the player that persists across server restarts.

get_persistent_data

data = await player.get_persistent_data()

Get all persistent data as a dictionary.

set_persistent_data

await player.set_persistent_data(key, value)

Set a persistent data key.

remove_persistent_data

await player.remove_persistent_data(key)

Remove a persistent data key.

has_persistent_data

result = await player.has_persistent_data(key)

Check if a persistent data key exists.

await player.set_persistent_data("quest_stage", "3")
if await player.has_persistent_data("quest_stage"):
    stage = (await player.get_persistent_data())["quest_stage"]

Effects

effects

effects = player.effects

Get a list of the player's active potion effects.

for effect in player.effects:
    print(f"{{effect.type}}: amplifier {{effect.amplifier}}, {{effect.duration}} ticks left")

add_effect

await player.add_effect(effect)

Apply a potion effect to the player.

await player.add_effect(Effect(EffectType.SPEED, duration=200, amplifier=1))

remove_effect

await player.remove_effect(effect_type)

Remove an active potion effect.

Sounds & UI

play_sound

await player.play_sound(sound, volume=1.0, pitch=1.0)

Play a sound to the player at their location.

await player.play_sound(Sound.ENTITY_EXPERIENCE_ORB_PICKUP)
await player.play_sound('block_note_block_bass', volume=0.5, pitch=2.0)

set_resource_pack

await player.set_resource_pack(url, hash="", prompt=None, required=False)

Send a resource pack to the player.

await player.set_resource_pack(
    "https://example.com/pack.zip",
    hash="a1b2c3d4e5f6...",
    prompt="Download our custom textures!",
    required=True
)

send_action_bar

await player.send_action_bar(message)

Display a message in the action bar (above the hotbar).

send_title

await player.send_title(title, subtitle="", fade_in=10, stay=70, fade_out=20)

Display a title and subtitle on the player's screen.

await player.send_title("§6Victory!", "§eYou won the game", fade_in=5, stay=40, fade_out=10)

Tab List

set_tab_list_header

await player.set_tab_list_header(header)

Set the header text shown above the player list in the tab screen.

set_tab_list_footer

await player.set_tab_list_footer(footer)

Set the footer text shown below the player list.

set_tab_list_header_footer

await player.set_tab_list_header_footer(header="", footer="")

Set both header and footer in a single call.

set_tab_list_name

await player.set_tab_list_name(name)

Set the player's display name in the tab list.

await player.set_tab_list_name("§c[Admin]§r Steve")

Permissions

has_permission

result = await player.has_permission(permission)

Check if the player has a permission node.

add_permission

result = await player.add_permission(permission, value=True)

Add or set a permission on the player. LuckPerms-aware.

remove_permission

result = await player.remove_permission(permission)

Remove a permission from the player. LuckPerms-aware.

has_group

result = await player.has_group(group)

Check if the player belongs to a permission group. LuckPerms only.

add_group

result = await player.add_group(group)

Add the player to a permission group. LuckPerms only.

remove_group

result = await player.remove_group(group)

Remove the player from a permission group. LuckPerms only.

Freeze & Vanish

Utility helpers for freezing and hiding players.

freeze

player.freeze()

Lock the player's position. The player is teleported back to their frozen location every tick until unfrozen. Synchronous.

unfreeze

player.unfreeze()

Release the player, allowing movement again. Synchronous.

is_frozen

Whether the player is currently frozen.

vanish

player.vanish()

Hide this player from all other players. Synchronous.

unvanish

player.unvanish()

Make the player visible again. Synchronous.

is_vanished

Whether the player is currently vanished.

Extension Shortcuts

These properties require a default extension instance to be assigned on the Player class. They provide convenient syntax for accessing extension data.

balance / deposit / withdraw

Player._default_bank = my_bank  # Set once at startup

bal = player.balance
player.deposit(100)
player.withdraw(50)

Requires Player._default_bank to be set to a Bank instance.

mana

Player._default_mana_store = my_mana  # Set once at startup

current = player.mana
player.mana = 50

Requires Player._default_mana_store to be set to a ManaStore instance.

xp / player_level

Player._default_level_system = my_levels  # Set once at startup

xp = player.xp
lvl = player.player_level

Requires Player._default_level_system to be set to a LevelSystem instance.