NetworkClient

Assets/Mirror/Runtime/NetworkClient.cs

@@ -14,29 +14,56 @@ public enum ConnectState
     }
 
     // TODO make fully static after removing obsoleted singleton!
+    /// <summary>
+    /// This is a network client class used by the networking system. It contains a NetworkConnection that is used to connect to a network server.
+    /// <para>The <see cref="NetworkClient">NetworkClient</see> handle connection state, messages handlers, and connection configuration. There can be many <see cref="NetworkClient">NetworkClient</see> instances in a process at a time, but only one that is connected to a game server (<see cref="NetworkServer">NetworkServer</see>) that uses spawned objects.</para>
+    /// <para><see cref="NetworkClient">NetworkClient</see> has an internal update function where it handles events from the transport layer. This includes asynchronous connect events, disconnect events and incoming data from a server.</para>
+    /// <para>The <see cref="NetworkManager">NetworkManager</see> has a NetworkClient instance that it uses for games that it starts, but the NetworkClient may be used by itself.</para>
+    /// </summary>
     public class NetworkClient
     {
         [EditorBrowsable(EditorBrowsableState.Never), Obsolete("Use NetworkClient directly. Singleton isn't needed anymore, all functions are static now. For example: NetworkClient.Send(message) instead of NetworkClient.singleton.Send(message).")]
         public static NetworkClient singleton = new NetworkClient();
 
+        /// <summary>
+        /// A list of all the active network clients in the current process.
+        /// <para>This is NOT a list of all clients that are connected to the remote server, it is client instances on the local game.</para>
+        /// </summary>
         [EditorBrowsable(EditorBrowsableState.Never), Obsolete("Use NetworkClient directly instead. There is always exactly one client.")]
-        public static List<NetworkClient> allClients => new List<NetworkClient>{singleton};
+        public static List<NetworkClient> allClients => new List<NetworkClient> { singleton };
 
+        /// <summary>
+        /// The registered network message handlers.
+        /// </summary>
         public static readonly Dictionary<int, NetworkMessageDelegate> handlers = new Dictionary<int, NetworkMessageDelegate>();
 
+        /// <summary>
+        /// The NetworkConnection object this client is using.
+        /// </summary>
         public static NetworkConnection connection { get; internal set; }
 
         internal static ConnectState connectState = ConnectState.None;
 
+        /// <summary>
+        /// The IP address of the server that this client is connected to.
+        /// <para>This will be empty if the client has not connected yet.</para>
+        /// </summary>
         public static string serverIp => connection.address;
 
-        // active is true while a client is connecting/connected
-        // (= while the network is active)
+        /// <summary>
+        /// active is true while a client is connecting/connected
+        /// (= while the network is active)
+        /// </summary>
         public static bool active => connectState == ConnectState.Connecting || connectState == ConnectState.Connected;
 
+        /// <summary>
+        /// This gives the current connection status of the client.
+        /// </summary>
         public static bool isConnected => connectState == ConnectState.Connected;
 
-        // NetworkClient can connect to local server in host mode too
+        /// <summary>
+        /// NetworkClient can connect to local server in host mode too
+        /// </summary>
         public static bool isLocalClient => connection is ULocalConnectionToServer;
 
         // local client in host mode might call Cmds/Rpcs during Update, but we
@@ -44,7 +71,10 @@ public class NetworkClient
         // to avoid race conditions. keep packets in Queue until LateUpdate.
         internal static Queue<byte[]> localClientPacketQueue = new Queue<byte[]>();
 
-        // connect remote
+        /// <summary>
+        /// Connect client to a NetworkServer instance.
+        /// </summary>
+        /// <param name="address"></param>
         public static void Connect(string address)
         {
             if (LogFilter.Debug) Debug.Log("Client Connect: " + address);
@@ -61,7 +91,9 @@ public static void Connect(string address)
             connection.SetHandlers(handlers);
         }
 
-        // connect host mode
+        /// <summary>
+        /// connect host mode
+        /// </summary>
         internal static void ConnectLocalServer()
         {
             if (LogFilter.Debug) Debug.Log("Client Connect Local Server");
@@ -81,7 +113,10 @@ internal static void ConnectLocalServer()
             localClientPacketQueue.Enqueue(MessagePacker.Pack(new ConnectMessage()));
         }
 
-        // Called by the server to set the LocalClient's LocalPlayer object during NetworkServer.AddPlayer()
+        /// <summary>
+        /// Called by the server to set the LocalClient's LocalPlayer object during NetworkServer.AddPlayer()
+        /// </summary>
+        /// <param name="localPlayer"></param>
         internal static void AddLocalPlayer(NetworkIdentity localPlayer)
         {
             if (LogFilter.Debug) Debug.Log("Local client AddLocalPlayer " + localPlayer.gameObject.name + " conn=" + connection.connectionId);
@@ -144,6 +179,10 @@ static void OnConnected()
             else Debug.LogError("Skipped Connect message handling because connection is null.");
         }
 
+        /// <summary>
+        /// Disconnect from server.
+        /// <para>The disconnect message will be invoked.</para>
+        /// </summary>
         public static void Disconnect()
         {
             connectState = ConnectState.Disconnected;
@@ -195,6 +234,15 @@ public static bool Send(short msgType, MessageBase msg)
             return false;
         }
 
+        /// <summary>
+        /// This sends a network message with a message Id to the server. This message is sent on channel zero, which by default is the reliable channel.
+        /// <para>The message must be an instance of a class derived from MessageBase.</para>
+        /// <para>The message id passed to Send() is used to identify the handler function to invoke on the server when the message is received.</para>
+        /// </summary>
+        /// <typeparam name="T">The message type to unregister.</typeparam>
+        /// <param name="message"></param>
+        /// <param name="channelId"></param>
+        /// <returns>True if message was sent.</returns>
         public static bool Send<T>(T message, int channelId = Channels.DefaultReliable) where T : IMessageBase
         {
             if (connection != null)
@@ -293,12 +341,12 @@ internal static void RegisterSystemHandlers(bool localClient)
             {
                 RegisterHandler<ObjectDestroyMessage>(ClientScene.OnLocalClientObjectDestroy);
                 RegisterHandler<ObjectHideMessage>(ClientScene.OnLocalClientObjectHide);
-                RegisterHandler<NetworkPongMessage>((conn, msg) => {});
+                RegisterHandler<NetworkPongMessage>((conn, msg) => { });
                 RegisterHandler<SpawnPrefabMessage>(ClientScene.OnLocalClientSpawnPrefab);
                 RegisterHandler<SpawnSceneObjectMessage>(ClientScene.OnLocalClientSpawnSceneObject);
-                RegisterHandler<ObjectSpawnStartedMessage>((conn, msg) => {}); // host mode doesn't need spawning
-                RegisterHandler<ObjectSpawnFinishedMessage>((conn, msg) => {}); // host mode doesn't need spawning
-                RegisterHandler<UpdateVarsMessage>((conn, msg) => {});
+                RegisterHandler<ObjectSpawnStartedMessage>((conn, msg) => { }); // host mode doesn't need spawning
+                RegisterHandler<ObjectSpawnFinishedMessage>((conn, msg) => { }); // host mode doesn't need spawning
+                RegisterHandler<UpdateVarsMessage>((conn, msg) => { });
             }
             else
             {
@@ -332,6 +380,12 @@ public static void RegisterHandler(MsgType msgType, NetworkMessageDelegate handl
             RegisterHandler((int)msgType, handler);
         }
 
+        /// <summary>
+        /// Register a handler for a particular message type.
+        /// <para>There are several system message types which you can add handlers for. You can also add your own message types.</para>
+        /// </summary>
+        /// <typeparam name="T">The message type to unregister.</typeparam>
+        /// <param name="handler"></param>
         public static void RegisterHandler<T>(Action<NetworkConnection, T> handler) where T : IMessageBase, new()
         {
             int msgType = MessagePacker.GetId<T>();
@@ -354,6 +408,10 @@ public static void UnregisterHandler(MsgType msgType)
             UnregisterHandler((int)msgType);
         }
 
+        /// <summary>
+        /// Unregisters a network message handler.
+        /// </summary>
+        /// <typeparam name="T">The message type to unregister.</typeparam>
         public static void UnregisterHandler<T>() where T : IMessageBase
         {
             // use int to minimize collisions
@@ -361,6 +419,10 @@ public static void UnregisterHandler<T>() where T : IMessageBase
             handlers.Remove(msgType);
         }
 
+        /// <summary>
+        /// Shut down a client.
+        /// <para>This should be done when a client is no longer going to be used.</para>
+        /// </summary>
         public static void Shutdown()
         {
             if (LogFilter.Debug) Debug.Log("Shutting down client.");