Events

_EventHandler = Minecraft

Certain events that happen on the server can be captured and reacted to.

These events are:

  • PlayerJoinEvent triggers whenever a player connects to the server

  • PlayerLeaveEvent triggers whenever a player disconnects from the server

  • PlayerDeathEvent triggers whenever a player dies

  • ChatEvent triggers whenever someone writes in the chat. This does not trigger for /-commands, postToChat(), direct console messages or other server logs.

  • BlockHitEvent triggers whenever a player clicks on a block with either the left or right mouse button. It does not matter whether the click had any in game effect as long as the block was reachable for the player.

  • ProjectileHitEvent triggers whenever a player hits anything with a projectile. This does not trigger for projectiles that were not fired by the player, such as by dispensers or skeletons.

There are two mutually exclusive ways how to receive events:

  • Polling:

    The corresponding poll*EventName* function can be called to receive the events of that type since the last call to that poll function.

    for event in mc.pollProjectileHitEvents():
        if event.target_player:
            mc.postToChat(f"Player {event.player} hit player {event.target_player} with {event.projectile_type}")
    
  • Register Callback:

    The corresponding registerCallback*EventName* function can register another function as a callback. That function is then called for each event as it arrives with the event as the argument to the callback function. Multiple functions can be registered for the same event, in which case the functions are called in order they were registered in.

    def myfunc(event):
        if event.target_player:
            mc.postToChat(f"Player {event.player} hit player {event.target_player} with {event.projectile_type}")
    
    mc.registerCallbackProjectileHitEvent(myfunc)
    

These methods of receiving events are mutually exclusive for the same event type because registering a function will also consume the events. Calling the poll-function for an event type where a function is registered as callback will raise a RuntimeException.

Note

In both cases, events will only be captured after the first call of either poll*EventName* or registerCallback*EventName* and indefinitly afterwards until stopEventPollingAndClearCallbacks() is called.

class PlayerJoinEvent(player: 'Player')
player: Player

The Player who connected to the server

timestamp: float

The timestamp when the event was received. Will be used for sorting events by default

class PlayerLeaveEvent(player: 'Player')
player: Player

The Player who disconnected from the server

timestamp: float

The timestamp when the event was received. Will be used for sorting events by default

class PlayerDeathEvent(player: 'Player', deathMessage: 'str')
player: Player

The Player who died

deathMessage: str

The death message the player received

timestamp: float

The timestamp when the event was received. Will be used for sorting events by default

class ChatEvent(player: 'Player', message: 'str')
player: Player

The Player who sent the chat message

message: str

The message sent in chat

timestamp: float

The timestamp when the event was received. Will be used for sorting events by default

class BlockHitEvent(player: 'Player', right_hand: 'bool', held_item: 'str', pos: 'Vec3', face: 'DIRECTION')
player: Player

The Player who clicked on a block

right_hand: bool

Whether the player used their right hand instead of their left

held_item: str

The item held in that players hand that clicked the block

pos: Vec3

The Vec3 position of the block that was clicked

face: Literal['east', 'south', 'west', 'north', 'up', 'down']

The face/side of the block that was clicked

timestamp: float

The timestamp when the event was received. Will be used for sorting events by default

class ProjectileHitEvent(player: 'Player', target: 'Player | Entity | str', projectile_type: 'str', pos: 'Vec3', face: 'DIRECTION | None')
player: Player

The Player that shot/used the projectile

target: Player | Entity | str

The target hit, use target_block, target_entity and target_player for details what was hit

projectile_type: str

The type of projectile that was used

pos: Vec3

The Vec3 position where the projectile hit something. In case a block was hit, this is the block position that was hit

face: Literal['east', 'south', 'west', 'north', 'up', 'down'] | None

The face/side of the block hit, None if an entity or player was hit instead

property target_player: Player | None

The target Player if a player was hit, None otherwise

property target_entity: Entity | None

The target Entity if a non-player entity was hit, None otherwise

property target_block: str | None

The target block id if a block was hit, None otherwise

timestamp: float

The timestamp when the event was received. Will be used for sorting events by default