styly-netsync-server 0.13.0__tar.gz → 0.15.0__tar.gz

{styly_netsync_server-0.13.0 → styly_netsync_server-0.15.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: styly-netsync-server
-Version: 0.13.0
+Version: 0.15.0
 Summary: STYLY NetSync Server - Multiplayer framework for Location-Based Entertainment VR/MR experiences
 Author-email: "STYLY, Inc." <info@styly.inc>
 License-Expression: Apache-2.0
@@ -81,13 +81,16 @@ styly-netsync-simulator --server tcp://localhost --room my_room --clients 50
 
 ## Wire protocol compatibility
 
-- Current transform wire protocol is `protocolVersion = 5`.
-- Transform messages use `MSG_CLIENT_POSE` (11) and `MSG_ROOM_POSE` (12) with the compact V5 pose body.
-- v5 adds an optional `MovingFloorLocal` pose flag. Bound avatars send head, hands, and virtual transforms in the registered moving floor's local coordinates, and reuse the existing 8-byte physical slot as direct physical position/yaw.
-- Unbound v5 poses keep the v4 `xrOriginDelta` semantics: `xrOriginDelta` carries a Y component as a 4th `int16` (`dx, dy, dz, dyaw` = 8 bytes vs. v3's 6), so receivers can reconstruct the sender's rig-Y motion.
+- Current wire protocol is `protocolVersion = 7`.
+- Transport uses three sockets: control (`control_port`, default `5555`) for RPC, Network Variables, ownership, ID mapping, and client hello; transform uplink (`transform_port`, default `5557`) for client/object poses; PUB/SUB (`pub_port`, default `5556`) for room pose and room object downlink.
+- Discovery responses use `STYLY-NETSYNC2|controlPort|transformPort|pubPort|serverName`; legacy `STYLY-NETSYNC|...` responses are explicitly incompatible.
+- `dealer_port` / `--dealer-port` remain a one-release compatibility alias for `control_port` / `--control-port`.
+- Transform messages use `MSG_CLIENT_POSE` (11) and `MSG_ROOM_POSE` (12) with the compact pose body. Clients register control identity with `MSG_CLIENT_HELLO` (19).
+- Moving-floor-local poses set the `MovingFloorLocal` pose flag. Bound avatars send head, hands, and virtual transforms in the registered moving floor's local coordinates, and reuse the existing 8-byte physical slot as direct physical position/yaw.
+- Unbound poses keep the `xrOriginDelta` semantics: `xrOriginDelta` carries a Y component as a 4th `int16` (`dx, dy, dz, dyaw` = 8 bytes), so receivers can reconstruct the sender's rig-Y motion.
 - Legacy transform protocols (v2/v3) and JSON transform fallback are not supported.
 - Deploy Unity and Python updates together when changing transform protocol behavior.
-- Protocol v5 position quantization ranges:
+- Protocol v7 position quantization ranges:
   - Absolute (`headPosAbs` only): signed `int24` at `0.01 m` per unit, per-axis range `[-83,886.08 m, 83,886.07 m]`.
   - XROrigin locomotion delta for unbound poses (`xrOriginDelta`, 4×`int16`: `dx, dy, dz, dyaw`): `0.01 m` per unit for translation, `0.1°` for yaw. Receivers reconstruct `physicalPos = invDeltaRot * (headPos − deltaPos)`; it is not on the wire as a separate absolute field.
   - Direct physical payload for moving-floor-local poses (`physical`, 4×`int16`: `x, y, z, yaw`): `0.01 m` per unit for translation, `0.1°` for yaw.
@@ -98,7 +101,7 @@ styly-netsync-simulator --server tcp://localhost --room my_room --clients 50
 
 The following options summarize trade-offs when expanding absolute-position range.
 
-Assumed unbound baseline (`protocolVersion=5`, `MovingFloorLocal` off):
+Assumed unbound baseline (`protocolVersion=7`, `MovingFloorLocal` off):
 - Client pose body with `Physical+Head+Right+Left` valid and `virtualCount=0`: `46 bytes` (matches `test_client_body_size_with_full_pose_no_virtuals`).
 - Room per-client entry (`clientNo + poseTime + clientBody`): `56 bytes`.
 
@@ -267,4 +270,4 @@ The response includes the room ID and whether each key was `"applied"`, `"queued
 
 ### Read consistency
 
-GET endpoints return a snapshot of the REST bridge's in-process cache, which is populated by PUB-SUB broadcasts from the server. The first request to a room lazily creates a bridge and may return an empty snapshot until the initial broadcasts arrive — retry after a short delay if needed.
+GET endpoints return a snapshot of the REST bridge's in-process cache, which is populated by control-lane sync messages from the server. The first request to a room lazily creates a bridge and may return an empty snapshot until the initial sync arrives — retry after a short delay if needed.

{styly_netsync_server-0.13.0 → styly_netsync_server-0.15.0}/README.md

@@ -42,13 +42,16 @@ styly-netsync-simulator --server tcp://localhost --room my_room --clients 50
 
 ## Wire protocol compatibility
 
-- Current transform wire protocol is `protocolVersion = 5`.
-- Transform messages use `MSG_CLIENT_POSE` (11) and `MSG_ROOM_POSE` (12) with the compact V5 pose body.
-- v5 adds an optional `MovingFloorLocal` pose flag. Bound avatars send head, hands, and virtual transforms in the registered moving floor's local coordinates, and reuse the existing 8-byte physical slot as direct physical position/yaw.
-- Unbound v5 poses keep the v4 `xrOriginDelta` semantics: `xrOriginDelta` carries a Y component as a 4th `int16` (`dx, dy, dz, dyaw` = 8 bytes vs. v3's 6), so receivers can reconstruct the sender's rig-Y motion.
+- Current wire protocol is `protocolVersion = 7`.
+- Transport uses three sockets: control (`control_port`, default `5555`) for RPC, Network Variables, ownership, ID mapping, and client hello; transform uplink (`transform_port`, default `5557`) for client/object poses; PUB/SUB (`pub_port`, default `5556`) for room pose and room object downlink.
+- Discovery responses use `STYLY-NETSYNC2|controlPort|transformPort|pubPort|serverName`; legacy `STYLY-NETSYNC|...` responses are explicitly incompatible.
+- `dealer_port` / `--dealer-port` remain a one-release compatibility alias for `control_port` / `--control-port`.
+- Transform messages use `MSG_CLIENT_POSE` (11) and `MSG_ROOM_POSE` (12) with the compact pose body. Clients register control identity with `MSG_CLIENT_HELLO` (19).
+- Moving-floor-local poses set the `MovingFloorLocal` pose flag. Bound avatars send head, hands, and virtual transforms in the registered moving floor's local coordinates, and reuse the existing 8-byte physical slot as direct physical position/yaw.
+- Unbound poses keep the `xrOriginDelta` semantics: `xrOriginDelta` carries a Y component as a 4th `int16` (`dx, dy, dz, dyaw` = 8 bytes), so receivers can reconstruct the sender's rig-Y motion.
 - Legacy transform protocols (v2/v3) and JSON transform fallback are not supported.
 - Deploy Unity and Python updates together when changing transform protocol behavior.
-- Protocol v5 position quantization ranges:
+- Protocol v7 position quantization ranges:
   - Absolute (`headPosAbs` only): signed `int24` at `0.01 m` per unit, per-axis range `[-83,886.08 m, 83,886.07 m]`.
   - XROrigin locomotion delta for unbound poses (`xrOriginDelta`, 4×`int16`: `dx, dy, dz, dyaw`): `0.01 m` per unit for translation, `0.1°` for yaw. Receivers reconstruct `physicalPos = invDeltaRot * (headPos − deltaPos)`; it is not on the wire as a separate absolute field.
   - Direct physical payload for moving-floor-local poses (`physical`, 4×`int16`: `x, y, z, yaw`): `0.01 m` per unit for translation, `0.1°` for yaw.
@@ -59,7 +62,7 @@ styly-netsync-simulator --server tcp://localhost --room my_room --clients 50
 
 The following options summarize trade-offs when expanding absolute-position range.
 
-Assumed unbound baseline (`protocolVersion=5`, `MovingFloorLocal` off):
+Assumed unbound baseline (`protocolVersion=7`, `MovingFloorLocal` off):
 - Client pose body with `Physical+Head+Right+Left` valid and `virtualCount=0`: `46 bytes` (matches `test_client_body_size_with_full_pose_no_virtuals`).
 - Room per-client entry (`clientNo + poseTime + clientBody`): `56 bytes`.
 
@@ -228,4 +231,4 @@ The response includes the room ID and whether each key was `"applied"`, `"queued
 
 ### Read consistency
 
-GET endpoints return a snapshot of the REST bridge's in-process cache, which is populated by PUB-SUB broadcasts from the server. The first request to a room lazily creates a bridge and may return an empty snapshot until the initial broadcasts arrive — retry after a short delay if needed.
+GET endpoints return a snapshot of the REST bridge's in-process cache, which is populated by control-lane sync messages from the server. The first request to a room lazily creates a bridge and may return an empty snapshot until the initial sync arrives — retry after a short delay if needed.

{styly_netsync_server-0.13.0 → styly_netsync_server-0.15.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "styly-netsync-server"
-version = "0.13.0"
+version = "0.15.0"
 description = "STYLY NetSync Server - Multiplayer framework for Location-Based Entertainment VR/MR experiences"
 readme = "README.md"
 requires-python = ">=3.11"

{styly_netsync_server-0.13.0 → styly_netsync_server-0.15.0}/src/styly_netsync/__init__.py

@@ -16,7 +16,7 @@ Examples:
 
     # Use server programmatically
     from styly_netsync import NetSyncServer
-    server = NetSyncServer(dealer_port=5555, pub_port=5556)
+    server = NetSyncServer(control_port=5555, transform_port=5557, pub_port=5556)
     server.start()
 
     # Use client programmatically

{styly_netsync_server-0.13.0 → styly_netsync_server-0.15.0}/src/styly_netsync/binary_serializer.py

@@ -6,7 +6,11 @@ from typing import Any
 logger = logging.getLogger(__name__)
 
 # Message type identifiers
-PROTOCOL_VERSION = 5
+# v7: Control and transform traffic use separate sockets, and clients register
+# their control identity with MSG_CLIENT_HELLO.
+# Bumped so mixed old/new builds fail the handshake instead of silently
+# misparsing NV traffic (the version byte rides on transform/object messages).
+PROTOCOL_VERSION = 7
 MSG_CLIENT_TRANSFORM = 1
 MSG_ROOM_TRANSFORM = 2  # Legacy room transform with short IDs only
 MSG_RPC = 3  # Remote procedure call
@@ -25,6 +29,9 @@ MSG_OBJECT_OWNERSHIP_REQUEST = 15  # Client → Server: RequestOwnership/Release
 MSG_OBJECT_OWNERSHIP_CHANGED = 16  # Server → Clients (ROUTER): ownership changed
 MSG_OBJECT_OWNERSHIP_REJECTED = 17  # Server → Client (ROUTER): request rejected
 MSG_CLIENT_VAR_CLEAR = 18  # Clear all client variables for the sender
+MSG_CLIENT_HELLO = 19  # Client → Server: bind control identity to device ID
+
+CLIENT_HELLO_FLAG_STEALTH = 0x01
 
 # Transform data type identifiers (deprecated - kept for reference)
 
@@ -33,7 +40,7 @@ MSG_CLIENT_VAR_CLEAR = 18  # Clear all client variables for the sender
 _max_virtual_transforms = 50
 MAX_VIRTUAL_TRANSFORMS = _max_virtual_transforms  # Legacy alias for backward compat
 
-# Protocol v5 transform encoding constants
+# Protocol v7 pose encoding constants
 ABS_POS_SCALE = 0.01
 LOCO_POS_SCALE = 0.01
 REL_POS_SCALE = 0.005
@@ -629,6 +636,17 @@ def serialize_rpc_message(data: dict[str, Any]) -> bytes:
     return bytes(buffer)
 
 
+def serialize_client_hello(device_id: str, is_stealth: bool = False) -> bytes:
+    """Serialize client hello for control-lane identity registration."""
+    buffer = bytearray()
+    buffer.append(MSG_CLIENT_HELLO)
+    buffer.append(PROTOCOL_VERSION)
+    flags = CLIENT_HELLO_FLAG_STEALTH if is_stealth else 0
+    buffer.append(flags)
+    _pack_string(buffer, device_id)
+    return bytes(buffer)
+
+
 def parse_version(version_str: str) -> tuple[int, int, int]:
     """Parse semantic version string into (major, minor, patch) tuple.
 
@@ -686,7 +704,7 @@ def serialize_global_var_set(data: dict[str, Any]) -> bytes:
     """Serialize global variable set message
 
     Args:
-        data: Dictionary with senderClientNo, variableName, variableValue, timestamp
+        data: Dictionary with senderClientNo, variableName, variableValue
     """
     buffer = bytearray()
 
@@ -704,9 +722,6 @@ def serialize_global_var_set(data: dict[str, Any]) -> bytes:
     value = data.get("variableValue", "")[:1024]
     _pack_string(buffer, value, use_ushort=True)
 
-    # Timestamp (8 bytes double)
-    buffer.extend(struct.pack("<d", data.get("timestamp", 0.0)))
-
     return bytes(buffer)
 
 
@@ -729,7 +744,6 @@ def serialize_global_var_sync(data: dict[str, Any]) -> bytes:
     for var in variables:
         _pack_string(buffer, var.get("name", "")[:64])
         _pack_string(buffer, var.get("value", "")[:1024], use_ushort=True)
-        buffer.extend(struct.pack("<d", var.get("timestamp", 0.0)))
         buffer.extend(struct.pack("<H", var.get("lastWriterClientNo", 0)))
 
     return bytes(buffer)
@@ -739,7 +753,8 @@ def serialize_client_var_set(data: dict[str, Any]) -> bytes:
     """Serialize client variable set message
 
     Args:
-        data: Dictionary with senderClientNo, targetClientNo, variableName, variableValue, timestamp
+        data: Dictionary with senderClientNo, targetClientNo, variableName,
+            variableValue
     """
     buffer = bytearray()
 
@@ -760,9 +775,6 @@ def serialize_client_var_set(data: dict[str, Any]) -> bytes:
     value = data.get("variableValue", "")[:1024]
     _pack_string(buffer, value, use_ushort=True)
 
-    # Timestamp (8 bytes double)
-    buffer.extend(struct.pack("<d", data.get("timestamp", 0.0)))
-
     return bytes(buffer)
 
 
@@ -770,7 +782,7 @@ def serialize_client_var_clear(data: dict[str, Any]) -> bytes:
     """Serialize client variable clear message.
 
     Args:
-        data: Dictionary with senderClientNo and timestamp.
+        data: Dictionary with senderClientNo.
     """
     buffer = bytearray()
 
@@ -780,9 +792,6 @@ def serialize_client_var_clear(data: dict[str, Any]) -> bytes:
     # Sender client number (2 bytes)
     buffer.extend(struct.pack("<H", data.get("senderClientNo", 0)))
 
-    # Timestamp (8 bytes double)
-    buffer.extend(struct.pack("<d", data.get("timestamp", 0.0)))
-
     return bytes(buffer)
 
 
@@ -811,7 +820,6 @@ def serialize_client_var_sync(data: dict[str, Any]) -> bytes:
         for var in variables:
             _pack_string(buffer, var.get("name", "")[:64])
             _pack_string(buffer, var.get("value", "")[:1024], use_ushort=True)
-            buffer.extend(struct.pack("<d", var.get("timestamp", 0.0)))
             buffer.extend(struct.pack("<H", var.get("lastWriterClientNo", 0)))
 
     return bytes(buffer)
@@ -832,7 +840,7 @@ def deserialize(data: bytes) -> tuple[int, dict[str, Any] | None, bytes]:
     offset += 1
 
     # Validate message type is within valid range
-    if message_type < MSG_CLIENT_TRANSFORM or message_type > MSG_CLIENT_VAR_CLEAR:
+    if message_type < MSG_CLIENT_TRANSFORM or message_type > MSG_CLIENT_HELLO:
         # Return invalid message type with None data instead of raising exception
         return message_type, None, b""
 
@@ -863,6 +871,8 @@ def deserialize(data: bytes) -> tuple[int, dict[str, Any] | None, bytes]:
             return message_type, _deserialize_client_var_sync(data, offset), b""
         elif message_type == MSG_CLIENT_VAR_CLEAR:
             return message_type, _deserialize_client_var_clear(data, offset), b""
+        elif message_type == MSG_CLIENT_HELLO:
+            return message_type, _deserialize_client_hello(data, offset), b""
         elif message_type == MSG_OBJECT_POSE:
             return message_type, _deserialize_object_pose(data, offset), b""
         elif message_type == MSG_ROOM_OBJECTS:
@@ -897,6 +907,22 @@ def deserialize(data: bytes) -> tuple[int, dict[str, Any] | None, bytes]:
         return message_type, None, b""
 
 
+def _deserialize_client_hello(data: bytes, offset: int) -> dict[str, Any]:
+    """Deserialize client hello control message."""
+    protocol_version = data[offset]
+    offset += 1
+    if protocol_version != PROTOCOL_VERSION:
+        raise ValueError(f"Unsupported protocol version: {protocol_version}")
+    flags = data[offset]
+    offset += 1
+    device_id, offset = _unpack_string(data, offset)
+    return {
+        "deviceId": device_id,
+        "flags": flags,
+        "isStealthMode": bool(flags & CLIENT_HELLO_FLAG_STEALTH),
+    }
+
+
 def _deserialize_client_body(data: bytes, offset: int) -> tuple[dict[str, Any], int]:
     """Deserialize protocol v5 compact pose body."""
     result: dict[str, Any] = {}
@@ -1247,10 +1273,6 @@ def _deserialize_global_var_set(data: bytes, offset: int) -> dict[str, Any]:
     # Variable value
     result["variableValue"], offset = _unpack_string(data, offset, use_ushort=True)
 
-    # Timestamp (8 bytes double)
-    result["timestamp"] = struct.unpack("<d", data[offset : offset + 8])[0]
-    offset += 8
-
     return result
 
 
@@ -1267,8 +1289,6 @@ def _deserialize_global_var_sync(data: bytes, offset: int) -> dict[str, Any]:
         var = {}
         var["name"], offset = _unpack_string(data, offset)
         var["value"], offset = _unpack_string(data, offset, use_ushort=True)
-        var["timestamp"] = struct.unpack("<d", data[offset : offset + 8])[0]
-        offset += 8
         var["lastWriterClientNo"] = struct.unpack("<H", data[offset : offset + 2])[0]
         offset += 2
         result["variables"].append(var)
@@ -1294,10 +1314,6 @@ def _deserialize_client_var_set(data: bytes, offset: int) -> dict[str, Any]:
     # Variable value
     result["variableValue"], offset = _unpack_string(data, offset, use_ushort=True)
 
-    # Timestamp (8 bytes double)
-    result["timestamp"] = struct.unpack("<d", data[offset : offset + 8])[0]
-    offset += 8
-
     return result
 
 
@@ -1307,10 +1323,6 @@ def _deserialize_client_var_clear(data: bytes, offset: int) -> dict[str, Any]:
 
     # Sender client number (2 bytes)
     result["senderClientNo"] = struct.unpack("<H", data[offset : offset + 2])[0]
-    offset += 2
-
-    # Timestamp (8 bytes double)
-    result["timestamp"] = struct.unpack("<d", data[offset : offset + 8])[0]
 
     return result
 
@@ -1336,8 +1348,6 @@ def _deserialize_client_var_sync(data: bytes, offset: int) -> dict[str, Any]:
             var = {}
             var["name"], offset = _unpack_string(data, offset)
             var["value"], offset = _unpack_string(data, offset, use_ushort=True)
-            var["timestamp"] = struct.unpack("<d", data[offset : offset + 8])[0]
-            offset += 8
             var["lastWriterClientNo"] = struct.unpack("<H", data[offset : offset + 2])[
                 0
             ]
@@ -1359,6 +1369,10 @@ def serialize_object_pose(data: dict[str, Any]) -> bytes:
     buffer = bytearray()
     buffer.append(MSG_OBJECT_POSE)
     buffer.append(PROTOCOL_VERSION)
+    # Sender device ID: lets the server attribute the pose by identity carried in
+    # the payload rather than the transform-lane socket identity (which a stealth
+    # owner never binds because it sends no MSG_CLIENT_POSE).
+    _pack_string(buffer, str(data.get("deviceId", "")))
     object_id = int(data.get("objectId", 0)) & 0xFFFFFFFF
     buffer.extend(struct.pack("<I", object_id))
     buffer.extend(struct.pack("<H", int(data.get("poseSeq", 0)) & 0xFFFF))
@@ -1456,6 +1470,8 @@ def _deserialize_object_pose(data: bytes, offset: int) -> dict[str, Any]:
     offset += 1
     if protocol_version != PROTOCOL_VERSION:
         raise ValueError(f"Unsupported protocol version: {protocol_version}")
+    device_id, offset = _unpack_string(data, offset)
+    result["deviceId"] = device_id
     result["objectId"] = struct.unpack("<I", data[offset : offset + 4])[0]
     offset += 4
     result["poseSeq"] = struct.unpack("<H", data[offset : offset + 2])[0]