# References & sources

Everything in this repo is grounded in the spec + real reference implementations, cited inline as `path:line` / wiki-URL + fetch date. This is the catalog of what was used and **which source to read for what**.

## Spec of record — minecraft.wiki (formerly wiki.vg)

wiki.vg was merged into **minecraft.wiki** in 2024; the protocol documentation lives under the Java Edition protocol pages.

| Page | Use |
|---|---|
| [`/w/Java_Edition_protocol`](https://minecraft.wiki/w/Java_Edition_protocol) | the live protocol: packet format, data types, per-state packet lists |
| [`/w/Protocol_version`](https://minecraft.wiki/w/Protocol_version) | the authoritative version→protocol-number table |
| `/w/Java_Edition_protocol/Server_List_Ping` | modern SLP + legacy `0xFE` ping |
| `/w/Java_Edition_protocol/Protocol_Encryption` | the AES/RSA encryption handshake |
| `/w/Java_Edition_<version>` | per-version **release notes** (gameplay + technical) |

> Historical per-version protocol pages are spotty on minecraft.wiki (some archive URLs 404). For exact per-version packet layouts we relied on **minecraft-data** + **ViaVersion** instead, which are versioned by construction.

## Reference implementations

Cloned to `/tmp/mcproto-refs/` during the build (ephemeral — re-clone to reproduce). Read for:

| Repo | Read for | Key files |
|---|---|---|
| [node-minecraft-protocol](https://github.com/PrismarineJS/node-minecraft-protocol) | clean reference impl of framing, encryption, ping, states | `src/states.js`, `src/transforms/encryption.js`, `src/client/encrypt.js`, `src/ping.js`, `src/transforms/framing.js`, `src/transforms/compression.js` |
| [minecraft-data](https://github.com/PrismarineJS/minecraft-data) | **per-version `protocol.json`** — authoritative packet IDs + field types per version (the diff source for the version docs) | `data/pc/<version>/protocol.json`, `data/pc/<version>/version.json`, `data/pc/common/protocolVersions.json` |
| [ViaVersion](https://github.com/ViaVersion/ViaVersion) | **what changed between adjacent versions** + the commit history that implemented it | `api/.../protocol/version/ProtocolVersion.java` (version constants), `common/.../protocols/v<X>to<Y>/` (per-step translation: `Protocol*.java`, `Clientbound/ServerboundPackets*.java`, `rewriter/`, `data/`), `git log -- <package>` |
| [Velocity](https://github.com/PaperMC/Velocity) | modern forwarding, login flow, state registry | `proxy/.../connection/PlayerDataForwarding.java` (the HMAC forwarding payload), `connection/VelocityConstants.java`, `connection/backend/LoginSessionHandler.java`, `protocol/packet/EncryptionRequest/ResponsePacket.java`, `protocol/StateRegistry.java`, `connection/forge/legacy/LegacyForgeConstants.java` |
| [BungeeCord](https://github.com/SpigotMC/BungeeCord) | legacy IP forwarding format | `proxy/.../connection/InitialHandler.java` (handshake parse), `ServerConnector.java` (the `\0`-delimited forward write), `forge/ForgeConstants.java` |

## Related projects (named, not cloned)

- **ViaBackwards** — extends ViaVersion so *newer* clients reach *older* servers (reverse direction).
- **ViaRewind** / **ViaLegacy** — compatibility below ViaVersion's 1.8 floor (down to 1.7.x and older release/beta protocols).
- **ViaForge** — Forge/FML handshake handling across versions.
- **BungeeGuard** (lucko) — token hardening of legacy forwarding.
- **Waterfall** — BungeeCord fork (now largely superseded by Velocity).

## Citation conventions in this repo

- Reference-impl facts: `repo/path/File.ext:line`.
- ViaVersion change-provenance: the package path + `git log` commit subject/hash.
- Spec facts: the minecraft.wiki URL + fetch date (`2026-06-19`).
- Anything not confirmable from the above carries an inline `<!-- VERIFY -->` flag (see [PLAN §3 Phase 4](PLAN.md) — the open-flag resolution pass).