Tutorial How to write a Game Plugin for SimTools v3.0 - API documentation

SimTools v3 - Game Plugin API Documentation

The SimTools v3 GamePlugin API offers support for:
12 Motion Outputs (6 stated, 6 anything)
12 Vibe Outputs
112 Dash Outputs (98 stated, 14 anything)

Whenever possible, please add Roll, Pitch and Yaw in Accelerations too.
Adding Roll, Pitch and Yaw in Accelerations allows for more options for our setups!
Roll – Roll in degrees
Pitch – Pitch in degrees
Yaw – Yaw in degrees
Heave – Heave as acceleration
Sway – Sway as acceleration
Surge – Surge as acceleration
Extra1 – Anything (Traction Loss as acceleration - if available)
Extra2 – Anything (Turbo as acceleration - if available)
Extra3 - Anything
Extra4 – Roll as acceleration
Extra5 – Pitch as acceleration
Extra6 – Yaw as acceleration

All game plugins created for SimTools v3 are made from 4 files (with one optional):
1) GameName_GamePlugin.dll
2) GameName_Banner.jpg
3) GameName_MaxMin.zip
4) GameName_Offsets.xml (Optional - used for memory hook plugins)

- Offsets.xml file - explained
Offsets.xml files are used to hold the offsets when building a memory hook game plugin. Using an Offsets file allows you to never have to update the plugin again; instead we can just update the Offsets file in the game plugin zip, and then upload the updated plugin to the repo. From there it will get pushed out to everyone that is using the Offsets file.

And there are 4 main sections of any new Game Plugin that need to be completed in order to produce a Game Plugin for SimTools v3.
1) Plugin Settings – Basic settings for the new Game Plugin.
2) Data Collecting– Collecting and deciphering the data sent from the game.
3) Patching – Patching/Un-Patching the game for telemetry output.
4) Game Status – Setting the Game Status

Before you really get started, you will need to figure out how you are going to get telemetry data out of the game. There is not always an obvious answer to the question, but often times looking up what engine the game is built on can provide some cues. Other times you can find information on Google about how to get telemetry data, and other times the games website provides an API to collect the data. And then sometimes there is no provided way to get telemetry data. (But it’s still possible to get the data need with memory hooks!)

Before we get started – Create a test app!
I highly suggest you create a simple test app first and learn how to collect data from the game before trying to create a new game plugin for SimTools. Once you have a proven way to get data from the game, creating a plugin for SimTools will be a lot easier to put together.

The examples below show 4 different ways to collect data from a game. Please select the example that is closest to what you are trying to accomplish as a starting point for your new game plugin.

Example 1) UDP Output – (Example – Dirt Rally)
These types of games export telemetry data via UDP packets.
If your game uses UDP packets to export telemetry data, start with this example.
(Some games in this category are: LFS, CodeMaster Games and NSR Stage 1)
DirtRally_Source_v2.zip

Example 2) Memory Mapped File – (Example – Assetto Corsa)
These types of games export telemetry data via Memory Mapped Files.
If your game uses Memory Mapped Files to export telemetry data, start with this example.
(Games in this category are: Assetto Corsa, SimBin Games)
AssettoCorsa_Source_v2.zip

Example 3) Memory Hooks – (Example - No Limits Coasters)
These types of games will export telemetry data via Memory Hooks, because no real form of telemetry exportation is available from the game. If your game has no telemetry output supported, using Memory Hooks to export data may be your only option.
If that is the case, start with this example.
(Some games in this category are: No Limits Coasters and Need for Speed Shift)
To Be Finished, I don't have a memory hook plugin finished yet…

Memory Hooks Examples:
Example 1
Example 2
Example 3

Example 4) Custom built DLL – (Example - rFactor)
These types of games install a custom built DLL to export telemetry data. You usually download a SDK from the games website to compile this DLL. (Some games in this category are: rFactor and PCars)
When you create your custom game DLL, There are 2 main ways to send the data to SimTools. (Both ways work but Way 1 is suggested.)

Way 1) The custom DLL collects the data needed from the game and sends UDP packets with the data needed. From here your Game Plugin will install this DLL and treat the Game Plugin as any other UDP output plugin.
(Use ‘Example 1’ files to build the plugin – UDP Output)

Way 2) The custom DLL collects the data needed from the game and sets it in a Memory Map file. From here your Game Plugin will install this DLL and treat the Game Plugin as any other memory mapped game.
(Use ‘Example 2’ files to build the plugin - Memory Mapped Files)

Once you have created the custom DLL file for the game, you can then use one of the examples above to create your new Game plugin.


~ Let’s get Started!! ~
The following steps apply to all of the game plugins posted above, no matter how the telemetry is delivered from the game. The first thing to do is to set all of the basic settings for the game plugin.
1) Open the selected plugin by unzipping the file and then clicking on “GamePlugin.sln”.
2) Then double click on “GamePlugin.vb” in the editor.


Section 1) Game Plugin Settings
3) Then expand the ‘PluginSettings()’ section of the plugin.
(This is what you should be looking at)


_PluginAuthorsName - The name (or names) of people that have worked on the plugin.

_GameName - This is name displayed in SimTools.

_ProcessName – The name that SimTools looks for in the list of windows processes in order to tell if the game has stopped. You can have multiple comma delimited exe names if needed. Like this (dirt2_game, dirt2VR_game, dirt2Mod_game). You do not need to add the “.exe” to the name and the exe name is not case sensitive.

_RequiresPatchingPath – Do we need to make any alterations to the game files? When set to False, PatchPathInfo, ValidatePathPath, PatchGame and UnpatchGame never get called but the game is still marked as Patched and ready to run in SimTools. (For example memory hook plugins do not require any file patching.)

_PlatformType – Is the plugin for the PC, or is it meant for Consoles? (aka - a Manual Start Plugin) When PluginType is sent to Console, PatchPathInfo, ValidatePathPath, PatchGame and UnpatchGame never get called, as the patching routine is skipped all together during installation. And the plugin is automatically set to be a manual start/ stop plugin.

_GameOrigin – This tells the user where the game that was used to create the plugin originated from. It also instructs SimTools how create a launch shortcut for the game. The options are CD, Steam, Epic or Origin (Set the GameOrigin to CD whenever the other options do not apply)

_GameType – This tells SimTools what type of game plugin we are dealing with. You can select either ‘Air, Land or Sea’. When a plugins GameType is classified as ‘Air’, SimTools automatically allows for 2 sets of Max/Min profiles for the game. (Allowing for you will have one Max/Min profile for when the plane is in the air, and a second profile for when the plane is on the ground / runway.)

_GameID – This value is dependent on _GameOrigin value above. It allows SimTools to automatically create a game shortcut to launch the game. And in some cases, it can allow SimTools to automatically know where the home page is for the game too.
If _GameOrigin above is set to:

CD – Plugins that have the _GameOrigin as ‘CD’ do not make launch shortcuts by default.
But there is a built in command you can use to make launch shortcuts while the game is being patched.
All you need to do is pass SimTools v3 an exe or shortcut for the game.
Create_LaunchShortcut(IPlugin_Game_v3.Shortcut_Type.From_Exe, MyPath & "LFS.exe")
With the built in command “Create_LaunchShortcut” we can make shortcuts for any game plugin that would otherwise not have one auto created by default.

Steam – You get the number from the https path for the download page of the game on Steam. Here I pull up the page for Dirt Rally, notice the number in the https address.


Epic - Create a shortcut for a game on the desktop then look at the .URL line in the file it created. All the links are of the form:
com.epicgames.launcher://apps/[codename]?action=launch&silent=true
Where [codename] is the name we are looking for.

Origin - To get an Origin game ID for a plugin, head down to ‘C:\ProgramData\Origin\LocalContent’ and search for a folder with your game name in it.
Open the folder up and you will see 3 files with the same name.
Example: OFB-EAST46851.dat, OFB-EAST46851.mfst, OFB-EAST46851.pkg
Simply add a colon between the last word and the numbers and that is your game ID.
So in this case its ‘OFB-EAST:46851’​

Auto Profiling

Auto profiling allows SimTools to automatically select the correct profile when the vehicle changes in the game. If no profile exists for the vehicle, SimTools will automatically create a profile for the new vehicle from the default profile for the game selected.

If the games telemetry output includes the current vehicle being used, we can enable auto profiling for the game plugin. To do this we simply set _AutoProfiling_Enabled = True. And then we make sure to set the current vehicle being used to the

‘_Status_Outputs._CurrentVehicle’ variable.

Game Provided Crashed

A game provided crashed variable allows SimTools to automatically detect that the user has crash and allows SimTools to trigger its internal crashed detection routine if enabled.

If the games telemetry output includes the a variable for crashed, we can enable GameProvidedCrashed for the game plugin. To do this we simply set _ GameProvidedCrashed_Enabled = True. And then we make sure to set the current crashed state to ‘_Status_Outputs._HasCrashed’ variable.

Motion Support

DOF_Supported values are used to tell SimTools what DOF outputs are supported by the plugin.
_DOF_Supported_Roll – set to true or false accordingly.
_DOF_Supported_Pitch – set to true or false accordingly.
_DOF_Supported_Heave – set to true or false accordingly.
_DOF_Supported_Yaw – set to true or false accordingly.
_DOF_Supported_Sway – set to true or false accordingly.
_DOF_Supported_Surge – set to true or false accordingly.
_DOF_Supported_Extra1 – “Traction Loss" Add a Force name here to set it to true.
_DOF_Supported_Extra2 – "" Not Used set to blank.
_DOF_Supported_Extra3 – "" Blank equals False.
_DOF_Supported_Extra4 – "" Blank equals False.
_DOF_Supported_Extra5 – "" Blank equals False.
_DOF_Supported_Extra6 – "" Blank equals False.

Output Type

This tells SimTools whether to treat the input as a degree or as an acceleration input. Acceleration inputs always return to zero when not used, where degree inputs do not return to zero and simply send the current degrees they are pointing to at the time. This value is then passed to the axis plugin so the output can be computed correctly for the two input types.

~ Assigning Motion Outputs ~
(All motion outputs get assigned to the ‘_Motion_Outputs’ structure.)
Assign the Motion output variable as follows:
_Motion_Outputs._IsAirborne = .b_InAir
_Motion_Outputs._Roll = .m_fRoll
_Motion_Outputs._Pitch = .m_fPitch
_Motion_Outputs._Yaw = .m_fYaw
_Motion_Outputs._Heave = .m_fAccelerationZ
_Motion_Outputs._Sway = .m_fAccelerationX
_Motion_Outputs._Surge = .m_fAccelerationY
_Motion_Outputs._Extra4 = .m_fRollVelocity
_Motion_Outputs._Extra5 = .m_fPitchVelocity
_Motion_Outputs._Extra6 = .m_fYawVelocity

Dash Support

Set _Enable_DashBoard to ‘True’ to enable the Dash Output System.
(Basic Dash Support should include Speed, Gear & Rpm)
Once enabled, you may assign Dash output variables.

~ Assigning Dash Outputs ~
(All dash outputs get assigned to the ‘_Dash_Outputs’ structure.)
Assign the dash output variable as follows:
(Set the corresponding var above to true or false, then assign the output as follows.
_Dash_Outputs._Speed_GroundSpeed = .speedKmh.ToString
_Dash_Outputs._Rpm = Int(.rpms + 0.5).ToString
_Dash_Outputs._Position_Gear = .gear.ToString
_Dash_Outputs._Capacity_FuelLevel = .fuel.ToString

Vibe Support (Buttkicker)

Set _VibeSupport_VibeEnabled to ‘True’ to enable the Vibe Output System.
(Basic Vibe support should include Speed, Gear & Rpm)
Once enabled, you may assign up to 12 output variables.
Here is the list of inputs we currently have for vibe.

Vibe Input (What to output from the game to use)
~~~~~~~~~~~~~~~~~~~~~~~~
Afterburners (Afterburners)
Chassis (FL, FR, RL, RR)
Collision F/B (Surge)
Collision L/R (Sway)
Flaps (Flaps)
Gear Shift (Current Gear)
Landing Gear (Landing Gear)
Road Detail (Heave)
Rpm (Rpm)
Turbo (Turbo)
Turbulence (Speed)
Weapons Bombs (Fired Weapon)
Weapons Cannons (Fired Weapon)
Weapons Flairs (Fired Weapon)
Weapons Guns (Fired Weapon)
Weapons Other (Fired Weapon)

~ Assigning Vibe Outputs ~
(All vibe outputs get assigned to the ‘_Vibe_Outputs’ structure.)
Assign all vibe output variables as follows: (Except 3D Chassis)
(Set the corresponding var above to a output type, then assign the output as follows.
_Vibe_Outputs._Vibe01 = .m_iRPM
_Vibe_Outputs._Vibe02 = .m_iGear

Assign the 3D Chassis variable like this:
_Vibe_Outputs._Vibe_Chassis_FL = .suspensionTravel.Front_Left
_Vibe_Outputs._Vibe_Chassis_FR = .suspensionTravel.Front_Right
_Vibe_Outputs._Vibe_Chassis_RL = .suspensionTravel.Rear_Left
_Vibe_Outputs._Vibe_Chassis_RR = .suspensionTravel.Rear_Right

If a game needs more range...
_Vibe_Outputs._Vibe_Chassis_FL = .suspensionTravel.Front_Left * 10000
_Vibe_Outputs._Vibe_Chassis_FR = .suspensionTravel.Front_Right * 10000
_Vibe_Outputs._Vibe_Chassis_RL = .suspensionTravel.Rear_Left * 10000
_Vibe_Outputs._Vibe_Chassis_RR = .suspensionTravel.Rear_Right * 10000


Section 2) Data Collecting
Game Start and Game Stop
With the GameStart and GameEnd routines below, we can start and stop the telemetry data collection from the game. In the pic below you can see that we are also collection the status of the game (Game is live or paused) and passing the status to SimTools as this is now required in v3.


Section 3) Patching the Game
This section will show you how to construct a patching routine for your new game plugin.

PatchPathInfo
This is used to tell the user the location they should patch there game at. It is presented to the user when they install the plugin.


PatchGame
This is used to edit a .txt or .cfg file (Live for Speed plugin example) or to install a custom DLL (rFactor plugin example) to enable telemetry output from the game. I strongly suggest you always backup any file you're going to edit before patching, and always try to restore the backup before trying to patch the game. (see the PatchGame routine in the picture below.)


UnPatchGame
This is used to remove whatever alterations were made to the game during the PatchGame procedure.


ValidatePatchPath
This is used to validate the path passed to SimTools from the user. In the picture above, we see that the user has a valid path when the path has the file “hardware_settings_config.xml” present. (In other words, it makes the user select the Dirt Rally folder)


ExtraSetupInfo
Here we should explain to the user, any extra steps that may be needed, to get the plugin running. Like needed in game settings to get telemetry running, where there are no files we can edit during the patching process to enable telemetry.


Section 4) Game Status
In SimTools 3, the plugin controls when the game is active or not. This allows us to get the same ‘centering when paused’ output, no matter how the game is collecting the data. All we need to do is set the _Status_Outputs._OutputActive variable to the current state of the game.

In some cases a variable is provided by the game, and in others where the game sends UDP data, you can simply detect when the UDP stream is active or not. For all games that send telemetry over UDP, you can simply copy the ‘Game Monitoring’ routine out of any UDP example plugin I have source available for.

That’s it!
Let’s compile your new plugin!

​

How to Compile the Plugin
Click on “My Project”


Make sure the “application” tab is selected. Now name the Game Plugin DLL as follows: GameName (without spaces) + _GamePlugin.
So for this example we get ‘LiveForSpeed_GamePlugin’. Use this name for both the ‘Assembly Name’ and the ‘Root Namespace’ as in the picture below


Right click on GamePlugin in the solution explorer and select Build!


Your new Game plugin can now be found in the folder;
ExamplePluginFolder\ GamePlugin\GamePlugin\bin\Release\MyPlugin_GamePlugin.dll

Congratulations!!
Your Games Plugin dll complete, On to the banner!​

(Now is a good time to use the Game Plugin Tester, and test that your new game plugin is working correctly.)


How too create a game banner for your new game plugin.
Create a (390 x 128 pixels) .jpg image to use as the banner for your new plugin.
The banner should clearly identify the game, without being confused with any other game or version.
Here is a good example:


Your new game banner should be named: GameName(without spaces) & “_GamePlugin.jpg” .
And the game name should match the dll’s game name.

Example naming scheme:
GameName_GamePlugin.dll
GameName_GamePlugin.jpg


How too install your new game plugin.
Launch SimTools v3 and then Drag-n-Drop the plugin and the banner into the main window.


Give your new game plugin a test, and while its running, and Capture valid Max/Min Settings for the game.
Once you have Max/Min settings for the game, you can proceed to the last step.


How to export the final game plugin.
(Please make sure you have Captured valid Max/Min Settings for the game before proceeding.)
Click on the main menu button and select Options.
In the lower right of the Options page you will find Export.


Then select Game Plugins and select your game plugin to export.
Lastly, select Community Plugin and your new plugin will be exported to "Documents\SimTools Exports".

Congratulations!!
Your new Game Plugin is now complete, and is ready to be loaded to the repo!
​

~ Game Plugin Tester ~
Here is the official game plugin tester app. (The first of the plugin tester series of apps!)
It was built so a plugin writer can easily test all aspects of their new game plugin in a simple visual way.
The game plugin tester can be really handy for verifying the outputs of your new game plugin, but can be used for full plugin debugging also.

Notice you can select any dash section output from the dash output type menu.
And you will notice the dash outputs for any section will either be enabled or disabled.
(This action is done directly from the plugins dash supported settings.)

Preview: Game running and I clicked the 'Game Start' button in the game plugin tester.


Game Plugin Tester Download:
Game_PluginTester_v2.zip

Let me know if you have any questions.
Take care,
yobuddy

The Game Plugin Tester and plugin examples posted!
I believe the game plugin information is now complete, let me know if you have any questions.
(I just need a good memory hook plugin example when I get one built.)
Chat soon!
yobuddy

Updated the Game Plugin tester and the sources of the game plugins above to v2.
Just a little change was needed for 'crash detection'.
Chat soon!
yobuddy

Sure, if the game supports it, we could add it to game dash outputs.

Yes, I think the old plugin had a dll for both 64 and 32 bit if i'm not mistaken.
There is a lot of api's for games too now days on github, some may output more data that what we did the first time.
for example...
https://github.com/TheIronWolfModding/rF2SharedMemoryMapPlugin

If you guy's notice a dash output missing, that should defiantly be in the stated set of outputs, please let me know and I will add them for the beta.
Thanks so much for playing with the api!

@vthinsel,
Just so you know, the only change that should be needed to change a PC plugin into a Console plugin, is setting the platform type to Console. When doing so, the patching stuff should all be ignored. (that's if the PC version's input is the same as the console version)

Thanks guys, you rock!

Yep, those are them.

When a group has more than one output option (temperature below), you will get a little white down arrow where you can select the output you want to see.


And once you pick a selection, you can see the name used to send the output on the form.
Hope that helps!

Hi Guys,
Know that crash detection will still work, even if the game does not provide a var for it.
So there is no need to try to figure out something if a crash var is not provided.
Take care!

The V3 interface is integrated, simplified, and more streamlined, but the basic motion tuning principles are the same, have sensible axis allocations, for convenience v3 tracks the totals, capture the Tuning Center Min/Max values, then tweak from there.