Entity metadata

Entity Metadata Format

Note that entity metadata is a totally distinct concept from block metadata. All entities must send at least one item of metadata, in most cases this will be the health item.

The entity metadata format is quirky dictionary format, where the key and the value's type are packed in a single byte.

To parse, repeat the following procedure:

1. Read an unsigned byte
2. If this byte == 127, stop reading
3. Decompose the byte.
   The bottom 5 bits (0x1F) serve as an identifier (key) for the data to follow.
   The top 3 bits (0xE0) serve as a type.
4. Read and unpack based on the type (below)

Type	Meaning
0	byte
1	short
2	int
3	float*
4	string16
5	slot
6	int, int, int (x, y, z)

*Not currently used

In C-like psuedocode: <source lang="c"> do {

   item = readByte();
   if (item == 0x7F) break;
   var index = item & 0x1F;
   var type = item >> 5;
   
   if (type == 0) metadata[index] = readByte();
   if (type == 1) metadata[index] = readShort();
   if (type == 2) metadata[index] = readInt();
   if (type == 3) metadata[index] = readFloat();
   if (type == 4) metadata[index] = readString16();
   if (type == 5) metadata[index] = readSlot();
   if (type == 6) {
       var vector;
       vector.x = readInt();
       vector.y = readInt();
       vector.z = readInt();
       metadata[index] = vector;
   }

} while (true); </source>

Common Metadata

Index 0, byte: Flags

All mobs, objects and players send metadata with index 0. The value is a byte representing 8 boolean flags:

Bit index	Bit mask	Meaning
0	0x01	Entity on fire
1	0x02	Entity crouched
2	0x04	Entity riding
3	0x08	Sprinting
4	0x10	Eating/Drinking/Blocking (any right click action?)
5	0x20	Invisible

Index 1, short: Drowning counter

Initialized to 300 on entity spawn. When underwater, this is decremented by 3 every tick (and sent S->C with Entity Metadata (0x28)). If the value dips below -19, an Entity Status (0x26) is sent (i.e. the entity is hurt) and counter is reset to 0.

Seems to be sent for *at least* all mobs. Not sure about players.

Index 6, float: Health

The health of a living entity.

Index 7, int: Potion effects

Players and most (all?) mobs send metadata with index 8. This specifies the colour of the bubbling effects around the player.

The value is an int, that should be decomposed into four bytes, representing 0x00RRGGBB

If the value is 0, no potion effects currently apply to the entity.

Index 8, slot: Firework type

Firework entities send a metadata with the item stack used to launch itself with index 8, not to be confused with the potion effect metadata above. These entities are generally unaffected by potion effects, so it doesn't matter that they reuse the same index.

This item stack will be a FIREWORK with the effects stored in its additional NBT data (meta item in Bukkit).

Index 8, byte: Hide potion effects

1 when a potion effect applied is given by a beacon. 0 when there are no beacon effects applied. It makes the potion particles less obtrusive.

Index 10, string: Name

The string to display on the nameplate, if shown.

Index 11, byte: Show name

If 1, the nameplate will be displayed over the entity.

Index 12, int: Animals

0 for ordinary animals.

Baby animals have the value -23999. This corresponds to the number of ticks in a minecraft day, which is how long it takes for a baby animal to "grow up". It is therefore considered likely that this field determines the size of the animal, and that Entity Metadata will update it as the animal grows.

When an animal becomes a parent this value is set to 6000 and is then decreased over time. Probably a countdown until they can have a new baby.

Mobs

Mobs are spawned via 0x18 Mob Spawn

Type	Name	x, z	y
50	Creeper	0.6	1.8
51	Skeleton	0.6	1.8
52	Spider	1.4	0.9
53	Giant Zombie	3.6	10.8
54	Zombie	0.6	1.8
55	Slime	0.6 * size	0.6 * size
56	Ghast	4	4
57	Zombie Pigman	0.6	1.8
58	Enderman
59	Cave Spider
60	Silverfish
61	Blaze
62	Magma Cube	0.6 * size	0.6 * size
63	Ender Dragon
64	Wither
65	Bat
66	Witch
90	Pig	0.9	0.9
91	Sheep	0.6	1.3
92	Cow	0.9	1.3
93	Chicken	0.3	0.4
94	Squid	0.95	0.95
95	Wolf	0.6	1.8
96	Mooshroom
97	Snowman
98	Ocelot
99	Iron Golem
120	Villager

Extra Metadata

Player

• Index 9 (byte): Number of arrows sticking into the player
• Index 18 (byte): Score of a player (Probably be the scoreboard displayed on death)

Creeper

• Index 16 (byte): Status. Depends on the fuse, values from -1 to 1
• Index 17 (byte): Charged. 1 if the creeper has been hit by lightning, 0 otherwise.

Spider / Cave Spider

• Index 16 (byte): Unknown, Values 0 and 1. Possibly aggression.

Slime / Magma Cube

• Index 16 (byte): Size. Randomly-generated. 0, 1, 2 or 4.

Ghast

• Index 16 (byte): Aggression. 1 for aggressive (red eyes), 0 otherwise.

Enderman

• Index 16 (byte): Item in hand
• Index 17 (byte): Item metadata
• Index 18 (byte): Aggression. 1 for aggressive, 0 otherwise.

Blaze

• Index 16 (byte): Attacking. 1 sets the blaze on fire, and shortly after it will attack. 0 signals the end of the attack.#

Ender Dragon

• Index 16 (int): Health. Full health = 200

Wither

• Index 16 (int): Health. Full health = 300

Pig

• Index 16 (byte): Saddled. 1 if the pig is wearing a saddle, 0 otherwise.

Sheep

• Index 16 (byte): bit 0x10 indicates shearedness. bits 0x0F indicate color (see below).

Index	Wool Color
0	White
1	Orange
2	Magenta
3	Light Blue
4	Yellow
5	Lime
6	Pink
7	Gray
8	Silver
9	Cyan
10	Purple
11	Blue
12	Brown
13	Green
14	Red
15	Black

Wolf

• Index 16 (byte): Flags (see below).
• Index 17 (string): Name of player that tamed wolf.
• Index 18 (float): Health. Values from 8 to 0
• Index 19 (byte): Unknown, either 0 or 1
• Index 20 (byte): Color of the collar. (look up)

Bit index	Bit mask	Meaning
0	0x01	Sitting down
1	0x02	Aggressive (red eyes)
2	0x04	Tamed

Ocelot

• Index 16 (byte): Flags. Same as Wolf but without the Agressive flag.
• Index 17 (string): Name of player that tamed the ocelot.
• Index 18 (byte): Skin: 0 - ocelot, 3 - tamed cat, probably 1 and 2 too.

Villager

• Index 12 (int): Same as index 12 of Animals, except that when the baby villager becomes a parent, no countdown starts.
• Index 16 (int): Profession of villager, as according to this.

Iron Golem

• Index 16 (byte): 0 or 1. Indicates whether the iron golem was spawned by natural means (0) or by a player constructing it (1).

Bat

• Index 16 (byte): 0 or 1. Indicates if the bat is flying (1) or is hanging off a block (0)

Pig Zombie / Zombie

• Index 12 (byte): 1 if it is a baby. 0 when it is an adult

Zombie

• Index 13 (byte): 1 if it is a villager. 0 if it is a normal zombie

Skeleton / Wither skeleton

• Index 13 (byte): 1 If it is a wither skeleton, 0 if it is a normal skeleton

Objects

Objects are spawned via 0x17 Spawn Object/Vehicle. See Object Data for more details.

ID	Name	x, z	y
1	Boat	1.5	0.6
2	Item Stack (Slot)	0.5	0.5
10	Minecart	0.98	0.7
11	Minecart (storage)	0.98	0.7
12	Minecart (powered)	0.98	0.7
50	Activated TNT	0.98	0.98
51	EnderCrystal	1.25?	2.25?
60	Arrow (projectile)	0.5	0.5
61	Snowball (projectile)	0.25	0.25
62	Egg (projectile)	0.25	0.25
65	Thrown Enderpearl
66	Wither Skull
70	Falling Objects	0.98	0.98
71	Item frames	?	?
72	Eye of Ender
73	Thrown Potion
74	Falling Dragon Egg	0.98	0.98
75	Thrown Exp Bottle
90	Fishing Float	0.25?	0.25?

Extra metadata

Arrow

• Index 16 (byte): 1 if the arrow should be effected by gravity. 0 if the arrow is stuck in a block

Minecart

• Index 16 (byte): Bitfield for flags, but the only known value is 1 if the minecart is powered and has fuel.
• Index 17 (int): Minecart shaking (When punched). Initialized to 0. Higher number gives a higher shaking.
• Index 18 (int): Unknown. Initialized to 1
• Index 19 (int): Damage taken. The cart breaks when this is over 40.
• Index 20 (int): Block ID and metadata (upper 16 bits: metadata; lower 16: block ID)
• Index 21 (int): Block Y position (default: 6)
• Index 22 (byte): Show block (1: true; 0: false)

Boat

• Index 17 (int): Time since last hit
• Index 18 (int): "Forward direction". Initialized to 1.
• Index 19 (int): Damage taken.

Item Stack (Slot)

• Index 10 (slot): Item stack (Slot)

Item Frame

• Index 2 (slot): Item stack (Slot)
• Index 3 (byte): Orientation (0-3, increments of 90 degrees)

Other

Players are spawned via 0x14 Named Entity Spawn. They have dimensions 0.6 * 1.8.

Paintings are spawned via 0x19 Entity: Painting. Their dimensions depend on their type.