chore(engine): updating docs

Author: github-actions[bot]

engine/docs/.gitignore

@@ -0,0 +1 @@
+Doxyfile

engine/docs/documentation.rst

@@ -0,0 +1,7 @@
+Documentation
+=============
+
+The documentation for the engine is seperated between the different libraries of the engine.
+Then everything is packed up and put into this site. The documentation is handled on the engine repository and then automatically pushed.
+
+This documentation is written in restructured text in order for it to be easier to operate with. We use sphinx to generate the relevant generated documentation.

engine/docs/how_to_use.rst

@@ -0,0 +1,20 @@
+Introduction to using the Engine
+================================
+
+Whether you work on this engine as a devlopper or you wanna use this
+engine you gonna want to have a test project. This is a walkthrough on
+how to setup a basic project
+
+As a devlopper on the engine
+----------------------------
+
+As a devlopper you want to be able to use your changes in your project.
+Therefore it is recommended to use the provided `cli <https://github.com/NanoForge-dev/CLI>`__
+
+As a user
+---------
+
+As a user you can either use the template and change the dependencies
+location. Or you can create a project and add the nanoforge
+dependencies. Note that it is recommended to use bun as a package
+manager.

engine/docs/index.rst

@@ -0,0 +1,12 @@
+Engine
+======
+
+.. toctree::
+    :maxdepth: 2
+
+    registry
+    documentation.rst
+    how_to_use.rst
+
+In this doc you will find both the how to use and why use this engine as well as its library.
+To understand how to use this engine please refer to :doc:`/how_to_use`

engine/docs/network/index.rst

@@ -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.

engine/docs/network/network-client-api.rst

@@ -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.
+

engine/docs/network/network-client.rst

@@ -0,0 +1,58 @@
+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.
+
+Example
+--------------------------------------------------
+
+It works exactly the same with UDP
+
+.. code-block:: javascript
+
+  // Wait for connection to be established
+  async function waitForConnection(): Promise<void> {
+    if (network.tcp?.isConnected()) return;
+
+    return new Promise((resolve) => {
+      const check = () => {
+        if (network.tcp.isConnected()) {
+          resolve();
+        } else {
+          setTimeout(check, 50);
+        }
+      };
+      check();
+    });
+  }
+  await waitForConnection();
+
+  // Send a json encoded packet
+  network.tcp.sendData(new TextEncoder().encode(JSON.stringify({ hello: 'world' })));
+
+  // Receive raw server packets
+  const latestsPackets = getReceivedPackets();
+
+  // Decode packets if encoded in json
+  const decodedPackets = latestsPackets.map((packet) => {
+    return JSON.parse(new TextDecoder().decode(packet));
+  });
+
+Notes
+-----
+
+- See `docs/network/network-client-api.rst` for the exact list available functions.
+- For packet framing/terminator semantics see `docs/network/packet-framing.rst`.

engine/docs/network/network-server-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.

engine/docs/network/network-server.rst

@@ -0,0 +1,49 @@
+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.
+
+Example
+--------------------------------------------------
+
+It works exactly the same with UDP
+
+.. code-block:: javascript
+  // Send everybody a json encoded packet
+  network.tcp.sendToEverybody(
+    new TextEncoder().encode(JSON.stringify(
+      { type: "are you here" }
+    ))
+  );
+
+  // Check connected clients
+  const connectedClients = getConnectedClients();
+
+  // Receive all packets
+  const allPackets = network.tcp.getReceivedPackets();
+
+  // Get first client packets
+  const firstClientPackets = map.get(connectedClients[0]);
+
+  // Decode packets if encoded in json
+  const decodedPackets = firstClientPackets.map((packet) => {
+    return JSON.parse(new TextDecoder().decode(packet));
+  });
+
+Notes
+-----
+
+- See `docs/network/network-server-api.rst` for the exact list available functions.
+- For packet framing and terminator semantics see `docs/network/packet-framing.rst`.

engine/docs/network/packet-framing.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.