Tutorial How to write a Game Plugin for SimTools 1.0 - API documentation

There are 3 sections of any new plugin that need to be completed in order to produce a compatible plugin for SimTools.
1) Game Plugin Settings – All of the settings for the new plugin.
2) Game Data Collection – Collecting and deciphering the data sent to SimTools.
3) Game Patching – patching/un-patching the game for output.

The first thing you need to do, is to figure out how you are going to get telemetry data out of the game.
Below are 4 plugin examples that all use different ways to collect data from a game.
Select the one that is closest to what you are trying to accomplish as a starting point for your plugin.

1) Live for Speed – Example Plugin – 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, NSR Stage 1)
LFS_V3_Source_Dash.zip
2) GTR2 – Example Plugin - 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. (Some games in this category are: all SimBin Games)
GTR2_V3_Source.zip
3) NoLimitsCoasters – Example Plugin - These types of games will export telemetry data via Memory Hooks because no real form of telemetry exportation is available. 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: NoLimitsCoasters, Need for Speed Shift)
NoLimits_V3_Source_v1.8.zip
Memory Hooks Examples:
Example 1
Example 2
Example 3

4) rFactor – Example Plugin - 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: all rFactor, PCars)
- When you create your custom game DLL, There are 2 main ways to have SimTools collect the data.
1) The custom DLL collects the data needed and sets it in a Memory Map file. From here your Game DLL will install this DLL and treat it as any other memory mapped game. (use example two files above)
2) The custom DLL directly broadcasts the UDP packets with the data needed to the ‘_Port’ address assigned in the plugin. You then catch the UDP packets with the ‘Process_PacketReceived’ sub routine and assign values to Roll_Output, Pitch_Output etc...
rFactor_V3_Source.zip

Let’s get started!!
The following steps apply to all plugins, no matter which one you start with. The first thing to do is to set all of the setting for the plugin.
1) Open the selected plugin by unzipping and clicking on “PluginExample.sln”.
2) Then click on “Plugin.vb” in the editor.

1) Game Plugin Settings
This is what you should be looking at; refer to this picture for the settings below.
(To Be Posted)
Per Game Settings
_PluginAuthorsName - The name, or names, of people that have worked on the plugin.
_GameName - this is name displayed in Game Managers list of games available.
_ProcessName – the name that SimTools looks for in windows processes list in order to tell if the game has started or stopped.
_Port – the Port used for sending and receiving information, all plugins use 4123 as of this posting.

Memory Map Variables
_Is_MemoryMap – if it is a memory map game set to true. (See example plugin)
_MMF_Name - if it is a memory map game, enter the memory map file name here

Memory Hook Variables
_Is_MemoryHook – if it is a memory hook game set to true. (See example plugin)
_MemoryHook_Roll – if it is a memory hook game; enter the memory location for roll.
_MemoryHook_Pitch – if it is a memory hook game; enter the memory location for pitch.
_MemoryHook_Heave – if it is a memory hook game; enter the memory location for heave.
_MemoryHook_Yaw – if it is a memory hook game; enter the memory location for yaw.
_MemoryHook_Sway – if it is a memory hook game; enter the memory location for sway.
_MemoryHook_Surge – if it is a memory hook game; enter the memory location for surge.
_MemoryHook_Extra1 – if it is a memory hook game; enter the memory location for surge.
_MemoryHook_Extra2 – if it is a memory hook game; enter the memory location for surge.
_MemoryHook_Extra3 – if it is a memory hook game; enter the memory location for surge.

DOF’s used for this game
These values are used control the red dots on the Profiles Page. See below.
They tell the user what DOF outputs are supported by the plugin.
_DOF_Supported_Roll – set to true of false accordingly.
_DOF_Supported_Pitch – set to true of false accordingly.
_DOF_Supported_Heave – set to true of false accordingly.
_DOF_Supported_Yaw – set to true of false accordingly.
_DOF_Supported_Sway – set to true of false accordingly.
_DOF_Supported_Surge – set to true of false accordingly.
_DOF_Supported_Extra1 – = not used.
_DOF_Supported_Extra2 – = not used.
_DOF_Supported_Extra3 – = not used.


GameDash - Dash Board Support
_Is_DashBoard = False - Set to True to enable the Dashboard Output System?
Once enabled you may assign up to 20 dash output variables.
You may the Variables anywhere within the plugin, but often used with either Process_PacketRecieved, Process_MemoryHook or Process_MemoryMap.
Assign the dash output variable as follows:
Dash_1_Output = Speed, & OUTPUT_VALUE_HERE.
Dash_2_Output = Rpm, & OUTPUT_VALUE_HERE
...


2) Game Data Collection
Startup and Shutdown Commands
if your game needs any extra commands to start or stop the collection of data, it can be entered here.

Process a Memory Hook
Place your end results in the output variables, Roll_MemHook, Pitch_MemHook, Etc...
NoLimitsCoasters – Example shown - Roll, Pitch etc... memory readings are strait forward.
No need to alter the Process_PacketsReceived subroutine when using a memory hooked game.

Process a Memory Map
Place your end results in the output variables, Roll_MemMap, Pitch_MemMap, Etc...
GTR2 – Example Plugin - The data structure is copied from memory and then outputs are assigned to the MemMap variables.
No need to alter the Process_PacketsReceived subroutine when using a memory mapped game.

Process the Packets Received
Decipher the incoming UDP packets from the Game or Game Manager into Game Engine. The following is an example of deciphering the outsim udp packet captured directly from the game. See the Live for Speed example plugin for more info. Simply place the end results in the output variables, Roll_Output, Pitch_Output, etc... (There is no need to alter this subroutine if you are using a memory mapped or memory hooked game) (Used by GameEngine)


3) Patching the Game
This section will show you how to construct a patching routing for the game section of SimTools

PatchPathInfo
This is used to tell the user the location they should patch there game at. It is presented to the user when they press the “Edit Path” button in GameManager.

ValidatePatchPath
Used to enable or disable the “Patch Game” button in GameManager. In the picture above, we see that the user has a valid path, when the path has the file “LFS.exe” present. (In other words, it makes the user select Live for Speeds installation folder)

PatchGame
Used to install a DLL (rFactor plugin example) or edit a .txt or .cfg file (Live for Speed plugin example) to achieve telemetry output from the game. With most games, I made a backup of the file I’m going to edit and save it to cfg.BAK.

UnPatchGame
Used to remove whatever alterations were made to the game during the PatchGame procedure.


How to Compile the Plugin
Click on “My Project”

Make sure the “application” tab is selected. Now name the game DLL as follows: _GameName (without spaces) + _Plugin.
So for “Live for Speed” we get ‘LiveforSpeed_Plugin’. Use this name for both the ‘Assembly Name’ and the ‘Root Namespace’ as in the picture below

Click the green play button at the top of the screen and it will compile you game dll and verify it as a plugin for SimTools.
Once verified - it reads back the _GameName from within the dll itself.

Your new game plugin can now be found in the folder:
Example Plugin Folder\AdditionPlugin\bin\Release\MyPlugin_Plugin.dll

Have a look at the LFS example in @yobuddy's original post. I am unclear if yours is a general question @lioxacydak1, if not what game are you specifically referring to?