III · The server

Verified against Minecraft 26.3 · Part III · The program that owns the world: one thread, one loop, twenty times a second, from the command line that starts it to the three different ways it stops.

Everything a player thinks of as the world — the blocks, the mobs, the weather, the hunger bar — is state owned by one object on one thread, and this part is that thread doing a full lap. Part I named the Server thread (anatomy); this is the first place you watch it work. A player recognises this part by its clock: nothing in the world happens continuously, and a furnace advances in steps of a twentieth of a second. The claim the part makes is that almost everything surprising about a server’s timing is the order of one method — which step of MinecraftServer.tickChildren runs before which — and a reader who finishes it can answer when for anything the server does: when a block change reaches a screen, when a mob stops being ticked, when a chest is on disk, and what is lost if the process is killed between two of those moments.

That is a small system to know so much about. Counting the four packages the atlas lists for this part — net/minecraft/server itself, and server/level, server/players and server/dedicated under it — the way it counts everything else, it is 95 files and 21,900 lines. Over half of those lines are server/level’s forty-two files at nearly three hundred lines apiece, because the objects that own a world are few and enormous. The other landmark is one file: MinecraftServer, the largest of the ninety-five and most of this part’s first page and its last two. Part I counts it too, because it is where the Server thread is made — the atlas lets a class belong to two parts, and this is the part that watches it work.

The shape of the part

Part III is a line into a loop and out again. Two pages are the loop itself — the server tick and the one step of it that is a whole lecture — and the other three are the beginning, the population and the end.

flowchart TD
    Tick["1 · The server tick"]
    Level["2 · The level tick"]
    Players["3 · Players and sessions"]
    Start["4 · Starting a server"]
    Death["5 · How a server dies"]
    Start -- "the thread, the levels" --> Tick
    Tick -- "MinecraftServer.tickChildren" --> Level
    Level -- "the packets it wrote" --> Tick
    Tick -- "the packet drain, the connection phase" --> Players
    Players -- "a join, a disconnect" --> Tick
    Tick -- "the loop's finally" --> Death

The five lectures of Part III, numbered to the watch order and wired in the order the program runs them; an arrow is a hand-off at run time, not a dependency between lectures.

The two numbered first are the loop itself. Seven later parts (IV, V, VI, VII, VIII, IX and XIII: every later part on the server’s side of the game except world generation) assume one of those two or the other, which makes them the most load-bearing pair in the book after Anatomy. The beginning and the end are numbered last because there has to be something for them to start and stop.

Before you start

Anatomy, and specifically its two loops figure. This part assumes you know that the Server thread is an event loop as well as a game loop, that a packet is decoded on a Netty thread and handled on this one, and that the client’s frame loop is a separate clock. Part II’s codecs and registries are assumed wherever something is written to disk or sent on the wire, and the resource system is assumed once, by starting a server, which runs its staged load for server data.

Two pages from a later part are assumed, and only one of them has to be read first. Tickets and loading owns what entity-ticking and block-ticking range mean, but the level tick defines both before it uses them, so it keeps until Part IV. Environment attributes and timelines does not keep: the level tick’s first act is to throw that system’s cache away, and that step does not mean much to a reader who has never met it. Watch that page out of order; everything else in Part IV can wait.

Watch in this order

1. The server tick — one 50 ms lap: the deadline that moves before the work starts, every packet since last time handled at once, every dimension advanced, and the two writes per client that carry the tick’s own packets. “Can’t keep up!” is not a warning that the server is about to skip ticks — it is the skip.
2. The level tick — one step of that lap, which is the whole world changing: weather, scheduled ticks, mob spawns, random ticks, every entity, every block entity. The block changes are broadcast before the entities move, so a change a piston makes reaches you a tick later than one a player’s command makes — with falling sand the exception that sends its own packets, and a console command as late as the piston.
3. Players and sessions — a join from the end of the login handshake to a player standing in a world with chunks on the way, and then the four ways that session changes: death, a dimension, a disconnect, and a debug command that sends the player back through the join handshake without dropping the socket. Dying replaces your player object; the Nether does not.
4. Starting a server — java -jar server.jar to the word Done: the EULA, the lock on session.lock, the packs and registries, the thread, the levels. The step that loads the world’s chunks loads none of them on an ordinary world.
5. How a server dies — three endings compared: /stop, a crash in the tick loop, and the watchdog thread that kills a server whose tick runs past its limit. A crash in the tick saves your world. The watchdog does not.

Where the part stops

Almost nothing: 2% of the part’s lines are named on no page in the book, which after Parts I and VIII is as close to complete as the book gets. What the five lectures leave out they mostly leave to another part, because a package is not a subject; the rest is a handful of small classes no lecture names, ServerEntityGetter the largest. Chunk generation — half of ChunkMap and everything around it — is Part IV’s, where a chunk rather than a tick is the thing being followed (chunk generation). The server half of a click is Parts V, VII and VIII’s. The machinery beside the loop that commands and data packs drive — the scoreboard, the function library, the advancement manager, all living in net/minecraft/server — is Part XIII’s, and the reload beside it is Part II’s. What is left, and it is the part’s whole subject, is the loop, the levels it drives, the players in them, and the two ends of the process.

Reference this part uses

Threads — the Server thread, the worker pool and the dedicated server’s five side threads, with who makes each. Game rules — the fourteen these five pages name, out of fifty-nine. Level data and rules — which file remembers what, and how level.dat is written. Packets — everything the tick sends. Diagram lanes — what each lane in the part’s figures stands for.

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