yojimbo: a C++ client/server networking library for competitive multiplayer games

What yojimbo solves for a C++ game that has to talk over UDP

Writing the transport layer of a multiplayer game is a slog. You need a handshake that proves the client is who it says it is, packets that cannot be read or forged in transit, a way to send time-sensitive state that should be dropped rather than delayed, and a separate path for the messages that absolutely must arrive in order. yojimbo packages all of that into one C++ library so the game code deals with messages instead of sockets.

The README is explicit about the target: client/server games with 100 players or less, designed around the networking requirements of competitive multiplayer games like first person shooters. That is a narrow audience on purpose. If your game is a turn-based board game or a co-op session for four friends, the machinery here is more than you need. If you are building something where a 40 ms delay changes the outcome of a fight, the feature list starts to line up with the problem.

The feature list is the pitch: cryptographically secure authentication via connect tokens, connection management and timeouts, encrypted and signed packets over UDP, packet fragmentation and reassembly, a bitpacker and serialization system, unreliable-unordered messages for time sensitive data, reliable-ordered messages with aggressive resend until ack, data blocks larger than the maximum packet size attached to reliable-ordered messages, and per-connection estimates of latency, jitter, packet loss and bandwidth sent, received and acked. Those last estimates matter more than they look. A competitive game usually wants to adapt its send rate to the connection it actually has, not the one it hoped for.

The architecture: netcode, reliable, serialize and a single-threaded loop

yojimbo is not a from-scratch implementation of everything it advertises. It is built on three other libraries by the same author: netcode for the connect token authentication standard, reliable for the reliable-ordered message layer, and serialize for the bitpacker and serialization system. The repository layout reflects that directly, with netcode/, reliable/ and serialize/ as top-level directories alongside include/ and source/. The README states that shipping yojimbo means shipping all four, and asks for credit for all four in product credits.

Two bundled dependencies sit underneath: libsodium for cryptography and tlsf, a two-level segregated fit allocator. Their own license notices apply. That means a yojimbo build is not a single-file drop-in; it pulls in a crypto library and an allocator, and the release notes show the vendored layers move independently. v1.13.5 is described as vendoring reliable 1.4.5, and v1.13.3 as vendoring reliable 1.4.4 and netcode 1.4.7. When you pin a yojimbo version, you are pinning those too.

The constraint that shapes application code is threading. The README says yojimbo is single-threaded and that all client and server functions must be called from the same thread. Running networking on its own thread is fine, but every yojimbo call has to happen on that one thread. In practice that pushes you toward a message queue between your game thread and your network thread, or toward calling yojimbo from the main loop. Either is workable; neither is invisible.

The second constraint is configuration symmetry. The README warns that the client and server must use the same configuration, and that the ClientServerConfig, channels and message factory must be identical on both sides or the client and server will not work together. Keeping the two sides in sync is described as your responsibility. There is no schema negotiation here. If you add a channel or a message type on the server and forget the client, you get a connection that fails for reasons the library will not diagnose for you.

Getting the source and building a first client and server

The README gives exactly one command for obtaining the code, a git clone, and points at the releases page as the alternative. It does not document build steps; those live in INSTALL.md and BUILDING.md at the repository root, which is where you should look before assuming a toolchain.

git clone https://github.com/mas-bandwidth/yojimbo.git

After cloning, the repository root contains CMakeLists.txt and a cmake/ directory, so CMake is the build entry point the layout implies. The README itself is silent on the exact configure and build invocation, so read BUILDING.md rather than guessing flags.

The runnable starting points are in the repository root: client.cpp and server.cpp, with shared.h holding what both sides need and loopback.cpp for a loopback test. The README does not walk through compiling or running them, so treat the presence of shared.h as the important signal: the configuration both sides must agree on is meant to live in a file like that, included by both binaries, rather than duplicated.

The usage pattern the feature list describes is a connect token obtained from a backend, passed to the client, which then connects to the server. The README does not print the API calls for that sequence; USAGE.md and STANDARD.md are the files to read for the handshake and the token format. If you are evaluating yojimbo rather than adopting it today, the honest first step is reading STANDARD.md to see whether the token issuance model fits your backend, because that is the part yojimbo will not do for you.

Where yojimbo is the wrong tool

The 100-player ceiling is a design assumption, not a bug, and it is stated plainly. If you are building a persistent world with hundreds of players in one session, or a battle royale match with a hundred concurrent combatants and a spectator layer on top, this library is not aimed at you. The per-connection estimates and the reliable-ordered machinery are tuned for the competitive shooter case, and nothing in the README suggests a mesh or relay topology for larger counts.

The bigger practical limitation is the absence of a homepage and the thinness of the README as an integration guide. There is no documented API reference in the README, no install instructions beyond git clone, and no worked example of the connect token handshake. The repository has USAGE.md, STANDARD.md, STATE-MACHINE.md, INSTALL.md and BUILDING.md, plus a doxygen.config, so the information exists, but it is spread across files the README does not summarize. Budget reading time accordingly.

Threading is the third boundary. If your engine already runs networking on a worker pool and expects the network library to be safe to call from multiple threads, yojimbo's single-threaded contract means you either serialize those calls yourself or restructure. The README presents this as a design choice rather than a limitation, and it is a defensible one, but it is a constraint you inherit.

Finally, the client/server-only posture rules out peer-to-peer designs. If your game wants players to host directly and connect to each other without an authoritative server, yojimbo's connection management and authentication model assume a server the client connects to.

How yojimbo differs from writing on raw sockets or using a general-purpose transport

The obvious alternative is rolling your own on top of UDP. That gives you total control and no dependency on libsodium, tlsf, netcode, reliable or serialize. It also means implementing connect token authentication, packet encryption and signing, fragmentation and reassembly, a bitpacker, and two delivery modes with their own ack logic. The README's feature list is essentially the checklist of what you would be rebuilding, and the release history shows the reliable and netcode layers are still being revised, which tells you those pieces are not trivial to get right once.

A second alternative is a general-purpose game networking transport that targets a different topology. yojimbo's distinguishing choice is that it is client/server first and competitive-shooter first: authentication via connect tokens is built in, channels and a message factory are part of the required shared configuration, and unreliable-unordered is a first-class delivery mode rather than an option bolted onto a reliable stream. If your project is peer-to-peer or your message volume is low enough that TCP would do, the connect token model and the channel configuration are overhead you would be carrying for nothing.

Within the same author's ecosystem, the layered structure is itself the comparison. netcode, reliable and serialize are usable independently. If you need only the authentication standard, or only the bitpacker, you can take that piece and leave the rest. yojimbo is the opinionated assembly of all three plus libsodium and tlsf into a client/server stack.

Maintenance, licensing and what an upgrade actually costs

The repository is not archived, and the last push was on 2026-09-14, which is recent. The release cadence around that date is worth noting: v1.13.3 on 2026-09-13, v1.13.4 the same day, and v1.13.5 on 2026-09-14. Two of those releases are explicitly vendoring updates to reliable and netcode. That pattern means an upgrade is not always a yojimbo change; sometimes it is a bump of a dependency whose behavior you also depend on, and the release titles tell you which.

The upgrade cost follows from the shared-configuration rule. Because ClientServerConfig, channels and the message factory must match on both sides, any change to the message set is a lockstep deploy: old clients talking to a new server, or the reverse, is the failure mode the README warns about. If you ship to players you cannot force to update, plan for version negotiation at your layer rather than expecting the library to provide it.

Licensing is BSD 3-Clause for yojimbo itself, which is permissive and imposes the usual notice retention. The README notes that yojimbo bundles libsodium and tlsf and that their own license notices apply as usual, so a compliance pass needs to cover those too. The crediting request for yojimbo, netcode, reliable and serialize is explicitly not a license requirement; the README calls it an official request. Whether you honor it is your call, not a legal obligation. This is a description of what the README states, not legal advice; have counsel review the bundled notices if you are shipping commercially.

Editorial conclusion

Adopt yojimbo if you have a C++ game engine, a client/server topology rather than peer-to-peer, and a player count the README caps at 100 or less; the library covers authentication, encryption, fragmentation and both unreliable-unordered and reliable-ordered messaging, so you are not writing that layer yourself. Do not adopt it if you need peer-to-peer, a managed language binding, or networking spread across several threads, since the README states all client and server calls must happen on one thread. Before committing, verify that your client and server can share one configuration source for ClientServerConfig, channels and the message factory, and that your build environment is covered by INSTALL.md and BUILDING.md rather than the README, which gives only the git clone command.

Frequently asked questions

Official sources

1. Issues
2. License: BSD-3-Clause
3. mas-bandwidth/yojimbo on GitHub
4. README
5. Releases