Architecture Overview
=====================

This networking library is designed around a **client–server model**,
where the **server is authoritative** and all clients connect through it.
The library builds on top of the Lidgren networking library and wraps it
with Unity components and patterns that make multiplayer games easier to
develop.

The Core Components
-------------------

The system is made up of four main scripts:

- **UCNetwork (Base Class)**  
  Abstract base class that defines the networking loop, message parsing,
  RPC serialization, ownership, and network ID mapping. Both the client
  and server inherit from it.

- **ServerNetwork**  
  Manages all connections from clients, validates input, owns global
  state, and distributes updates. Issues ID pools to clients and can
  instantiate objects itself.

- **ClientNetwork**  
  Connects to the server, instantiates objects, and forwards local input
  or actions (via RPCs or Sync messages). Renders authoritative updates
  from the server.

- **NetworkSync**  
  Attached to each networked GameObject. Handles per-object sync data,
  RPC targeting, and ownership callbacks. All networked prefabs must
  include this component.

Supporting systems include **Areas** (interest management), **Ownership**
(authoritative control of objects), and **Message Types** (RPC, Sync, Instantiate,
Destroy, etc.).

Data Flow Overview
------------------

.. code-block::

            +----------------------+
            |        Server        |
            |   (ServerNetwork)    |
            +----------+-----------+
                       ^
                       |
             All client traffic
                       |
        +--------------+--------------+
        |                             |
   +----+----+                   +----+----+
   | Client A |                   | Client B |
   | (Client  |                   | (Client  |
   | Network) |                   | Network) |
   +----+----+                   +----+----+
        |                             |
        |   Local input, RPCs, Sync   |
        |---------------------------->|
        |                             |
        | <---------------------------|
        |     Authoritative updates   |

- All traffic goes **through the server**. Clients never talk directly.
- Clients send **RPCs** (discrete events) or **Sync/LiteSync** (continuous state).
- The server validates, decides recipients (all clients, other clients,
  area-specific, etc.), and forwards updates.
- Clients interpolate or extrapolate received states to render smoothly.

Object Lifecycle
----------------

1. **Instantiation**
   - Client calls ``ClientNetwork.Instantiate("PrefabName", pos, rot)``.
   - Client chooses a free ID from its pool and tells the server.
   - Server tracks the object and forwards Instantiate messages to other clients.
   - All clients create the object locally with a ``NetworkSync`` component.

2. **Synchronization**
   - The owning machine (client or server) sends SyncUpdate or LiteSyncUpdate.
   - Server forwards updates to other clients in the same area.
   - Remote clients update transforms and apply custom byte data.

3. **Ownership**
   - By default, the spawner owns the object.
   - Ownership can transfer (on disconnect, area changes, or by server logic).
   - ``OnGainOwnership`` / ``OnLoseOwnership`` fire on the GameObject.

4. **Destruction**
   - Owner requests destruction via ``Destroy(objectId)``.
   - Server validates, forwards Destroy messages to all clients.
   - Object is removed everywhere.

Message Types
-------------

The server and client communicate using a small set of message types:

- **RPC (5)** – Remote procedure call (discrete actions).
- **SyncUpdate (1)** – Full transform sync + byte payload.
- **LiteSyncUpdate (11)** – Byte payload only.
- **Instantiate (2)** – Spawn a new object.
- **Destroy (9)** – Remove an object.
- **AddToArea (3) / RemoveFromArea (4)** – Client changes area membership.
- **AddObjectToArea (13) / RemoveObjectFromArea (14)** – Assign objects to areas.
- **IdAllocation (6)** – Server grants a pool of IDs to client.
- **OwnershipGained (7) / OwnershipLost (8)** – Change authority.
- **ConnectNetworkSync (12)** – Attach scene object to networking.

Lifecycle Diagram
-----------------

.. code-block::

    Client                 Server                 Other Clients
      |                      |                           |
      | Instantiate()        |                           |
      |--------------------->|                           |
      |                      |--- forward Instantiate -->|
      |                      |                           |
      |-- SyncUpdate ------->|--- SyncUpdate ----------->|
      |                      |                           |
      | Destroy(objectId)    |                           |
      |--------------------->|--- forward Destroy ------>|
      |                      |                           |

Key Ideas
---------

- **Authoritative server**: all validation and forwarding decisions happen server-side.
- **Areas**: clients only receive updates for areas they belong to.
- **Ownership**: only owners may send updates for objects.
- **ID Pools**: each client gets a block of IDs so local spawns are instant but still unique.
- **Reflection-based RPCs**: method names are sent as strings and invoked at runtime.

Summary
-------

- ``UCNetwork`` provides the backbone message loop and serialization.
- ``ServerNetwork`` manages clients, IDs, areas, and authority.
- ``ClientNetwork`` connects to the server and spawns/updates objects.
- ``NetworkSync`` lives on prefabs to tie Unity objects into the system.
- Data always flows **client → server → clients**; no peer-to-peer.
- Areas and ownership ensure bandwidth efficiency and authority.