---
title: "Entity handle"
---

> Documentation Index
> Fetch the complete documentation index at: https://aesthetic-docs.pages.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Entity handle

Returned by `player`, `world:players()`, `world:entities()`, `world:entity(id)`. Live
handle — every colon-call re-reads the game.

Do not keep handles past the entity's life. After despawn, death or world change,
re-query. Use `e:alive()` to know when to drop a handle.

## All entities

| Method | Meaning |
|--------|---------|
| `id`, `uuid`, `name`, `type` | Entity id, UUID, display name, type (`"minecraft:player"`) |
| `name_text`, `display_name` | Name / full display name as [text](/text) snapshots |
| `custom_name`, `has_custom_name` | Name-tag text snapshot (or `nil`), and whether one is set |
| `team`, `team_color` | [Scoreboard team](/scoreboard) handle (or `nil`) and `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 / eye position as [vec3](/vec3) |
| `prev_position`, `delta` | Previous-tick position and `position - prev_position` |
| `velocity` | Velocity as [vec3](/vec3), blocks per tick |
| `rotation` | Multi-return: `yaw, pitch` |
| `yaw`, `pitch` | Look direction |
| `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 (drowning) |
| `fall_distance` | Fall distance so far |
| `vehicle` | Entity it rides, or `nil` |
| `passengers` | Rider handles (empty when none) |

## Living entities

`nil` on non-living entities.

| Method | Meaning |
|--------|---------|
| `health`, `max_health`, `absorption` | Hearts, including yellow absorption |
| `armor` | Armor points |
| `hurt_time`, `death_time`, `dead` | Red-flash / death animation ticks |
| `baby`, `scale` | Baby flag and size multiplier |
| `body_yaw`, `head_yaw` | Body and head rotation. Players: base `yaw` is look direction. Mobs: `yaw` tracks body, `head_yaw` the head |
| `movement_speed` | Movement speed attribute |
| `blocking`, `climbing`, `gliding`, `sleeping`, `jumping` | Action state (`gliding` = elytra) |
| `using_item`, `using_riptide` | Using an item / riptide spinning |
| `item_use_time`, `item_use_time_left` | Ticks used / remaining for the current item |
| `held_item`, `offhand_item` | Hand [item handles](/item) |
| `active_item` | Item being used right now, or `nil` |
| `equipped(slot)` | Slot item: `"head"`, `"chest"`, `"legs"`, `"feet"`, `"mainhand"`, `"offhand"` |
| `effects` | Potion effects: `{id, name, name_text, category, amplifier, duration, infinite, ambient, visible}[]`. `category` is `"beneficial"`, `"harmful"` or `"neutral"` |
| `attributes` | `id -> {base, value}`, e.g. `e:attributes()["minecraft:attack_damage"].value` |

## Players

Any player also answers `ping` (ms; `0` when unknown) and `gamemode`.

**Your own player only** (`nil` for others):

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

## Self control

Only on your own player (`player`) — no-ops on other entities:

| Method | What it does |
|--------|--------------|
| `set_velocity(v)` | Sets velocity to a [vec3](/vec3), blocks per tick |
| `jump()` | Jumps, even mid-air |
| `set_position(pos)` | Teleports client-side to a [vec3](/vec3) |
| `set_rotation(yaw, pitch)` | Sets real view rotation (moves the camera, not freelook); pitch clamped to `[-90, 90]` |
| `raycast(max_distance?)` | Crosshair ray vs blocks and entities; [hit table](/raycast); default reach `4.5` |

Source: https://aesthetic-docs.pages.dev/entity/index.md