Skip to main content

PyReverb Banner

PyReverb

PyPI version License

PyReverb is a lightweight Python networking framework for real-time client–server synchronization of game and simulation objects.

It is designed to make it easy to:

  • Define network-aware objects once, and use them on both server and client
  • Keep object state synchronized across all peers
  • Trigger remote actions using events and RPC-like calls
  • Build fast multiplayer prototypes and real-time simulations

Table of Contents

  1. Features
  2. Why PyReverb
  3. Installation
  4. Quick Start
  5. Event System
  6. Project Structure
  7. Support
  8. Contributing
  9. License
  10. Author

Features

  • Object synchronization
    Define ReverbObject subclasses and keep their state in sync across the network.

  • Client–server framework
    Built-in Server and Client abstractions to manage connections and messaging.

  • Event-driven architecture
    Register callbacks on custom events (connect, disconnect, gameplay events, etc.).

  • Remote calls / actions
    Execute actions remotely between server and clients in a structured way.

  • Lightweight and focused
    Minimal external dependencies; integrates well with existing game loops (e.g. pygame).


Why PyReverb

  • Game-oriented: Designed with real-time games and interactive simulations in mind.
  • Simple mental model: Think in terms of objects and events, not raw sockets.
  • Python-first: Pure Python API that fits naturally into existing Python projects.
  • Extensible: You control how objects are created, synchronized, and updated.

Use it for:

  • 2D/3D multiplayer games
  • Real-time collaborative tools
  • Networked simulations and visualizations

Installation

Requirements:

  • Python 3.13+
  • virtualenv or another virtual environment tool (recommended)

Inside your virtual environment:

git clone https://github.com/LeLaboDuGame/PyReverb.git
cd PyReverb

# Install dependencies for development / local use
pip install -r requirements.txt

# Or install as a package (editable for development)
pip install -e .

You can also install directly from source in another project:

bash
pip install git+https://github.com/LeLaboDuGame/PyReverb.git

Quick Start

Below is a minimal end‑to‑end example showing:

  1. How to define a synchronized object
  2. How to start a server
  3. How to connect a client

The code is written as if you split it into three files: shared_objects.py, server.py, and client.py inside your project.

1. Define a networked object

# shared_objects.py
from pyreverb.reverb import ReverbManager, ReverbSide, ReverbObject

# Decide which side you're currently defining for.
# This file can be imported by both client and server.
ReverbManager.REVERB_SIDE = ReverbSide.SERVER  # or CLIENT when imported by the client


@ReverbManager.reverb_object_attribute
class Player(ReverbObject):
    def __init__(self, pos=(0, 0), uid=None, add_on_init=True):
        # Local attributes that will be synchronized
        self.pos = list(pos)
        super().__init__(uid=uid, add_on_init=add_on_init)

    def on_init_from_server(self):
        # Called when the Player is created on the server
        print(f"[SERVER] Player {self.uid} initialized at {self.pos}")

    def on_init_from_client(self):
        # Called when the Player appears on a client
        print(f"[CLIENT] Player {self.uid} spawned at {self.pos}")

2. Minimal server

# server.py
from pyreverb.reverb import ReverbManager, ReverbSide, Server
from shared_objects import Player  # noqa: F401 - ensure class is registered


def main():
    # Configure PyReverb as server-side
    ReverbManager.REVERB_SIDE = ReverbSide.SERVER

    server = Server()
    ReverbManager.REVERB_CONNECTION = server

    # Start listening for clients
    server.start_server()

    # Create a player instance on the server
    player = Player(pos=(5, 5))
    print(f"[SERVER] Created Player with uid={player.uid}")

    # Main loop placeholder (replace with your game loop)
    try:
        while True:
            # Process network events / messages
            server.update()
            # ... your game logic, physics, etc. ...
    except KeyboardInterrupt:
        print("[SERVER] Shutting down...")
        server.stop_server()


if __name__ == "__main__":
    main()

3. Minimal client

# client.py
from pyreverb.reverb import ReverbManager, ReverbSide, Client
from shared_objects import Player  # noqa: F401 - ensure class is registered


def main():
    # Configure PyReverb as client-side
    ReverbManager.REVERB_SIDE = ReverbSide.CLIENT

    client = Client()
    ReverbManager.REVERB_CONNECTION = client

    # Connect to the server (adjust host/port if needed)
    client.connect(host="127.0.0.1", port=5555)

    # Main loop placeholder (replace with your render / game loop)
    try:
        while True:
            client.update()
            # Here you would update local input and send changes, e.g.:
            # for player in Player.get_all_instances():
            #     player.pos[0] += 1  # move right, for example
    except KeyboardInterrupt:
        print("[CLIENT] Disconnecting...")
        client.disconnect()


if __name__ == "__main__":
    main()

How this works:

  • The Player class is registered as a networked object via @ReverbManager.reverb_object_attribute.
  • The server creates a Player instance; PyReverb synchronizes it with connected clients.
  • The client keeps a local mirror of the Player instance and can react to updates in its callbacks.

For more advanced usage (multiple object types, more complex logic, etc.), you can follow the same pattern with additional ReverbObject subclasses.


Event System

PyReverb uses an event-driven core so that you can react to network events without constantly polling everything manually.

A simplified usage pattern looks like this:

from pyreverb.reverb import ReverbManager

kernel = ReverbManager.get_kernel()

@kernel.on_event("client_connected")
def on_client_connected(client_id):
    print(f"Client connected: {client_id}")

@kernel.on_event("client_disconnected")
def on_client_disconnected(client_id):
    print(f"Client disconnected: {client_id}")

You can define and emit custom events to coordinate gameplay logic, lobby systems, or other high‑level behaviors above the raw networking layer.


Project Structure

At a high level, the repository is organized as follows:

  • src/pyreverb/ – Core library code
  • src/pyreverb/assets/ – Assets such as the README banner
  • src/pyreverb/Exemple/ – Example project demonstrating PyReverb in action
  • pyproject.toml – Packaging configuration
  • README.md – Project documentation (this file)

You can use the example project as a reference when integrating PyReverb into your own game or simulation.


Support

  • Open an Issue on the repository for bugs or feature requests.
  • Use Discussions (if enabled) for general questions and design ideas.
  • Check the source and examples for reference implementations.

Contributing

Contributions are welcome.

  1. Open an issue to discuss new features or changes.
  2. Fork the repository and create a feature branch:
    git checkout -b feature/my-feature
    
  3. Implement your changes and add tests or example usage where appropriate.
  4. Ensure code style and formatting are consistent.
  5. Open a Pull Request with a clear description of what you changed and why.

License

This project is licensed under the Apache License 2.0.
See the LICENSE file for the full license text.


Author

PyReverb is maintained by LeLaboDuGame (Twitch: https://twitch.tv/LaboTTV).
For more information and updates, see the project homepage:

Metadata

Release files for pyreverb 1.8.1.3

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

Source distribution (sdist)

Source distribution for pyreverb 1.8.1.3
File Size Uploaded Provenance Actions
pyreverb-1.8.1.3.tar.gz 24.7 kB Without provenance Details for pyreverb-1.8.1.3.tar.gz

Built distribution (wheel)

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

Total release size: 48.5 kB

Release files / pyreverb-1.8.1.3.tar.gz

Download URL pyreverb-1.8.1.3.tar.gz
Size 24.7 kB
Tags Source
SHA-256 checksum
How to use checksums
1cc2276cd06c5393b2af60a9d6df7f9887575d1b7ae9b2352c498c9ae47b567c
BLAKE2b-256 checksum
How to use checksums
ed3ee2106d93294d0cbfbe3de718e0b2bd19580a4e23792781d04a46beceb5f5
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/6.2.0 CPython/3.13.7

Release files / pyreverb-1.8.1.3-py3-none-any.whl

Download URL pyreverb-1.8.1.3-py3-none-any.whl
Size 23.8 kB
Tags Python 3
SHA-256 checksum
How to use checksums
285c16bc3fd284b10cd6934498d7c2ec72faaa5ecc7e29f7d73b7bdff78f3743
BLAKE2b-256 checksum
How to use checksums
920f8a6b9b09df0d01c68aa034308938a906006f0ec623bf07c3973be5cc515e
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/6.2.0 CPython/3.13.7

Security for pyreverb 1.8.1.3

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