Introduction

Verified against Minecraft 26.3

Java Minecraft is one codebase that runs as two programs. The server is the world: a loop that ticks twenty times a second, owns every chunk, entity and block, and decides what they are — save a few things it takes from your client once it has checked them, chief among them where the player you control, and anything it steers, stands. The client is a window, a loop that draws frames as fast as vsync or the frame-rate limit allow, and a copy of the world it is told about — which it will happily change on its own and be overruled about. It ticks too, nought to ten times inside each frame, catching its own copy up to the same twenty-a-second clock and dropping any tick owed beyond ten. They talk over a real Netty connection even when both run in the same process — in singleplayer the connection never touches a socket, but the packets are real, and an IntegratedServer is a MinecraftServer with the client half attached rather than absent. The split is behind some of the first things a player notices: the client predicts and the server overrules; a chunk exists on the server long before the client is sent it; a sword swing is a packet, a hit is a reply.

flowchart TD
    subgraph Client["Render thread"]
        MC["Minecraft: a frame, 0 to 10 ticks in it"]
        CL["ClientLevel: the copy it is told about"]
    end
    subgraph Netty["Netty event loop"]
        Conn["Connection: socket or in-process"]
    end
    subgraph Server["Server thread"]
        MS["MinecraftServer: a tick every 50 ms"]
        SL["ServerLevel: the world, one per dimension"]
    end
    subgraph Pool["Worker-Main-n"]
        W["generation, lighting, meshing"]
    end
    MC --> CL
    MS --> SL
    MC -- "what the player did" --> Conn
    Conn -- "what the world became" --> CL
    Conn <--> SL
    W -. "chunks" .-> SL
    W -. "meshes" .-> MC

The two programs and the four threads they run on: the client and the server each own their copy of the world and talk through the connection, and the worker pool hands its results back, dotted, to whichever of them asked.

The whole thing is 7,301 source files and about 740,000 lines of Java 25. Just under a third of those lines is client-only; the rest ships in both jars, and the picture below is the split — orange is the client’s, blue is everything the dedicated server also ships, and the hatched boxes are the packages Part I’s what this book skips tours, most of them what this book leaves out.

The four boxes of the first picture are the four threads that carry nearly all of it — the Render thread, which is also the client’s game thread; the Server thread; the Netty event loop; and a shared worker pool, whose threads are named Worker-Main-n — and the first lecture of the book, Anatomy, is those four threads and the two loops.

How the book is read

This site is the notes for a video lecture series, and that is why it keeps saying watched where a book would say read. One system page is one lecture; the page stands alone and nothing on it leans on the video to make sense, but the order, the scenarios and the figures are all built for someone who will eventually be shown them. The site is that series in three tiers, and the sidebar is its table of contents.

Parts are watched in order. Thirteen of them, I to XIII, each a system: the anatomy of the two programs, the foundations they are both built out of, the server, the world, blocks, entities, items, the player, networking, the client, rendering, world generation, and commands. Each opens on a landing page that argues what its part claims about its system, says what shape the part is, names the parts it assumes and what it uses each of them for, lists its pages in the order to watch them, says where the part stops, and says which Reference pages the part reads. A page is one lecture’s notes: it follows one scenario through the system (a player walks east across a chunk boundary; a server is clicked in the list) and its figure is the artefact — a sequence diagram whose lanes are class names, a state machine, a flowchart of a decision. Every diagram enlarges on click. Each part only assumes the ones before it, and the lecture map says where that is not quite true. The picture below is the whole of that, drawn as the line it nearly is: the parts in watch order, and a solid arc from a part to each part that assumes it. The two dependencies the whole book leans on, whether or not a landing page lists them — Part I for the threads, Part II for codecs and registries — keep their boxes and the one arc each along the spine but have the rest of theirs left off, because those would reach almost every box, and the two dashed arcs are the only places a part assumes a later one, each cut on purpose rather than solved by reordering.

The thirteen parts top to bottom in watch order; an arc on the right runs from a part to one that assumes it, always downward, and the two dashed arcs on the left are the only places a part assumes a later one, each labelled with the pages it needs.

Maps are looked at once. The atlas is four views of the decompile — where the code is, where the mass is, what everything imports and what extends what. Each view’s figure and its table are regenerated on every deploy, so their numbers are re-derived each time; the prose around them is written by hand from those tables, or from the tree where no table holds a number, and is re-read when the version moves. It is the “where is everything” answer a newcomer wants before any system page makes sense.

Reference is looked up. Twenty-three pages, of which these are the ones a reader reaches for first: the glossary, the naming drift table, a class index that answers “which page talks about ChunkMap”, the diagram lanes and the threads. Thirteen of the twenty-three are rewritten from the decompile or from the corpus on every deploy, so their rows are re-derived each time; the other ten are hand-kept, and the shelf’s own front page says which is which. The rule for what belongs here is would a viewer pause the video to read this.

For agents, the whole site is one file: llms-full.txt, regenerated on every deploy.

The rules the book keeps

Names, never code. A page names classes, methods, fields and packages so that anyone with the decompiled source can find them in a minute, and explains what they own, when they run and how they interact. It never reproduces the source — not a method body, not a snippet. Anyone who needs the code decompiles the game themselves, which is also the line Mojang’s mappings licence draws.

Mojang’s names. Every game identifier is Mojang’s official mapping, which the decompile uses. Fabric’s Yarn names differ; where a modder would not recognise a class under its official name, the Yarn name is noted once. Names have moved since 1.21 — even since 1.21.11, Lightmap was LightTexture and RedstoneWireBlock was RedStoneWireBlock — and the naming drift table is the translation.

Newest version only. Every page that describes the game says in its header which release it was verified against, or for a generated view which release it was generated from, and the book’s is 26.3. There are no version-difference sections, and the only “in 1.x this was” on a system page is the For a 1.21-era reader note at its foot. When a release lands, every page is re-read against it, and until a page has been, its header still names the release it was checked against.

Verified means tested. Every backticked name on every written page, and every class name of more than one word and every member named with its class or its lane inside a diagram, is checked against the decompile of the release the page’s header names before the site publishes, every diagram is parsed by the same mermaid the site ships, every lane in every diagram is checked against the one key the whole book uses, and every link and anchor between pages is checked to land. A page that fails any of those does not go up, and neither does a change that puts the landing pages, the sidebar, the lecture map, the dependency figure and the Reference shelf’s own index of who uses it out of step with each other. That is a narrow guarantee, and it is worth stating narrowly: it proves the names are real in that release, not that the sentence around them is true. The sentences are what the passes are for. The book has been fact-checked against the decompile three times — as drafted, after the pages were restructured into the book you are reading, and again for this release — and a page written after the first check has had every check since. The first two times every page checked had something wrong on it, and the third found errors again in every part. What is left is a correction waiting to be filed, and the repository is where to file it.

How the system works, not how the code reads. Object-level: this class owns that state, this call happens on that thread, this packet is sent then. Never line-level. Code makes boring video and dates fast.

What this book skips

Most of what the treemap hatches is left out, and it falls into three kinds. Code that is version differences by definition — save migration, the util/datafix and util/filefix trees — which rule three excludes on sight. Code that is not the game — Realms, telemetry, the profiler, the management server, RCON, the data generators. And code that is the game’s bookkeeping rather than its behaviour — statistics, player reporting, and a package of id constants nobody will recognise. What this book skips, the second lecture of Part I, draws that boundary honestly — what each thing is, how big, whether the dedicated server ships it, and the two or three class names to start at if you need it anyway — so a viewer knows the edge of the map before investing in thirteen parts. It also tours three things that are not skipped and are only surprising for where they live: the OpenAL backend, which sits in Blaze3D beside the window and RenderSystem rather than in the client’s sound package; the recipe book, which sits in the statistics package and belongs to Part VII; and the debug-drawing API every debug renderer in the game is now written against.

Unofficial, and free to reuse

This is an independent description of how the game works. It is not endorsed by, sponsored by or associated with Mojang Studios or Microsoft, and Minecraft is a trademark of Mojang Synergies AB.

The book is CC BY-SA 4.0: take it, adapt it, teach from it — credit minecraftdocs.dev and keep what you build under the same licence. That covers the writing and the figures, which are the only things here that are anyone’s to license. It does not cover the game, its source, its assets or Mojang’s mappings; none of those are in this book, which is why it names identifiers and never reproduces code. Corrections, and the repository the book is written in, are on GitHub.

The atlas

Verified against Minecraft 26.3 · Maps · Four views of the whole decompile, drawn by tools/map_source.py from the source tree on every deploy.

Before any system page makes sense you want the answer to a newcomer’s question: where is everything? The atlas is that answer, looked at once. Each map is one or more figures drawn from the decompile, prose saying what they show, and the tables they were drawn from — four figures and two tables on what extends what, one and one on the two bar charts, one and three on where the code is. Take them in any order; none of the four needs another.

No number in the atlas’s figures and tables is counted by hand — they come from tools/map_source.py, which reads all 7,301 files — but the four pages are not all one thing, and the distinction matters as much here as on the Reference shelf. The figures and the tables are generated: they live in src/generated/, are rewritten on every deploy, and cannot drift from the source they describe. The prose is typed, and every number quoted in a sentence was typed by a session, read off one of those tables or counted from the tree where no table holds it. So a version bump re-derives the tables by itself and leaves the sentences around them to be re-read, which is what the version pass is for.

flowchart LR
    D[("the 26.3 decompile")] --> T["map_source.py, on every deploy"] --> G["seven figures, seven tables"]
    G -- "included as they are" --> P["the four map pages"]
    G -- "read and typed by a session" --> S["the sentences"] --> P
    D -. "or counted from it where no table holds the number" .-> S

The two routes into an atlas page: the figures and tables arrive by the upper one and cannot drift, and the sentences arrive by the lower one, typed by a session, which is the route a version bump has to walk again by hand.

The four maps

The treemap is also the book’s picture of the two jars: the introduction uses it to show how much of the code the dedicated server ships, and Part I’s what this book skips uses its hatching to draw the boundary of the book.

How the numbers are counted

The decompile is the client jar, which is a strict superset of the server jar; beside it sits server-classes.txt, the list of classes the dedicated server also ships. From those two things every number on these pages follows.

The line counts include what the decompiler adds — braces on their own lines, expanded switches — and a table of constants written a line apiece can be longer than a class that does something. Read length as where the reading is, not where the difficulty is.

Rules: names, never code · how the system works, not how the code reads · newest version only · every backticked name passes tools/verify_names.py.

Where the code is

Verified against Minecraft 26.3 · Maps · The jar as a treemap of packages: area is lines of decompiled source, colour is which jar ships the package, hatching is the packages Part I’s what this book skips tours.

Java Minecraft is 7,301 classes and 741,069 lines of decompiled Java 25, and the first surprise in it is how little of that the client owns alone. Everything a player sees — every screen, the HUD, the whole renderer, the entity models, both GPU back-ends, the sound engine, Realms — is the orange near-third of this picture. The blue seven tenths ship in both jars, and the biggest inner box, world/level, is a fifth of the game by itself: blocks, block states, chunks, lighting and world generation, all of it code the dedicated server runs with no window attached.

Two jars, one tree

The client jar is a strict superset of the server jar, and the split is clean: the 2,264 client-only classes live in exactly five packages — net/minecraft/client (1,891 classes), com/mojang/renderpearl (146), com/mojang/realmsclient (137), com/mojang/blaze3d (86) and net/minecraft/realms (4). Every other package in the table below ships in both jars, class for class; no sub-package at this depth is mixed. The client-only side is 220,818 lines, 29.8% of the total, which is the “just under a third” the introduction quotes.

The consequence for reading this book: when a page says a class is client-only it is saying which package the class lives in, and every package Parts IV and V own ships in both jars. The oracle for which side a class is on is server-classes.txt.

What the big boxes are

world — 42%. world/level (151,146 lines, 1,418 classes) is Parts IV, V and XII: chunks, block states, lighting and, under world/level/levelgen, most of world generation — world/level/biome is its sibling rather than part of it. world/entity (110,760 lines, 727 classes) is Parts VI and VIII: the entity hierarchy, its AI and the player. world/item and world/inventory (37,813 lines between them) are Part VII.

client — 24%. client/gui (59,594 lines) is the screens and the HUD, Part X; client/renderer and client/model (63,361 lines together) are the frame, section meshing and the entity models, Part XI; client/multiplayer (11,303) holds ClientPacketListener and ClientLevel, the client’s copy of the world. The 41 classes directly in net/minecraft/client — Minecraft, Options, KeyMapping, MouseHandler — are 10,821 lines on their own. (That 41 is the itself only count defined below; the 1,891 above is the package with every sub-package under it.)

util — 7%, two thirds of it skipped. util/datafix, util/filefix and util/profiling are 34,866 of the package’s 54,700 lines and are all outside this book; the hatched boxes are those three, and much the largest of them is the save-migration history. What is left is the toolbox every part uses — Mth, RandomSource, Util — and the parsing and debug packages.

server — 7%. server/commands (13,357) is Part XIII’s command implementations; server/level is 42 classes and 12,166 lines — 290 lines a class, nearly three times the map’s average, in a package small enough to list (ServerLevel, ChunkMap, ServerPlayer), Parts III and IV; server/network is the serverbound packet handlers, Part IX; server/packs is the pack system, Part II; server/jsonrpc, the management server, is skipped.

renderpearl and blaze3d — 4%. The GPU abstraction, com/mojang/renderpearl, has two back-ends behind GpuDevice, and the Vulkan one (renderpearl/backend/vulkan, 7,387 lines) is larger than the OpenGL one (renderpearl/backend/opengl, 5,815); com/mojang/blaze3d keeps the window, the frame graph, the vertex formats and RenderSystem.

network — 3%, in 416 classes. network/protocol is 298 classes in 12,872 lines: the packet catalogue is many tiny classes, one per packet. network/chat (4,799) is Component and chat signing.

Below 3% the other boxes include Part II’s foundations — net/minecraft/core, net/minecraft/nbt, net/minecraft/tags, net/minecraft/resources — and Part XIII’s net/minecraft/commands (the command source, the argument types and the execution engine) and net/minecraft/advancements, plus com/mojang/realmsclient and the skipped net/minecraft/data. That last one is the program that writes the vanilla data pack — and it is not build-time only: the dedicated server ships all 174 classes, and Blocks and MinecraftServer both read data/worldgen constants at run time (what this book skips sorts every such reader into three kinds).

Where each part lives

The parts follow the tree, but not one box each. This table is the map from the book’s order to the jar’s, and it is the one table on this page that is a decision rather than a measurement: the packages are assigned by hand, in the tool that draws the atlas, and the counts follow. A package under net/minecraft is written without that prefix; itself only means the files directly in the package and not its sub-packages; a package two parts share is counted in both and a file in no part’s packages in none, so the total row is not the jar’s. A landing page that states its part’s size quotes its own row of this table, and the hatched packages and player reporting are left out of every row.

The table

Depth three is the outer boxes of the treemap; depth four is the inner ones. client-only counts the classes not in server-classes.txt.

Rules: names, never code · how the system works, not how the code reads · newest version only · every backticked name passes tools/verify_names.py.

Where the mass is

Verified against Minecraft 26.3 · Maps · The forty largest classes by lines of decompiled source, the top thirty of them drawn, coloured by which jar ships them.

The two largest classes in the game are the top of one hierarchy: Entity and LivingEntity, 9,078 lines between them, the thing every mob and player is before it is anything else. Third is Minecraft, the client itself. And then the list turns odd: two of the top ten are not game logic at all. BlockModelGenerators runs only inside the data generator — its single caller is ModelProvider — and writes the block model JSON that ships in the jar; BlockStateData is a table that the save-migration fixes consult when data a much older version saved is read, and nothing outside util/datafix reads it. Size is where the reading is, not where the game is.

64,082 lines are in these thirty classes, 8.6% of the game in 0.4% of its files.

Three kinds of big

Read down the bars and twenty-four of the thirty sort themselves into three kinds, and the kind tells you how to read the class.

The god objects. Entity and LivingEntity are the trunk, each over four thousand lines because each is the base of everything below it. The fork below them is not one chain: Mob is one of LivingEntity‘s direct subclasses and Avatar is another, with Player under it and ServerPlayer and LocalPlayer its two leaves in the thirty (entity anatomy has the tree). Those two leaves are long for the opposite reason to the trunk: no named class descends from either, and each is a whole side of the authority split written out. Minecraft and MinecraftServer are the two programs’ roots; ServerLevel is the world; ChunkMap is the world’s loader. Only two concrete mobs make the thirty — Fox and Bee, the two with the most bespoke behaviour in their own files — and what they are long with is per-species goal classes, which is exactly why Part VI explains the machine and declines to enumerate its instances: there is no Fox page and there is not going to be one.

The switchboards. ClientPacketListener is a handler method for every clientbound play packet, and ServerGamePacketListenerImpl is the same for every serverbound one — all but three of the packets both phases share are handled one class up, in ClientCommonPacketListenerImpl and ServerCommonPacketListenerImpl; between them they are the whole of what play can say, which is why Part IX’s pages keep coming back to them. FriendlyByteBuf is the buffer their packets are read from.

The catalogues written as code. SoundEvents, Blocks and Items are registries populated a constant at a time, and CreativeModeTabs lists every tab’s items a line apiece; DataFixers is the migration history; OceanMonumentPieces and StrongholdPieces are structures built by hand, room by room, in Java rather than in a template; Options is every setting in options.txt, and Hud is the in-world overlay — the crosshair, the hotbar, the bars — inside the wider Gui that also draws screens, toasts and the loading overlay. These are long because they are lists. None is hard.

The table

Forty rows, of which the figure draws thirty. side is which jar ships the class.

Rules: names, never code · how the system works, not how the code reads · newest version only · every backticked name passes tools/verify_names.py.

What everything imports

Verified against Minecraft 26.3 · Maps · The thirty most-imported Mojang classes: how many files name each one in an import statement.

One file in six imports BlockPos. That is the least surprising fact on this page; the next one is not. The chart counts Mojang imports only — net.minecraft and com.mojang — because the JDK’s List and the nullability annotation outrank everything on it and say nothing about the game. Under that rule the second most-imported type is not Minecraft’s: it is Codec, from Mojang’s DataFixerUpper library, imported by 943 files, with MapCodec sixth and RecordCodecBuilder seventh. Three of the seven classes the game most depends on are the serialisation vocabulary that turns objects into NBT and JSON and back, which is why Part II teaches codecs before anything a player can see.

Seven ideas, and where the book teaches them

The hubs are not thirty ideas; twenty-five of them are seven. The table below groups them, reading down the sixty rows rather than the thirty the figure draws, so that a family is not broken in half by the cut-off — ByteBufCodecs and PacketType are the wire’s vocabulary whether or not they clear it. So the table holds thirty-two names: twenty-five of the thirty, plus seven more from ranks 31 to 60 that their families would be incomplete without. The five of the thirty it leaves out are the two paragraphs after it, two and three.

Part II teaches three of the seven, Reference two, Part IX one, and the seventh — the world’s nouns — is the rest of the book. That is the more useful fact than Part II teaches the vocabulary: the classes a reader must know are not one part’s worth.

Two of the thirty belong to no family and get no row above, and neither does the first class after them; each is worth a look. Minecraft (284) is thirty-first, the first client-only class on the list and just outside the figure — the client’s hub is a hub for the client-only side alone, which is under a third of the files, and the shared seven tenths never name it. And Schema (404) and DSL (289) are the migration tree talking to itself: all but ten of the files that import Schema are in util/datafix, and the ten are its sibling util/filefix. One pair inside the table earns the same second look: ServerLevel (735) is imported by nearly as many files as Level (761), because most code that touches the world knows it is on the server and says so in its types.

The remaining three of the thirty have no row either. LogUtils (488) is Mojang’s logging library, the one line at the top of a class that keeps a logger. Util (457) is where the executors and the static odds and ends live (threads) — a hub because it is where the unclassifiable went, not because it is an idea. And BlockBehaviour (313) is the world’s nouns seen one class higher — the same one-class-higher shape what extends what draws for the Block tree.

What the count misses

An import is counted once per file, so the chart says how many files name the class, not how often. It also undercounts every class used inside its own package, because that needs no import: the 260 files that import Block are the files outside world/level/block that use it, and the same is true of BlockBehaviour and Minecraft. A class’s true reach is this number plus its package.

The table

Sixty rows, of which the figure draws thirty. side is which jar ships the class, or library for a class outside the decompile.

Rules: names, never code · how the system works, not how the code reads · newest version only · every backticked name passes tools/verify_names.py.

What extends what

Verified against Minecraft 26.3 · Maps · The widest inheritance trees, four of them drawn with the number of descendants on every branch.

Block has 297 descendants and Entity 192 — descendants, not direct subclasses, which is the count both tables below use — and those are the two trees a reader of this book will climb most often. But neither is the widest hierarchy in the game. That is FeatureElement, with 386 descendants from seven implementers — and it is not a hierarchy at all. It is an interface for anything that can be put behind a feature flag, and its seven implementers are BlockBehaviour, Item, EntityType, MenuType, MobEffect, Potion and GameRule, so its descendant count sweeps up the whole block tree and the whole item tree at once. ItemLike, second at 366, is Block plus Item. The interface table is a list of which mix-ins reach furthest; the class table is where the real trees are, and four of them are drawn below.

Entity

The shape is a spine with a few branches. LivingEntity holds 124 of the 192, Mob 114 of those, PathfinderMob 108 of those: nearly every mob is four classes deep before it is a species, and Part VI’s entity anatomy is that spine. The non-living entities are two families and a scattering — Projectile (26) and VehicleEntity (15), then hanging things, displays, and thirteen direct subclasses of Entity with no children of their own, from ItemEntity to LightningBolt.

Block

Block is wide and shallow: 92 direct subclasses, most of them terminal. The one deep branch is BaseEntityBlock (64), the abstract base most of the blocks that own a block entity extend — the interface that actually decides is EntityBlock, and two blocks implement it without taking that base at all, ComparatorBlock and JigsawBlock. Part V’s block entities is the branch in prose. The table’s first row, BlockBehaviour at 298, is the same tree seen from one class higher — Block is its only subclass, and it exists so that a block’s behaviour and its registry identity can be separate classes.

Item

Sixty-seven types descend from Item, for over a thousand registered items. The tree is small because an item’s behaviour mostly is not in its class: what a stack does is in its data components, and Items registers most of the game as a plain Item or BlockItem with an Item.Properties describing it. Part VII’s items and stacks is why the tree is this shape.

Screen

Screen (161) is Block’s shape again — 71 direct subclasses, 59 of them terminal — with one deep branch, AbstractContainerScreen (27), the screens that show a menu (GUI and screens is Part X’s), and one branch that is not in this book, RealmsScreen (27). The row above it in the table, AbstractContainerEventHandler at 162, is Screen’s parent with Screen as its only subclass, the same one-class-higher effect as BlockBehaviour.

Two trees the table shows and the figures do not

Goal has 202 descendants from 99 direct subclasses, and 132 of the 202 are nested classes, all but one inside the mob they serve — a fox’s own goals are declared in Fox, not in world/entity/ai/goal. Packet is an interface with 240 descendants from 229 direct implementers, and almost nothing below them: the packet catalogue is flat, and the packets reference is its list.

The tables

Class roots first, then interface roots; each table is the thirty roots of its kind with the most descendants. direct is the number of immediate subclasses or implementers; where is the package of the root.

Rules: names, never code · how the system works, not how the code reads · newest version only · every backticked name passes tools/verify_names.py.

I · Anatomy

Verified against Minecraft 26.3 · Part I · The whole program at once: which threads exist, which loop each runs, and how the two halves talk.

Part I is the program the other twelve parts run inside. Java Minecraft is one codebase running as two programs — a server whose whole life is a tick loop, and a client whose life is a frame loop with ticks inside it — on four threads worth memorising: the Render thread, which is also the client’s game thread; the Server thread, which is the world; the Netty event loop, which carries the packets (Netty is the networking library both halves use); and one shared worker pool that chunk generation, the server’s lighting and section meshing all queue onto. A player recognises the split by its symptom, the game that keeps drawing while the world stands still, and the book returns to it wherever the two halves disagree, as when a broken block comes back for a moment. Read this part first for the plainest reason there is: nearly every lane in every sequence diagram after it is a class that runs on one of these threads, and the ten that are not a class are a thread, the process, the wire, the disk, the session service or the game’s own code.

The shape of the part

Two pages: what the program is, and where the book stops. The first is a trace and the second is a boundary, and the boundary is drawn second because a reader decides whether to go on once they can see the whole program.

flowchart LR
    A["1 · Anatomy<br/>a trace: four threads, two loops, one wire"]
    B["2 · What this book skips<br/>a boundary: where the book stops"]
    A -- "the program first" --> B

The part’s two lectures, numbered to the watch order. The arrow is a dependency, not a call: the boundary means nothing until you can see the program it is drawn around.

Before you start

Nothing. This is the first part, and it assumes only that you have played the game.

Watch in this order

1. Anatomy — from main to a running singleplayer world: the Render thread that is also the game thread, the Server thread that is the world, the Netty threads that run more than bytes, and the one CPU pool that chunk generation, the server’s lighting and section meshing all share.
2. What this book skips — the boundary, drawn honestly on the treemap of the jar: save migration, Realms, telemetry, the profilers, the management server, the data generators, and where to start if you need one anyway. It is the second lecture and not the last because a boundary is worth drawing before you invest in thirteen parts, not after.

Where the part stops

Part I says which threads exist and hands the two loops and the wire on. What the Server thread does with a tick is Part III; what the frame loop does between ticks is Part X, and the frame itself Part XI; what crosses the wire between them is Part IX. This part owes you only enough of each to read a lane.

The part’s own packages are the two entry points, the client’s GameConfig and SilentInitException, and the two loop classes, and it leaves none of them unnamed: 0% of the part’s lines are named on no page in the book. The boundary that matters here is the book’s rather than the part’s, and drawing it is the second lecture’s whole job.

Reference this part uses

Diagram lanes — the abbreviations every sequence diagram uses, needed from the first figure of the first lecture onward. Threads — every thread, who makes it and what may run on it; Part I names the four to memorise and this is the rest. Naming drift — the 1.21-era names that have moved. The atlas — where everything is, and the treemap the second lecture reads.

Rules: names, never code · how the system works, not how the code reads · newest version only · every backticked name passes tools/verify_names.py.

Anatomy

Verified against Minecraft 26.3 · Part I · Clicking Singleplayer, picking a world, and standing in it a few seconds later.

A player clicks Singleplayer, picks a world from the list and waits. One thread has been running since main; by the time the world appears there are two that matter, and the second was created by the first, mid-frame, while the first went on drawing. They are two programs sharing a JVM. The server is the world — every chunk, entity and block, and the only thing allowed to change them; the client is a window, a frame loop and a copy of the world it is told about. Between them runs a Netty channel that never touches a socket, and over it the client walks the same handshake, login, configuration and play state machine it would walk against a server on the other side of the planet. The packets are real. What leaks between the two halves is not world state but a setting: pause is decided on the client, by Minecraft.isPaused, and enforced on the server, by IntegratedServer.tickServer running IntegratedServer.tickPaused instead of the world. The decision has a third term that nobody sees in the menu: the client only sets the flag while IntegratedServer.isPublished is false — which is why a world published to LAN never pauses, however deep in the options screen you are.

The cast

Three of Minecraft’s nullable fields between them mean “we are in a world”: Minecraft.level (a ClientLevel), Minecraft.player (a LocalPlayer) and Minecraft.gameMode (a MultiPlayerGameMode). A fourth, Minecraft.singleplayerServer, holds the IntegratedServer when one is running, and is the client’s answer to “am I the host”.

From main to a world

sequenceDiagram
    box transparent the client
    participant Main as Main
    participant MC as Minecraft
    participant Conn as Connection
    end
    box transparent the server
    participant IS as IntegratedServer
    participant SCL as ServerConnection<br/>Listener
    end

    Main->>Main: tryDetectVersion, loadLibraries, bootStrap, validate
    Note over Main: from here this thread is the Render thread
    Main->>MC: the constructor: a backend, a Window, every reload listener
    MC->>MC: the first ReloadInstance, the LoadingOverlay on screen
    Main->>MC: run: pollEvents, then runTick, until running goes false
    Note over Main,Conn: one loop so far. The next line makes the second.
    MC->>IS: spin builds it on this thread, then starts the Server thread
    par on the Server thread
        IS->>IS: runServer: initServer loads the level
    and meanwhile, on the Render thread
        MC->>MC: doWorldLoad: draw a frame, drain the queue, until isReady
    end
    MC->>SCL: startMemoryChannel: a Netty local address, no socket
    MC->>Conn: connectToLocalServer: the client's end of that channel
    Conn->>Conn: handshake, login, configuration, play — the walk any client makes

The one-time start-up, and the line where one loop becomes two: in the split box the Render thread goes on drawing while IntegratedServer.initServer loads the level. Everything below it is the client dialling a server that happens to be in the same JVM.

That is the book’s first sequence diagram, and its lanes are abbreviated the way every later one is: two or more letters of a class name, one meaning throughout. The key is diagram lanes.

Five main methods, and this trace starts in one of them. client/main/Main is the client’s, server/Main the dedicated server’s, data/Main the data generator’s, client/data/Main the generated client assets’ — models, atlases, equipment assets, waypoint styles — and gametest/Main the one that launches GameTestServer. (The tree holds a sixth main, SnbtDatafixer, which converts files and starts nothing.) Each parses its own command line — the client’s into a GameConfig the Minecraft constructor is built from — and then reads its own settings file: options.txt through Options on the client and server.properties through DedicatedServerProperties on the dedicated server. The two generator entry points are build-time programs, and what this book skips says how far that is true.

Bootstrap before anything exists. SharedConstants.tryDetectVersion reads version.json as the first statement of every one of those main methods, before the option parser exists; NativeLibrariesBootstrap.loadLibraries unpacks the natives, CrashReport.preload warms the reporter, and Bootstrap.bootStrap builds and freezes the static registries — blocks, items, entity types, the things that cannot be data-driven because the data loader itself needs them (identifiers and registries is what the freeze proves). ClientBootstrap does the client-only equivalents between that and Bootstrap.validate, which checks the result. DataFixers.optimize is kicked off concurrently before the registries are built and joined much later.

The GPU backend is chosen in the constructor. RenderSystem.initBackendSystem runs first and returns SDL’s clock, which Minecraft installs through Util.setTimeSource — so Util’s clock, on the client and on a singleplayer server beside it, comes from the windowing library. Then a GpuBackend is chosen by trying candidates in an order Options sets, unless a launch argument names one, until one of them loads its library and makes a GpuDevice — there are two, GlBackend and VulkanBackend (the window) — and only then is the one Window made, through the backend that succeeded. From then on the renderer only ever sees the GpuDevice abstraction in com/mojang/renderpearl.

Construction registers, it does not load. The constructor creates each manager and registers it on the ReloadableResourceManager; the loading is one ReloadInstance whose prepare phases run on Util.backgroundExecutor and whose apply phases run on the Render thread, with the LoadingOverlay on screen. Pressing F3+T re-runs exactly that path — see the resource system.

Opening a world spins a server. Minecraft.doWorldLoad calls MinecraftServer.spin, which constructs the IntegratedServer on the caller’s thread before starting the new one (starting a server has that order in full); the new thread’s body is MinecraftServer.runServer, which calls IntegratedServer.initServer and enters the loop. Meanwhile Minecraft.doWorldLoad keeps the Render thread drawing frames and draining its own queue until MinecraftServer.isReady, waiting out each sixtieth of a second in BlockableEventLoop.managedBlock: a thread that blocks on this half of the game keeps running that half’s queue while it waits, which is the reason the wait cannot deadlock.

The client connects like any other client. ServerConnectionListener.startMemoryChannel binds a Netty local address and Connection.connectToLocalServer connects to it; the client then walks handshake, login, configuration and play as it would against a remote server, with ClientHandshakePacketListenerImpl as its login listener. The server gives the local channel a handshake listener of its own, MemoryServerHandshakePacketListenerImpl, and skips the encryption request and compression it would send a remote client. Almost nothing in the play path knows it is singleplayer: the exceptions are the handful of places that ask Connection.isMemoryConnection or ServerCommonPacketListenerImpl.isSingleplayerOwner directly, among them ClientPacketListener.handleUpdateTags, which skips applying the tags it was sent because the server’s registries are already the client’s. The connection has what the local channel does and does not install, and protocol phases is the walk in full.

Two loops, and a wire between them

The client’s loop is a frame loop with ticks inside it; the server’s is a tick loop with no frames at all. They are not the same shape, and no page later in this book is readable until that difference is fixed in mind.

flowchart TD
    subgraph Client["the Render thread"]
        CR["Minecraft.run: RenderSystem.pollEvents,<br/>then Minecraft.runTick, once per frame"]:::client
        subgraph Frame["Minecraft.runTick"]
            CD["the DeltaTracker counts the whole ticks owed"]:::client --> CP["PacketProcessor.processQueuedPackets"]:::client
            CP --> CQ["BlockableEventLoop.runAllTasks"]:::client
            CQ --> CT["Minecraft.tick, 0 to 10 times"]:::client
            CT --> CF["Minecraft.renderFrame, on the partial tick"]:::client
        end
        CR --> CD
        CF --> CR
    end
    subgraph Server["the Server thread"]
        SR["MinecraftServer.runServer: the deadline is set first"]:::server
        subgraph STick["one server tick"]
            SP["PacketProcessor.processQueuedPackets"]:::server --> SS["MinecraftServer.tickServer: every ServerLevel, then the connections"]:::server
        end
        SW["MinecraftServer.waitUntilNextTick:<br/>run queued tasks, then park"]:::server
        SR --> SP
        SS --> SW
        SW --> SR
    end

The two loops side by side: the Render thread’s ring is a frame with a tick inside it, and the Server thread’s ring is the tick with no frame anywhere in it. The inner box in each is the call that holds the tick — Minecraft.runTick on one side, MinecraftServer.processPacketsAndTick on the other.

The frame loop. Minecraft.run polls SDL events and calls Minecraft.runTick once per frame, as fast as vsync or the frame-rate limit allow. Inside each frame a DeltaTracker.Timer running at twenty ticks a second says how many whole game ticks have elapsed since the last frame — usually zero or one, at most ten are run — and Minecraft.tick is called that many times, with BlockableEventLoop.runAllTasks draining the thread’s own queue just before them. The fractional remainder is the partial tick the renderers read, to interpolate with, from the DeltaTracker that Minecraft.renderFrame hands them. So the client has a 20 Hz tick, but it is a sub-step of the frame loop rather than a loop of its own; the client loop is the arithmetic in detail.

The tick loop. MinecraftServer.runServer re-reads this tick’s length every iteration from TickRateManager.nanosecondsPerTick — 50 ms by default, whatever /tick rate says otherwise, and zero under /tick sprint — and calls MinecraftServer.processPacketsAndTick, which drains the PacketProcessor and then runs MinecraftServer.tickServer. Afterwards MinecraftServer.waitUntilNextTick spends the slack running queued tasks and then parks until the next tick is due. There is no frame and no partial tick here at all. The “Can’t keep up!” warning is MinecraftServer.runServer’s own, decided before either call from how far behind the deadline already is; the server tick owns what is inside them — the tick budget, the deferrable work and the flush bracket around outbound packets.

Both are event loops first and game loops second. Minecraft and MinecraftServer both extend ReentrantBlockableEventLoop — the same base class, not an analogy — so each is an Executor whose queue drains on its own thread, and another thread that wants to touch that half’s state submits a task, or leaves its work in one of the queues beside the loop’s own that the owning thread drains — a packet in the PacketProcessor (below), a dedicated server’s console line in a list DedicatedServer.tickConnection drains, a level’s chunk work in its ServerChunkCache.MainThreadExecutor (below). BlockableEventLoop.managedBlock is the blocking form, and the reason the owning thread can wait for a future without deadlocking: it keeps draining its own queue while it waits.

A packet is decoded on one thread and handled on another. A packet arrives on a Netty IO thread and Connection.channelRead0 hands it to the current PacketListener; a handler that touches game state calls PacketUtils.ensureRunningOnSameThread, which, when it is off-thread, queues the packet on the owning side’s PacketProcessor instead of running it — the connection is that crossing in both directions. What matters here is when the queue is drained, because the two loops do not agree: first thing in MinecraftServer.processPacketsAndTick, but on the client early in Minecraft.runTick, after the delta tracker advances and before the ticks — so a client at 200 frames a second takes the server’s packets ten times more often than it ticks.

Four threads worth memorising

That is the set worth memorising, not the set that exists. The IO workers, the sound engine’s event loop, the dedicated server’s watchdog, console, RCON, query and management threads, the timer hack thread and the situational ones — authentication, chat filtering, server pinging, telemetry, world upgrades, the shutdown hooks — are all in Threads, with who makes each and what it is allowed to touch.

There is no fifth thread hiding on the client. The Render thread is the game thread: Minecraft.gameThread and the thread RenderSystem guards with RenderSystem.assertOnRenderThread are the same one, and there is no initGameThread and no isOnGameThread anywhere in the tree — only RenderSystem.isOnRenderThread. A slow client tick costs frames directly. What that thread does with a world is animate and predict one (Minecraft.tick calls ClientLevel.tickEntities, and block entities tick too), but nothing it concludes is authoritative, and the server’s packets overwrite whatever the prediction got wrong — which is a claim about the world, and the client’s own player is the exception the book spends Part VIII and prediction and acknowledgement on.

Everything else that matters is serialised onto a pool rather than given a thread. ConsecutiveExecutor and PriorityConsecutiveExecutor, in util/thread, are the mechanism: a queue that promises to run its tasks one at a time on a pool that otherwise runs many, which is how “worldgen” and “light” stay ordered on the worker pool, and how the IOWorker stays ordered on Util.ioPool — which is its own pool of IO-Worker-n threads, not one of the four. And ServerChunkCache.MainThreadExecutor is a further event loop layered on the server thread, which is why a tick that waits on a chunk does not deadlock the chunk that needs the tick.

What singleplayer shares by direct call

Every block, entity and inventory change a player makes crosses as a packet, even in one process. But the two halves share a JVM, and a handful of things do cross by direct call — settings, debug state and the options screen’s own updates — and a setting can reach the world before the call returns. The server reads Minecraft.isPaused every tick and the client’s render and simulation distances every tick it runs the world; WorldOptionsScreen.applyChanges calls IntegratedServer.publishServer and its siblings straight from the Render thread, and among them IntegratedServer.setPersonalGameType sets the host’s own game mode through ServerPlayer.setGameMode on the Render thread, not the Server thread; and IntegratedServer.latestTicksGizmos is a volatile list the server thread writes and the client reads. Treat “everything crosses as a packet” as a rule about play, not about the process.

Singleplayer differs in more than pausing, too. Beyond the pause and the distances following Options, IntegratedServer caps the player list at eight, owns LAN publishing and the LanServerPinger, drops the chat and command spam thresholds to zero where a dedicated server defaults to ten, takes native transport from the client’s own option rather than a server property, and answers the operator-permission questions differently.

A crash in singleplayer surfaces on the wrong half

Neither loop throws. Both catch everything and wrap it in a CrashReport, and a background thread that dies parks its report for a loop to pick up (how a server dies owns that relay, and the client loop the client’s own three exits). The asymmetry is Part I’s, because it follows from two programs sharing a JVM: only a loop constructed to propagate crashes rethrows a parked report, and IntegratedServer is not one. So a worker that dies doing the server’s work in singleplayer takes down the client, and the crash report names a thread the player was not watching.

Questions players ask

Does a dedicated server pause? Yes — an empty server stops ticking on its own (the server tick has the counter and what still runs). Pausing is not a singleplayer concept; only the client-decides-it half is.

Is twenty ticks a second a constant? No, it is a server field. The TickRateManager.nanosecondsPerTick the loop re-reads lives on a ServerTickRateManager, the server’s subclass of it, which adds the sprint /tick manipulates and sends clients the rate and the freeze; the client mirrors those two in ClientLevel, so the DeltaTracker slows and freezes with the server.

Does a busy server skip work? Less than you would think. The tick budget is one predicate, MinecraftServer.haveTime, travelling from MinecraftServer.tickServer down through every level, and what it actually gates is a short list that does not include loading or generating a chunk. The server tick has that list, and the sprint’s inverted effect on it.

For a 1.21-era reader. The client’s clock is DeltaTracker, which was Timer, and the partial tick is a DeltaTracker.Timer you ask rather than a float you are handed — it appears in the frame loop above and in every frame’s extract in Part XI. GLFW is gone; SDL makes the window, delivers its events and supplies the time source. The rest of the drift a 1.21 reader will trip on is naming drift.

Where to look

client/main/Main · Minecraft · server/Main · MinecraftServer · IntegratedServer · BlockableEventLoop · Util (the executors) · EventLoopGroupHolder · ServerConnectionListener · Connection · PacketProcessor · PacketUtils

Rules: names, never code · how the system works, not how the code reads · newest version only · every backticked name passes tools/verify_names.py.

What this book skips

Verified against Minecraft 26.3 · Part I · A reader opens the atlas, sees fourteen packages hatched, and asks what is in them and why no part counts them.

Open the atlas and part of the jar is drawn hatched. That hatching is this page. Java Minecraft is 7,301 source files and 741,069 lines, and the parts do not reach all of it. Some of what is left out is excluded on purpose by the newest-version-only rule — save migration is version-difference code, and a book that documents only the current version has nothing to say about it. Some is out of scope because it is a client for a service this book cannot read. And one hatched box is not skipped code so much as skipped ground: net/minecraft/data is the program that writes vanilla’s own content as a data pack, it ships in the dedicated server jar — all 174 files of it — and the running game compiles against it and calls into it. Blocks names TreeFeatures keys while it constructs mushroom blocks; MinecraftServer reaches for a MiscOverworldFeatures key for the bonus chest; the F3 screen’s biome-builder line runs through NoiseRouterData.peaksAndValleys into TerrainProvider. A boundary drawn honestly has to show where it leaks, and that is the largest leak in it.

The sizes, and which jar ships them

Each entry below says what the thing is, roughly how big it is, whether the dedicated server ships it, one fact worth knowing, and where to start reading. The treemap deliberately does not hatch net/minecraft/gametest: Part XIII covers it, so it is a gap that closed rather than a skip. It cannot hatch player reporting either, which is why the table has fifteen top-level rows against the map’s fourteen hatched packages: the map’s smallest box is a package four levels deep, and net/minecraft/client/multiplayer/chat/report is six, sitting inside a package Parts IX and X between them own. The counts in the tables are files unless a cell says classes, so a package-info.java counts as one there and wherever the prose quotes the tables; a cell or a sentence that counts a package’s working classes leaves it out.

The oracle for “server or client” throughout is the list of classes the dedicated server jar ships, which lives beside the decompile. It answers exactly one question — does the dedicated server have this class — so it can prove “client-only” and it can prove “both jars”, and it cannot prove “dedicated server only”. Two rows are labelled that way on the strength of a different check: nothing under net/minecraft/client or com/mojang/blaze3d references them. rcon is reached from DedicatedServer alone; jsonrpc from six files, and two of them — BuiltInRegistries and Registries — are classes the client loads at bootstrap, so the package’s types are on the client and the server it configures is not.

Save migration, and the fixer that moves files

net/minecraft/util/datafix — the largest thing on this page and the most explicitly out of scope. DataFixers is one static class whose whole body is the migration history of the game written out longhand: just over three hundred schema registrations and four hundred-odd fixes, from schema 99 up to the current world version. The rewriting machinery itself is Mojang’s external DataFixerUpper library; what lives here is the vanilla catalogue — util/datafix/schemas describing the shape of the data at each version, and util/datafix/fixes doing the individual rewrites.

A version number becomes a chain of fixes through DataFixTypes, an enum of about thirty type references (level, chunk, player, entity chunk, POI chunk, options, stats, advancements, and a long tail of saved-data kinds). DataFixTypes.updateToCurrentVersion takes the data version as an argument — every one of its fourteen callers reads the version itself — and asks the fixer to compose every rule from there to now. DataFixTypes.wrapCodec is the one that reads the version out of the tag: it wraps an ordinary codec so decoding pulls the data version, runs the chain, and encoding stamps the current version back in. It is the rarer door — two callers, PlayerAdvancements and DebugScreenEntryList — while player data takes the first one and reads the version itself, and chunk storage reads it too and takes a third, DataFixTypes.update. The rules are pre-compiled on a dedicated bootstrap thread, and that thread is built with some care to stay out of the way: one thread, daemon, at minimum priority, with a single caller in the client’s entry point, optimising exactly one type (the level-summary schema, so the world list opens fast). The dedicated server never asks for it at all.

net/minecraft/util/filefix does what the other cannot. A data fixer rewrites the contents of a tag after it has been read, so it can never move, rename, split or delete a file. FileFixerUpper operates on the world directory: its operations are moves, regex moves, group moves, deletions, content modifications and one composite that scopes a nested list of operations to matching folders, and the concrete fixes do things like relocate dimension storage, gather player storage into one folder and pull data out of level.dat into saved data (level data and rules).

It stays safe by working somewhere else: the whole upgrade runs against a custom copy-on-write file system over the world folder, whose writes land in a scratch directory, and the result is swapped in at the end. Exactly how safe depends on the filesystem underneath. Where hard links are available it uses them. Where they are not, it writes one file, upgrade_in_progress.json, recording the moves, and an upgrade cut short by a crash resumes from it the next time the world is opened, while one that fails on an error tries to move its files back. And where atomic move is unavailable it stops before the swap rather than risk a half-moved world.

The client does not grey out a world that needs the upgrade — it relabels the button. LevelSummary.primaryActionMessage turns Play into Upgrade and Play while leaving it active; what is disabled is Edit and Recreate, which would otherwise touch a directory the fixer is about to rearrange.

Telemetry writes to disk before it writes to the network

net/minecraft/client/telemetry, client-only. Exactly seven event types: world loaded, world unloaded, graphics capabilities (which now carries the backend name and the reason a backend failed — see Blaze3D), and four opt-in ones covering performance metrics, world load times, advancements and game load times. TelemetryProperty is the vocabulary; each property carries both an internal name and an export key.

Opting out is two-tier, and the game controls only one of the tiers. Minecraft.allowsTelemetry reads an account-level flag the game only reports; the in-game control only chooses whether the four opt-in events are sent, and is only offered when the account carries the flag that allows it. Everything sent is also written locally as a JSON event log with a seven-day expiry — and the send waits on the log opening, so a log that cannot be opened suppresses the send. A player can read their own outgoing telemetry, though not in the game: the telemetry screen renders the catalogue of event types and their properties, and a button next to it opens the log directory in the platform’s file manager.

Start at ClientTelemetryManager, TelemetryEventType.

Four profiling systems, and Tracy is the surprise

net/minecraft/util/profiling holds four profiling systems. Two sit in the package itself — the tick profiler and the Tracy bridge — and two in subpackages of it, jfr and metrics.

The tick profiler is the familiar one: Profiler is a thread-local holder of a ProfilerFiller, ActiveProfiler records the push/pop tree of named sections that pages in this book quote, and /perf and the client’s F3 profiler chart drive it.

Tracy is the surprise, and it is one class bridging out to Mojang’s Tracy binding. TracyZoneFiller implements the same interface, and Profiler.get falls back to the Tracy filler rather than the inactive one when Tracy is available — and Profiler.decorateFiller combines the two, so an attached Tracy build and a running /perf both see every section. With a Tracy build attached, every profiler section in the game streams out with no command run. Tracy reaches outside this package too, into Blaze3D’s frame capture, into the GPU abstraction’s TracyGpuProfiler and into the executor wrappers.

JFR (util/profiling/jfr) registers ten custom flight-recorder events under a Minecraft category — chunk generation, region reads and writes, packets sent and received, network summaries, server tick time, client FPS, structure generation, world load. Packet events are emitted straight from the packet codecs, so a recording gives a per-packet-type byte breakdown that this book’s packet reference cannot. Start with –jfrProfile or /jfr start.

Metrics (util/profiling/metrics) is /perf: sampling by nine MetricCategory values — pathfinding, event loops, consecutive executors, the tick loop, JVM, chunk rendering, chunk-rendering dispatch, CPU and GPU — written out as CSVs that PerfCommand zips.

The management server is not RCON

net/minecraft/server/jsonrpc, dedicated server only, and genuinely new. It is JSON-RPC 2.0 over a WebSocket, served by its own Netty bootstrap with an HTTP codec, an authentication handler, the WebSocket handshake and optional TLS. It is disabled by default; when enabled, TLS is on unless explicitly turned off, and the server refuses to start without a forty-character alphanumeric secret, generating one if absent.

What it exposes is the administrator’s surface, not the game’s: allow-list, bans and IP bans, players and kicks, operators, game rules, server status, save and stop, system messages, and a family of live server settings — including the idle-pause window, whose behaviour belongs to the server tick, because a dedicated server pauses too. Implementations sit behind service interfaces so the wire layer never touches the server object directly, and an executor service marshals calls onto the server thread.

The description of the API cannot drift from the handlers, because it is derived from them: every method is registered with a description and typed parameter and response schemas, and a discovery method returns an OpenRPC 1.3.2 document built by walking the two method registries and filtering on a per-method discoverable flag. There is also an outgoing direction for server-initiated notifications. The audience is panel and hosting operators.

Start at JsonRpc, ManagementServer.

RCON, query, and the pre-1.7 ping that removes itself

net/minecraft/server/rcon is seven classes of pre-Netty blocking socket code on its own threads. RconThread accepts the connections and RconClient speaks Valve’s Source RCON framing; commands execute as a RconConsoleSource, a command source that accumulates output into a string rather than a chat feed (Brigadier and commands). QueryThreadGs4 speaks the GameSpy4 UDP query protocol with a challenge-token handshake and a five-second cache on its full-status reply.

The pre-1.7 ping is not in that package. LegacyQueryHandler sits in the server’s network package and is installed into the Netty pipeline before the length-prefix splitter and the packet codec, right after the read timeout (the connection). It peeks at the first byte; if it is the legacy ping marker it answers in the old format and closes, and otherwise it resets the reader index, removes itself from the pipeline, and re-fires the bytes downstream. It costs one byte comparison per connection and then vanishes. The same encoding is used client-side so the server list can still ping ancient servers.

Realms is a client for a server nobody here can read

com/mojang/realmsclient, client-only, 137 files and 14,701 lines — more lines than the whole packet catalogue in network/protocol. Roughly sixty per cent is screens and the records behind them — subscriptions, world slots, templates, invites, backups, minigames, upload and download — and the rest is a task framework, the world-upload pipeline and the HTTP layer, a list of REST paths with a small request wrapper. net/minecraft/realms is three classes and a package-info.java vanilla keeps for Realms, RealmsScreen among them, the base the Realms screens extend; beyond it the Realms UI extends ordinary vanilla screens and widgets.

Out of scope because it is a service client: its behaviour is defined by a server this book cannot read. One fact anyway. The environment is chosen from an environment variable falling back to a system property, defaulting to production, in a static final field of the release client — and there are three environments, not two, because the third points at localhost.

Statistics, the scoreboard, and the recipe book

net/minecraft/stats is nine classes covering two concerns, plus a link into a third package that is the reason it is worth a paragraph.

Statistics: Stats declares eight registry-backed stat types — mined, crafted, used, broken, picked up, dropped, killed, killed by — plus a custom type holding the seventy-odd hand-declared counters (play time, distances by every mode of travel, damage dealt and blocked), each bound to a formatter that affects display only. A stat type is a lazily-populated map over a registry, so stat objects are interned; ServerStatsCounter adds the per-player file and a dirty set, and only dirty stats are sent. Statistics are one of two parts of the save that go through the data fixer as JSON rather than NBT — the other is advancement progress (advancements), and they are the only two.

The scoreboard link is why the package is worth a paragraph — and note that the class doing the linking is not in it: ObjectiveCriteria lives in net/minecraft/world/scores/criteria, which is why a scoreboard objective can name a statistic and why this package is reachable from a command at all (scores, teams and stored data is how the name is parsed).

The recipe book is the second concern, and it is in this package for historical reasons rather than architectural ones — RecipeBook, RecipeBookSettings and ServerRecipeBook are not skipped, they belong to recipes, with advancements reaching in from the other side. The address is the only thing surprising about them.

Two packages nobody will recognise

net/minecraft/gizmos is a debug-drawing API, in the game-engine sense of the word: the immediate-mode “draw me a box in the world for one frame” facility most engines have and Minecraft did not. Every one of the debug renderers — chunk borders, hitboxes, pathfinding, brains, points of interest, raids, light sections — is now written against it, and it is not client-only, which is the surprise. It is taught where its output is, in Part X, by debugging the running game; the address is what belongs here, because a reader hunting for the debug renderers’ drawing code will look under client/renderer/debug and find nothing that draws.

net/minecraft/references is not “references” in the data-fixer sense. It is a set of id-constant tables, and the split is not the one the package names suggest: BlockIds holds the keys for blocks with no item form (water, lava, wall torches, piston heads, wall signs), ItemIds the items with no block, and BlockItemIds — seven times BlockIds and not quite twice ItemIds — the pairs. Look for stone in BlockIds and it is not there. They exist to break a class-initialisation cycle: exactly twelve files outside the package name it, and four of them are the ones that need to name a block or item before the block and item classes are loaded — Blocks and Items themselves, and GrassBlock and MyceliumBlock, which name another block during that initialisation — while PotDecorations looks its brick up by key. The other seven are data generators that work in keys: four tag providers, a tag appender and two feature bootstraps, AquaticFeatures and NetherFeatures. A resource key is a registry plus an identifier, so it can be built with nothing loaded. Practically, it is the canonical machine-readable list of block and item ids, and a better starting point than the block and item holder classes if that is what you want — but not the id list: five sibling tables for entity types, block-entity types, potions, fluids and atlases live outside the package, in the trees they belong to.

The data generators, and why “data-driven” is both true and misleading

Most of net/minecraft/data is a build-time program: a second entry point with its own options, a generator that groups providers into packs, and a hash cache that skips unchanged files. net/minecraft/client/data is its client half, generating block and item models, the atlas definitions, equipment assets and waypoint styles.

The significance is a genuine paradox worth stating plainly. Vanilla’s own content is a data pack. net/minecraft/data/worldgen is most of the vanilla worldgen data pack written as Java — the biome feature lists, the material rules, the carvers, the jigsaw pools, the structures and structure sets, the processor lists — and the loot, recipe, tag and advancement packages do the same for their domains, all serialised through the same codecs the game uses to read a pack.

So “Minecraft is data-driven” is true: the running game only ever sees JSON parsed by codecs, with no vanilla-specific path (the resource system). And “you cannot change it without a data pack” is nearly true — which is the more useful statement, because the exceptions are load-bearing and a reader who believes the absolute version will misread three other pages.

The package is not build-time only, and the dedicated server ships all 174 files of it. Three kinds of exception:

• Plain id tables. AtlasIds is read at runtime by the model manager, the atlas manager, the map, sky, painting and particle renderers, and by a chat component. Nothing build-time about it.
• The bootstrap interface itself. BootstrapContext — in net/minecraft/data/worldgen — is what every vanilla data-pack registry’s bootstrap is written against, from damage types and enchantments to chat types, dialogs and world clocks. It is the most-imported type in the package by a wide margin.
• Constants and math the running game calls. Blocks itself names TreeFeatures keys while constructing mushroom and fungus blocks, and a CaveFeatures key and a VegetationFeatures key for the moss and pale moss blocks; MinecraftServer reaches for a MiscOverworldFeatures key for the bonus chest; a jigsaw block entity defaults to a Pools key; NoiseRouterData and NoiseGeneratorSettings, both shipped worldgen classes, are compiled against TerrainProvider and the material rules in net/minecraft/data/worldgen/material; and the F3 screen’s biome-builder line calls NoiseRouterData.peaksAndValleys, one line that delegates straight into TerrainProvider (density functions).

Vanilla’s density functions and noise settings still reach the running game as JSON. NoiseRouterData.bootstrap and NoiseGeneratorSettings.bootstrap are collected by VanillaRegistries, which the data-generator entry point runs and which Commands.validate borrows for its ambiguity check; the game itself reads the generated files out of the built-in pack. Editing TerrainProvider changes terrain by changing what that generator writes.

So net/minecraft/data holds a build-time program and a handful of tables and functions the shipped game compiles against and executes. The generator half is inert at runtime but for one static helper StructureTemplateManager borrows from NbtToSnbt, and it is the half worth reading — it is the fastest way to understand what a vanilla biome or structure declares, because it is typed and cross-referenced where the JSON is not, a point biomes and structure placement both depend on. And the report providers are how you get machine-readable dumps of the registries and the packets, two of the tables this book’s own reference layer covers.

The audio backend lives in Blaze3D, and is not skipped

com/mojang/blaze3d/audio is hatched for its address, like net/minecraft/gizmos above: the book teaches what it does and the atlas still counts it outside every part, because it is filed where nobody looks for it. It wraps OpenAL, and it sits inside Blaze3D, beside the window and RenderSystem, rather than in the client’s sound package where the engine, the manager, the channel bookkeeping and the Ogg decoding live. That is the boundary fact: Blaze3D is the platform layer for both devices, not only the graphics one, and a reader looking for the sound code under client/sounds will not find the half that talks to the driver. Everything the package does — the device and context, the channel limits (which are counters and not pools, as that page’s own heading insists), binaural rendering through Options.directionalAudio, hot-plugging a headset mid-game — is taught, in Part X, by the sound engine.

Player reporting

net/minecraft/client/multiplayer/chat/report, client-only. ReportingContext holds the sender, the environment (which server or realm), a log of the last thousand-odd received messages, and at most one draft report. There are three report kinds — chat, skin, name — and an eleven-value reason enum.

The piece worth naming is the context builder: a chat report does not send just the offending line, it walks the log backwards to assemble surrounding signed context, which is what makes the report verifiable at the other end. The report machinery is the consumer of the chat-signing system that chat and signing documents. Neither the transport nor the policy is in the game — both come from the account service library.

Gaps, and the ruling on each

The hatched boxes above are the boundary as drawn. Beside them sits a shorter list of things that were never excluded on principle — they were simply not written when the book reached them, and each has since been ruled on. Ten are now taught, either as a page of their own (net/minecraft/gametest, com/mojang/blaze3d/platform, the post-effect chains, the scoreboard and command storage) or as a section of one (the debug cluster across the HUD and debugging pages, item models on models and atlases, the packrat parser on Brigadier and on codecs, the animation framework on entity rendering, the pack classes on the resource system, and net/minecraft/client/resources, which turned out to be five systems with five owners rather than one gap). Naming where each landed is the landing pages’ job, not this one’s; what belongs here is the other ruling.

Declined, with the reason. A decline is a promise that a reader will not miss it, not a shrug.

Two things inside com/mojang/renderpearl/backend/vulkan are named before the decline rather than after it: DestructionQueue, the deferred-free discipline OpenGL needs no equivalent of, which is the clearest illustration of what the device seam hides, and vulkan/checkpoints, vendor breadcrumb extensions for GPU crash reports. The shader compiler is not in the declined tree. GlslCompiler and SPIRVModule, the shaderc and spirv-cross pair, sit in front of both backends in renderpearl/frontend/shaders, because Minecraft still authors GLSL and compiles it to SPIR-V once — Vulkan takes the SPIR-V as it is and OpenGL cross-compiles it back to GLSL — which is the whole reason one shader source can feed two backends. The interiors of com/mojang/renderpearl/backend/opengl are declined on the same grounds.

Named, and not yet written. These are real systems with real lectures in them, and no ruling above covers them: the carver tunnel walk; the dragon fight (EnderDragonFight); client/multiplayer‘s joining-a-server tail; and two corners of the pack system that the resource system names without teaching — the server-resource-pack prompt and download flow in client/resources/server, and the linkfs synthetic file system that presents the launcher’s hash-named asset files as the one tree their index describes. Beside them sit the maps’ saved data and the wandering trader’s timer, which the level data table names and no page teaches, four Part V mechanisms its landing page does not list: rails, the shelf, the beehive and fire spread; local difficulty (DifficultyInstance), which only that table’s page explains; and four things a player carries that Part VIII lists and does not teach — the attack’s visual effects, the damage statistics, the warden-spawn tracker and the spectator camera behind /spectate. They are named here so that a reader who wants one knows the book knows it is missing, and knows where to start.

Where to look

If you need one of these the entry points are named in each section; if you want a list rather than a system, start at net/minecraft/references for ids and the report providers in net/minecraft/data for everything else, and the atlas for the shape of the whole jar.

Rules: names, never code · how the system works, not how the code reads · newest version only · every backticked name passes tools/verify_names.py.

II · Foundations

Verified against Minecraft 26.3 · Part II · The machinery every later part assumes: how anything becomes data, gets a name and a number, is loaded, and reaches into code.

Part II is the vocabulary the other twelve parts speak without pausing to define it. Nothing here is a thing a player does; everything here is what happens underneath the things a player does — and a player still recognises it by its symptoms: the square brackets after an item name in a /give, the #minecraft:logs in a recipe file, the type line at the top of a recipe file. Each of those is one of these seven pages surfacing. The claim the part makes is that they are not seven mechanisms but three: a codec describes a value, a registry gives it a name and a number, a pack stack decides which copy of the file wins, and everything above is those three used again — which is why a world made almost entirely of JSON loads in seconds and why a data pack can recombine the game without adding a single behaviour to it.

The shape of the part

Part II is not a stack but a fan. Codecs and registries come before everything else here, and the five pages below them lean on those two far more than on each other. The last page is the pattern the rest exists to make possible.

flowchart TD
    C["1 · Codecs, NBT and JSON"]
    R["2 · Identifiers and registries"]
    S["3 · The resource system"]
    T["4 · Tags"]
    D["5 · Data components"]
    X["6 · Text components"]
    P["7 · The data-driven type pattern"]
    C -- "decodes every pack-written element" --> R
    C -- "a persisted component has one" --> D
    C -- "text is a value like any other" --> X
    R -- "/reload rebuilds the reloadable ones" --> S
    R -- "the tag table is swapped after the freeze" --> T
    R -- "an entry carries its starting components" --> D
    R -- "the registry of kinds is built in" --> P
    S -- "tags are read from the same stack" --> T
    T -- "any set field takes a tag" --> P
    D -- "a component type is a key, not a kind" --> P

The part as a fan, numbered to the watch order. An arrow points from the machinery to the page that takes it for granted: codecs at the top is what nothing else here is built without, registries hang directly off it, and the pattern at the foot, which no arrow leaves (none leaves text components either), is where the part is going.

Before you start

Anatomy, for the threads: built-in registries are frozen before either program exists, data-pack loading runs on the worker pool with hops back to the owning thread, and a reload’s apply phase runs on whichever thread owns the state being replaced.

Watch in this order

1. Codecs, NBT and JSON — one ItemStack written four ways: into a chunk file, into a packet, as a checksum in a click, and out of the text of a /give. The click sends no component values at all, only hashes.
2. Identifiers and registries — how minecraft:diamond_sword becomes an Item before the game exists, and how a data-pack biome becomes a Holder the client is told about. The wire id of a sword is its place in the order the items were registered.
3. The resource system — F3+T as a pipeline: a stack of packs, a snapshot of the list, every listener preparing at once, applying in order; /reload as the same pipeline on the server. On the client a failed reload deselects every pack it can, not the bad one.
4. Tags — #minecraft:logs from a JSON file to the set a parrot checks before it perches. A frozen registry’s contents never change, and yet /reload changes what the tag contains.
5. Data components — the prototype an item type supplies and the patch a stack carries. The prototype is built on every reload, with the world’s registries in hand, not in the constructor.
6. Text components — a death message built on the server, sent as a translation key, and worded by the client’s language file. The client receives it before it knows what it says.
7. The data-driven type pattern — the type field that picks a kind, a recipe’s or a loot function’s, is a lookup in a built-in registry of kinds. Fifty-six of the registries in BuiltInRegistries are read that way, and they are why a pack can compose the game’s behaviours without adding one.

Where the part stops

Every page here follows a scenario, so each names the classes its own scenario touches and names the families beside them without walking every member — the concrete Tag classes one per primitive, the fifteen partial component predicates, the read-only Holder views. Two omissions are deliberate: net/minecraft/util is a grab-bag rather than a system, named only where a page needs one of its helpers, and net/minecraft/core/dispenser is eleven dispense behaviours, the interface they share and the record each is handed, which the book names nowhere because what a dispenser is belongs to Part V and what each behaviour does is a catalogue. Between them that leaves a floor: 23% of the part’s lines are named on no page in the book. Save migration, the largest thing in net/minecraft/util, is outside that count altogether, out of scope by the newest-version-only rule (what this book skips has the boundary in full).

Reference this part uses

Math and primitives — the coordinate spaces, packings, shapes and random sources every page assumes; it was a Part II page and is now looked up, not watched. Registries — every registry key but the root’s: built-in, data-pack, synced. Data components — every DataComponentType in DataComponents. Naming drift — Identifier was ResourceLocation. Diagram lanes — the abbreviations every sequence diagram’s lanes are written with. The glossary is worth more here than in any other part: this is where the vocabulary every later part leans on is defined, and it is the page to check when a later part uses one of these words in a second sense.

Rules: names, never code · how the system works, not how the code reads · newest version only · every backticked name passes tools/verify_names.py.

Codecs, NBT and JSON

Verified against Minecraft 26.3 · Part II · One ItemStack written four ways: into a chest’s chunk file, into a container packet, as a checksum in a click, and out of the text of a /give.

A player types /give @s diamond_sword[damage=5], drops the sword into a chest, logs out, comes back and clicks the slot. In those few seconds the same sword has been written four times into four different shapes: parsed out of the square brackets, written into the chunk file the chest lives in, sent down a socket as bytes, and sent back up when the slot was clicked. The click is the one worth stopping on. It carries no component values at all. It names the item and the count in the clear — HashedStack.ActualItem is a Holder<Item>, an int and a hashed patch — and for each component the sword’s patch adds it sends one 32-bit checksum, produced by running that component’s own codec into HashOps, a DynamicOps whose output is a hash rather than a document. And it is the same codec every time. The codec that hashed the damage value is the codec that wrote it into the chunk file and the codec that parsed it out of the square brackets. One description of a type, and the format is an argument.

The cast

All of the game’s part of it ships in both jars. The thread column uses the names anatomy gives the threads, and which one holds a codec matters only where the same codec runs on two of them.

The four paths, side by side

Four columns, four diagrams. Read them as four answers to the same question.

Disk: a chest writes a list of slots

sequenceDiagram
    participant CBE as ChestBlockEntity
    participant CHelp as ContainerHelper
    participant TVO as TagValueOutput
    participant NbtIo as NbtIo

    Note over CBE: the server thread, inside chunk serialisation
    CBE->>TVO: createWithContext, from a ProblemReporter and the registries
    CBE->>CHelp: saveAllItems, handed the ValueOutput straight on
    CHelp->>TVO: list Items with ItemStackWithSlot.CODEC, one entry per occupied slot
    TVO->>TVO: ItemStack.MAP_CODEC writes id, count and components
    TVO-->>CBE: buildResult gives a CompoundTag
    Note over NbtIo: an IO worker, later
    NbtIo->>NbtIo: write, from RegionFileStorage: the chunk's tag into its region file

The disk path, and the thing to notice is what has no lane: ItemStack itself. Nothing here is a save method on a stack — an output object is made with context at the top, handed down two levels, and hands back its CompoundTag on the way out, with ProblemReporter.ScopedCollector.close logging anything that went wrong as the scope shuts.

ItemStack has no NBT method — there is no save and no parse on it. The ValueOutput the whole chain writes into is one TagValueOutput.createWithContext, made at the top with a ProblemReporter and the registries, whose CompoundTag TagValueOutput.buildResult hands back on the way out. ChestBlockEntity.saveAdditional receives that ValueOutput and calls ContainerHelper.saveAllItems, which opens a typed list under Items with ItemStackWithSlot.CODEC, a record of slot plus the stack’s own ItemStack.MAP_CODEC fields inlined. That map codec writes id, count (defaulting to 1) and components, the last being DataComponentPatch.CODEC, which spells a removal as !minecraft:foo. NbtUtils.addCurrentDataVersion stamps the data version on the way out. Load is the mirror: BlockEntity.loadStatic reads the id, ChestBlockEntity.loadAdditional calls ContainerHelper.loadAllItems over ValueInput.listOrEmpty.

Wire: a count, an id and a patch

sequenceDiagram
    participant PEnc as PacketEncoder
    participant IStack as ItemStack
    participant DCP as DataComponentPatch
    participant PDec as PacketDecoder

    Note over PEnc: Netty, clientbound
    PEnc->>IStack: OPTIONAL_STREAM_CODEC, a varint count where anything non-positive means empty
    IStack->>DCP: Item.STREAM_CODEC for the id, then STREAM_CODEC for the patch
    DCP-->>PEnc: added count, removed count, each type with its value, then the removed ids
    Note over PDec: Netty, serverbound, the creative slot alone
    PDec->>IStack: validatedStreamCodec over OPTIONAL_UNTRUSTED_STREAM_CODEC
    IStack->>IStack: re-encode through ItemStack.CODEC into NullOps, keeping only the errors

The wire path, in both directions, and the two halves are not symmetrical: the clientbound half above the second note lays the stack’s own fields into the buffer by hand, in a fixed order, while the serverbound half runs a Codec it does not want the output of, purely to see whether it throws.

The clientbound half is laid by hand. ItemStack.OPTIONAL_STREAM_CODEC writes a varint count where anything non-positive means empty and nothing else follows, then a registry id that resolves because the buffer is a RegistryFriendlyByteBuf, then DataComponentPatch.STREAM_CODEC, which writes each value with its component’s own wire codec — a varint for the damage, and for a component with no wire codec of its own, its Codec run into NBT. ItemStack.STREAM_CODEC is the same codec that refuses an empty stack. Serverbound is a different animal: ServerboundSetCreativeModeSlotPacket uses ItemStack.validatedStreamCodec over ItemStack.OPTIONAL_UNTRUSTED_STREAM_CODEC, and the decoded stack is re-encoded through ItemStack.CODEC into NullOps — output thrown away, only the errors kept — to prove that the persistent codec would have accepted it. Why that packet in particular is fenced, and what the other two fences are, belongs to packets and stream codecs.

Checksum: a hash instead of a stack

sequenceDiagram
    box transparent the client
    participant CPL as ClientPacketListener
    participant MPGM as MultiPlayer<br/>GameMode
    end
    box transparent the server
    participant SP as ServerPlayer
    participant ACM as Abstract<br/>ContainerMenu
    end

    Note over CPL: once, when configuration ends
    CPL->>CPL: a RegistryOps over <br/>HashOps.CRC32C_INSTANCE,<br/>from its own registries
    Note over SP: and the same ops, built the same way, from the server's
    Note over MPGM: the Render thread, on the click
    MPGM->>ACM: ServerboundContainerClickPacket: a HashedStack per changed slot
    Note over ACM: the server thread, after the click has been re-run
    ACM->>SP: the same hash of the server's own stack
    ACM->>ACM: RemoteSlot.<br/>Synchronized <br/>compares the two

Two machines computing the same number the same way, which is the only reason the comparison means anything. The packet carries no component values at all — one int per added component and the removed types by registry id — so a client that has been lied to about a stack cannot hash its way back to agreement.

HashOps is a DynamicOps like any other, and a codec cannot tell the difference: it builds maps and lists and strings as usual, and what comes back at the end is a hash code rather than a tree. There is no intermediate byte form to hash. Only one instance is ever built, HashOps.CRC32C_INSTANCE, and both sides wrap it in a RegistryOps — ClientPacketListener builds one from the registries it received during configuration, ServerPlayer from the server’s own — because a component value can name a registry entry, and a hash of an unresolvable name is no hash at all. The server’s is behind a 256-entry cache keyed on the TypedDataComponent, so the common components are hashed once per player and then looked up. Removals are not hashed: HashedPatchMap is a map of added component type to int plus a plain set of removed types. What the server does with the comparison — the either-or in RemoteSlot.Synchronized, and the promotion to a concrete stack when the hash agrees — is containers and menus.

Text: square brackets into a Tag

sequenceDiagram
    participant IP as ItemParser
    participant TagP as TagParser

    IP->>TagP: create once, as the command is built, over RegistryOps on NbtOps
    Note over IP: the server thread, while Brigadier parses the command line
    IP->>TagP: parseAsArgument at each component's value
    TagP-->>IP: a Tag, read no further than the value
    IP->>IP: DataComponentType.<br/>codecOrThrow parses that Tag

The shortest of the four paths, and the one that ends where the first began: the Tag the parser hands back goes through the very codec the chunk file used. Like the disk and checksum paths, it reaches a component’s codec by asking the DataComponentType for it.

ItemArgument hands GiveCommand an ItemInput, and ItemParser is what builds it. The parser holds a RegistryOps over NbtOps.INSTANCE and a TagParser created for that ops, so [damage=5] becomes a Tag and then goes through the very codec the chunk file used, reached by DataComponentType.codecOrThrow. A leading ItemParser.SYNTAX_REMOVED_COMPONENT is the command-line spelling of the same removal the disk codec writes. Data packs are the JSON twin of this path: RegistryDataLoader decodes every registry file in a data pack, loot tables among them, through a RegistryOps over JsonOps.INSTANCE, and a set_components function in a loot table reads its patch with DataComponentPatch.CODEC, the codec a stack’s components go through on disk.

One abstraction, and the ops that are not formats

A Codec is a description of a type and nothing else; it does not know what it is writing into. The format is the DynamicOps handed to it at the call, so the same object describes NBT on disk, JSON in a data pack, and SNBT typed at a command line. Most of the game’s codecs are records built with DataFixerUpper’s RecordCodecBuilder, from primitives and the combinators in ExtraCodecs, the game’s own vocabulary in net/minecraft/util; the class index is where to look one of them up.

Two of the game’s ops are not formats at all. HashOps, in the cast above, answers every question an encoding codec asks and returns a checksum instead of a document. NullOps, which the cast does not list, returns Unit: it encodes to nothing, and exists so that a codec can be run for its errors alone, which is exactly what ItemStack.validatedStreamCodec does to a creative-mode stack.

StreamCodec is the genuine exception, and it is not a Codec at all. A StreamCodec pairs an encoder and a decoder over a ByteBuf directly, with StreamCodec.composite building one out of field codecs; the catalogue of primitives is ByteBufCodecs. A packet is written once, read once and must be small, so it gets hand-laid bytes rather than a document in some format. The two worlds meet at ByteBufCodecs.fromCodec and ByteBufCodecs.fromCodecWithRegistries, which run an ordinary Codec into NBT and put the tag on the wire; the composing vocabulary on the far side of that meeting belongs to packets and stream codecs.

Where the registry context comes from

A codec that names an entry of a dynamic registry cannot resolve it on its own. RegistryFixedCodec demands a RegistryOps, and RegistryFileCodec and HolderSetCodec need one for a reference or a tag — a DelegatingOps carrying a RegistryOps.RegistryInfoLookup beside whatever real ops it wraps. There are two routes worth knowing: HolderLookup.Provider.createSerializationContext, which is what nearly every caller uses, and RegistryDataLoader.createContext, used during registry loading itself, when the registries are still being built (identifiers and registries). Both end at RegistryOps.create, which a handful of callers reach directly.

A codec over a built-in registry is a different case: Registry.holderByNameCodec — and so Item.CODEC — resolves against the registry instance captured inside the codec, and works on bare NbtOps.INSTANCE. The distinction is not academic. It decides which paths must build a context before they can decode anything, and in practice almost every real path must: TagValueOutput.createWithoutContext exists and is called by nothing at all, and there is no context-free ValueInput even in principle.

On the network the same context arrives as a decorator. RegistryFriendlyByteBuf adds RegistryFriendlyByteBuf.registryAccess to a FriendlyByteBuf, and RegistryFriendlyByteBuf.decorator is bound when the protocol switches from configuration to play. Configuration packets have no registry context — which is why registry data and tags are sent in that phase as NBT and ids, and why the ByteBufCodecs.holder family is play-only (protocol phases).

What NBT actually is

Tag is a sealed interface, and the scalar leaves are records.

Because the leaves are records, the old getAsInt family is gone: Tag.asInt and Tag.asString return Optional, CompoundTag.getInt is Optional and CompoundTag.getIntOr is its defaulted form, CompoundTag.get is still nullable, and the two-argument contains taking a type id no longer exists.

Three things about the binary form surprise people.

A mixed-type list is boxed on the way out. Binary NBT stores one element type per list, so ListTag.write promotes a heterogeneous list to compounds and wraps each element in a one-entry compound under the empty key, with ListTag.addAndUnwrap the exact inverse on read. This is not a legacy artefact left lying around — it is written today, and it is the whole reason mixed lists are legal at all.

A numeric array stays an array, but nothing turns a list into one. NbtOps.createCollector hands back a NbtOps.GenericListCollector for an empty list and only reaches for NbtOps.ByteListCollector, NbtOps.IntListCollector or NbtOps.LongListCollector when it is handed an existing ByteArrayTag, IntArrayTag or LongArrayTag — and those degrade back to the generic collector the moment an element does not fit. A codec building a fresh list gets a ListTag, whatever is in it; the arrays on disk are written by the codecs that asked for arrays.

A whole file need not be read to answer a question about it. StreamTagVisitor and the visitors beside it let NbtIo.parse pull a named handful of fields out of a region chunk without materialising the chunk: a CollectFields is built from the FieldSelectors the caller wants, two for the IOWorker reading a chunk’s data version and its blending data, three for StructureCheck, which is how it answers without loading a chunk; the world-list screen does the same to level.dat with SkipFields.

Every read that came from outside carries a budget. NbtAccounter is charged as the per-type read strategy in TagType walks the stream, with NbtAccounter.DEFAULT_NBT_QUOTA at 2 MiB, NbtAccounter.UNCOMPRESSED_NBT_QUOTA at 100 MiB and a depth cap of NbtAccounter.MAX_STACK_DEPTH; overrunning any of them raises an NbtException. Region compression is a separate global: RegionFileVersion.configure sets one process-wide selection from region-file-compression, a RegionFile captures it once for writing, but every chunk carries its own version byte and reads honour that — so one world can hold chunks in several compressions at once. RegionFileVersion.VERSION_CUSTOM (id 127) is the marker for a chunk written with a compression the game does not name; the marker for a chunk that grew too big and lives in its own external file is a different one — RegionFile’s external-stream flag, 128, set in the version byte. And NbtIo.writeCompressed (GZIP) is for the standalone files, level.dat and player data.

The text form is TagParser, and it is generic over its output ops rather than producing tags: SNBT can decode straight into any format’s target without a CompoundTag in between. TagParser.parseCompoundFully is the plain-string entry point; TagParser.FLATTENED_CODEC accepts an SNBT string only, and TagParser.LENIENT_CODEC, built as an alternative of the two, is the one that takes a string or an object interchangeably. Under it, SnbtGrammar is a packrat grammar and SnbtOperations supplies the built-in bool and uuid functions.

Save code never sees a CompoundTag

ValueOutput and ValueInput are the façade every BlockEntity and Entity writes through — ValueOutput.store with a codec, ValueOutput.child, ValueOutput.list, and typed getters with defaults on the way back in (ValueInput.getIntOr, ValueInput.getStringOr). The only implementations are TagValueOutput and TagValueInput, which wrap a CompoundTag and a DynamicOps, with ValueInputContextHelper holding the shared provider and the empty instances. The CompoundTag-returning methods on BlockEntity are final shells that build one of these, and they differ only in how much metadata they add: BlockEntity.saveCustomOnly none, BlockEntity.saveWithoutMetadata the block entity’s own components as a full DataComponentMap, and BlockEntity.saveWithFullMetadata the id and x, y and z. BlockEntity.saveWithId adds the id too, but only in the ValueOutput form — it has no CompoundTag shell.

The point of the façade is that an encode failure is reported, not thrown. Everything goes through a ProblemReporter, and ProblemReporter.ScopedCollector logs the whole collected tree of problems when it closes, rooted at BlockEntity.problemPath or Entity.problemPath; TagValueOutput.EncodeToFieldFailedProblem and its siblings are what a bad codec produces. An item that will not serialise costs you the item, not the tick. The deliberate exceptions to the façade are CustomData and TypedEntityData, the two components that carry a CompoundTag verbatim so that data packs have an escape hatch (data components).

Migration is the one thing that runs before any of this. DataFixTypes is the enum of every kind of file the game owns — DataFixTypes.CHUNK, DataFixTypes.PLAYER, DataFixTypes.LEVEL, DataFixTypes.OPTIONS and the rest — and each calls DataFixTypes.updateToCurrentVersion on the DataFixerUpper DataFixer from DataFixers.getDataFixer before the codec is shown the tag, using the data version NbtUtils.addCurrentDataVersion stamped when the file was written. The fixes themselves are out of scope here.

Trusted, untrusted and validated

The wire’s own vocabulary for how far to trust a document belongs to packets and stream codecs: the trusted/plain pairs are a read budget chosen by direction, and the creative slot is the one packet that carries an arbitrary stack and is fenced three ways for it. What belongs here is the fact that stands behind those fences: this page’s four paths run one ItemStack four ways, and the creative slot’s is the only one where the codec is run for its errors rather than its output. ItemStack.validatedStreamCodec re-encodes a decoded stack through ItemStack.CODEC into NullOps and keeps nothing but the problems — the persistent codec is used as a validator for the wire one, which is why a creative-mode stack cannot carry a component the disk would reject.

JSON, the third format in the title and the smallest on the wire

JSON is the format with the smallest footprint. It is the data packs, and on the wire it survives in exactly two places, both outside the play phase: ClientboundStatusResponsePacket and ClientboundLoginDisconnectPacket, sent through ByteBufCodecs.lenientJson. That is why the game ships two JSON parsers — LenientJsonParser for the wire and StrictJsonParser for data packs. Neither is where most JSON reading happens, though. GsonHelper is the toolbox — sixty-nine static helpers, most of them pulling one typed field out of a parsed object and naming the field in the exception when it is missing or the wrong shape — and it is the pre-codec way of reading JSON, still called from 124 places: the model loaders, the particle definitions, the operator, allow and ban lists, and the data fixers. It sits outside the codec pipeline but for one length check inside ComponentSerialization.flatRestrictedCodec; a field it reads is read by a hand-written parser and a field a codec reads is not. Chat text itself is NBT by the time it reaches the play phase: ComponentSerialization holds that whole matrix in one class (text components).

Questions players ask

Why does an item look identical and not stack? Because equality is prototype plus patch, and the patch is what these codecs round-trip. Two stacks that took different routes to the same components compare equal; one that kept a component the other dropped does not, however the tooltip reads.

Why can a data pack put arbitrary NBT on an item at all? Because CustomData and TypedEntityData are components whose value is a CompoundTag, passed through verbatim. Everything else on a stack has a real codec and is checked by it.

Why does a corrupt item vanish instead of crashing the world? Because the save façade reports rather than throws. The bad field becomes a problem on a ProblemReporter and is logged when the scope closes, and the chunk saves without it.

Why is a creative-mode item the one thing the server double-checks? Because it is the only packet on which a client authors a whole stack. Everywhere else the client either receives stacks or asserts hashes about stacks the server already sent it.

Why can a world hold chunks in two different compressions? Because the compression setting is captured per RegionFile for writing only, and every chunk stores the version byte it was written with. Reads honour the byte.

Where to look

Codec · DynamicOps · ExtraCodecs · RegistryOps · HolderLookup.Provider.createSerializationContext · Tag · CompoundTag · ListTag · NbtOps · NbtIo · NbtAccounter · TagParser · StreamTagVisitor · HashOps · NullOps · ValueOutput · ValueInput · TagValueOutput · ProblemReporter · BlockEntity (the save shells) · ContainerHelper · ItemStackWithSlot · ItemStack (the codec fields) · StreamCodec · ByteBufCodecs · RegistryFriendlyByteBuf · PacketEncoder · HashedPatchMap · ItemParser · DataFixTypes · RegionFileVersion

Rules: names, never code · how the system works, not how the code reads · newest version only · every backticked name passes tools/verify_names.py.

Identifiers and registries

Verified against Minecraft 26.3 · Part II · A player types /give @s minecraft:diamond_sword, and the sword reaches their inventory as the number of the line it was registered on.

A player types /give @s minecraft:diamond_sword. The string on the right is parsed into an Identifier, the identifier is paired with Registries.ITEM to make a ResourceKey, and the key is looked up in a table the server froze at startup, before any world existed — BuiltInRegistries.ITEM. The stack that then lands in the player’s inventory does not carry the name. Item.STREAM_CODEC is ByteBufCodecs.holderRegistry over Registries.ITEM, and it writes an integer. That integer is a line number. MappedRegistry.byId is an insertion-ordered list, MappedRegistry.register appends to it, and an entry’s numeric id is its position — so the wire id of a diamond sword is where its line falls in Items, reordering two lines in Blocks changes a block’s wire id, and a resource pack cannot. A dynamic registry, a biome from a data pack, gets its numbers the other way: its elements are decoded in parallel but registered in sorted order of their ids, so the server’s numbering does not depend on which file finished first. The client does not re-derive those numbers at all — it registers what the server sent, in the order the packet lists them.

The cast

All of this is server and client: MappedRegistry, BuiltInRegistries and RegistryDataLoader ship in the dedicated server jar. Client-only, of the classes this page names, are ClientRegistryLayer, RegistryDataCollector, KnownPacksManager and the client’s CommonListenerCookie — and, less surprisingly, ClientPacketListener, ClientConfigurationPacketListenerImpl and IntegratedServer.

The name

Identifier, in net/minecraft/resources, is a namespace and a path, and it is the class a 1.21-era reader knows as ResourceLocation. It is not a record: a final class with a private constructor whose validation is an assertion on the trusted path and a real check on the parsing paths (Identifier.isValidNamespace, Identifier.isValidPath). The two character sets differ, and the difference bites: a path may contain /, a namespace may not, and .. is rejected outright as a namespace. Identifier.DEFAULT_NAMESPACE is minecraft, and Identifier.withDefaultNamespace supplies it — as does parsing a string with no separator at all, or one that starts with the separator. Identifier.parse throws IdentifierException (which lives in net/minecraft, not beside Identifier) where Identifier.tryParse returns null. Identifier.read exists twice, once returning a DataResult for Identifier.CODEC and once over a Brigadier StringReader, with Identifier.readNonEmpty beside it, and Identifier.resolveAgainst carries a path-traversal guard. The one that surprises people: Identifier.compareTo orders by path first and namespace second, so a sorted list of ids is not grouped by mod.

A ResourceKey is an Identifier paired with the Identifier of the registry it belongs to, and keys are interned through a weak map keyed by ResourceKey.InternKey, so two keys for the same registry and id are literally the same object. Registries holds the 156 ResourceKeys of registries (Registries.ITEM, Registries.BIOME …) — 155 distinct objects, because two of the keys are one: Registries.DIMENSION and Registries.LEVEL_STEM are both built from the string dimension, so interning hands back one object under two names and two (unchecked) element types — Registries.LEVEL_STEM is the data-pack registry the RegistryLayer.DIMENSIONS layer loads, Registries.DIMENSION keys the ServerLevels, and the conversion helpers between them are identity functions at run time. Five more registry keys are declared by the class that owns them rather than here, which is why the catalogue’s total is 161 and this one is 156 (registries). Interning is what makes identity work: ResourceKey declares no equality of its own, so MappedRegistry.byKey, MappedRegistry.registrationInfos, Holder.Reference.is for a ResourceKey and every == against a key like Level.OVERWORLD rely on equal keys being one object. BlockIds, ItemIds and BlockItemIds (net/minecraft/references) hold the per-element keys the block and item initialisers use.

The table

Registry is the read interface — Registry.getValue, Registry.getKey, Registry.getId, Registry.getTags, and the codecs Registry.byNameCodec and Registry.holderByNameCodec — and it extends IdMap, so every registry is also an int-to-object table. WritableRegistry adds WritableRegistry.register and WritableRegistry.bindTags; DefaultedRegistry answers a default entry — air for items and blocks — instead of null. MappedRegistry is the one real implementation, with DefaultedMappedRegistry its only subclass. It holds the same entries in five indexes at once, and every lookup direction is one of them: MappedRegistry.byKey and MappedRegistry.byLocation from a name, the insertion-ordered MappedRegistry.byId from a number, and, from the object itself, the two identity maps MappedRegistry.byValue — what answers Registry.getKey — and MappedRegistry.toId, which returns −1 for anything it has never seen, an equal-but-distinct object included. It carries the MappedRegistry.frozen flag that MappedRegistry.validateWrite checks on every ordinary write.

A Holder is the seam between a registry and the code that names its entries. It is a sealed interface with two kinds (Holder.Kind). Holder.Reference is an entry in a registry — and is itself non-sealed: it knows its HolderOwner, its key, its tags and its components, and any of those may be unbound until the registry binds them (Holder.Reference.bindValue, Holder.Reference.bindTags, Holder.Reference.bindComponents). A reference is a promise: Holder.Reference.value throws until Holder.Reference.bindValue has run, codecs hand these out freely during a load, and the freeze is what makes every promise kept — or fails loudly. Holder.Direct is a record wrapping an inline value and a DataComponentMap that belongs to no registry: it has no key, is in no tag, and serialises inline. A HolderSet is a set of holders — HolderSet.Named is a tag, HolderSet.Direct a literal list.

What a codec sees is a read-only view. HolderGetter, HolderLookup and HolderOwner are those views — and HolderOwner exists for exactly one question, HolderOwner.canSerialize: the context asking to serialise a holder answers whether it is that holder’s owner, which is why a holder from one world refuses to be written by another; HolderLookup.Provider is “all the registries I may resolve against” and HolderLookup.RegistryLookup is one of them. RegistryAccess is a HolderLookup.Provider over a set of registries, and RegistryAccess.Frozen is a bare marker for the finished kind. Every static initialiser writes its elements through Registry.register or Registry.registerForHolder (the registries themselves go into the root through WritableRegistry.register); every codec that names a dynamic entry — RegistryFileCodec, RegistryFixedCodec, RegistryCodecs.holderSet, HolderSetCodec — resolves through a RegistryOps (codecs, NBT and JSON); and at runtime MinecraftServer.registryAccess and ClientPacketListener.registryAccess are where anything that must resolve a key goes, except the server’s reloadable registries, which MinecraftServer.reloadableRegistries holds.

Before the game exists

sequenceDiagram
    participant Boot as Bootstrap
    participant BIR as BuiltInRegistries
    participant Items as Items
    participant Item as Item
    participant DMR as Defaulted<br/>MappedRegistry

    Note over Boot,DMR: the launching thread, before any server or client object exists
    Boot->>BIR: class init: one empty registry per key, 95 of the 156, each with a loader
    Note over Boot,Items: the dispenser and cauldron bootstraps run first, so Items is already initialised
    Boot->>Items: class init: registerItem per item, Item.Properties.setId stores the key
    Items->>Item: new Item(properties), which knows its own key
    Item->>DMR: createIntrusiveHolder: a Holder.Reference with a value, no key
    Items->>DMR: register(key, item, BUILT_IN): bindKey, numeric id = byId.size()
    Boot->>BIR: bootStrap: createContents runs every loader, then freeze, then validate
    BIR->>BIR: freeze: the root, then each registry — tags bound empty, then MappedRegistry.freeze
    DMR->>DMR: bindValue on every holder, refuse an unbound one, build componentLookup
    Note over Boot,DMR: components and tags are bound together later, when a world loads

The bootstrap ladder, on one thread, before either program exists. The numeric id an item gets is the size of the registry when it registers — the line number of its registration — which is why the wire ids are stable only because the registration order is.

Both Main classes call Bootstrap.bootStrap early, after argument parsing and crash-report preload (anatomy has the order), on the launching thread before any server or client object exists, and Bootstrap.isBootstrapped is set before any registry is touched. Bootstrap.bootStrap calls BuiltInRegistries.bootStrap, and after it returns every built-in registry is frozen and any WritableRegistry.register throws.

Registries exist before their contents. BuiltInRegistries class init creates every registry empty and records the loader that fills it in BuiltInRegistries.LOADERS, an insertion-ordered map. Bootstrap.bootStrap then runs BuiltInRegistries.createContents — the loaders in that order. By then Items, Blocks and EntityTypes are already initialised: Bootstrap.bootStrap reaches FireBlock.bootStrap, EntityTypes.PLAYER, the dispense behaviours’ bootstrap and CauldronInteractions.bootStrap before it calls BuiltInRegistries.bootStrap, and those touch Blocks, EntityTypes and Items in that order — so BuiltInRegistries.createContents finds the loaders’ values already there rather than triggering them. Bootstrap.checkBootstrapCalled is the guard that makes “touched Blocks from a static initialiser” a crash rather than a silent empty registry; it works because the bootstrap flag is set before the registries are touched, not after.

The key travels in the properties. Items.registerItem takes a ResourceKey from ItemIds or BlockItemIds and calls Item.Properties.setId before constructing, so an Item knows its own key at construction time. Blocks do the same with BlockIds and BlockItemIds and BlockBehaviour.Properties.setId.

Five registries hand the object its own holder. BuiltInRegistries.BLOCK, BuiltInRegistries.ITEM, BuiltInRegistries.FLUID, BuiltInRegistries.ENTITY_TYPE and BuiltInRegistries.BLOCK_ENTITY_TYPE are created with intrusive holders: the constructor asks the registry for a Holder.Reference (MappedRegistry.createIntrusiveHolder) that wraps the object before it has a key, and stores it in Item.builtInRegistryHolder. Registration then binds the key to that holder rather than creating a new one, so Item.builtInRegistryHolder and the registry’s own holder are the same object, and a tag check on a block or item is a set lookup on the holder’s own bound tag set with no registry hop (tags). Holder.Reference.createIntrusive is marked deprecated — the mechanism is load-bearing but not encouraged.

The numeric id is the line number. MappedRegistry.register appends to MappedRegistry.byId, and every static registration carries RegistrationInfo.BUILT_IN — a Lifecycle and the KnownPack an entry came from, which for a static entry is nothing. The wire id of an item is the position of its line in Items, and Item.STREAM_CODEC encodes that integer. A dynamic registry numbers the other way, and the difference is worth holding: ResourceManagerRegistryLoadTask decodes its files in parallel and then registers them in sorted order of their ids, so the server’s numbering is the same whichever file finished first. The client still never derives a number — it registers what the packet lists, in the order the packet lists it — but because the server sorted, that order is reproducible rather than accidental.

Freeze is a proof, stated in full below. BuiltInRegistries.freeze freezes the root registry first, then every registry it holds, and BuiltInRegistries.validate closes the bootstrap: an empty registry is logged, a DefaultedRegistry whose default key is missing throws.

When a world opens

The server keeps its registries as a LayeredRegistryAccess in MinecraftServer.registries, one layer per RegistryLayer — RegistryLayer.STATIC, RegistryLayer.WORLD, RegistryLayer.DIMENSIONS, RegistryLayer.RELOADABLE, in that order — with MinecraftServer.registryAccess the flattened view. LayeredRegistryAccess.getAccessForLoading is everything before a layer, which is what that layer’s JSON may reference; LayeredRegistryAccess.compositeAccess is everything. The client mirrors this with two layers, ClientRegistryLayer.STATIC and ClientRegistryLayer.REMOTE. On both sides the STATIC layer is RegistryAccess.fromRegistryOfRegistries over BuiltInRegistries.REGISTRY — a live view of the frozen root registry, not a copy of it.

flowchart TD
    WL["WorldLoader.load, on Util.backgroundExecutor"]:::worker
    RDL["RegistryDataLoader.load for the world<br/>registries, then the dimensions"]:::worker
    T1["one RegistryLoadTask: feature"]:::worker
    T2["one RegistryLoadTask: placed feature"]:::worker
    T3["… one per RegistryDataLoader.RegistryData, 51 then 1"]:::worker
    F["RegistryLoadTask.freezeRegistry binds every promise,<br/>then the RegistryValidator"]:::worker
    LRA["LayeredRegistryAccess.replaceFrom:<br/>world and dimensions in one call"]:::worker
    WL --> RDL
    RDL --> T1
    RDL --> T2
    RDL --> T3
    T1 -. "an unbound Holder.Reference" .-> T2
    T2 -. "an unbound Holder.Reference" .-> T1
    T1 --> F
    T2 --> F
    T3 --> F
    F --> LRA

World load, as a task graph rather than a conversation: one task per registry, all on the worker pool, each able to ask any other in the same call for an element it has not registered yet. The dotted edges are the forward references, the freeze is where they stop being promises, and the last box runs on the worker pool too, not on the thread that called WorldLoader.load.

Later, a client logs in and reaches the configuration phase, and the server sends it what it just built.

sequenceDiagram
    box transparent the server
    participant SRT as Synchronize<br/>RegistriesTask
    participant SCPL as ServerConfiguration<br/>PacketListenerImpl
    end
    box transparent the client
    participant CCPL as ClientConfiguration<br/>PacketListenerImpl
    participant RDC as RegistryData<br/>Collector
    end

    SRT->>CCPL: ClientboundSelectKnownPacks: which packs do you have?
    CCPL->>SCPL: ServerboundSelectKnownPacks: accepted all-or-nothing
    SRT->>CCPL: one ClientboundRegistryDataPacket per synced registry
    Note over SRT,CCPL: an entry from a pack the client has carries no data
    SRT->>CCPL: ClientboundUpdateTagsPacket: tags as registry ints
    SCPL->>CCPL: ClientboundFinish<br/>ConfigurationPacket
    CCPL->>RDC: collectGameRegistries: rebuild REMOTE, patch the static tags
    RDC->>CCPL: a RegistryAccess.Frozen, into the play listener's cookie
    Note over CCPL,RDC: with an IntegratedServer, that Frozen is thrown away<br/>for the server's own registries
    CCPL->>SCPL: ServerboundFinish<br/>ConfigurationPacket

The same registries crossing to a client: SynchronizeRegistriesTask sends the three data packets, and the fourth, which lets play begin, comes through the listener from a later task, JoinWorldTask. The client decodes none of it until that finish packet arrives, and the last note is the singleplayer case, where the work of the whole exchange is discarded.

WorldLoader.load creates the resource manager on the main thread, runs RegistryDataLoader.load on Util.backgroundExecutor, and returns to the main thread for the final assembly; this is where the RegistryLayer.WORLD and RegistryLayer.DIMENSIONS layers are filled, and the RegistryLayer.RELOADABLE layer of the copy MinecraftServer.reloadableRegistries holds. The configuration phase is the third moment: SynchronizeRegistriesTask sends the dynamic registries on the server thread, and the client rebuilds its ClientRegistryLayer.REMOTE layer in RegistryDataCollector.collectGameRegistries — decoding on the worker pool, joined on the Render thread — before it will accept play packets.

Layers load against the layers before them. RegistryDataLoader.load is given lookups built from LayeredRegistryAccess.getAccessForLoading — built by TagLoader.buildUpdatedLookups, so that the static registries’ freshly read tags are visible to the worldgen codecs before they are applied (tags) — so a biome JSON may reference a placed feature (same layer) or a sound event (RegistryLayer.STATIC) but never a level stem (RegistryLayer.DIMENSIONS, which loads after). The lists RegistryDataLoader.WORLD_REGISTRIES, RegistryDataLoader.DIMENSION_REGISTRIES, RegistryDataLoader.RELOADABLE_REGISTRIES and RegistryDataLoader.SYNCHRONIZED_REGISTRIES say which keys belong to which step and which subset the client is told about. Both the world and the dimensions layers are installed in a single LayeredRegistryAccess.replaceFrom call, and the dimensions layer that wins is the world data’s, not necessarily the one just decoded — a saved world’s dimension set survives.

Loading is a task graph. Each registry is one RegistryLoadTask owning a fresh MappedRegistry and a lock-guarded ConcurrentHolderGetter. RegistryDataLoader.createContext hands every task’s getter to every other, so Biome.DIRECT_CODEC decoding on one worker can ask for a carver that another worker is still registering — the getter returns an unbound Holder.Reference, and the reference is bound when that registry freezes. Forward references cost nothing, even in a cycle — a feature can name placed features and a placed feature its feature — because nothing waits on them. Fourteen of the fifty-two world and dimension registries also carry a RegistryValidator other than the empty one in their RegistryDataLoader.RegistryData, run after the freeze — thirteen of them entity-variant registries running the same check, RegistryValidator.nonEmpty, and the fourteenth Registries.TIMELINE, whose Timeline.validateRegistry is its own.

Provenance is recorded per entry, and it is coarser than it looks. ResourceManagerRegistryLoadTask gives each element a RegistrationInfo naming the KnownPack it came from and a Lifecycle. The rule is presence, not vanilla-ness: an element from any pack that reports a KnownPack is stable, and only an element from a pack with no known-pack info is experimental. KnownPack.isVanilla is computed on that path and then discarded. Anything received over the network is experimental, and the RegistryLayer.RELOADABLE layer is read by the same task under the same rule; the registry’s own lifecycle is the merge of its entries’, and that merge is what the “experimental features” warning on world open reads.

The client is told what it does not already have. SynchronizeRegistriesTask first asks the client which KnownPacks it has (ClientboundSelectKnownPacks). The request lists only the server’s packs that declare one — PackLocationInfo.knownPackInfo is an optional, so a world’s own datapack is simply absent from it — and the client matches them against its bundled vanilla repository through KnownPacksManager.trySelectingPacks. The comparison is all or nothing: the client’s answer must equal the request exactly, or every element of every synced registry is sent in full. On a match, RegistrySynchronization.packRegistries sends every element’s id but leaves the NBT payload empty for entries from those packs, and the client’s RegistryLoadTask.PendingRegistration.findAndLoadFromResource re-decodes the JSON from its own jar. A modified biome from a custom data pack is sent in full through Biome.NETWORK_CODEC — the network codec, which omits the generation and mob-spawn settings the client never needs.

The client rebuilds one layer and patches the other. RegistryDataCollector accumulates the packets, and RegistryDataCollector.collectGameRegistries runs when configuration finishes — dispatching the load onto a background executor against the negotiated packs and then blocking on the result, so the decoding leaves the Render thread, which waits for it, without the phase becoming asynchronous. The ClientRegistryLayer.REMOTE layer is rebuilt wholesale and frozen — but the static registries cannot be rebuilt, so their tags are applied in place, through the mechanism tags owns, and when no registry data arrived at all the collector takes a tags-only path that patches and returns the original registries untouched. The result is a RegistryAccess.Frozen in CommonListenerCookie that every RegistryFriendlyByteBuf in the play phase decodes against.

Singleplayer throws most of that away. When an IntegratedServer exists, ClientConfigurationPacketListenerImpl.handleConfigurationFinished substitutes the server’s own registries for the ones the client just built, and the memory connection suppresses re-applying static tags and components client-side. Both halves then share the same registry objects — which is worth remembering whenever a page says “the client’s copy”.

The freeze rule, stated

A frozen registry’s contents never change. Its tags and its elements’ components do. Everything in this part that looks like an exception to the first sentence is one of the two things in the second.

MappedRegistry.freeze is a proof, not a switch. It binds every holder’s value and throws if any holder is still unbound, if any intrusive holder was created but never registered, or if any tag declared by a TagKey was never bound. The tag half of that proof works because a registry keeps its declared tags apart from its bound ones, which is the split tags is built on: the freeze checks the declared table and installs the bound one. For the static registries the real tags do not exist until a data pack is read, so BuiltInRegistries.freeze first binds the tags the bootstrap asked for to empty (MappedRegistry.bindAllTagsToEmpty) and the proof passes on empty sets. The freeze also builds MappedRegistry.componentLookup. After it, the MappedRegistry.frozen flag makes MappedRegistry.validateWrite throw on every ordinary write. Two things still change: MappedRegistry.prepareTagReload requires the frozen flag, and the component prototypes are rebound beside the tags (data components).

What changes afterwards changes through two doors. Tags: a world load swaps the tag tables of the static registries, and /reload does more than refill the RegistryLayer.RELOADABLE layer — it re-reads and re-applies tags for every registry in the server’s composite access. How a frozen registry’s tags are swapped is the pay-off of tags, and the mechanics of the reload itself belong to the resource system. Components: components are not part of the freeze at all. Every registry element’s DataComponentMap is bound after it by Holder.Reference.bindComponents, and /reload rebinds every one of them; data components owns how.

Feature flags: the same registry, narrowed

A frozen registry’s contents never change — but what a lookup will show you can be narrower than what the registry holds, and that is most of the feature-flag mechanism; the rest is a direct FeatureElement.isEnabled check where an element is used. FeatureFlagSet is a bitmask: a 64-bit long and the FeatureFlagUniverse it belongs to, with FeatureFlagSet.MAX_CONTAINER_SIZE at 64 flags. There is one universe, main, and FeatureFlags declares four flags in it — FeatureFlags.VANILLA and the three experiments, FeatureFlags.TRADE_REBALANCE, FeatureFlags.REDSTONE_EXPERIMENTS and FeatureFlags.MINECART_IMPROVEMENTS. A set that is not a subset of FeatureFlags.VANILLA_SET is what FeatureFlags.isExperimental reports, and what puts the warning on a world.

What carries a flag is a registry element. FeatureElement is an interface whose one abstract method is FeatureElement.requiredFeatures, implemented by exactly seven types — Item, BlockBehaviour, EntityType, GameRule, MenuType, Potion and MobEffect — and FeatureElement.FILTERED_REGISTRIES names the seven registries those live in. HolderLookup.RegistryLookup.filterFeatures is the filter: handed the world’s enabled set, it returns the same lookup untouched for any registry not in that set of seven, and a delegating lookup that hides the disabled elements for one that is. The registry underneath is not touched, and neither is its numbering — a disabled item keeps its wire id.

That is why an experiment is enabled per world and not per install. The set is WorldDataConfiguration.enabledFeatures, read from level.dat, and the filtered lookup is what CommandBuildContext hands every argument type, so /give cannot name a disabled item and /setblock cannot name a disabled block; GameRules builds its map from the filtered BuiltInRegistries.GAME_RULE, so a disabled rule is not merely refused but absent; and LevelReader.holderLookup filters for anything that asks a level for a registry. Where the flags come from is the pack stack — a feature pack is a built-in pack carrying a FeatureFlagsMetadataSection, and turning on an experiment is enabling a data pack (the resource system).

What crosses the wire, and where the files are

Built-in registry elements never cross the network — both sides ran the same static initialisers — but their tags do, and dynamic elements do: ClientboundSelectKnownPacks and ServerboundSelectKnownPacks, then ClientboundRegistryDataPacket (one per synchronised registry, entries as RegistrySynchronization.PackedRegistryEntry) in the configuration phase, then ClientboundUpdateTagsPacket, which is a common packet and arrives again mid-play after a server /reload; and a registry element, built-in or dynamic, crosses inside other packets as a bare varint id resolved against the buffer’s registry access, except in the few packets that send its key. Only one variant shifts that numbering: ByteBufCodecs.holder reserves 0 for an inline Holder.Direct and writes every registry id one higher, where ByteBufCodecs.holderRegistry — which Item.STREAM_CODEC uses — writes the raw id. On disk, every key in RegistryDataLoader.WORLD_REGISTRIES and RegistryDataLoader.DIMENSION_REGISTRIES reads data/<namespace>/<registry path>/*.json (Registries.elementsDirPath) through FileToIdConverter.registry over a ResourceManager (the resource system), its tags live under Registries.tagsDirPath — there is a third path builder, Registries.componentsDirPath, but it names a reports directory the data generator writes and nothing in the running game reads — and the reloadable set (loot tables, predicates, item modifiers, recipes, advancements and three more) is read the same way, through ReloadableServerRegistries. Which registry is which kind is reference/registries.

For a 1.21-era reader. Identifier was ResourceLocation, and the vanilla data you remember being registered in code is now read as JSON like anyone else’s: RegistrySetBuilder, BootstrapContext and VanillaRegistries are the data generator that writes those files into the jar, and the running game only ever reads them (what this book skips has how far that is true). And Block.BLOCK_STATE_REGISTRY is not a registry: IdMapper is the standalone IdMap behind block-state ids and similar palettes, sharing an interface with Registry and nothing else.

Where to look

Identifier · ResourceKey · Registries · Registry · MappedRegistry.register · MappedRegistry.freeze · DefaultedMappedRegistry · Holder · HolderSet · HolderLookup · Bootstrap.bootStrap · BuiltInRegistries.bootStrap · RegistryLayer · LayeredRegistryAccess · WorldLoader.load · RegistryDataLoader.load · RegistryLoadTask · ResourceManagerRegistryLoadTask · RegistryValidator · RegistrySynchronization.packRegistries · SynchronizeRegistriesTask · RegistryDataCollector.collectGameRegistries · NetworkRegistryLoadTask · ClientConfigurationPacketListenerImpl.handleConfigurationFinished · RegistryOps

Rules: names, never code · how the system works, not how the code reads · newest version only · every backticked name passes tools/verify_names.py.

The resource system

Verified against Minecraft 26.3 · Part II · A player presses F3+T, the screen goes to the logo and a bar, and every texture, model, sound and font is rebuilt from a stack of packs without the game stopping.

A player presses F3+T. The screen goes red, the Mojang Studios logo comes up, and a white bar creeps across under it while the old world keeps rendering behind. What is happening is one pipeline that everything the game reads from a pack goes through — textures, models, sounds, language strings, recipes, advancements, loot tables, tags, worldgen JSON: a stack of packs is discovered, merged into a resource manager that is a snapshot of the stack, and a list of reload listeners each rebuild their world from it, preparing at once on the worker pool (anatomy) where they have anything to prepare, and swapping their live state on the owning thread in the order they were registered. The client’s stack is resource packs (PackType.CLIENT_RESOURCES, the assets tree); the server’s is data packs (PackType.SERVER_DATA, the data tree) — same classes, two instances, two directories, and /reload is the same pipeline run by the server. The surprising part is the end. A reload that fails does not find the offending pack. Minecraft.rollbackResourcePacks deselects every resource pack it can, clears the options lists, saves, and reloads again — and if vanilla was the only selected pack it rethrows and crashes instead.

The cast

The pipeline

flowchart TD
    D["discover: PackRepository.reload re-runs every RepositorySource"] --> S["snapshot: a new MultiPackResourceManager over the opened packs"]
    S --> P["prepare: the worker pool reads, all at once"]
    P --> A["apply: each listener swaps its live state, in registration order"]
    A -- "ReloadInstance.checkExceptions finds none" --> F["finish: the level re-extracted"]
    A -- "a listener threw" --> R["roll back: every pack deselected"]
    R -- "the reload run again" --> D

The five stages and the one branch, which comes at the end and not at the start. A snapshot is of the pack list, not of the bytes; the rollback arrow runs back to discover because what follows a failure is another whole reload, not a retry of the stage that failed.

The rest of the page is a section per stage: what comes in, what is decided, what goes out. F3+T is the grounding trace; /reload is the coda, as a table of where the server’s run of the same pipeline differs.

Discover: the repository and its packs

What comes in is a set of RepositorySources (server/packs/repository), each a place packs are found. ClientPackSource and ServerPacksSource are the built-ins, both extending BuiltInPackSource, which also lists the packs bundled inside the vanilla pack — the art packs, the accessibility packs and every feature pack (BuiltInPackSource.TESTS_ID names one more, tests, which only a development build enables); FolderRepositorySource is a directory of user packs; DownloadedPackSource is server-sent packs, client only. PackRepository.reload re-runs every source into the available map and then rebuilds the selected list: prior choices are kept, and a pack whose Pack.isRequired is true is force-inserted at its Pack.getDefaultPosition. Reading the order out of options.txt is a startup step — Options.loadSelectedResourcePacks runs once in the Minecraft constructor, not on every F3+T.

A Pack is a discoverable pack: a PackLocationInfo (id, title, PackSource, optional KnownPack), a Pack.ResourcesSupplier that can open it, its Pack.Metadata (description, PackCompatibility, requested feature flags, overlays) and a PackSelectionConfig — required, default Pack.Position, fixed. Pack.Position owns the insertion algorithm that makes a fixed pack stick, and the list it inserts into runs from the bottom of the stack to the top: Pack.Position.BOTTOM inserts at the front of the list, past any pack already fixed there, and Pack.Position.TOP at the back. The last pack in the list wins (next section), which is why vanilla is BOTTOM and why “higher in the UI” means “later in the list”. The client’s vanilla pack cannot be deselected and the server’s can: ClientPackSource marks vanilla required and bottom; ServerPacksSource marks it bottom but optional.

What a pack is on disk is PackResources (server/packs): the raw file source with PackResources.getResource, PackResources.listResources and PackResources.getNamespaces. FilePackResources is a zip; PathPackResources a directory; OverlayedPackResources a pack plus its overlays subdirectories, which the Pack.ResourcesSupplier assembles for zip and folder packs. VanillaPackResources is not a PackResources itself: its Pack.ResourcesSupplier hands out FixedPathPackResources layers — the jar’s own assets and data, and on the client the launcher’s asset index above them — and never an overlay. Discovery is guarded: DirectoryValidator, ForbiddenSymlinkInfo and PackDetector decide what a folder is allowed to be, allowed_symlinks.txt is parsed into a DirectoryValidator by LevelStorageSource.parseValidator. One corner of server/packs is worth a sentence here. packs/linkfs is a synthetic read-only file system — LinkFileSystem, LinkFSProvider and a LinkFSPath that is a name in a tree rather than a name on disk — which presents the launcher’s asset files, stored under their hashes, as the one directory tree their index describes, so the game can open a pack that was never assembled.

What pack.mcmeta says

The file is read as ResourceMetadata sections: PackMetadataSection (description and a PackFormat range), FeatureFlagsMetadataSection, OverlayMetadataSection, ResourceFilterSection. Compatibility is a range, not a number. PackMetadataSection carries an inclusive range of PackFormat major/minor pairs and PackCompatibility reports too old, too new, unknown or compatible against the game’s own — resource 97.1 and data 121.0. Above PackFormat.lastPreMinorVersion (64 for assets, 81 for data) the min_format / max_format fields are mandatory and the old integer pack_format is not enough. A pack.mcmeta the strict codec rejects gets one more chance through a description-only fallback so the pack can at least be listed as incompatible. Overlays are versioned sub-packs: OverlayMetadataSection maps a PackFormat range to an overlays subdirectory that OverlayedPackResources layers on top of the pack itself, so one zip can carry variants for several game versions.

Feature flags are packs, but not auto-selected ones. A feature pack is a built-in pack carrying a FeatureFlagsMetadataSection, and its PackSource deliberately reports that it must not be added automatically. MinecraftServer.enableForcedFeaturePacks force-selects the ones matching the world’s forced features, and the world’s flag set is the selected packs’ requested flags joined with those forced ones. Turning on an experiment is enabling a data pack — through a different door than ordinary packs use. What the resulting FeatureFlagSet then gates is a registry lookup, and that is identifiers and registries.

What goes out of the stage is PackRepository.openAllSelected: the selected Packs opened into a list of PackResources, in order.

Snapshot: the manager

MultiPackResourceManager (server/packs/resources) is built from that list. It is a snapshot of the pack list, not of the bytes: it asks each pack for its namespaces — the first half of every id, the name of a directory under the pack’s assets or data root: minecraft for vanilla’s own files and whatever its author chose for the rest — and builds one FallbackResourceManager per namespace, each a stack searched from the last selected pack down. The old world stays up until the last apply, but the old files do not: on the client, ReloadableResourceManager.createReload closes the previous MultiPackResourceManager — with every file handle it held — before building the new one. What is frozen is which packs are in the stack; a Resource still opens its file when it is read, so a folder pack edited on disk mid-reload is observable. A zip is not: FilePackResources holds its zip open for the life of the pack.

A Resource is what a lookup returns: its source pack, an IoSupplier for the bytes — opened lazily, at read time — and a lazily-read ResourceMetadata found beside it. A .mcmeta is looked for in the winning pack or those above it, never in one below, so a pack overriding a texture without its .mcmeta loses the animation. ResourceFilterSection lets a pack hide lower packs’ files by pattern without providing replacements: MultiPackResourceManager reads each pack’s filter section and pushes it onto the namespace stacks as a filter, and a lookup that reaches a filtered entry stops there. Some loaders want every copy, not the winner: ResourceManager.getResourceStack and ResourceManager.listResourceStacks return all packs’ copies bottom-first, which is how languages, tags and atlas sources merge instead of overriding.

One more manager frames this one. ReloadableResourceManager is the long-lived client façade that holds the current snapshot and the PreparableReloadListener list; the server has no façade — each reload is a fresh MultiPackResourceManager inside MinecraftServer.ReloadableResources.

What goes out is one ResourceManager, wrapped in a PreparableReloadListener.SharedState, and a ReloadInstance that has already started, which is a SimpleReloadInstance, or its subclass ProfiledReloadInstance when the logger is at debug.

Prepare: every listener at once

A PreparableReloadListener.reload takes the shared state (which carries the ResourceManager), a background executor, a PreparableReloadListener.PreparationBarrier and a main-thread executor. SimplePreparableReloadListener splits that into SimplePreparableReloadListener.prepare (background) and SimplePreparableReloadListener.apply (main thread); SimpleJsonResourceReloadListener is the “every JSON file in a directory through one codec” specialisation, using FileToIdConverter to map assets/ns/equipment/foo.json to ns:foo; ResourceManagerReloadListener is the apply-only shape.

SimpleReloadInstance is the schedule, and this is what it does, read from SimpleReloadInstance.prepareTasks. It wraps both executors in counters. It calls PreparableReloadListener.prepareSharedState on every listener first, synchronously. Then it walks the listener list once, calling each listener’s PreparableReloadListener.reload and handing it a barrier chained to the previous listener’s returned future (the first listener’s barrier is chained to the initial task). The barrier’s PreparableReloadListener.PreparationBarrier.wait does two things: it posts a task to the main-thread executor that removes the listener from the set still preparing and completes the all-preparations future when that set empties, and it returns that future combined with the previous listener’s. So listener N’s apply runs only after every listener has reached its barrier and listener N−1 has finished entirely — apply included — and a listener that never reaches its barrier holds every apply behind it. The futures are sequenced fail-fast: the first listener to throw fails the reload as a whole. It does not stop the others — Util.sequenceFailFast completes the outer future exceptionally and leaves every prepare running; Util.sequenceFailFastAndCancel, which would cancel them, is not the one used here. What never happens is the applies.

flowchart TD
    SS["PreparableReloadListener.prepareSharedState:<br/>one synchronous pass, before any prepare starts"]:::client
    subgraph PREP["prepare, all at once"]
        TMp["TextureManager: read every texture"]:::worker
        AMp["AtlasManager: stitch every atlas"]:::worker
        MMp["ModelManager: load models and block states"]:::worker
        ETC["nineteen more listeners"]:::worker
    end
    ALL["all preparations in: every listener has reached its barrier"]:::client
    subgraph APP["apply, in registration order"]
        TMa["TextureManager: swap texture contents"]:::client --> AMa["AtlasManager: upload the atlases"]:::client
        AMa --> MMa["ModelManager: install the baked models"]:::client
    end
    SS --> PREP
    PREP --> ALL
    ALL --> APP
    SS -. "the pending sprite futures" .-> MMp
    AMp -. "completes them" .-> MMp

Three of the client’s twenty-two listeners, preparing on the worker pool and applying on the thread that owns the state, with the two rules that order them drawn once each: nothing in the lower box starts until the gate opens, and inside it each apply waits on the one above. The dotted pair is the single exception — AtlasManager.PENDING_STITCH, published in the first pass and completed during prepare, so the models load while the atlases stitch instead of queueing behind them.

The listeners registered between the three drawn are elided. Every apply waits on the all-preparations node; each apply also waits on the apply before it; and the dotted pair is the only way one listener’s prepare depends on another’s.

The shared-state channel

PreparableReloadListener.prepareSharedState is a separate first pass for a reason: it is the one place a listener can publish something for another listener’s prepare to consume, keyed by a PreparableReloadListener.StateKey. The game declares exactly one — AtlasManager.PENDING_STITCH. AtlasManager publishes a future per atlas there before any prepare starts; ModelManager and ParticleResources pull the pending sprite futures out of it and wait on them inside their own prepare, so model loading overlaps atlas stitching rather than queueing behind it. This is why the model/atlas dependency is not an apply-order dependency, and why reasoning about it from the registration list gets the wrong answer. Which thread runs that first pass depends on who started the reload: the Render thread on the client, but a worker on the server, because the server’s reload instance is created from inside an already-async chain.

Prepare never touches live state. That is the whole contract, and it is one-directional: a listener that reads from the manager in SimplePreparableReloadListener.apply is reading the new snapshot and that is fine (LanguageManager does exactly this, in the apply-only shape: LanguageManager.onResourceManagerReload reads the language files on the Render thread), while one that mutates live state in SimplePreparableReloadListener.prepare is racing the Render thread. Nothing a listener owns is torn down when a reload starts; the client keeps rendering with the old atlases while the new ones bake.

Apply: registration order

Registration order is apply order. The client registers, in order, LanguageManager, TextureManager, ShaderManager, SoundManager, AtlasManager, FontManager, the three colour listeners (GrassColorReloadListener, FoliageColorReloadListener, DryFoliageColorReloadListener), ModelManager, EquipmentAssetManager, PalettedTextureManager, EntityRenderDispatcher, BlockEntityRenderDispatcher, ParticleResources, GameRenderer, LevelExtractor, the cloud renderer, GpuWarnlistManager, a PeriodicNotificationManager, then SplashManager from Gui and WaypointStyleManager from Hud — twenty-two in all. On the client ReloadableResourceManager.createReload is called with Util.backgroundExecutor (named resourceLoad) and Minecraft itself as the main-thread executor, so apply runs on the Render thread, interleaved with frames. On the server a /reload calls ReloadableServerResources.loadResources with Util.backgroundExecutor and MinecraftServer, so apply runs on the Server thread; the first load, before any server runs, is handed the thread that waits for it — ServerMain, draining Util.blockUntilDone’s queue, on a dedicated server, and the Render thread when singleplayer opens a world.

The counters SimpleReloadInstance wrapped the executors in are where the progress bar’s numbers come from: its ReloadInstance.getActualProgress weighs prepare and apply tasks double and listeners past their barrier single, and the overlay smooths it.

Finish, or roll back

On the client LoadingOverlay is a poll. It draws the logo from the vanilla pack outside the reload (via VanillaPackResources.asResourceManager) and a smoothed bar from ReloadInstance.getActualProgress; a manual reload fades it in over half a second and it will not fade out until a full second has passed. Each tick, once ReloadInstance.isDone, it calls ReloadInstance.checkExceptions and hands the result to its finish callback. Success runs LevelExtractor.allChanged, which is why every chunk section rebuilds after F3+T, then ResourceLoadStateTracker.finishReload, DownloadedPackSource.onReloadSuccess and Minecraft.onResourceLoadFinished. Failure runs Minecraft.rollbackResourcePacks, which does not find the offending pack — it deselects every resource pack it can, clears the options lists, saves, and reloads again, and if vanilla was the only selected pack it rethrows and crashes instead. That recovery reload bypasses the one-at-a-time guard, skips the fade, and if it fails the client abandons recovery: Minecraft.abortResourcePackRecovery drops the overlay, disconnects any level and returns to the title screen with a failure toast. ShaderManager is constructed with Minecraft.triggerResourcePackRecovery for exactly this, so a shader that fails at runtime rather than at load takes the same road. Throughout, ResourceLoadStateTracker records what kind of reload this was and with which packs, so a crash report can say.