# 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. \
\
**This feature is available starting from Simhub 9.11.5**
## 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 (Optionnal)
```
### 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**
### Using the definition
If everything is properly configured the simulation will now be visible in the list, simply activate it.
### Summary
* Create a definition
* Generate the structure
* Send UDP telemetry
* Register or drop the definition
* Activate the simulation
### Troubleshooting
* If the sim does not appear, check simhub log files, any parsing or scanning errors will be visible (`C:\Program Files (x86)\SimHub\logs`)
* If data is not received by simhub, you might have a definition mismatch (IE changed fields, changed game identitity), you can use the telemetry test tool to check validity ( [#test-your-udp-feed](#test-your-udp-feed "mention"))
* The game signature and telemetry signature are visible in the SimDef Json, **never change it**, it's only shown for reference but is recomputed when the definition is loaded
* Process detection expects a process name, not a file name : Ie
* `notepad` is valid,
* `notepad.exe` **is not valid**
