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

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>

versions/1.21.md

@@ -0,0 +1,347 @@
+# Java Edition 1.21.x — "Tricky Trials" and the Long Patch Series
+
+**Protocol numbers:** 767 (1.21/1.21.1) · 768 (1.21.2/1.21.3) · 769 (1.21.4) · 770 (1.21.5) · 771 (1.21.6) · 772 (1.21.7/1.21.8) · 773 (1.21.9/1.21.10) · 774 (1.21.11)
+
+**Release span:** June 13, 2024 (1.21) — December 9, 2025 (1.21.11) — 8 distinct protocol versions across 11 game releases.
+
+Sources:
+- MCWIKI: `https://minecraft.wiki/w/Java_Edition_1.21[.X]` (fetched 2026-06-19)
+- VV: `/tmp/mcproto-refs/ViaVersion/common/src/main/java/com/viaversion/viaversion/protocols/v1_20_5to1_21/` … `v1_21_9to1_21_11/` (Protocol*.java + packet enums)
+- VV-LOG: `git -C /tmp/mcproto-refs/ViaVersion log --oneline -- common/.../protocols/<pkg>` (fetched 2026-06-19)
+- MD: `/tmp/mcproto-refs/minecraft-data/data/pc/1.21[.x]/version.json`
+
+---
+
+## Headline
+
+1.21 "Tricky Trials" (June 2024) was the major combat/adventure update: trial chambers, breeze mob, mace weapon, wind charge, crafter block, copper and tuff block variants, four new status effects. Patch releases after it were unusually numerous — 10 patches over 18 months spanning the "Wild West" (1.21.2: bundles), "Winter Drop" (1.21.4: pale garden/creaking), animal variants (1.21.5), "Chase the Skies" (1.21.6: happy ghasts, dialog system), "Copper Age" (1.21.9: copper golem/equipment), and "Mounts of Mayhem" (1.21.11: spears, nautilus, dimension attribute overhaul). Each sub-update bumped the protocol, producing 8 distinct wire versions inside a single major release line.
+
+---
+
+## Protocol bump summary
+
+| Protocol | MC versions | Released | Key protocol change |
+|---|---|---|---|
+| 767 | 1.21, 1.21.1 | 2024-06-13, 2024-08-08 | First 1.21 wire (attribute UUID→ID remap, `PROJECTILE_POWER` scalar) |
+| 768 | 1.21.2, 1.21.3 | 2024-10-22, 2024-10-23 | Major: `ENTITY_POSITION_SYNC` + `MOVE_MINECART_ALONG_TRACK` new; serverbound `CLIENT_TICK_END` + `BUNDLE_ITEM_SELECTED`; full item component rebuild; new entity types (Salmon sizes, etc.) |
+| 769 | 1.21.4 | 2024-12-03 | `PICK_ITEM` split into `PICK_ITEM_FROM_BLOCK`/`PICK_ITEM_FROM_ENTITY`; `LEVEL_PARTICLES` gets `always_show` field; `CUSTOM_MODEL_DATA` format extended (`1_21_4`); `PROFILE_ACTIONS_ENUM` gains "show hat" bit |
+| 770 | 1.21.5 | 2025-03-25 | `ADD_EXPERIENCE_ORB` removed (merged into `ADD_ENTITY`); `PLAYER_ROTATION` packet added; `PLAYER_CHAT` gets message-index prefix; serverbounds: `SET_TEST_BLOCK` + `TEST_INSTANCE_BLOCK_ACTION` (test framework); `PLAYER_LOADED` new; large item component churn (`UNBREAKABLE`, `ENCHANTMENTS`, `ATTRIBUTE_MODIFIERS`, `EQUIPPABLE`, `INSTRUMENT`, `JUKEBOX_PLAYABLE`, `TRIM`, many variants bump to `1_21_5`) |
+| 771 | 1.21.6 | 2025-06-17 | Dialog system: `CLEAR_DIALOG` + `SHOW_DIALOG` new (play + config); `CUSTOM_CLICK_ACTION` new serverbound (play + config); `TRACKED_WAYPOINT` new; `CHANGE_DIFFICULTY` changes type (unsigned byte → varint); `CHANGE_GAME_MODE` new serverbound; sneak/shift actions removed from `PLAYER_COMMAND` (now absorbed into `PLAYER_INPUT`); `ATTRIBUTE_MODIFIERS` → `1_21_6`, `EQUIPPABLE` → `1_21_6` |
+| 772 | 1.21.7, 1.21.8 | 2025-06-30, 2025-07-17 | Incremental: entity/item data remapping only (block/item ID changes); no new packet types; 1.21.8 was graphics bug-fix only |
+| 773 | 1.21.9, 1.21.10 | 2025-09-30, 2025-10-07 | `ADD_ENTITY` velocity field type changed (short×3 → `LOW_PRECISION_VECTOR`); `SET_ENTITY_MOTION` same; `PLAYER_ROTATION` gets "relative" boolean fields; four new `DEBUG_*` packets (`DEBUG_BLOCK_VALUE`, `DEBUG_CHUNK_VALUE`, `DEBUG_ENTITY_VALUE`, `DEBUG_EVENT`); `GAME_EVENT_TEST_HIGHLIGHT_POS` new; `EXPLODE` restructured (radius+count fields moved to `PROJECTILE_POWER`); config: `CODE_OF_CONDUCT` added; copper golem entity + copper equipment block/item IDs |
+| 774 | 1.21.11 | 2025-12-09 | `HORSE_SCREEN_OPEN` → `MOUNT_SCREEN_OPEN` rename; new entity types (`zombie_nautilus`, new mounts); `zombie_nautilus_variant` + `timeline` registries injected at FINISH_CONFIGURATION; massive `dimension_type` field migration (many fields → `attributes` NBT compound); `worldgen/biome` similarly gains `attributes`; new item components: `ATTACK_RANGE`, `USE_EFFECTS`, `MINIMUM_ATTACK_CHARGE`, `DAMAGE_TYPE`, `PIERCING_WEAPON`, `KINETIC_WEAPON`, `SWING_ANIMATION`, `ZOMBIE_NAUTILUS_VARIANT` |
+
+---
+
+## 767 — 1.21 / 1.21.1 (June 13 / August 8, 2024)
+
+### Gameplay headline
+Tricky Trials: trial chambers, breeze mob, mace+heavy core, wind charge, crafter block, copper/tuff variant blocks, four status effects (Wind Charged, Weaving, Oozing, Infested). First release requiring 64-bit OS and Java 21+. [MCWIKI 1.21](https://minecraft.wiki/w/Java_Edition_1.21)
+
+**1.21.1** hotfixed two security exploits (update suppression block-entity swap; server crash via malicious command-completion target selector causing stack exhaustion) plus two gameplay bugs. Same protocol 767. Servers running 1.21.1 are compatible with 1.21 clients. [MCWIKI 1.21.1](https://minecraft.wiki/w/Java_Edition_1.21.1)
+
+### Protocol changes (766→767)
+VV package: `v1_20_5to1_21/` ([`Protocol1_20_5To1_21.java`](/tmp/mcproto-refs/ViaVersion/common/src/main/java/com/viaversion/viaversion/protocols/v1_20_5to1_21/Protocol1_20_5To1_21.java))
+
+**Play state — clientbound (0x00–0x7B):** Packet set identical in count/IDs to 1.20.5 (`ClientboundPackets1_21` enum ends at `SERVER_LINKS` 0x7B = 124 entries). Notable: `PROJECTILE_POWER` (0x79) already existed as of 1.20.5 but its payload changed — 1.21 converts the separate x/y/z doubles (three fields) into a single `acceleration_power` scalar (magnitude of the velocity vector). VV does this inline: `Protocol1_20_5To1_21.java:registerPackets()` reads the three doubles, computes `sqrt(x²+y²+z²)`, writes one double. [VV `Protocol1_20_5To1_21.java:registerPackets()`]
+
+**Attribute modifiers:** UUID-keyed modifiers in `UPDATE_ATTRIBUTES` replaced by string IDs. VV maps UUID→string via `AttributeModifierMappings1_21`. Bidirectional mapping: server sends string IDs, old clients need UUIDs, VV translates. [VV `Protocol1_20_5To1_21.java:registerPackets()`, `AttributeModifierMappings1_21`]
+
+**Chat type holder:** `DISGUISED_CHAT` and `PLAYER_CHAT` chat-type field changed from plain varint to `Holder<ChatType>` (inline or registry reference). VV wraps the varint into `ChatType.TYPE` holder. [VV `Protocol1_20_5To1_21.java:registerPackets()`]
+
+**Item components:** The 1.20.5 component set carries forward. VV's `VersionedTypes.V1_21.structuredData` filler enumerates which components exist at this version — all keys use `1_20_5`-suffixed variants except `FOOD1_21`, `JUKEBOX_PLAYABLE1_21`, `ATTRIBUTE_MODIFIERS1_21`. [VV `Protocol1_20_5To1_21.java:onMappingDataLoaded()`]
+
+**New entity tags:** `blocks_wind_charge_explosions` (block), several entity tags (`can_turn_in_boats`, `deflects_projectiles`, `immune_to_infested`, `immune_to_oozing`, `no_anger_from_wind_charge`). Enchantment tags added (`curse`, `double_trade_price`, `in_enchanting_table`, etc.). [VV `Protocol1_20_5To1_21.java:onMappingDataLoaded()`]
+
+---
+
+## 768 — 1.21.2 / 1.21.3 (October 22 / October 23, 2024)
+
+### Gameplay headline
+Bundles (dyeable, store up to 64 mixed items), new banner patterns (field masoned, bordure indented). Experimental content: Minecart Improvements, Redstone Experiments, Winter Drop (pale garden biome, creaking mob) gated behind feature flags. Significant ender pearl chunk-loading change. [MCWIKI 1.21.2](https://minecraft.wiki/w/Java_Edition_1.21.2)
+
+**1.21.3** hotfixed salmon size regression (small salmon incorrectly downsized on world load) and Realms resource-pack failure. Same protocol 768. [MCWIKI 1.21.3](https://minecraft.wiki/w/Java_Edition_1.21.3)
+
+MD confirms: `data/pc/1.21.3/version.json` = `768`.
+
+### Protocol changes (767→768)
+VV package: `v1_21to1_21_2/` ([`Protocol1_21To1_21_2.java`](/tmp/mcproto-refs/ViaVersion/common/src/main/java/com/viaversion/viaversion/protocols/v1_21to1_21_2/Protocol1_21To1_21_2.java))
+
+This is the most substantial bump in the 1.21 line.
+
+#### New clientbound play packets
+- **`ENTITY_POSITION_SYNC` (0x20):** New packet for authoritative entity position sync (replaces the indirect position-via-teleport path for most entities). All subsequent packet IDs shift up by 1. [VV `ClientboundPackets1_21_2.java:0x20`]
+- **`MOVE_MINECART_ALONG_TRACK` (0x31):** New dedicated minecart movement packet for the experimental Minecart Improvements feature. [VV `ClientboundPackets1_21_2.java:0x31`]
+- **`SET_CURSOR_ITEM` (0x5A):** Sends the item on the cursor (held item in inventory GUI). Was previously implicit. [VV `ClientboundPackets1_21_2.java:0x5A`]
+- **`SET_HELD_SLOT` (0x63):** Replaces `SET_CARRIED_ITEM` rename. [VV `ClientboundPackets1_21_2.java:0x63`]
+- **`SET_PLAYER_INVENTORY` (0x66):** Sends a specific slot of the player inventory. [VV `ClientboundPackets1_21_2.java:0x66`]
+
+Total play clientbound count grows from 124 (0x7B) to 131 (0x82).
+
+#### New serverbound play packets
+- **`BUNDLE_ITEM_SELECTED` (0x02):** Client reports which item inside a bundle was selected. VV cancels this (no equivalent in 1.21). [VV `Protocol1_21To1_21_2.java:cancelServerbound()`]
+- **`CLIENT_TICK_END` (0x0B):** Client sends at end of each tick. VV cancels. [VV `Protocol1_21To1_21_2.java:cancelServerbound()`]
+
+#### Packet field changes
+- **`LOGIN_FINISHED` (login state):** `strict_error_handling` boolean field removed. VV reads and discards it. [VV `Protocol1_21To1_21_2.java:registerPackets()`]
+- **`SET_TIME`:** `doDaylightCycle` was encoded as negative day-time; now explicit `doDaylightCycle: boolean` field added. VV converts the sign-encoding to explicit field. [VV `Protocol1_21To1_21_2.java:registerPackets()`]
+- **`PLAYER_INFO_UPDATE`:** `PROFILE_ACTIONS_ENUM` updated to `1_21_2` variant. Display-name entries now include component rewriting. [VV `Protocol1_21To1_21_2.java:replaceClientbound()`]
+- **`UPDATE_ATTRIBUTES`:** Attribute modifier format: UUID field removed, modifiers now have string ID only (already done in 767 serverside, now serverbound clean-up). VV tracks `generic.max_health` to compute max health for 1.21 clients. [VV `Protocol1_21To1_21_2.java:appendClientbound()`]
+
+#### Item component changes (notable)
+- `DAMAGE_RESISTANT` → `DAMAGE_RESISTANT1_21_2` (format change)
+- `FOOD` → `FOOD1_21_2` (split into food + consumable components)
+- `CONSUMABLE1_21_2`, `USE_COOLDOWN`, `EQUIPPABLE1_21_2`, `ITEM_MODEL`, `GLIDER`, `TOOLTIP_STYLE`, `DEATH_PROTECTION` added
+- `REPAIRABLE`, `ENCHANTABLE` added
+- `LOCK` → `LOCK1_21_2`, `POTION_CONTENTS` → `POTION_CONTENTS1_21_2`, `INSTRUMENT` → `INSTRUMENT1_21_2`, `TRIM` → `TRIM1_21_2`
+
+[VV `Protocol1_21To1_21_2.java:onMappingDataLoaded()`]
+
+#### Damage types added
+`ender_pearl` and `mace_smash` damage types added to registry. [VV `Protocol1_21To1_21_2.java:registryDataRewriter()`]
+
+#### Chunk-load workaround
+1.21.2 introduced a rendering bug: if a loaded chunk received new data without being unloaded first, it wouldn't render correctly. VV injects a `ChunkLoadTracker` that forces chunk unload before re-send, only for 1.21.2 clients (not 1.21.3 which got the 1.21.2 packet set, as 1.21.4 fixed the bug). [VV `Protocol1_21To1_21_2.java:init()`]
+
+#### `CLIENT_INFORMATION`
+New `particle_status` varint field added at end. VV reads and discards it when translating to 1.21. [VV `Protocol1_21To1_21_2.java:clientInformation()`]
+
+---
+
+## 769 — 1.21.4 (December 3, 2024)
+
+### Gameplay headline
+Pale garden biome + pale oak wood set; creaking heart block; creaking mob (freezes when observed); eyeblossom; resin blocks. Spawn damage immunity removed. Water Breathing/Conduit Power now restore oxygen. [MCWIKI 1.21.4](https://minecraft.wiki/w/Java_Edition_1.21.4)
+
+### Protocol changes (768→769)
+VV package: `v1_21_2to1_21_4/` ([`Protocol1_21_2To1_21_4.java`](/tmp/mcproto-refs/ViaVersion/common/src/main/java/com/viaversion/viaversion/protocols/v1_21_2to1_21_4/Protocol1_21_2To1_21_4.java))
+
+Relatively lightweight protocol bump — no new packet types, primarily field changes and item-component format updates.
+
+- **`PICK_ITEM` split:** Serverbound `PICK_ITEM` (0x22) split into `PICK_ITEM_FROM_BLOCK` (0x22) and `PICK_ITEM_FROM_ENTITY` (0x23). VV provides a `PickItemProvider` to handle the split. [VV `Protocol1_21_2To1_21_4.java:register()`]
+- **`LEVEL_PARTICLES`:** `always_show` boolean field added after `override_limiter`. VV writes `false` for it when translating down. [VV `Protocol1_21_2To1_21_4.java:registerPackets()` `replaceClientbound(LEVEL_PARTICLES)`]
+- **`PLAYER_INFO_UPDATE`:** `PROFILE_ACTIONS_ENUM` → `1_21_4` variant (adds "show hat" action). VV writes `true` by default. [VV `Protocol1_21_2To1_21_4.java:registerPackets()`]
+- **Item components:** `CUSTOM_MODEL_DATA` → `1_21_4` (format extended), `TRIM` → `1_21_4`.
+- **`PLAYER_LOADED` serverbound:** Added (0x2A in 1.21.5 but arrives at 768→769 boundary). <!-- VERIFY exact version introduced -->
+- VV does NOT add a `ChunkLoadTracker` for 1.21.4 clients — Mojang fixed the rendering bug in this release. [VV `Protocol1_21To1_21_2.java:init()` comment]
+
+---
+
+## 770 — 1.21.5 (March 25, 2025)
+
+### Gameplay headline
+Farm animal variants (cold/warm/temperate pigs, cows, chickens with biome-based spawning), new decorative plants (leaf litter, wildflowers, bushes, firefly bushes), wolf sound variants (7). Game test framework (`/test` command, test blocks). Text components switch from JSON to SNBT. [MCWIKI 1.21.5](https://minecraft.wiki/w/Java_Edition_1.21.5)
+
+### Protocol changes (769→770)
+VV package: `v1_21_4to1_21_5/` ([`Protocol1_21_4To1_21_5.java`](/tmp/mcproto-refs/ViaVersion/common/src/main/java/com/viaversion/viaversion/protocols/v1_21_4to1_21_5/Protocol1_21_4To1_21_5.java))
+
+This is one of the larger protocol bumps: packet added/removed and major item-component churn.
+
+#### Packet additions and removals
+
+**Clientbound play:**
+- **`ADD_EXPERIENCE_ORB` removed.** Experience orbs now spawn via the regular `ADD_ENTITY` packet (entity type `experience_orb`). All subsequent IDs shift. [VV `ClientboundPackets1_21_5.java` — no `ADD_EXPERIENCE_ORB` entry; 1.21 enum had it at 0x02]
+- **`PLAYER_ROTATION` (0x42) added:** Server sends player rotation authoritative update. Separate from `PLAYER_POSITION`. [VV `ClientboundPackets1_21_5.java:0x42`]
+- **`TEST_INSTANCE_BLOCK_STATUS` (0x77):** New packet for the game test framework. [VV `ClientboundPackets1_21_5.java:0x77`]
+
+**Serverbound play (vs 1.21.4):**
+- `PICK_ITEM_FROM_BLOCK` (0x22), `PICK_ITEM_FROM_ENTITY` (0x23) — carried from 769
+- **`PLAYER_LOADED` (0x2A):** New — client signals it has loaded the world. [VV `ServerboundPackets1_21_5.java:0x2A`]
+- **`SET_TEST_BLOCK` (0x39):** Test framework. VV cancels. [VV `Protocol1_21_4To1_21_5.java:cancelServerbound()`]
+- **`TEST_INSTANCE_BLOCK_ACTION` (0x3D):** Test framework. VV cancels. [VV `Protocol1_21_4To1_21_5.java:cancelServerbound()`]
+
+#### Packet field changes
+- **`PLAYER_CHAT`:** Message-index varint added as first field. VV synthesizes this using `MessageIndexStorage` (tracks per-connection index). [VV `Protocol1_21_4To1_21_5.java:replaceClientbound(PLAYER_CHAT)`, `MessageIndexStorage`]
+- **`CHAT_COMMAND_SIGNED` and `CHAT` (serverbound):** `checksum: byte` field added at end. VV reads and drops it. [VV `Protocol1_21_4To1_21_5.java:registerServerbound(CHAT_COMMAND_SIGNED)`, `registerServerbound(CHAT)`]
+- **`wolf_variant` registry:** `assets` field restructured — `wild_texture`, `tame_texture`, `angry_texture` moved under `assets` compound; `biomes` field removed. VV remaps on registry send. [VV `Protocol1_21_4To1_21_5.java:registryDataRewriter` handler for `wolf_variant`]
+
+#### Item component changes (major churn)
+Many component keys changed to `1_21_5`-suffixed variants:
+- `UNBREAKABLE` → `1_21_5`, `ENCHANTMENTS` → `1_21_5`, `STORED_ENCHANTMENTS` → `1_21_5`
+- `DYED_COLOR` → `1_21_5`, `TRIM` → `1_21_5`, `ATTRIBUTE_MODIFIERS` → `1_21_5`
+- `EQUIPPABLE` → `1_21_5`, `TOOL` → `1_21_5`, `INSTRUMENT` → `1_21_5`, `JUKEBOX_PLAYABLE` → `1_21_5`
+- **New components added:** `BLOCKS_ATTACKS1_21_5` (shield-like), `PROVIDES_BANNER_PATTERNS1_21_5`, `TOOLTIP_DISPLAY`, `WEAPON`, `POTION_DURATION_SCALE`, `PROVIDES_TRIM_MATERIAL1_21_5`, `BREAK_SOUND`
+- **Mob-variant components as items:** `VILLAGER_VARIANT`, `WOLF_VARIANT`, `WOLF_COLLAR`, `FOX_VARIANT`, `SALMON_SIZE`, `PARROT_VARIANT`, `TROPICAL_FISH_*`, `MOOSHROOM_VARIANT`, `RABBIT_VARIANT`, `PIG_VARIANT`, `FROG_VARIANT`, `HORSE_VARIANT`, `PAINTING_VARIANT`, `LLAMA_VARIANT`, `AXOLOTL_VARIANT`, `CAT_VARIANT`, `CAT_COLLAR`, `SHEEP_COLOR`, `SHULKER_COLOR`, `COW_VARIANT`, `CHICKEN_VARIANT1_21_5`, `WOLF_SOUND_VARIANT` — all bucket/spawn-egg entity variant data is now carried as item components.
+
+[VV `Protocol1_21_4To1_21_5.java:onMappingDataLoaded()`]
+
+#### Smithing trim recipe slot display change
+Trim pattern slot display format changed — VV substitutes a placeholder (holder index 0) when translating smithing-trim recipe packets down. [VV `Protocol1_21_4To1_21_5.java` `recipeRewriter` anonymous class]
+
+---
+
+## 771 — 1.21.6 (June 17, 2025)
+
+### Gameplay headline
+"Chase the Skies" — rideable happy ghasts (up to 4 riders, colored harnesses); locator bar (shows other players' direction/distance in HUD); mob-to-mob leads; craftable saddles; waypoints. Dialog system (server-controlled modal UI). [MCWIKI 1.21.6](https://minecraft.wiki/w/Java_Edition_1.21.6)
+
+### Protocol changes (770→771)
+VV package: `v1_21_5to1_21_6/` ([`Protocol1_21_5To1_21_6.java`](/tmp/mcproto-refs/ViaVersion/common/src/main/java/com/viaversion/viaversion/protocols/v1_21_5to1_21_6/Protocol1_21_5To1_21_6.java))
+
+#### New packets
+
+**Clientbound play:**
+- **`TRACKED_WAYPOINT` (0x83):** Waypoint tracking for the locator bar feature. [VV `ClientboundPackets1_21_6.java:0x83`]
+- **`CLEAR_DIALOG` (0x84):** Dismiss the current server dialog. [VV `ClientboundPackets1_21_6.java:0x84`]
+- **`SHOW_DIALOG` (0x85):** Display a dialog to the player. [VV `ClientboundPackets1_21_6.java:0x85`]
+
+**Configuration state — clientbound:**
+- **`CLEAR_DIALOG` (0x11)** and **`SHOW_DIALOG` (0x12)** also appear in Configuration state — dialogs can be shown during config phase. [VV `ClientboundConfigurationPackets1_21_6.java:0x11,0x12`]
+
+**Serverbound play:**
+- **`CHANGE_GAME_MODE` (0x04):** New packet for switching game mode. VV translates this to `CHAT_COMMAND` (`/gamemode <name>`) for 1.21.5 servers. [VV `Protocol1_21_5To1_21_6.java:registerServerbound(CHANGE_GAME_MODE)`]
+- **`CUSTOM_CLICK_ACTION` (0x41):** New serverbound packet sent when a player interacts with a dialog element. VV cancels (no equivalent). [VV `Protocol1_21_5To1_21_6.java:cancelServerbound(CUSTOM_CLICK_ACTION)`]
+
+#### Packet field changes
+- **`CHANGE_DIFFICULTY`:** Difficulty value changes type from `unsigned byte` to `varint`. VV converts both directions. [VV `Protocol1_21_5To1_21_6.java:registerClientbound(CHANGE_DIFFICULTY)`, `registerServerbound(CHANGE_DIFFICULTY)`]
+- **`PLAYER_COMMAND`:** `press_shift_key` (action 0) and `release_shift_key` (action 1) removed — sneak is now a `PLAYER_INPUT` flag. All remaining actions shift down by 2. VV synthesizes `press_shift_key`/`release_shift_key` from `PLAYER_INPUT`'s sneak flag, using `SneakStorage` to track state changes. [VV `EntityPacketRewriter1_21_6.java:registerServerbound(PLAYER_COMMAND)`, `registerServerbound(PLAYER_INPUT)`]
+
+#### Configuration: dialog registry injection
+At `FINISH_CONFIGURATION`, VV synthesizes a `minecraft:dialog` registry entry (`server_links` dialog type) and sends it as `REGISTRY_DATA` — vanilla servers don't send this so older clients wouldn't see server links dialogs. [VV `EntityPacketRewriter1_21_6.java:appendClientbound(FINISH_CONFIGURATION)`]
+
+#### Dimension type: cloud_height defaults
+VV patches dimension-type registry entries to inject a default `cloud_height: 192` for overworld-like dimensions, since 1.21.6 clients render clouds based on this field. [VV `Protocol1_21_5To1_21_6.java:registryDataRewriter` handler for `dimension_type`]
+
+#### Item components
+- `ATTRIBUTE_MODIFIERS` → `1_21_6`, `EQUIPPABLE` → `1_21_6`
+
+[VV `Protocol1_21_5To1_21_6.java:onMappingDataLoaded()`]
+
+---
+
+## 772 — 1.21.7 / 1.21.8 (June 30 / July 17, 2025)
+
+### Gameplay headline
+**1.21.7:** New music disc "Lava Chicken" (Hyper Potions, from chicken jockey kill); new painting "Dennis" (3×3, A Minecraft Movie tie-in). 16 bug fixes (AMD/Qualcomm rendering, texture atlas leaks). [MCWIKI 1.21.7](https://minecraft.wiki/w/Java_Edition_1.21.7)
+
+**1.21.8:** Graphics bug-fix only — Intel Gen11 shading errors, inventory item-color glitches on Intel integrated graphics. Same protocol 772. [MCWIKI 1.21.8](https://minecraft.wiki/w/Java_Edition_1.21.8)
+
+### Protocol changes (771→772)
+VV package: `v1_21_6to1_21_7/` ([`Protocol1_21_6To1_21_7.java`](/tmp/mcproto-refs/ViaVersion/common/src/main/java/com/viaversion/viaversion/protocols/v1_21_6to1_21_7/Protocol1_21_6To1_21_7.java))
+
+Purely incremental — **no new packet types**. Same clientbound/serverbound enum as 771. VV's `Protocol1_21_6To1_21_7` class has an empty `registerPackets()` body; translation is limited to block/item/entity ID remapping and dialog-packet item rewriting. [VV `Protocol1_21_6To1_21_7.java:registerPackets()`]
+
+The `git log` shows `6b74116ff Handle item changes in dialog packets` as the main content commit — items embedded in `SHOW_DIALOG` / `CLEAR_DIALOG` needed remapping for the new block/item IDs. [VV-LOG `v1_21_6to1_21_7`]
+
+---
+
+## 773 — 1.21.9 / 1.21.10 (September 30 / October 7, 2025)
+
+### Gameplay headline
+"The Copper Age" — copper golem mob, copper tools/armor (stone-tier, high enchantability), copper chests (with oxidation), shelves (all wood types), copper lanterns/chains/bars. Chat drafts persist. New game rules (portal control, mob spawn). [MCWIKI 1.21.9](https://minecraft.wiki/w/Java_Edition_1.21.9)
+
+**1.21.10:** Five bug fixes from 1.21.9 (wind charge collision, TP chunk loading, piston/cobweb entity clip). Same protocol 773. [MCWIKI 1.21.10](https://minecraft.wiki/w/Java_Edition_1.21.10)
+
+### Protocol changes (772→773)
+VV package: `v1_21_7to1_21_9/` ([`Protocol1_21_7To1_21_9.java`](/tmp/mcproto-refs/ViaVersion/common/src/main/java/com/viaversion/viaversion/protocols/v1_21_7to1_21_9/Protocol1_21_7To1_21_9.java))
+
+This is a notably large bump: movement encoding overhaul, explosion restructure, debug packet additions.
+
+#### Entity velocity encoding change
+- **`ADD_ENTITY`:** Entity initial velocity previously encoded as three signed shorts (`velX`, `velY`, `velZ` — each = velocity × 8000, clamped). Now encoded as `LOW_PRECISION_VECTOR` (a compact 3-component float vector type). VV translates: reads the old shorts, reconstructs the vector. [VV `EntityPacketRewriter1_21_9.java:replaceClientbound(ADD_ENTITY)`]
+- **`SET_ENTITY_MOTION`:** Same change — shorts → `LOW_PRECISION_VECTOR`. [VV `EntityPacketRewriter1_21_9.java:registerClientbound(SET_ENTITY_MOTION)`]
+- **`PLAYER_ROTATION`:** Gets two `relative: boolean` flags (one per axis). VV writes `false` for both when translating down. [VV `EntityPacketRewriter1_21_9.java:registerClientbound(PLAYER_ROTATION)`]
+
+#### Explosion restructure
+`EXPLODE` packet restructured: the explosion radius and affected-block count (previously sent inline) are now sourced from `PROJECTILE_POWER`'s tracked state. VV emits the old-format explosion packet using values from `LastExplosionPowerStorage`. A new `block_particles` list field appended (VV writes count=0). [VV `Protocol1_21_7To1_21_9.java:replaceClientbound(EXPLODE)`]
+
+#### New debug packets (clientbound play)
+Four new debug visualisation packets added (likely tied to the game test framework):
+- **`DEBUG_BLOCK_VALUE` (0x1A)**
+- **`DEBUG_CHUNK_VALUE` (0x1B)**
+- **`DEBUG_ENTITY_VALUE` (0x1C)**
+- **`DEBUG_EVENT` (0x1D)**
+
+And **`GAME_EVENT_TEST_HIGHLIGHT_POS` (0x27):** Highlight test positions in the world. [VV `ClientboundPackets1_21_9.java`]
+
+All existing IDs shift up accordingly — packet count goes from 134 (0x85) in 772 to 139 (0x8A) in 773.
+
+#### Configuration state changes
+- **`CODE_OF_CONDUCT` (0x13)** added to serverbound Configuration packets (client accepts/rejects). VV cancels `ACCEPT_CODE_OF_CONDUCT` when translating down. [VV `ServerboundConfigurationPackets1_21_9.java:0x09`; `Protocol1_21_7To1_21_9.java:cancelServerbound(ACCEPT_CODE_OF_CONDUCT)`]
+
+#### Debug sample subscription
+`DEBUG_SAMPLE_SUBSCRIPTION` serverbound changed: from a single `type: varint` to a list `count: varint` + per-entry `registry_id: varint`. VV maps the new `DEDICATED_SERVER_TICK_TIME` subscription (id=0) back to the old `TICK_TIME` type (0). [VV `Protocol1_21_7To1_21_9.java:registerServerbound(DEBUG_SAMPLE_SUBSCRIPTION)`]
+
+#### `SET_DEFAULT_SPAWN_POSITION`
+<!-- VERIFY: field format change in 773 vs 772 — VV entity rewriter references this packet but full diff not extracted -->
+
+---
+
+## 774 — 1.21.11 (December 9, 2025)
+
+### Gameplay headline
+"Mounts of Mayhem" — nautilus (tameable aquatic mount), zombie nautilus (hostile), camel husk, parched (desert skeleton), zombie horseman. Spears (7 material tiers, jab + charge attacks, lunge enchantment). Nautilus armor. Netherite horse armor. Overhaul of dimension type and biome data (environment attributes system). [MCWIKI 1.21.11](https://minecraft.wiki/w/Java_Edition_1.21.11)
+
+### Protocol changes (773→774)
+VV package: `v1_21_9to1_21_11/` ([`Protocol1_21_9To1_21_11.java`](/tmp/mcproto-refs/ViaVersion/common/src/main/java/com/viaversion/viaversion/protocols/v1_21_9to1_21_11/Protocol1_21_9To1_21_11.java))
+
+This is the most structurally significant bump of the 1.21 line from a proxy standpoint.
+
+#### Packet rename
+- **`HORSE_SCREEN_OPEN` → `MOUNT_SCREEN_OPEN`** (same ID 0x28; name change only reflects expanded mount support). VV registers a direct remap. [VV `EntityPacketRewriter1_21_11.java:registerClientbound(HORSE_SCREEN_OPEN → MOUNT_SCREEN_OPEN)`]
+
+#### New entity type
+- **`zombie_nautilus`** entity type added. New entity-data type `zombieNautilusVariantType` registered. [VV `EntityPacketRewriter1_21_11.java:registerRewrites()`, `EntityTypes1_21_11`]
+
+#### Registry injection at FINISH_CONFIGURATION
+VV injects two entirely new registries before the config-phase completes, so older servers' clients see them:
+- **`zombie_nautilus_variant`** registry — VV synthesizes a single entry (`minecraft:pale` with `temperate` asset ID). [VV `Protocol1_21_9To1_21_11.java:registerPackets()`, `appendClientbound(FINISH_CONFIGURATION)`]
+- **`timeline`** registry — an experimental feature allowing time-based behavior modifications. VV synthesizes entries from `MAPPINGS.timelineRegistry()`. [VV `Protocol1_21_9To1_21_11.java:registerPackets()`]
+
+#### `dimension_type` registry overhaul (massive)
+The `dimension_type` data format was significantly restructured — many fields extracted into a new `attributes` compound NBT sub-object. VV performs full field-level migration for each dimension type entry:
+- `fixed_time` → `has_fixed_time` boolean
+- `has_raids` → `attributes/"gameplay/can_start_raid"`
+- `piglin_safe` → `attributes/"gameplay/piglins_zombify"` (inverted)
+- `respawn_anchor_works` → `attributes/"gameplay/respawn_anchor_works"`
+- `ultrawarm` → `attributes/"gameplay/fast_lava"` + `"gameplay/water_evaporates"`
+- `cloud_height` → `attributes/"visual/cloud_height"` + synthesizes `"visual/cloud_color": "#ccffffff"`
+- New fields added: `skybox`, `cardinal_light`, `timelines` list, `attributes/"visual/sky_light_color"`, `attributes/"visual/fog_start_distance"`, `attributes/"visual/fog_end_distance"`, `attributes/"audio/background_music"`, ambient cave sounds.
+
+[VV `Protocol1_21_9To1_21_11.java:registryDataRewriter` `dimension_type` handler]
+
+#### `worldgen/biome` registry overhaul
+Biome registry entries similarly gain an `attributes` sub-object with all sound and visual properties migrated:
+- `effects.sky_color` → `attributes/"visual/sky_color"` (suppressed for nether biomes)
+- `effects.water_fog_color` → `attributes/"visual/water_fog_color"`
+- `effects.fog_color` → `attributes/"visual/fog_color"`
+- `effects.music` → `attributes/"audio/background_music"`
+- `effects.mood_sound`/`additions_sound`/`ambient_sound` → `attributes/"audio/ambient_sounds"`
+- `effects.particle` → `attributes/"visual/ambient_particles"`
+
+[VV `Protocol1_21_9To1_21_11.java:registryDataRewriter` `worldgen/biome` handler]
+
+#### New item components
+- `ATTACK_RANGE`, `USE_EFFECTS`, `MINIMUM_ATTACK_CHARGE`, `DAMAGE_TYPE1_21_11`, `PIERCING_WEAPON`, `KINETIC_WEAPON`, `SWING_ANIMATION`, `ZOMBIE_NAUTILUS_VARIANT1_21_11`
+
+[VV `Protocol1_21_9To1_21_11.java:onMappingDataLoaded()`]
+
+#### Game time storage
+VV adds `GameTimeStorage` to track absolute game time (needed for timeline-based behavior). [VV `Protocol1_21_9To1_21_11.java:init()`]
+
+#### Serverbound: spear cancel
+`PLAYER_ACTION` action ID 7 ("stab") added for spear jab — VV cancels these when downgrading. [VV `EntityPacketRewriter1_21_11.java:registerServerbound(PLAYER_ACTION)`]
+
+---
+
+## Proxy and ViaVersion translation impact
+
+| Bump | Translation cost | Key challenge |
+|---|---|---|
+| 766→767 | Low | Attribute UUID↔ID bidirectional map; `PROJECTILE_POWER` scalar; chat type holder |
+| 767→768 | High | 7 new clientbound packets (all IDs shift); 2 new serverbound; full item-component set rebuild; max-health tracking; chunk-load workaround for 1.21.2 clients |
+| 768→769 | Medium | `PICK_ITEM` split; `LEVEL_PARTICLES` field insert; profile action enum extension |
+| 769→770 | High | `ADD_EXPERIENCE_ORB` removal (XP orbs now `ADD_ENTITY`); message-index synthesis for chat; chat checksum stripping; test-framework packets cancelled; 20+ new item components including all mob-variant data |
+| 770→771 | Medium | Dialog packet passthrough (play+config); sneak flag synthesis from `PLAYER_INPUT`; `PLAYER_COMMAND` action re-numbering; `CHANGE_DIFFICULTY` type conversion; dialog registry injection |
+| 771→772 | Low | ID remapping only; dialog packet item rewriting |
+| 772→773 | High | Entity velocity type change (`LOW_PRECISION_VECTOR` ↔ shorts) for ALL entities; explosion packet restructure; 5 new debug/test packets shifting all IDs; explosion power storage tracking |
+| 773→774 | Very high | Full `dimension_type` field migration (many fields → `attributes` compound); full `worldgen/biome` field migration; two new registry types injected during config; new entity type + variant; spear action filtering |
+
+**Proxy notes:**
+- **Login state:** `LOGIN_FINISHED` lost `strict_error_handling` (768). If a proxy injects it, strip on the way down.
+- **Configuration state:** Dialog packets (`CLEAR_DIALOG`, `SHOW_DIALOG`) appear in both config and play states from 771 onward. Proxies must forward these in both states.
+- **`CODE_OF_CONDUCT` (config, 773):** New serverbound; cancel when forwarding to 772 servers.
+- **`BUNDLE_ITEM_SELECTED` / `CLIENT_TICK_END` (768):** Cancel toward 767 servers.
+- **Chunk-load (768):** 1.21.2 clients need forced chunk unload before re-send; 1.21.3/1.21.4 don't.
+- **Item components:** Every bump through 770 added or renamed component keys. A proxy doing item translation must track which component key set the connected client/server uses.
+- **`dimension_type` (774):** By far the most complex registry translation in the 1.21 line — the field-level migration is large enough that ViaVersion devotes ~150 lines of registry rewriting code to it alone.