# event list & properties

these are the **only** valid event names. anything else in `@Katton.listen("...")` will error

### `player_join`

fires when a player enters `the arena` (or their own preset world), **NOT** the same as connecting to the server

```csharp
@Katton.listen("player_join")
function onJoin(event) {
    event.player.sendMessage("&aWelcome!")
}
```
properties: `event.player`

### `player_quit`

fires when a player leaves `the arena`

```csharp
@Katton.listen("player_quit")
function onQuit(event) {
    Katton.log.info(event.player.name + " left")
}
```
properties: `event.player`

### `player_death`

```csharp
@Katton.listen("player_death")
function onDeath(event) {
    for (player in Katton.players.all()) {
        player.sendMessage("&c" + event.player.name + " has died")
        event.clearDrops() // you can use this to clear the drops (if keep inv is off)
    }
}
```
properties: `event.player` & `event.clearDrops()`

### `player_respawn`

```csharp
@Katton.listen("player_respawn")
function onRespawn(event) {
    event.player.sendMessage("&around 2!!")
}
```
properties: `event.player`

### `player_interact`

fires when you interact with a block like a chest

```csharp
@Katton.listen("player_interact")
function onInteract(event) {
    if (event.action == "right_click_block") {
        event.player.sendMessage("&7you right clicked a " + event.block.type)
    }
}
```
properties: `event.player`, `event.item`, `event.action`, `event.block`

actions: `right_click_air`, `right_click_block`, `left_click_air`, `left_click_block`

### `player_hit`

fires when a player hits an entity (another player or mob)

```csharp
@Katton.listen("player_hit")
function onHit(event) {
    event.player.sendMessage("&7you hit " + event.victim.name)
}
```
properties: `event.player`, `event.attacker`, `event.victim`, `event.damage`, `event.finalDamage`, `event.cause`, `event.projectile`

### `player_damage`

fires when a player takes damage from any source

```csharp
@Katton.listen("player_damage")
function onDamage(event) {
    event.player.sendMessage("&7you took " + event.finalDamage + " damage from " + event.source)
}
```
properties: `event.player`, `event.damage`, `event.finalDamage`, `event.cause`, `event.source`, `event.projectile`

### `player_chat`

fires when someone sends a chat message

```csharp
@Katton.listen("player_chat")
function onInteract(event) {
    val player = event.player // person who typed the message
    val msg = event.message // message wrote

    if (msg == "hi" || msg == "Hi") {
        for (p in Katton.players.all()) {
            p.sendMessage("&ehi " + player.name + "!")
        }
    }
}
```
properties: `event.player`, `event.message`

### `player_input`

fires when you press a key like: `forward`, `backward`, `left`, `right`, `jump`, `sneak`, `sprint`

```csharp
@Katton.listen("player_input")
function onEvent(event) {
    val player = event.player

    if (event.jump) {
        player.sendMessage("you jumped!")
    }

    if (event.shift) {
        player.sendMessage("you shifted!")
    }

    if (event.forward) {
        player.sendMessage("you went forwards!")
    }
}
```
properties: `event.forward`, `event.backward`, `event.left`, `event.right`, `event.jump`, `event.sneak`, `event.sprint`

### `player_leftclick` / `player_rightclick`

if you want to detect when a player left clicks or right clicks:

```csharp
@Katton.listen("player_rightclick")
function onRightClick(event) {
    val item = event.item
    if (item != null && item.getTag("ability") == "leap_wand") {
        event.player.launchForward(horizontal = 1.8, vertical = 0.65)
        event.cancel()
    }
}
```
properties: `event.player`, `event.item`

### `block_break` / `block_place`

```csharp
@Katton.listen("block_break")
function onBreak(event) {
    if (event.block.type == "tnt") {
        event.cancel() // no breaking TNT
    }
}

@Katton.listen("block_place")
function onPlace(event) {
    Katton.log.info(event.player.name + " placed " + event.block.type) // only shows to you
}
```
properties: `event.player`, `event.block`

### `entity_death`

fires for any entity dying, including players

```csharp
@Katton.listen("entity_death")
function onEntityDeath(event) {
    var entity = event.entity
    event.killer.sendMessage(entity.type)
    if (entity.type == "zombie") {
        event.killer.sendMessage("zombie died")
    }
}
```
properties: `event.entity`, `event.killer`/`event.player`

### `item_drop` / `item_pickup`

```csharp
@Katton.listen("item_drop")
function onDrop(event) {
    event.player.sendMessage("&7dropped: " + event.item.type)
}

@Katton.listen("item_pickup")
function onPickup(event) {
    event.player.sendMessage("&apicked up something!")
}
```
properties: `event.player`, `event.item` (both events)

### `player_interact_entity`

fires when a player right clicks an entity

```csharp
@Katton.listen("player_interact_entity")
function onEntityInteract(event) {
    if (event.entity.type == "villager") {
        event.player.sendMessage("&ethe villager hates u")
    }
}
```
properties: `event.player`, `event.entity`

### `projectile_hit`

fires when a projectile hits either a block or a entity

```csharp
@Katton.listen("projectile_hit")
function onProjectileHit(event) {
    val player = event.player // returns the player who owns the projectile
    val projectile = event.projectile.type // returns the type of projectile
    val entity = event.entity // returns the entity
    val block = event.block // returns the block

    var entityType = "null"
    if (entity != null) {
        entityType = entity.type
    }
    
    var blockType = "null"
    if (block != null) {
        blockType = block.type
    }

    player.sendMessage("player: "+player.name + " | projectile: " +projectile + " | entity: " + entityType + " | block: " + blockType)
}
```
properties: `event.player`, `event.projectile`, `event.entity`, `event.block`

### `player_shoot_bow`

fires when a player shoots a bow

```csharp
@Katton.listen("player_shoot_bow")
function onBowShoot(event) {
    val player = event.player // returns the player who shot the bow
    val item = event.item // returns the true item that was used
    val projectile = event.projectile.type // returns the projectile entity

    player.sendMessage("player: "+player.name + " | item: " +item.name + " | projectile: " + projectile)
}
```
properties: `event.player`, `event.item`, `event.projectile`

`event.item` **is** a full `item` value where you can call `.getTag(...)`, `.setName(...)`, etc. on it. see [item](../api/item.md).

`event.block` **is** a full `block` value. see [block](../api/block.md).

`event.entity`/`event.projectile` **is** a full `entity` value. see [entity](../api/entity.md).
