<!-- https://minecraftdocs.dev/systems/networking/ — this page as markdown. The book's index: https://minecraftdocs.dev/llms.txt; the whole book in one file: https://minecraftdocs.dev/llms-full.txt -->

# IX · Networking

> Verified against **Minecraft 26.3** · Part IX · One socket, four languages, and everything the two halves of the game say to each other across it.

Parts II to IV had a single machine to describe, and Parts V to VIII
compared two. This one is about what passes between them. A player meets the
seam as a set of symptoms — the *Connection lost*
screen with a reason string on it, the world that arrives in a pause and then a flood,
the chest whose contents appear only when it is opened, the chat line that
turns red and takes every line after it with it — and each of those can be a
decision rather than a fault. Singleplayer runs the same wire, an
integrated server on its own threads talking to the client through an
in-memory channel, so the split is not a multiplayer feature bolted on the
side: it is the shape of the program, and **the wire is not a pipe between two
halves of one machine but a border between two machines, and the server treats
what arrives from a client as a claim rather than a fact.**

## The shape of the part

Part IX is **the wire three times, and two things it carries**. The first
three lectures are all about the wire and are ordered by what they describe it
as: bytes on a socket, then the values those bytes are, then the four
languages the socket speaks in turn — a connection changes language as it goes
from handshaking to playing, and the last of the three is where that happens.
After those three, the part is mostly about what the wire carries rather
than the wire. The last two both sit inside the play language: everything the server
chooses to tell a client about the world, and the one protocol in the book in
which what a player sends is signed, so that the server and the players it
reaches can check it.

```mermaid
flowchart TD
    subgraph W["the wire, three times"]
      TC["1 · The connection — bytes to a handler call, and back"]
      PSC["2 · Packets and stream codecs — what crosses the wire"]
      PP["3 · Protocol phases — four languages over one socket"]
    end
    subgraph A["inside the play phase"]
      WCT["4 · What the client is told — the server's choosing"]
      CS["5 · Chat and signing — proving who sent a message"]
    end
    TC -- "two threads" --> PSC
    PSC -- "a codec table per phase" --> PP
    W ~~~ A
```

*The five lectures, numbered to the watch order: the top box is the wire
itself, the bottom box is the one language the last two live inside, and an
arrow is what the lecture before it settles. Nothing points into the bottom
box: its title says where the last two live, and neither needs the other or
the lecture above it.*

The spine is the first two: read them together, because the second is
the second half of the first. The last two could hardly differ more —
telling a client where the mobs are and sending it chunks is most of what a
connection ever carries,
while chat is a handful of packets a minute with a wholly disproportionate
amount of cryptography on it.

## Before you start

**[Part I's anatomy](../anatomy/anatomy#two-loops-and-a-wire-between-them)
first**, for the two-loops figure. The client's frame loop and the server's
tick loop are different clocks, and the client drains its inbound packets once
per **frame**, not once per tick. That one fact is behind most of what looks
like network jitter, and the first and fourth lectures lean on it.

**[Part III](../server/README) next, and not optionally**, because two of
this part's claims are really facts about somebody else's loop and Part IX
states the consequence rather than re-teaching the loop: [the server
tick](../server/server-tick#what-minecraftservertickchildren-runs-and-in-what-order)
owns what happens after every level has ticked, and [the level
tick](../server/server-level-tick#the-broadcast-which-is-why-entities-are-a-tick-behind)
owns the phase in which broadcasts go out — before the entity phase, which is
why one broadcast carries the block changes made so far this tick but the
*previous* tick's entity movement.

**Then [Part II](../foundations/README)** for two objects this part assumes
whole:
[codecs](../foundations/codecs-nbt-json#one-abstraction-and-the-ops-that-are-not-formats),
because a packet codec is the same idea specialised to a byte buffer, and
[components](../foundations/text-components#a-component-is-three-things),
because what a chat line displays is one. **And [Part
VI's authority](../entities/authority#five-predicates-and-the-final-one-the-other-four-hang-off)**,
which is the premise under lecture four: which side of the wire is allowed to
decide where a thing is, and therefore what the other side may be told late.

Nothing here waits on Part X. The client's half of the story is the deeper
version of the first item above, and where its arithmetic would matter these
pages state the consequence and link forward to it.

## Watch in this order

1. [The connection](the-connection) — you swing at a pig, and some
   milliseconds later a method runs on the server's game thread. The lecture
   with the there-and-back diagram, and then the whole life of the channel that
   carried it: two threads, two codec layers, one hop.
2. [Packets and stream codecs](packets-and-stream-codecs) — the second
   half of the same lecture. What the thing crossing the wire is, now that
   you have watched it travel, and why its number is written down nowhere.
3. [Protocol phases](protocol-phases) — a login, from clicking a server
   in the list to standing in the world: four languages over one socket, and
   the surprising thing about *when* in that sequence a player becomes an
   object on the server.
4. [What the client is told](what-the-client-is-told) — a creeper walks
   into view. Not a trace but a policy: three gates a change passes before it
   becomes a packet, and the things the server decides never to say.
5. [Chat and signing](chat-and-signing) — the part's closer, and the one
   system in the book whose messages are signed by the player who wrote them. What each check catches, and whether it kills the
   message, the chain, or the connection.

One and two are the pair to keep together; four and five can be watched in
either order, and neither strictly needs three.

## Where the part stops

Part IX's packages hold **490 files and 38,711 lines**, and
the count flatters it, because **this part owns the wire, not everything in
`network/`**: `Component` and the classes around it belong to [Part
II](../foundations/text-components#a-component-is-three-things), much of
`client/multiplayer` is the receiving end, which is Part X's, and the largest
block is the packet classes, catalogued in [packets](../../reference/packets)
rather than narrated one by one.

Three systems in those packages this part names and does not teach.
**Player reporting** is out of scope on [what this book
skips](../anatomy/what-this-book-skips#player-reporting). The **server list
screen** is one more screen for [GUI and
screens](../client/gui-and-screens); only [how a typed address becomes a
socket](the-connection#what-the-client-dials-is-not-what-the-player-typed)
belongs here. The **boss-bar feed** — `ClientboundBossEventPacket`, one packet with six
operations — belongs to its model, [scores, teams and stored
data](../commands/scoreboard-and-data#the-third-sink-is-a-boss-bar-and-it-is-this-pages-shape-again),
and to [the HUD](../client/hud). Past those,
**8% of the part's lines are named on no page in the book**.

Outward, what the client *does* with what it is told is Part X's, and how a
`ServerPlayer` comes to exist at all is [Part
III's](../server/players-and-sessions#preparing-a-place-to-stand). This
part stops at the packet that says so.

## Reference this part uses

[Packets](../../reference/packets) above all — the catalogue this part
narrates, and the page to keep open beside every lecture in it. Then [the
threads](../../reference/threads), which names the Netty event loop and the
two game threads and lists the nine handlers on the client's play listener that
never hop. Behind those: [registries](../../reference/registries) for
what crosses during configuration, [components](../../reference/components)
where a packet carries a stack, [level data and
rules](../../reference/level-data-and-rules) for the values a server sends
on request rather than on change, and [diagram
lanes](../../reference/lanes).


---

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