Entities#

This page is the thematic overview of how the protocol manages entities. The byte-level layout of every packet listed here lives in Play — Clientbound and Play — Serverbound; this page only documents the conventions and cross-cutting semantics. Synced data fields ("entity metadata") are described in ./entity-metadata.

The server is fully authoritative over entity state. Clients receive a stream of small mutation packets that reference entities by their server-assigned Entity ID (a VarInt; 0 is reserved for "no entity" in some packets). UUIDs are only sent at spawn time and for player-info bookkeeping.

Lifecycle#

ID	Packet	Direction	Purpose
0x01	Add Entity	Client-bound	Spawn an entity (any type, including the player's own object form when seen by others).
0x4D	Remove Entities	Client-bound	Despawn one or more entities by ID.
0x63	Set Entity Data	Client-bound	Push synced data fields (see ./entity-metadata).
0x35	Move Entity Pos	Client-bound	Small relative position movement (delta encoded).
0x36	Move Entity Pos Rot	Client-bound	Small relative position + rotation movement (delta encoded).
0x38	Move Entity Rot	Client-bound	Small relative rotation.
0x7D	Teleport Entity	Client-bound	Absolute reposition with optional relative-flags.
0x23	Entity Position Sync	Client-bound	Authoritative resync of position+velocity (no animation).
0x53	Rotate Head	Client-bound	Updates only the head yaw.
0x65	Set Entity Motion	Client-bound	Sets velocity for client-side prediction.
0x22	Entity Event	Client-bound	Status code (one byte) — death animations, totem of undying, etc.
0x19	Damage Event	Client-bound	Modern signed damage notification (replaces legacy Animate(hurt)).
0x2A	Hurt Animation	Client-bound	Pure visual hurt direction.
0x02	Animate	Client-bound	One of: swing, leave bed, critical effect, magic critical, swing offhand.
0x7C	Take Item Entity	Client-bound	Animates an item being collected by an entity.
0x6B	Set Passengers	Client-bound	Replaces the passenger list of a vehicle.
0x39	Move Vehicle	Client-bound	Server-driven vehicle reposition.
0x22	Move Vehicle	Server-bound	Player-controlled vehicle movement.
0x74	Sound Entity	Client-bound	Plays a sound attached to an entity.
0x46	Player Info Update	Client-bound	Manages tablist + per-player chat session keys.
0x45	Player Info Remove	Client-bound	Drop tablist entries by UUID.

Identifiers#

• Entity ID — VarInt, server-assigned, unique within the world. Reused after despawn. 0 is reserved for "no entity" in some optional fields (e.g. damage source IDs, where the wire value is entity_id + 1).
• Entity UUID — sent only by Add Entity and the player-info packets. Used for player identity and chat-signature correlation, never for routine packet addressing.

Angle encoding#

Entity rotation on the wire uses byte-encoded angles for spawn / movement packets and float-degrees for absolute teleports.

• Byte angle (Pitch, Yaw, Head yaw): byte = floor(degrees * 256 / 360). One unit ≈ 1.406°.
• Float angle (Teleport Entity, Entity Position Sync, Hurt Animation, vehicle moves): plain degrees as IEEE-754 float.

For non-living entities the head yaw is normally equal to the body yaw.

Position: absolute vs delta#

There are three encodings in use for entity position:

1. Absolute Double, used by Add Entity, Teleport Entity, Entity Position Sync and the vehicle-move packets. Plain Double per axis.
2. Delta Short, used by Move Entity Pos and Move Entity Pos Rot. Encodes current - previous in 1/4096 of a block (short = Δblocks * 4096). A delta packet is only valid while the entity has not moved more than ±8 blocks since the last absolute teleport (±8 blocks * 4096 = ±32768 saturates the short). When the budget is exceeded, or to defeat accumulated rounding error, the server sends a full Teleport Entity instead.
3. LP Vec3 Velocity, used in Add Entity and Set Entity Motion. Variable-length Vec3.LP_STREAM_CODEC (net.minecraft.network.LpVec3): single 0x00 byte when the vector is below 3.05e-5 on every axis, otherwise 6 bytes encoding three 15-bit packed axes plus a 2-bit scale and a continuation flag, optionally followed by a VarInt for the upper scale bits. Range is ±1.717e10 per axis. This replaces the pre-1.21.7 short × 3 velocity encoding ((blocks per tick) * 8000 clamped to a signed short) — a stale spec here will produce 5 extra bytes per Add Entity packet and disconnect the client.

Teleport Entity carries a Relative flags bitset that lets a single packet mix absolute and delta semantics per axis (used for elytra / boat resync without snapping):

Bit	Meaning
0	X is relative
1	Y is relative
2	Z is relative
3	Yaw is relative
4	Pitch is relative
5	Velocity X is relative
6	Velocity Y is relative
7	Velocity Z is relative
8	Rotate velocity by the new yaw/pitch

Damage and animations#

Modern damage uses Damage Event (signed source identifiers, optional source position) plus Hurt Animation for the camera/model flinch direction. The legacy Animate(hurt) flag is no longer used in 26.1.2 — Animate now only carries the swing / bed / critical / magic-critical / off-hand-swing codes.

Entity Event is a generic catch-all that uses a 32-bit Int entity ID (not a VarInt — kept for protocol-historical reasons) and a single byte of event code (2 = hurt legacy, 3 = death, 35 = totem, 60 = explode, etc.).

Add Entity Data field#

The numeric Type field in Add Entity indexes into the minecraft:entity_type registry, whose IDs are part of the protocol contract for 26.1.2. The auxiliary Data integer is type-dependent; the most common uses are:

Entity type	Data meaning
falling_block	Block-state numeric ID.
item_frame, glow_item_frame, painting	Hanging facing direction (0=down, 1=up, 2=north, 3=south, 4=west, 5=east).
arrow, spectral_arrow, trident	Shooter entity ID + 1 (0 = none).
fishing_bobber	Owner player entity ID.
fireball, small_fireball, dragon_fireball, wither_skull	Shooter entity ID + 1.
experience_orb	XP value.
All others	0.

Most entity-specific state (variant, age, color, pose, nameplate, etc.) lives in the synced data fields delivered by Set Entity Data; see ./entity-metadata.

Player as entity#

A player is also an entity, but tablist and chat-session bookkeeping is independent of its entity ID. Player Info Update carries an action bitset (add player, initialize chat, update gamemode, update listed, update latency, update display name, update list priority, update show-hat) plus per-action payloads keyed by player UUID. Player Info Remove is just a list of UUIDs to drop.

These packets are how the client learns of a player's chat session public key (see ./chat) and gamemode changes that occur on other clients.

Source: net/minecraft/network/protocol/game/ClientboundAddEntityPacket.java, ClientboundMoveEntityPacket.java, ClientboundTeleportEntityPacket.java, ClientboundEntityPositionSyncPacket.java, ClientboundSetEntityDataPacket.java, ClientboundRemoveEntitiesPacket.java, ClientboundRotateHeadPacket.java, ClientboundSetEntityMotionPacket.java, ClientboundEntityEventPacket.java, ClientboundDamageEventPacket.java, ClientboundHurtAnimationPacket.java, ClientboundAnimatePacket.java, ClientboundTakeItemEntityPacket.java, ClientboundSetPassengersPacket.java, ClientboundMoveVehiclePacket.java, ClientboundSoundEntityPacket.java, ClientboundPlayerInfoUpdatePacket.java, ClientboundPlayerInfoRemovePacket.java, net/minecraft/world/entity/Entity.java, net/minecraft/world/entity/EntityType.java.