Telepathy: 700 lines of TCP networking for Unity games

Written after three years of UDP in a shipped MMORPG

Telepathy is described in one line as simple, message based, allocation free MMO scale TCP networking in C# and no magic, and the README explains where that came from. It was originally designed for a uMMORPG after three years in UDP hell, and the reasoning is stated as a list of what the team needed: stable and bug free, high performance, concurrent, allocation free, simple and message based. The stability claim has a specific basis, which is that Telepathy uses only 700 lines of code. That is a small enough amount of code to read, and it is the reason the project can make a promise about behaviour that a large networking stack with layers of abstraction cannot. The high performance claim is about scale, thousands of connections and packages, and the concurrency model is two threads per connection, which it says makes heavy use of multi core processors. The allocation free claim is the one that matters most in a game, because there are no allocations in the hot path, which avoids GC spikes. And the simplicity claim is that the library wraps the insanity behind four operations: Connect, Send, Disconnect and Tick.

Framing is the guarantee, and it is the whole point

The distinguishing feature is stated in a single line: Telepathy uses framing, so anything sent will be received the same way. And the message based property is spelled out with a small example that is worth memorising, because it captures the bug class that TCP itself introduces. Sending messages A, B and C means they are received as A, B and C, never as AB and C, or BC and A. TCP is a byte stream with no notion of a message, so an application that writes three separate payloads can have them coalesced into one read or split across two. Every game networking layer solves this with framing, and the difference between implementations is how much machinery they use to do it. Telepathy's position is that the framing is the library's job, so the game code above it deals in messages and never in byte counts. The README also links to a SyncThing forum thread on KCP versus TCP, which tells you the audience for the library includes people who have already thought hard about this trade-off, and the project's stated attitude is that Minecraft and World of Warcraft, two of the biggest multiplayer games of all time, both use TCP networking, and there is a reason for that.

The API is four methods and an event per connection

The server side is a class you construct with a buffer size, three events you assign, and the four lifecycle methods. The events are OnConnected, OnData and OnDisconnected, and the OnData callback receives an ArraySegment<byte> rather than a byte array, which is the allocation-free design in action:

Telepathy.Server server = new Telepathy.Server(1024);
server.OnConnected = (connectionId) => Console.WriteLine(connectionId + " Connected");
server.OnData = (connectionId, message) => Console.WriteLine(connectionId + " Data: " + BitConverter.ToString(message.Array, message.Offset, message.Count));
server.OnDisconnected = (connectionId) => Console.WriteLine(connectionId + " Disconnected");

// start
server.Start(1337);

The client is the same shape with the connection id removed, since a client has one connection:

Telepathy.Client client = new Telepathy.Client(1024);
client.OnConnected = () => Console.WriteLine("Client Connected");
client.OnData = (message) => Console.WriteLine("Client Data: " + BitConverter.ToString(message.Array, message.Offset, message.Count));
client.OnDisconnected = () => Console.WriteLine("Client Disconnected");

// connect
client.Connect("localhost", 1337);

The Tick method is the part that surprises people coming from an async socket library, because there is no callback loop to await. You call Tick in your update loop, and it processes the incoming messages, and the comment in the code is a warning rather than a suggestion, that the limit parameter is there to avoid deadlocks. The client is ticked even when it is not connected, so that disconnect messages are still processed, and the same applies to the server when it is not active. The one rule the code repeats is that the message ArraySegment is only valid until the callback returns, because the buffer is reused, and copying it is your decision.

Unity is the target, and async sockets are the thing it avoids

The project states that it is raw C# and made for Unity and Mirror or DOTSNET, and the Unity integration is a MonoBehaviour script in the README that wires the client and the server into the engine. Two details in that script are worth pointing out. The first is Application.runInBackground set to true, with the comment that without it the connection does not receive, which is the classic Unity trap where a background window stops ticking. The second is the logger redirection, where Telepathy.Logger.Log, LogWarning and LogError are assigned to Debug.Log, Debug.LogWarning and Debug.LogError so the library's output lands in the Unity console. The positioning against async sockets is stated just as bluntly: they perform great in regular C# projects, but poorly when used in Unity. The reason is not spelled out in the README, but the design makes it inferable. Telepathy is a pump you drive from your own loop, so it never depends on the thread pool, never creates a task per read, and never allocates in the hot path, while an async socket library in a game tends to introduce a continuation on every message and a GC pause you cannot control. The repository carries a LoadTest/ directory, a Telepathy.Tests/ project, an appveyor.yml and a CI workflow, which is what you would expect from a library whose claims are about scale.

Where Telepathy is the wrong tool

Four limits are clear from the design. The first is that the transport is TCP and only TCP. For a game where the traffic is mostly position updates and you would rather drop a packet than wait, a reliable ordered transport is the wrong primitive, and the README is candid that the project chose TCP after its UDP attempt rather than after a neutral comparison. The second is the Tick model. It is a good fit for a game loop and a poor fit for a service, a server-side tool or an ASP.NET application, because you have to own the pump, and the deadlock warning attached to the limit parameter is a sign of how the model behaves when the loop is blocked. The third is the scope of the library. It gives you framing, connections, sends and disconnects, and nothing else: no reliability layer, no encryption, no compression, no lag compensation, no snapshot interpolation. It is a transport, and if you need a transport plus a protocol design plus prediction and reconciliation, you are still writing that game networking yourself. The fourth is the maturity signal. The project publishes no GitHub releases, the last push was on 2026-08-22, and the repository is under the MirrorNetworking organisation while the CI badge points at a vis2k fork, which suggests the code lives in a personal account and is mirrored.

Editorial conclusion

Adopt Telepathy if you are writing a Unity or DOTSNET multiplayer game on TCP and want framing, message boundaries and a garbage-collection-free hot path without adopting a full networking stack. Do not adopt it if reliable ordered delivery is not your requirement, since its whole premise is TCP, or if you want a general purpose.NET socket library, since the Tick-driven pump is designed around a game loop. Before you build on it, measure the Tick cost at your target connection count, remember that the message buffer is only valid until your callback returns, and note that the last push was on 2026-08-22 with no GitHub releases published.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. MirrorNetworking/Telepathy on GitHub
4. README