packets/: packet model + catalogs + wire-format deep-dives

Control-state catalogs (handshake/status/login/config), categorized Play catalog (~182 packets), and deep-dives on the four hard formats: chunk data (paletted containers + light), entity metadata (type registry), slot/structured components, command graph (Brigadier). Sourced from minecraft-data + ViaVersion. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
2026-06-19 15:15:26 +02:00
parent a3d5f64ef5
commit 90b711d12a
8 changed files with 2159 additions and 0 deletions
@@ -0,0 +1,453 @@
+# Play-State Packet Catalog — Java Edition 1.21.1 (protocol 767)
+
+**Version lock**: all IDs on this page are 1.21.1 (protocol 767). Play-state IDs shift between versions — sometimes heavily. See [`../versions/1.21.md`](../versions/1.21.md) for the delta from 1.20.x, and [`../versions/INDEX.md`](../versions/INDEX.md) for the full version map.
+
+**Sources**:
+- `minecraft-data`: `/tmp/mcproto-refs/minecraft-data/data/pc/1.21.1/protocol.json` (packet IDs + field types, authoritative for 1.21.1)
+- `ViaVersion CB`: `/tmp/mcproto-refs/ViaVersion/common/src/main/java/com/viaversion/viaversion/protocols/v1_20_5to1_21/packet/ClientboundPackets1_21.java` (ordered enum — ordinal = wire ID)
+- `ViaVersion SB`: `/tmp/mcproto-refs/ViaVersion/common/src/main/java/com/viaversion/viaversion/protocols/v1_20_3to1_20_5/packet/ServerboundPackets1_20_5.java` (serverbound IDs unchanged from 1.20.5→1.21.1; no new SB enum file in the `v1_20_5to1_21` package)
+
+**Totals** (minecraft-data count): **124 clientbound**, **58 serverbound** = 182 play-state packets.
+
+**Notation**:
+- `CB` = Server→Client (clientbound)
+- `SB` = Client→Server (serverbound)
+- `→ format-*.md` = that packet's binary layout has its own deep-dive doc in this directory
+- `<!-- UNCONFIRMED -->` = claim not verified against a second source
+
+---
+
+## 1. Connection / System
+
+Core session-maintenance and state-transition packets.
+
+### Clientbound
+
+| ID | ViaVersion name | mc-data name | Purpose |
+|----|-----------------|--------------|---------|
+| 0x00 | `BUNDLE_DELIMITER` | `bundle_delimiter` | Frame boundary: server wraps a group of CB packets between two 0x00 delimiters; client applies them atomically (added 1.19.4) |
+| 0x26 | `KEEP_ALIVE` | `keep_alive` | Heartbeat: server sends random `i64` ID; client must echo it within timeout or be kicked |
+| 0x35 | `PING` | `ping` | Echoes an `i32` ID back from client's `PONG` (not the status-ping; used for latency measurement mid-session) |
+| 0x36 | `PONG_RESPONSE` | `ping_response` | Server response to client's `PING_REQUEST` (0x21 SB); carries `i64` payload |
+| 0x1D | `DISCONNECT` | `kick_disconnect` | Kick with chat-component reason (Text component, NBT-encoded in 1.20.3+) |
+| 0x2B | `LOGIN` | `login` | **Join Game** — first play-state packet after configuration; see detail below |
+| 0x47 | `RESPAWN` | `respawn` | Sent on dimension change or respawn; see detail below |
+| 0x53 | `SET_CARRIED_ITEM` | `held_item_slot` | Sets the client's active hotbar slot (0–8) |
+| 0x69 | `START_CONFIGURATION` | `start_configuration` | Transitions back to Configuration state for resource-pack / registry updates (1.20.2+) |
+| 0x19 | `CUSTOM_PAYLOAD` | `custom_payload` | Plugin channel message (`Identifier` channel + byte blob) |
+| 0x16 | `COOKIE_REQUEST` | `cookie_request` | Server requests a previously stored cookie value from the client (1.20.5+) |
+| 0x6B | `STORE_COOKIE` | `store_cookie` | Server pushes a key/value cookie to the client for later retrieval (1.20.5+) |
+| 0x73 | `TRANSFER` | `transfer` | Transfers the client to a different server (host + port); 1.20.5+ |
+
+### Serverbound
+
+| ID | ViaVersion name | mc-data name | Purpose |
+|----|-----------------|--------------|---------|
+| 0x18 | `KEEP_ALIVE` | `keep_alive` | Echo of server's `i64` keep-alive ID |
+| 0x27 | `PONG` | `pong` | Echo of server's `PING` `i32` ID |
+| 0x21 | `PING_REQUEST` | `ping_request` | Client-initiated latency probe; carries `i64` payload; server echoes via `PONG_RESPONSE` |
+| 0x00 | `ACCEPT_TELEPORTATION` | `teleport_confirm` | Client acks a `PLAYER_POSITION` teleport by echoing its `varint teleportId` |
+| 0x0C | `CONFIGURATION_ACKNOWLEDGED` | `configuration_acknowledged` | Client acks `START_CONFIGURATION`, triggering transition back to Configuration state |
+| 0x11 | `COOKIE_RESPONSE` | `cookie_response` | Response to `COOKIE_REQUEST`; carries key + optional value |
+| 0x12 | `CUSTOM_PAYLOAD` | `custom_payload` | Plugin channel message (SB direction) |
+| 0x2B | `RESOURCE_PACK` | `resource_pack_receive` | Client reports resource-pack download status (accepted/declined/downloaded/failed) |
+
+---
+
+### Detail: LOGIN (0x2B CB) — Join Game
+
+First play-state packet sent by the server (after Configuration → Play transition). Sets up the client's world context.
+
+Fields (from `protocol.json` `packet_login`):
+
+| Field | Type | Notes |
+|-------|------|-------|
+| `entityId` | i32 | Client's entity ID |
+| `isHardcore` | bool | |
+| `worldNames` | varint-prefixed string[] | All dimension names known to the server |
+| `maxPlayers` | varint | (informational, not enforced client-side) |
+| `viewDistance` | varint | Server's configured view distance |
+| `simulationDistance` | varint | |
+| `reducedDebugInfo` | bool | Hides debug overlay |
+| `enableRespawnScreen` | bool | |
+| `doLimitedCrafting` | bool | |
+| `worldState` | SpawnInfo | Composite: dimension type ID, dimension name, hashed seed, gamemode, prev gamemode, debug/flat flags, death location (optional), portal cooldown |
+| `enforcesSecureChat` | bool | If true, server requires signed chat messages |
+
+### Detail: RESPAWN (0x47 CB)
+
+Sent on dimension switch, death respawn, or `/respawn`. Resets world context without a full Login.
+
+Fields (`packet_respawn`):
+
+| Field | Type | Notes |
+|-------|------|-------|
+| `worldState` | SpawnInfo | Same composite type as Login |
+| `copyMetadata` | u8 | Bitmask: bit 0 = keep attributes, bit 1 = keep entity data |
+
+---
+
+## 2. Entity
+
+Spawning, movement, metadata, equipment, effects, and removal.
+
+### Clientbound
+
+| ID | ViaVersion name | mc-data name | Purpose |
+|----|-----------------|--------------|---------|
+| 0x01 | `ADD_ENTITY` | `spawn_entity` | Spawn any non-XP entity; carries entity ID (varint), UUID, type (varint), position (f64×3), angles, data (varint, type-dependent), velocity |
+| 0x02 | `ADD_EXPERIENCE_ORB` | `spawn_entity_experience_orb` | Spawn XP orb; entity ID + position + count (i16) |
+| 0x03 | `ANIMATE` | `animation` | Play entity animation (swing arm, take damage, leave bed, etc.); entity ID + animation byte |
+| 0x2E | `MOVE_ENTITY_POS` | `rel_entity_move` | Delta position only (fixed-point i16×3); entity moved < 8 blocks |
+| 0x2F | `MOVE_ENTITY_POS_ROT` | `entity_move_look` | Delta position + rotation |
+| 0x30 | `MOVE_ENTITY_ROT` | `entity_look` | Rotation only |
+| 0x48 | `ROTATE_HEAD` | `entity_head_rotation` | Yaw of entity head (separate from body) |
+| 0x31 | `MOVE_VEHICLE` | `vehicle_move` | Absolute position + rotation for mounted vehicle |
+| 0x70 | `TELEPORT_ENTITY` | `entity_teleport` | Absolute position + rotation for entities beyond delta range (>8 blocks) |
+| 0x5A | `SET_ENTITY_MOTION` | `entity_velocity` | Velocity in fixed-point i16 units (1/8000 m/tick) |
+| 0x58 | `SET_ENTITY_DATA` | `entity_metadata` | Entity metadata key-value stream; **→ `format-entity-metadata.md`** |
+| 0x5B | `SET_EQUIPMENT` | `entity_equipment` | Equipment slots (main/off hand, 4 armor slots); slot bitmask + Slot data |
+| 0x76 | `UPDATE_MOB_EFFECT` | `entity_effect` | Apply/update a potion effect (entity ID, effect ID, amplifier, duration, flags) |
+| 0x43 | `REMOVE_MOB_EFFECT` | `remove_entity_effect` | Remove a specific effect from entity |
+| 0x59 | `SET_ENTITY_LINK` | `attach_entity` | Attach entity A to entity B (leash); entity ID + vehicle ID (-1 to detach) |
+| 0x5F | `SET_PASSENGERS` | `set_passengers` | Set which entities are riding on a vehicle; vehicle entity ID + array of passenger IDs |
+| 0x42 | `REMOVE_ENTITIES` | `entity_destroy` | Remove one or more entities by ID (varint array) |
+| 0x1F | `ENTITY_EVENT` | `entity_status` | Entity-specific status byte (e.g. death animation, tipped arrow hit, villager anger) |
+| 0x1A | `DAMAGE_EVENT` | `damage_event` | Entity took damage: entity ID, damage type, source entity/position (1.19.4+) |
+| 0x24 | `HURT_ANIMATION` | `hurt_animation` | Visual-only hurt swing (entity ID + yaw); added 1.19.4 |
+| 0x75 | `UPDATE_ATTRIBUTES` | `entity_update_attributes` | Update base attribute values (movement speed, attack damage, etc.) |
+| 0x6F | `TAKE_ITEM_ENTITY` | `collect` | Entity picked up an item (item entity ID + collector entity ID + pickup count) |
+| 0x3F | `PLAYER_LOOK_AT` | `face_player` | Make entity/player face a position or another entity |
+| 0x79 | `PROJECTILE_POWER` | `set_projectile_power` | Projectile acceleration vector <!-- UNCONFIRMED exact semantics --> |
+
+### Serverbound
+
+| ID | ViaVersion name | mc-data name | Purpose |
+|----|-----------------|--------------|---------|
+| 0x1A | `MOVE_PLAYER_POS` | `position` | Player position update (`f64` x/y/z + `bool` onGround) |
+| 0x1B | `MOVE_PLAYER_POS_ROT` | `position_look` | Position + yaw/pitch |
+| 0x1C | `MOVE_PLAYER_ROT` | `look` | Rotation only |
+| 0x1D | `MOVE_PLAYER_STATUS_ONLY` | `flying` | Ground status only (used when no other movement to report) |
+| 0x1E | `MOVE_VEHICLE` | `vehicle_move` | Absolute position + rotation while controlling a vehicle |
+| 0x16 | `INTERACT` | `use_entity` | Interact with entity: entity ID + action (attack/interact/interact-at) + hand + position (for interact-at) |
+| 0x24 | `PLAYER_ACTION` | `block_dig` | Block dig/place actions (start dig, cancel, finish, drop item, swap hands, shoot arrow) + location + face + sequence |
+| 0x25 | `PLAYER_COMMAND` | `entity_action` | Player-state commands: sneak start/stop, sprint start/stop, leave bed, start/stop elytra, horse jump |
+| 0x36 | `SWING` | `arm_animation` | Arm swing animation (main or off hand) |
+| 0x37 | `TELEPORT_TO_ENTITY` | `spectate` | Spectator teleport to entity UUID |
+| 0x26 | `PLAYER_INPUT` | `steer_vehicle` | Vehicle steering input (sideways/forward + flags for jump/unmount) |
+| 0x1F | `PADDLE_BOAT` | `steer_boat` | Boat paddle state (left + right `bool`) |
+| 0x20 | `PICK_ITEM` | `pick_item` | Pick Block (middle-click); carries hotbar slot index |
+| 0x15 | `ENTITY_TAG_QUERY` | `query_entity_nbt` | Debug: request entity NBT (debug build) |
+
+---
+
+## 3. World
+
+Chunks, blocks, lighting, world events, and world border.
+
+### Clientbound
+
+| ID | ViaVersion name | mc-data name | Purpose |
+|----|-----------------|--------------|---------|
+| 0x27 | `LEVEL_CHUNK_WITH_LIGHT` | `map_chunk` | Full chunk column + light data bundled; **→ `format-chunk-data.md`** |
+| 0x2A | `LIGHT_UPDATE` | `update_light` | Update lighting only (no block data); same sky/block light structure as above; **→ `format-chunk-data.md`** |
+| 0x0C | `CHUNK_BATCH_FINISHED` | `chunk_batch_finished` | Signals end of chunk batch; carries batch size (varint); client responds with `CHUNK_BATCH_RECEIVED` (1.20.2+) |
+| 0x0D | `CHUNK_BATCH_START` | `chunk_batch_start` | Signals start of chunk batch (1.20.2+) |
+| 0x0E | `CHUNKS_BIOMES` | `chunk_biomes` | Update biome data for existing chunks without re-sending block data (1.20+) |
+| 0x21 | `FORGET_LEVEL_CHUNK` | `unload_chunk` | Unload a chunk column; `i32` chunk X + Z |
+| 0x54 | `SET_CHUNK_CACHE_CENTER` | `update_view_position` | Shift the client's chunk center (sent on player movement between chunks) |
+| 0x55 | `SET_CHUNK_CACHE_RADIUS` | `update_view_distance` | Update render distance |
+| 0x09 | `BLOCK_UPDATE` | `block_change` | Single block change: `Position` + block state ID (varint) |
+| 0x49 | `SECTION_BLOCKS_UPDATE` | `multi_block_change` | Multiple block changes in one chunk section; section coords + array of `(localPos << 12 | stateId)` i64 |
+| 0x07 | `BLOCK_ENTITY_DATA` | `tile_entity_data` | Update a block entity's NBT (chest, furnace, sign, etc.) |
+| 0x08 | `BLOCK_EVENT` | `block_action` | Block action event (e.g. chest open/close sound, note block pitch, piston extension); location + action byte + action param + block type |
+| 0x06 | `BLOCK_DESTRUCTION` | `block_break_animation` | Show block breaking animation progress (0–9) for a given entity ID at a position |
+| 0x05 | `BLOCK_CHANGED_ACK` | `acknowledge_player_digging` | Server acknowledges a block-dig sequence number; carries sequence ID + position + block state + status + successful bool |
+| 0x28 | `LEVEL_EVENT` | `world_event` | World event/sound (door open, explosion sound, portal, block break sound, etc.); event ID + position + data + global flag |
+| 0x20 | `EXPLODE` | `explosion` | Explosion: position (f64), radius (f32), array of affected block offsets, player knockback velocity, interaction type, particles, sound |
+| 0x22 | `GAME_EVENT` | `game_state_change` | Game state notifications: start/stop rain, change gamemode, win game, demo events, bed/respawn prompts, guardian elder effect, etc. Carries `u8` reason + `f32` value |
+| 0x56 | `SET_DEFAULT_SPAWN_POSITION` | `spawn_position` | World spawn point (used for compass direction) |
+| 0x25 | `INITIALIZE_BORDER` | `initialize_world_border` | Full world border state (center, size, lerp target, lerp time, warning blocks/time) |
+| 0x4D | `SET_BORDER_CENTER` | `world_border_center` | Update border center |
+| 0x4E | `SET_BORDER_LERP_SIZE` | `world_border_lerp_size` | Animate border size change |
+| 0x4F | `SET_BORDER_SIZE` | `world_border_size` | Set border size instantly |
+| 0x50 | `SET_BORDER_WARNING_DELAY` | `world_border_warning_delay` | Warning time (seconds) |
+| 0x51 | `SET_BORDER_WARNING_DISTANCE` | `world_border_warning_reach` | Warning distance (blocks) |
+| 0x64 | `SET_TIME` | `update_time` | World age (i64, always incrementing) + time of day (i64, 0–24000; negative = frozen) |
+| 0x62 | `SET_SIMULATION_DISTANCE` | `simulation_distance` | Server's entity simulation radius |
+| 0x71 | `TICKING_STATE` | `set_ticking_state` | Tick rate + whether frozen (1.20.3+) |
+| 0x72 | `TICKING_STEP` | `step_tick` | Advance frozen world by N ticks (1.20.3+) |
+| 0x0B | `CHANGE_DIFFICULTY` | `difficulty` | Current difficulty + locked flag |
+
+### Serverbound
+
+| ID | ViaVersion name | mc-data name | Purpose |
+|----|-----------------|--------------|---------|
+| 0x08 | `CHUNK_BATCH_RECEIVED` | `chunk_batch_received` | Client reports desired chunks/tick back to server after batch (throttle feedback) |
+| 0x01 | `BLOCK_ENTITY_TAG_QUERY` | `query_block_nbt` | Debug: request block entity NBT at position |
+| 0x02 | `CHANGE_DIFFICULTY` | `set_difficulty` | Op changes world difficulty (op-only) |
+| 0x19 | `LOCK_DIFFICULTY` | `lock_difficulty` | Op locks/unlocks difficulty |
+| 0x38 | `USE_ITEM_ON` | `block_place` | Place/use block: hand + block position + face + cursor position + head-inside-block flag + sequence |
+| 0x39 | `USE_ITEM` | `use_item` | Use item in hand (right-click in air): hand + sequence |
+| 0x17 | `JIGSAW_GENERATE` | `generate_structure` | Generate jigsaw structure (op/debug) |
+| 0x30 | `SET_COMMAND_BLOCK` | `update_command_block` | Update command block: position + command + mode + flags |
+| 0x31 | `SET_COMMAND_MINECART` | `update_command_block_minecart` | Update command block in minecart |
+| 0x33 | `SET_JIGSAW_BLOCK` | `update_jigsaw_block` | Update jigsaw block settings |
+| 0x34 | `SET_STRUCTURE_BLOCK` | `update_structure_block` | Update structure block settings |
+| 0x35 | `SIGN_UPDATE` | `update_sign` | Submit sign text (front/back): position + is-front-side + 4 lines |
+
+---
+
+## 4. Inventory / Container
+
+Opening, populating, and interacting with containers and the player inventory.
+
+### Clientbound
+
+| ID | ViaVersion name | mc-data name | Purpose |
+|----|-----------------|--------------|---------|
+| 0x33 | `OPEN_SCREEN` | `open_window` | Open a container UI; window ID + menu type (varint) + title (NBT text) |
+| 0x23 | `HORSE_SCREEN_OPEN` | `open_horse_window` | Open horse inventory UI (separate from generic containers) |
+| 0x12 | `CONTAINER_CLOSE` | `close_window` | Server closes a container (window ID) |
+| 0x13 | `CONTAINER_SET_CONTENT` | `window_items` | Full slot sync for open container; window ID + `stateId` + Slot array + carried item; **Slot type → `format-slot-and-components.md`** |
+| 0x15 | `CONTAINER_SET_SLOT` | `set_slot` | Update single slot; window ID + `stateId` + slot index (i16) + Slot; **→ `format-slot-and-components.md`** |
+| 0x14 | `CONTAINER_SET_DATA` | `craft_progress_bar` | Update a container "property" (furnace progress, enchant seed, etc.); window ID + property ID (i16) + value (i16) |
+| 0x32 | `OPEN_BOOK` | `open_book` | Open a book UI (hand: main/off) |
+| 0x34 | `OPEN_SIGN_EDITOR` | `open_sign_entity` | Open sign editor UI for a position; bool for front/back side |
+| 0x37 | `PLACE_GHOST_RECIPE` | `craft_recipe_response` | Show recipe in crafting grid (response to `PLACE_RECIPE` SB) |
+| 0x17 | `COOLDOWN` | `set_cooldown` | Start item use cooldown (item ID + ticks) |
+| 0x2D | `MERCHANT_OFFERS` | `trade_list` | Villager trade list (window ID + trades array + villager level/XP + regular villager + can restock) |
+| 0x2C | `MAP_ITEM_DATA` | `map` | Map item data (map ID + scale + locked + icons + patch data) |
+
+### Serverbound
+
+| ID | ViaVersion name | mc-data name | Purpose |
+|----|-----------------|--------------|---------|
+| 0x0F | `CONTAINER_CLOSE` | `close_window` | Client closed a container (window ID) |
+| 0x0E | `CONTAINER_CLICK` | `window_click` | Inventory click; window ID + `stateId` + slot (i16) + button + mode + changed slots array + cursor Slot |
+| 0x0D | `CONTAINER_BUTTON_CLICK` | `enchant_item` | Click a container button (enchanting table slot select, trade button, etc.) |
+| 0x10 | `CONTAINER_SLOT_STATE_CHANGED` | `set_slot_state` | Toggle a slot state (e.g. toggle a crafting grid slot on/off — added 1.20.2) <!-- UNCONFIRMED exact usage --> |
+| 0x22 | `PLACE_RECIPE` | `craft_recipe_request` | Request to auto-fill a recipe in crafting grid; window ID + recipe ID + make-all flag |
+| 0x32 | `SET_CREATIVE_MODE_SLOT` | `set_creative_slot` | Creative-mode direct slot set; slot (i16) + Slot data |
+| 0x29 | `RECIPE_BOOK_SEEN_RECIPE` | `displayed_recipe` | Mark a recipe as seen in the recipe book |
+| 0x28 | `RECIPE_BOOK_CHANGE_SETTINGS` | `recipe_book` | Toggle recipe book filter/open state |
+| 0x2A | `RENAME_ITEM` | `name_item` | Submit anvil rename string |
+| 0x2E | `SET_BEACON` | `set_beacon_effect` | Set beacon effect (primary + secondary effect IDs) |
+| 0x2D | `SELECT_TRADE` | `select_trade` | Select villager trade by index |
+| 0x14 | `EDIT_BOOK` | `edit_book` | Submit book contents (hand + pages array + optional title) |
+
+---
+
+## 5. Player
+
+Position synchronization, health, XP, abilities, and player list.
+
+### Clientbound
+
+| ID | ViaVersion name | mc-data name | Purpose |
+|----|-----------------|--------------|---------|
+| 0x40 | `PLAYER_POSITION` | `position` | **Synchronize player position**: server-authoritative teleport; fields: x/y/z (f64), yaw/pitch (f32), flags (PositionUpdateRelatives bitmask — absolute vs relative per axis), `teleportId` (varint); client must confirm with `ACCEPT_TELEPORTATION`; see field detail below |
+| 0x38 | `PLAYER_ABILITIES` | `abilities` | Player ability flags (invulnerable, flying, allow-fly, creative-mode) + fly speed + field-of-view modifier |
+| 0x5D | `SET_HEALTH` | `update_health` | Health (f32), food (varint), saturation (f32) |
+| 0x5C | `SET_EXPERIENCE` | `experience` | XP bar progress (f32 0–1) + total XP levels (varint) + total XP points (varint) |
+| 0x3E | `PLAYER_INFO_UPDATE` | `player_info` | Add/update player list entries; bitmask of actions (add player, initialize chat, update gamemode, update listed, update latency, update display name) + array of UUID + per-action data |
+| 0x3D | `PLAYER_INFO_REMOVE` | `player_remove` | Remove player list entries by UUID array |
+| 0x3A | `PLAYER_COMBAT_END` | `end_combat_event` | Player exited combat (duration + entity ID) |
+| 0x3B | `PLAYER_COMBAT_ENTER` | `enter_combat_event` | Player entered combat |
+| 0x3C | `PLAYER_COMBAT_KILL` | `death_combat_event` | Player killed in combat (player entity ID + death message) |
+| 0x39 | `PLAYER_CHAT` | `player_chat` | Signed player chat message; see field detail below |
+| 0x09 | `CLIENT_COMMAND` (mismap) | — | See SB below |
+| 0x52 | `SET_CAMERA` | `camera` | Set which entity the player's camera follows |
+| 0x31 | `MOVE_VEHICLE` | `vehicle_move` | Sync vehicle position to client |
+
+### Serverbound
+
+| ID | ViaVersion name | mc-data name | Purpose |
+|----|-----------------|--------------|---------|
+| 0x09 | `CLIENT_COMMAND` | `client_command` | Perform client action: 0 = respawn, 1 = open inventory stats |
+| 0x0A | `CLIENT_INFORMATION` | `settings` | Client settings: locale, view distance, chat mode, colors, skin parts, main hand, filter text, allow server listings |
+| 0x23 | `PLAYER_ABILITIES` | `abilities` | Client reports flying flag (bit 1); other flags ignored by server |
+| 0x2F | `SET_CARRIED_ITEM` | `held_item_slot` | Change held hotbar slot (0–8) |
+| 0x0B | `COMMAND_SUGGESTION` | `tab_complete` | Tab-complete request; `transactionId` (varint) + partial command string |
+| 0x13 | `DEBUG_SAMPLE_SUBSCRIPTION` | `debug_sample_subscription` | Subscribe to debug performance samples (tick duration, ping, etc.) |
+
+---
+
+### Detail: PLAYER_POSITION (0x40 CB) — Synchronize Player Position
+
+The server asserts the player's canonical position. Client must respond with `ACCEPT_TELEPORTATION` (0x00 SB) carrying the same `teleportId` before sending movement packets will be trusted again.
+
+Fields (from `protocol.json` `packet_position`):
+
+| Field | Type | Notes |
+|-------|------|-------|
+| `x` | f64 | |
+| `y` | f64 | |
+| `z` | f64 | |
+| `yaw` | f32 | |
+| `pitch` | f32 | |
+| `flags` | `PositionUpdateRelatives` (u8 bitmask) | Bit 0=X, 1=Y, 2=Z, 3=pitch, 4=yaw: if set, the value is *relative* to current |
+| `teleportId` | varint | Client echoes in `ACCEPT_TELEPORTATION` |
+
+---
+
+## 6. UI / HUD
+
+Chat messages (all three kinds), titles, scoreboard, boss bar, tab list.
+
+### Clientbound
+
+| ID | ViaVersion name | mc-data name | Purpose |
+|----|-----------------|--------------|---------|
+| 0x6C | `SYSTEM_CHAT` | `system_chat` | System message (NBT text component + `isActionBar` bool); used for `/say`, `/tell`, server announcements |
+| 0x39 | `PLAYER_CHAT` | `player_chat` | Signed player chat; carries sender UUID, message, timestamp, signature (256-byte optional), chat type decoration reference, optional unsigned fallback; see detail below |
+| 0x1E | `DISGUISED_CHAT` | `profileless_chat` | System-style chat that mimics a player message without a UUID (no signature); added 1.19.3 |
+| 0x1C | `DELETE_CHAT` | `hide_message` | Delete a previously sent signed chat message by signature hash |
+| 0x65 | `SET_TITLE_TEXT` | `set_title_text` | Show title (NBT text) |
+| 0x63 | `SET_SUBTITLE_TEXT` | `set_title_subtitle` | Show subtitle (NBT text) |
+| 0x4C | `SET_ACTION_BAR_TEXT` | `action_bar` | Action bar message (NBT text) |
+| 0x66 | `SET_TITLES_ANIMATION` | `set_title_time` | Title timing: fade-in, stay, fade-out (all i32 ticks) |
+| 0x0F | `CLEAR_TITLES` | `clear_titles` | Clear title/subtitle/action bar; `bool` reset (resets timing) |
+| 0x0A | `BOSS_EVENT` | `boss_bar` | Boss bar operation: ADD, REMOVE, UPDATE_HEALTH, UPDATE_TITLE, UPDATE_STYLE, UPDATE_FLAGS; UUID + per-action data |
+| 0x6D | `TAB_LIST` | `playerlist_header` | Tab list header + footer (both NBT text) |
+| 0x5E | `SET_OBJECTIVE` | `scoreboard_objective` | Create/remove/update scoreboard objective; name + mode (0=create,1=remove,2=update) + display name + type |
+| 0x61 | `SET_SCORE` | `scoreboard_score` | Set an entity's score for an objective; entity name + objective name + score (varint) + optional display name + optional number format |
+| 0x44 | `RESET_SCORE` | `reset_score` | Remove a score entry; entity name + optional objective name (1.20.3+) |
+| 0x57 | `SET_DISPLAY_OBJECTIVE` | `scoreboard_display_objective` | Set which objective appears in a display slot (sidebar, list, below-name) |
+| 0x60 | `SET_PLAYER_TEAM` | `teams` | Scoreboard team operations: CREATE, REMOVE, INFO_UPDATE, ADD_PLAYERS, REMOVE_PLAYERS |
+| 0x18 | `CUSTOM_CHAT_COMPLETIONS` | `chat_suggestions` | Add/remove/set chat autocomplete suggestions (1.19.1+) |
+| 0x0B | `CHANGE_DIFFICULTY` (mismap) | `difficulty` | See World § above |
+| 0x1B | `DEBUG_SAMPLE` | `debug_sample` | Performance debug sample push (tick durations, etc.) |
+
+### Serverbound
+
+| ID | ViaVersion name | mc-data name | Purpose |
+|----|-----------------|--------------|---------|
+| 0x06 | `CHAT` | `chat_message` | Player chat message; text + timestamp + salt + optional signature + ack bitset |
+| 0x04 | `CHAT_COMMAND` | `chat_command` | Run command (unsigned); command string |
+| 0x05 | `CHAT_COMMAND_SIGNED` | `chat_command_signed` | Run command with signed arguments (1.19.1+) |
+| 0x07 | `CHAT_SESSION_UPDATE` | `chat_session_update` | Update session signing key (public key + expiry + signature) |
+| 0x03 | `CHAT_ACK` | `message_acknowledgement` | Acknowledge received signed chat messages (cumulative offset into message history) |
+
+---
+
+### Detail: PLAYER_CHAT (0x39 CB) — Signed Chat
+
+Fields (`protocol.json` `packet_player_chat`):
+
+| Field | Type | Notes |
+|-------|------|-------|
+| `senderUuid` | UUID | |
+| `index` | varint | Position in sender's message sequence |
+| `signature` | optional byte[256] | RSA-signed message hash; absent for unsigned messages |
+| `plainMessage` | string | Raw text |
+| `timestamp` | i64 | Unix ms |
+| `salt` | i64 | |
+| `previousMessages` | previousMessages | Compact acknowledgment of prior messages (used for signature chaining) |
+| `unsignedChatContent` | optional NBT | Decorated/filtered version if different from plain |
+| `filterType` | varint | 0=pass-through, 1=fully-filtered, 2=partially-filtered |
+| `filterTypeMask` | conditional | Bitmask when `filterType=2` |
+| `type` | ChatTypesHolder | Reference into registry for formatting (chat, say-command, etc.) |
+| `networkName` | NBT | Sender's display name |
+| `networkTargetName` | optional NBT | Target for directed messages (whisper, /tell) |
+
+---
+
+## 7. Commands / Recipes
+
+The command graph, tab-complete, and recipe synchronization.
+
+### Clientbound
+
+| ID | ViaVersion name | mc-data name | Purpose |
+|----|-----------------|--------------|---------|
+| 0x11 | `COMMANDS` | `declare_commands` | Full command graph as a node tree; **→ `format-command-graph.md`** |
+| 0x10 | `COMMAND_SUGGESTIONS` | `tab_complete` | Tab-complete response; `transactionId` + match start + length + array of (text, optional tooltip) |
+| 0x77 | `UPDATE_RECIPES` | `declare_recipes` | Full recipe list (crafting, smelting, stonecutting, etc.) |
+| 0x41 | `RECIPE` | `unlock_recipes` | Recipe book state: action (init/add/remove) + recipe IDs shown + recipe IDs highlighted + display settings |
+| 0x37 | `PLACE_GHOST_RECIPE` | `craft_recipe_response` | (Repeat from Inventory §) Display recipe in crafting grid |
+| 0x4A | `SELECT_ADVANCEMENTS_TAB` | `select_advancement_tab` | Open advancement tab (optional identifier) |
+| 0x74 | `UPDATE_ADVANCEMENTS` | `advancements` | Advancement data: reset flag + added map + removed IDs + progress map |
+
+### Serverbound
+
+| ID | ViaVersion name | mc-data name | Purpose |
+|----|-----------------|--------------|---------|
+| 0x0B | `COMMAND_SUGGESTION` | `tab_complete` | Tab-complete request (see Player §5 SB) |
+| 0x22 | `PLACE_RECIPE` | `craft_recipe_request` | (Repeat from Inventory §) |
+| 0x28 | `RECIPE_BOOK_CHANGE_SETTINGS` | `recipe_book` | Recipe book toggle |
+| 0x29 | `RECIPE_BOOK_SEEN_RECIPE` | `displayed_recipe` | Mark recipe seen |
+| 0x2C | `SEEN_ADVANCEMENTS` | `advancement_tab` | Open/close an advancement tab |
+
+---
+
+## 8. Sound / Particle
+
+### Clientbound
+
+| ID | ViaVersion name | mc-data name | Purpose |
+|----|-----------------|--------------|---------|
+| 0x68 | `SOUND` | `sound_effect` | Named sound at fixed position (sound ID varint, category, x/y/z as fixed-point i32, volume f32, pitch f32, seed i64) |
+| 0x67 | `SOUND_ENTITY` | `entity_sound_effect` | Same but position follows an entity ID |
+| 0x6A | `STOP_SOUND` | `stop_sound` | Stop sounds matching a category (optional) and/or sound ID (optional) |
+| 0x29 | `LEVEL_PARTICLES` | `world_particles` | Spawn particle effect: particle type + data + position (f64) + offset (f32×3) + max speed + count + long-range flag |
+| 0x28 | `LEVEL_EVENT` | `world_event` | (See World §) Also carries many sound/effect IDs |
+
+### Serverbound
+
+_(No SB packets for sound/particle — client never requests specific sounds.)_
+
+---
+
+## 9. Misc
+
+Tags, resource packs, server info, and debug/telemetry.
+
+### Clientbound
+
+| ID | ViaVersion name | mc-data name | Purpose |
+|----|-----------------|--------------|---------|
+| 0x78 | `UPDATE_TAGS` | `tags` | Registry tag lists (block, item, fluid, entity type, etc.); map of registry → array of (tag ID + value IDs) |
+| 0x46 | `RESOURCE_PACK_PUSH` | `add_resource_pack` | Push a resource pack to client: UUID + URL + hash + forced + optional prompt message (1.20.3: UUID-keyed; 1.20.5: stacks) |
+| 0x45 | `RESOURCE_PACK_POP` | `remove_resource_pack` | Remove a previously pushed resource pack by UUID (optional; clear all if absent) |
+| 0x4B | `SERVER_DATA` | `server_data` | Server icon (optional PNG bytes) + enforces-secure-chat flag (sent once at login) |
+| 0x6E | `TAG_QUERY` | `nbt_query_response` | Response to block/entity NBT query; transaction ID + NBT |
+| 0x04 | `AWARD_STATS` | `statistics` | Statistics update (category + statistic + value; varint array) |
+| 0x2C | `MAP_ITEM_DATA` | `map` | (See Inventory §) |
+| 0x3C | `PLAYER_COMBAT_KILL` | `death_combat_event` | (See Player §) |
+| 0x7A | `CUSTOM_REPORT_DETAILS` | `custom_report_details` | Key-value map sent to crash reports (1.20.5+) |
+| 0x7B | `SERVER_LINKS` | `server_links` | List of labeled URLs (bug report, feedback, support, etc.) shown in pause menu (1.20.5+) |
+
+### Serverbound
+
+| ID | ViaVersion name | mc-data name | Purpose |
+|----|-----------------|--------------|---------|
+| 0x2B | `RESOURCE_PACK` | `resource_pack_receive` | Client status for a resource pack UUID: accepted/declined/success/failed |
+
+---
+
+## Cross-links
+
+- **Slot type** (used in container packets): [`format-slot-and-components.md`](format-slot-and-components.md) — Slot encoding, item component NBT, 1.20.5 data-driven component format
+- **Entity metadata**: [`format-entity-metadata.md`](format-entity-metadata.md) — per-type metadata keys, value encoding
+- **Chunk data + lighting**: [`format-chunk-data.md`](format-chunk-data.md) — section encoding, palette, heightmaps, block entity list, sky/block light arrays
+- **Command graph**: [`format-command-graph.md`](format-command-graph.md) — node types, flags, parser IDs, redirect mechanism
+- **Version deltas**: [`../versions/1.21.md`](../versions/1.21.md) — what changed 1.20.5→1.21; [`../versions/INDEX.md`](../versions/INDEX.md) — full version map
+
+> **Note**: The `format-*.md` cross-link targets do not exist yet in this directory — they are planned deep-dive docs. Links will resolve when those docs are written.
+
+---
+
+## Version caveat
+
+Play-state packet IDs change **frequently** between versions. Examples of large shifts:
+
+| Version range | Notable shift |
+|---|---|
+| 1.19 → 1.19.1 | Chat signing added; PLAYER_CHAT restructured |
+| 1.20.2 | Configuration state added; START_CONFIGURATION 0x69 is new |
+| 1.20.3 | NBT chat components replace string; SET_SCORE/RESET_SCORE split |
+| 1.20.5 | Item components (data-driven Slot); cookies; resource-pack UUID stacking; SERVER_LINKS; CUSTOM_REPORT_DETAILS |
+| 1.21 (767) | No major new play packets vs 1.20.5; PROJECTILE_POWER (0x79) added |
+
+Always cross-check IDs against `minecraft-data/data/pc/<version>/protocol.json` or the ViaVersion `ClientboundPackets<version>` enum for the target version.