{"id":15028735,"url":"https://github.com/mirrornetworking/telepathy","last_synced_at":"2025-04-13T09:00:02.694Z","repository":{"id":45301204,"uuid":"144561454","full_name":"MirrorNetworking/Telepathy","owner":"MirrorNetworking","description":"Simple, message based, MMO Scale TCP networking in C#. And no magic.","archived":false,"fork":false,"pushed_at":"2024-09-27T16:49:58.000Z","size":584,"stargazers_count":1170,"open_issues_count":20,"forks_count":136,"subscribers_count":66,"default_branch":"master","last_synced_at":"2024-10-29T19:59:38.668Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"C#","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/MirrorNetworking.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2018-08-13T10:00:18.000Z","updated_at":"2024-10-26T16:50:27.000Z","dependencies_parsed_at":"2023-11-14T23:25:15.897Z","dependency_job_id":"c8189104-0cb3-4bf7-bea6-e9d27de897de","html_url":"https://github.com/MirrorNetworking/Telepathy","commit_stats":null,"previous_names":["vis2k/telepathy","mirrornetworking/telepathy"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MirrorNetworking%2FTelepathy","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MirrorNetworking%2FTelepathy/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MirrorNetworking%2FTelepathy/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MirrorNetworking%2FTelepathy/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/MirrorNetworking","download_url":"https://codeload.github.com/MirrorNetworking/Telepathy/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248688556,"owners_count":21145765,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-09-24T20:08:58.461Z","updated_at":"2025-04-13T09:00:02.663Z","avatar_url":"https://github.com/MirrorNetworking.png","language":"C#","readme":"![Telepathy Logo](https://i.imgur.com/2Dw1zx6.png)\n\n[![Discord](https://img.shields.io/discord/343440455738064897.svg)](https://discordapp.com/invite/N9QVxbM)\n\n[![CI](https://github.com/vis2k/Telepathy/actions/workflows/main.yml/badge.svg)](https://github.com/vis2k/Telepathy/actions/workflows/main.yml)\n\nSimple, message based, allocation free MMO Scale TCP networking in C#. And no magic.\n\nTelepathy was designed with the [KISS Principle](https://en.wikipedia.org/wiki/KISS_principle) in mind.\u003cbr/\u003e\nTelepathy is fast and extremely reliable, designed for [MMO](https://assetstore.unity.com/packages/templates/systems/ummorpg-remastered-159401) scale Networking.\u003cbr/\u003e\nTelepathy uses framing, so anything sent will be received the same way.\u003cbr/\u003e\nTelepathy is raw C# and made for Unity \u0026 [Mirror](https://github.com/vis2k/Mirror) | [DOTSNET](https://u3d.as/YUi).\u003cbr/\u003e\n\n# What makes Telepathy special?\nTelepathy was originally designed for [uMMORPG](https://assetstore.unity.com/packages/templates/systems/ummorpg-remastered-159401) after 3 years in UDP hell.\n\nWe needed a library that is:\n* **Stable \u0026 Bug free:** Telepathy uses only 700 lines of code. There is no magic.\n* **High performance:** Telepathy can handle thousands of connections and packages.\n* **Concurrent:** Telepathy uses two threads per connection. It can make heavy use of multi core processors.\n* **Allocation Free:** Telepathy has no allocations in hot path. Avoids GC spikes in Games.\n* **Simple:** Telepathy wraps all the insanity behind Connect/Send/Disconnect/Tick.\n* **Message based:** sending messages A,B,C are received as A,B,C. Never as AB,C or BC,A.\n\nMMORPGs are insanely difficult to make and we created Telepathy so that we would never have to worry about low level Networking again.\u003cbr\u003e\n\nSee also: [SyncThing article on KCP vs. TCP](https://forum.syncthing.net/t/connections-over-udp/9382).\n\n# What about...\n* Async Sockets: perform great in regular C# projects, but poorly when used in Unity.\n* UDP vs. TCP: Minecraft and World of Warcraft are two of the biggest multiplayer games of all time and they both use TCP networking. There is a reason for that.\n\n# Using the Telepathy Server\n```C#\n// create server \u0026 hook up events\n// note that the message ArraySegment\u003cbyte\u003e is only valid until returning (allocation free)\nTelepathy.Server server = new Telepathy.Server(1024);\nserver.OnConnected = (connectionId) =\u003e Console.WriteLine(connectionId + \" Connected\");\nserver.OnData = (connectionId, message) =\u003e Console.WriteLine(connectionId + \" Data: \" + BitConverter.ToString(message.Array, message.Offset, message.Count));\nserver.OnDisconnected = (connectionId) =\u003e Console.WriteLine(connectionId + \" Disconnected\");\n\n// start\nserver.Start(1337);\n\n// tick to process incoming messages (do this in your update loop)\n// =\u003e limit parameter to avoid deadlocks!\nserver.Tick(100);\n\n// send a message to client with connectionId = 0 (first one)\nbyte[] message = new byte[]{0x42, 0x13, 0x37};\nserver.Send(0, new ArraySegment\u003cbyte\u003e(message));\n\n// stop the server when you don't need it anymore\nserver.Stop();\n```\n\n# Using the Telepathy Client\n```C#\n// create client \u0026 hook up events\n// note that the message ArraySegment\u003cbyte\u003e is only valid until returning (allocation free)\nTelepathy.Client client = new Telepathy.Client(1024);\nclient.OnConnected = () =\u003e Console.WriteLine(\"Client Connected\");\nclient.OnData = (message) =\u003e Console.WriteLine(\"Client Data: \" + BitConverter.ToString(message.Array, message.Offset, message.Count));\nclient.OnDisconnected = () =\u003e Console.WriteLine(\"Client Disconnected\");\n\n// connect\nclient.Connect(\"localhost\", 1337);\n\n// tick to process incoming messages (do this in your update loop)\n// =\u003e limit parameter to avoid deadlocks!\nclient.Tick(100);\n\n// send a message to server\nbyte[] message = new byte[]{0xFF};\nclient.Send(new ArraySegment\u003cbyte\u003e(message));\n\n// disconnect from the server when we are done\nclient.Disconnect();\n```\n\n# Unity Integration\nHere is a very simple MonoBehaviour script for Unity. It's really just the above code with logging configured for Unity's Debug.Log:\n```C#\nusing System;\nusing UnityEngine;\n\npublic class SimpleExample : MonoBehaviour\n{\n    Telepathy.Client client = new Telepathy.Client(1024);\n    Telepathy.Server server = new Telepathy.Server(1024);\n\n    void Awake()\n    {\n        // update even if window isn't focused, otherwise we don't receive.\n        Application.runInBackground = true;\n\n        // use Debug.Log functions for Telepathy so we can see it in the console\n        Telepathy.Logger.Log = Debug.Log;\n        Telepathy.Logger.LogWarning = Debug.LogWarning;\n        Telepathy.Logger.LogError = Debug.LogError;\n\n        // hook up events\n        client.OnConnected = () =\u003e Debug.Log(\"Client Connected\");\n        client.OnData = (message) =\u003e Debug.Log(\"Client Data: \" + BitConverter.ToString(message.Array, message.Offset, message.Count));\n        client.OnDisconnected = () =\u003e Debug.Log(\"Client Disconnected\");\n\n        server.OnConnected = (connectionId) =\u003e Debug.Log(connectionId + \" Connected\");\n        server.OnData = (connectionId, message) =\u003e Debug.Log(connectionId + \" Data: \" + BitConverter.ToString(message.Array, message.Offset, message.Count));\n        server.OnDisconnected = (connectionId) =\u003e Debug.Log(connectionId + \" Disconnected\");\n    }\n\n    void Update()\n    {\n        // client\n        if (client.Connected)\n        {\n            // send message on key press\n            if (Input.GetKeyDown(KeyCode.Space))\n                client.Send(new ArraySegment\u003cbyte\u003e(new byte[]{0x1}));\n        }\n\n        // tick to process messages\n        // (even if not connected so we still process disconnect messages)\n        client.Tick(100);\n\n        // server\n        if (server.Active)\n        {\n            if (Input.GetKeyDown(KeyCode.Space))\n                server.Send(0, new ArraySegment\u003cbyte\u003e(new byte[]{0x2}));\n\n        }\n\n        // tick to process messages\n        // (even if not active so we still process disconnect messages)\n        server.Tick(100);\n    }\n\n    void OnGUI()\n    {\n        // client\n        GUI.enabled = !client.Connected;\n        if (GUI.Button(new Rect(0, 0, 120, 20), \"Connect Client\"))\n            client.Connect(\"localhost\", 1337);\n\n        GUI.enabled = client.Connected;\n        if (GUI.Button(new Rect(130, 0, 120, 20), \"Disconnect Client\"))\n            client.Disconnect();\n\n        // server\n        GUI.enabled = !server.Active;\n        if (GUI.Button(new Rect(0, 25, 120, 20), \"Start Server\"))\n            server.Start(1337);\n\n        GUI.enabled = server.Active;\n        if (GUI.Button(new Rect(130, 25, 120, 20), \"Stop Server\"))\n            server.Stop();\n\n        GUI.enabled = true;\n    }\n\n    void OnApplicationQuit()\n    {\n        // the client/server threads won't receive the OnQuit info if we are\n        // running them in the Editor. they would only quit when we press Play\n        // again later. this is fine, but let's shut them down here for consistency\n        client.Disconnect();\n        server.Stop();\n    }\n}\n```\nMake sure to enable 'run in Background' for your project settings, which is a must for all multiplayer games.\nThen build it, start the server in the build and the client in the Editor and press Space to send a test message.\n\n# Benchmarks\n**Real World**\u003cbr/\u003e\nTelepathy is constantly tested in production with [uMMORPG](https://www.assetstore.unity3d.com/#!/content/51212).\nWe [recently tested](https://youtu.be/mDCNff1S9ZU) 500 players all broadcasting to each other in the worst case scenario, without issues.\n\nWe had to stop the test because we didn't have more players to spawn clients.\u003cbr/\u003e\n\n**Connections Test**\u003cbr/\u003e\nWe also test only the raw Telepathy library by spawning 1 server and 1000 clients, each client sending 100 bytes 14 times per second and the server echoing the same message back to each client. This test should be a decent example for an MMORPG scenario and allows us to test if the raw Telepathy library can handle it.\n\nTest Computer: 2015 Macbook Pro with a 2,2 GHz Intel Core i7 processor.\u003cbr/\u003e\nTest Results:\u003cbr/\u003e\n\n| Clients | CPU Usage | Ram Usage | Bandwidth Client+Server  | Result |\n| ------- | ----------| --------- | ------------------------ | ------ |\n|   128   |        7% |     26 MB |         1-2 MB/s         | Passed |\n|   500   |       28% |     51 MB |         3-4 MB/s         | Passed |\n|  1000   |       42% |     75 MB |         3-5 MB/s         | Passed |\n\nYou can run this test yourself by running the provided [LoadTest](LoadTest)\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmirrornetworking%2Ftelepathy","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmirrornetworking%2Ftelepathy","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmirrornetworking%2Ftelepathy/lists"}