Home

Awesome

Documentation Discord release openupm

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

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:

  1. Mirage requires at least Unity 2020 LTS. You may install Unity 2020 LTS via the Unity website or via the Unity Hub. <br/> 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.
  2. 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.
  3. Add the OpenUPM registry. Click on the Edit menu, then select Project settings..., select Package Manager, and add a scoped registry like so: <br/> Name: OpenUPM <br/> Url: https://package.openupm.com <br/> Scopes:
    • com.cysharp.unitask
    • com.openupm
    • com.miragenet
    • com.miragenet.mirage Scoped Registry
  4. Close the project settings.
  5. 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: Install Mirage
  6. 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:

MirageMirror
Installs via OpenUPM UPM repositoryInstalls from the Unity Asset Store
Errors are thrown as exceptionsErrors are logged
[ServerRpc][Command]
[ClientRpc(target = RpcTarget.Owner)][TargetRpc]
Subscribe to events in NetworkServerOverride methods in NetworkManager
Subscribe to events in NetworkClientOverride methods in NetworkManager
Subscribe to events in NetworkIdentityOverride methods in NetworkBehaviour
Methods use PascalCase (C# guidelines)No consistency
NetworkTime available in NetworkBehaviourNetworkTime is global static
Send any data as messagesMessages must implement NetworkMessage
Supports Unity 2020.3 LTS or laterSupports Unity 2020.3 LTS or later
Offers simple Socket API to implement new protocolsEach protocol requires a new transport

Some notable features that Mirage has:

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

Development environment setup

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

Linux and Mac

  1. 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.
  2. Clone the Mirage repository:
    cd /path/to/somewhere/on/your/disk
    mkdir MirageNetworking
    git clone https://github.com/MirageNet/Mirage.git MirageNetworking
    
  3. Open the newly cloned repo in Unity 2020.3 LTS or later.

Windows

  1. 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.
  2. 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.
  3. Open in Unity 2020.3 LTS or later and have fun!

Transport and Sockets

Mirage supports multiple ways of transporting data:

Contributing

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

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!