Fallback Transport (#1198)

* Fallback Transport

* doc

* doc

* help URL

* exception

* fixed help url

Assets/Mirror/Runtime/Transport/FallbackTransport.cs

@@ -0,0 +1,138 @@
+// uses the first available transport for server and client.
+// example: to use Apathy if on Windows/Mac/Linux and fall back to Telepathy
+//          otherwise.
+using System;
+using System.Collections.Generic;
+using UnityEngine;
+
+namespace Mirror
+{
+    [HelpURL("https://mirror-networking.com/docs/Transports/Fallback.html")]
+    public class FallbackTransport : Transport
+    {
+        public Transport[] transports;
+
+        // the first transport that is available on this platform
+        Transport available;
+
+        public void Awake()
+        {
+            if (transports == null || transports.Length == 0)
+            {
+                throw new Exception("FallbackTransport requires at least 1 underlying transport");
+            }
+            InitClient();
+            InitServer();
+            available = GetAvailableTransport();
+            Debug.Log("FallbackTransport available: " + available.GetType());
+        }
+
+        // The client just uses the first transport available
+        Transport GetAvailableTransport()
+        {
+            foreach (Transport transport in transports)
+            {
+                if (transport.Available())
+                {
+                    return transport;
+                }
+            }
+            throw new Exception("No transport suitable for this platform");
+        }
+
+        public override bool Available()
+        {
+            return available.Available();
+        }
+
+        // clients always pick the first transport
+        void InitClient()
+        {
+            // wire all the base transports to our events
+            foreach (Transport transport in transports)
+            {
+                transport.OnClientConnected.AddListener(OnClientConnected.Invoke);
+                transport.OnClientDataReceived.AddListener(OnClientDataReceived.Invoke);
+                transport.OnClientError.AddListener(OnClientError.Invoke);
+                transport.OnClientDisconnected.AddListener(OnClientDisconnected.Invoke);
+            }
+        }
+
+        public override void ClientConnect(string address)
+        {
+            available.ClientConnect(address);
+        }
+
+        public override bool ClientConnected()
+        {
+            return available.ClientConnected();
+        }
+
+        public override void ClientDisconnect()
+        {
+            available.ClientDisconnect();
+        }
+
+        public override bool ClientSend(int channelId, ArraySegment<byte> segment)
+        {
+            return available.ClientSend(channelId, segment);
+        }
+
+        public override int GetMaxPacketSize(int channelId = 0)
+        {
+            return available.GetMaxPacketSize(channelId);
+        }
+
+        void InitServer()
+        {
+            // wire all the base transports to our events
+            foreach (Transport transport in transports)
+            {
+                transport.OnServerConnected.AddListener(OnServerConnected.Invoke);
+                transport.OnServerDataReceived.AddListener(OnServerDataReceived.Invoke);
+                transport.OnServerError.AddListener(OnServerError.Invoke);
+                transport.OnServerDisconnected.AddListener(OnServerDisconnected.Invoke);
+            }
+        }
+
+        public override bool ServerActive()
+        {
+            return available.ServerActive();
+        }
+
+        public override string ServerGetClientAddress(int connectionId)
+        {
+            return available.ServerGetClientAddress(connectionId);
+        }
+
+        public override bool ServerDisconnect(int connectionId)
+        {
+            return available.ServerDisconnect(connectionId);
+        }
+
+        public override bool ServerSend(List<int> connectionIds, int channelId, ArraySegment<byte> segment)
+        {
+            return available.ServerSend(connectionIds, channelId, segment);
+        }
+
+        public override void ServerStart()
+        {
+            available.ServerStart();
+        }
+
+        public override void ServerStop()
+        {
+            available.ServerStop();
+        }
+
+        public override void Shutdown()
+        {
+            available.Shutdown();
+        }
+
+        public override string ToString()
+        {
+            return available.ToString();
+        }
+    }
+}

Assets/Mirror/Runtime/Transport/FallbackTransport.cs.meta

@@ -0,0 +1,11 @@
+fileFormatVersion: 2
+guid: 330c9aab13d2d42069c6ebbe582b73ca
+MonoImporter:
+  externalObjects: {}
+  serializedVersion: 2
+  defaultReferences: []
+  executionOrder: 0
+  icon: {instanceID: 0}
+  userData: 
+  assetBundleName: 
+  assetBundleVariant: 

doc/Transports/Fallback.md

@@ -0,0 +1,18 @@
+# FallbackTransport
+
+The FallbackTransport can be used to work around transport platform limits.
+
+For example, our Apathy transport is currently only available on Windows, Mac and Linux where as Telepathy is available on all Platforms. Apathy has significant performance improvements, and ideally we would want Mirror to use Apathy if on Windows/Mac/Linux and fall back to Telepathy otherwise.
+
+This is what the FallbackTransport allows us to do.
+
+Usage:
+
+1. Add a gameobject with a NetworkManager to your scene if you have not done so
+2. By default, Unity will add TelepathyTransport to your NetworkManager game object
+3. Add a FallbackTransport component to the gameobject
+4. Assign the FallbackTransport component in your NetworkManager's transport
+5. Add a ApathyTransport component to the gameobject
+6. Add both ApathyTransport and TelepathyTransport to the FallbackTransport's transport property.
+
+Important: all fallback transport need to be binary compatible with each other. For example, it might happen that the server runs Apathy and a client connects to it with Telepathy.

doc/Transports/index.md

@@ -2,15 +2,17 @@
 Mirror is a high level Networking Library that can use several different low level transports.
 To use a transport, simply add it as component to the NetworkManager and drag it into the NetworkManager's Transport field.
 
--   [TCP - Telepathy](Telepathy.md)  
+-   [TCP - Telepathy](Telepathy.md)
     Simple, message based, MMO Scale TCP networking in C#. And no magic.
--   [UDP - Ignorance](Ignorance.md)  
+-   [UDP - Ignorance](Ignorance.md)
     Ignorance implements a reliable and unreliable sequenced UDP transport based on ENet.
--   [UDP - LiteNetLib4Mirror](LiteNetLib4Mirror.md)  
+-   [UDP - LiteNetLib4Mirror](LiteNetLib4Mirror.md)
     LiteNetLib4Mirror implements a UDP transport based on LiteNetLib with Network Discovery and uPnP included.
--   [WebGL - WebSockets](WebSockets.md)  
+-   [WebGL - WebSockets](WebSockets.md)
     WebSockets transport layer for Mirror that target WebGL clients, without relying on Unity's stodgy old LLAPI.
--   [Steam - Fizzy](Fizzy.md)  
+-   [Steam - Fizzy](Fizzy.md)
     A complete rebuild utilising Async (Previously SteamNetNetworkTransport) of a Steam P2P network transport layer.
--   [Multiplexer - Multiplexer](Multiplexer.md)  
+-   [Multiplexer - Multiplexer](Multiplexer.md)
     Multiplexer is a bridging transport to allow a server to handle clients on different transports concurrnently, for example desktop clients using Telepathy together with WebGL clients using Websockets.
+-   [Fallback](Fallback.md)
+    Fallback is a compatibility transport for transports that don't run on all platforms and need fallback options to cover all other platforms.