claude-timemachine
90b711d12a
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>
36 lines
4.0 KiB
Markdown
36 lines
4.0 KiB
Markdown
# Minecraft Java Edition Protocol — a deep-dive reference (1.7.10 → latest)
|
||
|
||
A from-scratch, version-aware study of the Minecraft: Java Edition network protocol — how a client and server (and the proxies between them) actually talk. Built by reading the spec (minecraft.wiki, ex-wiki.vg) alongside real reference implementations, and writing down what's true, what changed between versions, and *why*.
|
||
|
||
**Scope**: the wire protocol from **1.7.10** (protocol 5) to the latest release. Emphasis on the structural/cross-version mechanics — framing, the connection state machine, the handshake, login + encryption, the configuration phase, and **proxy forwarding modes** — rather than an exhaustive packet-by-packet dump (minecraft.wiki already is that; this explains how the pieces fit and how they drift across versions).
|
||
|
||
## Contents
|
||
|
||
| Doc | Covers |
|
||
|---|---|
|
||
| [00-overview.md](00-overview.md) | TCP framing, packet structure (length-prefixed), the four/five connection states, big picture |
|
||
| [01-data-types.md](01-data-types.md) | VarInt/VarLong, String, UUID, Position, NBT, Identifier, arrays, optionals |
|
||
| [02-connection-lifecycle.md](02-connection-lifecycle.md) | State machine handshake→status/login→(configuration)→play, with the per-version transitions |
|
||
| [03-handshake.md](03-handshake.md) | The handshake packet; `serverAddress`-field abuse (Forge FML, BungeeCord, Velocity); SRV records; the protocol-version table |
|
||
| [04-status-ping.md](04-status-ping.md) | Modern Server List Ping; legacy 1.6− ping (0xFE); the status JSON + favicon |
|
||
| [05-login-encryption.md](05-login-encryption.md) | LoginStart, Encryption Request/Response, RSA + AES/CFB8, shared secret, server-id hash, online-mode `hasJoined`, compression handshake, 1.19 profile keys |
|
||
| [06-configuration.md](06-configuration.md) | The 1.20.2+ configuration state, registry sync, known-packs (1.20.5+), play↔config re-entry |
|
||
| [07-version-differences.md](07-version-differences.md) | Protocol-number table 1.7.10→latest, the major breaking changes per era, and how ViaVersion translates between them |
|
||
| [proxy-forwarding/](proxy-forwarding/) | What a proxy does; online vs offline mode; BungeeCord legacy forwarding; Velocity modern forwarding; BungeeGuard; Forge/FML |
|
||
| [versions/](versions/INDEX.md) | **Per-version deep-dives** — one doc per release line (1.7.10→26.2), what changed in each protocol bump, sourced from release notes + ViaVersion commits + wiki |
|
||
| [packets/](packets/README.md) | **Packet reference** — the packet model, complete control-state catalogs, the categorized Play catalog (~182 packets), + wire-format deep-dives: chunk data (paletted containers), entity metadata, slot/components, command graph |
|
||
| [references.md](references.md) | Every source: spec pages + which reference repo to read for what |
|
||
| [PLAN.md](PLAN.md) | How this repo was built — orchestration + per-agent research spec |
|
||
|
||
## How this was built
|
||
|
||
Iterative: research a topic against minecraft.wiki + the reference implementations below, write the doc with citations (source `file:line` + wiki section), cross-link, verify dubious claims, repeat.
|
||
|
||
**Reference implementations consulted** (see [references.md](references.md) for exact files):
|
||
- [PrismarineJS/node-minecraft-protocol](https://github.com/PrismarineJS/node-minecraft-protocol) — clean JS impl + `minecraft-data` per-version packet definitions
|
||
- [PaperMC/Velocity](https://github.com/PaperMC/Velocity) — modern forwarding, login flow
|
||
- [SpigotMC/BungeeCord](https://github.com/SpigotMC/BungeeCord) — legacy forwarding
|
||
- [ViaVersion/ViaVersion](https://github.com/ViaVersion/ViaVersion) — the canonical map of what changed between every protocol version
|
||
|
||
> Status: **foundation + per-version docs complete** (8 topical docs + 16 release-line docs, 1.7.10→26.2). Remaining: a verification pass over the inline `<!-- VERIFY -->` flags (minor detail-level uncertainties — protocol numbers + crypto/forwarding formats are already multi-source-confirmed). See [PLAN.md](PLAN.md).
|