Documentation
¶
Overview ¶
Package versions holds one protocol table per Minecraft version.
What is generated and what is not ¶
Most of each version_<v>.go is generated by internal/gen/genversion.mjs from minecraft-data: packet ids, entity and item names, block-state classification, chunk framing. Those files say DO NOT EDIT and mean it.
Three fields in them are *not* generated by that tool, because minecraft-data does not carry the data: ComponentIDs, SlotDisplayIDs and Components. The first two come from internal/gen/gencomponents.mjs, which reads the server's own registries report; the third is written by hand from measurements taken against a running server of that version.
That split is a trap, and this comment exists because of it. Regenerating a version file with genversion.mjs will drop those three fields, and dropping them does not break the build — it silently turns component decoding off for that version. TestEveryVersionCarriesComponentTables is there to make that loud rather than silent, and re-adding them means re-running gencomponents.mjs and restoring the Components literal.
Support status ¶
26.1 full. Every payload shape in understudy/components.go was read off
a 26.1 server, so it is the version the others are measured against.
26.2 full. Components and the recipe book both decode whole: twenty
items covering every encoding that differs elsewhere replay with no
truncated window, and the book reads 1009 recipes. Thirty-two
component ids moved from 26.1 and no payload shape did.
1.21.11 full. Components and the recipe book both decode whole: 130 items
replay with no truncated window, and the book reads all 1443
entries.
1.21.4 components only, and not a target. They decode — 56 items replay
clean — but the recipe book stops at entry 102 of 1358, and that is
deliberately left. The version is old enough not to be worth the
remaining archaeology. Client.MissingRecipes reports the shortfall
so a half-decoded book cannot be mistaken for a small one.
Versions and releases ¶
The set of Minecraft versions a build speaks is a property of the build, not of the tag: one binary carries them all and picks by the server-list ping. Release tags are therefore ordinary Go semver — they have to be, since the module proxy accepts nothing else — and the Minecraft support matrix lives in the release notes, in the status list above, and in `understudy-client -versions`, which prints what the binary in your hand can actually talk to.
Two conventions give that matrix semver weight:
- Adding a Minecraft version is a minor bump. Nothing that worked stops.
- Removing one is a major bump. Someone's server is on it.
Carrying all four costs about 1.3 MB of binary and 1 MB of resident memory, measured, which is why there is no per-version build and no build tag to exclude one. Auto-detection is worth more than the megabyte.
Adding a version ¶
- node internal/gen/genversion.mjs <minecraft-data> <version> <out.go> — or, when minecraft-data has not shipped the version yet, first run internal/gen/reports-to-mcdata.mjs to build its input from the server's own reports. That is how 26.2 was added: minecraft-data had no 26.2 in either the npm package or the repository.
- Run that version's server with --reports, then node internal/gen/gencomponents.mjs <registries.json> <version> <out_components.go>
- Measure the component encodings against a running server and fill in Components. Do not copy another version's: 1.21.4 and 1.21.11 disagree with each other as much as either does with 26.1.
Leaving Components nil is a valid answer. It means components refuse to decode on that version, which costs a partial window and reports why — where guessing costs a desynchronised one that reports nothing.
Source Files