Timemachine/minecraft_protocol
2
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

minecraft_protocol: foundation + per-version protocol docs 1.7.10->26.2

Browse Source 
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>
This commit is contained in:
claude-timemachine
2026-06-19 14:15:32 +02:00
commit d73c1c9537
35 changed files with 8894 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+34
View File
@@ -0,0 +1,34 @@
# 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 |
| [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).