/Mirage

Easy to use Network library for Unity 3d

Primary LanguageC#MIT LicenseMIT

Documentation Forum Discord release openupm

Build Quality Gate Status SonarCloud Coverage Lines of Code Technical Debt Code Smells

Mirage is a high level Networking API for Unity.

Mirage is built and tested for MMO Scale Networking by the developers of Cubica.

Mirage is optimized for ease of use and probability of success.

With Mirage the objects in the client are mirror images of the objects in the server. Mirage provides all the tools necessary to keep them in sync and pass messages between them.

Installation

To install Mirage, follow these steps:

  1. Install Unity 2020.1.17 or later
  2. Start a new project or open your existing one
  3. Add openupm registry. Click on the menu Edit -> Project settings..., and add a scoped registry like so: Scoped Registry
  4. Close the project settings
  5. Open the package manager. Click on menu Window -> Package Manager and select "Packages: My Registries", select the latest version of Mirage and click install, like so: Install Mirage
  6. You may come back to the package manager to unistall Mirage or upgrade it.

Comparison with Mirror

When migrating a project from Mirror to Mirage, these will be the most notable differences.

Mirage Mirror
Install via Unity Package Manager Install from Asset Store
Errors are thrown as exceptions Errors are logged
[ServerRpc] [Command]
[ClientRpc(target=Client.Owner)] [TargetRpc]
Subscribe to events in NetworkServer Override methods in NetworkManager
Subscribe to events in NetworkClient Override methods in NetworkManager
Subscribe to events in NetworkIdentity Override methods in NetworkBehaviour
Methods use PascalCase (C# guidelines) No consistency
NetworkTime available in NetworkBehaviour NetworkTime is global static
Send any data as messages Messages must implement NetworkMessage
Supports Unity 2019.3 or later Supports Unity 2018.4 or later

Mirage has many new features

  • Mirage supports fast domain reload
  • Components can be added in child objects
  • Your client can connect to multiple servers. For example chat server and game server
  • Modular, use only the components you need.
  • Error handling
  • Version defines
  • Server Rpcs can return values
  • The default transport features DoS prevention
  • The default transport has CRC64 integrity check
  • Mirage provides unreliable channel out of the box

If you look under the hood, the code base has some significant differences based on the core values of each project

  • Mirage follows the SOLID principles.
  • Mirage avoids singletons and static state in general.
  • Mirage has high Test Coverage
  • Mirage has low Technical Debt
  • Mirage values code quality, Mirror values API stability

Development environment

If you want to contribute to Mirage, follow these steps:

Linux and Mac

  1. Install git
  2. clone this repo
  3. Open in unity 2020.1.x or later

Windows

  1. Install git or use your favorite git client
  2. as administrator, clone this repo with symbolic links support: 
    git clone -c core.symlinks=true https://github.com/MirageNet/Mirage.git
    It you don't want to use administrator, add symlink support to your account. If you don't enable symlinks, you will be able to work on Mirage but Unity will not see the examples.
  3. Open in unity 2019.4.x or later

Transports

Here is a list of some transports supported by NG and how they compare to each other

Kcp Websocket Steam LiteNetLibNG IgnoranceNG
CCU 1000+ ? ? ? ?
Protocol UDP TCP UDP UDP UDP
Unreliable ✅ ✅ ✅ ✅
WebGL ✅
Mobile ✅ ? ?
CPU LOW HIGH ? ? ?
NAT Punch ✅
Encryption ✅ ✅
IPV6 ✅ ✅ ? ? ?
Managed ✅ ✅ ✅
Based on KCP Websockets Steam Game Networking Sockets LiteNetLib ENet

Contributing

There are several ways to contribute to this project:

  • Pull requests for bug fixes and features are always appreciated.
  • Pull requests to improve the documentation is also welcome
  • Make tutorials on how to use this
  • Test it and open issues
  • Review existing pull requests
  • Donations

When contributing code, please keep these things in mind:

  • KISS principle. Everything needs to be as simple as possible.
  • An API is like a joke, if you have to explain it is not a good one. Do not require people to read the documentation if you can avoid it.
  • Follow C# code conventions.
  • Follow SOLID principles as much as possible.
  • Keep your pull requests small and obvious, if a PR can be split into several small ones, do so.