# 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](../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/](../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:

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