pc 26.3: protocol and data fixes for 26.3 (stacked on #1300)

[DallasCarraher]

Summary

Protocol and data fixes that make pc 26.3 (protocol 777) usable end to end. With the full stack applied, mineflayer logs in, completes configuration, spawns, and stays connected on a real 26.3 Realm and a vanilla 26.3 server. It tracks entities and players, loads chunks and light, and handles inventory, recipes and advancements without PartialReadErrors.

Every fix was found in live testing and confirmed by decompiling the official 26.3 server jar (javap -c -p on the relevant STREAM_CODECs and registration order), not inferred from captured bytes alone.

State of this PR (2026-09-23)

• Stacked on 🎈 Add Minecraft pc 26.3 data #1300 (the pc_26_3 scaffold), which needs regenerating against current master now that 26.2 (Add Minecraft PC 26.2 data (protocol 776) #1298) has merged. Once it is, I'll rebase this branch onto it as asked, one update PR at a time.
• Until that rebase, the commit list also shows:
  • the pre-merge 26.2 commits from the branch this started from (c9acdcec…2003e226, 03d96de1, merge c8823767); those are superseded by Add Minecraft PC 26.2 data (protocol 776) #1298.
  • ebd0242e (clientTickEndPacket feature), which belongs to Add clientTickEndPacket feature flag (1.21.3+) #1304.
• CI (build (24)) is green against master as of 924e26d6.

Fixes

Packet IDs and packet layouts

• Login packet_success: added the missing sessionId: UUID.
• Configuration-state IDs: added post_effects at 0x0a, shifting store_cookie through code_of_conduct. Before this, select_known_packs was read as custom_report_details and the connection stalled forever.
• Play-state IDs realigned to GameProtocols registration order (144 clientbound, 69 serverbound), with schemas for the 5 new packets.
• accept_teleportation (serverbound teleport_confirm) now carries x/y/z/yRot/xRot. Consumer side: Send resolved position/rotation in accept_teleportation for 26.3+ mineflayer#4125.
• packet_login (play): added onlineMode: bool between worldState and enforcesSecureChat. Reported by @maebahesioru against Paper 26.3.
• packet_advancements: PositionedAdvancement x/y moved to be siblings of key/value, and the stale displayData.xCord/yCord removed.
• packet_world_particles: particle moved first, three max-speed floats added, count is a varint, and a trailing randomizationType enum added.
• Stepped entity movement: rel_entity_move/entity_move_look use a new entityDelta type (reader in pc 26.3: add entityDelta type for the new stepped entity-move encoding node-minecraft-protocol#1538), and sync_entity_position uses the new PositionPath (linear or stepped).

Light data

• All four light masks are now ByteBufCodecs.BIT_SET = readByteArray → BitSet.valueOf(byte[]) (a varint count of bytes, not longs), on both map_chunk and update_light. update_light was missed at first. Its masks decoded as i64, which either raised a PartialReadError or handed BigInt values to prismarine-chunk and killed the connection. Consumer side: pc 26.3: read/write light-section masks as byte arrays, not long arrays prismarine-chunk#334.

Registries and enums

• entityMetadataEntry types follow EntityDataSerializers.registerSerializer(...) call order (not declaration order). New entries: optional_living_entity_reference and dye_color.
• SlotComponentType reordered to the 122 components DataComponents registers (every id from 40 up had shifted). pot_decorations is now four option<ItemStackTemplate>. Added attack_animation, interact_animation, cushion/color, waxed, sulfur_cube_content, villager_food, mob_visibility and sign_text_front/back; removed map_color.
• Particle type mapper rebuilt from ParticleTypes (128 entries, with the new geyser variants).
• SlotDisplay tag is an IDSet, not a string.
• ItemBlockProperty minValue/maxValue are option<string>. An open-ended range desynced the stream and dropped the connection.
• hand fields are main_hand/off_hand mappers, and entity_action uses Mojang's action names, matching master's pc/26.1: map every InteractionHand field to main_hand/off_hand #1278/Fix PC protocol enum inconsistencies in difficulty, game-state reasons, and entity actions packet fields #1295 for 26.1. The bytes on the wire are unchanged.

Data files

• entities.json regenerated from EntityTypes registration order (161 entries; player is 159).
• items/blocks/foods/recipes/blockCollisionShapes regenerated for 26.3's 121 new items and 90 new blocks, using the server's --reports registries.
• The rest of the stale dataPaths.json 26.3 row repointed from 26.1 to 26.2.

Features

• playerActionHasChangeDestroyDirection (26.3): CHANGE_DESTROY_DIRECTION was inserted at id 1 of the player-action enum. Consumer side: pc 26.3: use the shifted player-action ids for digging and releasing the held item mineflayer#4146.

Build hygiene

• 26.1, 26.2 and 26.3 each have a frozen proto.yml, and protocol.json is the direct npm run build output. 26.1's frozen yaml includes master's post-freeze changes (pc/26.1: map every InteractionHand field to main_hand/off_hand #1278, Fix PC protocol enum inconsistencies in difficulty, game-state reasons, and entity actions packet fields #1295), and features.json is sorted.

Known gaps

• block_transformer, compostable, cooking_fuel, brewing_fuel and provides_pottery_pattern have correct ids but no codec yet (they read as void). An item carrying one will desync.
• Field names for villager_food and sign_text_* are guesses. Their types and order come from bytecode.
• The new items' and blocks' hardness, shape and stack size are copied from analogues, so they're approximate. No recipes exist yet for the new items.
• playerActionHasChangeDestroyDirection is gated to 26.3 only, because 26.1/26.2 are unverified.
• On 26.1–26.3, mineflayer's elytraFly still sends start_elytra_flying, which no longer exists after Fix PC protocol enum inconsistencies in difficulty, game-state reasons, and entity actions packet fields #1295's rename. It needs Handle standardized minecraft-data entity action mappers mineflayer#4120.

Test plan

• npm test in tools/js (schema validation, yaml↔json sync, audits) passes on the branch and on a trial merge with current master.
• Schema-level round trips (createSerializer/createDeserializer) for the advancements, ItemBlockPredicate, entity-delta and light-update changes. Replayed 379 captured packets, including a 72 KB advancements packet, with zero parse errors.
• Live on a real 26.3 Realm: full login, configuration and play; entity_metadata, advancements and recipe_book_add decode cleanly; nearby players link to bot.players.
• Live on a vanilla 26.3 server: particle and item-predicate cases, plus a 5-minute session with about 6,400 update_light and 9,900 map_chunk packets, 7 deaths and respawns, and zero decode errors.

🤖 Generated with Claude Code

[maebahesioru]

Tested this branch against a real Paper 26.3-8-dev server (protocol 777) and found two more packet differences that cause read errors on every connection. Both verified by decompiling the classes from paper-26.3.jar.

1. packet_login (play/toClient) — missing onlineMode

26.3 added onlineMode: bool between worldState and enforcesSecureChat:

ClientboundLoginPacket fields:
  playerId, hardcore, levels, maxPlayers, chunkRadius, simulationDistance,
  reducedDebugInfo, showDeathScreen, doLimitedCrafting, commonPlayerSpawnInfo,
  onlineMode, enforcesSecureChat

Without it, every login packet under-reads by exactly 1 byte:

Chunk size is 114 but only 113 was read ; partial packet : {"name":"login", ...}

Fix: insert {"name": "onlineMode", "type": "bool"} after worldState.

2. packet_advancements (play/toClient) — elements are now PositionedAdvancement

Each entry of advancementMapping gained x: f32 and y: f32:

public final class ClientboundUpdateAdvancementsPacket$PositionedAdvancement extends Record {
  private final AdvancementHolder advancement;
  private final float x;
  private final float y;
}

Without them the packet over-reads badly:

Chunk size is 293 but only 118 was read ; partial packet : {"name":"advancements", ...}

Fix: append {"name": "x", "type": "f32"}, {"name": "y", "type": "f32"} to the element container.

Result

After these two fixes (plus the sessionId and configuration-state ID fixes already in this PR), a 26.1-based mineflayer can log in to a 26.3 server, receive chunks (map_chunk x329), and walk around with correct ground detection — running for minutes without a kick.

Remaining known issue

packet_recipe_book_add still partial-reads (Unexpected buffer end while reading VarInt inside the IDSet of craftingRequirements). It is caught and skipped by the read loop so it doesn't break the session, but it's the last read error I haven't tracked down. If you already know the correct IDSet shape there, that would close the last gap.

Thanks for this branch — it saved me from writing the 26.3 data from scratch.

[maebahesioru]

Follow-up: 26.3 also needs its own entities.json (entity type IDs shifted)

Found while actually playing on a Paper 26.3-8-dev server (protocol 777).
pc/26.3 currently inherits entities from pc/26.1, but the entity type IDs
moved in 26.3, so spawn_entity decodes to the wrong entity.

I measured this by summoning each entity and reading back the spawn_entity
type field (matching the new entity against the pre-summon bot.entities
snapshot so ambient mobs don't pollute the result). 128 of 157 entities were
measurable, with zero duplicate IDs.

entity	26.1	26.3 (measured)	delta
cow	30	30	0
donkey	36	37	+1
egg	39	40	+1
ender_dragon	43	44	+1
experience_orb	49	50	+1
item	71	72	+1
skeleton	115	118	+3
wither_skull	147	151	+4
wolf	148	152	+4
zombie	150	154	+4

Shift boundaries look like ID 33-36 (+1), 146-147 (+4), 149-150 (+5).

Symptom

Items lying in the world decode as item_display instead of item, so they
never appear in bot.entities and collect_item-style logic can never see
them. entity_metadata is affected too (e.g. particle → sonic_boom values
misalign and trigger PartialReadError).

Also: packet_recipe_book_add

The IDSet inside RecipeDisplayEntry.craftingRequirements still partial-reads
(Unexpected buffer end while reading VarInt). Since RecipeDisplayEntry's
field list matches the decompiled class otherwise, I suspect the IDSet
(HolderSet) shape rather than the entry itself. I worked around it by replacing
the packet's type with restBuffer (keeps the packet ID mapping intact, just
discards the body) — login, chunks, movement and entity sync all work with that.

Happy to open a PR with the full measured table and a patched pc/26.3/entities.json
(putting the 29 non-summonable entities into the remaining free IDs) if useful.
Thanks again for this branch.

[DallasCarraher]

Pushed a follow-up commit (0604243) fixing the `packet_advancements` schema properly.

The previous commit in this PR (2fc2152) correctly identified that PositionedAdvancement adds an x/y pair, but placed the two floats in the wrong spot: appended inside the Advancement container (after sendsTelemtryData) while the old xCord/yCord fields were still left inside displayData. That duplication caused a catastrophic misalignment on the next advancements packet in live testing (PartialReadError: string field expecting a size >1MB).

Re-decompiled the 26.3 server jar end to end this time (ClientboundUpdateAdvancementsPacket, $PositionedAdvancement, AdvancementHolder, Advancement, DisplayInfo, AdvancementRequirements, AdvancementProgress, CriterionProgress STREAM_CODECs) to get the full picture:

• added is List<PositionedAdvancement>, and PositionedAdvancement.STREAM_CODEC = composite(AdvancementHolder, x: f32, y: f32) — x/y are siblings of the advancement entry (key/value in the existing schema shape), not fields inside it.
• DisplayInfo.STREAM_CODEC has no x/y at all — xCord/yCord were stale leftovers from an older layout.
• Advancement, AdvancementRequirements, AdvancementProgress, CriterionProgress were all re-checked against the current schema's requirements/progressMapping/criterionProgress and match, so those were left untouched.

Verified with a schema-level round-trip test (serialize a sample advancements packet through the fixed schema, then deserialize it) — the buffer is now fully consumed with no PartialReadError. Full live-connection verification is currently blocked by the unrelated recipe_book_add IDSet parsing bug also being tracked in this PR's branch (it throws earlier in the packet stream and desyncs everything downstream); will re-verify against a live server once that lands.

[DallasCarraher]

Pushed fixes for the two fully-specified items from the review above (thanks @maebahesioru):

• packet_login (play/toClient): added the missing onlineMode: bool between worldState and enforcesSecureChat.
• packet_advancements (play/toClient): appended x: f32 / y: f32 to each advancementMapping entry (PositionedAdvancement).

Not included yet: the 26.3 entities.json ID shifts (waiting on the full measured table, since the sample in the comment covers only 10 of 128 entities) and the packet_recipe_book_add IDSet shape (still unresolved).

About the failing build (24) check: it was already failing on this branch before these commits (red on ebd0242e as well as 2fc21525). Running npm test in tools/js locally reproduces:

Error: 26.3 (26.3) / protocol.json is desynced from yaml, please run 'npm run build'

I'm deliberately not running npm run build and committing the output. data/dataPaths.json points pc/26.3's proto at pc/latest/proto.yml, which has drifted well past 26.3 (it already contains unrelated newer content such as sulfur_cube_content and shifted particle tables). Regenerating pc/26.3/protocol.json from it would overwrite the 26.3-specific packet layout in this PR, including the sessionId, configuration-state and onlineMode/advancements fixes, with a mix of stale and too-new data.

The real fix is deciding how pc/26.3 should source its protocol definition, for example by giving it its own proto.yml seeded from the current protocol.json like pc/26.1 and pc/26.2 have. I don't think this PR should make that call unilaterally, so I'd appreciate a maintainer's input on the preferred approach.

[extremeheat]

I merged #1298 for 26.2 ; in general we should focus on one update PR at a time as otherwise things get quite complicated

The pc_26.3 scaffold PR #1300 will need to be regenerated after 26.2 is merged to be inline with latest master

[DallasCarraher]

Thanks @extremeheat, understood on one update PR at a time. I'll hold off on further changes here and rebase this onto the regenerated pc_26.3 scaffold (#1300) once 26.2 is in and the scaffold is refreshed against latest master.

Since this PR is stacked on #1300, the build (24) failure (yaml desync and the version-regression audit) looks like it should be resolved by the regeneration rather than by anything in this PR, so I'm not pushing a fix for it here.

[DallasCarraher]

Pushed three more commits to this branch (heads-up, since I'd said I'd hold off until the rebase onto the regenerated #1300 scaffold; these are all fixes found live against a real 26.3 Realm and the local 26.3 server, and I'll rebase the whole stack once #1300 is refreshed):

• 6507f06e — entity metadata ids + data component ids. (1) entityMetadataEntry's type mapper was numbered by the declaration order of EntityDataSerializers; wire ids follow the registerSerializer(...) call order (e.g. boolean=8, particles=17, villager_data=18, pose=20). This corrects the earlier renumbering in 4f521880 and stops PartialReadError on every villager/player entity_metadata packet. (2) SlotComponentType had 110 entries but 26.3 registers 122 data components, shifting every id from 40 on; reordered to the DataComponents register order, added the codecs readable from bytecode, and re-encoded pot_decorations as four Optional<ItemStackTemplate>. That was the remaining cause of the PartialReadError on the ~70 KB advancements packet. Five newer components (block_transformer, compostable, cooking_fuel, brewing_fuel, provides_pottery_pattern) have correct ids but no codec yet. All confirmed with javap on server-26.3.jar; recorded packets replay with 0 parse errors.
• 49f8409d — regenerate items/blocks/foods/recipes/blockCollisionShapes for 26.3. 26.3 inserts 121 items and 90 blocks mid-registry, shifting later ids (iron tools decoded as light blue dye). Generated from the server jar's --reports registries; note attributes for the new entries are approximate (hardness/shape/stack size derived from analogues).
• 06d6aaff — playerActionHasChangeDestroyDirection feature flag (26.3 inserts CHANGE_DESTROY_DIRECTION at id 1 of the player-action enum, shifting abort/finish-dig and release-use-item).

Happy to split these into separate PRs if that's easier to review.

[maebahesioru]

Thanks for pushing the fixes and for the credit — I've been following the commits.

On the remaining entities.json ID shifts: I still have the measured spawn_entity type IDs from my testing (summoned each entity on a Paper 26.3-8-dev server and read back the type field). Happy to share the raw data or open a follow-up PR with a corrected entities.json for pc/26.3 if that would help — just let me know.

Makes sense to hold off until #1300 is regenerated before rebasing the stack.