# player

you get a `player` value from `Katton.players.*` selectors, the `sender` parameter in a command handler, or `event.player` in an event handler

---

## properties

```csharp
player.name //player name
player.uuid //player uuid as a string
player.type //entity type name
player.world //current world name
player.location //player location object
player.health //player health
player.game_mode //player game mode
player.velocity //player velocity object
player.vehicle //a `entity` value for whatever they are riding
player.is_sneaking //true / false
player.is_sprinting //true / false
player.facing //tells you which direction the player is looking, as a number: 1 (down), 2 (up), 3 (north), 4 (south), 5 (west), 6 (east)
player.tool //an `item` value for whatever's in their main hand (empty hand still gives you an item value, just air)
player.offhand_tool //same, but their off hand
player.is_blocking //whether the player is blocking
```

## methods

```csharp
player.setArmor(slot, item)
player.getArmor(slot)
player.countItem(material)
player.setGamemode(gamemode)
player.setHealth(health)
player.sendMessage(text)
player.sendTitle(title, subtitle = "")
player.setCompassTarget(location)
player.sendActionBar(text)
player.teleport(location)
player.give(item)
player.setTool(item)
player.setOffhandTool(item)
player.playSound(sound, volume = 1.0, pitch = 1.0)
player.launchForward(horizontal = 1.8, vertical = 0.65)
player.setVelocity(x, y, z)
player.giveEffect(Katton.potionEffect(potion_effect, time, strength))
player.removeEffect(potion_effect)
player.removeAllEffects()
player.clearInventory()
player.setGlowing(glowing = true)
player.setMovementSpeed(speed)
player.resetMovementSpeed()
player.setJumpStrength(strength)
player.resetJumpStrength()
player.setScale(scale)
player.resetScale()
player.setInvulnerable(invulnerable = true)
player.mount(entity)
player.dismount()
player.shootProjectile(projectile = "arrow", speed = 2.0)
```

---

### `setArmor`

sets an item to the player's armor slot

```csharp
player.setArmor(slot, item)
```

| parameter | default | description |
| --- | --- | --- |
| `slot` | *required* | a slot string |
| `item` | *required* | a `Katton.item(...)` value |

> [!note]
> the avialable armor slots are: head/helmet, chest/chestplate, legs/leggings, feet/boots

#### example

```csharp
val helmet = Katton.item("diamond_helmet")
player.setArmor("head", helmet)
```

---

### `getArmor`

gets the item in the specified armor slot

```csharp
player.getArmor(slot)
```

| parameter | default | description |
| --- | --- | --- |
| `slot` | *required* | a slot string ('head', 'chestplate', 'leggings', or 'boots') |

#### example

```csharp
val helmet = player.getArmor("head")
```

---

### `countItem`

number of that material in inventory (incl. armor/offhand)

```csharp
player.countItem(material)
```

| parameter | default | description |
| --- | --- | --- |
| `material` | *required* | material name string |

#### example

```csharp
val count = player.countItem("diamond")
```

---

### `setGamemode`

changes a player gamemode

```csharp
player.setGamemode(gamemode)
```

| parameter | default | description |
| --- | --- | --- |
| `gamemode` | *required* | changes a player's gamemode to: survival/adventure, creative, spectator |

> [!note]
> survival/adventure sets them to survival if placing/breaking/building is on, if not it sets them to adventure

#### example

```csharp
player.setGamemode("creative") // caps doesn't matter
```

---

### `setHealth`

sets the player's current health

```csharp
player.setHealth(health)
```

| parameter | default | description |
| --- | --- | --- |
| `health` | default=20.0 | target health value |

#### example

```csharp
player.setHealth(5)
```

---

### `sendMessage`

sends a chat message to the player

```csharp
player.sendMessage(text)
```

| parameter | default | description |
| --- | --- | --- |
| `text` | *required* | chat message text, supports `&` color codes |

#### example

```csharp
player.sendMessage("&awelcome!")
```

---

### `sendTitle`

displays a optional title and optional subtitle on the player's screen

```csharp
player.sendTitle(title, subtitle = "")
```

| parameter | default | description |
| --- | --- | --- |
| `title` | default="" | top line title text, supports `&` color codes |
| `subtitle` | default="" | bottom line subtitle text, supports `&` color codes |

#### example

```csharp
player.sendTitle("&cRED", "") // shows RED in red on the top line and nothing on the bottom
player.sendTitle("&eGet Ready!", "&7Round starting...") // shows Get Ready! in yellow on top and Round starting on bottom
```

---

### `setCompassTarget`

sets the target location for the player's compass

```csharp
player.setCompassTarget(location)
```

| parameter | default | description |
| --- | --- | --- |
| `location` | *required* | location object `{ x, y, z, yaw, pitch }` |

#### example

```csharp
player.setCompassTarget({ "x": 100, "y": 64, "z": 200 })
```

---

### `sendActionBar`

displays text above the player's hotbar

```csharp
player.sendActionBar(text)
```

| parameter | default | description |
| --- | --- | --- |
| `text` | *required* | action bar text, supports `&` color codes |

#### example

```csharp
player.sendActionBar("&emoooooo") // shows moooooo in yellow on the actionbar
```

---

### `teleport`

teleports the player to a target location object

```csharp
player.teleport(location)
```

| parameter | default | description |
| --- | --- | --- |
| `location` | *required* | location object `{ x, y, z, yaw, pitch }` |

#### example

```csharp
player.teleport({ "x": 100, "y": 50, "z": 150, "yaw": 0, "pitch": 0 })
```

---

### `give`

adds an item to the player's inventory

```csharp
player.give(item)
```

| parameter | default | description |
| --- | --- | --- |
| `item` | *required* | a `Katton.item(...)` value |

> [!note]
> see item for making items

#### example

```csharp
val sword = Katton.item("diamond_sword")
player.give(sword)
```

---

### `setTool`

replaces whatever item is currently held in that hand slot

```csharp
player.setTool(item)
```

| parameter | default | description |
| --- | --- | --- |
| `item` | *required* | a `Katton.item(...)` value |

> [!note]
> replaces whatever's currently in that hand, it doesn't add to the inventory like `give` does

#### example

```csharp
player.setTool(Katton.item("diamond_sword"))
```

---

### `setOffhandTool`

replaces whatever item is currently held in that hand slot

```csharp
player.setOffhandTool(item)
```

| parameter | default | description |
| --- | --- | --- |
| `item` | *required* | a `Katton.item(...)` value |

> [!note]
> replaces whatever's currently in that hand, it doesn't add to the inventory like `give` does

#### example

```csharp
player.setOffhandTool(Katton.item("shield"))
```

---

### `playSound`

plays a sound effect directly to the player

```csharp
player.playSound(sound, volume = 1.0, pitch = 1.0)
```

| parameter | default | description |
| --- | --- | --- |
| `sound` | *required* | bukkit sound key string |
| `volume` | default=1.0 | sound volume |
| `pitch` | default=1.0 | sound pitch multiplier |

> [!note]
> you can find all valid sound names at: https://jd.papermc.io/paper/1.21.11/org/bukkit/Sound.html

#### example

```csharp
player.playSound("entity_experience_orb_pickup")
player.playSound("entity_experience_orb_pickup", 0.5, 1.5)
```

---

### `launchForward`

launches the player in the direction they are currently facing

```csharp
player.launchForward(horizontal = 1.8, vertical = 0.65)
```

| parameter | default | description |
| --- | --- | --- |
| `horizontal` | default=1.8 | forward speed force |
| `vertical` | default=0.65 | upward speed force |

> [!note]
> maximum value for both horizontal and vertical speed is `6.0`

#### example

```csharp
player.launchForward(1.8, 0.65)
```

---

### `setVelocity`

sets the player's velocity

```csharp
player.setVelocity(x, y, z)
```

| parameter | default | description |
| --- | --- | --- |
| `x` | default=1.0 | x velocity |
| `y` | default=1.0 | y velocity |
| `z` | default=1.0 | z velocity |

#### example

```csharp
player.setVelocity(0.5, 2, 1)
```

---

### `giveEffect`

gives the player a potion effect

```csharp
player.giveEffect(Katton.potionEffect(potion_effect, time, strength))
```

| parameter | default | description |
| --- | --- | --- |
| `potion_effect` | *required* | the potion effect to give |
| `time` | *required* | the amount of time it should last |
| `strength` | *required* | the strength of the effect |

#### example

```csharp
player.giveEffect(Katton.potionEffect("speed", 10.seconds, 2))
```

---

### `removeEffect`

removes a specific potion effect from the player

```csharp
player.removeEffect(potion_effect)
```

| parameter | default | description |
| --- | --- | --- |
| `potion_effect` | *required* | the potion effect to remove |

#### example

```csharp
player.removeEffect("speed")
player.removeEffect(Katton.potionEffect("speed"))
```

---

### `removeAllEffects`

removes all active potion effects from a player

```csharp
player.removeAllEffects()
```

---

### `clearInventory`

wipes the player's entire inventory

```csharp
player.clearInventory()
```

> [!note]
> wipes everything, including equipped armor and offhand slots

#### example

```csharp
player.clearInventory()
```

---

### `setGlowing`

enables or disables the vanilla outline glowing effect around the player

```csharp
player.setGlowing(glowing = true)
```

| parameter | default | description |
| --- | --- | --- |
| `glowing` | default=true | whether the glowing effect should be active |

#### example

```csharp
player.setGlowing(true)
player.setGlowing(false)
```

---

### `setMovementSpeed`

modifies or resets the player's walking movement speed attribute

```csharp
player.setMovementSpeed(speed)
```

| parameter | default | description |
| --- | --- | --- |
| `speed` | default=0.1 | movement speed attribute base value (vanilla default is `0.1`) |

#### example

```csharp
player.setMovementSpeed(0.3) // vanilla default is 0.1
```

---

### `resetMovementSpeed`

modifies or resets the player's walking movement speed attribute

```csharp
player.resetMovementSpeed()
```

#### example

```csharp
player.resetMovementSpeed() // back to 0.1
```

---

### `setJumpStrength`

modifies or resets the player's jump height attribute

```csharp
player.setJumpStrength(strength)
```

| parameter | default | description |
| --- | --- | --- |
| `strength` | default=0.42 | jump strength attribute base value (vanilla default is `0.42`) |

#### example

```csharp
player.setJumpStrength(0.6) // vanilla default is 0.42
```

---

### `resetJumpStrength`

modifies or resets the player's jump height attribute

```csharp
player.resetJumpStrength()
```

#### example

```csharp
player.resetJumpStrength() // back to 0.42
```

---

### `setScale`

modifies the player's scale attribute

```csharp
player.setScale(scale)
```

| parameter | default | description |
| --- | --- | --- |
| `scale` | default=1.0 | scale factor |

---

### `resetScale`

resets the player's scale attribute to 1.0

```csharp
player.resetScale()
```

---

### `setInvulnerable`

toggles godmode damage immunity for the player

```csharp
player.setInvulnerable(invulnerable = true)
```

| parameter | default | description |
| --- | --- | --- |
| `invulnerable` | default=true | whether the player should be immune to all damage |

#### example

```csharp
player.setInvulnerable(true) // immune to all damage
player.setInvulnerable(false)
```

---

### `mount`

makes the player mount a entity

```csharp
player.mount(entity)
```

| parameter | default | description |
| --- | --- | --- |
| `entity` | *required* | the entity the player rides |

---

### `dismount`

makes the player stop riding whatever they are currently riding

```csharp
player.dismount()
```

#### example

```csharp
player.dismount()
```

---

### `shootProjectile`

shoots a projectile from the player in the direction they are currently facing

```csharp
player.shootProjectile(projectile = "arrow", speed = 2.0)
```

| parameter | default | description |
| --- | --- | --- |
| `projectile` | default="arrow" | type of projectile to launch |
| `speed` | default=2.0 | velocity multiplier of the projectile |

> [!note]
> maximum `speed` value is `6.0`

#### example

```csharp
player.shootProjectile("arrow", 2.0)
```

---
