Virtual Joystick

Map head tracking to virtual joystick axes using vJoy driver

The Virtual Joystick protocol allows you to map head tracking movements to a virtual joystick device. This enables head tracking in games that support joystick input but don’t have native head tracking support.

How It Works

The protocol:

1. Connects to the vJoy virtual joystick driver
2. Maps your 6 head tracking axes (X, Y, Z, Pitch, Yaw, Roll) to 6 joystick axes
3. Scales values to fit joystick axis ranges
4. Updates the virtual joystick in real-time as you move your head

Axis Mapping

OpenTrack maps tracking data to these HID joystick axes:

Tracking Axis	Joystick Axis	HID Usage
X Position	X	HID_USAGE_X
Y Position	Y	HID_USAGE_Y
Z Position	Z	HID_USAGE_Z
Pitch	RX (Rotation X)	HID_USAGE_RX
Yaw	RY (Rotation Y)	HID_USAGE_RY
Roll	RZ (Rotation Z)	HID_USAGE_RZ

Prerequisites

vJoy Driver Installation

1. Download vJoy

   Download the vJoy driver from:

   • Official site: http://vjoystick.sourceforge.net/
   • SourceForge: https://sourceforge.net/projects/vjoystick/
2. Run installer

   Run the vJoy installer and follow the setup wizard.

   Important: Install as administrator.

3. Configure vJoy device

   After installation, run Configure vJoy from the Start menu:

   1. Select Device 1
   2. Ensure these axes are enabled:
      • X, Y, Z
      • RX, RY, RZ
   3. Click Apply
4. Verify installation

   Check Windows Device Manager:

   • Control Panel → Device Manager
   • Look for “vJoy Device” under “Human Interface Devices”

If vJoy is not installed or configured correctly, OpenTrack will display an error:

• “vjoystick won’t work without the driver installed.”
• “Virtual joystick already in use.”
• “Device missing. Add joystick #1.”

You must resolve these before the protocol will function.

Setup Instructions

1. Install vJoy driver

   Follow the prerequisites section above to install and configure vJoy.

2. Select Virtual Joystick protocol

   In OpenTrack, go to the Output dropdown and select “Joystick emulation — vjoystick”.

3. Start OpenTrack

   Click Start in OpenTrack. The protocol will:

   • Connect to vJoy device #1
   • Query axis ranges
   • Begin sending joystick data
4. Configure game controls

   In your game’s control settings:

   1. Look for view control or camera options
   2. Bind view axes to the virtual joystick axes:
      • View left/right → Joystick RY (Yaw)
      • View up/down → Joystick RX (Pitch)
      • View roll → Joystick RZ (Roll)
      • View forward/back → Joystick Z
      • View left/right position → Joystick X
      • View up/down position → Joystick Y
   3. Adjust sensitivity and dead zones as needed
5. Test in game

   Launch your game and verify head movements control the view through the virtual joystick.

Configuration

Axis Value Ranges

The protocol automatically scales tracking data to joystick axis ranges:

Position axes (X, Y, Z):

• Input range: ±50 cm
• Output: Scaled to joystick axis min/max

Rotation axes (Pitch, Yaw, Roll):

• Input range: ±180°
• Output: Scaled to joystick axis min/max

Value Scaling Formula

int to_axis_value(double value, double minmax, long axis_min, long axis_max) {
    return clamp(
        (value + minmax) * axis_max / (2 * minmax) - axis_min,
        axis_min,
        axis_max
    );
}

// Position example (±50 cm range)
joystick_x = to_axis_value(headpose[X], 50.0, axis_min[0], axis_max[0]);

// Rotation example (±180° range)  
joystick_rx = to_axis_value(headpose[Pitch], 180.0, axis_min[3], axis_max[3]);

Use Cases

Games Without Native Head Tracking

Many games support joystick input but not head tracking. Examples:

• Racing games (camera movement)
• Flight arcade games
• Mech games (torso twist)
• First-person games (view control)

View Control Schemes

Cockpit games:

Yaw → Look left/right
Pitch → Look up/down
Roll → Lean head
X → Lean body left/right
Y → Lean body up/down  
Z → Lean body forward/back

Third-person games:

Yaw → Rotate camera
Pitch → Camera height
Z → Camera distance

Hybrid Input

Combine virtual joystick with physical controls:

• Use mouse/gamepad for aiming
• Use head tracking for view/camera
• Map only needed axes to avoid conflicts

Troubleshooting

”vjoystick won’t work without the driver installed”

Cause: vJoy driver not installed.

Solution:

1. Download vJoy from sourceforge.net/projects/vjoystick
2. Run installer as administrator
3. Restart OpenTrack

”Virtual joystick already in use”

Cause: Another application has acquired vJoy device #1.

Solution:

1. Close other applications that might use vJoy
2. Check Task Manager for vjoy-related processes
3. Restart computer if needed
4. Ensure OpenTrack starts before other joystick applications

”Device missing. Add joystick #1”

Cause: vJoy device #1 not configured.

Solution:

1. Run “Configure vJoy” from Start menu
2. Ensure Device 1 exists and is enabled
3. Enable axes: X, Y, Z, RX, RY, RZ
4. Click Apply
5. Restart OpenTrack

Game Doesn’t Detect Joystick

Symptoms: vJoy works in OpenTrack but game doesn’t see it.

Solution:

1. Test in Windows: Control Panel → Devices → Game Controllers
   • vJoy Device should appear
   • Right-click → Game controller settings → Properties
   • Move your head and verify axes move
2. Restart game: Some games only detect joysticks at startup
3. Check game settings: Ensure joystick input is enabled
4. Update game: Some older games don’t support modern HID devices

Wrong Axis Mapping

Symptoms: Moving head left/right rotates camera up/down.

Solution:

1. Check game control bindings
2. Different games map RX/RY/RZ differently
3. Try swapping axis assignments in game settings
4. Use OpenTrack axis mapping to reassign before sending to joystick

Axis Moves But View Doesn’t Center

Cause: Game expects spring-centered joystick.

Solution:

• In OpenTrack mapping, enable “Center” for position axes
• Adjust dead zone in game settings
• Some games aren’t suitable for head tracking via joystick

Jittery or Jumpy Movement

Cause: Insufficient smoothing or low update rate.

Solution:

1. Increase filter smoothing in OpenTrack
2. Adjust game joystick sensitivity
3. Enable joystick dead zones in game
4. Check input device tracking quality

Advanced Configuration

Partial Axis Usage

You don’t need to use all 6 axes. Common configurations:

Rotation only (3DOF):

• Map only Pitch, Yaw, Roll
• Leave position axes at center
• Good for games with fixed camera position

Position only:

• Map only X, Y, Z
• Use for body lean in racing games
• Keep rotation centered

vJoy Multi-Device

If you need multiple virtual joysticks:

1. Configure additional vJoy devices (Device 2, 3, etc.)
2. OpenTrack uses Device 1 only
3. Use other devices for different applications
4. Avoid device conflicts

Game-Specific Profiles

Create OpenTrack profiles for different games:

1. Save profile with game name
2. Configure axis mappings per game
3. Set appropriate ranges and curves
4. Use profile shortcuts for quick switching

Technical Details

vJoy API Functions

// Driver check
vJoyEnabled()              // Check if driver installed
GetVJDStatus(device_id)    // Check device status

// Axis configuration  
GetVJDAxisExist()          // Check if axis exists
GetVJDAxisMin()            // Get axis minimum value
GetVJDAxisMax()            // Get axis maximum value

// Control
AcquireVJD(device_id)      // Acquire exclusive control
RelinquishVJD(device_id)   // Release control

// Data transmission
SetAxis(value, device_id, axis_id)  // Set axis value

Device Status Codes

Status	Description	Action
VJD_STAT_OWN	Already owned	Bug - should not happen
VJD_STAT_FREE	Available	Normal - acquire device
VJD_STAT_BUSY	In use	Close other app
VJD_STAT_MISS	Not configured	Run Configure vJoy
VJD_STAT_UNKN	Unknown error	Reinstall driver

Axis ID Constants

HID_USAGE_X  = 0x30  // Position X
HID_USAGE_Y  = 0x31  // Position Y
HID_USAGE_Z  = 0x32  // Position Z
HID_USAGE_RX = 0x33  // Rotation X (Pitch)
HID_USAGE_RY = 0x34  // Rotation Y (Yaw)
HID_USAGE_RZ = 0x35  // Rotation Z (Roll)

Update Rate

The protocol updates the virtual joystick at the same rate as OpenTrack’s main loop:

• Typically 50-60 Hz depending on input device
• No artificial rate limiting
• Games poll joystick at their own rate

The Virtual Joystick protocol is most useful for games without native head tracking support. For games with FreeTrack support, use the FreeTrack protocol directly for better performance and lower latency.

Alternatives

For games that support other input methods:

• FreeTrack support: Use FreeTrack protocol (better performance)
• Mouse emulation: Use MouseLook or FreePIE scripts
• UDP output: Send data to custom game mods
• OSC protocol: Control games via Open Sound Control