# entity

you get an `entity` value from `Katton.world().entities`, or as the return value of `Katton.world().spawnEntity(...)`. players are **not** included here, they're exposed separately via `player` values (see [player](https://www.google.com/search?q=player.md)) and `Katton.world().players`

---

## properties

```csharp
entity.uuid //"8667ba71-b85a-4004-af54-457a9734eed7" as a string
entity.type //"zombie"
entity.is_valid //true / false. an entity can stop existing at any point, whether it dies, despawns, etc. once that happens, every method below (other than the properties) throws a runtime error so check first if the `entity` value still exists
entity.location //{ x: 12.5, y: 64.0, z: -3.0, yaw: 90.0, pitch: 0.0 }
entity.health //20.0, living entities only
entity.max_health //20.0, living entities only
entity.tags //a list of scoreboard tag strings
entity.vehicle //a `entity` value for whatever they are riding
entity.yaw //living entities only
entity.pitch //living entities only
```

## methods

```csharp
entity.setHealth(health)
entity.setDisplayName(text)
display.setSkin(username)
entity.teleport(location)
entity.setGlowing(glowing = true)
entity.addTag(tag)
entity.removeTag(tag)
entity.hasTag(tag)
entity.setMovementSpeed(speed)
entity.resetMovementSpeed()
entity.setJumpStrength(strength)
entity.resetJumpStrength()
display.setScale(x, y, z) or entity.setScale(scale)
entity.resetScale()
display.setText(text)
display.setBackgroundColor(r, g, b, a)
display.resetBackground()
display.setDefaultBackground(enabled)
display.setTextOpacity(opacity)
display.setAlignment(alignment)
display.setLineWidth(width)
display.setSeeThrough(seeThrough)
display.setShadowed(shadowed)
display.setBillboard(billboard)
display.setItem(item)
display.setBlock(material)
display.setOffset(x, y, z)
display.setRotation(yaw, pitch, roll)
display.setTeleportDuration(ticks)
display.setInterpolationDuration(ticks)
display.setInterpolationDelay(ticks)
entity.giveEffect(potion_effect)
entity.removeEffect(potion_effect)
entity.removeAllEffects()
thisEntity.mount(entity)
thisEntity.dismount()
entity.kill()
```

---

### `setHealth`

sets the entity's current health

```csharp
entity.setHealth(health)
```

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

> [!note]
> living entities only. value is clamped between `0` and the entity's `max_health`

#### example

```csharp
val zombie = Katton.world().spawnEntity("zombie", player.location)
zombie.setHealth(5)
```

---

### `setDisplayName`

sets the custom name tag displayed above the entity

```csharp
entity.setDisplayName(text)
```

| parameter | default | description |
| --- | --- | --- |
| `text` | default="" | custom display text, supports `&` color codes |

> [!note]
> passing `""` hides the name tag

#### example

```csharp
zombie.setDisplayName("&c&lBOSS ZOMBIE")
```

---

### `setSkin`

sets the entity's skin if the entity is a mannequin

```csharp
display.setSkin(username)
```

| parameter | default | description |
| --- | --- | --- |
| `username` | *required* | changes the skin of a mannequin to this username |

> [!note]
> only works on mannequins

#### example

```csharp
mannequin.setSkin("yayAmelia")
```

---

### `teleport`

teleports the entity to a target location object

```csharp
entity.teleport(location)
```

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

#### example

```csharp
zombie.teleport({ "x": 0, "y": 70, "z": 0, "yaw": 0, "pitch": 0 })
```

---

### `setGlowing`

enables or disables the vanilla outline glowing effect around the entity

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

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

#### example

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

---

### `addTag`

adds a scoreboard tag to the entity

```csharp
entity.addTag(tag)
```

| parameter | default | description |
| --- | --- | --- |
| `tag` | default="" | scoreboard tag string |

> [!note]
> scoreboard tags are handy for marking specific entities your script spawned so you can tell them apart from everything else in the world later

#### example

```csharp
val zombie = Katton.world().spawnEntity("zombie", player.location)
zombie.addTag("boss_fight_mob")
for (e in Katton.world().entities) {
    if (e.hasTag("boss_fight_mob")) {
        e.setGlowing(true)
    }
}
```

---

### `removeTag`

removes a scoreboard tag from the entity

```csharp
entity.removeTag(tag)
```

| parameter | default | description |
| --- | --- | --- |
| `tag` | default="" | scoreboard tag string |

> [!note]
> `removeTag` does nothing if the tag was never there

---

### `hasTag`

checks if the entity has a scoreboard tag

```csharp
entity.hasTag(tag)
```

| parameter | default | description |
| --- | --- | --- |
| `tag` | default="" | scoreboard tag string |

---

### `setMovementSpeed`

modifies movement speed attribute base values

```csharp
entity.setMovementSpeed(speed)
```

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

> [!note]
> living entities only

#### example

```csharp
zombie.setMovementSpeed(0.3)
```

---

### `resetMovementSpeed`

resets movement speed attribute base values to default

```csharp
entity.resetMovementSpeed()
```

> [!note]
> living entities only

---

### `setJumpStrength`

modifies jump height attribute base values

```csharp
entity.setJumpStrength(strength)
```

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

> [!note]
> living entities only

#### example

```csharp
zombie.setJumpStrength(0.6)
```

---

### `resetJumpStrength`

resets jump height attribute base values to default

```csharp
entity.resetJumpStrength()
```

> [!note]
> living entities only

---

### `setScale`

resizes the display entity along each coordinate axis or modifies the living entity's scale attribute

```csharp
display.setScale(x, y, z) or entity.setScale(scale)
```

| parameter | default | description |
| --- | --- | --- |
| `scale` | default=1.0 | scale value multiplier |
| `x` | default=1 | horizontal scale factor (width) |
| `y` | default=1 | vertical scale factor (height) |
| `z` | default=1 | depth scale factor (length) |

> [!note]
> only works on display entities for 3 axis scale, or living entities for attribute scale

#### example

```csharp
val display = Katton.world().spawnEntity("block_display", player.location)
display.setBlock("stone")
display.setScale(1, 3, 1)
```

---

### `resetScale`

resets the scale configuration back to default

```csharp
entity.resetScale()
```

---

### `setText`

sets the text content displayed by a text display entity

```csharp
display.setText(text)
```

| parameter | default | description |
| --- | --- | --- |
| `text` | default="" | text content string, automatically filtered and styled |

> [!note]
> only works on text display entities (`text_display`)

#### example

```csharp
val display = Katton.world().spawnEntity("text_display", player.location)
display.setText("hello world")
```

---

### `setBackgroundColor`

changes the background color of a text display entity

```csharp
display.setBackgroundColor(r, g, b, a)
```

| parameter | default | description |
| --- | --- | --- |
| `r` | default=0 | red color channel (0 to 255) |
| `g` | default=0 | green color channel (0 to 255) |
| `b` | default=0 | blue color channel (0 to 255) |
| `a` | default=255 | alpha transparency channel (0 to 255) |

> [!note]
> only works on text display entities (`text_display`)

#### example

```csharp
display.setBackgroundColor(255, 0, 0, 128)
```

---

### `resetBackground`

resets the background color of a text display entity

```csharp
display.resetBackground()
```

> [!note]
> only works on text display entities (`text_display`)

#### example

```csharp
display.resetBackground()
```

---

### `setDefaultBackground`

configures whether the default background is enabled for a text display entity

```csharp
display.setDefaultBackground(enabled)
```

| parameter | default | description |
| --- | --- | --- |
| `enabled` | default=true | whether the default background is enabled |

> [!note]
> only works on text display entities (`text_display`)

#### example

```csharp
display.setDefaultBackground(false)
```

---

### `setTextOpacity`

sets the opacity of the text on a text display entity

```csharp
display.setTextOpacity(opacity)
```

| parameter | default | description |
| --- | --- | --- |
| `opacity` | default=255 | text opacity value (0 to 255) |

> [!note]
> only works on text display entities (`text_display`)

#### example

```csharp
display.setTextOpacity(128)
```

---

### `setAlignment`

sets the text alignment on a text display entity

```csharp
display.setAlignment(alignment)
```

| parameter | default | description |
| --- | --- | --- |
| `alignment` | default="center" | alignment string, must be one of: left, center, right |

> [!note]
> only works on text display entities (`text_display`)

#### example

```csharp
display.setAlignment("left")
```

---

### `setLineWidth`

sets the maximum line width for wrapping text on a text display entity

```csharp
display.setLineWidth(width)
```

| parameter | default | description |
| --- | --- | --- |
| `width` | default=200 | maximum width (clamped between 1 and 1000) |

> [!note]
> only works on text display entities (`text_display`)

#### example

```csharp
display.setLineWidth(300)
```

---

### `setSeeThrough`

enables or disables whether the text display is visible through blocks

```csharp
display.setSeeThrough(seeThrough)
```

| parameter | default | description |
| --- | --- | --- |
| `seeThrough` | default=true | whether text renders through obstacles |

> [!note]
> only works on text display entities (`text_display`)

#### example

```csharp
display.setSeeThrough(true)
```

---

### `setShadowed`

enables or disables the text shadow effect on a text display entity

```csharp
display.setShadowed(shadowed)
```

| parameter | default | description |
| --- | --- | --- |
| `shadowed` | default=true | whether text has a shadow |

> [!note]
> only works on text display entities (`text_display`)

#### example

```csharp
display.setShadowed(true)
```

---

### `setBillboard`

sets the billboard setting of the text display entity

```csharp
display.setBillboard(billboard)
```

| parameter | default | description |
| --- | --- | --- |
| `billboard` | default=center | the billboard setting |

> [!note]
> only works on text display entities (`text_display`)

#### example

```csharp
display.setBillboard("fixed")
```

---

### `setItem`

sets the item stack displayed by an item display entity

```csharp
display.setItem(item)
```

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

> [!note]
> only works on item display entities (`item_display`). see item for making items

#### example

```csharp
val display = Katton.world().spawnEntity("item_display", player.location)
display.setItem(Katton.item("diamond_sword"))
```

---

### `setBlock`

sets the block material displayed by a block display entity

```csharp
display.setBlock(material)
```

| parameter | default | description |
| --- | --- | --- |
| `material` | *required* | block material name string (e.g. `"stone"`) |

> [!note]
> only works on block display entities (`block_display`)

#### example

```csharp
val display = Katton.world().spawnEntity("block_display", player.location)
display.setBlock("stone")
```

---

### `setOffset`

shifts the display entity relative to the entity's actual pivot point without moving the entity itself

```csharp
display.setOffset(x, y, z)
```

| parameter | default | description |
| --- | --- | --- |
| `x` | default=0 | horizontal translation offset (left / right) |
| `y` | default=0 | vertical translation offset (up / down) |
| `z` | default=0 | forward / backward translation offset |

> [!note]
> only works on display entities (`item_display`, `block_display`, `text_display`)

#### example

```csharp
val display = Katton.world().spawnEntity("block_display", player.location)
display.setBlock("stone")
display.setOffset(0, 2, 0)
```

---

### `setRotation`

rotates the display model using degrees

```csharp
display.setRotation(yaw, pitch, roll)
```

| parameter | default | description |
| --- | --- | --- |
| `yaw` | default=0 | horizontal rotation around the vertical Y axis (left / right) |
| `pitch` | default=0 | vertical tilt around the X axis (up / down) |
| `roll` | default=0 | sideways tilt around the Z axis |

> [!note]
> only works on display entities (`item_display`, `block_display`, `text_display`)

#### example

```csharp
val display = Katton.world().spawnEntity("item_display", player.location)
display.setItem(Katton.item("diamond_sword"))
display.setRotation(0, 45, 90)
```

---

### `setTeleportDuration`

sets the teleport tick duration for position changes to transition smoothly instead of snapping immediately

```csharp
display.setTeleportDuration(ticks)
```

| parameter | default | description |
| --- | --- | --- |
| `ticks` | default=0 | transition duration in ticks (clamped between `0` and `59`) |

> [!note]
> only works on display entities (`item_display`, `block_display`, `text_display`)

#### example

```csharp
display.setTeleportDuration(20)
```

---

### `setInterpolationDuration`

sets the interpolation duration

```csharp
display.setInterpolationDuration(ticks)
```

| parameter | default | description |
| --- | --- | --- |
| `ticks` | default=0 | interpolation duration in ticks |

> [!note]
> only works on display entities (`item_display`, `block_display`, `text_display`)

---

### `setInterpolationDelay`

sets the interpolation delay

```csharp
display.setInterpolationDelay(ticks)
```

| parameter | default | description |
| --- | --- | --- |
| `ticks` | default=0 | interpolation delay in ticks |

> [!note]
> only works on display entities (`item_display`, `block_display`, `text_display`)

---

### `giveEffect`

gives the entity a potion effect

```csharp
entity.giveEffect(potion_effect)
```

| parameter | default | description |
| --- | --- | --- |
| `effect` | *required* | a potion effect value |

---

### `removeEffect`

removes a specific potion effect from the entity

```csharp
entity.removeEffect(potion_effect)
```

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

---

### `removeAllEffects`

removes all active potion effects from the entity

```csharp
entity.removeAllEffects()
```

---

### `mount`

makes the entity mount an entity

```csharp
thisEntity.mount(entity)
```

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

---

### `dismount`

makes the entity stop riding whatever they are currently riding

```csharp
thisEntity.dismount()
```

---

### `kill`

removes the entity immediately from the world

```csharp
entity.kill()
```

#### example

```csharp
zombie.kill()
```

---
