pyreverb 1.8.0

Multiplayer library

PyReverb

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
   • 1. Define a networked object
   • 2. Minimal server
   • 3. Minimal client
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:

• GitHub: https://github.com/LeLaboDuGame/PyReverb