minecraft_protocol/packets/README.md

Packets — Model & Navigation

Scope: Java Edition, 1.21.1 baseline (protocol 773) unless noted. Sources: minecraft-data/data/pc/1.21.1/protocol.json · minecraft.wiki/w/Java_Edition_protocol/Packets

---

1. Packet Framing Recap

Every packet is length-prefixed over TCP. Two modes exist:

Uncompressed (before Set Compression arrives):

[Length: VarInt] [Packet ID: VarInt] [Payload: bytes...]

Compressed (after Set Compression; applies for rest of session):

[Packet Length: VarInt] [Data Length: VarInt] [Packet ID + Payload: zlib or raw]

Data Length = 0 means the inner payload was not compressed (below threshold). When Data Length > 0 it is the uncompressed size of (Packet ID + Payload).

Full framing spec with code citations: ../00-overview.md §2.

---

2. Packet ID Scoping

Packet IDs are scoped by BOTH connection state AND traffic direction.

The same byte value 0x00 identifies a completely different packet in each slot:

State	Direction	0x00 packet
Handshaking	Serverbound	Handshake
Status	Serverbound	Status Request
Status	Clientbound	Status Response
Login	Serverbound	Login Start
Login	Clientbound	Disconnect (Login)
Configuration	Serverbound	Client Information
Configuration	Clientbound	Cookie Request
Play	Serverbound	Confirm Teleportation
Play	Clientbound	Bundle Delimiter

A parser must track the current state and which peer sent the packet before it can decode the ID. State transitions are driven by specific packets (Handshake → Status/Login, Login Acknowledged → Configuration, Finish Configuration → Play).

---

3. ID Instability Across Versions

Packet IDs within a state/direction namespace are not stable between protocol versions. When Mojang adds or removes packets, every subsequent ID in that list shifts.

Examples:

• Configuration state did not exist before 1.20.2 (protocol 764). All its IDs are new.
• In 1.20.5 (protocol 766), Cookie/Transfer/Store-Cookie/Resource-Pack-Pop/Resource-Pack-Push were added to Configuration, shifting existing IDs upward.
• Login gained Cookie Request (CB 0x05) and Cookie Response (SB 0x04) in 1.20.5.
• Login Acknowledged (SB 0x03) was added in 1.20.2.

For per-version ID tables, see ../versions/ and the authoritative machine-readable source below.

---

4. Authoritative Per-Version Packet Definitions

minecraft-data provides a complete, machine-readable protocol schema for every supported version:

/tmp/mcproto-refs/minecraft-data/data/pc/<version>/protocol.json

Structure per state/direction:

{
  "<state>": {
    "toClient": {
      "types": {
        "packet": ["container", [
          { "name": "name", "type": ["mapper", { "type": "varint", "mappings": { "0x00": "..." } }] },
          { "name": "params", "type": ["switch", { "compareTo": "name", "fields": { "...": "packet_..." } }] }
        ]],
        "packet_<name>": ["container", [ ... field defs ... ]]
      }
    }
  }
}

The mappings object is the ID→name table. The packet_<name> types give field-level detail.

---

5. Navigation

Document	Contents
catalog-control-states.md	Complete packet tables for Handshaking, Status, Login, Configuration (1.21.1)
catalog-play.md	Play-state packet index (high count — separate file)
format-chunk-data.md	Chunk Data & Update Light packet payload format
format-entity-metadata.md	Entity metadata encoding, type IDs, value formats
format-slot-and-components.md	Item slot encoding; data component system (1.20.5+)
format-command-graph.md	Declare Commands packet graph encoding
../versions/	Per-version delta notes; ID shift history
../00-overview.md	Transport, framing, compression, encryption
../03-handshake.md	Handshake packet deep-dive
../04-status-ping.md	Status/ping flow detail
../05-login-encryption.md	Login + encryption flow detail
../06-configuration.md	Configuration state detail