Entity Metadata & Synced Data

Minecraft synchronizes persistent entity visual states, animation flags, poses, and properties via Entity Metadata (historically called DataWatchers in Java Edition and Actor Data in Bedrock Edition).

Instead of transmitting full state packets whenever an entity crouches, catches fire, or takes damage, the server broadcasts compact metadata updates to nearby observers.

---

Edition Comparison

Feature	Minecraft: Java Edition	Minecraft: Bedrock Edition
Packet Name	CSetEntityMetadata (SET_ENTITY_DATA)	CSetActorData (Packet ID 39)
Storage Structure	TrackedData list terminating with 0xFF	SyncedActorDataList (HashMap<u32, MetadataValue>)
Key Type	Index (u8) mapped to typed MetaDataType	Enum keys (entity_data_key::*)
Flags	Bitfield byte (fire, crouching, sprinting, glowing)	Bitfield int64 (entity_data_flag::*)
Dynamic Properties	N/A (baked into tracked indices)	PropertySyncData (client/server sync)
Crate Location	crates/pumpkin-protocol/src/java/client/play/entity_metadata.rs	crates/pumpkin-protocol/src/bedrock/client/set_actor_data.rs

---

1. Java Edition: CSetEntityMetadata

In Java Edition, entity metadata consists of numbered index entries. Each entry defines an index, a MetaDataType ID, and the encoded value. The list terminates with a single 0xFF byte.

Key Index Hierarchy

Entity metadata follows an object-oriented inheritance model:

1. Entity (Base):
   • 0: State bitfield (flags: bit 0 = on fire, bit 1 = crouching, bit 3 = sprinting, bit 5 = invisible, bit 6 = glowing).
   • 1: Air supply (VarInt).
   • 2: Custom name (optional TextComponent).
   • 3: Custom name visible (bool).
   • 4: Silent (bool).
   • 5: No gravity (bool).
   • 6: Pose (Standing, FallFlying, Sleeping, Swimming, SpinAttack, Crouching, Dying).
2. LivingEntity (extends Entity):
   • 8: Hand states (using item, active hand).
   • 9: Health (f32).
   • 10: Potion effect ambient color.
3. Player (extends LivingEntity):
   • Additional hearts, skin customization bitmask, main hand indicator.

Sending Metadata Updates in Pumpkin

Pumpkin encodes entity metadata in pumpkin-protocol:

use pumpkin_protocol::VarInt;
use pumpkin_protocol::java::client::play::CSetEntityMetadata;

// Construct metadata update for entity with ID 42
let packet = CSetEntityMetadata::new(
    VarInt(entity.entity_id),
    serialized_metadata_bytes,
);

// Broadcast to chunk observers
world.broadcast_packet_all(&packet).await;

---

2. Bedrock Edition: CSetActorData

Bedrock Edition uses CSetActorData (packet(39)), storing properties in a dictionary mapping u32 keys to strongly-typed MetadataValue variants.

Key & Flag Constants

Bedrock exposes flags as a 64-bit integer bitfield under entity_data_key::FLAGS:

• entity_data_flag::ON_FIRE (0): Entity is burning.
• entity_data_flag::SNEAKING (1): Player is sneaking.
• entity_data_flag::RIDING (2): Entity is mounted on a vehicle.
• entity_data_flag::SPRINTING (3): Player is sprinting.
• entity_data_flag::USING_ITEM (4): Player is actively charging a bow, eating food, or using a shield.
• entity_data_flag::INVISIBLE (5): Entity is invisible.
• entity_data_flag::GLOWING (26): Entity has the glowing effect outline.

Constructing and Updating Actor Data in Pumpkin

In crates/pumpkin/src/entity/living.rs:

use pumpkin_protocol::bedrock::client::set_actor_data::{
    CSetActorData, MetadataValue, PropertySyncData, SyncedActorDataList,
    entity_data_flag, entity_data_key,
};

let mut actor_data = SyncedActorDataList::new();

// Set entity flags (e.g. actively using an item)
let mut flags: i64 = 0;
if is_using_item {
    flags |= 1i64 << entity_data_flag::USING_ITEM;
}
actor_data.set(entity_data_key::FLAGS, MetadataValue::Int64(flags));

// Set air supply
actor_data.set(entity_data_key::AIR_SUPPLY, MetadataValue::Short(air as i16));

// Set custom name tag
actor_data.set(entity_data_key::NAME, MetadataValue::String(name));

let packet = CSetActorData {
    target_runtime_id: VarULong(entity_id),
    actor_data,
    synced_properties: PropertySyncData::default(),
    tick: VarULong(current_tick),
};

client.try_enqueue_client_packet(&packet);

---

Multi-Version Compatibility

Because Mojang frequently shifts metadata indices between Minecraft releases, pumpkin-protocol leverages translation tables from pumpkin-data:

• For Java Edition, pumpkin_data::meta_data_type::MetaDataType remaps indices dynamically based on the client's JavaMinecraftVersion.
• For Bedrock Edition, SyncedActorDataList validates keys against the active Bedrock protocol version to prevent client crashes.