{"id":18265731,"url":"https://github.com/jacksonrakena/promul","last_synced_at":"2025-04-04T21:31:54.642Z","repository":{"id":206760386,"uuid":"717641463","full_name":"jacksonrakena/promul","owner":"jacksonrakena","description":"An open-source networking \u0026 relay implementation for Unity Netcode for GameObjects","archived":false,"fork":false,"pushed_at":"2023-12-12T22:31:54.000Z","size":475,"stargazers_count":46,"open_issues_count":1,"forks_count":4,"subscribers_count":5,"default_branch":"main","last_synced_at":"2025-03-20T19:34:42.484Z","etag":null,"topics":["netcode-for-gameobjects","relay","relay-server","unity","unity-multiplayer","unity-netcode"],"latest_commit_sha":null,"homepage":"","language":"C#","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/jacksonrakena.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null}},"created_at":"2023-11-12T04:40:23.000Z","updated_at":"2025-03-13T23:29:26.000Z","dependencies_parsed_at":"2023-11-18T01:59:46.415Z","dependency_job_id":"d51064b8-32a3-43db-88ee-eb89a613d5f0","html_url":"https://github.com/jacksonrakena/promul","commit_stats":null,"previous_names":["jacksonrakena/promul"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jacksonrakena%2Fpromul","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jacksonrakena%2Fpromul/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jacksonrakena%2Fpromul/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jacksonrakena%2Fpromul/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/jacksonrakena","download_url":"https://codeload.github.com/jacksonrakena/promul/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247252284,"owners_count":20908658,"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":["netcode-for-gameobjects","relay","relay-server","unity","unity-multiplayer","unity-netcode"],"created_at":"2024-11-05T11:19:35.349Z","updated_at":"2025-04-04T21:31:53.897Z","avatar_url":"https://github.com/jacksonrakena.png","language":"C#","funding_links":[],"categories":["Open Source Repositories"],"sub_categories":["Networking"],"readme":"# Promul\nPromul is a simple, lightweight, and easy-to-use relay server and session management implementation for [Unity Netcode for GameObjects](https://docs-multiplayer.unity3d.com/netcode/current/about/).  \n\nPromul is designed to quickly allow independent and small developers to have fully functional peer-to-peer (P2P) gameplay over top of an open-source relay server, allowing players to play together without complicated port-forwarding configurations, and with minimal infrastructure investment and expenditure for the development team.\n\nIt works by providing a relay server and wire protocol for clients, allowing players to both host and join games using Unity's Netcode for GameObjects library. It ships with its own UDP-based networking solution, which can be used independently of the relay protocol.\n  \nPromul uses a heavily-modified version of the [LibNetLib](https://github.com/RevenantX/LiteNetLib) library for its internal networking, converting the library from a thread-based non-async model to a Task-based Asynchronous Programming (TAP)-based implementation.\nTechnical details of the networking are explained in engineering section below.\n  \nPromul is intended to be a free and open-source alternative to [Unity Relay](https://unity.com/products/relay). It supports join secret-based session management, with a REST API for creating and deleting sessions, and an admin UI for managing active sessions.\n\n## Setup\n#### Relay server and API\nClone this repository and build and run the program under [/Server](/Server). The relay server will bind on UDP port 4098 while the API server will bind on TCP port 3000.\n\nTo create a new session, call `PUT /session/create`. The API will respond with the join code.\n\n#### Relay client (Transport)\nInstall the transport by adding it in the Unity Package Manager by git URL:  \n`https://github.com/jacksonrakena/Promul.git`\n  \nNext, add `PromulTransport` to your NetworkManager GameObject. Set the `Address` and `Port` to the address and port of your relay server.  \n\nExample:  \n![Alt text](example.png)  \n  \n\nYou should now be ready to use Promul as a relay server for your Unity project. You can call `NetworkManager`'s `StartHost`/`StartClient`/`StartServer` methods as normal.\n\n## Engineering\n```mermaid\nflowchart TD\n    subgraph Unity\n    Code[Your Unity code] --\u003e|Unity Netcode| Runtime[Promul.Runtime.Unity]\n    end\n\n    subgraph Unreal Engine\n    UECode[Your UE code] --\u003e RuntimeUE[\"Promul.Runtime.Unreal\\n(planned)\"]\n    end\n\n    subgraph \"Protocol layer\"\n    Protocol[Promul.Relay.Protocol]\n    end\n    Protocol--\u003eCore\n    Runtime--\u003eProtocol\n        RuntimeUE--\u003eProtocol\n    \n    subgraph Relay server\n    API[Promul.Server.API\\nFront-facing]--\u003eServer[Promul.Server]\n    Server--\u003eProtocol\n    end\n\n    subgraph Transit layer\n    Core[Promul\\nKey networking capabilities]\n    Core--\u003eNative[Native sockets]\n    Core--\u003eManaged[Managed sockets]\n    end\n```\n\n### Transit layer\nPromul's included networking solution is a very heavily modified version of the amazing [LibNetLib](https://github.com/RevenantX/LiteNetLib) by Ruslan Pyrch.\n\nPromul is *probably* compatible with LibNetLib clients and servers. I don't know, and I don't check.  \nCompatibility with LibNetLib is not a goal of Promul.\n\n#### Differences from LibNetLib\nAmong other differences:\n- The library requires .NET Standard 2.1.\n    - This limits the Unity versions that can use the library, but also\n      allows the library to use newer constructs such as `ArraySegment\u003cT\u003e`.\n- The `NetDataReader` and `NetDataWriter` classes have been removed in favour of `BinaryReader` and `BinaryWriter` from `System.IO`.\n    - This means support for `INetSerializable` has been removed. Clients are expected to create extension overloads for `BinaryWriter.Write` and `BinaryReader.Read{Type}`.\n- The logic and receive threads have been removed, in favour of a long-running `Task` spawned by the `NetManager`.\n- Most of the library's blocking methods have been replaced with Task-based Asynchronous Programming (TAP) methods, using `Task`. This requires\n  a significant rewrite of most parts of the library.\n- NAT punch-through and manual mode have both been removed.\n    - The transport will now put transport events onto a queue,\n      and `NetworkTransport#PollEvents` will dequeue events and pass them to Unity Netcode.\n- `NetManager#Start` has been replaced by `PromulManager#ListenAsync`, which will begin infinitely looping, waiting for incoming messages.\n    - This method will block, so in the Unity transport, it is spawned on an un-awaited `Task`.\n    - Servers are expected to use a paradigm such as `BackgroundService` to run the long-running `Task`.\n- Documentation has been improved.\n- `NetPacket` no longer has jurisdiction over its data. It is a wrapper around an `ArraySegment\u003cbyte\u003e`.\n- Most (if not all) usages of `byte[] data, int offset, int count` have been replaced with `ArraySegment\u003cbyte\u003e`.\n- `INetBasedListener` and related classes have been removed. All events\n  are invoked on the `PromulManager` class as\n  regular CLR `event` types.\n- In many classes, extraneous overloads have been removed in favour of default parameters.\n### Protocol layer\nPromul's Unity relay uses its own wire protocol over the transit layer. The protocol is shown in the following diagram:\n```mermaid\nsequenceDiagram\n    autonumber\n    Host (ID 0)-\u003e\u003e+Relay API: PUT /session/create\n    Relay API-\u003e\u003eRelay: Creates session\n    Relay API-\u003e\u003e-Host (ID 0): Sends join code \"KDS92F\" + connection info\n    \n    Host (ID 0)-\u003e\u003eRelay: UDP Connect (KDS92F)\n    Client (ID 1)-\u003e\u003e+Relay API: PUT /session/join KDS92F\n    note right of Relay API: Join code is transferred out-of-band\n    Relay API-\u003e\u003e-Client (ID 1): Sends connection address and port\n\n    Client (ID 1)-\u003e\u003e+Relay: UDP Connect (KDS92F)\n    Relay-\u003e\u003eHost (ID 0): 0x11 CLIENT_CONNECTED\n    Relay-\u003e\u003e-Client (ID 1): 0x10 CONNECTED\n\n    rect rgba(0, 0, 255, .1)\n            note right of Relay: Data is now relayed by 0x00 DATA messages\n    Client (ID 1)-\u003e\u003e+Relay: 0x00 DATA, target=0\n    Relay--\u003e\u003e-Host (ID 0): 0x00 DATA, author=1\n    Host (ID 0)-\u003e\u003e+Relay: 0x00 DATA, target=1,\n    Relay-\u003e\u003e-Client (ID 1): 0x00 DATA, author=0\n    note right of Host (ID 0): author field becomes target when sending to relay\n    end\n\n    Client (ID 1)--xRelay: Connection lost\n    Relay-\u003e\u003e+Host (ID 0): 0x12 CLIENT_DISCONNECTED\n    note right of Relay: Relay notifies host of disconnection\n    \n    Host (ID 0)--xRelay: Connection lost\n    Relay-\u003e\u003eRelay API: Destroys session\n```\n\n## Roadmap\n### Engineering \u0026mdash; Transit/Protocol\n- [x] Task-based asynchronous programming rewrite\n- [x] Authentication and binding tests\n- [x] MTU negotation tests\n- [ ] Replace logging with a better solution\n- [ ] Restore merged sending support\n- [ ] Restore NAT punch-through(?)\n- [ ] Improve memory and throughput performance\n- [ ] More real-world replications in tests\n- [ ] More uses of `ValueTask\u003cT\u003e` over regular tasks\n### Relay Server\n- [x] Basic create/join session by join code\n  - [x] Update session manager\n- [x] Basic web interface\n  - [ ] Further development of web interface\n- [ ] Multicast(?)\n## Copyright\n\u0026copy; 2023 Firework Eyes Studio (NZBN 9429048922678) under the MIT License.\n\nThis project uses a heavily modified version of LibNetLib.  \nLiteNetLib \u0026copy; 2020 Ruslan Pyrch, under the following license:\n```\nMIT License\n\nCopyright (c) 2020 Ruslan Pyrch\n\nPermission is hereby granted, free of charge, to any person obtaining a copy\nof this software and associated documentation files (the \"Software\"), to deal\nin the Software without restriction, including without limitation the rights\nto use, copy, modify, merge, publish, distribute, sublicense, and/or sell\ncopies of the Software, and to permit persons to whom the Software is\nfurnished to do so, subject to the following conditions:\n\nThe above copyright notice and this permission notice shall be included in all\ncopies or substantial portions of the Software.\n\nTHE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\nIMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\nFITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\nAUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\nLIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\nOUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE\nSOFTWARE.\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjacksonrakena%2Fpromul","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjacksonrakena%2Fpromul","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjacksonrakena%2Fpromul/lists"}