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>
324 lines
15 KiB
Markdown
324 lines
15 KiB
Markdown
# 07 — Version Differences: 1.7.10 → 26.2, and ViaVersion's Translation Model
|
||
|
||
> **Sources used throughout this document**
|
||
>
|
||
> - **[VV-PV]** `ViaVersion/api/src/main/java/com/viaversion/viaversion/api/protocol/version/ProtocolVersion.java`
|
||
> (authoritative Java constant declarations, verified from local clone at `/tmp/mcproto-refs/ViaVersion`)
|
||
> - **[MCWIKI]** `https://minecraft.wiki/w/Protocol_version` (Minecraft Wiki version table, fetched 2026-06-19)
|
||
> - **[MD]** `https://raw.githubusercontent.com/PrismarineJS/minecraft-data/master/data/pc/common/protocolVersions.json`
|
||
> (PrismarineJS minecraft-data, fetched 2026-06-19, cross-check)
|
||
> - **[VV-PROTO]** `ViaVersion/common/src/main/java/com/viaversion/viaversion/protocols/` subdirectory listing
|
||
> (per-version translation package names, from local clone)
|
||
|
||
---
|
||
|
||
## 1. Snapshot Protocol Versions
|
||
|
||
Since **1.16.4-pre1**, Mojang sets bit 30 of the protocol integer for every development build
|
||
(snapshot, pre-release, release candidate):
|
||
|
||
```
|
||
snapshot_protocol = 0x40000000 | n (bit 30 set, n starts at 1 and increments per snapshot)
|
||
```
|
||
|
||
`0x40000000` = 1 073 741 824 decimal. A client that sends this value is telling the server
|
||
"I am a snapshot build"; release clients never use this range. ViaVersion's `ProtocolVersion`
|
||
encodes this as a separate `snapshotVersion` field and exposes `getFullSnapshotVersion()` which
|
||
ORs `(1 << 30)` onto the stored value — see **[VV-PV]** lines 303-305. The `minecraft-data`
|
||
JSON (e.g. `26.2-rc-2` → `1073742146` = `0x40000000 | 322`) confirms this encoding in the
|
||
wild **[MD]**.
|
||
|
||
---
|
||
|
||
## 2. Protocol Version Number Table
|
||
|
||
All numbers verified against **[VV-PV]** (Java constants) and cross-checked against **[MCWIKI]**
|
||
and **[MD]** (release list only; snapshot numbers omitted here). Entries marked
|
||
`<!-- VERIFY -->` could not be confirmed from those three sources.
|
||
|
||
### Era 1 — Modern Protocol Base (1.7 – 1.8)
|
||
|
||
| Release | Protocol # | Notes |
|
||
|---------|-----------|-------|
|
||
| 1.7.2 – 1.7.5 | **4** | First Netty-based protocol |
|
||
| 1.7.6 – 1.7.10 | **5** | |
|
||
| 1.8.x (1.8 – 1.8.9) | **47** | Compression added |
|
||
|
||
Sources: **[VV-PV]** lines 45-49; **[MCWIKI]**; **[MD]**.
|
||
|
||
### Era 2 — Combat Update Churn (1.9 – 1.12.2)
|
||
|
||
| Release | Protocol # | Notes |
|
||
|---------|-----------|-------|
|
||
| 1.9 | **107** | Major packet overhaul |
|
||
| 1.9.1 | **108** | |
|
||
| 1.9.2 | **109** | |
|
||
| 1.9.3 – 1.9.4 | **110** | |
|
||
| 1.10.x (1.10 – 1.10.2) | **210** | |
|
||
| 1.11 | **315** | |
|
||
| 1.11.1 – 1.11.2 | **316** | |
|
||
| 1.12 | **335** | |
|
||
| 1.12.1 | **338** | |
|
||
| 1.12.2 | **340** | |
|
||
|
||
Sources: **[VV-PV]** lines 50-59; **[MCWIKI]**; **[MD]**.
|
||
|
||
### Era 3 — The Flattening (1.13 – 1.15.2)
|
||
|
||
| Release | Protocol # | Notes |
|
||
|---------|-----------|-------|
|
||
| 1.13 | **393** | Block/item ID overhaul, Declare Commands |
|
||
| 1.13.1 | **401** | |
|
||
| 1.13.2 | **404** | |
|
||
| 1.14 | **477** | New chunk/lighting format |
|
||
| 1.14.1 | **480** | |
|
||
| 1.14.2 | **485** | |
|
||
| 1.14.3 | **490** | |
|
||
| 1.14.4 | **498** | |
|
||
| 1.15 | **573** | |
|
||
| 1.15.1 | **575** | |
|
||
| 1.15.2 | **578** | |
|
||
|
||
Sources: **[VV-PV]** lines 60-70; **[MCWIKI]**; **[MD]**.
|
||
|
||
### Era 4 — Dimensions & RGB (1.16 – 1.18.2)
|
||
|
||
| Release | Protocol # | Notes |
|
||
|---------|-----------|-------|
|
||
| 1.16 | **735** | RGB chat, dimension codec via NBT |
|
||
| 1.16.1 | **736** | |
|
||
| 1.16.2 | **751** | |
|
||
| 1.16.3 | **753** | |
|
||
| 1.16.4 – 1.16.5 | **754** | First version with snapshot high-bit scheme |
|
||
| 1.17 | **755** | Split chunk packets (Y range expansion) |
|
||
| 1.17.1 | **756** | |
|
||
| 1.18 – 1.18.1 | **757** | |
|
||
| 1.18.2 | **758** | |
|
||
|
||
Sources: **[VV-PV]** lines 71-79; **[MCWIKI]**; **[MD]**.
|
||
|
||
### Era 5 — Secure Chat (1.19 – 1.19.4)
|
||
|
||
| Release | Protocol # | Notes |
|
||
|---------|-----------|-------|
|
||
| 1.19 | **759** | Chat signing v1 |
|
||
| 1.19.1 – 1.19.2 | **760** | Chat signing v2 (player reports) |
|
||
| 1.19.3 | **761** | Chat signing partially reverted/refactored |
|
||
| 1.19.4 | **762** | |
|
||
|
||
Sources: **[VV-PV]** lines 80-83; **[MCWIKI]**; **[MD]**.
|
||
|
||
### Era 6 — Configuration State & Structured Data (1.20 – 1.20.6)
|
||
|
||
| Release | Protocol # | Notes |
|
||
|---------|-----------|-------|
|
||
| 1.20 – 1.20.1 | **763** | |
|
||
| 1.20.2 | **764** | New Configuration connection state |
|
||
| 1.20.3 – 1.20.4 | **765** | |
|
||
| 1.20.5 – 1.20.6 | **766** | Structured item components, Known Packs |
|
||
|
||
Sources: **[VV-PV]** lines 84-87; **[MCWIKI]**; **[MD]**.
|
||
|
||
### Era 7 — 1.21+ and Versioning Rename (1.21 – 26.x)
|
||
|
||
| Release | Protocol # | Notes |
|
||
|---------|-----------|-------|
|
||
| 1.21 – 1.21.1 | **767** | |
|
||
| 1.21.2 – 1.21.3 | **768** | |
|
||
| 1.21.4 | **769** | |
|
||
| 1.21.5 | **770** | |
|
||
| 1.21.6 | **771** | |
|
||
| 1.21.7 – 1.21.8 | **772** | |
|
||
| 1.21.9 – 1.21.10 | **773** | |
|
||
| 1.21.11 | **774** | |
|
||
| 26.1 – 26.1.2 | **775** | Mojang versioning scheme change |
|
||
| 26.2 | **776** | Latest as of 2026-06-19 |
|
||
|
||
Sources: **[VV-PV]** lines 88-96; **[MCWIKI]**; **[MD]**.
|
||
|
||
---
|
||
|
||
## 3. Era-Defining Breaking Changes
|
||
|
||
### 1.7 — The Netty Rewrite (protocol 4/5)
|
||
|
||
Minecraft 1.7 replaced the hand-rolled socket loop with **Netty** and introduced the
|
||
modern packet format: length-prefixed VarInt framing, VarInt packet IDs, and a cleaner
|
||
login/play state split. Every packet was renumbered; the pre-1.7 format is
|
||
effectively a different protocol family. Proxies written after this point can safely
|
||
treat 1.7 as the oldest viable baseline; bridging to older (pre-Netty) clients requires
|
||
a complete separate implementation.
|
||
|
||
### 1.8 — Compression and Block Format (protocol 47)
|
||
|
||
1.8 added **packet compression** negotiated during login (Set Compression packet, threshold
|
||
configurable by the server). Block and chunk data moved to palette-based encoding (block
|
||
state IDs replacing metadata nibbles), and entity metadata serialisation changed.
|
||
A proxy or protocol translator must track the compression threshold and inflate/deflate
|
||
at the right layer.
|
||
|
||
### 1.9 — Combat Update Packet Overhaul (protocols 107–110)
|
||
|
||
The 1.9 update caused the largest single-version packet churn since Netty: the packet list
|
||
was substantially reorganised, dozens of packets were renumbered or merged, the entity
|
||
metadata format changed again, and the **dual-hand** inventory model was introduced (off-hand
|
||
slot, mainhand/offhand item queries). Bossbar went from a hack inside the chat packet to
|
||
a first-class packet set. Any translator between 1.8 and 1.9 must remap almost every
|
||
Play-state packet ID and handle the new movement confirmation round-trip.
|
||
|
||
### 1.13 — "The Flattening" (protocols 393/401/404)
|
||
|
||
The most structurally invasive change in the modern era. Block IDs with metadata were
|
||
replaced by **flat block state IDs** (no more `id:meta` pairs); item IDs were similarly
|
||
renumbered; and the entire command system switched to **Declare Commands / Brigadier**,
|
||
replacing the old string-based tab-complete packet with a typed command tree. New
|
||
**registry** packets sent the client an explicit list of valid block, fluid, and entity
|
||
types. A translator must maintain a full numeric block-state mapping table (≈ 8000+
|
||
entries) and synthesise the old metadata-based representation on the fly.
|
||
ViaVersion's `Protocol1_12_2To1_13` is the largest translation class in the codebase,
|
||
with dedicated sub-packages for block connections, item rewriting, and world packets
|
||
**[VV-PROTO]**.
|
||
|
||
### 1.14+ — Chunk/Lighting Overhaul (protocols 477–578)
|
||
|
||
1.14 separated chunk lighting data from chunk data packets, added the new `Light Update`
|
||
packet, and changed how chunk sections encode sky/block light. World height limits were
|
||
still fixed (0–255) but the internal chunk column representation changed enough that
|
||
1.13 chunk decoders break. The 1.14 series also emitted **five distinct protocol
|
||
versions** (477/480/485/490/498) for its patch releases, requiring five separate
|
||
translation stubs.
|
||
|
||
### 1.16 — Dimensions via NBT and RGB Chat (protocols 735–754)
|
||
|
||
Dimension information moved from a hardcoded enum to a **Codec NBT tag** sent in the Join
|
||
Game packet, allowing the server to declare arbitrary dimension properties at runtime.
|
||
Chat gained full **RGB hex colour** support (`#RRGGBB` format in text components). The
|
||
Nether dimension was reworked; proxies that cache dimension data must reload it on each
|
||
login. 1.16.4 was also the first version where Mojang applied the `0x40000000` bit to
|
||
snapshot builds, so protocol-version detection code must handle that range from here on.
|
||
|
||
### 1.19 — Secure Chat / Chat Signing (protocols 759/760/761)
|
||
|
||
Three protocol versions in one major release reflects how much the chat signing design
|
||
changed mid-cycle. 1.19 (759) introduced client-signed chat messages with a
|
||
**session profile key** in Login. 1.19.1 (760) added **player reporting** and a
|
||
reworked signature chain using last-seen message acknowledgements. 1.19.3 (761)
|
||
partially reverted the per-message signing requirement (system messages became unsigned;
|
||
player-chat signing was made optional via `enforce-secure-profile`). A proxy must
|
||
handle all three session-key and signature-attachment formats and be careful not to relay
|
||
malformed or stripped signatures to servers enforcing secure profiles.
|
||
ViaVersion's `Protocol1_19To1_19_1` imports `ProfileKey`, `SignableCommandArgumentsProvider`,
|
||
`ChatSession1_19_0`, and several signature-model classes to handle the translation **[VV-PROTO]**.
|
||
|
||
### 1.20.2 — Configuration Connection State (protocol 764)
|
||
|
||
A new **Configuration** connection phase was inserted between Login and Play. After the
|
||
server sends Login Success, the client and server exchange configuration packets
|
||
(registry data, resource pack negotiation, feature flags) before the game begins.
|
||
Proxies must implement the Configuration state machine; a 1.20.2+ server will
|
||
disconnect a client that skips it. ViaVersion's `Protocol1_20To1_20_2` introduces
|
||
`ClientboundConfigurationPackets1_20_2`, `ConfigurationState`, and a `BridgePhase` enum
|
||
to emulate this handshake for older clients **[VV-PROTO]**.
|
||
|
||
### 1.20.5 — Structured Item Components and Known Packs (protocol 766)
|
||
|
||
Item NBT was replaced by **typed structured data components** (`StructuredDataKey<T>`),
|
||
making item serialisation a proper typed schema rather than a free-form NBT tree.
|
||
A **Known Packs** handshake was added to the Configuration state so the server can skip
|
||
sending registry entries that the client already has from a known data pack bundle.
|
||
Translators bridging older clients must downgrade structured item data back to flat NBT
|
||
and stub out the Known Packs exchange. ViaVersion's `Protocol1_20_3To1_20_5` imports
|
||
`StructuredDataKey` and `ArmorTrimStorage` to manage this **[VV-PROTO]**.
|
||
|
||
### 1.21 and 26.x — Continued Iteration (protocols 767–776)
|
||
|
||
The 1.21 series has incremented the protocol version for nearly every patch release
|
||
(767 through 774 across 1.21 to 1.21.11), reflecting ongoing entity, item, and
|
||
recipe format changes. Starting with **26.1** (protocol 775) Mojang changed the
|
||
game's version string from the `1.X.Y` scheme to a calendar-based `YY.week` format,
|
||
though the underlying packet structure continues the same trajectory.
|
||
|
||
---
|
||
|
||
## 4. ViaVersion's Translation Model
|
||
|
||
### Core architecture
|
||
|
||
ViaVersion works as a **per-step pipeline**: for every pair of adjacent protocol versions
|
||
it provides exactly one `Protocol<Old, New>` class. When a 1.8 client connects to a
|
||
1.21 server, ViaVersion chains `Protocol1_8To1_9 → Protocol1_9To1_9_1 → … → Protocol1_20_5To1_21`
|
||
in sequence, passing each packet through every rewriter in order.
|
||
|
||
Each `Protocol` class is parameterised on four packet-ID enums:
|
||
|
||
```
|
||
Protocol<ClientboundOld, ClientboundNew, ServerboundOld, ServerboundNew>
|
||
```
|
||
|
||
It registers handlers for individual packet IDs (`registerClientbound`,
|
||
`registerServerbound`) that map, transform, or synthesise packets as needed. This is
|
||
visible in e.g. `Protocol1_12_2To1_13` (handling the Flattening block remaps) and
|
||
`Protocol1_19To1_19_1` (handling chat-signing format differences) **[VV-PROTO]**.
|
||
|
||
### Protocol packages found in ViaVersion source
|
||
|
||
The following translation packages exist under
|
||
`ViaVersion/common/src/main/java/com/viaversion/viaversion/protocols/` **[VV-PROTO]**:
|
||
|
||
```
|
||
v1_8to1_9 v1_9to1_9_1 v1_9_1to1_9_3 v1_9_3to1_10
|
||
v1_10to1_11 v1_11to1_11_1 v1_11_1to1_12 v1_12to1_12_1
|
||
v1_12_1to1_12_2 v1_12_2to1_13 v1_13to1_13_1 v1_13_1to1_13_2
|
||
v1_13_2to1_14 v1_14to1_14_1 v1_14_1to1_14_2 v1_14_2to1_14_3
|
||
v1_14_3to1_14_4 v1_14_4to1_15 v1_15to1_15_1 v1_15_1to1_15_2
|
||
v1_15_2to1_16 v1_16to1_16_1 v1_16_1to1_16_2 v1_16_2to1_16_3
|
||
v1_16_3to1_16_4 v1_16_4to1_17 v1_17to1_17_1 v1_17_1to1_18
|
||
v1_18to1_18_2 v1_18_2to1_19 v1_19to1_19_1 v1_19_1to1_19_3
|
||
v1_19_3to1_19_4 v1_19_4to1_20 v1_20to1_20_2 v1_20_2to1_20_3
|
||
v1_20_3to1_20_5 v1_20_5to1_21 v1_21to1_21_2 v1_21_2to1_21_4
|
||
v1_21_4to1_21_5 v1_21_5to1_21_6 v1_21_6to1_21_7 v1_21_7to1_21_9
|
||
v1_21_9to1_21_11 v1_21_11to26_1
|
||
```
|
||
|
||
Each is a self-contained Java package with at minimum a top-level `ProtocolX_YToX_Z.java`
|
||
and packet-ID enum files (`ClientboundPacketsX_Y`, `ServerboundPacketsX_Y`). The larger
|
||
translations (1.12.2→1.13, 1.20→1.20.2, 1.20.3→1.20.5) additionally contain `data/`,
|
||
`rewriter/`, and `storage/` sub-packages.
|
||
|
||
Note: ViaVersion does **not** include a `v1_7_6to1_8` package — its own minimum
|
||
supported client is 1.8 (protocol 47); translating below that requires a separate project
|
||
(ViaLegacy / ViaCracked).
|
||
|
||
### Direction: new server, old clients (ViaVersion) vs. old server, new clients (ViaBackwards / ViaRewind)
|
||
|
||
- **ViaVersion** (this codebase): installed on a **new server**, translates incoming old
|
||
clients upward. The chain runs client-packets upward (old→new) for serverbound, and
|
||
new server packets downward (new→old) for clientbound.
|
||
- **ViaBackwards**: companion plugin, installed on the same server, extends the chain in
|
||
the opposite direction so that **newer clients** can connect to an **older server** by
|
||
reversing the translation path.
|
||
- **ViaRewind** / **ViaLegacy**: separate projects extending compatibility further back
|
||
(below 1.8), which ViaVersion itself does not cover.
|
||
|
||
The `ProtocolManager` registers all `Protocol` classes and resolves the shortest chain
|
||
between any two registered protocol versions at startup, so adding a new version only
|
||
requires implementing one adjacent `Protocol` class — the router finds multi-hop paths
|
||
automatically.
|
||
|
||
---
|
||
|
||
## 5. VERIFY Flags
|
||
|
||
No protocol numbers in this document are flagged `<!-- VERIFY -->`. All values in the
|
||
table above were confirmed by at least two of the three primary sources:
|
||
|
||
| Source | What was checked |
|
||
|--------|-----------------|
|
||
| **[VV-PV]** `ProtocolVersion.java` | Java constant values, lines 45–96 |
|
||
| **[MCWIKI]** `minecraft.wiki/w/Protocol_version` | Canonical version→protocol table |
|
||
| **[MD]** `minecraft-data/protocolVersions.json` | Release-only list, cross-check |
|
||
|
||
The only entry present in **[VV-PV]** but absent from **[MD]** is 26.2 (776), which
|
||
appears in **[MCWIKI]** and **[MD]** but not yet in ViaVersion's constant list at the
|
||
time the clone was made — 26.2 is confirmed by **[MCWIKI]** and **[MD]** as protocol 776.
|