- Owner — The client or server responsible for creating and closing its network resources.
- Transport (
NetworkTransport) — Sends and receives datagrams through the owner's local and UDP endpoints. - Endpoint (
DatagramEndpoint) — One place where datagrams are sent and received: a UDP socket or a local queue. - Local link (
LoopbackLink) — A private pair of endpoints connecting a client and server inside one process. - Network (
ClientNetwork/ServerNetwork) — The application's interface for configuring network I/O, polling packets, and creating connections. - Packet network (
PacketNetwork) — Shared client/server implementation of binding, polling, and packet-envelope decoding. - Connection (
ConnectionChannel) — Communication with one peer, including its address and queued outgoing messages. - Reliable channel (
ReliableChannel) — Tracks packet sequences, acknowledgements, and reliable retransmissions for one connection. - Address (
NetworkAddress) — Identifies a UDP IP/port or an endpoint on a specific local link. - Datagram — One independently delivered unit of bytes, together with its source address when received.
- Packet — A Quake II protocol unit carried by a datagram; either connectionless or sequenced.
- Envelope (
PacketEnvelope) — The decoded outer packet structure, identifying its kind and header fields. - Message (
ClientMessage/ServerMessage) — One command or update inside a sequenced packet, such as movement or entity state. - Codec — Converts protocol values to and from bytes; it does not own sockets or connections.
- Handshake (
ClientHandshake) — The exchange used to establish a connection, including challenges and retries. - Session — The lifetime of a connection to a server; it can span multiple map changes.
- Client and server each own a separate transport.
- Each transport manages an optional UDP socket (optional, for multiplayer) and one endpoint of the local link (singleplayer and local hosting).
- Stopping or closing one side preserves messages already queued for the other side.
- Map changes preserve reconnect traffic; clearing both local queues requires an explicit session-level decision.
NetworkPacket adapts a received datagram for the engine. PacketCodec identifies
two packet types, represented by PacketEnvelope.Sequenced and
PacketEnvelope.Connectionless.
These carry communication over an established game connection (during playing the map):
- Header: sequence and acknowledgement fields, plus a qport on client-to-server packets.
- Body: zero or more typed
ClientMessageorServerMessagevalues, such as movement, player state, or entity updates. - Handling: peer routing and
ReliableChannelacceptance, followed by message-body decoding and dispatch.
MessageBodyCodec validates the whole body before dispatch, returning all messages
or a typed rejection. Malformed bodies cause the server to drop the sending client,
or the receiving client to return to its console. A failed movement checksum makes
the server ignore the rest of the packet. Demo playback uses the same validation
for headerless server bodies; other file readers retain their existing sizebuf_t
behavior.
These are independent datagrams that can be sent by connected or unconnected peers, without requiring a running map:
- Marker: a leading sequence value of -1 identifies a connectionless packet.
- Payload: text commands and replies, such as
getchallenge,connect,ping, andprint, described byConnectionlessCommand. - Handling: connectionless command or handshake handlers, bypassing
ReliableChannelandMessageBodyCodec. Handshake retries are managed byClientHandshake.
For server info and print replies, a newline separates the command line from the
remaining reply text; these are not two separately encoded strings.
Outgoing packets are built as bytes. Sending depends on connection state, rate limiting, and keepalive or handshake timing, rather than occurring on every frame on both sides.
Remote communication uses UDP; in-process communication uses LoopbackLink.
Both use the Quake II packet protocol and its reliability machinery.
When reliable data is ready to send or retransmit, it goes first, followed by the
unreliable batch if there is room. A packet can also contain only its header.
The entry point is ConnectionChannel.transmit; protocol state is managed by
ReliableChannel. Sequence and acknowledgement fields track reliable delivery;
a dropped reliable payload is resent when acknowledgement state indicates a retry is needed.
The bulk of the network traffic between server & client constitute entity updates and move messages. To reduce traffic, the Quake II protocol uses delta compression: sending selected fields relative to a reference state, rather than always sending the complete state. The following messages use delta compression:
PlayerInfoMessage(from server)PacketEntitiesMessage(from server)MoveMessage(from client)
The reference depends on the message:
- Player state uses a client-acknowledged frame when available, otherwise a zero state.
- Entity updates use the acknowledged frame for existing entities and baselines for newly visible entities.
- Movement sends three commands as a delta chain: the oldest against a zero command, then each later command against the preceding one.
Field masks identify what is transmitted. Some fields are sent even when unchanged; for example, movement commands always include their duration and light level. Player-state updates send the weapon index only when it differs from the reference state, including changes to zero.
see package jake2.qcommon.network.messages.server
see package jake2.qcommon.network.messages.client
see jake2.server.ClientStates
The following diagram illustrates client/server communication when client connects to server. Starting from typing connect 'someaddress' and until client becomes connected and receives the updates from the server.
[s] marks a message carried in a sequenced packet; [c] marks a connectionless packet.
Sequence numbers belong to packets, and several [s] messages may share one packet.
sequenceDiagram
participant client
participant server
Note over client: User types connect hostname
opt Remote UDP connection
client->>server: [c] getchallenge
server->>client: [c] challenge
end
client->>server: [c] connect
Note over server: client.state = connected
server->>client: [c] client_connect
Note over client: state = connected
client->>server: [s] StringCmdMessage new
server->>client: [s] ServerDataMessage
loop until all config strings are transmitted
server->>client: [s] StuffTextMessage cmd configstrings
client->>server: [s] StringCmdMessage configstrings
server->>client: [s] ConfigStringMessage
end
loop until all baselines are transmitted
server->>client: [s] StuffTextMessage cmd baselines
client->>server: [s] StringCmdMessage baselines
server->>client: [s] SpawnBaselineMessage
end
Note over client: precache resources
loop for each missing file
client->>server: [s] StringCmdMessage download path [offset]
server->>client: [s] DownloadMessage first chunk
loop remaining chunks of this file
client->>server: [s] StringCmdMessage nextdl
server->>client: [s] DownloadMessage next chunk
end
end
client->>server: [s] StringCmdMessage begin
Note over server: client.state = spawned
loop During gameplay, when updates are sent
server->>client: [s] FrameHeaderMessage
server->>client: [s] PlayerInfoMessage
server->>client: [s] PacketEntitiesMessage
client->>server: [s] MoveMessage
end