EXTERNAL SIM INTEGRATION

This feature is currently in beta. Some breaking changes in the telemetry “contract” may still occur. Thank you for your understanding. SimHub was originally built around avoiding third-party plugins for telemetry integration, while maintaining strong normalization across all supported simulations. However, this approach is not sufficient for private, specialized, or experimental simulations that are not publicly available.

To address this, SimHub now allows declaring external simulations.

Core concepts

External simulation integration is designed to avoid:

• Sim-side SDKs

• Plugin SDKs

• Any hard dependency on a specific language

It relies on a simple binary UDP feed and a formalized contract, defined by a definition file.

The definition file (*.simdef)

The definition file describes:

• The game identity (name, picture, unique ID)

• Process identification for automatic sim detection.

• The telemetry format (default UDP port, available fields, etc.)

It acts as the contract between the simulation and SimHub.

The definition file is typically shipped with the simulation to ensure it is always up to date. A dedicated editor is available in SimHub.

The registration file (*.simlink)

The registration file is a simple pointer to a definition file, allowing SimHub to discover it automatically.

• It contains a single line: the path to the .simdef file.

Registration can be skipped by placing the definition directly in a SimHub-managed folder (see Getting Started).

The UDP telemetry feed

Once the definition is created, a corresponding data structure can be sent from the simulation over UDP.

SimHub provides:

• A C# generator

• A C++ generator

These generate:

• The correct structure

• A minimal sending loop

The packet includes a header to ensure proper identification and reduce invalid format errors.

Optional extractor process

If the target simulation cannot provide a native integration, an external extractor can be used.

The extractor is responsible for:

• Reading simulation data (memory, API, etc.)

• Producing the expected UDP telemetry feed

Getting started

Enable the definition editor

In SimHub, open the settings, and in Global enable the game definition authoring tools

The editor will now appear in the left menu

Creating the definition

Open the editor tool and create a new definition

Simulation Identity

Fill:

• Name

• Icon path : The icon path must be relative to the definition file

Important

• If you are copying a definition from another sim, make sure to regenerate the Unique Id to avoid conflicts later

Telemetry definition

Add all the fields you will be able to provide out of the sim

You can also add custom fields:

• They will be exposed in SimHub

• They won’t be used internally by SimHub features

Important

• The declared fields will be used to determine the available features. Do not declare fields you cannot provide.

Create the telemetry feed

Once the definition is ready : Click on copy demo code (c# or c++) This gives you:

• The exact packet structure

• Required constants

• A minimal sending loop

Data conversion

The generated structure includes comments for:

• Units

• Directions

• Expected formats

You must convert your simulation data to match these expectations. Important

• Everytime you change the definition (Add, remove or reorder fields), this structure and/or constants must be updated.

• SimHub requires a minimum of 60Hz data for a correct fidelity. Higher rates are allowed and Extra packets may be ignored if needed

Test your UDP feed

Once your simulation sends telemetry:

Open Telemetry Receiver Tester in SimHub editor. If the feed is invalid the error will be visible. Otherwise the content will be shown

Important :

• If you have configured an extractor process, this won't be automatically spawned using the tester.

Store your definition

During development

You can register the definition right from the editor to make it available in SimHub.

Production recommendation

It is recommended to ship the definition file along the sim installed files, so it's always up to date and matching the simulator build.

YourGame/
    telemetry.simdef
    logo.jpg
    extractor.exe

Make the simulation visible in SimHub

There are two approaches

Registered (recommended)

• Create a link file into %localappdata%\SimHub\ExternalSims\Registrations\{UniqueId}.shlink

• The file must simply contain the absolute path of the definition file.

• It is recommended to always write/rewrite it at sim startup so it's kept up to date in case the installation got moved.

• The link file name must match the pointing definition UniqueId

Dropped in (fallback)

• This procedure is a fall back in case the integration is not native to the game (IE extractor process).

• In such case simply drop the definition and all the dependencies (logo, extractor process) into %localappdata%\SimHub\ExternalSims\Definitions\{SimName}\

Important :

• If multiple definitions share the same UniqueId: Registered definitions take priority

Summary

• Create a definition

• Generate the structure

• Send UDP telemetry

• Register or drop the definition