# Entity

Handles come from `player`, `world:players()`, `world:entities()` and `world:entity(id)`.
Every call re-reads the game, so a handle you keep stays current. It does not survive the
entity: after a despawn, death or world change, query again. `e:alive()` tells you when to
drop one.

```lua
local target = world:player("Notch")
if target and target:distance() < 6 then
    rotation.look_at(target:eye_position())
end
```

## Any entity

| Method | Returns |
|--------|---------|
| `id()`, `uuid()` | Numeric entity id, UUID string |
| `type()` | Type id, e.g. `"minecraft:player"` |
| `name()` | Display name as a string |
| `name_text()`, `display_name()` | Name and full display name as [text](text.md) |
| `custom_name()`, `has_custom_name()` | Name-tag text or `nil`, and whether one is set |
| `team()`, `team_color()` | [Scoreboard team](scoreboard.md) or `nil`, and its `0xAARRGGBB` color |
| `is_self()` | `true` for your own player |
| `alive()`, `age()` | Alive flag, ticks since spawn |
| `pose()` | `"standing"`, `"crouching"`, `"swimming"`, `"gliding"`, `"sleeping"`, … |
| `position()`, `eye_position()` | Feet and eye position as [vec3](vec3.md) |
| `prev_position()`, `delta()` | Last tick's position, and `position - prev_position` |
| `velocity()` | Blocks per tick as [vec3](vec3.md) |
| `yaw()`, `pitch()`, `rotation()` | Look angles; `rotation` returns both |
| `width()`, `height()` | Hitbox size |
| `distance()` | Distance from you (`0` for yourself or with no local player) |
| `on_ground()`, `sneaking()`, `sprinting()`, `swimming()`, `crawling()` | Movement state |
| `spectator()`, `invisible()`, `glowing()`, `silent()`, `no_gravity()` | Status flags |
| `on_fire()`, `fire_ticks()`, `fire_immune()` | Burning state |
| `in_water()`, `wet()`, `submerged()`, `in_lava()` | Fluid state; `wet` includes rain |
| `frozen_ticks()`, `frozen()` | Powder snow freezing |
| `air()`, `max_air()` | Remaining air before drowning |
| `fall_distance()` | Blocks fallen so far |
| `vehicle()` | Entity it rides, or `nil` |
| `passengers()` | Riders, empty when none |

## Living entities

`nil` on anything that is not living.

| Method | Returns |
|--------|---------|
| `health()`, `max_health()`, `absorption()` | Hearts, including yellow absorption |
| `armor()` | Armor points |
| `hurt_time()`, `death_time()`, `dead()` | Red-flash and death animation ticks |
| `baby()`, `scale()` | Baby flag, size multiplier |
| `body_yaw()`, `head_yaw()` | On players `yaw` is the look direction; on mobs `yaw` follows the body and `head_yaw` the head |
| `movement_speed()` | Movement speed attribute |
| `blocking()`, `climbing()`, `gliding()`, `sleeping()`, `jumping()` | Action state (`gliding` is elytra) |
| `using_item()`, `using_riptide()` | Using an item, riptide spinning |
| `item_use_time()`, `item_use_time_left()` | Ticks spent and left on the current item |
| `held_item()`, `offhand_item()` | Hand [items](item.md) |
| `active_item()` | Item being used right now, or `nil` |
| `equipped(slot)` | `"head"`, `"chest"`, `"legs"`, `"feet"`, `"mainhand"`, `"offhand"` |
| `effects()` | Potion effects, see below |
| `attributes()` | `id -> {base, value}`, e.g. `e:attributes()["minecraft:attack_damage"].value` |

An effect entry is
`{id, name, name_text, category, amplifier, duration, infinite, ambient, visible}`, where
`category` is `"beneficial"`, `"harmful"` or `"neutral"`.

## Players

Every player also answers `ping()` (ms, `0` when unknown) and `gamemode()`.

These are yours alone and return `nil` for other players:

| Method | Returns |
|--------|---------|
| `food()`, `saturation()` | Hunger bar and the hidden saturation behind it |
| `xp_level()`, `xp_progress()`, `total_xp()` | Level, progress to the next (`0..1`), total points |
| `attack_cooldown()` | Attack charge `0..1`, `1` at full strength |
| `flying()`, `allow_flying()`, `creative()` | Ability flags |
| `walk_speed()`, `fly_speed()` | Ability speeds |

## Control

Only your own player acts on these; on other entities they do nothing.

| Method | Does |
|--------|------|
| `set_velocity(v)` | Sets velocity in blocks per tick |
| `jump()` | Jumps, even mid-air |
| `set_position(pos)` | Teleports client-side |
| `set_rotation(yaw, pitch)` | Sets the real view rotation and moves the camera with it. Pitch clamps to `[-90, 90]` |
| `raycast([max_distance])` | Crosshair ray against blocks and entities, default reach `4.5`. Fields on [Blocks & hits](blocks.md#raycast-hits) |

For server-visible aim that leaves the camera alone, use [`rotation`](rotation.md) instead of
`set_rotation`.