Connection and Disconnection
============================

This section explains how clients connect to and disconnect from the server, 
how unique client identifiers are assigned, and how the server can 
intentionally remove (kick) a client.

Connecting to a Server
----------------------

On the client side, connections are managed through the
``ClientNetwork`` component. To use it, attach ``ClientNetwork`` to
a GameObject in your **Client** Unity project.

.. code-block:: csharp

   // Example: Connecting a client
   using UnityEngine;

   public class GameStarter : MonoBehaviour
   {
       public ClientNetwork clientNetwork;

       void Start()
       {
           string serverAddress = "127.0.0.1";   // IP or hostname of the server
           int port = 603;                       // Default UCNetwork port
           string username = "Student01";
           string password = "";
           string clientType = "Player";
           ulong uniqueId = 12345;               // Could be a Steam ID or device ID

           clientNetwork.Connect(
               serverAddress,
               port,
               username,
               password,
               clientType,
               uniqueId
           );
       }
   }

When ``Connect()`` is called, the client sends its login information
(username, password, clientType, and uniqueId) to the server for approval.

On the server side, ``ServerNetwork`` receives a
``ConnectionRequest`` message. The game logic (your own code) must
approve or deny the connection using:

.. code-block:: csharp

   serverNetwork.ConnectionApproved(clientId);
   // or
   serverNetwork.ConnectionDenied(clientId);

If approved, the server assigns this client a pool of **network IDs**
used later for spawning objects.

Unique Client IDs
-----------------

Every client has a **unique identifier** (``RemoteUniqueIdentifier``)
assigned by the Lidgren networking library when they connect.
This ID is a 64-bit value that:

- Distinguishes one client from another, even if they share the same IP.
- Is stable for the lifetime of the connection.
- Is used in many server APIs, such as kicking a client or assigning ownership.

On the server, you can access this ID in callbacks or through
``ClientData.networkIdentifier``.

.. note::

   This is *not* the same as the ``uniqueId`` value the client sends
   in ``Connect()``. That field is optional game-specific metadata
   (for example, a Steam ID or account ID). The ``RemoteUniqueIdentifier``
   is the authoritative network ID managed by the library.

Disconnecting from a Server
---------------------------

Clients can voluntarily disconnect using:

.. code-block:: csharp

   clientNetwork.Disconnect("Player has quit");

This will:
- Close the underlying Lidgren ``NetClient`` connection.
- Clean up all locally tracked network objects.

When a client disconnects, the server is notified and will:
- Transfer or destroy any objects the client owned.
- Remove the client from its internal client list.

On the server, you can detect disconnections through Unity messages:

.. code-block:: csharp

   void OnClientDisconnected(long clientId)
   {
       Debug.Log("Client disconnected: " + clientId);
   }

Kicking a Client
----------------

The server may also *forcibly* disconnect a client, for example due to
misbehavior, cheating, or admin action. Use the ``Kick()`` method:

.. code-block:: csharp

   // Example: Kick a client by ID
   long clientId = 123456789L; // RemoteUniqueIdentifier
   serverNetwork.Kick(clientId);

Internally, this sends a disconnection message to the client and
removes them from the server’s active connections. The client will
receive the same disconnect cleanup sequence as if it had quit normally.

Connection Lifecycle Diagram
----------------------------

The following diagram shows the typical connection flow:

.. code-block::

    +---------+         Connect()          +---------+
    | Client  | -------------------------> | Server  |
    |         |   (username, password,     |         |
    |         |    clientType, uniqueId)   |         |
    +---------+                            +---------+
                                             |
                                             v
                                     ConnectionRequest
                                             |
                       +---------------------+---------------------+
                       |                                           |
                ConnectionApproved                          ConnectionDenied
                       |                                           |
                       v                                           v
                  +---------+                               +-------------+
                  | Client  |                               | Connection  |
                  | Active  |                               | Closed      |
                  +---------+                               +-------------+
                       |
             Disconnect() or Kick()
                       |
                       v
                +-------------+
                | Connection  |
                | Closed      |
                +-------------+

Unity Callbacks for Connection Events
-------------------------------------

Both ``ClientNetwork`` and ``ServerNetwork`` use Unity’s
``SendMessage`` system to notify your scripts when network status
changes. You can implement any of these methods in your own MonoBehaviour
scripts to react to connection events:

- ``OnNetStatusConnected`` – Called when a client has successfully connected.
- ``OnNetStatusDisconnected`` – Called when a connection is closed.
- ``OnClientConnected(long clientId)`` – Server-only, called when a new client connects.
- ``OnClientDisconnected(long clientId)`` – Server-only, called when a client disconnects.
- ``OnNetStatusInitiatedConnect`` – Called when a client starts attempting a connection.
- ``OnNetStatusRespondedAwaitingApproval`` – Called when the server has received a connection but has not yet approved.
- ``OnNetStatusRespondedConnect`` – Called when the server has approved the connection.

Example usage on the server:

.. code-block:: csharp

   public class ServerUI : MonoBehaviour
   {
       void OnClientConnected(long clientId)
       {
           Debug.Log("Client joined: " + clientId);
       }

       void OnClientDisconnected(long clientId)
       {
           Debug.Log("Client left: " + clientId);
       }
   }

Example usage on the client:

.. code-block:: csharp

   public class ClientUI : MonoBehaviour
   {
       void OnNetStatusConnected()
       {
           Debug.Log("Connected to server!");
       }

       void OnNetStatusDisconnected()
       {
           Debug.Log("Disconnected from server!");
       }
   }

Summary
-------

- **Clients connect** using ``ClientNetwork.Connect(server, port, username, password, clientType, uniqueId)``.
- **Servers approve or deny** connections via ``ConnectionApproved()`` or ``ConnectionDenied()``.
- **Unique client IDs** are assigned by the network library (``RemoteUniqueIdentifier``) and are used for ownership, tracking, and kicking.
- **Clients disconnect** voluntarily using ``Disconnect(reason)``.
- **Servers can kick** a client using ``Kick(clientId)``.
- **Unity callbacks** let you hook into connect/disconnect events without modifying networking code.