Entity metadata

Metadata Format

The 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 bytes (0x1F) serve as an identifier (key) for the data to follow. 
   The top 3 bits (0xE0) serve as a type:
    0: byte
    1: short
    2: int
    3: float
    4: string16,
    5: short, byte, short (slot type)
    6: int, int, int
4) Read and unpack based on the type (above)

In python:

   #socket is positioned at the beginning of the metadata array
   metadata = {}
   x = socket.unpack('byte')
   while x != 127:
       index = x & 0x1F # Lower 5 bits
       ty    = x >> 5   # Upper 3 bites
       if ty == 0: val = socket.unpack('byte') 
       if ty == 1: val = socket.unpack('short') 
       if ty == 2: val = socket.unpack('int') 
       if ty == 3: val = socket.unpack('float') 
       if ty == 4: val = socket.unpack('string16')
       if ty == 5:
           val = {}
           val["id"]     = socket.unpack('short')
           val["count"]  = socket.unpack('byte')
           val["damage"] = socket.unpack('short')
       if ty == 6:
           val = []
           for i in range(3):
               val.append(socket.unpack('int'))
       metadata[index] = (ty, val)
       x = socket.unpack('byte')
   return metadata

Common Metadata

Index 0: 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

Index 8: 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 4-bit nibbles, representing 0x00RRGGBB

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

Mobs

Mobs are spawned via 0x18 Mob Spawn

50: Creeper

• Dimensions: 0.6 * 1.8
• Index 16 (byte): Status. Depends on the fuse
• Index 17 (byte): Charged. 1 if the creeper has been hit by lightning, 0 otherwise.

51: Skeleton

• Dimensions: 0.6 * 1.8
• No extra metadata

52: Spider

• Dimensions: 1.4 * 0.9 (note: has this changed?)
• No extra metadata

53: Giant Zombie

• Dimensions: 3.6 * 10.8
• No extra metadata

54: Zombie

• Dimensions: 0.6 * 1.8
• No extra metadata

55: Slime

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

56: Ghast

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

57: Zombie Pigman

• Dimensions: 0.6 * 1.8
• No extra metadata

58: Enderman

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

59: Cave Spider

• Dimensions: Unknown
• No extra metadata

60: Silverfish

• Dimensions: Unknown
• No extra metadata

61: Blaze

• Dimensions: Unknown
• No extra metadata

62: Magma Cube

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

63: Ender Dragon

• Dimensions: Unknown
• No extra metadata

90: Pig

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

91: Sheep

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

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

92: Cow

• Dimensions: 0.9 * 1.3
• No extra metadata

93: Duck

• Dimensions: 0.3 * 0.4
• No extra metadata

94: Squid

• Dimensions: 0.95 * 0.95
• No extra metadata

95: Wolf

• Dimensions: Unknown
• Index 16 (byte): Flags (see below).
• Index 17 (string): Name of player that tamed wolf.
• Index 18 (int): Health.

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

96: Mooshroom?

Suspected to be mooshroom, but currently undocumented

97: Snowman

• Dimensions: Unknown
• No extra metadata

120: Villager

• Dimensions: Unknown
• No extra metadata

Objects

Objects are spawned via 0x17 Add Object/Vehicle

ID	Name	Width	Height
1	Boat	1.5	0.6
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
60	Arrow (projectile)	0.5	0.5
61	Snowball (projectile)	0.25	0.25
62	Egg (projectile)	0.25	0.25
70	Falling Sand	0.98	0.98
71	Falling Gravel	0.98	0.98
90	Fishing Float	0.25?	0.25?

Other

Player entities have dimensions 0.6 * 1.8

Pickups have dimensions 0.25 * 0.25