PyJavaBridge

Event proxy and event type mapping

Event

The Event class is the proxy object passed to your @event handlers. It exposes fields relevant to the specific Bukkit event that fired. Fields that don't apply to the current event type are None.

Attributes

player

The player involved in the event. Available for all player-related events (player_join, player_chat, player_interact, etc.).

@event
async def player_join(e):
    await e.player.send_message(f"Welcome, {e.player.name}!")

entity

The entity involved in the event. Available for entity events (entity_damage, entity_death, etc.).

block

The block involved in the event. Available for block events (block_break, block_place, etc.).

world

The world where the event occurred.

location

The location relevant to the event.

item

The item involved in the event. Available for interact events, inventory events, etc.

inventory

The inventory involved in the event. Available for inventory_click, inventory_close, etc.

chunk

The chunk involved in the event.

slot

The inventory slot index for inventory_click events.

damager

The source of damage for entity_damage events. Can be an entity (attacker, projectile) or a block (cactus, lava).

damage

The raw damage amount for entity_damage events (before armor/enchantment modifiers).

final_damage

The final damage after all modifiers for entity_damage events.

damage_cause

The DamageCause for damage events (e.g. "ENTITY_ATTACK", "FALL", "FIRE").

Methods

cancel

await event.cancel()

Cancel the event, preventing its default action. Only works on cancellable events.

@event
async def block_break(e):
    if e.block.type.name == "BEDROCK":
        await e.cancel()
        await e.player.send_message("You can't break bedrock!")

Damage Override

For entity_damage events, returning a number from the handler overrides the final damage:

@event
async def entity_damage(e):
    if e.damage_cause == "FALL":
        return 0  # Cancel all fall damage
    if e.player:
        return e.damage * 0.5  # Half damage for players

Chat Override

For player_chat events, returning a string cancels the original message and broadcasts your string instead:

@event
async def player_chat(e):
    return f"[VIP] {e.player.name}: {e.message}"

Returning None (or not returning) leaves the chat message unchanged.

Respawn Location Override

For player_respawn events, returning a Location overrides where the player respawns:

@event
async def player_respawn(e):
    return Location(0, 100, 0, e.player.world)  # Custom spawn point

Event Type Mapping

Events are resolved from handler function names: snake_case → PascalCase + Event.

Function name Bukkit event
player_join PlayerJoinEvent
player_quit PlayerQuitEvent
player_chat AsyncPlayerChatEvent
player_move PlayerMoveEvent
player_interact PlayerInteractEvent
block_break BlockBreakEvent
block_place BlockPlaceEvent
entity_damage EntityDamageEvent / EntityDamageByEntityEvent
entity_death EntityDeathEvent
inventory_click InventoryClickEvent
inventory_close InventoryCloseEvent
world_load WorldLoadEvent
weather_change WeatherChangeEvent

Special cases

Supported packages

The bridge discovers events from all standard Bukkit/Paper event packages: