diff --git a/Assets/Mirror/Runtime/Transport/Transport.cs b/Assets/Mirror/Runtime/Transport/Transport.cs index 6f3430e11..c14a7f111 100644 --- a/Assets/Mirror/Runtime/Transport/Transport.cs +++ b/Assets/Mirror/Runtime/Transport/Transport.cs @@ -30,61 +30,31 @@ namespace Mirror /// Abstract transport layer component public abstract class Transport : MonoBehaviour { - /// - /// The current transport used by Mirror. - /// + /// The current transport used by Mirror. public static Transport activeTransport; - /// - /// Is this transport available in the current platform? - /// Some transports might only be available in mobile - /// Many will not work in webgl - /// Example usage: return Application.platform == RuntimePlatform.WebGLPlayer - /// - /// True if this transport works in the current platform + /// Is this transport available in the current platform? public abstract bool Available(); - #region Client - /// - /// Notify subscribers when this client establish a successful connection to the server - /// callback() - /// + /// Called by Transport when the client connected to the server. public Action OnClientConnected = () => Debug.LogWarning("OnClientConnected called with no handler"); - /// - /// Notify subscribers when this client receive data from the server - /// callback(ArraySegment<byte> data, int channel) - /// + /// Called by Transport when the client received a message from the server. public Action, int> OnClientDataReceived = (data, channel) => Debug.LogWarning("OnClientDataReceived called with no handler"); - /// - /// Notify subscribers when this client encounters an error communicating with the server - /// callback(Exception e) - /// + /// Called by Transport when the client encountered an error. public Action OnClientError = (error) => Debug.LogWarning("OnClientError called with no handler"); - /// - /// Notify subscribers when this client disconnects from the server - /// callback() - /// + /// Called by Transport when the client disconnected from the server. public Action OnClientDisconnected = () => Debug.LogWarning("OnClientDisconnected called with no handler"); - /// - /// Determines if we are currently connected to the server - /// - /// True if a connection has been established to the server + /// True if the client is currently connected to the server. public abstract bool ClientConnected(); - /// - /// Establish a connection to a server - /// - /// The IP address or FQDN of the server we are trying to connect to + /// Connects the client to the server at the address. public abstract void ClientConnect(string address); - /// - /// Establish a connection to a server - /// - /// The address of the server we are trying to connect to + /// Connects the client to the server at the Uri. public virtual void ClientConnect(Uri uri) { // By default, to keep backwards compatibility, just connect to the host @@ -92,119 +62,61 @@ public virtual void ClientConnect(Uri uri) ClientConnect(uri.Host); } - /// - /// Send data to the server - /// - /// The channel to use. 0 is the default channel, - /// but some transports might want to provide unreliable, encrypted, compressed, or any other feature - /// as new channels - /// The data to send to the server. Will be recycled after returning, so either use it directly or copy it internally. This allows for allocation-free sends! + /// Sends a message to the server over the given channel. + // The ArraySegment is only valid until returning. Copy if needed. public abstract void ClientSend(int channelId, ArraySegment segment); - /// - /// Disconnect this client from the server - /// + /// Disconnects the client from the server public abstract void ClientDisconnect(); - #endregion - - #region Server - - - /// - /// Retrieves the address of this server. - /// Useful for network discovery - /// - /// the url at which this server can be reached + /// Returns server address as Uri. + // Useful for NetworkDiscovery. public abstract Uri ServerUri(); - /// - /// Notify subscribers when a client connects to this server - /// callback(int connId) - /// + /// Called by Transport when a new client connected to the server. public Action OnServerConnected = (connId) => Debug.LogWarning("OnServerConnected called with no handler"); - /// - /// Notify subscribers when this server receives data from the client - /// callback(int connId, ArraySegment<byte> data, int channel) - /// + /// Called by Transport when the server received a message from a client. public Action, int> OnServerDataReceived = (connId, data, channel) => Debug.LogWarning("OnServerDataReceived called with no handler"); - /// - /// Notify subscribers when this server has some problem communicating with the client - /// callback(int connId, Exception e) - /// + /// Called by Transport when a server's connection encountered a problem. public Action OnServerError = (connId, error) => Debug.LogWarning("OnServerError called with no handler"); - /// - /// Notify subscribers when a client disconnects from this server - /// callback(int connId) - /// + /// Called by Transport when a client disconnected from the server. public Action OnServerDisconnected = (connId) => Debug.LogWarning("OnServerDisconnected called with no handler"); - /// - /// Determines if the server is up and running - /// - /// true if the transport is ready for connections from clients + /// True if the server is currently listening for connections. public abstract bool ServerActive(); - /// - /// Start listening for clients - /// + /// Start listening for connections. public abstract void ServerStart(); - /// - /// Send data to a client. - /// - /// The client connection id to send the data to - /// The channel to be used. Transports can use channels to implement - /// other features such as unreliable, encryption, compression, etc... - /// + /// Send a message to a client over the given channel. public abstract void ServerSend(int connectionId, int channelId, ArraySegment segment); - /// - /// Disconnect a client from this server. Useful to kick people out. - /// - /// the id of the client to disconnect + /// Disconnect a client from the server. public abstract void ServerDisconnect(int connectionId); - /// - /// Get the client address - /// - /// id of the client - /// address of the client + /// Get a client's address on the server. + // Can be useful for Game Master IP bans etc. public abstract string ServerGetClientAddress(int connectionId); - /// - /// Stop listening for clients and disconnect all existing clients - /// + /// Stop listening and disconnect all connections. public abstract void ServerStop(); - #endregion - - /// - /// The maximum packet size for a given channel. Unreliable transports - /// usually can only deliver small packets. Reliable fragmented channels - /// can usually deliver large ones. - /// - /// GetMaxPacketSize needs to return a value at all times. Even if the - /// Transport isn't running, or isn't Available(). This is because - /// Fallback and Multiplex transports need to find the smallest possible - /// packet size at runtime. - /// - /// channel id - /// the size in bytes that can be sent via the provided channel + /// Maximum message size for the given channel. + // Different channels often have different sizes, ranging from MTU to + // several megabytes. + // + // Needs to return a value at all times, even if the Transport isn't + // running or available because it's needed for initializations. public abstract int GetMaxPacketSize(int channelId = Channels.Reliable); - /// - /// The maximum batch(!) size for a given channel. - /// Uses GetMaxPacketSize by default. - /// Some transports like kcp support large max packet sizes which should - /// not be used for batching all the time because they end up being too - /// slow (head of line blocking etc.). - /// - /// channel id - /// the size in bytes that should be batched via the provided channel + /// Maximum batch(!) size for the given c hannel. + // Uses GetMaxPacketSize by default. + // Some transports like kcp support large max packet sizes which should + // not be used for batching all the time because they end up being too + // slow (head of line blocking etc.). public virtual int GetMaxBatchSize(int channelId) => GetMaxPacketSize(channelId); @@ -242,15 +154,10 @@ public virtual void ServerEarlyUpdate() {} public virtual void ClientLateUpdate() {} public virtual void ServerLateUpdate() {} - /// - /// Shut down the transport, both as client and server - /// + /// Shut down the transport, both as client and server public abstract void Shutdown(); - /// - /// called when quitting the application by closing the window / pressing stop in the editor - /// virtual so that inheriting classes' OnApplicationQuit() can call base.OnApplicationQuit() too - /// + /// Called by Unity when quitting. Inheriting Transports should call base for proper Shutdown. public virtual void OnApplicationQuit() { // stop transport (e.g. to shut down threads)