Using Datasets

The pkg/datasets sub-packages provide ready-made DataSet definitions paired with companion Go structs. Instead of building data definitions field by field with AddToDataDefinition, you pass a constructor’s return value to RegisterDataset and use CastDataAs[T] to decode incoming messages directly into the companion struct.

How It Works

Every dataset package exposes two things:

1. A constructor (New*Dataset()) that returns *datasets.DataSet — a slice of DataDefinition entries that RegisterDataset feeds to SimConnect.
2. A companion struct (e.g., PositionDataset) whose fields map 1-to-1, in order, to those definitions. Pass the struct type to CastDataAs[T] to decode a received message.

import (
    "github.com/mrlm-net/simconnect/pkg/datasets/aircraft"
    "github.com/mrlm-net/simconnect/pkg/engine"
    "github.com/mrlm-net/simconnect/pkg/types"
)

const (
    PosDefID = 1000
    PosReqID = 1001
)

// Register the dataset once, after connecting
client.RegisterDataset(PosDefID, aircraft.NewPositionDataset())

client.RequestDataOnSimObject(
    PosReqID, PosDefID,
    types.SIMCONNECT_OBJECT_ID_USER,
    types.SIMCONNECT_PERIOD_SECOND,
    types.SIMCONNECT_DATA_REQUEST_FLAG_CHANGED,
    0, 0, 0,
)

// Decode in the message loop
for msg := range client.Stream() {
    if types.SIMCONNECT_RECV_ID(msg.DwID) == types.SIMCONNECT_RECV_ID_SIMOBJECT_DATA {
        data := msg.AsSimObjectData()
        if data.DwRequestID == PosReqID {
            pos := engine.CastDataAs[aircraft.PositionDataset](&data.DwData)
            fmt.Printf("lat=%.4f lon=%.4f alt=%.0fft\n", pos.Latitude, pos.Longitude, pos.Altitude)
        }
    }
}

The same pattern applies to every dataset in this document.

aircraft

Import path: github.com/mrlm-net/simconnect/pkg/datasets/aircraft

PositionDataset fields

AirspeedDataset fields

EngineDataset fields

ControlSurfacesDataset fields

environment

Import path: github.com/mrlm-net/simconnect/pkg/datasets/environment

WeatherDataset fields

Note: PrecipState is stored as float64 to preserve struct alignment. Cast to uint32 before bit-testing: state := uint32(w.PrecipState).

TimeDataset fields

simulator

Import path: github.com/mrlm-net/simconnect/pkg/datasets/simulator

SimStateDataset fields

Note: CrashFlag is stored as float64. Cast to uint32 before bit-testing.

CameraDataset fields

Camera state values correspond to the constants in pkg/manager/state-enums.go (e.g., CameraStateCockpit = 2, CameraStateDrone = 4). See Manager Usage for the full list.

objects

Import path: github.com/mrlm-net/simconnect/pkg/datasets/objects

SimObjectPositionDataset fields

Use this dataset with RequestDataOnSimObjectType to query all nearby objects in a single request:

import "github.com/mrlm-net/simconnect/pkg/datasets/objects"

const (
    ObjDefID = 2000
    ObjReqID = 2001
)

client.RegisterDataset(ObjDefID, objects.NewSimObjectPositionDataset())

client.RequestDataOnSimObjectType(
    ObjReqID,
    ObjDefID,
    25000, // 25 km radius
    types.SIMCONNECT_SIMOBJECT_TYPE_AIRCRAFT,
)

for msg := range client.Stream() {
    if types.SIMCONNECT_RECV_ID(msg.DwID) == types.SIMCONNECT_RECV_ID_SIMOBJECT_DATA_BYTYPE {
        data := msg.AsSimObjectDataByType()
        if data.DwRequestID == ObjReqID {
            obj := engine.CastDataAs[objects.SimObjectPositionDataset](&data.DwData)
            fmt.Printf("objectID=%d lat=%.4f lon=%.4f\n", data.DwObjectID, obj.Latitude, obj.Longitude)
        }
    }
}

traffic

Import path: github.com/mrlm-net/simconnect/pkg/datasets/traffic

This is the original reference implementation. AircraftDataset combines identity strings ([128]byte, [32]byte) with float64 motion fields and int32 boolean/enum fields, demonstrating the mixed-type pattern for datasets that include SimConnect string variables.

Alignment note

All numeric fields in the companion structs use float64, even for variables that logically carry boolean or enum values. This is intentional: using a uniform 8-byte type for every numeric field eliminates Go struct padding between fields. The byte layout of the struct must match the byte layout that SimConnect writes into the data block, and that layout is determined entirely by the order and type of entries in the DataSet.Definitions slice. If you add, remove, or reorder fields in either the struct or the constructor, CastDataAs[T] will silently misalign — the compiler cannot catch this.