styly-netsync-server 0.10.4__tar.gz → 0.11.0__tar.gz

{styly_netsync_server-0.10.4 → styly_netsync_server-0.11.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: styly-netsync-server
-Version: 0.10.4
+Version: 0.11.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,12 +81,14 @@ styly-netsync-simulator --server tcp://localhost --room my_room --clients 50
 
 ## Wire protocol compatibility
 
-- Current transform wire protocol is `protocolVersion = 3`.
-- Transform messages use `MSG_CLIENT_POSE` (11) and `MSG_ROOM_POSE` (12) with the compact V3 pose body.
-- Legacy transform protocol v2 and JSON transform fallback are not supported.
+- Current transform wire protocol is `protocolVersion = 4`.
+- Transform messages use `MSG_CLIENT_POSE` (11) and `MSG_ROOM_POSE` (12) with the compact V4 pose body.
+- v4 vs. v3: `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 (e.g. elevators).
+- Legacy transform protocols (v2/v3) and JSON transform fallback are not supported.
 - Deploy Unity and Python updates together when changing transform protocol behavior.
-- Protocol v3 position quantization ranges:
-  - Absolute (`physicalPos`, `headPosAbs`): signed `int24` at `0.01 m` per unit, per-axis range `[-83,886.08 m, 83,886.07 m]`.
+- Protocol v4 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 (`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.
   - Head-relative (`right/left/virtual`): signed `int16` at `0.005 m` per unit, per-axis range `[-163.84 m, 163.835 m]`.
 - These are encoding limits, not a hard world-size cap. Worlds can be larger, but encoded axis values are clamped if they exceed the representable range.
 
@@ -94,18 +96,18 @@ styly-netsync-simulator --server tcp://localhost --room my_room --clients 50
 
 The following options summarize trade-offs when expanding absolute-position range.
 
-Assumed baseline (`protocolVersion=3`):
-- Client pose body with `Physical+Head+Right+Left` valid and `virtualCount=0`: `49 bytes`
-- Room per-client entry (`clientNo + poseTime + clientBody`): `59 bytes`
+Assumed baseline (`protocolVersion=4`):
+- 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`.
 
 | Option | Absolute Position Encoding | Per-axis Range | Client Body Delta | Room Per-client Delta |
 |---|---|---:|---:|---:|
-| A. Coarser scale (current integer width) | `int24 @ 0.02m` | `[-167,772.16m, 167,772.14m]` | `+0B` (`49 -> 49`) | `+0B` (`59 -> 59`) |
-| B. Cell + local | `cell(i16, 256m) + local(int24 @ 0.01m)` | `[-8,472,494.08m, 8,472,238.07m]` | `+6B` (`49 -> 55`, `+12.2%`) | `+6B` (`59 -> 65`, `+10.2%`) |
-| C. Cell + local (large cell) | `cell(i16, 1024m) + local(int24 @ 0.01m)` | `[-33,638,318.08m, 33,637,294.07m]` | `+6B` (`49 -> 55`, `+12.2%`) | `+6B` (`59 -> 65`, `+10.2%`) |
+| A. Coarser scale (current integer width) | `int24 @ 0.02m` | `[-167,772.16m, 167,772.14m]` | `+0B` (`46 -> 46`) | `+0B` (`56 -> 56`) |
+| B. Cell + local | `cell(i16, 256m) + local(int24 @ 0.01m)` | `[-8,472,494.08m, 8,472,238.07m]` | `+6B` (`46 -> 52`, `+13.0%`) | `+6B` (`56 -> 62`, `+10.7%`) |
+| C. Cell + local (large cell) | `cell(i16, 1024m) + local(int24 @ 0.01m)` | `[-33,638,318.08m, 33,637,294.07m]` | `+6B` (`46 -> 52`, `+13.0%`) | `+6B` (`56 -> 62`, `+10.7%`) |
 
 Notes:
-- Option B/C deltas assume both absolute transforms are present (`physicalPos` and `headPosAbs`).
+- Only `headPosAbs` is on the wire as an absolute field; `physicalPos` is reconstructed from `headPosAbs + xrOriginDelta`. Option B/C deltas therefore apply to `headPosAbs` only.
 - Option B/C can reduce average overhead if `cell` is transmitted only when changed, but that requires extra state and flags in the wire format.
 
 ## Configuration
@@ -160,7 +162,7 @@ The server launches an embedded FastAPI application that exposes REST endpoints
 
 ```json
 {
-  "vars": {
+  "variables": {
     "name": "Jack",
     "lang": "EN"
   }
@@ -179,11 +181,35 @@ The server launches an embedded FastAPI application that exposes REST endpoints
 ```bash
 curl -sS -X POST "http://127.0.0.1:8800/v1/rooms/default_room/devices/00000000-0000-0000-0000-000000000000/client-variables" \
   -H "Content-Type: application/json" \
-  -d '{"vars":{"name":"Jack","lang":"EN"}}'
+  -d '{"variables":{"name":"Jack","lang":"EN"}}'
 ```
 
 The response includes the current mapping status (`clientNo` or `null`) and whether each key was `"applied"` or `"queued"`.
 
+- Read endpoints:
+  - `GET /v1/rooms/{roomId}/devices/{deviceId}/client-variables` — returns all client variables for the device.
+
+    ```json
+    {"clientNo": 7, "variables": {"name": "Jack", "lang": "EN"}}
+    ```
+
+    If the device has no `clientNo` mapping yet, returns `{"clientNo": null, "variables": {}}`.
+
+  - `GET /v1/rooms/{roomId}/devices/{deviceId}/client-variables/{name}` — returns a single variable.
+
+    ```json
+    {"clientNo": 7, "value": "Jack"}
+    ```
+
+    Returns `404` if the device is unmapped or the variable is not set.
+
+- Example:
+
+  ```bash
+  curl -sS "http://127.0.0.1:8800/v1/rooms/default_room/devices/00000000-0000-0000-0000-000000000000/client-variables"
+  curl -sS "http://127.0.0.1:8800/v1/rooms/default_room/devices/00000000-0000-0000-0000-000000000000/client-variables/name"
+  ```
+
 ### Global variables
 
 - Endpoint: `POST /v1/rooms/{roomId}/global-variables`
@@ -191,7 +217,7 @@ The response includes the current mapping status (`clientNo` or `null`) and whet
 
 ```json
 {
-  "vars": {
+  "variables": {
     "score": "42",
     "stage": "lobby"
   }
@@ -210,7 +236,33 @@ The response includes the current mapping status (`clientNo` or `null`) and whet
 ```bash
 curl -sS -X POST "http://127.0.0.1:8800/v1/rooms/default_room/global-variables" \
   -H "Content-Type: application/json" \
-  -d '{"vars":{"score":"42","stage":"lobby"}}'
+  -d '{"variables":{"score":"42","stage":"lobby"}}'
 ```
 
 The response includes the room ID and whether each key was `"applied"`, `"queued"`, or `"failed"`.
+
+- Read endpoints:
+  - `GET /v1/rooms/{roomId}/global-variables` — returns all global variables for the room.
+
+    ```json
+    {"variables": {"score": "42", "stage": "lobby"}}
+    ```
+
+  - `GET /v1/rooms/{roomId}/global-variables/{name}` — returns a single variable.
+
+    ```json
+    {"value": "42"}
+    ```
+
+    Returns `404` if the variable is not set.
+
+- Example:
+
+  ```bash
+  curl -sS "http://127.0.0.1:8800/v1/rooms/default_room/global-variables"
+  curl -sS "http://127.0.0.1:8800/v1/rooms/default_room/global-variables/score"
+  ```
+
+### 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.

{styly_netsync_server-0.10.4 → styly_netsync_server-0.11.0}/README.md

@@ -42,12 +42,14 @@ styly-netsync-simulator --server tcp://localhost --room my_room --clients 50
 
 ## Wire protocol compatibility
 
-- Current transform wire protocol is `protocolVersion = 3`.
-- Transform messages use `MSG_CLIENT_POSE` (11) and `MSG_ROOM_POSE` (12) with the compact V3 pose body.
-- Legacy transform protocol v2 and JSON transform fallback are not supported.
+- Current transform wire protocol is `protocolVersion = 4`.
+- Transform messages use `MSG_CLIENT_POSE` (11) and `MSG_ROOM_POSE` (12) with the compact V4 pose body.
+- v4 vs. v3: `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 (e.g. elevators).
+- Legacy transform protocols (v2/v3) and JSON transform fallback are not supported.
 - Deploy Unity and Python updates together when changing transform protocol behavior.
-- Protocol v3 position quantization ranges:
-  - Absolute (`physicalPos`, `headPosAbs`): signed `int24` at `0.01 m` per unit, per-axis range `[-83,886.08 m, 83,886.07 m]`.
+- Protocol v4 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 (`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.
   - Head-relative (`right/left/virtual`): signed `int16` at `0.005 m` per unit, per-axis range `[-163.84 m, 163.835 m]`.
 - These are encoding limits, not a hard world-size cap. Worlds can be larger, but encoded axis values are clamped if they exceed the representable range.
 
@@ -55,18 +57,18 @@ styly-netsync-simulator --server tcp://localhost --room my_room --clients 50
 
 The following options summarize trade-offs when expanding absolute-position range.
 
-Assumed baseline (`protocolVersion=3`):
-- Client pose body with `Physical+Head+Right+Left` valid and `virtualCount=0`: `49 bytes`
-- Room per-client entry (`clientNo + poseTime + clientBody`): `59 bytes`
+Assumed baseline (`protocolVersion=4`):
+- 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`.
 
 | Option | Absolute Position Encoding | Per-axis Range | Client Body Delta | Room Per-client Delta |
 |---|---|---:|---:|---:|
-| A. Coarser scale (current integer width) | `int24 @ 0.02m` | `[-167,772.16m, 167,772.14m]` | `+0B` (`49 -> 49`) | `+0B` (`59 -> 59`) |
-| B. Cell + local | `cell(i16, 256m) + local(int24 @ 0.01m)` | `[-8,472,494.08m, 8,472,238.07m]` | `+6B` (`49 -> 55`, `+12.2%`) | `+6B` (`59 -> 65`, `+10.2%`) |
-| C. Cell + local (large cell) | `cell(i16, 1024m) + local(int24 @ 0.01m)` | `[-33,638,318.08m, 33,637,294.07m]` | `+6B` (`49 -> 55`, `+12.2%`) | `+6B` (`59 -> 65`, `+10.2%`) |
+| A. Coarser scale (current integer width) | `int24 @ 0.02m` | `[-167,772.16m, 167,772.14m]` | `+0B` (`46 -> 46`) | `+0B` (`56 -> 56`) |
+| B. Cell + local | `cell(i16, 256m) + local(int24 @ 0.01m)` | `[-8,472,494.08m, 8,472,238.07m]` | `+6B` (`46 -> 52`, `+13.0%`) | `+6B` (`56 -> 62`, `+10.7%`) |
+| C. Cell + local (large cell) | `cell(i16, 1024m) + local(int24 @ 0.01m)` | `[-33,638,318.08m, 33,637,294.07m]` | `+6B` (`46 -> 52`, `+13.0%`) | `+6B` (`56 -> 62`, `+10.7%`) |
 
 Notes:
-- Option B/C deltas assume both absolute transforms are present (`physicalPos` and `headPosAbs`).
+- Only `headPosAbs` is on the wire as an absolute field; `physicalPos` is reconstructed from `headPosAbs + xrOriginDelta`. Option B/C deltas therefore apply to `headPosAbs` only.
 - Option B/C can reduce average overhead if `cell` is transmitted only when changed, but that requires extra state and flags in the wire format.
 
 ## Configuration
@@ -121,7 +123,7 @@ The server launches an embedded FastAPI application that exposes REST endpoints
 
 ```json
 {
-  "vars": {
+  "variables": {
     "name": "Jack",
     "lang": "EN"
   }
@@ -140,11 +142,35 @@ The server launches an embedded FastAPI application that exposes REST endpoints
 ```bash
 curl -sS -X POST "http://127.0.0.1:8800/v1/rooms/default_room/devices/00000000-0000-0000-0000-000000000000/client-variables" \
   -H "Content-Type: application/json" \
-  -d '{"vars":{"name":"Jack","lang":"EN"}}'
+  -d '{"variables":{"name":"Jack","lang":"EN"}}'
 ```
 
 The response includes the current mapping status (`clientNo` or `null`) and whether each key was `"applied"` or `"queued"`.
 
+- Read endpoints:
+  - `GET /v1/rooms/{roomId}/devices/{deviceId}/client-variables` — returns all client variables for the device.
+
+    ```json
+    {"clientNo": 7, "variables": {"name": "Jack", "lang": "EN"}}
+    ```
+
+    If the device has no `clientNo` mapping yet, returns `{"clientNo": null, "variables": {}}`.
+
+  - `GET /v1/rooms/{roomId}/devices/{deviceId}/client-variables/{name}` — returns a single variable.
+
+    ```json
+    {"clientNo": 7, "value": "Jack"}
+    ```
+
+    Returns `404` if the device is unmapped or the variable is not set.
+
+- Example:
+
+  ```bash
+  curl -sS "http://127.0.0.1:8800/v1/rooms/default_room/devices/00000000-0000-0000-0000-000000000000/client-variables"
+  curl -sS "http://127.0.0.1:8800/v1/rooms/default_room/devices/00000000-0000-0000-0000-000000000000/client-variables/name"
+  ```
+
 ### Global variables
 
 - Endpoint: `POST /v1/rooms/{roomId}/global-variables`
@@ -152,7 +178,7 @@ The response includes the current mapping status (`clientNo` or `null`) and whet
 
 ```json
 {
-  "vars": {
+  "variables": {
     "score": "42",
     "stage": "lobby"
   }
@@ -171,7 +197,33 @@ The response includes the current mapping status (`clientNo` or `null`) and whet
 ```bash
 curl -sS -X POST "http://127.0.0.1:8800/v1/rooms/default_room/global-variables" \
   -H "Content-Type: application/json" \
-  -d '{"vars":{"score":"42","stage":"lobby"}}'
+  -d '{"variables":{"score":"42","stage":"lobby"}}'
 ```
 
 The response includes the room ID and whether each key was `"applied"`, `"queued"`, or `"failed"`.
+
+- Read endpoints:
+  - `GET /v1/rooms/{roomId}/global-variables` — returns all global variables for the room.
+
+    ```json
+    {"variables": {"score": "42", "stage": "lobby"}}
+    ```
+
+  - `GET /v1/rooms/{roomId}/global-variables/{name}` — returns a single variable.
+
+    ```json
+    {"value": "42"}
+    ```
+
+    Returns `404` if the variable is not set.
+
+- Example:
+
+  ```bash
+  curl -sS "http://127.0.0.1:8800/v1/rooms/default_room/global-variables"
+  curl -sS "http://127.0.0.1:8800/v1/rooms/default_room/global-variables/score"
+  ```
+
+### 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.

{styly_netsync_server-0.10.4 → styly_netsync_server-0.11.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "styly-netsync-server"
-version = "0.10.4"
+version = "0.11.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.10.4 → styly_netsync_server-0.11.0}/src/styly_netsync/binary_serializer.py

@@ -6,7 +6,7 @@ from typing import Any
 logger = logging.getLogger(__name__)
 
 # Message type identifiers
-PROTOCOL_VERSION = 3
+PROTOCOL_VERSION = 4
 MSG_CLIENT_TRANSFORM = 1
 MSG_ROOM_TRANSFORM = 2  # Legacy room transform with short IDs only
 MSG_RPC = 3  # Remote procedure call
@@ -32,7 +32,7 @@ MSG_OBJECT_OWNERSHIP_REJECTED = 17  # Server → Client (ROUTER): request reject
 _max_virtual_transforms = 50
 MAX_VIRTUAL_TRANSFORMS = _max_virtual_transforms  # Legacy alias for backward compat
 
-# Protocol v3 transform encoding constants
+# Protocol v4 transform encoding constants
 ABS_POS_SCALE = 0.01
 LOCO_POS_SCALE = 0.01
 REL_POS_SCALE = 0.005
@@ -372,7 +372,7 @@ def _create_transform_dict(
 
 
 def _serialize_client_body(buffer: bytearray, client: dict[str, Any]) -> None:
-    """Serialize a client body in protocol v3 compact format."""
+    """Serialize a client body in protocol v4 compact format."""
     pose_seq = int(client.get("poseSeq", 0)) & 0xFFFF
     head = client.get("head", {}) or {}
     right = client.get("rightHand", {}) or {}
@@ -380,6 +380,7 @@ def _serialize_client_body(buffer: bytearray, client: dict[str, Any]) -> None:
     virtuals = client.get("virtuals", []) or []
     has_xr_origin_delta = (
         "xrOriginDeltaX" in client
+        or "xrOriginDeltaY" in client
         or "xrOriginDeltaZ" in client
         or "xrOriginDeltaYaw" in client
     )
@@ -421,6 +422,7 @@ def _serialize_client_body(buffer: bytearray, client: dict[str, Any]) -> None:
     virtual_valid = head_valid and bool(flags & POSE_FLAG_VIRTUALS_VALID)
 
     xr_origin_delta_x = float(client.get("xrOriginDeltaX", 0.0))
+    xr_origin_delta_y = float(client.get("xrOriginDeltaY", 0.0))
     xr_origin_delta_z = float(client.get("xrOriginDeltaZ", 0.0))
     xr_origin_delta_yaw = float(client.get("xrOriginDeltaYaw", 0.0))
     head_pos = _transform_get_position(head)
@@ -430,8 +432,9 @@ def _serialize_client_body(buffer: bytearray, client: dict[str, Any]) -> None:
     if physical_valid:
         buffer.extend(
             struct.pack(
-                "<hhh",
+                "<hhhh",
                 _quantize_signed(xr_origin_delta_x, LOCO_POS_SCALE),
+                _quantize_signed(xr_origin_delta_y, LOCO_POS_SCALE),
                 _quantize_signed(xr_origin_delta_z, LOCO_POS_SCALE),
                 _quantize_signed(xr_origin_delta_yaw, PHYSICAL_YAW_SCALE),
             )
@@ -849,7 +852,7 @@ def deserialize(data: bytes) -> tuple[int, dict[str, Any] | None, bytes]:
 
 
 def _deserialize_client_body(data: bytes, offset: int) -> tuple[dict[str, Any], int]:
-    """Deserialize protocol v3 compact pose body."""
+    """Deserialize protocol v4 compact pose body."""
     result: dict[str, Any] = {}
     result["poseSeq"] = struct.unpack("<H", data[offset : offset + 2])[0]
     offset += 2
@@ -874,6 +877,7 @@ def _deserialize_client_body(data: bytes, offset: int) -> tuple[dict[str, Any],
     head_pos = (0.0, 0.0, 0.0)
     head_rot = (0.0, 0.0, 0.0, 1.0)
     xr_origin_delta_x = 0.0
+    xr_origin_delta_y = 0.0
     xr_origin_delta_z = 0.0
     xr_origin_delta_yaw = 0.0
 
@@ -882,11 +886,12 @@ def _deserialize_client_body(data: bytes, offset: int) -> tuple[dict[str, Any],
             raise ValueError(
                 "PhysicalValid set but XROrigin delta encoding flag is missing"
             )
-        dx_q, dz_q, dyaw_q = struct.unpack("<hhh", data[offset : offset + 6])
+        dx_q, dy_q, dz_q, dyaw_q = struct.unpack("<hhhh", data[offset : offset + 8])
         xr_origin_delta_x = _dequantize_signed(dx_q, LOCO_POS_SCALE)
+        xr_origin_delta_y = _dequantize_signed(dy_q, LOCO_POS_SCALE)
         xr_origin_delta_z = _dequantize_signed(dz_q, LOCO_POS_SCALE)
         xr_origin_delta_yaw = _dequantize_signed(dyaw_q, PHYSICAL_YAW_SCALE)
-        offset += 6
+        offset += 8
 
     if head_valid:
         hx_q, offset = _unpack_int24_le(data, offset)
@@ -913,7 +918,7 @@ def _deserialize_client_body(data: bytes, offset: int) -> tuple[dict[str, Any],
 
     if physical_valid and head_valid:
         translated_x = head_pos[0] - xr_origin_delta_x
-        translated_y = head_pos[1]
+        translated_y = head_pos[1] - xr_origin_delta_y
         translated_z = head_pos[2] - xr_origin_delta_z
         physical_pos = _rotate_yaw_vector(
             translated_x,
@@ -1041,6 +1046,7 @@ def _deserialize_client_body(data: bytes, offset: int) -> tuple[dict[str, Any],
             )
 
     result["xrOriginDeltaX"] = xr_origin_delta_x
+    result["xrOriginDeltaY"] = xr_origin_delta_y
     result["xrOriginDeltaZ"] = xr_origin_delta_z
     result["xrOriginDeltaYaw"] = xr_origin_delta_yaw
     result["physical"] = physical
@@ -1052,7 +1058,7 @@ def _deserialize_client_body(data: bytes, offset: int) -> tuple[dict[str, Any],
 
 
 def _deserialize_client_transform(data: bytes, offset: int) -> dict[str, Any]:
-    """Deserialize client pose (v3) from binary data."""
+    """Deserialize client pose (v4) from binary data."""
     result: dict[str, Any] = {}
 
     protocol_version = data[offset]
@@ -1090,7 +1096,7 @@ def _deserialize_rpc_message(data: bytes, offset: int) -> dict[str, Any]:
 
 
 def _deserialize_room_transform(data: bytes, offset: int) -> dict[str, Any]:
-    """Deserialize room pose (v3) with client numbers only."""
+    """Deserialize room pose (v4) with client numbers only."""
     result: dict[str, Any] = {}
 
     protocol_version = data[offset]

{styly_netsync_server-0.10.4 → styly_netsync_server-0.11.0}/src/styly_netsync/rest_bridge.py

@@ -29,7 +29,7 @@ VarValue = Annotated[str, StringConstraints(max_length=MAX_VALUE)]
 class UpsertBody(BaseModel):
     """Request body for client or global variable upsert."""
 
-    vars: dict[VarName, VarValue] = Field(default_factory=dict)
+    variables: dict[VarName, VarValue] = Field(default_factory=dict)
 
 
 class PreseedStore:
@@ -187,6 +187,25 @@ class RoomBridge:
             logger.debug("Failed to lookup client number for %s: %s", device_id, exc)
             return None
 
+    def get_global_variables(self) -> dict[str, str]:
+        """Return a snapshot of cached global variables for this room."""
+        try:
+            return self._manager.get_all_global_variables()
+        except Exception as exc:  # pragma: no cover - defensive
+            logger.debug("get_all_global_variables failed: %s", exc)
+            return {}
+
+    def get_client_variables(self, device_id: str) -> tuple[int | None, dict[str, str]]:
+        """Return (client_no, snapshot) for device; client_no is None if unmapped."""
+        client_no = self.get_client_no(device_id)
+        if client_no is None:
+            return None, {}
+        try:
+            return client_no, self._manager.get_all_client_variables(client_no)
+        except Exception as exc:  # pragma: no cover - defensive
+            logger.debug("get_all_client_variables failed: %s", exc)
+            return client_no, {}
+
     def _apply_to_client(self, client_no: int, kvs: dict[str, str]) -> set[str]:
         """Apply stored variables to the target client via set_client_variable."""
         applied: set[str] = set()
@@ -308,15 +327,15 @@ def create_app(server_addr: str, dealer_port: int, sub_port: int) -> FastAPI:
 
     @app.post("/v1/rooms/{room_id}/devices/{device_id}/client-variables")
     def upsert(room_id: str, device_id: str, body: UpsertBody) -> dict[str, object]:
-        if not body.vars:
-            raise HTTPException(status_code=400, detail="vars must not be empty")
+        if not body.variables:
+            raise HTTPException(status_code=400, detail="variables must not be empty")
         try:
-            store.upsert(room_id, device_id, body.vars)
+            store.upsert(room_id, device_id, body.variables)
         except ValueError as exc:
             raise HTTPException(status_code=409, detail=str(exc)) from exc
 
         bridge = manager.get(room_id)
-        statuses = bridge.apply_now_or_queue(device_id, body.vars)
+        statuses = bridge.apply_now_or_queue(device_id, body.variables)
         client_no = bridge.get_client_no(device_id)
 
         return {
@@ -328,15 +347,15 @@ def create_app(server_addr: str, dealer_port: int, sub_port: int) -> FastAPI:
 
     @app.post("/v1/rooms/{room_id}/global-variables")
     def upsert_global(room_id: str, body: UpsertBody) -> dict[str, object]:
-        if not body.vars:
-            raise HTTPException(status_code=400, detail="vars must not be empty")
+        if not body.variables:
+            raise HTTPException(status_code=400, detail="variables must not be empty")
 
         bridge = manager.get(room_id)
-        statuses = bridge.apply_global_now_or_queue(body.vars)
+        statuses = bridge.apply_global_now_or_queue(body.variables)
 
         # Only store variables that were queued (not applied immediately)
         queued = {
-            name: body.vars[name]
+            name: body.variables[name]
             for name, state in statuses.items()
             if state != "applied"
         }
@@ -351,6 +370,45 @@ def create_app(server_addr: str, dealer_port: int, sub_port: int) -> FastAPI:
             "result": {name: {"state": state} for name, state in statuses.items()},
         }
 
+    @app.get("/v1/rooms/{room_id}/global-variables")
+    def get_global_variables(room_id: str) -> dict[str, object]:
+        bridge = manager.get(room_id)
+        return {"variables": bridge.get_global_variables()}
+
+    @app.get("/v1/rooms/{room_id}/global-variables/{name}")
+    def get_global_variable(room_id: str, name: VarName) -> dict[str, object]:
+        bridge = manager.get(room_id)
+        variables = bridge.get_global_variables()
+        if name not in variables:
+            raise HTTPException(
+                status_code=404, detail=f"Global variable '{name}' not found"
+            )
+        return {"value": variables[name]}
+
+    @app.get("/v1/rooms/{room_id}/devices/{device_id}/client-variables")
+    def get_client_variables(room_id: str, device_id: str) -> dict[str, object]:
+        bridge = manager.get(room_id)
+        client_no, variables = bridge.get_client_variables(device_id)
+        return {"clientNo": client_no, "variables": variables}
+
+    @app.get("/v1/rooms/{room_id}/devices/{device_id}/client-variables/{name}")
+    def get_client_variable(
+        room_id: str, device_id: str, name: VarName
+    ) -> dict[str, object]:
+        bridge = manager.get(room_id)
+        client_no, variables = bridge.get_client_variables(device_id)
+        if client_no is None:
+            raise HTTPException(
+                status_code=404,
+                detail=f"Device '{device_id}' has no client mapping",
+            )
+        if name not in variables:
+            raise HTTPException(
+                status_code=404,
+                detail=f"Client variable '{name}' not found for device '{device_id}'",
+            )
+        return {"clientNo": client_no, "value": variables[name]}
+
     return app
 
 

{styly_netsync_server-0.10.4 → styly_netsync_server-0.11.0}/src/styly_netsync/server.py

@@ -1056,7 +1056,7 @@ class NetSyncServer:
                         except UnicodeDecodeError as e:
                             logger.error(f"Failed to decode room ID: {e}")
                             continue
-                        # Protocol v3 binary-only handling (no JSON fallback)
+                        # Protocol v4 binary-only handling (no JSON fallback)
                         try:
                             msg_type, data, raw_payload = binary_serializer.deserialize(
                                 message_bytes
@@ -1127,7 +1127,7 @@ class NetSyncServer:
                                 logger.warning(f"Unknown binary msg_type: {msg_type}")
                         except Exception as e:
                             logger.warning(
-                                "Failed to decode protocol v3 message from room %s: %s",
+                                "Failed to decode protocol v4 message from room %s: %s",
                                 room_id,
                                 e,
                             )

{styly_netsync_server-0.10.4 → styly_netsync_server-0.11.0}/src/styly_netsync_server.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: styly-netsync-server
-Version: 0.10.4
+Version: 0.11.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,12 +81,14 @@ styly-netsync-simulator --server tcp://localhost --room my_room --clients 50
 
 ## Wire protocol compatibility
 
-- Current transform wire protocol is `protocolVersion = 3`.
-- Transform messages use `MSG_CLIENT_POSE` (11) and `MSG_ROOM_POSE` (12) with the compact V3 pose body.
-- Legacy transform protocol v2 and JSON transform fallback are not supported.
+- Current transform wire protocol is `protocolVersion = 4`.
+- Transform messages use `MSG_CLIENT_POSE` (11) and `MSG_ROOM_POSE` (12) with the compact V4 pose body.
+- v4 vs. v3: `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 (e.g. elevators).
+- Legacy transform protocols (v2/v3) and JSON transform fallback are not supported.
 - Deploy Unity and Python updates together when changing transform protocol behavior.
-- Protocol v3 position quantization ranges:
-  - Absolute (`physicalPos`, `headPosAbs`): signed `int24` at `0.01 m` per unit, per-axis range `[-83,886.08 m, 83,886.07 m]`.
+- Protocol v4 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 (`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.
   - Head-relative (`right/left/virtual`): signed `int16` at `0.005 m` per unit, per-axis range `[-163.84 m, 163.835 m]`.
 - These are encoding limits, not a hard world-size cap. Worlds can be larger, but encoded axis values are clamped if they exceed the representable range.
 
@@ -94,18 +96,18 @@ styly-netsync-simulator --server tcp://localhost --room my_room --clients 50
 
 The following options summarize trade-offs when expanding absolute-position range.
 
-Assumed baseline (`protocolVersion=3`):
-- Client pose body with `Physical+Head+Right+Left` valid and `virtualCount=0`: `49 bytes`
-- Room per-client entry (`clientNo + poseTime + clientBody`): `59 bytes`
+Assumed baseline (`protocolVersion=4`):
+- 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`.
 
 | Option | Absolute Position Encoding | Per-axis Range | Client Body Delta | Room Per-client Delta |
 |---|---|---:|---:|---:|
-| A. Coarser scale (current integer width) | `int24 @ 0.02m` | `[-167,772.16m, 167,772.14m]` | `+0B` (`49 -> 49`) | `+0B` (`59 -> 59`) |
-| B. Cell + local | `cell(i16, 256m) + local(int24 @ 0.01m)` | `[-8,472,494.08m, 8,472,238.07m]` | `+6B` (`49 -> 55`, `+12.2%`) | `+6B` (`59 -> 65`, `+10.2%`) |
-| C. Cell + local (large cell) | `cell(i16, 1024m) + local(int24 @ 0.01m)` | `[-33,638,318.08m, 33,637,294.07m]` | `+6B` (`49 -> 55`, `+12.2%`) | `+6B` (`59 -> 65`, `+10.2%`) |
+| A. Coarser scale (current integer width) | `int24 @ 0.02m` | `[-167,772.16m, 167,772.14m]` | `+0B` (`46 -> 46`) | `+0B` (`56 -> 56`) |
+| B. Cell + local | `cell(i16, 256m) + local(int24 @ 0.01m)` | `[-8,472,494.08m, 8,472,238.07m]` | `+6B` (`46 -> 52`, `+13.0%`) | `+6B` (`56 -> 62`, `+10.7%`) |
+| C. Cell + local (large cell) | `cell(i16, 1024m) + local(int24 @ 0.01m)` | `[-33,638,318.08m, 33,637,294.07m]` | `+6B` (`46 -> 52`, `+13.0%`) | `+6B` (`56 -> 62`, `+10.7%`) |
 
 Notes:
-- Option B/C deltas assume both absolute transforms are present (`physicalPos` and `headPosAbs`).
+- Only `headPosAbs` is on the wire as an absolute field; `physicalPos` is reconstructed from `headPosAbs + xrOriginDelta`. Option B/C deltas therefore apply to `headPosAbs` only.
 - Option B/C can reduce average overhead if `cell` is transmitted only when changed, but that requires extra state and flags in the wire format.
 
 ## Configuration
@@ -160,7 +162,7 @@ The server launches an embedded FastAPI application that exposes REST endpoints
 
 ```json
 {
-  "vars": {
+  "variables": {
     "name": "Jack",
     "lang": "EN"
   }
@@ -179,11 +181,35 @@ The server launches an embedded FastAPI application that exposes REST endpoints
 ```bash
 curl -sS -X POST "http://127.0.0.1:8800/v1/rooms/default_room/devices/00000000-0000-0000-0000-000000000000/client-variables" \
   -H "Content-Type: application/json" \
-  -d '{"vars":{"name":"Jack","lang":"EN"}}'
+  -d '{"variables":{"name":"Jack","lang":"EN"}}'
 ```
 
 The response includes the current mapping status (`clientNo` or `null`) and whether each key was `"applied"` or `"queued"`.
 
+- Read endpoints:
+  - `GET /v1/rooms/{roomId}/devices/{deviceId}/client-variables` — returns all client variables for the device.
+
+    ```json
+    {"clientNo": 7, "variables": {"name": "Jack", "lang": "EN"}}
+    ```
+
+    If the device has no `clientNo` mapping yet, returns `{"clientNo": null, "variables": {}}`.
+
+  - `GET /v1/rooms/{roomId}/devices/{deviceId}/client-variables/{name}` — returns a single variable.
+
+    ```json
+    {"clientNo": 7, "value": "Jack"}
+    ```
+
+    Returns `404` if the device is unmapped or the variable is not set.
+
+- Example:
+
+  ```bash
+  curl -sS "http://127.0.0.1:8800/v1/rooms/default_room/devices/00000000-0000-0000-0000-000000000000/client-variables"
+  curl -sS "http://127.0.0.1:8800/v1/rooms/default_room/devices/00000000-0000-0000-0000-000000000000/client-variables/name"
+  ```
+
 ### Global variables
 
 - Endpoint: `POST /v1/rooms/{roomId}/global-variables`
@@ -191,7 +217,7 @@ The response includes the current mapping status (`clientNo` or `null`) and whet
 
 ```json
 {
-  "vars": {
+  "variables": {
     "score": "42",
     "stage": "lobby"
   }
@@ -210,7 +236,33 @@ The response includes the current mapping status (`clientNo` or `null`) and whet
 ```bash
 curl -sS -X POST "http://127.0.0.1:8800/v1/rooms/default_room/global-variables" \
   -H "Content-Type: application/json" \
-  -d '{"vars":{"score":"42","stage":"lobby"}}'
+  -d '{"variables":{"score":"42","stage":"lobby"}}'
 ```
 
 The response includes the room ID and whether each key was `"applied"`, `"queued"`, or `"failed"`.
+
+- Read endpoints:
+  - `GET /v1/rooms/{roomId}/global-variables` — returns all global variables for the room.
+
+    ```json
+    {"variables": {"score": "42", "stage": "lobby"}}
+    ```
+
+  - `GET /v1/rooms/{roomId}/global-variables/{name}` — returns a single variable.
+
+    ```json
+    {"value": "42"}
+    ```
+
+    Returns `404` if the variable is not set.
+
+- Example:
+
+  ```bash
+  curl -sS "http://127.0.0.1:8800/v1/rooms/default_room/global-variables"
+  curl -sS "http://127.0.0.1:8800/v1/rooms/default_room/global-variables/score"
+  ```
+
+### 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.

{styly_netsync_server-0.10.4 → styly_netsync_server-0.11.0}/tests/test_binary_serializer.py

@@ -220,6 +220,7 @@ def _build_random_client_pose(
     )
     head_rot = _random_unit_quaternion(rng)
     xr_origin_delta_x = rng.uniform(-20.0, 20.0)
+    xr_origin_delta_y = rng.uniform(-5.0, 5.0)
     xr_origin_delta_z = rng.uniform(-20.0, 20.0)
     xr_origin_delta_yaw = rng.uniform(-180.0, 180.0)
 
@@ -249,6 +250,7 @@ def _build_random_client_pose(
         "poseSeq": rng.randint(0, 65535),
         "flags": 0x3E,  # Physical + Head + Right + Left + Virtuals
         "xrOriginDeltaX": xr_origin_delta_x,
+        "xrOriginDeltaY": xr_origin_delta_y,
         "xrOriginDeltaZ": xr_origin_delta_z,
         "xrOriginDeltaYaw": xr_origin_delta_yaw,
         "head": _build_transform(head_pos, head_rot),
@@ -259,11 +261,15 @@ def _build_random_client_pose(
 
 
 def _reconstruct_physical_from_head_and_delta(
-    head: dict[str, float], delta_x: float, delta_z: float, delta_yaw: float
+    head: dict[str, float],
+    delta_x: float,
+    delta_y: float,
+    delta_z: float,
+    delta_yaw: float,
 ) -> tuple[tuple[float, float, float], tuple[float, float, float, float]]:
     """Reconstruct yaw-only physical pose from head pose and XROrigin delta."""
     tx = head["posX"] - delta_x
-    ty = head["posY"]
+    ty = head["posY"] - delta_y
     tz = head["posZ"] - delta_z
 
     inv_yaw_rad = math.radians(-delta_yaw)
@@ -282,12 +288,12 @@ def _reconstruct_physical_from_head_and_delta(
     return (px, ty, pz), physical_rot
 
 
-class TestTransformSerializationV3:
-    """Tests for protocol v3 transform compact serialization."""
+class TestTransformSerializationV4:
+    """Tests for protocol v4 transform compact serialization."""
 
-    def test_protocol_version_is_v3(self) -> None:
-        """Protocol version constant should be updated to v3."""
-        assert binary_serializer.PROTOCOL_VERSION == 3
+    def test_protocol_version_is_v4(self) -> None:
+        """Protocol version constant should be at v4."""
+        assert binary_serializer.PROTOCOL_VERSION == 4
 
     def test_client_roundtrip_without_flags_infers_valid_bits(self) -> None:
         """Serializer should infer valid bits when flags are omitted."""
@@ -295,6 +301,7 @@ class TestTransformSerializationV3:
             "deviceId": "infer-flags",
             "poseSeq": 77,
             "xrOriginDeltaX": 1.25,
+            "xrOriginDeltaY": 0.4,
             "xrOriginDeltaZ": -2.5,
             "xrOriginDeltaYaw": 33.3,
             "head": _build_transform(
@@ -331,6 +338,7 @@ class TestTransformSerializationV3:
         assert abs(decoded["head"]["posY"] - 1.6) <= 0.01
         assert abs(decoded["head"]["posZ"] + 2.3) <= 0.01
         assert abs(decoded["xrOriginDeltaX"] - 1.25) <= 0.01
+        assert abs(decoded["xrOriginDeltaY"] - 0.4) <= 0.01
         assert abs(decoded["xrOriginDeltaZ"] + 2.5) <= 0.01
         assert abs(decoded["xrOriginDeltaYaw"] - 33.3) <= 0.1
         assert len(decoded["virtuals"]) == 1
@@ -349,6 +357,7 @@ class TestTransformSerializationV3:
                 | binary_serializer.POSE_FLAG_VIRTUALS_VALID
             ),
             "xrOriginDeltaX": 9.0,
+            "xrOriginDeltaY": 9.0,
             "xrOriginDeltaZ": 9.0,
             "xrOriginDeltaYaw": 9.0,
             "head": _build_transform(
@@ -409,7 +418,7 @@ class TestTransformSerializationV3:
 
             assert msg_type == binary_serializer.MSG_CLIENT_POSE
             assert decoded is not None
-            assert decoded["protocolVersion"] == 3
+            assert decoded["protocolVersion"] == 4
             assert len(raw) > 0
 
             o_head = original["head"]
@@ -466,15 +475,18 @@ class TestTransformSerializationV3:
             assert left_err <= 1.0
 
             o_dx = original["xrOriginDeltaX"]
+            o_dy = original["xrOriginDeltaY"]
             o_dz = original["xrOriginDeltaZ"]
             o_dyaw = original["xrOriginDeltaYaw"]
             assert abs(o_dx - decoded["xrOriginDeltaX"]) <= 0.01
+            assert abs(o_dy - decoded["xrOriginDeltaY"]) <= 0.01
             assert abs(o_dz - decoded["xrOriginDeltaZ"]) <= 0.01
             assert abs(o_dyaw - decoded["xrOriginDeltaYaw"]) <= 0.1
 
             expected_pos, expected_rot = _reconstruct_physical_from_head_and_delta(
                 decoded["head"],
                 decoded["xrOriginDeltaX"],
+                decoded["xrOriginDeltaY"],
                 decoded["xrOriginDeltaZ"],
                 decoded["xrOriginDeltaYaw"],
             )
@@ -518,6 +530,7 @@ class TestTransformSerializationV3:
             "poseSeq": 10,
             "flags": 0x3E,
             "xrOriginDeltaX": 9999.0,
+            "xrOriginDeltaY": 9999.0,
             "xrOriginDeltaZ": -9999.0,
             "xrOriginDeltaYaw": 9999.0,
             "head": _build_transform(
@@ -551,6 +564,7 @@ class TestTransformSerializationV3:
         assert min_abs <= decoded["head"]["posY"] <= max_abs
         assert min_abs <= decoded["head"]["posZ"] <= max_abs
         assert min_loco <= decoded["xrOriginDeltaX"] <= max_loco
+        assert min_loco <= decoded["xrOriginDeltaY"] <= max_loco
         assert min_loco <= decoded["xrOriginDeltaZ"] <= max_loco
         assert (
             binary_serializer.INT16_MIN * binary_serializer.PHYSICAL_YAW_SCALE
@@ -574,6 +588,7 @@ class TestTransformSerializationV3:
             "poseSeq": 33,
             "flags": 0x3E,
             "xrOriginDeltaX": 250.12,
+            "xrOriginDeltaY": -42.5,
             "xrOriginDeltaZ": -125.34,
             "xrOriginDeltaYaw": 179.9,
             "head": _build_transform(
@@ -595,16 +610,18 @@ class TestTransformSerializationV3:
         assert abs(decoded["head"]["posY"] + 5000.9) <= 0.01
         assert abs(decoded["head"]["posZ"] - 4321.01) <= 0.01
         assert abs(decoded["xrOriginDeltaX"] - 250.12) <= 0.01
+        assert abs(decoded["xrOriginDeltaY"] + 42.5) <= 0.01
         assert abs(decoded["xrOriginDeltaZ"] + 125.34) <= 0.01
         assert abs(decoded["xrOriginDeltaYaw"] - 179.9) <= 0.1
 
     def test_client_body_size_with_full_pose_no_virtuals(self) -> None:
-        """Full pose body (no virtuals) should match current protocol v3 byte size."""
+        """Full pose body (no virtuals) should match current protocol v4 byte size."""
         payload = {
             "deviceId": "size-check",
             "poseSeq": 1,
             "flags": 0x1E,  # Physical + Head + Right + Left
             "xrOriginDeltaX": 1.0,
+            "xrOriginDeltaY": 0.5,
             "xrOriginDeltaZ": 2.0,
             "xrOriginDeltaYaw": 10.0,
             "head": _build_transform(
@@ -621,7 +638,8 @@ class TestTransformSerializationV3:
         _, _, raw = binary_serializer.deserialize(
             binary_serializer.serialize_client_transform(payload)
         )
-        assert len(raw) == 44
+        # v4 added a Y component to xrOriginDelta (+2 bytes vs. v3's 44).
+        assert len(raw) == 46
 
     def test_physical_requires_delta_encoding_flag(self) -> None:
         """PhysicalValid frames must carry the XROrigin-delta encoding bit."""
@@ -633,6 +651,7 @@ class TestTransformSerializationV3:
                 | binary_serializer.POSE_FLAG_HEAD_VALID
             ),
             "xrOriginDeltaX": 1.0,
+            "xrOriginDeltaY": 0.3,
             "xrOriginDeltaZ": -2.0,
             "xrOriginDeltaYaw": 30.0,
             "head": _build_transform(
@@ -663,7 +682,7 @@ class TestTransformSerializationV3:
         c2["poseTime"] = 223.456
 
         room_payload = {
-            "roomId": "room-v3",
+            "roomId": "room-v4",
             "broadcastTime": 999.123,
             "clients": [c1, c2],
         }
@@ -672,8 +691,8 @@ class TestTransformSerializationV3:
 
         assert msg_type == binary_serializer.MSG_ROOM_POSE
         assert decoded is not None
-        assert decoded["protocolVersion"] == 3
-        assert decoded["roomId"] == "room-v3"
+        assert decoded["protocolVersion"] == 4
+        assert decoded["roomId"] == "room-v4"
         assert len(decoded["clients"]) == 2
 
         for src, dst in zip(room_payload["clients"], decoded["clients"], strict=True):
@@ -686,6 +705,28 @@ class TestTransformSerializationV3:
             assert abs(src_head["posY"] - dst_head["posY"]) <= 0.01
             assert abs(src_head["posZ"] - dst_head["posZ"]) <= 0.01
 
+    def test_foot_invariant_head_minus_physical_equals_delta_y(self) -> None:
+        """head.y - reconstructed physical.y must equal xrOriginDeltaY.
+
+        Follows by construction from `_deserialize_client_body`
+        (`translated_y = head_pos[1] - xr_origin_delta_y`) and the yaw-only
+        rotation that preserves Y. Pinning this protocol-shape invariant means
+        any future change that decouples the two (e.g. dropping delta_y from
+        the reconstruction, or adding extra Y transforms) breaks loudly here
+        rather than silently on the wire.
+        """
+        rng = random.Random(20260425)
+        for _ in range(200):
+            payload = _build_random_client_pose(rng, virtual_count=0)
+            _, decoded, _ = binary_serializer.deserialize(
+                binary_serializer.serialize_client_transform(payload)
+            )
+            assert decoded is not None
+            d_head = decoded["head"]
+            d_phys = decoded["physical"]
+            d_dy = decoded["xrOriginDeltaY"]
+            assert abs((d_head["posY"] - d_phys["posY"]) - d_dy) <= 1e-6
+
     def test_denormalized_quaternion_roundtrip(self) -> None:
         """Non-unit quaternions should be normalized and survive roundtrip."""
         # magnitude = 2.0

{styly_netsync_server-0.10.4 → styly_netsync_server-0.11.0}/tests/test_rest_bridge.py

@@ -177,14 +177,14 @@ class TestGlobalVariablesEndpoint:
     def test_post_returns_200(self, client: TestClient) -> None:
         resp = client.post(
             "/v1/rooms/room1/global-variables",
-            json={"vars": {"score": "42"}},
+            json={"variables": {"score": "42"}},
         )
         assert resp.status_code == 200
 
     def test_post_response_structure(self, client: TestClient) -> None:
         resp = client.post(
             "/v1/rooms/room1/global-variables",
-            json={"vars": {"score": "42"}},
+            json={"variables": {"score": "42"}},
         )
         body = resp.json()
         assert body["roomId"] == "room1"
@@ -194,7 +194,7 @@ class TestGlobalVariablesEndpoint:
     def test_post_empty_vars_returns_400(self, client: TestClient) -> None:
         resp = client.post(
             "/v1/rooms/room1/global-variables",
-            json={"vars": {}},
+            json={"variables": {}},
         )
         assert resp.status_code == 400
 
@@ -206,14 +206,14 @@ class TestGlobalVariablesEndpoint:
         long_name = "x" * 65
         resp = client.post(
             "/v1/rooms/room1/global-variables",
-            json={"vars": {long_name: "v"}},
+            json={"variables": {long_name: "v"}},
         )
         assert resp.status_code == 422
 
     def test_post_var_value_too_long_returns_422(self, client: TestClient) -> None:
         resp = client.post(
             "/v1/rooms/room1/global-variables",
-            json={"vars": {"k": "x" * 1025}},
+            json={"variables": {"k": "x" * 1025}},
         )
         assert resp.status_code == 422
 
@@ -240,7 +240,7 @@ class TestGlobalVariablesEndpoint:
                 tc = TestClient(app)
                 resp = tc.post(
                     "/v1/rooms/room_full/global-variables",
-                    json={"vars": {"overflow": "x"}},
+                    json={"variables": {"overflow": "x"}},
                 )
                 assert resp.status_code == 409
         finally:
@@ -263,10 +263,156 @@ class TestGlobalVariablesEndpoint:
                 tc = TestClient(app)
                 resp = tc.post(
                     "/v1/rooms/room1/global-variables",
-                    json={"vars": {"k": "v"}},
+                    json={"variables": {"k": "v"}},
                 )
                 assert resp.status_code == 200
                 # Store should remain empty since the var was applied
                 assert rest_bridge.global_store.get("room1") == {}
         finally:
             rest_bridge.global_store = original_store
+
+
+# ---------------------------------------------------------------------------
+# RoomBridge read method tests
+# ---------------------------------------------------------------------------
+
+
+class TestRoomBridgeReadMethods:
+    def test_get_global_variables_delegates_to_manager(self) -> None:
+        bridge = _make_bridge(client_no=1)
+        bridge._manager.get_all_global_variables.return_value = {"a": "1", "b": "2"}
+        result = bridge.get_global_variables()
+        assert result == {"a": "1", "b": "2"}
+        bridge._manager.get_all_global_variables.assert_called_once_with()
+
+    def test_get_global_variables_swallows_exceptions(self) -> None:
+        bridge = _make_bridge(client_no=1)
+        bridge._manager.get_all_global_variables.side_effect = RuntimeError("boom")
+        assert bridge.get_global_variables() == {}
+
+    def test_get_client_variables_unmapped_returns_none_and_empty(self) -> None:
+        bridge = _make_bridge(client_no=1)
+        bridge._manager.get_client_no.return_value = None
+        client_no, variables = bridge.get_client_variables("device-x")
+        assert client_no is None
+        assert variables == {}
+        bridge._manager.get_all_client_variables.assert_not_called()
+
+    def test_get_client_variables_mapped_returns_snapshot(self) -> None:
+        bridge = _make_bridge(client_no=1)
+        bridge._manager.get_client_no.return_value = 7
+        bridge._manager.get_all_client_variables.return_value = {"name": "alice"}
+        client_no, variables = bridge.get_client_variables("device-x")
+        assert client_no == 7
+        assert variables == {"name": "alice"}
+        bridge._manager.get_all_client_variables.assert_called_once_with(7)
+
+    def test_get_client_variables_swallows_exceptions(self) -> None:
+        bridge = _make_bridge(client_no=1)
+        bridge._manager.get_client_no.return_value = 7
+        bridge._manager.get_all_client_variables.side_effect = RuntimeError("boom")
+        client_no, variables = bridge.get_client_variables("device-x")
+        assert client_no == 7
+        assert variables == {}
+
+
+# ---------------------------------------------------------------------------
+# GET endpoint tests via TestClient
+# ---------------------------------------------------------------------------
+
+
+def _make_get_client(mock_bridge: MagicMock) -> TestClient:
+    """Build a TestClient whose BridgeManager always returns the given bridge."""
+    with patch("styly_netsync.rest_bridge.BridgeManager") as MockBM:
+        MockBM.return_value.get.return_value = mock_bridge
+        app = create_app("localhost", 5555, 5556)
+        return TestClient(app)
+
+
+class TestGlobalVariablesGetEndpoint:
+    def test_get_all_returns_snapshot(self) -> None:
+        mock_bridge = MagicMock()
+        mock_bridge.get_global_variables.return_value = {"score": "10", "level": "3"}
+        tc = _make_get_client(mock_bridge)
+        resp = tc.get("/v1/rooms/room1/global-variables")
+        assert resp.status_code == 200
+        assert resp.json() == {"variables": {"score": "10", "level": "3"}}
+
+    def test_get_all_returns_empty_when_cache_empty(self) -> None:
+        mock_bridge = MagicMock()
+        mock_bridge.get_global_variables.return_value = {}
+        tc = _make_get_client(mock_bridge)
+        resp = tc.get("/v1/rooms/room1/global-variables")
+        assert resp.status_code == 200
+        assert resp.json() == {"variables": {}}
+
+    def test_get_single_returns_value(self) -> None:
+        mock_bridge = MagicMock()
+        mock_bridge.get_global_variables.return_value = {"score": "10"}
+        tc = _make_get_client(mock_bridge)
+        resp = tc.get("/v1/rooms/room1/global-variables/score")
+        assert resp.status_code == 200
+        assert resp.json() == {"value": "10"}
+
+    def test_get_single_missing_returns_404(self) -> None:
+        mock_bridge = MagicMock()
+        mock_bridge.get_global_variables.return_value = {}
+        tc = _make_get_client(mock_bridge)
+        resp = tc.get("/v1/rooms/room1/global-variables/missing")
+        assert resp.status_code == 404
+
+    def test_get_single_name_too_long_returns_422(self) -> None:
+        mock_bridge = MagicMock()
+        mock_bridge.get_global_variables.return_value = {}
+        tc = _make_get_client(mock_bridge)
+        long_name = "x" * 65
+        resp = tc.get(f"/v1/rooms/room1/global-variables/{long_name}")
+        assert resp.status_code == 422
+
+
+class TestClientVariablesGetEndpoint:
+    def test_get_all_unknown_device_returns_null_mapping_and_empty(self) -> None:
+        mock_bridge = MagicMock()
+        mock_bridge.get_client_variables.return_value = (None, {})
+        tc = _make_get_client(mock_bridge)
+        resp = tc.get("/v1/rooms/room1/devices/device-x/client-variables")
+        assert resp.status_code == 200
+        assert resp.json() == {"clientNo": None, "variables": {}}
+
+    def test_get_all_mapped_device_returns_snapshot(self) -> None:
+        mock_bridge = MagicMock()
+        mock_bridge.get_client_variables.return_value = (7, {"name": "alice"})
+        tc = _make_get_client(mock_bridge)
+        resp = tc.get("/v1/rooms/room1/devices/device-x/client-variables")
+        assert resp.status_code == 200
+        assert resp.json() == {"clientNo": 7, "variables": {"name": "alice"}}
+
+    def test_get_single_returns_value(self) -> None:
+        mock_bridge = MagicMock()
+        mock_bridge.get_client_variables.return_value = (7, {"name": "alice"})
+        tc = _make_get_client(mock_bridge)
+        resp = tc.get("/v1/rooms/room1/devices/device-x/client-variables/name")
+        assert resp.status_code == 200
+        assert resp.json() == {"clientNo": 7, "value": "alice"}
+
+    def test_get_single_unknown_device_returns_404(self) -> None:
+        mock_bridge = MagicMock()
+        mock_bridge.get_client_variables.return_value = (None, {})
+        tc = _make_get_client(mock_bridge)
+        resp = tc.get("/v1/rooms/room1/devices/device-x/client-variables/name")
+        assert resp.status_code == 404
+
+    def test_get_single_missing_variable_returns_404(self) -> None:
+        mock_bridge = MagicMock()
+        mock_bridge.get_client_variables.return_value = (7, {})
+        tc = _make_get_client(mock_bridge)
+        resp = tc.get("/v1/rooms/room1/devices/device-x/client-variables/name")
+        assert resp.status_code == 404
+
+    def test_get_single_name_too_long_returns_422(self) -> None:
+        mock_bridge = MagicMock()
+        mock_bridge.get_client_variables.return_value = (7, {})
+        tc = _make_get_client(mock_bridge)
+        long_name = "x" * 65
+        resp = tc.get(f"/v1/rooms/room1/devices/device-x/client-variables/{long_name}")
+        assert resp.status_code == 422