multiplayerlib 0.0.1__tar.gz

multiplayerlib-0.0.1/LICENSE

@@ -0,0 +1,25 @@
+MIT License
+
+Copyright (c) 2026 griffingreat1
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of the MultiplayerLib software and associated documentation files (the “Software”), 
+to deal in the Software without restriction, including without limitation the rights 
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of 
+the Software, and to permit persons to whom the Software is furnished to do so, 
+subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all 
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, 
+INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A 
+PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT 
+HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF 
+CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE 
+OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+
+---
+
+Note: This license applies **only to the MultiplayerLib library**.  
+The included demo game code is **not covered by this license** and can be used, modified, or distributed freely.

multiplayerlib-0.0.1/PKG-INFO

@@ -0,0 +1,257 @@
+Metadata-Version: 2.4
+Name: multiplayerlib
+Version: 0.0.1
+Summary: MultiplayerLib - A lightweight Python multiplayer networking library
+Author: griffingreat1
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: cryptography==50.0.1
+Requires-Dist: orjson==3.12.0
+Dynamic: license-file
+
+# MultiplayerLib
+
+MultiplayerLib is a lightweight UDP networking library designed for simple real-time multiplayer games. It provides a minimal, easy-to-integrate API for fast client-server communication with optional compression and encryption.
+
+---
+
+## Table of Contents
+- [Features](#-features)
+- [Installation](#-installation)
+- [Quick Start](#quick-start-example)
+- [Architecture Overview](#architecture-overview)
+- [API Reference](#api-reference)
+- [Packet Examples](#packet-examples-and-typical-usage-in-a-game)
+- [Troubleshooting](#troubleshooting--tips)
+- [Security Notes](#security-notes)
+- [Contributing](#contributing)
+
+---
+
+## ✨ Features
+
+- 🚀 UDP networking for low-latency gameplay
+- 👥 Multi-client server support
+- 🔄 Real-time state synchronization
+- 🗜️ Optional packet compression using zlib
+- 🔐 Optional encryption using Fernet (AES) + PBKDF2 key derivation
+- 📦 JSON-based packet formatting (human readable)
+- 🧵 Background threaded receive loop
+- 🛡️ Safe send/receive queue system
+- 🔧 Minimal API surface: `NetworkManager`, `EncryptionManager`
+
+---
+
+## 📦 Installation
+
+run the install command to install the package
+
+```pip install multiplayerlib
+```
+
+---
+
+## Quick Start Example
+
+### Host (Server)
+
+```py
+mgr = NetworkManager(
+    is_host=True,
+    base_port=5000,
+    use_compression=True,
+    use_encryption=False
+)
+mgr.start()
+```
+
+### Client
+
+```py
+mgr = NetworkManager(
+    is_host=False,
+    peer_ip="1.2.3.4",
+    base_port=5000,
+    use_compression=True,
+    use_encryption=False
+)
+mgr.start()
+```
+
+### Sending / Receiving
+
+```py
+mgr.safe_send({
+    "type": "playerdata",
+    "position": {"x": 10, "y": 20, "rotation": 0},
+    "health": 100
+})
+
+msg = mgr.safe_receive()
+if msg:
+    # handle decoded packet
+    pass
+```
+
+---
+
+## Architecture Overview
+
+- The system follows a **client-server UDP model**:
+  - One host acts as the server
+  - Multiple clients can connect and send packets
+- The server broadcasts received packets to all connected clients
+- Each client sends state updates to the server
+
+### Networking Flow
+
+1. Client sends packet → Server receives
+2. Server updates peer registry (heartbeats)
+3. Server broadcasts packet to all other clients
+4. Clients receive and process updates via `incoming_queue`
+
+### Design Notes
+
+- UDP is used for low latency (no built-in reliability)
+- Packet delivery is not guaranteed
+- Ordering is not enforced
+- Designed for frequent state updates (position, actions, etc.)
+
+---
+
+## API Reference
+
+### NetworkManager
+
+#### Constructor
+```py
+NetworkManager(
+    is_host=True,
+    peer_ip=None,
+    base_port=5000,
+    use_compression=True,
+    use_encryption=False,
+    encryption_key=DEFAULT_KEY,
+    encryption_salt=DEFAULT_SALT
+)
+```
+
+#### Methods
+
+- `start()`
+  Starts background receive and peer cleanup threads.
+
+- `safe_send(data: dict)`
+  Sends a packet to all connected peers (server) or to the host (client).
+
+- `safe_receive() -> dict | None`
+  Non-blocking receive from internal queue.
+
+- `close()`
+  Stops networking and closes socket.
+
+---
+
+### Packet Pipeline
+
+Outgoing:
+```
+dict → JSON → compress (optional) → encrypt (optional) → UDP packet
+```
+
+Incoming:
+```
+UDP packet → decrypt → decompress → JSON decode → dict
+```
+
+---
+
+### EncryptionManager
+
+- Uses PBKDF2-derived key + Fernet encryption
+- Requires identical key/salt on both sides
+- Encrypt/decrypt operates on bytes
+
+---
+
+## Packet Examples
+
+Common patterns used in games:
+
+### Player State
+```json
+{
+  "type": "playerdata",
+  "position": {
+    "x": 640,
+    "y": 360,
+    "rotation": 1.57
+  },
+  "health": 100
+}
+```
+
+### Action Event
+```json
+{
+  "type": "shoot",
+  "pos": [x, y],
+  "vec": [vx, vy],
+  "timestamp": 1234567890.0
+}
+```
+
+### Disconnect
+```json
+{
+  "type": "quit"
+}
+```
+
+---
+
+## Important Constants
+
+Defined in `NetworkConstants.py`:
+
+- `BUFFER_SIZE = 4096`
+- `DEFAULT_PORT = 5000`
+- `POSITIONUPDATEINTERVAL = 1/30`
+- `DEFAULT_KEY`, `DEFAULT_SALT`
+
+---
+
+## Troubleshooting & Tips
+
+- If bind fails, ensure the port is not in use
+- If packets are missing, remember UDP does not guarantee delivery
+- If encryption fails, ensure:
+  - same key
+  - same salt
+  - same `use_encryption` setting
+- Keep packets small (UDP safe size ~1–1.5KB recommended)
+
+---
+
+## Security Notes
+
+- Default keys are for development only
+- Always generate secure keys for real applications
+- Treat UDP as **insecure transport unless encrypted**
+
+---
+
+## Contributing
+
+Contributions welcome:
+- new packet utilities
+- performance improvements
+- reliability features (ordering, ack system)
+- better debugging/logging tools
+
+---
+
+## License
+
+MIT License — see [LICENSE](../LICENSE)

multiplayerlib-0.0.1/README.md

@@ -0,0 +1,245 @@
+# MultiplayerLib
+
+MultiplayerLib is a lightweight UDP networking library designed for simple real-time multiplayer games. It provides a minimal, easy-to-integrate API for fast client-server communication with optional compression and encryption.
+
+---
+
+## Table of Contents
+- [Features](#-features)
+- [Installation](#-installation)
+- [Quick Start](#quick-start-example)
+- [Architecture Overview](#architecture-overview)
+- [API Reference](#api-reference)
+- [Packet Examples](#packet-examples-and-typical-usage-in-a-game)
+- [Troubleshooting](#troubleshooting--tips)
+- [Security Notes](#security-notes)
+- [Contributing](#contributing)
+
+---
+
+## ✨ Features
+
+- 🚀 UDP networking for low-latency gameplay
+- 👥 Multi-client server support
+- 🔄 Real-time state synchronization
+- 🗜️ Optional packet compression using zlib
+- 🔐 Optional encryption using Fernet (AES) + PBKDF2 key derivation
+- 📦 JSON-based packet formatting (human readable)
+- 🧵 Background threaded receive loop
+- 🛡️ Safe send/receive queue system
+- 🔧 Minimal API surface: `NetworkManager`, `EncryptionManager`
+
+---
+
+## 📦 Installation
+
+run the install command to install the package
+
+```pip install multiplayerlib
+```
+
+---
+
+## Quick Start Example
+
+### Host (Server)
+
+```py
+mgr = NetworkManager(
+    is_host=True,
+    base_port=5000,
+    use_compression=True,
+    use_encryption=False
+)
+mgr.start()
+```
+
+### Client
+
+```py
+mgr = NetworkManager(
+    is_host=False,
+    peer_ip="1.2.3.4",
+    base_port=5000,
+    use_compression=True,
+    use_encryption=False
+)
+mgr.start()
+```
+
+### Sending / Receiving
+
+```py
+mgr.safe_send({
+    "type": "playerdata",
+    "position": {"x": 10, "y": 20, "rotation": 0},
+    "health": 100
+})
+
+msg = mgr.safe_receive()
+if msg:
+    # handle decoded packet
+    pass
+```
+
+---
+
+## Architecture Overview
+
+- The system follows a **client-server UDP model**:
+  - One host acts as the server
+  - Multiple clients can connect and send packets
+- The server broadcasts received packets to all connected clients
+- Each client sends state updates to the server
+
+### Networking Flow
+
+1. Client sends packet → Server receives
+2. Server updates peer registry (heartbeats)
+3. Server broadcasts packet to all other clients
+4. Clients receive and process updates via `incoming_queue`
+
+### Design Notes
+
+- UDP is used for low latency (no built-in reliability)
+- Packet delivery is not guaranteed
+- Ordering is not enforced
+- Designed for frequent state updates (position, actions, etc.)
+
+---
+
+## API Reference
+
+### NetworkManager
+
+#### Constructor
+```py
+NetworkManager(
+    is_host=True,
+    peer_ip=None,
+    base_port=5000,
+    use_compression=True,
+    use_encryption=False,
+    encryption_key=DEFAULT_KEY,
+    encryption_salt=DEFAULT_SALT
+)
+```
+
+#### Methods
+
+- `start()`
+  Starts background receive and peer cleanup threads.
+
+- `safe_send(data: dict)`
+  Sends a packet to all connected peers (server) or to the host (client).
+
+- `safe_receive() -> dict | None`
+  Non-blocking receive from internal queue.
+
+- `close()`
+  Stops networking and closes socket.
+
+---
+
+### Packet Pipeline
+
+Outgoing:
+```
+dict → JSON → compress (optional) → encrypt (optional) → UDP packet
+```
+
+Incoming:
+```
+UDP packet → decrypt → decompress → JSON decode → dict
+```
+
+---
+
+### EncryptionManager
+
+- Uses PBKDF2-derived key + Fernet encryption
+- Requires identical key/salt on both sides
+- Encrypt/decrypt operates on bytes
+
+---
+
+## Packet Examples
+
+Common patterns used in games:
+
+### Player State
+```json
+{
+  "type": "playerdata",
+  "position": {
+    "x": 640,
+    "y": 360,
+    "rotation": 1.57
+  },
+  "health": 100
+}
+```
+
+### Action Event
+```json
+{
+  "type": "shoot",
+  "pos": [x, y],
+  "vec": [vx, vy],
+  "timestamp": 1234567890.0
+}
+```
+
+### Disconnect
+```json
+{
+  "type": "quit"
+}
+```
+
+---
+
+## Important Constants
+
+Defined in `NetworkConstants.py`:
+
+- `BUFFER_SIZE = 4096`
+- `DEFAULT_PORT = 5000`
+- `POSITIONUPDATEINTERVAL = 1/30`
+- `DEFAULT_KEY`, `DEFAULT_SALT`
+
+---
+
+## Troubleshooting & Tips
+
+- If bind fails, ensure the port is not in use
+- If packets are missing, remember UDP does not guarantee delivery
+- If encryption fails, ensure:
+  - same key
+  - same salt
+  - same `use_encryption` setting
+- Keep packets small (UDP safe size ~1–1.5KB recommended)
+
+---
+
+## Security Notes
+
+- Default keys are for development only
+- Always generate secure keys for real applications
+- Treat UDP as **insecure transport unless encrypted**
+
+---
+
+## Contributing
+
+Contributions welcome:
+- new packet utilities
+- performance improvements
+- reliability features (ordering, ack system)
+- better debugging/logging tools
+
+---
+
+## License
+
+MIT License — see [LICENSE](../LICENSE)

multiplayerlib-0.0.1/pyproject.toml

@@ -0,0 +1,17 @@
+[project]
+name = "multiplayerlib"
+version = "0.0.1"
+description = "MultiplayerLib - A lightweight Python multiplayer networking library"
+requires-python = ">=3.10"
+dependencies = [
+    "cryptography==50.0.1",
+    "orjson==3.12.0",
+]
+readme = "README.md"
+authors = [
+  {name="griffingreat1"},
+]
+
+[build-system]
+requires = ["setuptools>=61.0"]
+build-backend = "setuptools.build_meta"

multiplayerlib-0.0.1/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

multiplayerlib-0.0.1/src/multiplayerlib/EncryptionManager.py

@@ -0,0 +1,27 @@
+# this file is part of MultiplayerLib, which is under an MIT license.
+# see LICENSE file at root of this repository for details.
+
+from multiplayerlib.NetworkConstants import *
+from cryptography.fernet import Fernet
+from cryptography.hazmat.primitives import hashes
+from cryptography.hazmat.primitives.kdf.pbkdf2 import PBKDF2HMAC
+import base64
+import sys
+import zlib
+
+class EncryptionManager:
+    def __init__(self,key,salt):
+        kdf = PBKDF2HMAC(
+            algorithm=hashes.SHA256(),
+            length=32,
+            salt=salt.to_bytes(16,sys.byteorder),
+            iterations=1_000_000,
+        )
+        self.key = base64.urlsafe_b64encode(kdf.derive(key))
+        self.encrypter = Fernet(self.key)
+    
+    def encrypt(self,bytesObject):
+        return self.encrypter.encrypt(bytesObject)
+
+    def decrypt(self,bytesObject):
+        return self.encrypter.decrypt(bytesObject)

multiplayerlib-0.0.1/src/multiplayerlib/NetworkConstants.py

@@ -0,0 +1,9 @@
+# this file is part of MultiplayerLib, which is under an MIT license.
+# see LICENSE file at root of this repository for details.
+
+BUFFER_SIZE = 1024
+DEFAULT_PORT = 5000
+
+DEFAULT_KEY = "encryptionKeyForFernetEncryption"
+DEFAULT_SALT = 2815
+PEER_TIMEOUT = 5

multiplayerlib-0.0.1/src/multiplayerlib/NetworkLib.py

@@ -0,0 +1,234 @@
+# this file is part of MultiplayerLib, which is under an MIT license.
+# see LICENSE file at root of this repository for details.
+
+"""
+Network utilities and a NetworkManager for peer-to-peer UDP communication.
+
+Provides helpers for encoding/decoding messages, optional compression and
+encryption, and a simple API for sending/receiving JSON-serializable packets.
+"""
+
+import random
+
+import orjson
+import socket
+import threading
+import time
+from multiplayerlib.NetworkConstants import *
+from multiplayerlib.EncryptionManager import EncryptionManager
+import zlib
+from queue import Queue
+
+class Peer():
+    registry = {}
+    registry_lock = threading.Lock()
+    def __init__(self,address):
+        self.address = address
+        self.latestPacketTime = time.time()
+    
+    def heartbeat(self):
+        self.latestPacketTime = time.time()
+    
+    def get_is_alive(self):
+        return time.time()-self.latestPacketTime < PEER_TIMEOUT
+    
+    def get_address(self):
+        return self.address
+
+    @classmethod
+    def getInstance(cls, value):
+        with cls.registry_lock:
+            instance = cls.registry.get(value)
+            if instance is None:
+                instance = cls(value)
+                cls.registry[value] = instance
+            return instance
+
+    @classmethod
+    def update_registry(cls):
+        with cls.registry_lock:
+            cls.registry = {
+                address: instance
+                for address, instance in cls.registry.items()
+                if instance.get_is_alive()
+            }
+
+class NetworkManager:
+    """
+    High-level manager for UDP networking.
+
+    Handles socket setup, optional compression and encryption of packets, and
+    provides a background receiving loop to accumulate incoming messages.
+    """
+    def __init__(self, is_host=True, peer_ip=None, base_port=DEFAULT_PORT, use_compression=False, use_encryption=False, encryption_key=DEFAULT_KEY, encryption_salt=DEFAULT_SALT) -> None:
+        """
+        Network Manager
+        
+        :param is_host: host server or connect to server
+        :param peer_ip: ip address of peer (only required if client is NOT the server host)
+        :param base_port: the base port for the server. server hosts recv on this port and client hosts recv on base_port + 1. client sends to base_port and server sends to base_port + 1
+        :param use_compression: if true, packets will be compressed. this allows for reduced size of packets. defaults to true. (most UDP packets should be small enough that this isnt needed)
+        :param use_encryption: if true, packets will be encrypted before sending.
+        """
+        if use_encryption:
+            self.encryptionManager = EncryptionManager(encryption_key.encode(),encryption_salt)
+            originalMessage = getSamplePacketString()
+            encryptedTestMessage = self.encryptionManager.encrypt(zlib.compress(orjson.dumps(getSamplePacketString())))
+            decryptedTestMessage = orjson.loads(zlib.decompress(self.encryptionManager.decrypt(encryptedTestMessage)))
+            print(f"encryption is working: {originalMessage==decryptedTestMessage}")
+
+        self.compress_packets = use_compression
+        self.use_encryption = use_encryption
+
+        self.is_host = is_host
+        self.peer_ip = peer_ip
+        
+        self.local_port = base_port if is_host else base_port + random.randint(1,10)
+        self.peer_port = base_port + 1 if is_host else base_port
+
+        self.peer_addr = None if is_host else (peer_ip,self.peer_port)
+
+        self.sock = socket.socket(socket.AF_INET, socket.SOCK_DGRAM)
+        self.sock.setsockopt(socket.SOL_SOCKET, socket.SO_REUSEADDR, 1)
+        self.sock.setsockopt(socket.SOL_SOCKET, socket.SO_RCVBUF, 32768)
+        self.sock.setsockopt(socket.SOL_SOCKET, socket.SO_SNDBUF, 32768)
+        self.sock.setsockopt(socket.IPPROTO_IP, socket.IP_TOS, 0x10)
+        self.sock.settimeout(0.5)
+
+        try:
+            self.sock.bind(("",self.local_port))
+            print(f"Socket bound to {socket.gethostbyname(socket.gethostname())}:{self.local_port}")
+        except OSError as e:
+            print(f"Socket bind failed on port {self.local_port}: {e}")
+        
+        self.running = False
+        self.incoming_queue = Queue()
+    
+    def start(self) -> None:
+        """
+        Start the receiver loop in a background thread.
+        """
+        self.running = True
+        threading.Thread(
+            target=self.recv_loop, 
+            daemon=True
+        ).start()
+
+        threading.Thread(
+            target=self.peer_cleanup_loop,
+            daemon=True
+        ).start()
+
+    def peer_cleanup_loop(self):
+        """
+        Periodically remove timed-out peers.
+        """
+        while self.running:
+            Peer.update_registry()
+            time.sleep(1)
+
+    def recv_loop(self) -> None:
+        """
+        Continuously receive packets and decode them into the incoming queue.
+        """
+        while self.running:
+            try:
+                data,addr = self.sock.recvfrom(BUFFER_SIZE)
+                if self.is_host:
+                    peer = Peer.getInstance(addr)
+                    peer.heartbeat()
+                    with Peer.registry_lock:
+                        peers = list(Peer.registry.items())
+
+                    for address, peer in peers:
+                        if address != addr:
+                            self.sock.sendto(data, address)
+                try:
+                    msg = self.decode_message(data)
+                    self.incoming_queue.put(msg)
+                except Exception:
+                    pass
+            except Exception:
+                time.sleep(0.01)
+
+    def safe_receive(self) -> dict | None:
+        """
+        Retrieve the next parsed packet from the incoming queue in a non-blocking way.
+        """
+        try:
+            return self.incoming_queue.get_nowait()
+        except:
+            return None
+    
+    def decode_message(self, message_encoded: bytes) -> dict:
+        """
+        Decode a raw packet into a Python object.
+        """
+        if self.use_encryption:
+            message_encoded = self.encryptionManager.decrypt(message_encoded)
+        if self.compress_packets:
+            message_encoded = zlib.decompress(message_encoded)
+        message = orjson.loads(message_encoded)
+        return message
+
+    def prepare_message(self, data: dict) -> bytes:
+        """
+        Prepare a Python object for sending over the network.
+        """
+        message_encoded = orjson.dumps(data)
+        if self.compress_packets:
+            message_encoded = zlib.compress(message_encoded)
+        if self.use_encryption:
+            message_encoded = self.encryptionManager.encrypt(message_encoded)
+        return message_encoded
+
+    def safe_send(self, data: dict) -> None:
+        """
+        Send a data packet to the currently known peer address.
+        """
+        if self.is_host:
+            with Peer.registry_lock:
+                peers = list(Peer.registry.items())
+
+            for address, peer in peers:
+                try:
+                    self.sock.sendto(self.prepare_message(data), address)
+                except Exception as e:
+                    print(e)
+        else:
+            if self.peer_addr:
+                try:
+                    self.sock.sendto(self.prepare_message(data), self.peer_addr)
+                except Exception as e:
+                    print(e)
+
+    def close(self) -> None:
+        """
+        Stop the receive loop and close the underlying socket.
+        """
+        self.running = False
+        try:
+            self.sock.close()
+        except Exception:
+            pass
+
+
+def getSamplePacketString() -> dict:
+    """
+    Returns a basic example of a packet in a dictionary structure.
+    """
+    data = {
+        "type":"playerdata",
+        "packetNum":random.randint(0,100),
+        "position":{
+            "x":random.randint(0,600),
+            "y":random.randint(0,600),
+            "rotation":random.uniform(0,6.28)
+        },
+        "velocity":[random.randint(0,5),random.randint(0,5)],
+        "health":random.randint(0,100),
+        "timestamp":time.time(),
+        "deaths":random.randint(0,100),
+        "ID":random.randint(0,1000)
+    }
+    return data

multiplayerlib-0.0.1/src/multiplayerlib/__init__.py

@@ -0,0 +1,15 @@
+# this file is part of MultiplayerLib, which is under an MIT license.
+# see LICENSE file at root of this repository for details.
+
+"""
+:MultiplayerLib:\n
+Multiplayerlib is a library designed to allow for easy creation of multiplayer games with any game
+module. It is currently limited to only 2 player games where one player is the host and one player
+connects, although there are plans for adding support for more than just 1v1 games.
+"""
+from multiplayerlib.NetworkLib import *
+from multiplayerlib.NetworkConstants import *
+
+def help():
+    print("example packet:")
+    getSamplePacketString()

multiplayerlib-0.0.1/src/multiplayerlib.egg-info/PKG-INFO

@@ -0,0 +1,257 @@
+Metadata-Version: 2.4
+Name: multiplayerlib
+Version: 0.0.1
+Summary: MultiplayerLib - A lightweight Python multiplayer networking library
+Author: griffingreat1
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: cryptography==50.0.1
+Requires-Dist: orjson==3.12.0
+Dynamic: license-file
+
+# MultiplayerLib
+
+MultiplayerLib is a lightweight UDP networking library designed for simple real-time multiplayer games. It provides a minimal, easy-to-integrate API for fast client-server communication with optional compression and encryption.
+
+---
+
+## Table of Contents
+- [Features](#-features)
+- [Installation](#-installation)
+- [Quick Start](#quick-start-example)
+- [Architecture Overview](#architecture-overview)
+- [API Reference](#api-reference)
+- [Packet Examples](#packet-examples-and-typical-usage-in-a-game)
+- [Troubleshooting](#troubleshooting--tips)
+- [Security Notes](#security-notes)
+- [Contributing](#contributing)
+
+---
+
+## ✨ Features
+
+- 🚀 UDP networking for low-latency gameplay
+- 👥 Multi-client server support
+- 🔄 Real-time state synchronization
+- 🗜️ Optional packet compression using zlib
+- 🔐 Optional encryption using Fernet (AES) + PBKDF2 key derivation
+- 📦 JSON-based packet formatting (human readable)
+- 🧵 Background threaded receive loop
+- 🛡️ Safe send/receive queue system
+- 🔧 Minimal API surface: `NetworkManager`, `EncryptionManager`
+
+---
+
+## 📦 Installation
+
+run the install command to install the package
+
+```pip install multiplayerlib
+```
+
+---
+
+## Quick Start Example
+
+### Host (Server)
+
+```py
+mgr = NetworkManager(
+    is_host=True,
+    base_port=5000,
+    use_compression=True,
+    use_encryption=False
+)
+mgr.start()
+```
+
+### Client
+
+```py
+mgr = NetworkManager(
+    is_host=False,
+    peer_ip="1.2.3.4",
+    base_port=5000,
+    use_compression=True,
+    use_encryption=False
+)
+mgr.start()
+```
+
+### Sending / Receiving
+
+```py
+mgr.safe_send({
+    "type": "playerdata",
+    "position": {"x": 10, "y": 20, "rotation": 0},
+    "health": 100
+})
+
+msg = mgr.safe_receive()
+if msg:
+    # handle decoded packet
+    pass
+```
+
+---
+
+## Architecture Overview
+
+- The system follows a **client-server UDP model**:
+  - One host acts as the server
+  - Multiple clients can connect and send packets
+- The server broadcasts received packets to all connected clients
+- Each client sends state updates to the server
+
+### Networking Flow
+
+1. Client sends packet → Server receives
+2. Server updates peer registry (heartbeats)
+3. Server broadcasts packet to all other clients
+4. Clients receive and process updates via `incoming_queue`
+
+### Design Notes
+
+- UDP is used for low latency (no built-in reliability)
+- Packet delivery is not guaranteed
+- Ordering is not enforced
+- Designed for frequent state updates (position, actions, etc.)
+
+---
+
+## API Reference
+
+### NetworkManager
+
+#### Constructor
+```py
+NetworkManager(
+    is_host=True,
+    peer_ip=None,
+    base_port=5000,
+    use_compression=True,
+    use_encryption=False,
+    encryption_key=DEFAULT_KEY,
+    encryption_salt=DEFAULT_SALT
+)
+```
+
+#### Methods
+
+- `start()`
+  Starts background receive and peer cleanup threads.
+
+- `safe_send(data: dict)`
+  Sends a packet to all connected peers (server) or to the host (client).
+
+- `safe_receive() -> dict | None`
+  Non-blocking receive from internal queue.
+
+- `close()`
+  Stops networking and closes socket.
+
+---
+
+### Packet Pipeline
+
+Outgoing:
+```
+dict → JSON → compress (optional) → encrypt (optional) → UDP packet
+```
+
+Incoming:
+```
+UDP packet → decrypt → decompress → JSON decode → dict
+```
+
+---
+
+### EncryptionManager
+
+- Uses PBKDF2-derived key + Fernet encryption
+- Requires identical key/salt on both sides
+- Encrypt/decrypt operates on bytes
+
+---
+
+## Packet Examples
+
+Common patterns used in games:
+
+### Player State
+```json
+{
+  "type": "playerdata",
+  "position": {
+    "x": 640,
+    "y": 360,
+    "rotation": 1.57
+  },
+  "health": 100
+}
+```
+
+### Action Event
+```json
+{
+  "type": "shoot",
+  "pos": [x, y],
+  "vec": [vx, vy],
+  "timestamp": 1234567890.0
+}
+```
+
+### Disconnect
+```json
+{
+  "type": "quit"
+}
+```
+
+---
+
+## Important Constants
+
+Defined in `NetworkConstants.py`:
+
+- `BUFFER_SIZE = 4096`
+- `DEFAULT_PORT = 5000`
+- `POSITIONUPDATEINTERVAL = 1/30`
+- `DEFAULT_KEY`, `DEFAULT_SALT`
+
+---
+
+## Troubleshooting & Tips
+
+- If bind fails, ensure the port is not in use
+- If packets are missing, remember UDP does not guarantee delivery
+- If encryption fails, ensure:
+  - same key
+  - same salt
+  - same `use_encryption` setting
+- Keep packets small (UDP safe size ~1–1.5KB recommended)
+
+---
+
+## Security Notes
+
+- Default keys are for development only
+- Always generate secure keys for real applications
+- Treat UDP as **insecure transport unless encrypted**
+
+---
+
+## Contributing
+
+Contributions welcome:
+- new packet utilities
+- performance improvements
+- reliability features (ordering, ack system)
+- better debugging/logging tools
+
+---
+
+## License
+
+MIT License — see [LICENSE](../LICENSE)

multiplayerlib-0.0.1/src/multiplayerlib.egg-info/SOURCES.txt

@@ -0,0 +1,12 @@
+LICENSE
+README.md
+pyproject.toml
+src/multiplayerlib/EncryptionManager.py
+src/multiplayerlib/NetworkConstants.py
+src/multiplayerlib/NetworkLib.py
+src/multiplayerlib/__init__.py
+src/multiplayerlib.egg-info/PKG-INFO
+src/multiplayerlib.egg-info/SOURCES.txt
+src/multiplayerlib.egg-info/dependency_links.txt
+src/multiplayerlib.egg-info/requires.txt
+src/multiplayerlib.egg-info/top_level.txt

multiplayerlib-0.0.1/src/multiplayerlib.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

multiplayerlib-0.0.1/src/multiplayerlib.egg-info/requires.txt

@@ -0,0 +1,2 @@
+cryptography==50.0.1
+orjson==3.12.0

multiplayerlib-0.0.1/src/multiplayerlib.egg-info/top_level.txt

@@ -0,0 +1 @@
+multiplayerlib