feat(docs): network

Author: Tchips46

.idea/[NanoForge] Engine.iml

@@ -0,0 +1,68 @@
+Network Overview
+================
+
+This page describes the global design and rationale for the engine's networking
+libraries: the `network-server` and `network-client` TypeScript packages. These
+libraries provide a small, pragmatic networking layer used by the example
+`pong-network` game and designed to be easy to understand and integrate.
+
+Goals
+-----
+
+- Minimal, predictable protocol for multiplayer games.
+- Use well-understood transports: TCP for reliable control messages and UDP
+  for low-latency, best-effort state updates.
+- Provide clear validation hooks (magic value, versioning) to avoid processing
+  ```restructuredtext
+  Network Overview
+  ================
+
+  This page explains how the engine's TypeScript networking packages actually
+  work and the rationale behind important implementation choices. The two
+  packages are `network-server` and `network-client` and are used by the
+  `example/pong-network` project.
+
+  Design summary
+  --------------
+
+  - Two logical transports are provided: a reliable, ordered channel (called
+    "TCP" in the packages) and an unreliable, unordered channel (called
+    "UDP"). Important: these names refer to channel semantics in the library,
+    not to raw OS sockets. Implementation details:
+    - The reliable channel is implemented over WebSocket (node `ws` and
+      browser `WebSocket`) to provide an ordered, byte-stream-like channel.
+    - The unreliable channel is implemented as a WebRTC `RTCDataChannel`
+      created with `ordered: false, maxRetransmits: 0`. WebSocket is used for
+      signaling/ICE exchange between client and server.
+
+- For packet framing and terminator semantics see the dedicated note:
+  `docs/network/packet-framing.rst`.
+
+  Why these choices
+  ------------------
+
+  - WebSocket for reliable messages: WebSocket is universally available in
+    browsers and easy to host in Node.js. Using it for the "TCP" channel avoids
+    needing a separate TCP server and simplifies browser + native client parity.
+
+  - WebRTC DataChannel for unreliable messages: Browsers cannot open raw UDP
+    sockets; WebRTC provides a browser-friendly unreliable datagram channel
+    with low latency. The repository uses WebSocket for ICE signaling and
+    negotiates a `RTCDataChannel` for actual game-state messages.
+
+  - Terminator (magic value) appended at packet end: appending a terminator is
+    robust against fragmented transport frames. Because WebSocket and RTC
+    DataChannels can split or aggregate application messages, a terminator
+    allows the receiver to detect full logical packets regardless of chunking.
+
+  - Configurable `magicValue`: The default (`PACKET_END`) is a human-readable
+    sentinel that makes debugging easier; it is configurable via the server or
+    client config objects if you prefer a shorter or binary marker.
+
+  Serialization and extensibility
+  -------------------------------
+
+  - Example code uses JSON payloads for clarity (easy to inspect and debug).
+    The transport layer operates on `Uint8Array` buffers, so you can replace
+    JSON with any binary encoding for
+    production.

.idea/misc.xml

@@ -0,0 +1,49 @@
+TCPClient
+~~~~~~~~~
+
+**connect** ()
+  Initiate a WebSocket connection to the server (e.g. `ws://<ip>:<port>`).
+
+  :return: Promise<void>
+
+**isConnected** ()
+  Return `true` when the underlying WebSocket is open.
+
+  :return: boolean
+
+**sendData** (*data*)
+  Send a payload to the server.
+
+  :param data: Uint8Array — raw payload bytes.
+  :return: void
+
+**getReceivedPackets** ()
+  Return an array of complete packets that were reassembled from received chunks.
+
+  :return: Uint8Array[] — array of packet buffers.
+
+
+UDPClient
+~~~~~~~~~
+
+**connect** ()
+  Open a WebSocket for signaling, create an RTCPeerConnection and initiate an SDP offer.
+
+  :return: Promise<void>
+
+**isConnected** ()
+  Return `true` when the RTCDataChannel is open.
+
+  :return: boolean
+
+**sendData** (*data*)
+  Send a payload on the data channel.
+
+  :param data: Uint8Array — raw payload bytes.
+  :return: void
+
+**getReceivedPackets** ()
+  Return an array of complete packets reassembled from received data-channel chunks.
+
+  :return: Uint8Array[] — array of packet buffers.
+

docs/network/index.rst

@@ -0,0 +1,41 @@
+Client Networking (network-client)
+==================================
+
+This document describes how the `network-client` package actually connects
+to a `NetworkServerLibrary` instance and the concrete APIs you will use from
+client-side code.
+
+Overview
+--------
+
+A client connects to a single server instance (one TCP/WebSocket control
+channel and optionally a single WebRTC data channel for unreliable traffic).
+Client responsibilities in a game are typically:
+
+- Initiate a TCP connection and send control commands (join/play/input).
+- Optionally negotiate a WebRTC data channel for receiving server snapshots
+  or sending low-latency updates.
+
+Minimal usage pattern (as in `example/pong-network`)
+--------------------------------------------------
+
+.. code-block:: javascript
+
+  // Ensure TCP is connected
+  await network.tcp.connect();
+
+  // Wait for UDP (RTC data channel) if used by the server
+  await waitForConnection();
+
+  // Send a simple reliable control message (play)
+  network.tcp.sendData(new TextEncoder().encode(JSON.stringify({ type: 'play' })));
+
+  // Send input messages (example)
+  network.tcp.sendData(new TextEncoder().encode(JSON.stringify({ type: 'input', key: 'up' })));
+
+Notes
+-----
+
+- See `docs/network/network-client-api.rst` for the client functions exposed to
+  your game code.
+- For packet framing/terminator semantics see `docs/network/packet-framing.rst`.

docs/network/network-client-api.rst

@@ -0,0 +1,64 @@
+TCPServer
+~~~~~~~~~
+
+**listen** ()
+  Start the WebSocket server and begin accepting clients.
+
+  :return: void
+
+**getConnectedClients** ()
+  Return a snapshot array of numeric client IDs currently connected.
+
+  :return: number[] — an array of client IDs.
+
+**sendToEverybody** (*data*)
+  Send a payload to every connected client.
+
+  :param data: Uint8Array — raw payload bytes.
+  :return: void
+  :throws: none (errors are logged, not thrown)
+
+**sendToClient** (*clientId, data*)
+  Send a payload to the client identified by `clientId`.
+
+  :param clientId: number — numeric client identifier.
+  :param data: Uint8Array — payload bytes.
+  :return: void
+  :throws: none (logs if client unknown)
+
+**getReceivedPackets** ()
+  Parse and return complete packets received from each client. Each packet is a `Uint8Array` buffer.
+
+  :return: Map<number, Uint8Array[]> — mapping client ID to array of packets.
+
+
+UDPServer
+~~~~~~~~~
+
+**listen** ()
+  Start the signaling WebSocket and accept incoming client offers (SDP/ICE).
+
+  :return: void
+
+**getConnectedClients** ()
+  Return a snapshot array of client IDs with active data channels.
+
+  :return: number[] — list of client IDs.
+
+**sendToEverybody** (*data*)
+  Send a payload to every connected data channel.
+
+  :param data: Uint8Array — raw payload bytes.
+  :return: void
+
+**sendToClient** (*clientId, data*)
+  Send a payload to a single client data channel.
+
+  :param clientId: number
+  :param data: Uint8Array
+  :return: void
+
+**getReceivedPackets** ()
+  Parse incoming channel chunks and return a map of complete packets per client.
+
+  :return: Map<number, Uint8Array[]> — mapping client ID to array of packets.

docs/network/network-client.rst

@@ -0,0 +1,47 @@
+Server Networking (network-server)
+==================================
+
+This document explains the actual `network-server` package implementation and
+the APIs you will use from server-side code.
+
+Overview
+--------
+
+The server listens on configured ports and accepts client connections.
+A single server process can accept many clients; typical server responsibilities
+in a game are:
+
+- Accept reliable control messages from clients over the TCP (WebSocket) channel.
+- Optionally establish `RTCPeerConnection`s (via WebSocket signaling) to receive
+  unreliable, unordered data channels for low-latency state updates.
+
+Minimal usage pattern (as in `example/pong-network`)
+--------------------------------------------------
+
+- Server reads incoming TCP packets and handles simple single-message commands
+  (JSON frames in the example):
+
+.. code-block:: javascript
+
+  // In a server system: read incoming messages
+  const clientPackets = network.tcp.getReceivedPackets();
+  clientPackets.forEach((packets, clientId) => {
+    packets.forEach((packet) => {
+      const msg = JSON.parse(new TextDecoder().decode(packet));
+      if (msg.type === 'play') {
+        // register client and reply using network.tcp.sendToClient(...)
+      }
+    });
+  });
+
+- To broadcast authoritative state, the server can use `network.tcp.sendToEverybody`
+  or `network.tcp.sendToClient(clientId, data)`, and use the UDP-like data channels
+  (WebRTC) for fast, best-effort updates.
+
+Notes
+-----
+
+- See `docs/network/network-server-api.rst` for the exact list of server
+  functions available to your systems.
+- For packet framing and terminator semantics see:
+  `docs/network/packet-framing.rst`.

docs/network/network-server-api.rst

@@ -0,0 +1,49 @@
+Packet Framing — Magic Terminator
+================================
+
+This short note explains how packets are framed and reassembled in the
+network packages, at a logical level. The framing strategy is
+simple and robust to transport fragmentation or aggregation.
+
+Concept
+-------
+
+- Each logical packet is a payload of bytes that the application wants to
+  send (JSON or binary).
+- Before sending, the library *appends* a configurable terminator string
+  (the "magic value") to the end of the payload. The default value in the
+  project config is `PACKET_END`.
+- The terminator is applied as bytes (UTF-8 encoding of the configured
+  string) and therefore forms a unique byte suffix that marks the end of a
+  logical packet.
+
+Why an end terminator
+---------------------
+
+- Transports like WebSocket and RTC DataChannels may split or combine
+  application messages into arbitrary chunks. A terminator lets a receiver
+  reliably detect the end of each logical packet regardless of how the
+  transport fragments or aggregates bytes.
+- Using a short, human-readable terminator makes debugging easier.
+- The terminator is configurable so you can pick a value that does not
+  collide with your payload contents (especially important if using raw or
+  binary payloads).
+
+Sender logic
+---------------------------
+
+1. Serialize the application message into bytes (e.g., JSON => UTF-8
+   bytes, or a binary codec output).
+2. Append the configured terminator bytes to the end of the payload.
+3. Send the resulting buffer on the transport (WebSocket or DataChannel).
+
+Receiver logic
+-----------------------------
+
+1. Accumulate incoming chunks of bytes into a per-connection buffer.
+2. Repeatedly search the accumulated buffer for the terminator sequence.
+3. For each occurrence, extract bytes from buffer start up to (but not
+   including) the terminator — this is a complete logical packet.
+4. Remove the extracted packet and trailing terminator from the buffer and
+   continue searching; keep any leftover bytes (partial packet) for the
+   next incoming chunk.

docs/network/network-server.rst

@@ -159,9 +159,9 @@ namespace nfo {
          */
         Entity entity_from_index(const std::size_t entity_id)
         {
-            if (std::ranges::find(_dead_entities, id) != _dead_entities.end() || id >= _next_entity)
+            if (std::ranges::find(_dead_entities, entity_id) != _dead_entities.end() || entity_id >= _next_entity)
                 throw std::runtime_error("Entity index out of range.");
-            return Entity(id);
+            return Entity(entity_id);
         }
 
         /**