Download and install headtracking

headtracking is published as a preview on GitHub. Each release has one archive per system, containing the VPX plugin and the demo app. The file names include the version number, so pick the file for your system on the releases page.

Open the releases page

There is currently no build for Intel Macs or Windows on ARM. The Windows files are digitally signed, and the macOS programs are signed and notarized by Apple.

What is in the archive

• The plugin: headtracking.dll (Windows), libheadtracking.so (Linux) or libheadtracking.dylib (macOS), with its plugin.cfg.
• headtracking-demo, the demo app: test your camera without VPX, and share a capture of your cabinet.
• On Windows, a setup folder with the Kinect driver installer.
• The licence and the README.

Install the plugin in Visual Pinball X

You need Visual Pinball X 10.8.1 or later.

1. Create a headtracking folder in the plugins folder of your VPX installation, and copy the plugin library and plugin.cfg into it. Both must be in the same folder.

   <VPX_install>/plugins/headtracking/
   ├── plugin.cfg
   ├── headtracking.dll          (Windows)
   ├── libheadtracking.so        (Linux)
   └── libheadtracking.dylib     (macOS)

2. Start VPX once: it finds the new plugin by itself.
3. Load any table, press F12 → Plugin Settings → Head Tracking and tick Enable. Quit and reload the table: tracking starts with the game.

Set up the view

The plugin reminds you of these points in a notification when a game starts.

1. In F12 → Cabinet Settings, enter your real lockbar width and screen inclination. The automatic calibration and the head position are based on them.
2. For the table's point of view, choose the Window view layout with rotation 0, and turn on cabinet autofit. Window is the layout designed for head tracking.
3. Stand in your normal playing position while the table loads: the first stable head position becomes the neutral position. Later, hold the lockbar button for 2 seconds to recenter.

Settings

Every setting is on the same F12 → Plugin Settings → Head Tracking page and applies live while you play, except Backend and Camera, which are read when the game starts (reload the table after changing them).

They are stored in VPinballX.ini, in the [Plugin.HeadTracking] section. If you edit that file by hand, do it with VPX closed: VPX rewrites the whole file when it exits.

Linux

• Webcam: your user must be allowed to use the camera. On most distributions it already is (the video group); otherwise run sudo usermod -aG video "$USER" and log out and back in.
• Kinect: without udev rules, only the administrator can open the Kinect, and VPX fails silently. If a Kinect is plugged in but missing from its camera list, the demo app offers an Install udev rule button, which asks for your password. You can also add the rules yourself, then unplug and replug the Kinect:
  udev rules for Kinect v2 and Kinect v1

  sudo tee /etc/udev/rules.d/90-kinect2.rules > /dev/null <<'EOF'
  # Microsoft Kinect v2 (Xbox One)
  SUBSYSTEM=="usb", ATTR{idVendor}=="045e", ATTR{idProduct}=="02c4", MODE="0666"
  SUBSYSTEM=="usb", ATTR{idVendor}=="045e", ATTR{idProduct}=="02d8", MODE="0666"
  SUBSYSTEM=="usb", ATTR{idVendor}=="045e", ATTR{idProduct}=="02d9", MODE="0666"
  EOF
  sudo tee /etc/udev/rules.d/51-kinect.rules > /dev/null <<'EOF'
  # Microsoft Kinect v1 (Xbox 360) and Kinect for Windows v1
  SUBSYSTEM=="usb", ATTR{idVendor}=="045e", ATTR{idProduct}=="02b0", MODE="0666"
  SUBSYSTEM=="usb", ATTR{idVendor}=="045e", ATTR{idProduct}=="02ad", MODE="0666"
  SUBSYSTEM=="usb", ATTR{idVendor}=="045e", ATTR{idProduct}=="02ae", MODE="0666"
  SUBSYSTEM=="usb", ATTR{idVendor}=="045e", ATTR{idProduct}=="02c2", MODE="0666"
  SUBSYSTEM=="usb", ATTR{idVendor}=="045e", ATTR{idProduct}=="02be", MODE="0666"
  SUBSYSTEM=="usb", ATTR{idVendor}=="045e", ATTR{idProduct}=="02bf", MODE="0666"
  EOF
  sudo udevadm control --reload-rules
  sudo udevadm trigger

• No other library to install: only system libraries present by default on Debian, Ubuntu, Fedora and Arch are used.

Windows

Out of the box, Windows installs no usable driver for a Kinect v1 or v2: it shows up as an unknown device. To install one:

1. Plug in the Kinect and start headtracking-demo.exe. If no usable driver is found, a yellow banner offers Install Kinect drivers (UAC prompt). You can also double-click setup\setup-kinect.cmd.
2. Accept the administrator prompt. The PowerShell window lists what will change and asks you to type yes; anything else cancels without touching the system.
3. Wait for the script to finish (about 10 to 30 seconds), click rescan in the demo, then restart VPX.

The script is signed in release archives. It works for both Kinect v1 and v2. If you prefer not to run it, you can bind WinUSB by hand with Zadig; the steps are in the detailed install guide. On Windows 7, install Microsoft Security Advisory 3033929 first.

A Kinect v2 also needs a dedicated USB 3.0 port on the back of the motherboard, not a hub.

macOS

A Kinect needs no extra driver on macOS. For a webcam, allow VPX in System Settings → Privacy & Security → Camera the first time. The build runs natively on Apple silicon.

Build from source

You need a recent stable Rust, cmake 3.20 or later and libclang. The native libraries are included as submodules and built statically.

git clone --recurse-submodules https://github.com/Le-Syl21/headtracking
cd headtracking
cargo build --release

Full details, including every Windows and Linux troubleshooting step: docs/INSTALL.md.