Items, Inventory, and Crafting

This chapter's thesis: the architectural history of the item system is a history of "technical follows the community" — hardcoded recipes yielded to data-driven ones, free-form NBT yielded to components, and every step came after players had used items beyond what the officials imagined, forcing the architecture to ratify it after the fact. Items are the primary carrier of player property, so changes to their format are migration hell by nature. If componentization had happened in a parallel world with no mod-ecosystem pressure — merely for the officials' own tidiness — this thesis's causal chain would be wrong.

1The problem

Start by examining one specific sword. It is called "Invincible Artifact"; it carries Sharpness V, its durability is down to a third, and it bears the signature of a friend's ID from some server, three years back. In a player's eyes it is a piece of property with a story (the design volume's case that items are carriers of stories is made in Crafting, Items, and Inventory). In data's eyes, what is it?

The answer to that question has changed three times in fifteen years, and each change forced every server save, mod, datapack, and tool site on the network to move house along with it. The item system is the best specimen of this book's thesis that "architectural debt and design freedom share one source": it is the data players touch most often (added, removed, changed, queried every minute), the data most sensitive to format (every entry is somebody's property), and the interface densest with community creation (the disaster zone of mods and datapacks). Three identities stacked on one another make up this chapter's entire tension.

2Why items are hard to migrate

First, the root of the difficulty. When the world's terrain changes, players curse a little and accept it (the storage chapter showed the seam where old terrain meets new); but when an item changes, players feel robbed — if "Invincible Artifact" arrived at its new home as a plain iron sword, three years of play have been partly voided.

So the iron law of item migration is far harsher than the one for terrain: terrain may be "reinterpreted"; items permit only a "lossless move". The difficulty of the lossless move lies in two properties of item data. One, every item can be different: two swords of the same diamond-sword type differ in enchantments, durability, name, and lore — they cannot be "same-type compressed" the way stone blocks can; each piece must be preserved faithfully. Two, the shape of the data is defined by its users: the fields the officials open on items, the community (mods) will stuff with private cargo of its own — your migrator must not only recognize official fields but understand all manner of third-party ones. The heaviest share of save compatibility (the converter of Storage and Serialization) walks into its narrowest alley right here.

3Stacks, NBT, and the era of free parking

The basic unit of items is the item stack: identical items pile up in one stack, generally capped at 64. A dirt block picked up empty-handed and a fully enchanted god-sword are, structurally, the same thing: one record of "type + count + extra data". The first two parts are simple; all the trouble lives in the third.

The carrier of the extra data is NBT (the storage chapter described this format of "storage boxes with labels"). A stack hangs an NBT tag off itself, and inside it can ride durability loss, an enchantment list, a display name, lore text — structurally a parking lot you pull into at will. In official hands the design was restrained: durability, enchantments, name — a few fixed spaces. But a parking lot that does not number its spaces lets anyone park: mods stuff an energy value for their wands into the tag, datapacks stuff quest progress, server plugins stuff ownership marks — one and the same lot, with every household painting its own space lines.

The cost of free parking surfaced as the ecosystem grew. For the officials: item data became unpredictable — you cannot know what a tag will contain; one piece of bad data crashes the save on read, and network sync can only ship the tag wholesale (a chest of complex items makes a sync packet big enough to be wasteful). For the community: there is no schema — which field holds "energy value", of what type, whether negatives are legal, all of it up to the author's mood; the ghost stories of two mods happening to use the same field name and overwriting each other's effects are legion. The era of free parking was, in essence, "structurelessness traded for unlimited flexibility" — while the ecosystem was small, flexibility was honey; once it grew, structurelessness was arsenic.

One easily missed fact made the confusion worse: players used the inventory as a database. Museums of quest items, chests arranged by era, memorial walls — what players write onto items is not only enchantments but plot and commemoration (the design volume's "carriers of stories" lands at the data layer like this: those stories all live inside that structureless tag). The real load of item data therefore runs far past the official design imagination: it is an equipment system and a player's diary in one. What a format reform has to move was never "data" — it is diaries.

4Componentization: from free parking lot to named slots

In April 2024, version 1.20.5 completed the largest refactor in the item system's history: the free-form NBT tag was replaced by a system of "components"¹. The new rule fits in one sentence: every customizable property of an item is registered as a named component — durability is max_damage, enchantments are enchantments, the name is custom_name; each component has an officially defined structure, default value, and serialization rule, and an unused component simply does not appear.

Why did this have to happen? List the motives and every one of them points at the scale of the community ecosystem.

First, predictability is an ecosystem's oxygen. Datapack and mod authors need the promise that "this field is always called this and is always this type" — a free parking lot cannot support ten thousand merchants. Named slots turn the component into an interface that can be documented, validated, and collaborated on across works: this is the officials' own format done mod-style, one step further toward the system layer than datapacks.

Second, the bandwidth-and-sync bill. Under the old system an item's tag traveled whole; under the new one, components sync on demand — a component that has not changed does not leave home. For servers with thousands of items in motion (the network tax described in the entities chapter), this is weight removed that you can feel.

Third, robustness. Named components can be validated: bad data is refused at the entrance instead of sneaking into the save and detonating at load time. The data converter described in the storage chapter finally has clean input coming in.

Componentization is a textbook case of "following the community": the mod scene long ago worked out that "named fields beat free-form blobs" (Forge's capability system and the various item-attribute schemes were its forerunners), and the officials completed the course at the vanilla layer. It is at the same time a data-layer footnote to the design volume's "constraints are depth" — give up structureless freedom, buy back a sustainable ecosystem — the same logic as when the piston was absorbed into the game.

5Data-driven recipes: following once more

The architectural history of recipes (how things get crafted) is a double of the same story. Early on, recipes were hardcoded in the program — to change "how many diamonds a diamond sword costs" you changed code; and a community that wanted to tune balance (servers do it constantly: vanilla recipes too dear or too cheap) could only write mods. The demand for data-driven recipes was fed to maturity entirely by community practice: years of recipe-customization features across the mod scene validated the conclusion "a recipe should be data, not code" thoroughly enough that the officials moved recipes into JSON around 1.12 and folded them into the datapack system with 1.13 — the design volume's account of officials ratifying community practice was completed nowhere more thoroughly than here.

The chain reaction that followed data-driven is worth recording: freed from the program, recipes at once became the most common entry point for datapack authors (change a drop, add a recipe — the Hello World of every datapack), and the balance tuning of modpacks (the curatorial design of the modpack chapter) became possible because of it — opening one craft to the public directly created an author class. Technical follows the community, and the community repays with prosperity: nowhere does this feedback loop draw a rounder circle than at the recipe.

6The window protocol: the inventory interface's authority ledger

The interaction interface for items (inventory, chest, crafting table) has an archaic name at the protocol layer: the window. The window protocol is the principle of "server authority" touching ground at the item layer (yet another expansion of this volume's opening three sentences): the inventory the client draws is only a rehearsal — you drag the diamond into the crafting grid and it snaps into place on screen, but the server does not recognize it; when you click the result, the client reports "what I did, in which slot of which window," and the server checks it against its own ledger (do you really have that diamond? is that slot really empty?) and only then sends down the authoritative outcome. The smoothness you see is a conspiracy between local rehearsal and server adjudication (a family member of this volume's "feel lies").

This design keeps item interaction honest over bad networks: the client may pretend; the ledger exists only on the server. It also explains, in passing, two things every player knows: why item-duplication bugs all live in "the gap between the server's ledger and the rehearsal" (the network-side cousin of the cascading-update bugs), and why a single renumbering of the window protocol itself (1.17 renumbered window IDs to start from 1) sent anti-cheats and container mods across the whole network rewriting code overnight — any revision of a page in the authority ledger is an affair of the entire ecosystem.

Inside the division of labor between rehearsal and authority hides a subtle economy of feel. The local rehearsal supplies "zero latency" — drag, place, take, all instant, the feel indistinguishable from single-player; the server's adjudication supplies "zero fraud" — no client, however clever, can conjure a diamond that was never in stock. The handover happens at the one click that actually "commits": everything before it is rehearsal; only after it is there an account. Players never need to know this double-entry bookkeeping exists — the best authority system is one you cannot feel — until someone tries to cross it and discovers that behind every slot stand a pair of eyes that trusts no one.

7Migration hell: the add-only interpreter

Now to total up "migration hell". The item format changed three times in fifteen years (raw NBT, the 1.13 Flattening, 1.20.5 componentization), and every change added a fresh layer of rewrite rules to the DataFixerUpper converter described in the storage chapter. That layer of rules lives under two iron laws: add only, never remove (a save from ten years ago must still be able to upgrade; not one old rule may be deleted) and lossless, piece by piece (this chapter's opening iron law). The converter has therefore grown into an archaeological stratum — each layer one era's item format, and any player's antique must be translated layer by layer into the present.

That is the complete meaning of "items are compatibility hell": the hell is not the technical difficulty of any one migration; it is that the debt can never be written off. Terrain may be reinterpreted and generation may swap algorithms; items alone must cross every architectural revolution intact, piece by piece — because they are not data, they are the container of player time and feeling. Componentization has landed, but no one dares promise it is the last change: as long as players keep writing stories onto items, the data carrier of those stories has to keep moving house.

8What this chapter leaves behind

• For players: your "Invincible Artifact" has moved house three times in the data world — each time intact — and behind that stands a translation system designed specifically for "the player's past".
• For developers: what you can take away is the "follows the community" roadmap — permit feral growth first (free-form NBT), and once the ecosystem has validated a usage, formalize the validated usage (components); plus the interface iron law that "named lists beat free-form fields". What you cannot take away is the mass of the migration debt: daring three revolutions of the item format is possible because behind them stands an add-only converter system and a corps of mod authors shipping compatible builds within 48 hours — a whole society's engineering capability.

注释

1. Minecraft Wiki, "Data component format" (from 1.20.5, item data moved from free-form NBT tags to a system of named components: components have officially defined structures and default values, and do not appear unless set), minecraft.wiki, retrieved 2026-09-18: see https://minecraft.wiki/w/Data_component_format . ↩