This page introduces STYLY-NetSync, a multiplayer framework designed specifically for Location-Based Entertainment (LBE) XR experiences. It covers the system's purpose, dual-component architecture (Unity client + Python server), core capabilities, and technology stack.
For detailed architectural information, see System Architecture. For installation and setup instructions, see Getting Started. For Unity client API documentation, see Unity Client. For Python server configuration and deployment, see Python Server.
STYLY-NetSync is a client-server networking framework optimized for real-time synchronization of multiple XR (VR/AR/MR) devices in venue-based installations. It addresses the specific requirements of Location-Based Entertainment scenarios where 10-60 players share physical space and need low-latency synchronization of:
The framework consists of two synchronized components that must be deployed together:
| Component | Technology | Purpose |
|---|---|---|
| Unity Client Package | Unity 6 + NetMQ | Runs on each XR device, handles avatar tracking and scene synchronization |
| Python Server | Python 3.11+ + ZeroMQ | Central relay server, runs on venue network, manages rooms and broadcasts state |
Current version: 0.10.1 (Unity package and Python server versions must match)
Sources: README.md1-42 STYLY-NetSync-Unity/Packages/com.styly.styly-netsync/package.json1-27 STYLY-NetSync-Server/pyproject.toml1-46
The following diagram shows the high-level system components and their relationships using actual code entities from the repository:
Sources: STYLY-NetSync-Unity/Packages/com.styly.styly-netsync/Runtime/NetSyncManager.cs STYLY-NetSync-Server/src/styly_netsync/server.py STYLY-NetSync-Server/src/styly_netsync/binary_serializer.py
The following table maps user-facing features to their implementation entities:
| Feature | Unity Component | Server Handler | Message Type | Description |
|---|---|---|---|---|
| Avatar Transform Sync | TransformSyncManager | _handle_client_transform | MSG_CLIENT_POSE (0x0B)MSG_ROOM_POSE (0x0C) | Real-time head, hand, physical position sync at 10-60 Hz |
| Remote Procedure Calls | RPCManager | _send_rpc_to_room | MSG_RPC (0x03) | Broadcast or targeted function calls with string arguments |
| Global Variables | NetworkVariableManager | _buffer_global_var_setRoomState | MSG_GLOBAL_VAR_SET (0x07)MSG_GLOBAL_VAR_SYNC (0x08) | Room-wide shared key-value state |
| Client Variables | NetworkVariableManager | _buffer_client_var_setRoomState | MSG_CLIENT_VAR_SET (0x09)MSG_CLIENT_VAR_SYNC (0x0A) | Per-client attribute storage |
| Device ID Mapping | MessageProcessor | _broadcast_id_mappings | MSG_DEVICE_ID_MAPPING (0x06) | Client number ↔ device ID resolution |
| Human Presence | HumanPresenceManager | N/A (client-side only) | N/A | Physical position collision avoidance markers |
Sources: STYLY-NetSync-Unity/Packages/com.styly.styly-netsync/Runtime/Internal/ STYLY-NetSync-Server/src/styly_netsync/server.py400-800 STYLY-NetSync-Server/src/styly_netsync/binary_serializer.py1-50
STYLY-NetSync uses a custom binary protocol (version 3) optimized for XR data:
Key Design Decisions:
int24 at 0.01m precision (±83.8 km per axis), hand-relative positions use int16 at 0.005m precision (±163 m per axis)For detailed protocol specification, see Network Protocol. For XR-specific design rationale, see XR-Specific Design Decisions.
Sources: STYLY-NetSync-Server/src/styly_netsync/binary_serializer.py1-200 CLAUDE.md72-90 README.md89-94
The Unity client package depends on the following components:
Installation Method: OpenUPM CLI (scoped registry for all dependencies)
Sources: STYLY-NetSync-Unity/Packages/com.styly.styly-netsync/package.json7-14 README.md42-68
The Python server uses the following dependencies:
| Dependency | Version | Purpose |
|---|---|---|
pyzmq | ≥26.0.0 | ZeroMQ bindings for Python |
fastapi | ≥0.115.0 | REST API for external integrations |
uvicorn | ≥0.30.0 | ASGI server for FastAPI |
msgpack | ≥1.0.5 | Binary serialization (network variables) |
psutil | ≥5.9.0 | System resource monitoring |
loguru | ≥0.7.2 | Structured logging with rotation |
Installation Method: uvx styly-netsync-server@0.10.1 (creates isolated venv automatically)
Python Version: 3.11+ required (3.11 and 3.12 tested)
Sources: STYLY-NetSync-Server/pyproject.toml38-45 README.md75-83
STYLY-NetSync uses ZeroMQ with two distinct socket patterns:
Pattern Characteristics:
| Pattern | Direction | Use Case | Delivery Guarantee |
|---|---|---|---|
| DEALER-ROUTER | Bidirectional | Client → Server requests, Server → Client responses, targeted RPCs | Request-response with identity routing |
| PUB-SUB | One-to-many | Room broadcasts (poses, global variables, mappings) | Fire-and-forget multicast |
Default Ports:
For detailed communication flow, see Communication Patterns. For message types and serialization, see Network Protocol.
Sources: STYLY-NetSync-Server/src/styly_netsync/server.py100-200 STYLY-NetSync-Unity/Packages/com.styly.styly-netsync/Runtime/Internal/ConnectionManager.cs README.md236-238
Unity Client:
Python Server:
Version Compatibility: Unity package and Python server versions must match. Protocol v3 does not provide backward compatibility with older versions.
For detailed installation instructions, see Installation. For configuration and deployment, see Getting Started.
Sources: README.md60-83 README.md85-94
Unity Scene Setup:
NetSyncManager component to scene (right-click hierarchy → STYLY NetSync → NetSyncManager)C# API Example:
For complete API documentation, see Unity Client API. For demo scenes and samples, see Demo Scenes and Samples.
Sources: README.md158-219 README.md96-155
Current Release: 0.10.1 (2024)
Version Tracking:
Compatibility Policy:
For release management and CI/CD processes, see Release Management.
Sources: CLAUDE.md119-127 README.md85-94 STYLY-NetSync-Unity/Packages/com.styly.styly-netsync/package.json3 STYLY-NetSync-Server/pyproject.toml7
Refresh this wiki