packets/: packet model + catalogs + wire-format deep-dives
Control-state catalogs (handshake/status/login/config), categorized Play catalog (~182 packets), and deep-dives on the four hard formats: chunk data (paletted containers + light), entity metadata (type registry), slot/structured components, command graph (Brigadier). Sourced from minecraft-data + ViaVersion. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
This commit is contained in:
claude-timemachine
@@ -0,0 +1,111 @@
|
||||
# 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 |
|
||||
Reference in New Issue
Block a user