feat(packages/network): client and server for tcp/udp and networked pong as example

.github/ISSUE_TEMPLATE/01-packages_bug_report.yml

@@ -23,6 +23,8 @@ body:
         - graphics-2d
         - input
         - music
+        - network-client
+        - network-server
         - sound
     validations:
       required: true

.github/ISSUE_TEMPLATE/03-feature_request.yml

@@ -21,6 +21,8 @@ body:
         - graphics-2d
         - input
         - music
+        - network-client
+        - network-server
         - sound
         - eslint-config
         - prettier-config

.github/issue-labeler.yml

@@ -38,6 +38,14 @@ packages:music:
   - "### Which (package|utils|package or utils) is this (bug
     report|feature request) for\\?\\n\\nmusic\\n"
 
+packages:network-client:
+  - "### Which (package|utils|package or utils) is this (bug
+    report|feature request) for\\?\\n\\nnetwork-client\\n"
+
+packages:network-server:
+  - "### Which (package|utils|package or utils) is this (bug
+    report|feature request) for\\?\\n\\nnetwork-server\\n"
+
 packages:sound:
   - "### Which (package|utils|package or utils) is this (bug
     report|feature request) for\\?\\n\\nsound\\n"

.github/labeler.yml

@@ -58,6 +58,18 @@ packages:music:
           - packages/music/*
           - packages/music/**/*
 
+packages:network-client:
+  - changed-files:
+      - any-glob-to-any-file:
+          - packages/network-client/*
+          - packages/network-client/**/*
+
+packages:network-server:
+  - changed-files:
+      - any-glob-to-any-file:
+          - packages/network-server/*
+          - packages/network-server/**/*
+
 packages:sound:
   - changed-files:
       - any-glob-to-any-file:

.github/labels.yml

@@ -78,6 +78,14 @@
   description: "Related to Music library"
   color: "aaa3dc"
 
+- name: "packages:network-client"
+  description: "Related to NetworkClient library"
+  color: "aaa3dc"
+
+- name: "packages:network-server"
+  description: "Related to NetworkServer library"
+  color: "aaa3dc"
+
 - name: "packages:sound"
   description: "Related to Sound library"
   color: "aaa3dc"

LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright © 2025 NanoForge
+Copyright © 2026 NanoForge
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

README.md

@@ -1,55 +1,81 @@
-[![Nanoforge Documentation](https://github.com/NanoForge-dev/docs/actions/workflows/deploy.yml/badge.svg)](https://github.com/NanoForge-dev/docs/actions/workflows/deploy.yml)
-
-# Engine
-
-This repository contains the full engine for NanoForge.
-It can be used by itself.
+<div align="center">
+	<br />
+	<p>
+		<a href="https://github.com/NanoForge-dev"><img src="https://github.com/NanoForge-dev/Engine/blob/main/.github/logo.png" width="546" alt="NanoForge" /></a>
+	</p>
+	<br />
+	<p>
+		<a href="https://github.com/NanoForge-dev/Engine/actions"><img src="https://github.com/NanoForge-dev/Engine/actions/workflows/tests.yml/badge.svg" alt="Tests status" /></a>
+		<a href="https://github.com/NanoForge-dev/Engine/commits/main"><img src="https://img.shields.io/github/last-commit/NanoForge-dev/Engine.svg?logo=github&logoColor=ffffff" alt="Last commit." /></a>
+		<a href="https://github.com/NanoForge-dev/Engine/graphs/contributors"><img src="https://img.shields.io/github/contributors/NanoForge-dev/Engine.svg?maxAge=3600&logo=github&logoColor=fff&color=00c7be" alt="contributors" /></a>
+	</p>
+</div>
 
-The engine is made of multiple components:
-
-- [ecs-client](packages/ecs-client)
-- [ecs-server](packages/ecs-server)
-- [ecs-lib](packages/ecs-lib)
-- [input](packages/input)
-- [core](packages/core)
-- [common](packages/common)
-- [graphics-2d](packages/graphics-2d)
-- [asset-manager](packages/asset-manager)
-- [sound](packages/sound)
-- [music](packages/music)
+[![Nanoforge Documentation](https://github.com/NanoForge-dev/docs/actions/workflows/deploy.yml/badge.svg)](https://github.com/NanoForge-dev/docs/actions/workflows/deploy.yml)
 
-This is the full nanoforge engine including all the default libraries.
+## About
 
-In order to manage this project we use (pnpm)[https://pnpm.io/]
+This repository contains multiple packages with separate [releases][github-releases]. Nanoforge is a powerful game engine for web browser.
 
 ## Documentation
 
 The full documentation can be found at: [https://nanoforge-dev.github.io/docs/engine](https://nanoforge-dev.github.io/docs/engine)
 
-## Installing dependencies
+## Usage
 
-To install dependencies run:
+To use Nanoforge Engine, please refer to the [CLI documentation][cli-source] !
 
-```sh
-pnpm i
-```
-
-## Building
-
-To build the project run:
+First, install the CLI :
 
-```sh
-pnpm build
+```bash
+npm install -g @nanoforge-dev/cli
 ```
 
-## Tests
+And then create a new project :
 
-To run tests use:
-
-```sh
-pnpm test
+```bash
+nf new
 ```
 
-## Setting up a test project
-
-In order to setup a test project see (this)[https://github.com/NanoForge-dev/Engine/docs/Introduction.md]
+## Packages
+
+- `@nanoforge-dev/common` ([source][common-source]) - Common interfaces and utilities used by Nanoforge Engine
+- `@nanoforge-dev/core` ([source][core-source]) - A core package that contains game main loop
+- `@nanoforge-dev/ecs-lib` ([source][ecs-lib-source]) - A powerful data structure for managing game entities (_do not use this in your projects_)
+- `@nanoforge-dev/ecs-client` ([source][ecs-client-source]) - A wrapper of `@nanoforge-dev/ecs-lib` for client-side usage
+- `@nanoforge-dev/ecs-server` ([source][ecs-server-source]) - A wrapper of `@nanoforge-dev/ecs-lib` for server-side usage
+- `@nanoforge-dev/config` ([source][config-source]) - A wrapper of `class-validator` and `class-transformer` to imports validation and transformation decorators
+- `@nanoforge-dev/graphics-2d` ([source][graphics-2d-source]) - A base 2D graphics library
+- `@nanoforge-dev/asset-manager` ([source][asset-manager-source]) - A manager for loading assets to uniform workwith between client and server
+- `@nanoforge-dev/network-client` ([source][network-client-source]) - A network lib with tcp and udp support for client-side usage
+- `@nanoforge-dev/network-server` ([source][network-server-source]) - A network lib with tcp and udp support for server-side usage
+- `@nanoforge-dev/input` ([source][input-source]) - An input manager for handling keyboard and mouse events
+- `@nanoforge-dev/music` ([source][music-source]) - A music player for your game
+- `@nanoforge-dev/sound` ([source][sound-source]) - A sound manager for your game
+
+## Contributing
+
+Please read through our [contribution guidelines][contributing] before starting a pull request. We welcome contributions of all kinds, not just code! If you're stuck for ideas, look for the [good first issue][good-first-issue] label on issues in the repository. If you have any questions about the project, feel free to ask them on [Discussions][discussions]. Before creating your own issue or pull request, always check to see if one already exists! Don't rush contributions, take your time and ensure you're doing it correctly.
+
+## Help
+
+If you don't understand something in the documentation, you are experiencing problems, or you just need a gentle nudge in the right direction, please ask on [Discussions][discussions].
+
+[contributing]: https://github.com/NanoForge-dev/Engine/blob/main/.github/CONTRIBUTING.md
+[discussions]: https://github.com/NanoForge-dev/Engine/discussions
+[cli-source]: https://github.com/NanoForge-dev/CLI
+[github-releases]: https://github.com/NanoForge-dev/Engine/releases
+[asset-manager-source]: https://github.com/NanoForge-dev/Engine/tree/main/packages/asset-manager
+[common-source]: https://github.com/NanoForge-dev/Engine/tree/main/packages/common
+[config-source]: https://github.com/NanoForge-dev/Engine/tree/main/packages/config
+[core-source]: https://github.com/NanoForge-dev/Engine/tree/main/packages/core
+[ecs-client-source]: https://github.com/NanoForge-dev/Engine/tree/main/packages/ecs-client
+[ecs-lib-source]: https://github.com/NanoForge-dev/Engine/tree/main/packages/ecs-lib
+[ecs-server-source]: https://github.com/NanoForge-dev/Engine/tree/main/packages/ecs-server
+[graphics-2d-source]: https://github.com/NanoForge-dev/Engine/tree/main/packages/graphics-2d
+[input-source]: https://github.com/NanoForge-dev/Engine/tree/main/packages/input
+[music-source]: https://github.com/NanoForge-dev/Engine/tree/main/packages/music
+[network-client-source]: https://github.com/NanoForge-dev/Engine/tree/main/packages/network-client
+[network-server-source]: https://github.com/NanoForge-dev/Engine/tree/main/packages/network-server
+[sound-source]: https://github.com/NanoForge-dev/Engine/tree/main/packages/sound
+[good-first-issue]: https://github.com/NanoForge-dev/Engine/contribute

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.

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