Unity Callbacks
===============

This networking library uses Unity’s ``SendMessage`` system to notify
your scripts about important network events. Any MonoBehaviour in the
scene can implement these methods, and they will be called automatically
when the corresponding event happens.

Callbacks are grouped below by category.

Connection Status Callbacks
---------------------------

These are fired in response to changes in the underlying Lidgren
connection state. They are triggered by ``UCNetwork.HandleMessage_StatusChanged``.

- ``OnNetStatusNone()``  
  Fired when the connection status is ``None`` (not yet initialized).

- ``OnNetStatusInitiatedConnect()``  
  Fired when the client begins attempting a connection.

- ``OnNetStatusReceivedInitiation()``  
  Fired when the other endpoint responds to the connection initiation.

- ``OnNetStatusRespondedAwaitingApproval()``  
  Fired when the server has received a connection request but has not yet
  approved or denied it.

- ``OnNetStatusRespondedConnect()``  
  Fired when the server has approved the connection and a response has
  been received.

- ``OnNetStatusConnected()``  
  Fired when the connection is fully established and ready for data.

- ``OnNetStatusDisconnecting()``  
  Fired when a connection is in the process of disconnecting.

- ``OnNetStatusDisconnected()``  
  Fired when a connection has been closed.

Server-Specific Callbacks
-------------------------

These are called only on the server side when clients join or leave.

- ``OnClientConnected(long clientId)``  
  Fired when a client connects. The ``clientId`` is the client’s
  ``RemoteUniqueIdentifier``.

- ``OnClientDisconnected(long clientId)``  
  Fired when a client disconnects. The ``clientId`` is the client’s
  ``RemoteUniqueIdentifier``.

Ownership Callbacks
-------------------

These are fired on networked objects (those with a ``NetworkSync``)
when ownership changes. They are triggered by ``UCNetwork.AddOwnedId``
and ``UCNetwork.RemoveOwnedId``.

- ``OnGainOwnership()``  
  Fired when this machine becomes the owner of the object.
  Typically used to enable input, authority-driven logic,
  or camera follow.

- ``OnLoseOwnership()``  
  Fired when this machine loses ownership of the object.
  Typically used to disable input and relinquish control.

Object Lifecycle Callbacks
--------------------------

These are invoked on GameObjects with a ``NetworkSync`` when they are
instantiated or destroyed by the networking system.

- ``NetworkInitialized()``  
  Fired after an object has been instantiated and its
  ``NetworkSync`` has been assigned a network ID. Use this for
  initialization logic that depends on networking.

- ``OnDestroyNetworkObject()`` *(optional)*  
  If implemented, can be used to clean up before a networked
  object is destroyed. (Default destruction is automatic.)

Custom Event Hooks
------------------

Some callbacks are reserved for optional or advanced features:

- **Voice Chat (stubbed)**  
  If you implement voice chat, additional callbacks may be added
  such as ``OnVoiceDataReceived(int networkId, byte[] data)``.
  These are not wired by default but can be integrated with the
  existing ``VoiceData`` message type.

Example Usage
-------------

**Client Status Display**

.. code-block:: csharp

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

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

**Server Logging**

.. code-block:: csharp

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

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

**Ownership Example**

.. code-block:: csharp

   public class PlayerController : MonoBehaviour
   {
       bool hasControl;

       void OnGainOwnership()
       {
           hasControl = true;
           Debug.Log("Now controlling this player object.");
       }

       void OnLoseOwnership()
       {
           hasControl = false;
           Debug.Log("Lost control of this player object.");
       }
   }

Summary
-------

- **Connection callbacks** reflect client/server connect and disconnect events.
- **Server callbacks** notify when clients join or leave.
- **Ownership callbacks** let you react when authority changes.
- **Object lifecycle callbacks** run when objects are created and initialized.
- These methods are automatically invoked if present on your scripts.