Events — MCPQ 1.0.0 documentation

MCPQ 1.0.0 documentation

# 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