BudsVR Simulator for Unity

MVP build for a 3DoF VR headset rotation simulator driven by Galaxy Buds Pro-style quaternion packets. This first phase intentionally ships with a Python UDP mock bridge, so the Unity camera pipeline can be tested before real Bluetooth integration is added.

What It Does

• Sends real-time mock head orientation as UDP JSON.
• Receives packets in Unity on a background thread.
• Applies rotation to Main Camera, an XR camera, or any custom Transform.
• Supports recenter with R.
• Supports smoothing, deadzone, spike rejection, sensitivity, yaw-only/pitch-yaw/full rotation modes, and axis inversion.
• Shows a lightweight Game View debug HUD with packet rate, latency, sequence, Euler values, and connection state.

What It Does Not Do Yet

• It is not a real VR headset.
• It does not provide positional 6DoF tracking.
• It does not include the real Galaxy Buds Pro Bluetooth reader yet.
• It does not render stereo VR output.

Architecture Summary

The MVP is split into two parts:

1. tools/BudsHeadtrackingBridge.py generates sinusoidal yaw, pitch, and roll, converts it to a normalized quaternion, and sends JSON packets to Unity over UDP.
2. Assets/BudsVRSimulator/Runtime receives UDP packets, validates quaternion data, applies recenter and smoothing, then rotates the configured Unity transform on the main thread.

The JSON packet shape already matches the planned real bridge:

{
  "type": "buds_headtracking",
  "timestamp": 1710000000.123,
  "sequence": 12345,
  "quaternion": { "x": 0.0123, "y": 0.0345, "z": 0.0567, "w": 0.9981 },
  "raw": { "x": 0.0123, "y": 0.0345, "z": 0.0567, "w": 0.9981 },
  "status": "tracking"
}

Quick Start

1. Open this folder as a Unity project or copy Assets/BudsVRSimulator into an existing Unity 2021.3+ project.
2. Add BudsHeadtrackingReceiver to an empty GameObject named BudsVR Simulator.
3. Add BudsHeadtrackingApplier to the same GameObject.
4. Assign your Main Camera or XR camera to the applier Target field. If left empty, it will try to use Camera.main.
5. Add BudsDebugHud to the same GameObject.
6. Enter Play Mode.
7. In a terminal, run:

python .\tools\BudsHeadtrackingBridge.py --mock --host 127.0.0.1 --port 7777 --rate-limit 90 --verbose

The camera should begin rotating with the mock head motion. Press R to recenter and F1 to toggle the HUD.

Main Unity Components

• BudsHeadtrackingReceiver: UDP JSON receiver and connection diagnostics.
• BudsHeadtrackingApplier: rotation mapping, recenter, smoothing, and target transform application.
• BudsRecenter: neutral-forward offset storage.
• BudsSmoothingFilter: Slerp, exponential, and low-pass smoothing.
• BudsDebugHud: Game View diagnostics overlay.

Recommended MVP Settings

• Receiver Port: 7777
• Receiver Use Latest Only: enabled
• Applier Apply In Late Update: enabled
• Applier Use Local Rotation: enabled for cameras under rigs/XR Origins
• Applier Apply Mode: AddToInitialRotation
• Smoothing mode: Slerp
• Smoothing value: 0.1 to 0.3
• Recenter key: R

Assumptions

• The Python mock quaternion uses a Unity-friendly yaw(Y), pitch(X), roll(Z) convention.
• Real Galaxy Buds Pro axis mapping may differ by firmware/device path and will be calibrated in phase 2.
• UDP localhost is the only implemented transport in MVP.

Roadmap

• Real BudsPro-Headtracking Bluetooth reader.
• Coordinate mapping presets and calibration wizard.
• Unity Editor window.
• XR Origin sample scene.
• Recording/playback.
• WebSocket/TCP/binary transport options.
• Ray interaction and controller simulation helpers.