Events

class EventHandler

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 poll() function on the corresponding SingleEventHandler can be called to receive the events of that type since the last call to that poll() or get() function.

  for event in mc.events.projectile_hit.poll():
      mc.postToChat(f"Player {event.player} hit {event.target}")
  

  Alternatively, the get() or get_nowait() functions on the corresponding SingleEventHandler can be called to get (and potentially wait) for the next event of that type.

  event = mc.events.projectile_hit.get(timeout=5):
  if event is None:
      mc.postToChat("Did NOT get an event within 5 seconds")
  else:
      mc.postToChat(f"Got event {event} within 5 seconds")
  

• Register Callback:

  The register() function on the corresponding SingleEventHandler 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):
      mc.postToChat(f"Player {event.player} hit {event.target}")
  
  mc.events.projectile_hit.register(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 to either poll(), get(), get_nowait() or register() and indefinitely afterwards until stop() is called.

property player_join: SingleEventHandler[PlayerJoinEvent]

Receive the SingleEventHandler for the PlayerJoinEvent event.

property player_leave: SingleEventHandler[PlayerLeaveEvent]

Receive the SingleEventHandler for the PlayerLeaveEvent event.

property player_death: SingleEventHandler[PlayerDeathEvent]

Receive the SingleEventHandler for the PlayerDeathEvent event.

property chat: SingleEventHandler[ChatEvent]

Receive the SingleEventHandler for the ChatEvent event.

property block_hit: SingleEventHandler[BlockHitEvent]

Receive the SingleEventHandler for the BlockHitEvent event.

property projectile_hit: SingleEventHandler[ProjectileHitEvent]

Receive the SingleEventHandler for the ProjectileHitEvent event.

stopEventPollingAndClearCallbacks() → None

Stops all active event capturing and clears event backlogs and registered callback functions. Calling a polling function or registering a callback afterwards, will start capturing events anew.

---

class SingleEventHandler

The specific event handler responsible for receiving a certain type of event in different ways.

get(timeout: int | None = None) → EventType | None

Get and potentially wait for at most timeout seconds for the next event that was not yet received with either poll() or get(). If timeout is None, wait potentially indefinitely for the next event or until stop() is called or the connection closes.

Note

This function checks periodically (every few seconds) if stop() was called and whether the connection was closed while waiting. If either of these checks is true, then eventually this function will stop waiting and return None.

Parameters:

timeout (int | None, optional) – time in seconds to wait for at most for next event, if None may wait indefinitely, defaults to None

Raises:

RuntimeError – if called while a callback is registered

Returns:

the next event of that type since last poll, or None if not received within timeout seconds

Return type:

EventType | None

get_nowait() → EventType | None

Identical to get() with timeout of 0. This function does not block and returns immediately.

Raises:

RuntimeError – if called while a callback is registered

Returns:

the next event of that type if one has already been received since last poll, else None

Return type:

EventType | None

poll(maximum: int | None = 10) → list[EventType]

Poll up to maximum many events received since the last time poll() or get() was called, or all events received since then if maxmimum is None. This function does not block and returns immediately with the events not yet received with either poll() or get().

Parameters:

maximum (int | None, optional) – the maxmimum number of events to return, if None return all received events

Raises:

RuntimeError – if called while a callback is registered

Returns:

a list of events of that type since last poll, oldest first

Return type:

list[EventType]

register(callback: Callable[[EventType], None]) → None

Register a callback function to run whenever an event is received 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.

Note

Registered callback functions consume the received events, therefore polling and registering at the same time is not possible and will result in a RuntimeException if using poll() or get() with registered callback.

Note

No other events can be received while a callback function is being run, so make your callback functions non-blocking and fast if possible.

Parameters:

callback (Callable[[EventType], None]) – the function called with the event as argument for each event of that type

stop() → None

Stop the receiving of this event type and clear all events and callbacks. Calling either poll(), get() or register() afterwards will start receiving events again.

---

class PlayerJoinEvent(player: 'Player')

player: Player

The Player who connected to the server

timestamp: float

The timestamp when the event was received. Used for sorting events of same type

class PlayerLeaveEvent(player: 'Player')

player: Player

The Player who disconnected from the server

timestamp: float

The timestamp when the event was received. Used for sorting events of same type

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. Used for sorting events of same type

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. Used for sorting events of same type

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. Used for sorting events of same type

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. Used for sorting events of same type