MirageNet/Mirage

What is Mirage?

Mirage is a rolling-release high-level API for the Unity Game Engine that provides a powerful, yet easy to use networking API. Be it an online MMO, co-op adventure game or, a first-person shooter, Mirage improves your networked projects' probability of success significantly. With its modular structure and "use only what you need" approach, Mirage lets you unleash maximum performance out of your networking.

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

Mirage is a rolling-release network stack. With every update, you get the latest features and bug fixes. You are encouraged to diagnose, report, and help fix bugs that you find: Issue tickets will be investigated, feature requests are considered, and pull requests are regularly reviewed.

Mirage is built by passionate network engineers and is backed by a friendly community.

Installation

To install Mirage, follow these steps:

Mirage requires at least Unity 2020 LTS. You may install Unity 2020 LTS via the Unity website or via the Unity Hub.
You may use newer versions, however, LTS versions are strongly recommended as newer versions can contain bugs, glitches, or just flat-out break game projects.
Start a new project or open your existing one. If opening an existing one, it is strongly recommended to back it up before installing Mirage.
Add the OpenUPM registry. Click on the Edit menu, then select Project settings..., select Package Manager, and add a scoped registry like so:
Name: OpenUPM
Url: https://package.openupm.com
Scopes:
- com.cysharp.unitask
- com.openupm
- com.miragenet
- com.miragenet.mirage
Close the project settings.
Open the package manager by clicking on the Window menu and selecting Package Manager. Then select Packages, My Registries, select the latest version of Mirage and click install, like so:
You may come back to the package manager at any time to uninstall Mirage or upgrade it.

Migrating from Mirror

If you've got a project already using Mirror and you want to migrate it to Mirage, it's recommended to check out our Migration Guide for a smooth transition. Also check the heading below, as there are some major differences between Mirage and the other network library.

Comparison with Mirror

Mirage has some notable differences from its distant sister, Mirror. The table below briefly details them:

Mirage	Mirror
Installs via OpenUPM UPM repository	Installs from the Unity Asset Store
Errors are thrown as exceptions	Errors are logged
`[ServerRpc]`	`[Command]`
`[ClientRpc(target = RpcTarget.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 2020.3 LTS or later	Supports Unity 2020.3 LTS or later
Offers simple Socket API to implement new protocols	Each protocol requires a new transport

Some notable features that Mirage has:

Modular API: You only use the components you need
Network components can be added to child objects
Clients can connect to multiple servers - for example, be connected to a chat server while connected to a game server
Fast play mode support
Error handling
Version defines
Server Rpcs can return values
Bit packing to help compress values and reduce bandwidth

Peeking under the hood, Mirage is built upon fundamental pillars:

Mirage avoids singletons and static states in general
Mirage follows the SOLID principles
Mirage has high and low

Development environment setup

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

Linux and Mac

Ensure the git client is installed. On Linux, you can install it via your Package Manager. MacOS should have it included with the Xcode command-line tools, available from Apple.

Clone the Mirage repository:

cd /path/to/somewhere/on/your/disk
mkdir MirageNetworking
git clone https://github.com/MirageNet/Mirage.git MirageNetworking

Open the newly cloned repo in Unity 2020.3 LTS or later.

Windows

Install the git Windows Client or use your favorite git client (Fork, SourceTree, etc). Note that cloning the repository using a GUI tool should be fairly straightforward, we'll omit this for a command line example.
As an administrator, clone this repo with symbolic links support using Git Bash:
```
cd C:\UnityProjects\DontReallyUseThisExamplePath
mkdir MirageNetworking
git clone -c core.symlinks=true https://github.com/MirageNet/Mirage.git
```
If 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.
Open in Unity 2020.3 LTS or later and have fun!

Transport and Sockets

Mirage supports multiple ways of transporting data:

Native UDP socket (default on Windows and Linux) with fallback to C# UDP Sockets (default on MacOS and other platforms)
Steam (via Facepunch Steamworks)
WebSocket for WebGL clients (via SimpleWebSocket)

Contributing

See the Development Environment Setup above.
Fork this Mirage repository.
Using your new fork, create your feature branch: git checkout -b my-new-feature
Then commit your changes: git commit -am 'Add some feature'
Push to the branch: git push origin my-new-feature
Submit a pull request and let the team review your work. 😃

The team will review it ASAP and give it the stamp of approval, ask for changes or decline it with a detailed explanation.

Thank you for using Mirage and we hope to see your project be successful!

MirageNet / Mirage