Getting Started

This guide walks you through installing the SimConnect Go SDK and connecting to Microsoft Flight Simulator for the first time.

Prerequisites

Before you begin, make sure you have the following:

• Microsoft Flight Simulator 2020 or 2024
• SimConnect SDK (included with the MSFS SDK)
• Go 1.25+ — download from go.dev/dl/
• Windows OS (SimConnect is a Windows-only API)

Installation

Create a new Go project and install the SDK:

mkdir my-simconnect-app && cd my-simconnect-app
go mod init my-simconnect-app
go get github.com/mrlm-net/simconnect

All SimConnect code requires the windows build tag. Files must include //go:build windows at the top.

Your First Connection

Create a main.go file with the following code:

//go:build windows

package main

import (
    "fmt"
    "log"
    "time"

    "github.com/mrlm-net/simconnect"
)

func main() {
    client := simconnect.NewClient("My First App")

    if err := client.Connect(); err != nil {
        log.Fatal("Failed to connect:", err)
    }
    defer client.Disconnect()

    fmt.Println("Connected to SimConnect!")
    time.Sleep(5 * time.Second)
    fmt.Println("Disconnecting...")
}

Run your application while MSFS is running:

go run .

Troubleshooting: If you get a DLL not found error, use simconnect.ClientWithDLLPath("path/to/SimConnect.dll") or set the SIMCONNECT_DLL environment variable.

Using the Manager

For production applications, the Manager provides automatic reconnection, state tracking, and structured lifecycle management. This is the recommended approach for robust add-ons.

//go:build windows

package main

import (
    "context"
    "fmt"
    "os"
    "os/signal"

    "github.com/mrlm-net/simconnect/pkg/manager"
)

func main() {
    ctx, cancel := context.WithCancel(context.Background())
    defer cancel()

    sigChan := make(chan os.Signal, 1)
    signal.Notify(sigChan, os.Interrupt)

    mgr := manager.New("My Managed App",
        manager.WithContext(ctx),
        manager.WithAutoReconnect(true),
    )

    mgr.OnConnectionStateChange(
        func(old, current manager.ConnectionState) {
            fmt.Printf("State: %s -> %s\n", old, current)
        },
    )

    go func() {
        <-sigChan
        fmt.Println("Shutting down...")
        mgr.Stop()
        cancel()
    }()

    if err := mgr.Start(); err != nil {
        fmt.Println("Manager stopped:", err)
    }
}

Key differences from the low-level client:

• Auto-reconnect: The manager automatically retries the connection when the simulator disconnects or is not running.
• State callbacks: Subscribe to connection state changes instead of polling.
• Graceful shutdown: Signal handling with context cancellation ensures clean disconnection.

Next Steps