This project has been renamed to **PinionCore.Remote** , please move to this [page](https://github.com/jiowchern/PinionCore.Remote). # Regulus Remote [![Maintainability](https://camo.githubusercontent.com/4ed06436c67b8157865440835a5b83b98fe491e34a0b9a0694d6b1a553dd9b8a/68747470733a2f2f6170692e636f6465636c696d6174652e636f6d2f76312f6261646765732f39396362356531646331326361666266653435312f6d61696e7461696e6162696c697479)](https://codeclimate.com/github/jiowchern/Regulus.Remote/maintainability) ![commit last date](https://camo.githubusercontent.com/c762ce109c1bed0810d18e44b933e33c077ab4ffe5a3eabcc5a985c5b3d20fa9/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f6c6173742d636f6d6d69742f6a696f77636865726e2f526567756c75732e52656d6f7465) ![NuGet Downloads](https://camo.githubusercontent.com/0af1683e8f70bceaea4ad0c6b3853b6faa2a4fe75a4cc12ed526af07109953a1/68747470733a2f2f696d672e736869656c64732e696f2f6e756765742f64742f526567756c75732e52656d6f7465) ## Introduction Regulus Remote is a powerful and flexible server-client communication framework developed in C#. Designed to work seamlessly with the Unity game engine and any other .NET Standard 2.0 compliant environments, it simplifies network communication by enabling servers and clients to interact through interfaces. This object-oriented approach reduces the maintenance cost of protocols and enhances code readability and maintainability. Key features of Regulus Remote include support for IL2CPP and AOT, making it compatible with various platforms, including Unity WebGL. It provides default TCP connection and serialization mechanisms but also allows for customization to suit specific project needs. The framework supports methods, events, properties, and notifiers, giving developers comprehensive tools to build robust networked applications. With its stand-alone mode, developers can simulate server-client interactions without a network connection, facilitating development and debugging. Regulus Remote aims to streamline network communication in game development and other applications, enabling developers to focus more on implementing business logic rather than dealing with the complexities of network protocols. ## Feature Server and client transfer through the interface, reducing the maintenance cost of the protocol. ![plantUML](https://camo.githubusercontent.com/dce87144cf414fe47edf85bdefd8b5f472624771fd3e455003153e59864b9354/687474703a2f2f7777772e706c616e74756d6c2e636f6d2f706c616e74756d6c2f7376672f5a5033314a69436d3338526c55476556474d587a57416367396b71306b6f34673759316156716c31494952374771415a787176524c47646944357a677356775f5669656b67484b7a55704f647770766a3374674d674435356668662d574c43525561524a4e306e44444749355444513133657932413849636e4c65466856722d306445796b727a63656e63446f54574d79574e76337274335a6372415431456d79464f793845597250433672714d435f54754c747747526d5349706b5f56656a7a4270515239673273367870504a7765567765674576436e384967387149643568696d4e7969365636377773704d6333534147766957506277445f6476444b5f597a726830694d74337059624a6741646a336e647a4f5570637a677076727930) ## Supports * Support **IL2CPP & AOT**. * Compatible with **.Net Standard2.0** or above development environment. * **Tcp** connection is provided by default, and any connection can be customized according to your needs. * **Serialization** is provided by default, and can be customized. * Support **Unity3D WebGL**, provide server-side Websocket, client-side need to implement their own. ## Usage 1. Definition Interface ```IGreeter``` . ```csharp namespace Protocol { public struct HelloRequest { public string Name; } public struct HelloReply { public string Message; } public interface IGreeter { Regulus.Remote.Value SayHello(HelloRequest request); } } ``` 2. Server implemente ```IGreeter```. ```csharp namespace Server { class Greeter : IGreeter { Regulus.Remote.Value SayHello(HelloRequest request) { return new HelloReply() { Message = $"Hello {request.Name}." }; } } } ``` 3. Use ```IBinder.Bind``` to send the ```IGreeter``` to the client. ```csharp namespace Server { public class Entry { readonly Greeter _Greeter; readonly Regulus.Remote.IBinder _Binder; readonly Regulus.Remote.ISoul _GreeterSoul; public Entry(Regulus.Remote.IBinder binder) { _Greeter = new Greeter(); _Binder = binder; // bind to client. _GreeterSoul = binder.Bind(_Greeter); } public void Dispose() { _Binder.Unbind(_GreeterSoul); } } } ``` 4. Client uses ```IAgent.QueryNotifier``` to obtain ```IGreeter```. ```csharp namespace Client { class Entry { public Entry(Regulus.Remote.IAgent agent) { agent.QueryNotifier().Supply += _AddGreeter; agent.QueryNotifier().Unsupply += _RemoveGreeter; } async void _AddGreeter(IGreeter greeter) { // Having received the greeter from the server, // begin to implement the following code. var reply = await greeter.SayHello(new HelloRequest() {Name = "my"}); } void _RemoveGreeter(IGreeter greeter) { // todo: The server has canceled the greeter. } } } ``` --- After completing the above steps, the server and client can communicate through the interface to achieve object-oriented development as much as possible. #### Specification **Interface** In addition to the above example ``IGreeter.SayHello``, there are a total of four ways to ... * [```Method```](https://github.com/jiowchern/Regulus.Remote/blob/github-readme/document/communications-method.md) <-- ```IGreeter.SayHello``` * [```Event```](https://github.com/jiowchern/Regulus.Remote/blob/github-readme/document/communications-event.md) * [```Property```](https://github.com/jiowchern/Regulus.Remote/blob/github-readme/document/communications-property.md) * [```Notifier```](https://github.com/jiowchern/Regulus.Remote/blob/github-readme/document/communications-notifier.md) **Serialization** For the types that can be serialized, see [```Regulus.Serialization```](https://github.com/jiowchern/Regulus.Remote/blob/github-readme/Regulus.Serialization/README.md) instructions. --- ## Getting Started This is a server-client framework, so you need to create three projects : ```Protocol```, ```Server``` and ```Client```. #### Requirements * Visual Studio 2022 17.0.5 above. * .NET Sdk 5 above. #### Protocol Project Create common interface project ```Protocol.csproj```. ```powershell Sample/Protocol>dotnet new classlib ``` 1. Add References ```xml all runtime; build; native; contentfiles; analyzers; buildtransitive ``` 2. Add interface, ```IGreeter.cs``` ```csharp namespace Protocol { public interface IGreeter { Regulus.Remote.Value SayHello(string request); } } ``` 3. Add ```ProtocolCreater.cs```. ```csharp namespace Protocol { public static partial class ProtocolCreater { public static Regulus.Remote.IProtocol Create() { Regulus.Remote.IProtocol protocol = null; _Create(ref protocol); return protocol; } /* Create a partial method as follows. */ [Regulus.Remote.Protocol.Creater] static partial void _Create(ref Regulus.Remote.IProtocol protocol); } } ``` This step is to generate the generator for the ``IProtocol``, which is an important component of the framework and is needed for communication between the server and the client. **_Note_** >> As shown in the code above, Add ```Regulus.Remote.Protocol``` attribute to the method you want to get ```IProtocol```, the method specification must be ```static partial void Method(ref Regulus.Remote.IProtocol)```, otherwise it will not pass compilation. --- #### Server Project Create the server. ```Server.csproj``` ```powershell Sample/Server>dotnet new console ``` 1. Add References ```xml ``` 2. Instantiate ```IGreeter``` ```csharp namespace Server { public class Greeter : Protocol.IGreeter { Regulus.Remote.Value SayHello(string request) { // Return the received message return $"echo:{request}"; } } } ``` 3. The server needs an entry point to start the environment , creating an entry point that inherits from ``Regulus.Remote.IEntry``. ```Entry.cs``` ```csharp namespace Server { public class Entry : Regulus.Remote.IEntry { void IBinderProvider.RegisterClientBinder(IBinder binder) { binder.Binder(new Greeter()); } void IBinderProvider.UnregisterClientBinder(IBinder binder) { // when client disconnect. } void IEntry.Update() { // Update } } } ``` 4. Create Tcp service ```csharp namespace Server { static void Main(string[] args) { // Get IProtocol with ProtocolCreater var protocol = Protocol.ProtocolCreater.Create(); // Create Service var entry = new Entry(); var set = Regulus.Remote.Server.Provider.CreateTcpService(entry, protocol); int yourPort = 0; set.Listener.Bind(yourPort); // Close service set.Listener.Close(); set.Service.Dispose(); } } ``` --- #### Client Project Create Client. ```Client.csproj```. ```powershell Sample/Client>dotnet new console ``` 1. Add References ```xml ``` 2. Create Tcp client ```csharp namespace Client { static async Task Main(string[] args) { // Get IProtocol with ProtocolCreater var protocol = Protocol.ProtocolCreater.Create(); var set = Regulus.Remote.Client.Provider.CreateTcpAgent(protocol); bool stop = false; var task = System.Threading.Tasks.Task.Run(() => { while (!stop) { set.Agent.Update(); } }); // Start Connecting EndPoint yourEndPoint = null; var peer = await set.Connector.Connect(yourEndPoint ); set.Agent.Enable(peer); // SupplyEvent ,Receive add IGreeter. set.Agent.QueryNotifier().Supply += greeter => { greeter.SayHello("hello"); }; // SupplyEvent ,Receive remove IGreeter. set.Agent.QueryNotifier().Unsupply += greeter => { }; // Close stop = true; task.Wait(); set.Connector.Disconnect(); set.Agent.Disable(); } } ``` --- ## Standalone mode In order to facilitate development and debugging, a standalone mode is provided to run the system without a connection. ```powershell Sample/Standalone>dotnet new console ``` 1. Add References ```xml ``` 2. Create standlone service ```csharp namespace Standalone { static void Main(string[] args) { // Get IProtocol with ProtocolCreater var protocol = Protocol.ProtocolCreater.Create(); // Create service var entry = new Entry(); var service = Regulus.Remote.Standalone.Provider.CreateService(entry , protocol); var agent = service.Create(); bool stop = false; var task = System.Threading.Tasks.Task.Run(() => { while (!stop) { agent.Update(); } }); agent.QueryNotifier().Supply += greeter => { greeter.SayHello("hello"); }; agent.QueryNotifier().Unsupply += greeter => { }; // Close stop = true; task.Wait(); agent.Dispose(); service.Dispose(); } } ``` --- ## Custom Connection If you want to customize the connection system you can do so in the following way. #### Client Create a connection use ```CreateAgent``` and implement the interface ```IStreamable```. ```csharp var protocol = Protocol.ProtocolCreater.Create(); IStreamable stream = null ;// todo: Implementation Interface IStreamable var service = Regulus.Remote.Client.CreateAgent(protocol , stream) ; ``` implement ```IStreamable```. ```csharp using Regulus.Remote; namespace Regulus.Network { public interface IStreamable { ///

/// Receive data streams. ///

/// Stream instance. /// Start receiving position. /// Count of byte received. /// Actual count of byte received. IWaitableValue Receive(byte[] buffer, int offset, int count); ///

/// Send data streams. ///

/// Stream instance. /// Start send position. /// Count of byte send. /// Actual count of byte send. IWaitableValue Send(byte[] buffer, int offset, int count); } } ``` #### Server Create a service use ```CreateService``` and implement the interface ```IListenable```. ```csharp var protocol = Protocol.ProtocolCreater.Create(); var entry = new Entry(); IListenable listener = null; // todo: Implementation Interface IListenable var service = Regulus.Remote.Server.CreateService(entry , protocol , listener) ; ``` implement ```IListenable```. ```csharp namespace Regulus.Remote.Soul { public interface IListenable { // When connected event System.Action StreamableEnterEvent; // When disconnected event System.Action StreamableLeaveEvent; } } ``` --- ## Custom Serialization implement ```ISerializable```. ```csharp namespace Regulus.Remote { public interface ISerializable { Regulus.Memorys.Buffer Serialize(System.Type type, object instance); object Deserialize(System.Type type, Regulus.Memorys.Buffer buffer); } } ``` and bring it to the server ```CreateTcpService```. ```csharp var protocol = Protocol.ProtocolCreater.Create(); var entry = new Entry(); ISerializable yourSerializer = null; var service = Regulus.Remote.Server.CreateTcpService(entry , protocol , yourSerializer) ; ``` and bring it to the client ```CreateTcpAgent```. ```csharp var protocol = Protocol.ProtocolCreater.Create(); ISerializable yourSerializer = null ; var service = Regulus.Remote.Client.CreateTcpAgent(protocol , yourSerializer) ; ``` If need to know what types need to be serialized can refer ```Regulus.Remote.IProtocol.SerializeTypes```. ```csharp namespace Regulus.Remote { public interface IProtocol { // What types need to be serialized. System.Type[] SerializeTypes { get; } System.Reflection.Assembly Base { get; } EventProvider GetEventProvider(); InterfaceProvider GetInterfaceProvider(); MemberMap GetMemberMap(); byte[] VerificationCode { get; } } } ``` --- ## Example **Chat Room** A full example of the application can be found here, including the Unity and Stride3D version. [Link](https://github.com/jiowchern/Regulus.Samples/tree/readme/Chat1)