Metadata-Version: 2.4
Name: styly-netsync-server
Version: 0.5.4
Summary: STYLY NetSync Server - Multiplayer framework for Location-Based Entertainment VR/MR experiences
Author-email: "STYLY, Inc." <info@styly.inc>
License: Apache-2.0
Project-URL: Homepage, https://styly.inc
Project-URL: Repository, https://github.com/styly-dev/STYLY-NetSync
Project-URL: Documentation, https://github.com/styly-dev/STYLY-NetSync/blob/main/README.md
Project-URL: Issues, https://github.com/styly-dev/STYLY-NetSync/issues
Keywords: unity,multiplayer,vr,mr,location-based-entertainment,real-time,zeromq,networking
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Games/Entertainment
Classifier: Topic :: Internet
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: System :: Networking
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: pyzmq>=26.0.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
Requires-Dist: black>=23.0.0; extra == "dev"
Requires-Dist: ruff>=0.1.0; extra == "dev"
Requires-Dist: mypy>=1.0.0; extra == "dev"
Dynamic: license-file

# STYLY NetSync Server

A Unity-based multiplayer framework for Location-Based Entertainment (LBE) VR/AR experiences. Provides real-time synchronization of player positions, hand tracking, and virtual objects using a Python server with ZeroMQ networking and binary serialization.

## Installation

### From PyPI (when published)
```bash
pip install styly-netsync-server
```

### From Source
```bash
# Clone the repository
git clone https://github.com/PsychicVRLab/STYLY-LBE-Multiplayer.git
cd STYLY-LBE-Multiplayer/STYLY-NetSync-Server

# Install in development mode
pip install -e .
```

### Using uv (recommended)
```bash
# Run without installing (one-time use)
uvx styly-netsync-server

# Run with custom options
uvx styly-netsync-server --dealer-port 5555 --pub-port 5556

# Run with uv (automatically installs dependencies)
uv run ./dev  # Convenience script for development
```

## Usage

### Command Line

Start the server with default settings:
```bash
styly-netsync-server
```

Start with custom configuration:
```bash
styly-netsync-server --dealer-port 5555 --pub-port 5556 --beacon-port 9999 --name "My-Server"
```

Disable UDP discovery:
```bash
styly-netsync-server --no-beacon
```

### Programmatic Usage

```python
from styly_netsync import NetSyncServer
import time

# Create and start server
server = NetSyncServer(
    dealer_port=5555,
    pub_port=5556,
    enable_beacon=True,
    beacon_port=9999,
    server_name="STYLY-NetSync-Server"
)

try:
    server.start()
    # Keep server running
    while True:
        time.sleep(1)
except KeyboardInterrupt:
    server.stop()
```

### Python Client Example

```python
from styly_netsync import net_sync_manager

manager = net_sync_manager(server="tcp://localhost", room="my_room")
manager.start()
snapshot = manager.get_room_transform_data()
```

### Client Simulator

Test the server with simulated clients:
```bash
# Simulate 100 clients
styly-netsync-simulator --clients 100

# Custom server and room
styly-netsync-simulator --server tcp://localhost --room my_room --clients 50
```

## Architecture

- **Binary Protocol**: Efficient ZeroMQ-based networking with ~60% bandwidth reduction vs JSON
- **Threading Model**: Separate threads for receive, periodic broadcast, and cleanup operations
- **Client Management**: Device ID to client number mapping with automatic cleanup
- **Network Variables**: Synchronized key-value storage with conflict resolution
- **RPC System**: Remote procedure calls for custom game logic

## Dependencies

- Python 3.8+
- pyzmq >= 26.0.0

## Development

### Testing During Development

There are several ways to test the server during development:

#### 1. Install in Development Mode
```bash
# Install the package in editable mode
pip install -e .

# Run the server
styly-netsync-server
```

#### 2. Run Directly as Python Module
```bash
# From the project root
python -m styly_netsync

# With custom options
python -m styly_netsync --dealer-port 6000 --pub-port 6001
```

#### 3. Use uv for Development
```bash
# Run using convenience script (automatically installs dependencies)
uv run ./dev

# Run with custom options
uv run ./dev --dealer-port 6000 --pub-port 6001

# Use uvx for one-time execution without installation
uvx --from . styly-netsync-server

# Test with client simulator
uvx --from . styly-netsync-simulator --clients 50
```

#### 4. Create Test Scripts
```python
# test_server.py
from src.styly_netsync import NetSyncServer

server = NetSyncServer(dealer_port=5555, pub_port=5556)
try:
    server.start()
    print("Server is running. Press Ctrl+C to stop.")
    while True:
        pass
except KeyboardInterrupt:
    server.stop()
```

#### 5. Use the Test Client
```bash
# Start the server first
styly-netsync-server

# In another terminal, run the test client
python test_client.py
```

#### 6. Load Testing with Client Simulator
```bash
# Start server
styly-netsync-server

# In another terminal, simulate multiple clients
styly-netsync-simulator --clients 100 --room test_room

# Monitor server logs for performance metrics
```

### Code Quality

```bash
# Install development dependencies
pip install -e ".[dev]"

# Run tests
pytest

# Format code
black src/ tests/

# Lint code
ruff src/ tests/

# Type check
mypy src/
```
