claude-timemachine
d73c1c9537
8 topical docs (overview, data types, lifecycle, handshake, status/ping, login+encryption, configuration, version-differences) + proxy-forwarding set + 16 per-version release-line docs, sourced from minecraft.wiki, ViaVersion (source + commits), minecraft-data, node-minecraft-protocol, Velocity, BungeeCord. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
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 | TCP framing, packet structure (length-prefixed), the four/five connection states, big picture |
| 01-data-types.md | VarInt/VarLong, String, UUID, Position, NBT, Identifier, arrays, optionals |
| 02-connection-lifecycle.md | State machine handshake→status/login→(configuration)→play, with the per-version transitions |
| 03-handshake.md | The handshake packet; serverAddress-field abuse (Forge FML, BungeeCord, Velocity); SRV records; the protocol-version table |
| 04-status-ping.md | Modern Server List Ping; legacy 1.6− ping (0xFE); the status JSON + favicon |
| 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 | The 1.20.2+ configuration state, registry sync, known-packs (1.20.5+), play↔config re-entry |
| 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/ | What a proxy does; online vs offline mode; BungeeCord legacy forwarding; Velocity modern forwarding; BungeeGuard; Forge/FML |
| versions/ | 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 |
| references.md | Every source: spec pages + which reference repo to read for what |
| 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 for exact files):
- PrismarineJS/node-minecraft-protocol — clean JS impl +
minecraft-dataper-version packet definitions - PaperMC/Velocity — modern forwarding, login flow
- SpigotMC/BungeeCord — legacy forwarding
- 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.