Skip to main content

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.

  • source code along with demo game can be found here

Table of Contents


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
  • Built in logging.
  • Methods for the host to ban certain addresses.

Installation

run the install command to install the package

pip install multiplayerlib


Quick Start Example

Host (Server)

mgr = NetworkManager(
    is_host=True,
    base_port=5000,
    use_compression=True,
    use_encryption=False
)
mgr.start()

Client

mgr = NetworkManager(
    is_host=False,
    peer_ip="1.2.3.4",
    base_port=5000,
    use_compression=True,
    use_encryption=False
)
mgr.start()

Sending / Receiving

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, however it is suggested that users implement some packet numbering/packet ordering system in their game code. MultiplayerLib is merely intended to send the json packets, how users use them is up to them.
  • Designed for frequent state updates (position, actions, etc.)

API Reference

MultiplayerLib

  • checkForUpdates() checks PyPI for a more recent release of multiplayerlib. returns true if update available. returns false if the pypi api is unreachable or if current version matches latest version.

NetworkManager

Constructor

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

Data Types

MultiplayerLib uses JSON serialization for packets. Data passed to safe_send() must be composed of JSON-compatible values:

  • None
  • bool
  • int
  • float
  • str
  • list
  • dict with string keys

Lists and dictionaries can be nested arbitrarily, but may only contain JSON compatible types.


Packet Examples

Common patterns used in games:

Player State

{
  "type": "playerdata",
  "position": {
    "x": 640,
    "y": 360,
    "rotation": 1.57
  },
  "health": 100
}

Action Event

{
  "type": "shoot",
  "pos": [x, y],
  "vec": [vx, vy],
  "timestamp": 1234567890.0
}

Disconnect

{
  "type": "quit"
}

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

Contributors

  • griffingreat1

License

MIT License — see LICENSE

Metadata

Release files for multiplayerlib 0.1.4.post1

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for multiplayerlib 0.1.4.post1
File Size Uploaded Provenance Actions
multiplayerlib-0.1.4.post1.tar.gz 11.7 kB Without provenance Details for multiplayerlib-0.1.4.post1.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for multiplayerlib 0.1.4.post1
File Interpreter ABI Platform Actions
multiplayerlib-0.1.4.post1-py3-none-any.whl Python 3 none any Details for multiplayerlib-0.1.4.post1-py3-none-any.whl

Total release size: 22.5 kB

Release files / multiplayerlib-0.1.4.post1.tar.gz

Download URL multiplayerlib-0.1.4.post1.tar.gz
Size 11.7 kB
Tags Source
SHA-256 checksum
How to use checksums
9f0d52726f27852bc51a19e109c1c6c84c1ad7cc76f3deee2f322eb2a1083a88
BLAKE2b-256 checksum
How to use checksums
3d2219de0b2ad7ddd8f5c2e8223b743a0e365331b607e98b97d2831e6b10585b
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.14.6

Release files / multiplayerlib-0.1.4.post1-py3-none-any.whl

Download URL multiplayerlib-0.1.4.post1-py3-none-any.whl
Size 10.8 kB
Tags Python 3
SHA-256 checksum
How to use checksums
4b9f6d43fe351dca449ecb900fbcbd547befc0f837f199252d18d232d73d7f97
BLAKE2b-256 checksum
How to use checksums
1b93f66c7898704ff1e228c8265c9336837f00ad55ff6d45adee88c3518f0f51
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.14.6

Security for multiplayerlib 0.1.4.post1

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page