> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/opentrack/opentrack/llms.txt
> Use this file to discover all available pages before exploring further.

# SimConnect

> Native protocol for Microsoft Flight Simulator X and Prepar3D

SimConnect is the native camera control protocol for Microsoft Flight Simulator X (FSX), FSX Steam Edition, and Lockheed Martin Prepar3D. It provides direct 6DOF camera positioning through the simulator's official SDK.

## How It Works

The SimConnect protocol:

1. Loads the SimConnect SDK library (`SimConnect.dll`) using side-by-side assembly manifests
2. Opens a connection to the running flight simulator
3. Subscribes to frame update events to maintain the connection
4. Sends camera position updates using `CameraSetRelative6DOF` API calls
5. Automatically handles reconnection if the simulator restarts

### Technical Implementation

The protocol runs in a separate thread and:

* Polls for simulator events using `CallDispatch` with a 2-second timeout
* Automatically reconnects every 5 seconds if connection is lost
* Converts OpenTrack coordinates to SimConnect camera space
* Handles exception and quit events from the simulator

## Compatible Simulators

<CardGroup cols={2}>
  <Card title="Microsoft Flight Simulator X" icon="plane">
    All versions: RTM, SP1, SP2, Acceleration Pack
  </Card>

  <Card title="FSX Steam Edition" icon="steam">
    Steam version with all updates
  </Card>

  <Card title="Prepar3D v1-v5" icon="plane-departure">
    Lockheed Martin Prepar3D all versions
  </Card>
</CardGroup>

<Note>
  **Microsoft Flight Simulator 2020/2024** does not use SimConnect for head tracking. Use the FreeTrack protocol instead.
</Note>

## Prerequisites

### SimConnect SDK Installation

The SimConnect protocol requires the SimConnect SDK to be installed on your system.

<Steps>
  <Step title="Locate SDK installer">
    The SimConnect SDK is included with your flight simulator installation:

    **FSX/FSX-SE:**

    ```
    <FSX Install Dir>\SDK\Core Utilities Kit\SimConnect SDK\
    ```

    **Prepar3D:**

    ```
    <P3D Install Dir>\SDK\Core Utilities Kit\SimConnect SDK\
    ```
  </Step>

  <Step title="Run installer">
    Run `SimConnect.msi` and complete the installation wizard.
  </Step>

  <Step title="Verify installation">
    After installation, `SimConnect.dll` should be registered in the system's side-by-side (SxS) assembly cache.
  </Step>
</Steps>

<Warning>
  If the SimConnect SDK is not installed, OpenTrack will display an error:

  **"Install FSX/Prepar3D SimConnect SDK"**

  You must install the SDK before using this protocol.
</Warning>

## Setup Instructions

<Steps>
  <Step title="Install SimConnect SDK">
    Follow the prerequisites section above to install the required SDK.
  </Step>

  <Step title="Select SimConnect protocol">
    In OpenTrack, go to the **Output** dropdown and select **"Microsoft FSX SimConnect"**.
  </Step>

  <Step title="Configure SimConnect version">
    Click the settings button next to the Output dropdown.

    **SimConnect manifest selection:**

    * FSX RTM (original)
    * FSX SP1
    * FSX SP2
    * FSX Acceleration Pack / SP2 with extras
    * FSX Steam Edition (original)
    * FSX Steam Edition (latest)
    * Prepar3D

    Select the version matching your simulator installation.
  </Step>

  <Step title="Start OpenTrack">
    Click **Start** in OpenTrack. The protocol will:

    * Load the SimConnect library
    * Wait for the simulator to start
    * Automatically connect when detected
  </Step>

  <Step title="Launch simulator">
    Start FSX or Prepar3D. OpenTrack will connect automatically.
  </Step>

  <Step title="Verify connection">
    In the simulator, load a flight. Your head movements should now control the camera view.
  </Step>
</Steps>

## Configuration

### SimConnect Version Manifests

OpenTrack includes manifests for different SimConnect versions to ensure compatibility:

| Manifest                     | SimConnect Version | Compatible With       |
| ---------------------------- | ------------------ | --------------------- |
| `fsx_rtm.manifest`           | 10.0.60905.0       | FSX Original          |
| `fsx_sp1.manifest`           | 10.0.61242.0       | FSX SP1               |
| `fsx_sp2.manifest`           | Multiple           | FSX SP2               |
| `fsx_p3d_sp2_xpack.manifest` | 10.0.61259.0       | FSX Acceleration, P3D |
| `fsx_steam_orig.manifest`    | 10.0.62607.0       | FSX Steam (early)     |
| `fsx_steam_last.manifest`    | 10.0.62615.0       | FSX Steam (current)   |

The correct manifest is loaded using activation context based on your selection.

## Coordinate System

OpenTrack coordinates are converted to SimConnect camera space:

```cpp theme={null}
// Position conversion (cm to meters)
float deltaX = -headpose[TX] * 0.01;  // Negated
float deltaY =  headpose[TY] * 0.01;
float deltaZ = -headpose[TZ] * 0.01;  // Negated

// Rotation conversion (degrees, directly passed)
float pitch = -headpose[Pitch];  // Negated
float roll  =  headpose[Roll];
float yaw   =  headpose[Yaw];

// Call SimConnect API
SimConnect_CameraSetRelative6DOF(
    handle, 
    deltaX, deltaY, deltaZ,
    pitch, roll, yaw
);
```

## Connection Management

### Automatic Reconnection

The protocol includes robust reconnection logic:

* **Connection timeout**: 2 seconds between frames
* **Reconnect delay**: 5 seconds after disconnect
* **Event-driven**: Reconnects on simulator quit/exception events

### Status Messages

OpenTrack displays connection status:

* `"fsx: connect failed, retry in 5 seconds..."` - Waiting for simulator
* `"fsx: timeout reached, reconnecting"` - Connection lost
* `"fsx: got quit event"` - Simulator closed

## Troubleshooting

### "Install FSX/Prepar3D SimConnect SDK" Error

**Cause**: SimConnect SDK not installed or not in SxS assembly cache.

**Solution**:

1. Locate the SDK installer in your simulator's SDK folder
2. Run `SimConnect.msi` as administrator
3. Restart OpenTrack after installation

### "dll load failed" Error

**Cause**: SimConnect.dll could not be loaded.

**Solution**:

1. Verify SDK is installed correctly
2. Check Windows Event Viewer for SxS loading errors
3. Try selecting a different manifest version
4. Reinstall the SimConnect SDK

### Connection Timeouts

**Symptoms**: OpenTrack connects but frequently disconnects.

**Solution**:

* Ensure simulator is running in foreground
* Check no other applications are using SimConnect
* Verify firewall isn't blocking SimConnect
* Try running both OpenTrack and simulator as administrator

### Head Tracking Not Working

**Symptoms**: Connected but camera doesn't move.

**Solution**:

1. Verify tracking is working in OpenTrack preview window
2. In simulator, ensure external view or virtual cockpit mode is active
3. Check simulator graphics settings don't override camera controls
4. Try reloading the flight or restarting the simulator

### Prepar3D Specific Issues

<Warning>
  **Important**: Do not attempt to reconnect on exception events in Prepar3D.

  OpenTrack handles this automatically. Reconnection is only performed on quit events or timeouts to avoid breaking Prepar3D's SimConnect implementation.
</Warning>

## Advanced Configuration

### Multiple Simulator Installations

If you have multiple simulators installed:

1. Create separate OpenTrack profiles for each
2. Select the appropriate SimConnect manifest per profile
3. Use OpenTrack's profile switcher to change between them

### Performance Tuning

For best performance:

* Use the most recent manifest version for your simulator
* Ensure OpenTrack filter settings match your input device framerate
* Consider reducing update rate if CPU usage is high

## Technical Details

### SimConnect API Functions Used

```cpp theme={null}
SimConnect_Open()                    // Open connection
SimConnect_Close()                   // Close connection  
SimConnect_CameraSetRelative6DOF()   // Set camera position
SimConnect_CallDispatch()            // Process events
SimConnect_SubscribeToSystemEvent()  // Subscribe to "1sec" frame events
```

### Thread Safety

The protocol uses:

* `QMutex` for protecting shared data between threads
* Separate background thread for SimConnect event processing
* Atomic bool for reconnection signaling

### Event Handling

The protocol responds to these SimConnect events:

* `SIMCONNECT_RECV_ID_EVENT_FRAME` - Frame updates (maintains connection)
* `SIMCONNECT_RECV_ID_EXCEPTION` - Error events (logged only)
* `SIMCONNECT_RECV_ID_QUIT` - Simulator closing (triggers reconnect)

<Note>
  The SimConnect protocol provides the most responsive and stable head tracking experience for FSX and Prepar3D users. For other flight simulators, use the FreeTrack protocol.
</Note>